React Native SDK

@qasimha/react-native-sdk brings the full checkout into your app without building any of it. The SDK presents the Qasimha hosted checkout in the system browser sheet (SFSafariViewController or Chrome Custom Tab), watches for the customer's return to your app, and resolves with a typed result your code can act on.

The flow stays server-driven: your server creates the payment session and hands the app a paymentUrl, which the SDK opens. Alongside checkout, the module ships QasimhaPromo, a ready-made instalment summary you can drop into product, cart, and checkout screens.

Security stays where it belongs. The app holds no secret key and makes no API call other than the publishable-key promo request, so nothing sensitive lives in your binary. And whatever result the SDK reports, the outcome is always confirmed by your server, same as a web integration.

Requirements

Install

npm install @qasimha/react-native-sdk
npm install react-native-svg        # optional, recommended for QasimhaPromo
cd ios && pod install

Autolinking handles the native setup on both platforms. Installing the package registers the Android library and the iOS pod automatically. Rebuild the app after installing; a JavaScript reload won't pick up the native code.

Under the hood, the module is a NativeModules bridge module. On the New Architecture it runs through React Native's interop layer, which is enabled by default from React Native 0.74, so no extra configuration is needed. JavaScript locates the module through TurboModuleRegistry with a NativeModules fallback, which means the SDK works in bridge, bridgeless, and New Architecture apps without you touching any of it.

Configuration

• No secret key in the app. Your server holds sk_test_... or sk_live_..., creates the session and returns paymentUrl and the merchantUrl it used. The app passes both to startCheckout unchanged. There is no environment setting: paymentUrl already points at the environment your server used.
• Publishable key, for the promo only. QasimhaPromo needs pk_test_... (UAT, calls https://api-uat.qasimha.com) or pk_live_... (production, calls https://api.qasimha.com). Have your backend return it, so the app always matches the backend's environment, or set it per build with your usual environment-config tool.

Give UAT and production their own build configs. Build each environment as a separate Android flavour or iOS build configuration, and give each its own return scheme (such as myshop-uat://) or link host. That way a build can only ever be returned to itself, and a UAT checkout can never land in your production app.

Keep the pairing on the server: when an app build requests a payment session, your server must create it with that build's return URLs. The simplest approach is to send the build's environment or scheme with the session request and have the server look up the matching URLs.

Set up the return into your app

Use App Links (Android) and Universal Links (iOS) for the return. They're the secure choice because the OS verifies that your app owns the link host, so no other app can intercept the checkout return.

Custom schemes (myshop://) are simpler to set up since they need no domain verification, but any app can register the same scheme and claim your return. If you use one anyway, keep it unique to your app and treat it as a convenience for development, not the return path for a production release.

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

android {
  flavorDimensions "environment"
  productFlavors {
    uat {
      dimension "environment"
      applicationIdSuffix ".uat"
      manifestPlaceholders = [qasimhaReturnScheme: "myshop-uat"]
    }
    production {
      dimension "environment"
      manifestPlaceholders = [qasimhaReturnScheme: "myshop"]
    }
  }
}

<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/" />
</intent-filter>

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.shop",
    "sha256_cert_fingerprints": ["AB:CD:EF:..."]
  }
}]

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array><string>myshop</string></array>
  </dict>
</array>

{
  "applinks": {
    "details": [
      { "appIDs": ["TEAMID.com.example.shop"], "components": [ { "/": "/qasimha/*" } ] }
    ]
  }
}

import React

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
  return RCTLinkingManager.application(app, open: url, options: options)
}

func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  return RCTLinkingManager.application(application, continue: userActivity, restorationHandler: restorationHandler)
}

Then pass every incoming link to handleReturn, once, near the root of your app:

import { useEffect } from 'react';
import { Linking } from 'react-native';
import { handleReturn } from '@qasimha/react-native-sdk';

export function useQasimhaReturn() {
  useEffect(() => {
    const subscription = Linking.addEventListener('url', ({ url }) => {
      if (!handleReturn(url)) routeMyOwnDeepLink(url);
    });
    Linking.getInitialURL().then((url) => url && handleReturn(url));
    return () => subscription.remove();
  }, []);
}

handleReturn(url) returns true when the URL matched the pending checkout (the checkout resolves and the sheet closes), and false otherwise, including when no checkout is pending. Keep your own deep-link handling for the false case. With presentation: 'webAuthenticationSession' on iOS, the return does not need this wiring.

