Integrating Mada, Apple Pay, and GCC Payment Gateways in Flutter and FastAPI

Introduction

The payment landscape across the Gulf Cooperation Council (GCC) is one of the most advanced, digitally saturated financial ecosystems in the world. Driven by regulatory mandates from the Saudi Central Bank (SAMA), the Central Bank of Oman (CBO), and the Central Bank of the UAE (CBUAE), the region has rapidly pivoted toward a cashless economy. In Saudi Arabia alone, digital point-of-sale and e-commerce transactions surpassed 70% of all payment activity well ahead of the Vision 2030 timeline.

However, international software teams often struggle when launching e-commerce, on-demand delivery, or subscription applications in the Gulf. Attempting to deploy standard international payment flows (such as Stripe Checkout or PayPal) without regional adaptations leads to cart abandonment rates exceeding 60%.

In the GCC, consumer trust and transaction velocity are anchored to specific national payment schemes:

• Mada: The domestic debit card network in Saudi Arabia, boasting more than 30 million issued cards and powering the vast majority of consumer purchases.
• Apple Pay: The undisputed leader for mobile checkout across the GCC, where iOS holds dominant market share in high-disposable-income demographics.
• Regional Debit Switches: KNET in Kuwait, Benefit in Bahrain, OmanNet in Oman, and NAPS in Qatar.

When architecting production mobile applications like BeesApp (loyalty and merchant checkout in Saudi Arabia) and Apaale (ridesharing and logistics), integrating these regional payment rails seamlessly was paramount.

In this engineering deep dive, I will guide you through the end-to-end architecture of integrating Mada, Apple Pay, and regional gateways using Flutter on the mobile frontend and a secure, idempotent FastAPI backend in Python.

The GCC Payment Rails Ecosystem: Mada, KNET, and Regional Gateways

To design a scalable payment pipeline, you must first understand the technical topology of payment routing in the Middle East.

┌────────────────────────────────────────────────────────────────────────┐
│                   GCC Domestic Payment Architecture                    │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│   ┌───────────────────────────────────────────────────────────────┐    │
│   │                      Flutter Mobile App                       │    │
│   │  - Native Apple Pay (PassKit with 'mada' network)             │    │
│   │  - Embedded Mada Card Form with BIN Detection                 │    │
│   │  - 3D Secure 2.0 (3DS2) In-App Challenge Sheet               │    │
│   └───────────────┬───────────────────────────────▲───────────────┘    │
│                   │ Encrypted Token               │ 3DS Challenge      │
│                   ▼                               │                    │
│   ┌───────────────────────────────────────────────┴───────────────┐    │
│   │                   Regional Payment Gateway                    │    │
│   │         (Moyasar / Tap Payments / PayTabs / Checkout)         │    │
│   └───────────────┬───────────────────────────────▲───────────────┘    │
│                   │ SAMA / National Switch        │ Settlement Status  │
│                   ▼                               │                    │
│   ┌───────────────────────────────────────────────┴───────────────┐    │
│   │                   National Payment Switches                   │    │
│   │    - Saudi Arabia: Mada Network / SPAN2                       │    │
│   │    - Kuwait: KNET Switch                                      │    │
│   │    - Bahrain: BenefitNet                                      │    │
│   │    - Oman: OmanNet Switch                                     │    │
│   └───────────────────────────────────────────────────────────────┘    │
└────────────────────────────────────────────────────────────────────────┘

Domestic Cards vs. International Cards

In Western markets, debit cards are typically cobranded with Visa or Mastercard and route directly through international credit card networks. In Saudi Arabia, every domestic bank card issued by Al Rajhi, SNB (Saudi National Bank), Riyad Bank, or Alinma is connected directly to Mada.

When a user enters a Mada card in your app:

