Noon Payments Flutter Plugin

A high-performance, professional Flutter plugin for integrating the Noon Payments SDK (v2.1.0) on Android and iOS. This plugin provides a seamless way to accept payments in your Flutter app using Noon's secure native payment sheets, with full support for customization and easy environment switching.

✨ Features

• 📱 Native Payment Sheet: Uses officially supported Noon Payments native UI (Android AAR & iOS XCFramework).
• 🎨 Deep Customization: Customize UI elements (colors, labels, and logos).
• 🛡️ Zero-Configuration Bundling: Native SDKs are built-in—no manual downloads required.
• 🧩 Universal Result Model: Unified response parsing for success, cancellations, and failures.
• 🍏 Apple Pay Support: Noon's drop-in sheet, native Apple Pay Direct Integration (PassKit), and Apple Pay on Flutter Web (Safari + Chrome/Edge cross-device QR).
• 🤖 Google Pay Support: Seamless integration with Google Pay via Noon SDK.
• 🌍 Localization: Native support for English and Arabic.
• 🧪 Modern API: Clean, type-safe API using NoonEnvironment constants and custom endpoints.

📖 Documentation & SDK Version

• SDK Version: 2.1.0 (Android & iOS)
• Official Documentation: docs.noonpayments.com

🚀 Installation

1. Add Dependency

Add the package to your pubspec.yaml:

dependencies:
  noon_payments: ^1.2.0

🛠️ Platform Setup

🤖 Android Setup

1. Minimum SDK Version: Ensure your app-level Gradle file has a minimum SDK of at least 26:

   android {
       defaultConfig {
           minSdk = 26
       }
   }

2. Enable Data Binding: Since the Noon SDK uses Data Binding, you must enable it in your app-level Gradle file:

   android {
       buildFeatures {
           dataBinding = true
       }
   }

3. Google Pay Metadata: Add the following inside your <application> tag in AndroidManifest.xml:

   <meta-data
       android:name="com.google.android.gms.wallet.api.enabled"
       android:value="true" />

🍎 iOS Setup & Apple Pay

1. Deployment Target: Ensure your iOS deployment target is at least 13.0.
2. Framework Embedding: The plugin declares the bundled NoonPaymentsSDK.xcframework as a vendored framework in its podspec. If you integrate or inspect it manually in Xcode, ensure it is embedded and signed by the Runner target.
3. Apple Pay Capabilities: To enable Apple Pay, you must configure your Apple Developer account and Xcode:
   • Go to your Apple Developer Portal.
   • Create a new Merchant ID (e.g., merchant.com.yourcompany.app).
   • Open your project in Xcode.
   • Go to your target's Signing & Capabilities tab.
   • Click + Capability and add Apple Pay.
   • Check the box next to the Merchant ID you created.
4. Noon Dashboard & Certificate Configuration:
   • Step 1: Download the CSR (Certificate Signing Request) file from your Noon Payments Dashboard (You May Need to Contact Noon Support for activation).
   • Step 2: Upload this CSR to the Apple Developer Portal under your Merchant ID to generate a Payment Processing Certificate.
   • Step 3: Download the certificate (.cer) from Apple and re-upload it back to the Noon Dashboard.
   • Step 4: Ensure your Backend sends YOUR valid merchantIdentifier in your server-side call.
   • Step 5: Ensure Mobile SDK is activated in your Noon Payments Dashboard (You can contact Noon Support for activation).

💳 Usage

⚙️ 1. Generate Order ID (Server-Side)

Before launching the payment sheet, your backend must call Noon's INITIATE API.

🔌 2. Initiate Payment

import 'package:noon_payments/noon_payments.dart';

final result = await NoonPayments.initiatePayment(
  orderId: "YOUR_ORDER_ID_FROM_BACKEND",
  authHeader: "Key YOUR_AUTHORIZED_KEY_HERE",

  // Use predefined global endpoints:
  environment: NoonEnvironment.sandbox, // or NoonEnvironment.production

  // OR use a custom regional endpoint (e.g., Saudi Arabia):
  // environment: NoonEnvironment(
  //   "[https://api-test.sa.noonpayments.com/payment/v1/order](https://api-test.sa.noonpayments.com/payment/v1/order)",
  // ),

  language: NoonPaymentLanguage.english, // or NoonPaymentLanguage.arabic
);