Start a checkout

Get paymentUrl and merchantUrl from your server and pass the same three return URLs your server sent to POST /api/v1/pay/session/create.

import { startCheckout } from '@qasimha/react-native-sdk';

async function pay(paymentUrl: string) {
  const result = await startCheckout({
    paymentUrl,
    merchantUrl: {
      success: 'https://shop.example/qasimha/return',
      failure: 'https://shop.example/qasimha/return',
      cancel: 'https://shop.example/qasimha/cancel',
    },
    language: 'ar',
  });

  switch (result.type) {
    case 'success':
      await confirmOnServer(result.orderId);
      break;
    case 'failure':
      showDeclined(result.status);
      break;
    case 'cancelled':
      break;
  }
}

API reference

startCheckout(options): Promise<CheckoutResult>

Only one checkout runs at a time. When the shopper dismisses the sheet, startCheckout waits 300 ms before it resolves cancelled, so a return URL still in flight through Linking wins.

handleReturn(url: string): boolean

Call it from Linking's url event and with getInitialURL(). true when the URL matched the pending checkout's return URLs; false otherwise.

isCheckoutInProgress(): boolean

true while a checkout is presented. Use it to disable your pay button.

parseReturnUrl(url, merchantUrl) and validateCheckoutOptions(options)

The pure functions behind the module, for tests and for apps that route the return themselves. parseReturnUrl(url: string, merchantUrl: MerchantUrl): CheckoutResult | null returns null when url is not one of the merchant URLs. validateCheckoutOptions(options) throws QasimhaCheckoutError with INVALID_OPTIONS, or returns the normalised options.

CheckoutResult

type CheckoutResult =
  | { type: 'success'; orderId: string; orderReferenceId?: string }
  | { type: 'failure'; status: string; orderId?: string; orderReferenceId?: string }
  | { type: 'cancelled' };

The URL matches when its scheme, host (with port) and path prefix, at a segment boundary, match one of your merchant URLs, checked in the order success, failure, cancel. Give the cancel URL a dedicated path: a return URL with an empty path matches every link on that host.

QasimhaCheckoutError

startCheckout rejects with QasimhaCheckoutError (code, message, and field for INVALID_OPTIONS):

Handle the result and confirm on your server

A return URL is navigation, not proof. Before showing "paid" or fulfilling, your server reads the order with its secret key (orders.get in the server SDKs, GET /api/v1/merchant/orders/{orderId}) and acts on the status it returns. Your server also receives the webhook, the durable record. Never change an order from the return URL parameters alone.

Keep the orderId your server returned when it created the session. cancelled carries no id, and a payment can complete even when the return link was lost, so confirm with the session's orderId when the result has none. A cancelled order stays AwaitingCheckout and expires on its own; your server may cancel it.

Promo component

import { QasimhaPromo } from '@qasimha/react-native-sdk';

<QasimhaPromo amount={1200} publicKey={publishableKey} lang="ar" textStyle={{ fontSize: 16, color: '#1f2937' }} />

It renders the Qasimha logo and "Split into 4 monthly payments of [symbol] 300", with "Interest-free · Sharia-compliant" under it for Sharia-compliant plans.

• Calls GET /api/v1/widget/plans?amount=1200.00&currency=SAR&lang=ar with X-Public-Key, credentials: 'omit', a 5-second timeout, no cookies, no storage. It reloads when the amount, key, language or host changes.
• Fails closed: renders nothing, never a computed number, when the key, amount or apiBaseUrl is invalid, the request fails or times out, the status is not 2xx, the response is not success: true with currency: "SAR" and a valid plan, or the amount is outside minAmount to maxAmount.
• Place it on product, cart and checkout screens, not in every list row: each mounted instance makes one request.

How the currency symbol is drawn, in order: your renderSymbol; otherwise react-native-svg when it is installed; otherwise an empty box of the symbol's size, hidden from accessibility, so the layout stays stable. The amount is always to the right of the symbol in a left-to-right row, with Latin digits and thousands separators. Screen readers hear the currency name.

Other exports

Plan has instalments, frequency, instalmentAmount, firstInstalmentAmount, lastInstalmentAmount, feesIncludingVat, totalPayable and shariaCompliant.

Complete example

