Mobile SDK (React Native)

Requirements

React Native 0.73+ or Expo SDK 50+
react-native-webview >= 13
react-native-safe-area-context >= 4

Expo Go can preview the sheet and hosted eSewa/Khalti screens. Native QR sharing and reliable installed-app detection require the config plugin and a development build. Expo Go cannot apply native app-query configuration.

Installation

npm install @paybridge-np/mobile-sdk react-native-webview react-native-safe-area-context

yarn add @paybridge-np/mobile-sdk react-native-webview react-native-safe-area-context

npx expo install @paybridge-np/mobile-sdk react-native-webview react-native-safe-area-context

Add the config plugin, then rebuild the native app:

app.json

{
  "expo": {
    "scheme": "myapp",
    "plugins": ["@paybridge-np/mobile-sdk"]
  }
}

npx expo prebuild

Use your normal local or EAS development-build command after prebuild. eSewa’s sandbox Intent app is currently an Android UAT APK.

How it works

Your backend creates an amount-bound session using your secret API key. Your app receives that short-lived session and uses a publishable key to present the server-approved methods. Your secret API key never touches the device.

Your backend  →  POST /v1/mobile/session (secret key)  →  { session_id, client_secret, methods }
Mobile app    →  PaymentSheet (publishable key)         →  server-confirmed result

Payment sheet (recommended)

The payment sheet asks your backend for one session and renders whatever payment methods PayBridgeNP resolved for that merchant. Your app never picks a provider and never builds a payment UI, so turning Fonepay on for a merchant is a dashboard change, not an app release.

The payment sheet showing Bank App, Fonepay QR, eSewa and Khalti — A merchant with Fonepay: Bank App (detected apps only), Fonepay QR, eSewa, Khalti.

The payment sheet showing Fonepay QR, eSewa and Khalti — The same sheet for a merchant without Fonepay bank-app access: Fonepay QR, eSewa, Khalti.

1. Your backend creates a session

Session creation requires the payments:write scope when your secret key has an explicit scope list. Unrestricted secret keys continue to work. The app uses a publishable key and the session client secret for the device calls. Call POST /v1/mobile/session with your secret key and no provider:

curl -X POST https://api.paybridgenp.com/v1/mobile/session \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: order_123_mobile" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 245000,
    "currency": "NPR",
    "customer": {
      "name": "Ram Bahadur",
      "email": "ram@example.com",
      "phone": "98XXXXXXXX"
    }
  }'

{
  "session_id": "cs_...",
  "client_secret": "mcs_...",
  "amount": 245000,
  "expires_at": "2026-08-16T12:15:00Z",
  "methods": [
    { "id": "fonepay_qr", "provider": "fonepay", "label": "Fonepay QR" },
    { "id": "bank_intent", "provider": "fonepay", "label": "Bank App", "banks": [ ... ] },
    { "id": "esewa", "provider": "esewa", "label": "eSewa", "esewa_intent_eligible": true },
    { "id": "khalti", "provider": "khalti", "label": "Khalti" }
  ]
}

methods is computed server-side from the merchant’s enabled providers, their mode, their plan and the amount. A method the merchant cannot actually use is never returned, so the sheet cannot show a dead option. The device puts Bank App before Fonepay QR when a supported bank app is installed. One installed bank opens directly; multiple installed banks appear in a compact picker. Eligible eSewa Intent opens only when the eSewa app is detected. Otherwise, the sheet keeps the buyer in eSewa’s hosted checkout. Return session_id and client_secret to your app. Do not send your secret key to the device. Use one stable Idempotency-Key per merchant order. A retry after a timeout or app restart then returns the same session instead of creating a second payable session.

2. Your app presents the sheet

import { usePaymentSheet, PaymentSheet } from "@paybridge-np/mobile-sdk";

export default function CheckoutScreen() {
  const { present, paymentSheetProps } = usePaymentSheet({
    publishableKey: "pk_live_...",
    // Required for eSewa Intent. Configure the same scheme in app.json.
    returnUrl: "myapp://paybridge/return",
    // Use config: { baseUrl: "https://staging-api.example.com" } outside production.
    fetchSession: () =>
      fetch("https://your-backend.com/api/mobile-session", { method: "POST" })
        .then((r) => r.json()),
    onComplete: ({ status, sessionId }) => {
      if (status === "success") console.log("server reports paid", sessionId);
    },
    onCancel: () => {},
    onError: (err) => console.error(err),
  });

  return (
    <>
      <Button title="Pay" onPress={present} />
      <PaymentSheet {...paymentSheetProps} />
    </>
  );
}