1. Transaction processing fees are substantially lower for merchants compared to international credit cards (often capped at minimal basis points by SAMA regulations).
2. The transaction routes through the Saudi Payments national switch (SPAN2) rather than exiting the country to international clearinghouses.
3. Every Mada e-commerce transaction strictly mandates 3D Secure (3DS) two-factor authentication via SMS OTP sent by the issuing Saudi bank.

Comparing GCC Payment Service Providers (PSPs)

Selecting the right payment aggregator is critical for developer experience and transaction success rates:

For most startups and enterprise applications targeting Saudi Arabia, Moyasar and Tap Payments offer the cleanest developer ergonomics, excellent documentation, and battle-tested Flutter support.

Apple Pay Architecture in the GCC: Native PassKit and Mada Routing

Apple Pay is the conversion engine of the GCC mobile ecosystem. In Saudi Arabia and the UAE, where iPhone usage exceeds 75% in major urban centers, providing Apple Pay removes the friction of manually typing 16-digit card numbers, expiration dates, and billing addresses.

However, configuring Apple Pay for Saudi Arabia requires specific platform settings. If you misconfigure your Apple Pay merchant profile, Mada cards stored in Apple Wallet will be rejected or grayed out, leaving only international credit cards functional.

The Mada Apple Pay Requirement

Under SAMA guidelines, Apple Pay transactions on Saudi-issued cards must route through the domestic Mada network. To enable this, your iOS PassKit request must explicitly list PKPaymentNetwork.mada alongside Visa and Mastercard.

Step 1: iOS Entitlements Setup

In your Flutter project's ios/Runner/Runner.entitlements, enable Apple Pay and declare your merchant identifier:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.in-app-payments</key>
    <array>
        <string>merchant.com.itsmoeenahmad.beesapp</string>
    </array>
</dict>
</plist>

Step 2: Payment Profile Configuration (apple_pay_config.json)

Using the official pay Flutter package (or custom native platform channels), define your regional payment profile in an asset file:

{
  "provider": "apple_pay",
  "data": {
    "merchantIdentifier": "merchant.com.itsmoeenahmad.beesapp",
    "displayName": "BeesApp Rewards",
    "merchantCapabilities": ["3DS", "debit", "credit"],
    "supportedNetworks": [
      "mada",
      "visa",
      "masterCard"
    ],
    "countryCode": "SA",
    "currencyCode": "SAR",
    "requiredBillingContactFields": ["emailAddress", "name", "phoneNumber"],
    "requiredShippingContactFields": []
  }
}

Crucial Insight: Including "mada" in supportedNetworks and "debit" in merchantCapabilities is mandatory. Without these keys, iOS will disable all Saudi bank cards stored in the user's Apple Wallet during checkout.

Step 3: Flutter Apple Pay Button Implementation

Here is a clean implementation of the Apple Pay button widget using Riverpod for payment state management:

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:pay/pay.dart';

class SaudiApplePayButton extends ConsumerWidget {
  final double amount;
  final String orderId;
  final VoidCallback onPaymentStarted;
  final Function(String paymentToken) onPaymentSuccess;
  final Function(String errorMessage) onPaymentFailed;

  const SaudiApplePayButton({
    super.key,
    required this.amount,
    required this.orderId,
    required this.onPaymentStarted,
    required this.onPaymentSuccess,
    required this.onPaymentFailed,
  });

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final paymentItems = [
      PaymentItem(
        label: 'Total Order #$orderId',
        amount: amount.toStringAsFixed(2),
        status: PaymentItemStatus.final_price,
      ),
    ];