Your server creates the session and returns paymentUrl and merchantUrl (server endpoint). The app presents it and confirms on the server.

import React, { useState } from 'react';
import { Button, Text, View } from 'react-native';
import {
  QasimhaCheckoutError, QasimhaPromo, isCheckoutInProgress, startCheckout,
  type CheckoutResult, type MerchantUrl,
} from '@qasimha/react-native-sdk';

const API = 'https://shop.example';

type Session = { orderId: string; orderReferenceId: string; paymentUrl: string; merchantUrl: MerchantUrl };

export function CheckoutScreen({ items, total, publishableKey, lang }: {
  items: { productId: string; quantity: number }[];
  total: number;
  publishableKey: string;
  lang: 'ar' | 'en';
}) {
  const [message, setMessage] = useState<string | null>(null);
  const [busy, setBusy] = useState(false);

  const confirm = async (orderId: string) => {
    const response = await fetch(`${API}/api/orders/${encodeURIComponent(orderId)}`);
    const order = (await response.json()) as { status: string; paid: boolean };
    setMessage(order.paid ? 'Order confirmed. Thank you.' : `Payment not completed (${order.status}).`);
  };

  const pay = async () => {
    if (isCheckoutInProgress()) return;
    setBusy(true);
    setMessage(null);
    try {
      const response = await fetch(`${API}/api/checkout`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
        body: JSON.stringify({ items }),
      });
      if (response.status !== 201) throw new Error(`HTTP ${response.status}`);
      const session = (await response.json()) as Session;

      const result: CheckoutResult = await startCheckout({
        paymentUrl: session.paymentUrl,
        merchantUrl: session.merchantUrl,
        language: lang,
      });
      // Confirm every outcome on the server; a cancelled result carries no order id.
      const orderId = result.type !== 'cancelled' && result.orderId ? result.orderId : session.orderId;
      await confirm(orderId);
    } catch (error) {
      setMessage(error instanceof QasimhaCheckoutError ? `Could not open the checkout (${error.code}).` : 'Could not start the payment.');
    } finally {
      setBusy(false);
    }
  };

  return (
    <View>
      <QasimhaPromo amount={total} publicKey={publishableKey} lang={lang} />
      <Button title="Pay with Qasimha" onPress={pay} disabled={busy} />
      {message ? <Text>{message}</Text> : null}
    </View>
  );
}

Call useQasimhaReturn() (above) once in your root component.

Test in UAT

1. Point a UAT build at a server using your sk_test_... key. Use a pk_test_... key for the promo.
2. Run every path on a real Android device and a real iPhone: finish, decline, cancel on the hosted page, and dismiss the sheet. Check each result and that the app asks your server before it shows "paid".
3. Kill the app while the checkout is open, then finish the payment. Check that your server still finds the order through the webhook or the session's orderId.
4. If you use webAuthenticationSession on iOS, test it on your oldest supported iOS version, with the return URLs you ship.
5. Check the promo shows for an amount in your range and is hidden for one outside it, with and without react-native-svg.

Release builds

• Android: consumer R8 rules are shipped; nothing to add.
• iOS: symbols are stripped in your release build with the rest of the app. The iOS module ships a privacy manifest declaring no tracking.
• Metro and react-native-svg: the module loads react-native-svg with an optional require. Metro's resolver.allowOptionalDependencies is false by default, so an app without react-native-svg may fail to bundle. Install react-native-svg or set that option to true.

Go-live checklist

• The production build uses pk_live_...; the server uses sk_live_... and sends the production return URLs.
• assetlinks.json and apple-app-site-association are served from the production return domain.
• qasimhaReturnScheme and the iOS URL scheme are unique to your app.
• useQasimhaReturn() runs at the root, so every screen hands return links over.
• The app confirms every order with your server; your server also processes the webhook.

Security

• No secret on the device. The only credential in the app is the publishable key for the promo, which the API scopes to reading plans.
• TLS validation is the platform's; no option to disable it and no certificate pinning.
• No storage, analytics or fingerprinting. Nothing is written to logs.
• PCI DSS: card entry happens on the hosted checkout and the payment provider. You stay in SAQ-A scope.
• App hardening: root/jailbreak detection, anti-tamper and runtime protection are recommended for apps that present payments. Use a RASP product or the platform's integrity APIs; the module does not perform them.

Troubleshooting

Related