The device authenticates with your publishable key plus the per-session client secret. The publishable key is safe to ship in your app; the client secret authorises exactly one payment and expires with the session.

How each method behaves

Method	What happens
Fonepay QR	The QR renders natively in your app’s theme with an expiry countdown and waiting/scanned feedback. PayBridgeNP holds the Fonepay connection server-side and safely refreshes an expired display QR while continuing to watch older payable attempts.
Bank App	This method appears only when at least one supported bank app is detected on the device, and lists only detected apps. Tapping opens the bank with the server-produced Fonepay payload. Requires the Enterprise plan in live mode.
eSewa	Opens eSewa Intent when the server marks the session eligible and `returnUrl` is configured. If the app cannot open, the buyer can retry it; another method is exposed only after provider-side cancellation. Other sessions use ePay v2 directly. Returning from the app checks server status before the picker can reopen.
Khalti	Khalti’s hosted page, in a managed in-app screen showing your merchant name and the amount.

Choose bank app: the detected bank apps listed in the sheet — Bank App lists only the bank apps installed on the device.

Fonepay QR shown inside the payment sheet with an expiry countdown — Fonepay QR renders natively with a countdown and a Share QR button.

Confirming a payment

onComplete runs after PayBridgeNP’s status endpoint reports success or expired. Failed or cancelled provider attempts return to the method picker when it is safe to retry. A buyer can still close their bank app after paying, so your backend must treat the payment.succeeded webhook as the fulfillment authority, exactly as it does on web.

The demo shop showing the paid state after the sheet completed — The demo app after onComplete: the sheet heard success, the server's webhook is still the final word.

App restart recovery

The SDK does not own your app navigation or silently persist a client secret. Keep the active session in platform-secure storage and call resume(session) after restoring your checkout screen. Clear it after onComplete or an explicit sheet close. On Android, initialise callbacks from lifecycle setup rather than depending on in-memory checkout variables.

Theming

appearance accepts tokens only: colors, radius, typography and the primary button. Light and dark are both supported. Layout is deliberately not overridable so the sheet stays upgradeable.

Usage (legacy `usePayBridgeNP`)

usePayBridgeNP and ProviderSheet require your app to choose the provider before a session exists, which means the provider list lives in your app and changing it needs an app release. They still work and are not going away without notice, but new integrations should use the payment sheet above.

`usePayBridgeNP` hook (recommended)

Let the user pick the provider - session is created lazily after they tap.

import { usePayBridgeNP, ProviderSheet } from "@paybridge-np/mobile-sdk";

export default function CheckoutScreen() {
  const { present, sheetProps } = usePayBridgeNP({
    createSession: async (provider) => {
      const res = await fetch("https://your-backend.com/api/mobile-session", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ provider, amount: 5000 }),
      });
      return res.json();
    },
    amount: 5000, // paisa - shown in sheet before session is created
    onSuccess: (result) => console.log("paid", result.payment_id),
    onFailure: (result) => console.log("failed", result.error),
    onCancel: () => console.log("cancelled"),
  });

  return (
    <>
      <Button title="Pay NPR 50" onPress={present} />
      <ProviderSheet {...sheetProps} />
    </>
  );
}

Pre-built session

Use this when your backend picks the provider before showing the sheet.

import { useState, useEffect } from "react";
import { usePayBridgeNP, ProviderSheet } from "@paybridge-np/mobile-sdk";
import type { MobileSession } from "@paybridge-np/mobile-sdk";

export default function CheckoutScreen() {
  const [session, setSession] = useState<MobileSession | null>(null);

  useEffect(() => {
    fetch("https://your-backend.com/api/mobile-session", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ provider: "khalti", amount: 5000 }),
    })
      .then((r) => r.json())
      .then(setSession);
  }, []);

  const { present, sheetProps } = usePayBridgeNP({
    session,
    onSuccess: (result) => console.log("paid", result.payment_id),
    onFailure: (result) => console.log("failed", result.error),
    onCancel: () => console.log("cancelled"),
  });

  return (
    <>
      <Button title="Pay" onPress={present} disabled={!session} />
      <ProviderSheet {...sheetProps} />
    </>
  );
}

`ProviderSheet` directly

import { ProviderSheet } from "@paybridge-np/mobile-sdk";

<ProviderSheet
  visible={sheetVisible}
  createSession={handleCreateSession}
  amount={5000}
  onSuccess={handleSuccess}
  onFailure={handleFailure}
  onCancel={handleCancel}
/>

API reference

`usePayBridgeNP(options)`