    return ApplePayButton(
      paymentConfiguration: PaymentConfiguration.fromJsonString(
        '''
        {
          "provider": "apple_pay",
          "data": {
            "merchantIdentifier": "merchant.com.itsmoeenahmad.beesapp",
            "displayName": "BeesApp Checkout",
            "merchantCapabilities": ["3DS", "debit", "credit"],
            "supportedNetworks": ["mada", "visa", "masterCard"],
            "countryCode": "SA",
            "currencyCode": "SAR"
          }
        }
        ''',
      ),
      paymentItems: paymentItems,
      style: ApplePayButtonStyle.black,
      type: ApplePayButtonType.buy,
      margin: const EdgeInsets.only(top: 15.0),
      onPaymentResult: (result) async {
        try {
          // Extract encrypted Apple Pay token
          final tokenString = result['token'] as String?;
          if (tokenString == null || tokenString.isEmpty) {
            onPaymentFailed('Invalid Apple Pay authorization token received.');
            return;
          }
          onPaymentSuccess(tokenString);
        } catch (e) {
          onPaymentFailed('Failed to process Apple Pay payload: $e');
        }
      },
      loadingIndicator: const Center(
        child: CircularProgressIndicator.adaptive(),
      ),
    );
  }
}

Direct Mada Card Processing and BIN Detection in Flutter

While Apple Pay handles iOS users effortlessly, Android users (and iOS users who prefer physical cards) require a native credit and debit card input sheet.

When accepting card payments in Saudi Arabia, your checkout UI should immediately reassure users that their domestic Mada card is supported by automatically highlighting the Mada brand logo when a valid Mada Bank Identification Number (BIN) is typed.

Real-Time Mada BIN Detection Logic

Mada cards are issued under specific Bank Identification Numbers. You can detect Mada cards in real-time within your Flutter text controller:

class MadaBinDetector {
  /// Verified Saudi Mada Card BIN Prefixes
  static final List<String> _madaBinPrefixes = [
    '588845', '440647', '440795', '409201', '458456', '484783',
    '462220', '455708', '455036', '486094', '486095', '486096',
    '504300', '524130', '524541', '529415', '535825', '543357',
    '554180', '557606', '588982', '588983', '589005', '589206',
    '604906', '605141', '636120', '968201', '968202', '968203',
    '968204', '968205', '968206', '968207', '968208', '968209',
    '968211', '417633', '468540', '468541', '468542', '468543',
  ];

  static bool isMadaCard(String rawCardNumber) {
    final clean = rawCardNumber.replaceAll(RegExp(r'\D'), '');
    if (clean.length < 6) return false;

    final prefixSix = clean.substring(0, 6);
    return _madaBinPrefixes.contains(prefixSix);
  }

  static String getCardBrand(String rawCardNumber) {
    final clean = rawCardNumber.replaceAll(RegExp(r'\D'), '');
    if (clean.isEmpty) return 'Unknown';

    if (isMadaCard(clean)) return 'Mada';
    if (clean.startsWith('4')) return 'Visa';
    if (clean.startsWith('51') || clean.startsWith('52') ||
        clean.startsWith('53') || clean.startsWith('54') ||
        clean.startsWith('55')) {
      return 'Mastercard';
    }
    if (clean.startsWith('34') || clean.startsWith('37')) return 'Amex';

    return 'Unknown';
  }
}

Handling the 3D Secure 2.0 Challenge Flow