if (result.isSuccess) {
  print("✅ Payment Successful! Data: ${result.data}");
} else if (result.isCancelled) {
  print("🚫 User cancelled the payment.");
} else {
  print("❌ Payment Failed: ${result.errorMessage} (Code: ${result.errorCode})");
}

🎨 3. UI Customization (Optional)

import 'dart:typed_data';

import 'package:flutter/services.dart';

// Load your logo from assets
final ByteData rawLogo = await rootBundle.load('assets/logo.png');
final Uint8List logoBytes = rawLogo.buffer.asUint8List();

final customStyle = NoonPaymentStyle(
  logoBytes: logoBytes,
  backgroundColor: "#F8F9FA",
  paymentOptionHeadingText: "Secure Checkout",
  payNowButtonBackground: "#4CAF50",
  payableAmountText: "Total to Pay",
);

await NoonPayments.initiatePayment(
  // ... other parameters
  style: customStyle,
);

🍏 Apple Pay (Direct Integration)

In addition to Noon's drop-in payment sheet (initiatePayment, which can show Apple Pay as one of its options), this plugin supports Apple Pay's Direct Integration on iOS and Flutter Web. Your app presents Apple's own Apple Pay UI (PassKit on iOS, ApplePaySession in the browser on Web) and the resulting payment token is submitted to Noon.

How it works

Native Apple Pay sheet (PassKit)  →  Apple Pay token  →  Noon INITIATE API  →  Result

The token Apple hands you is encrypted, and someone has to decrypt it to charge the card. Noon documents two ways to do this:

• Flow A: get the token from Apple → send the (encrypted) token to Noon → Noon decrypts it and charges. ✅
• Flow B: get the token from Apple → send it to your backend → your backend decrypts it (using your own certificate) → send the decrypted fields to Noon → Noon charges. ✅

Think of it like a locked box:

• Flow A → you hand the locked box to Noon, and Noon has the key.
• Flow B → you have the key, so you open the box yourself and hand Noon what's inside.

Prerequisites

1. Complete the iOS Setup & Apple Pay steps above (Merchant ID, Apple Pay capability, payment processing certificate exchanged between Apple and the Noon Dashboard).
2. Ensure your order category is configured to route through the mobile channel — contact Noon Support.
3. To accept mada cards, include ApplePayNetwork.mada in supportedNetworks.

Option 1 (iOS) — Convenience: present + INITIATE from the client

Easiest path; consistent with initiatePayment (uses your authHeader on the device). iOS only — on web use payWithApplePayServerSide.

import 'package:noon_payments/noon_payments.dart';

// 1. Only show the Apple Pay button if the device supports it.
final bool canUseApplePay = await NoonPayments.isApplePayAvailable();

// 2. Present the native sheet and submit the token to Noon.
final result = await NoonPayments.payWithApplePay(
  config: const NoonApplePayConfig(
    merchantIdentifier: 'merchant.com.yourcompany.app', // YOUR Merchant ID
    countryCode: 'AE',
    currencyCode: 'AED',
    summaryItems: [
      // The LAST item is the grand total; its label is usually your business name.
      NoonApplePaySummaryItem(label: 'Your Business', amount: '10'),
    ],
    supportedNetworks: [
      ApplePayNetwork.visa,
      ApplePayNetwork.masterCard,
      ApplePayNetwork.mada, // required to accept mada cards
    ],
  ),
  order: const NoonOrder(
    amount: '10',
    currency: 'AED',
    name: 'Test Order',
    category: 'pay',
    reference: 'NPORDTEST0001',
    // channel defaults to 'mobile'
  ),
  authHeader: 'Key YOUR_AUTHORIZED_KEY',
  environment: NoonEnvironment.sandbox, // or .production / a custom regional URL
  paymentAction: 'AUTHORIZE,SALE',       // AUTHORIZE | SALE | AUTHORIZE,SALE
);

