Moyasar Flutter SDK

Accept payments in your Flutter app through Apple Pay, Samsung Pay, STC Pay, and Credit Card — with the 3DS step handled for you.

Moyasar Flutter SDK Demo

Method Platforms Widget
Credit Card (with managed 3DS) iOS, Android CreditCard
Apple Pay iOS ApplePay
Samsung Pay Android (Samsung devices) SamsungPay
STC Pay iOS, Android STCPay

Every widget hides itself when its method isn't available on the device, so you can drop them all into one screen without platform checks.

Install

flutter pub add moyasar

Requires Flutter >=1.17.0, Dart >=2.18.2 <4.0.0, and iOS 12.0+. You'll need a Moyasar account — get your API keys.

Quick start

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

class Checkout extends StatelessWidget {
  Checkout({super.key});

  final paymentConfig = PaymentConfig(
    publishableApiKey: 'YOUR_PUBLISHABLE_API_KEY',
    amount: 25758, // SAR 257.58 — smallest currency unit (1 SAR = 100 halalas)
    description: 'Order #1324',
    creditCard: CreditCardConfig(saveCard: false, manual: false),
    applePay: ApplePayConfig(
      merchantId: 'YOUR_APPLE_MERCHANT_ID',
      label: 'YOUR_STORE_NAME',
      manual: false,
      saveCard: false,
    ),
    samsungPay: SamsungPayConfig(
      serviceId: 'YOUR_SAMSUNG_SERVICE_ID',
      merchantName: 'YOUR_STORE_NAME',
    ),
  );

  void onPaymentResult(result) {
    if (result is PaymentResponse && result.status == PaymentStatus.paid) {
      // Verify on your backend before fulfilling the order.
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        ApplePay(config: paymentConfig, onPaymentResult: onPaymentResult),
        SamsungPay(config: paymentConfig, onPaymentResult: onPaymentResult),
        CreditCard(config: paymentConfig, onPaymentResult: onPaymentResult),
      ],
    );
  }
}

A widget requires its matching config: ApplePay needs applePay, SamsungPay needs samsungPay.

Handling the result

onPaymentResult receives either a PaymentResponse or an error. Always check the type first:

void onPaymentResult(result) {
  if (result is PaymentResponse) {
    switch (result.status) {
      case PaymentStatus.paid:
        // Charged. Verify on your backend before fulfilling.
        break;
      case PaymentStatus.authorized:
      case PaymentStatus.captured:
        // Manual capture flow: funds held, then taken.
        break;
      case PaymentStatus.initiated:
        // Awaiting the 3DS step or an OTP.
        break;
      case PaymentStatus.failed:
        // Declined.
        break;
    }
    return;
  }

  if (result is PaymentCanceledError) {
    // The user dismissed the payment sheet.
  } else if (result is ValidationError) {
    // Invalid input — inspect result.errors.
  } else if (result is NetworkError || result is TimeoutError) {
    // The payment may have reached the server. Reconcile it before retrying.
  }
}
Error type Meaning
PaymentCanceledError The user dismissed the payment sheet.
UnprocessableTokenError The wallet returned an empty or unusable token.
ValidationError Invalid request data. Has message and errors.
AuthError The publishable API key was rejected.
ApiError Moyasar returned a server-side error.
NetworkError / TimeoutError The client did not receive a result; the payment may still have been processed.
UnspecifiedError Anything else.

Per-method details (masked card number, STC message, 3DS URL) live on result.source.

Apple Pay

  1. Set up your Apple developer account and connect it to Moyasar.
  2. Enable the Apple Pay capability in Xcode.
ApplePay(
  config: paymentConfig,
  onPaymentResult: onPaymentResult,
  buttonType: ApplePayButtonType.buy,          // optional, default: inStore
  buttonStyle: ApplePayButtonStyle.automatic,  // optional, default: black
)

Renders Apple's native PKPaymentButton and drives the sheet through PassKit — no third-party dependency.

Apple Pay currently accepts SAR in this SDK. It does not convert AED or another currency to SAR. Moyasar's multi-currency support depends on the payment method and account; this SDK rejects non-SAR Apple Pay before opening the sheet. If a Saudi SAR charge is accepted by a card issued in another currency, any exchange rate or foreign-currency fee is set by the card issuer, not the SDK.

The button stays busy until the current session finishes. The SDK submits an authorized token once, waits for Moyasar's response before reporting success to Apple Pay, and delivers onPaymentResult after the sheet closes. Closing the sheet after token submission does not cancel processing. The original callback can still run if its widget was removed; check mounted before updating a page.

For a timeout, network error, or an unreadable response, check the payment on your backend before offering another payment. Assign and persist a givenID for the payment attempt before opening Apple Pay, and use that ID for reconciliation and any retry of the same request. A new Apple Pay token must not be treated as an idempotent replay of the original request. See Moyasar idempotency.

Before fulfilling an order, your backend should fetch the payment with its secret key and verify the payment ID belongs to the order, plus its amount, currency, and status. paid confirms a direct payment; authorized confirms only a hold, and a manual-capture flow must verify successful capture before treating funds as collected. Complete the order idempotently so a repeated callback or webhook cannot fulfill it twice. Keep the order pending while a payment outcome is unknown.

Visibility is handled for you:

Situation Behavior
Not iOS, or the device can't support Apple Pay Renders nothing
iOS 15+, no card in Wallet Payment button — the user adds a card inside the sheet
iOS 14 and below, no card "Set Up Apple Pay", which opens Wallet
Card available Payment button

buttonType: plain, buy, setUp, inStore, donate, checkout, book, subscribe, reload, addMoney, topUp, order, rent, support, contribute, tip buttonStyle: white, whiteOutline, black, automatic (follows light/dark mode)