Under SAMA security regulations, 100% of e-commerce Mada transactions require 3D Secure verification. Once your Flutter app transmits the card data to the gateway (e.g., Moyasar API), the gateway returns a response containing a transaction_url (the bank's 3DS OTP challenge page).

The mobile app must launch an in-app WebView sheet, monitor the redirected URL, and catch the terminal callback (https://yourdomain.com/payments/callback):

import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

class ThreeDSChallengeModal extends StatefulWidget {
  final String challengeUrl;
  final String expectedReturnUrl;
  final Function(String paymentId) onChallengeSuccess;
  final Function(String error) onChallengeFailed;

  const ThreeDSChallengeModal({
    super.key,
    required this.challengeUrl,
    required this.expectedReturnUrl,
    required this.onChallengeSuccess,
    required this.onChallengeFailed,
  });

  @override
  State<ThreeDSChallengeModal> createState() => _ThreeDSChallengeModalState();
}

class _ThreeDSChallengeModalState extends State<ThreeDSChallengeModal> {
  late final WebViewController _controller;
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();
    _controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..setNavigationDelegate(
        NavigationDelegate(
          onPageStarted: (url) {
            _handleUrlInterception(url);
          },
          onPageFinished: (_) {
            if (mounted) setState(() => _isLoading = false);
          },
        ),
      )
      ..loadRequest(Uri.parse(widget.challengeUrl));
  }

  void _handleUrlInterception(String currentUrl) {
    if (currentUrl.startsWith(widget.expectedReturnUrl)) {
      final uri = Uri.parse(currentUrl);
      final status = uri.queryParameters['status'];
      final paymentId = uri.queryParameters['id'] ?? '';

      if (status == 'paid') {
        widget.onChallengeSuccess(paymentId);
        Navigator.of(context).pop();
      } else {
        widget.onChallengeFailed(uri.queryParameters['message'] ?? '3DS verification failed');
        Navigator.of(context).pop();
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Bank 3DS Verification'),
        leading: IconButton(
          icon: const Icon(Icons.close),
          onPressed: () {
            widget.onChallengeFailed('User cancelled bank verification');
            Navigator.of(context).pop();
          },
        ),
      ),
      body: Stack(
        children: [
          WebViewWidget(controller: _controller),
          if (_isLoading)
            const Center(
              child: CircularProgressIndicator.adaptive(),
            ),
        ],
      ),
    );
  }
}

Secure Backend Architecture with FastAPI: Webhook Verification and Idempotency

Never rely on the client mobile app to confirm payment settlement. A malicious client could reverse engineer the callback URL or simulate a successful 3DS response to unlock paid features, rewards, or dispatch delivery orders without paying.

The Golden Rule of Mobile Fintech: The Flutter app is solely an orchestration and presentation layer. The state transition from PENDING to PAID must be triggered exclusively by cryptographically signed backend webhooks received directly from the payment gateway.

┌────────────────────────────────────────────────────────────────────────┐
│                   Secure Payment Settlement Sequence                   │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│   Flutter App          Regional Gateway           FastAPI Server       │
│        │                      │                         │              │
│        │── Initiate Card ────►│                         │              │
│        │◄── 3DS Challenge ────│                         │              │
│        │                      │                         │              │
│        │── Complete OTP ─────►│                         │              │
│        │                      │── POST /webhooks ──────►│              │
│        │                      │   (HMAC Signature +     │              │
│        │                      │    Idempotency Key)     │ Verify HMAC  │
│        │                      │                         │ Lock DB Row  │
│        │                      │◄── 200 OK Response ─────│ Settle Order │
│        │                                                │              │
│        │◄── Poll / WebSocket Settle Notification ───────│              │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

FastAPI Production Webhook Handler

Here is the complete production implementation of a secure FastAPI payment webhook router. It validates the cryptographic HMAC signature, verifies payload integrity, prevents duplicate event replay attacks via idempotency keys, and acquires database row-level locks:

import hmac
import hashlib
import json
from fastapi import APIRouter, Header, HTTPException, Request, Depends, status
from pydantic import BaseModel, Field
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select
from typing import Optional

router = APIRouter(prefix="/api/v1/payments", tags=["payments"])

# Regional Gateway Webhook Shared Secret (Store in HashiCorp Vault or AWS Secrets)
GATEWAY_WEBHOOK_SECRET = "sec_prod_gcc_mada_781920384729103"


class GatewayPaymentData(BaseModel):
    id: str
    status: str
    amount: int  # Stored in halalas / baisa (e.g. 15000 halalas = 150.00 SAR)
    currency: str
    description: Optional[str] = None
    fee: Optional[int] = 0
    invoice_id: Optional[str] = None
    source_type: str = Field(alias="source.type", default="mada")


class PaymentWebhookPayload(BaseModel):
    event: str
    data: GatewayPaymentData


def verify_hmac_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    """
    Verifies that the incoming webhook payload was strictly signed by the gateway.
    Protects against spoofing and man-in-the-middle attacks.
    """
    if not signature_header:
        return False

    computed_mac = hmac.new(
        key=secret.encode("utf-8"),
        msg=raw_body,
        digestmod=hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(computed_mac, signature_header)


@router.post("/moyasar-webhook", status_code=status.HTTP_200_OK)
async def handle_regional_payment_webhook(
    request: Request,
    x_moyasar_signature: Optional[str] = Header(None),
    x_idempotency_key: Optional[str] = Header(None),
    # db: AsyncSession = Depends(get_async_db)
):
    """
    Production-grade webhook receiver for Saudi Mada and Apple Pay settlement.
    """
    raw_body = await request.body()

    # 1. Cryptographic Signature Verification
    if not x_moyasar_signature or not verify_hmac_signature(
        raw_body=raw_body,
        signature_header=x_moyasar_signature,
        secret=GATEWAY_WEBHOOK_SECRET
    ):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid cryptographic webhook signature."
        )

    # 2. Parse and Validate JSON Schema
    try:
        payload_dict = json.loads(raw_body.decode("utf-8"))
        payload = PaymentWebhookPayload(**payload_dict)
    except Exception as err:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail=f"Malformed webhook JSON payload: {err}"
        )

    payment_data = payload.data
    payment_id = payment_data.id
    payment_status = payment_data.status.lower()

    # 3. Handle Idempotency Check in Database
    # Query database for existing transaction record
    # async with db.begin():
    #     stmt = (
    #         select(Order)
    #         .where(Order.payment_gateway_id == payment_id)
    #         .with_for_update()  # Lock the row to prevent concurrent race conditions
    #     )
    #     result = await db.execute(stmt)
    #     order = result.scalar_one_or_none()
    #
    #     if not order:
    #         raise HTTPException(status_code=404, detail="Order not found")
    #
    #     if order.status == "COMPLETED":
    #         # Already settled! Acknowledge webhook immediately to prevent retries
    #         return {"status": "success", "message": "Already processed (idempotent)"}

    # 4. State Transition
    if payment_status == "paid":
        # Convert halalas to SAR
        amount_sar = payment_data.amount / 100.0
        # order.status = "COMPLETED"
        # order.settled_at = datetime.utcnow()
        # await db.commit()

        # 5. Trigger Asynchronous Background Notifications (Push Notification / SMS)
        # await notify_user_payment_success(order.user_id, amount_sar)
        return {
            "status": "success",
            "payment_id": payment_id,
            "amount_sar": amount_sar,
            "settled": True
        }
    
    elif payment_status in ["failed", "canceled"]:
        # order.status = "FAILED"
        # await db.commit()
        return {"status": "failed", "payment_id": payment_id}

    return {"status": "ignored", "payment_id": payment_id}