if (result.isSuccess) {
  print('✅ Apple Pay successful! ${result.data}');
} else if (result.isCancelled) {
  print('🚫 User cancelled Apple Pay.');
} else {
  print('❌ Failed: ${result.errorMessage} (Code: ${result.errorCode})');
}

Option 2 (iOS) — Most secure: present on device, INITIATE on your backend

Keeps your authorization key off the device. The plugin only presents Apple Pay and hands you the token; your server calls INITIATE. iOS only.

final NoonApplePayToken? token = await NoonPayments.getApplePayToken(
  const NoonApplePayConfig(
    merchantIdentifier: 'merchant.com.yourcompany.app',
    countryCode: 'AE',
    currencyCode: 'AED',
    summaryItems: [NoonApplePaySummaryItem(label: 'Your Business', amount: '10')],
  ),
);

if (token == null) {
  // User cancelled the sheet.
} else {
  // Send token.paymentInfo to your backend. Your server then POSTs to
  // [https://api.noonpayments.com/payment/v1/order](https://api.noonpayments.com/payment/v1/order) with:
  //   "paymentData": { "type": "ApplePay", "data": { "paymentInfo": "<token.paymentInfo>" } }
  await myBackend.completeApplePay(paymentInfo: token.paymentInfo);
}

🌐 Apple Pay on the Web (Flutter Web)

The browser presents Apple's ApplePaySession UI and Apple picks the right experience per device:

Browser support

<script crossorigin src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>

Under the hood (the 2-step Noon web flow; iOS is a single call):

ApplePaySession (native sheet OR cross-device QR)
   │  onvalidatemerchant ──► your backend ──► Noon INITIATE (data.validationUrl) ──► validationData
   │                          completeMerchantValidation(validationData)
   │  onpaymentauthorized ─► your backend ──► Noon PROCESS_AUTHENTICATION (data.paymentInfo = token)
   └─ completePayment(status) ──► NoonPaymentResult

How to register your web domain with Apple Pay

Apple Pay JS will silently refuse to run on an unregistered domain. The Domain Verification process consists of two main steps: one in your Apple Developer account, and the other within your Flutter Web project and server. Here are the practical steps in detail:

Step 1: Download the Verification File from Apple Developer Account

1. Log in to your Apple Developer Account and navigate to the Certificates, Identifiers & Profiles section.
2. From the sidebar, select Identifiers, and make sure to filter by Merchant IDs using the dropdown menu at the top right.
3. Click on the Merchant ID associated with your project (the one used with Noon Payments).
4. Scroll down to the Website Verification section and click the Add Domain button.
5. Enter your website's domain name (e.g., yourdomain.com) without https:// and without www, then click Save.
6. A Download button will appear for the verification file. Download it; the exact file name will be: apple-developer-merchantid-domain-association.

Step 2: Add the File to Your Flutter Web Project In a Flutter project, any static files or browser configurations must be placed inside the main web directory so they are included in the final build output.

1. Open your Flutter project directory.
2. Navigate to the web folder.
3. Create a new directory inside the web folder and name it .well-known (note the starting dot, making it a hidden directory).
4. Move the downloaded verification file into this new directory.

Your project folder structure should look like this:

my_flutter_project/
  ├── lib/
  └── web/
      ├── .well-known/
      │     └── apple-developer-merchantid-domain-association
      ├── index.html
      └── favicon.png

Step 3: Confirm Verification

• Host the deployed site ensuring the file is accessible at exactly: https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association (must be publicly reachable, over HTTPS, with no redirects).
• Go back to the Apple Developer Portal and click Verify.
• Note: The merchantIdentifier you pass in NoonApplePayConfig must match the one registered for these domains.

Wire it up — payWithApplePayServerSide + your backend

