Flutter SDK

qasimha_checkout presents the Qasimha hosted checkout from a Flutter app in the system browser sheet and tells you how it ended. Your server creates the session and receives a paymentUrl; your app hands it to the plugin. The plugin holds no secret and makes no API call with a secret key.

Requirements

Install

flutter pub add qasimha_checkout

Set up the return into your app

Use your own HTTPS pages (Android App Links, iOS Universal Links) when you can: they are verified against your domain. A custom scheme (myshop://qasimha/return) is simpler but any app can claim it. Both work with the same merchantUrl.

android {
    defaultConfig {
        manifestPlaceholders["qasimhaReturnScheme"] = "myshop"
    }
}

<activity android:name=".MainActivity" android:launchMode="singleTask">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" android:host="shop.example" android:pathPrefix="/qasimha/return" />
    </intent-filter>
</activity>

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    intent.data?.let { QasimhaCheckoutPlugin.handleReturn(it) }
}

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key><string>com.example.shop</string>
    <key>CFBundleURLSchemes</key><array><string>myshop</string></array>
  </dict>
</array>

If your app intercepts links itself, call QasimhaCheckout.handleReturn(uri) from Dart. It returns true when the URI completed the pending checkout and false when it is not a Qasimha return, so your own router can take it.

Start a checkout

Get paymentUrl from your server and pass it with the same three return URLs your server sent when creating the session.

import 'package:qasimha_checkout/qasimha_checkout.dart';

final result = await QasimhaCheckout.start(
  CheckoutOptions(
    paymentUrl: Uri.parse(session.paymentUrl),
    merchantUrl: MerchantUrl(
      success: Uri.parse('https://shop.example/qasimha/return?order=1001'),
      failure: Uri.parse('https://shop.example/qasimha/return?order=1001'),
      cancel: Uri.parse('https://shop.example/cart'),
    ),
    presentation: Presentation.systemBrowser,
    language: 'ar',
  ),
);

switch (result) {
  case CheckoutSuccess(:final orderId):
    final order = await myServer.confirmQasimhaOrder(orderId);
    if (order.isPaid) showThankYou();
  case CheckoutFailure(:final status):
    showNotCompleted(status);
  case CheckoutCancelled():
    backToCart();
}

CheckoutOptions

start throws ArgumentError for invalid options, StateError while another checkout is in progress, and CheckoutException (no_activity, no_browser, no_view_controller, unsupported_presentation, unsupported_platform) when the platform cannot present the checkout.

On iOS, webAuthenticationSession shows the system consent sheet and needs custom-scheme return URLs below iOS 17.4 (https callbacks work from 17.4). The three URLs must share a scheme, and for https a host and path.

This plugin has no embedded WebView mode. The checkout redirects to the payment gateway and the Nafath app switch, which the system browser handles with the platform's TLS, autofill and cookie isolation. If you must keep the checkout in-app, the native Android and iOS SDKs offer a hardened WebView.

Handle the result and confirm on your server

Treat CheckoutSuccess as "the shopper came back on the success URL". Only your server, calling GET /api/v1/merchant/orders/{orderId} with your secret key, tells you the order is approved. Your server also receives the webhook. A cancelled order stays awaiting checkout; cancel it through the API if you wish.

Promo widget

QasimhaPromo shows "Split into 4 monthly payments of [riyal symbol] 300" with your publishable key.

QasimhaPromo(amount: 1200, publicKey: 'pk_test_...', lang: 'ar')

• Calls GET /api/v1/widget/plans with the X-Public-Key header and a 5-second timeout. pk_test_ keys go to UAT, pk_live_ keys to production. apiBaseUrl overrides the host (https, or http on localhost).
• Fails closed: a zero-size box, never a computed number, when the key or amount is invalid, the request fails, or the amount is outside the plan range.
• RiyalAmount, RiyalAmount.span and RiyalSymbol are exported for your own screens that show Qasimha amounts.
• Sends only the amount and the publishable key. No cookies, no storage.

Release builds

• Android: consumer R8 rules are shipped; the plugin uses no reflection. You do not need extra ProGuard rules.
• iOS: symbols are stripped with your release build. The plugin ships a privacy manifest declaring no tracking and no collected data.

Security

• No secret on the device. The session is created on your server. The only credential the plugin holds is the pk_ key for the promo widget.
• TLS validation is the platform's. No certificate pinning and no option to disable validation.
• No analytics, fingerprinting or storage.
• PCI DSS: the plugin never sees card data. You stay in SAQ-A scope.
• App hardening: root and jailbreak detection, anti-tamper and runtime protection are recommended for apps that handle payments. They are your app's responsibility.

Troubleshooting

Related

• Mobile SDKs overview
• Return URLs
• Order lifecycle
• Webhooks