SAMA Regulatory Compliance and Security Best Practices

Operating a fintech, e-commerce, or subscription service in Saudi Arabia requires strict adherence to regulations established by the Saudi Central Bank (SAMA). Non-compliance can result in immediate merchant account termination, hefty financial fines, or domain blocking.

┌────────────────────────────────────────────────────────────────────────┐
│                   SAMA Compliance Security Framework                   │
├───────────────────────────┬────────────────────────────────────────────┤
│ Regulatory Domain         │ Technical Mandate                          │
├───────────────────────────┼────────────────────────────────────────────┤
│ PCI-DSS Compliance        │ Never store, transmit, or log full PAN,    │
│                           │ CVV, or card PIN in mobile RAM or servers. │
├───────────────────────────┼────────────────────────────────────────────┤
│ Data Sovereignty (NDMO)   │ Transaction logs and citizen PII must      │
│                           │ reside on servers physically within KSA.   │
├───────────────────────────┼────────────────────────────────────────────┤
│ 3D Secure 2.0 (3DS2)      │ 100% of domestic Mada e-commerce cards     │
│                           │ must challenge through issuing bank SMS.   │
├───────────────────────────┼────────────────────────────────────────────┤
│ Secure Tokenization       │ Mobile apps must use transient gateway     │
│                           │ tokens or Apple Pay device PANs (DPAN).   │
└───────────────────────────┴────────────────────────────────────────────┘