NoonPayments.payWithApplePayServerSide(...) presents the sheet (or QR) and lets your backend make the two Noon calls (so your key never reaches the browser, and there's no CORS problem). You provide two callbacks:

final result = await NoonPayments.payWithApplePayServerSide(
  config: NoonApplePayConfig(
    merchantIdentifier: 'merchant.com.yourcompany.app',
    countryCode: 'AE',
    currencyCode: 'AED',
    summaryItems: [NoonApplePaySummaryItem(label: 'Your Business', amount: amount)],
    supportedNetworks: const [ApplePayNetwork.visa, ApplePayNetwork.masterCard, ApplePayNetwork.mada],
  ),

  // 1) Apple asks us to validate the merchant. Send the URL to YOUR server,
  //    which calls Noon INITIATE and returns the `validationData` string.
  onValidateMerchant: (validationUrl) async {
    final res = await http.post(
      Uri.parse('[https://your-server.com/apple-pay/validate](https://your-server.com/apple-pay/validate)'),
      headers: {'Content-Type': 'application/json'},
      body: jsonEncode({'validationUrl': validationUrl, 'reference': ref}),
    );
    return jsonDecode(res.body)['validationData'] as String;
  },

  // 2) User authorized. Send the token to YOUR server, which calls Noon
  //    PROCESS_AUTHENTICATION and tells you if it succeeded.
  onPaymentAuthorized: (paymentInfo) async {
    final res = await http.post(
      Uri.parse('[https://your-server.com/apple-pay/authorize](https://your-server.com/apple-pay/authorize)'),
      headers: {'Content-Type': 'application/json'},
      body: jsonEncode({'paymentInfo': paymentInfo, 'reference': ref}),
    );
    final ok = jsonDecode(res.body)['status'] == 'paid';
    return ok ? NoonPaymentResult.parse(res.body) : NoonPaymentResult.failed(errorMessage: 'Declined');
  },
);

Your backend (the two calls Noon documents for the web flow):

// Node.js (Express) — keys stay here, not in the browser.

// (1) Merchant validation → Noon INITIATE with Apple's validation URL.
app.post("/apple-pay/validate", async (req, res) => {
  const { validationUrl, reference } = req.body;
  const order = await db.orders.findByRef(reference); // your trusted amount/items
  const noon = await fetch(
    "[https://api.noonpayments.com/payment/v1/order](https://api.noonpayments.com/payment/v1/order)",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Key YOUR_AUTHORIZED_KEY",
      },
      body: JSON.stringify({
        apiOperation: "INITIATE",
        order: {
          amount: order.amount,
          currency: "AED",
          name: "Test Order",
          category: "pay",
          channel: "web",
          reference,
        },
        configuration: { paymentAction: "AUTHORIZE,SALE" },
        paymentData: { type: "ApplePay", data: { validationUrl } },
      }),
    },
  ).then((r) => r.json());

  await db.orders.attachNoonId(reference, noon.result.order.id); // store for step 2
  res.json({ validationData: noon.result.paymentData.data.validationData });
});

// (2) Payment authorized → Noon PROCESS_AUTHENTICATION with the token.
app.post("/apple-pay/authorize", async (req, res) => {
  const { paymentInfo, reference } = req.body;
  const order = await db.orders.findByRef(reference); // has noon order id from step 1
  const noon = await fetch(
    "[https://api.noonpayments.com/payment/v1/order](https://api.noonpayments.com/payment/v1/order)",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Key YOUR_AUTHORIZED_KEY",
      },
      body: JSON.stringify({
        apiOperation: "PROCESS_AUTHENTICATION",
        order: { id: order.noonId },
        paymentData: { type: "ApplePay", data: { paymentInfo } },
      }),
    },
  ).then((r) => r.json());

  if (noon.resultCode === 0)
    return res.json({ status: "paid", noonOrderId: order.noonId });
  res.json({ status: "failed", message: noon.message });
});

Apple Pay API reference

📖 Style Properties

All color values should be hex strings such as #FFFFFF or #4CAF50.

⚖️ License

This project is licensed under the MIT License - see the LICENSE file for details.