Samsung Pay

Samsung Android devices only. Add the spay_sdk_api_level meta-data to your AndroidManifest.xml — see the integration guide. The SDK bundles Samsung's official Flutter plugin, so no app-level override is needed.

SamsungPay(config: paymentConfig, onPaymentResult: onPaymentResult)

The widget hides itself when Samsung Pay isn't ready. To check explicitly in a custom flow:

final eligible = await SamsungPayEligibility.isEligible(paymentConfig);

final result = await SamsungPayEligibility.check(paymentConfig); // with diagnostics
debugPrint('${result.reason}'); // ready, notAndroid, notReady, sdkError, timeout...

Credit Card & STC Pay

Both render a full form and accept an optional locale. Localization.ar() also switches the layout to RTL; individual strings can be overridden through its named parameters.

CreditCard(config: paymentConfig, onPaymentResult: onPaymentResult)

STCPay(
  config: paymentConfig,
  onPaymentResult: onPaymentResult,
  locale: const Localization.ar(),
)

Configuration

PaymentConfig

Field Type Default Description
publishableApiKey String required Your publishable key.
amount int required Smallest currency unit (25758 = SAR 257.58).
description String required Tag for the payment.
currency String 'SAR' ISO currency code.
metadata Map<String, dynamic>? null Searchable key/value pairs.
supportedNetworks List<PaymentNetwork> visa, mada, masterCard, unionPay Also accepts amex.
applePay ApplePayConfig? null Required by ApplePay.
samsungPay SamsungPayConfig? null Required by SamsungPay.
creditCard CreditCardConfig? null Used by CreditCard.
merchantCountryCode String 'SA' Used by Samsung Pay.
givenID String? null Sets the payment ID — use for idempotent retries.
splits List<PaymentSplit>? null Split the amount (aggregation clients only).
baseUrl String? null Override the API host, e.g. https://apimig.moyasar.com.
applyCoupon bool? null Set false to skip coupon application.

ApplePayConfig

Field Type Default Description
merchantId String required Must match Xcode and your dashboard.
label String required Store name in the payment sheet.
manual bool required Authorize now, capture later.
saveCard bool required Tokenize for later charges.
merchantCapabilities List<String> ["3DS", "debit", "credit"] Must include "3DS".
supportedCountries List<String> [] Allows cards issued in any country by default. Set a list such as ["SA"] to restrict card-issuing countries. Does not change the payment currency.

SamsungPayConfig

Field Type Default Description
serviceId String required From the Samsung merchant dashboard.
merchantName String required Shown in the payment sheet.
orderNumber String? auto-generated [A-Za-z0-9-], max 36 chars. Returned as samsungpay_order_id in the response metadata.
manual bool false Authorize now, capture later.

CreditCardConfig

saveCard (bool, required) — tokenize after a successful payment. manual (bool, required) — authorize now, capture later.

PaymentSplit

Divide a payment among recipients, in compliance with SAMA and ZATCA. Aggregation clients only — splits on other payments are ignored. The splits must total the payment amount.

splits: [
  PaymentSplit(recipientId: 'ENTITY_ID', amount: 20000, recipientType: 'Entity'),
  PaymentSplit(recipientId: 'PLATFORM_ID', amount: 5758, recipientType: 'Platform', feeSource: true),
]

Also accepts description, reference, feeSource (default false, only one split may be the fee source), and refundable (default true).

Building your own UI

Use these when you need full control over the interface — you collect the payment data, the SDK talks to the API.

// Credit Card
final source = CardPaymentRequestSource(
  creditCardData: CardFormModel(
    name: 'John Doe',
    number: '4111111111111111',
    cvc: '123',
    month: '05',
    year: '2027',
  ),
  tokenizeCard: paymentConfig.creditCard!.saveCard,
  manualPayment: paymentConfig.creditCard!.manual,
);

// Apple Pay — appleToken is the PKPaymentToken payment data
final source = ApplePayPaymentRequestSource(
  appleToken,
  paymentConfig.applePay!.manual,
  paymentConfig.applePay!.saveCard,
);

// Samsung Pay
final source = SamsungPayPaymentRequestSource(
  samsungPayToken: token,
  manualPayment: paymentConfig.samsungPay!.manual,
);

// Then, for any source:
final result = await Moyasar.pay(
  apiKey: paymentConfig.publishableApiKey,
  paymentRequest: PaymentRequest(paymentConfig, source),
);

With a custom Credit Card UI, 3DS is your responsibility: when status is initiated, open (result.source as CardPaymentResponseSource).transactionUrl in a web view and watch for the redirect to PaymentConfig.callbackUrl.

STC Pay takes two steps — start the payment, then verify the OTP:

final result = await Moyasar.pay(
  apiKey: paymentConfig.publishableApiKey,
  paymentRequest: PaymentRequest(paymentConfig, StcRequestSource(mobile: '0512345678')),
);

final transactionUrl = (result.source as StcResponseSource).transactionUrl!;

final verified = await Moyasar.verifyOTP(
  transactionURL: transactionUrl,
  otpRequest: OtpRequestSource(otpValue: '1234'),
);

Testing

  • Credit Card — test cards work against the sandbox.
  • Apple Pay — use a real device; the simulator can't complete an authorization. Test amounts.
  • Samsung Pay — requires a Samsung device. The example app uses flavors: flutter run --flavor default_ (Apple Pay) or --flavor spay (Samsung Pay). See example/CONFIGURATION_GUIDE.md.

Deprecations

STCPaymentComponent is deprecated and will be removed in the next major version — it's a drop-in rename to STCPay.

Issues and pull requests are welcome at moyasar/moyasar-flutter.

Libraries

moyasar
Moyasar Flutter SDK helps you accept payments quickly and securely.