Essential Compliance Rules for Engineers:

1. Zero Raw Card Storage: Never save card numbers or CVV codes inside Flutter's SharedPreferences, GetStorage, or SQLite databases. Even with encryption, storing raw card data violates PCI-DSS Level 1. Always convert card data to a transient single-use token via your gateway's SDK before it ever hits your backend.
2. Local Cloud Regions: Under the National Data Management Office (NDMO) and SAMA guidelines, financial transaction records containing citizen PII (national IDs, bank balances, phone numbers) must reside inside Saudi Arabia. When hosting your FastAPI backend, deploy in local hyperscale data center regions:
   • Google Cloud Dammam (me-central2)
   • AWS Riyadh / Bahrain (me-south-1 / me-central-1)
   • Oracle Cloud Riyadh / Jeddah
3. Audit Logging with PII Redaction: Implement strict middleware in FastAPI that automatically sanitizes sensitive fields (e.g., card_number, token, otp) from standard access logs before shipping them to Datadog, Elastic, or CloudWatch.

Edge Cases, Refund Workflows, and Network Failures

In mobile commerce, edge cases define your system's actual reliability. Here is how to engineer around the most frequent payment failure modes in the GCC:

1. Cellular Network Drops During 3DS Verification

A customer riding through an underground underpass in Riyadh experiences a network drop while the bank OTP webpage is loading. The user force-quits the app. Five minutes later, their bank SMS arrives confirming 150 SAR was deducted, but the Flutter app never received the final redirect.

The Solution:

• Every checkout creates a pending_orders record in your backend with a unique reference_id.
• If the Flutter app reconnects or launches, its initial dashboard query checks for any pending payments.
• Concurrently, the gateway's server-to-server webhook fires independently of the user's mobile connection, updating the order to PAID.
• When the user reopens the app, the state is already reconciled.

2. Mada Automated Reversal on Timeout

If a 3DS challenge times out or the customer enters the wrong SMS code three times, the Mada switch triggers an automatic reversal. The funds are unlocked on the customer's debit card within minutes to 24 hours depending on the issuing bank (e.g., Al Rajhi or SNB). Your backend must catch the failed webhook event and release any reserved inventory locks.

Key Takeaways for GCC Payment Integrations

1. Prioritize Apple Pay: Configure PassKit with explicit "mada" and "debit" capabilities to capture over 70% of high-value iOS transactions with single-touch biometric authentication.
2. Detect Mada BINs: Provide instant visual feedback in Flutter by identifying domestic BIN prefixes and ensuring seamless 3DS2 in-app challenge routing.
3. Decouple Settlement from the Mobile Client: Never trust the mobile app for payment confirmation. Use FastAPI to handle cryptographically signed HMAC webhooks with atomic idempotency locks.
4. Enforce SAMA Compliance: Keep transaction PII within local GCC data centers, adhere strictly to PCI-DSS zero-card-storage mandates, and safeguard audit logs.

Conclusion

Integrating regional payment gateways like Mada and Apple Pay is not just a checkout convenience; it is the fundamental prerequisite for financial viability and customer conversion across Saudi Arabia and the GCC. Attempting to force international payment abstractions without regional optimization invariably leads to failed transactions and lost revenue.

By combining native Flutter payment sheets, proactive 3DS2 challenge orchestration, and a hardened FastAPI settlement backend with cryptographic verification and idempotency controls, you can construct a resilient financial pipeline that scales alongside the Gulf's rapidly expanding digital economy.

Ready to integrate Mada, Apple Pay, or GCC payment gateways into your app? I architect and deliver secure, production-grade fintech systems from responsive Flutter client apps to high-concurrency, SAMA-compliant FastAPI backends. Book a meeting to discuss your product architecture.