Option	Type	Required	Description
`session`	`MobileSession \| null`	No	Pre-built session from your backend
`createSession`	`(provider) => Promise<MobileSession>`	No	Lazy factory - called when user picks a provider
`amount`	`number`	No	Amount in paisa - shown before session is created (lazy mode)
`config`	`PayBridgeNPMobileConfig`	No	Custom `baseUrl`, `timeout`
`onSuccess`	`(result: CheckoutResult) => void`	Yes	Called on successful payment
`onFailure`	`(result: CheckoutResult) => void`	Yes	Called on failed payment
`onCancel`	`() => void`	Yes	Called when the user closes the sheet; does not cancel the server session

Returns { present, dismiss, isVisible, sheetProps }.

Pass either session or createSession - not both. createSession is preferred as it defers session creation until the user has picked a provider.

`ProviderSheet` props

Same options as usePayBridgeNP, plus visible: boolean.

`PayBridgeNPMobileConfig`

PayBridgeMobileConfig is still exported as a deprecated alias, so existing imports keep compiling.

Field	Default	Description
`baseUrl`	`https://api.paybridgenp.com`	PayBridgeNP API base URL
`timeout`	`30000`	Request timeout in ms

`CheckoutResult`

type CheckoutResult = {
  status: "success" | "failed" | "cancelled";
  payment_id?: string;
  amount?: number;        // paisa
  provider?: "esewa" | "khalti";
  provider_ref?: string;
  error?: string;
};

`MobileSession`

type MobileSession = {
  session_id: string;
  expires_at: string;    // ISO timestamp - expires in 15 minutes
  provider: "esewa" | "khalti";
  amount: number;        // paisa
  native_params: Record<string, string | number>;
};

Sandbox testing

Create the session on your backend with a sk_test_... key and the sheet runs in test mode. In test mode, PayBridgeNP uses its own eSewa and Khalti sandbox credentials, so you do not configure anything for those two providers; the buyer just logs into the provider’s test environment with the test accounts below. Fonepay is different: it has no test environment at all. eSewa (sandbox, rc-epay.esewa.com.np)

Field	Value
eSewa ID	`9806800001` through `9806800005`
Password	`Nepal@123`
MPIN	`1122`
Token / OTP	`123456`

Khalti (test checkout, test-pay.khalti.com)

Field	Value
Khalti ID	`9800000005` (recommended)
MPIN	`1111`
OTP	`987654`

Khalti’s test wallets are shared by every integrator. 9800000001 to 9800000004 are often drained or return “insufficient balance”, “similar request already being processed”, or a 400; those messages come from Khalti’s sandbox, not from your integration. Fonepay (no sandbox, real money)

Fonepay has no test environment. In test mode the sheet shows Fonepay only if your project has its own Fonepay merchant credentials configured (dashboard, Providers), and it then runs against the real Fonepay network: the QR and bank-app payments move real money. PayBridgeNP caps test-mode Fonepay at NPR 1,000 per payment and NPR 5,000 per month, so keep test amounts tiny (NPR 10 works fine).

The sandbox testing guide walks through the same flow on the hosted checkout page.

SDKs

Tools

Mobile SDK (React Native)

Requirements

Installation

How it works

Payment sheet (recommended)

1. Your backend creates a session

2. Your app presents the sheet

How each method behaves

Confirming a payment

App restart recovery

Theming

Usage (legacy `usePayBridgeNP`)

`usePayBridgeNP` hook (recommended)

Pre-built session

`ProviderSheet` directly

API reference

`usePayBridgeNP(options)`

`ProviderSheet` props

`PayBridgeNPMobileConfig`

`CheckoutResult`

`MobileSession`

Sandbox testing

​Requirements

​Installation

​How it works

​Payment sheet (recommended)

​1. Your backend creates a session

​2. Your app presents the sheet

​How each method behaves

​Confirming a payment

​App restart recovery

​Theming

​Usage (legacy usePayBridgeNP)

​usePayBridgeNP hook (recommended)

​Pre-built session

​ProviderSheet directly

​API reference

​usePayBridgeNP(options)

​ProviderSheet props

​PayBridgeNPMobileConfig

​CheckoutResult

​MobileSession

​Sandbox testing

Requirements

Installation

How it works

Payment sheet (recommended)

1. Your backend creates a session

2. Your app presents the sheet

How each method behaves

Confirming a payment

App restart recovery

Theming

Usage (legacy `usePayBridgeNP`)

`usePayBridgeNP` hook (recommended)

Pre-built session

`ProviderSheet` directly

API reference

`usePayBridgeNP(options)`

`ProviderSheet` props

`PayBridgeNPMobileConfig`

`CheckoutResult`

`MobileSession`

Sandbox testing