Mobile SDK (React Native)

Requirements

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

Compatible with Expo Go - no custom dev build or config plugin required.

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

How it works

Your backend creates a checkout session using your secret API key. The session is passed to the mobile SDK - your API key never touches the device.

Your backend  →  POST /v1/mobile/session (API key)  →  { session_id, native_params }
Mobile app    →  ProviderSheet / usePayBridgeNP        →  onSuccess(result)

Backend: create a session

Call POST /v1/mobile/session from your server:

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

Response:

{
  "session_id": "cs_XXXX",
  "expires_at": "2026-04-14T12:00:00Z",
  "provider": "khalti",
  "amount": 5000,
  "native_params": { ... }
}

Field	Required	Description
`amount`	Yes	In paisa (1 NPR = 100 paisa)
`provider`	Yes	`"esewa"` or `"khalti"`
`customer.name`	Yes	Customer’s full name
`customer.email`	Yes	Customer’s email address
`customer.phone`	Yes	Customer’s phone number
`description`	No	Optional payment description
`metadata`	No	Optional key-value metadata
`expires_at`	-	Session expires in 15 minutes (response field)

Usage

`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`	`PayBridgeMobileConfig`	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 user cancels

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.

`PayBridgeMobileConfig`

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

Use sk_test_... keys on your backend. The sandbox uses real provider test environments - no extra setup needed. eSewa sandbox test credentials

Field	Value
eSewa ID	`9806800001` (or 02/03/04/05)
Password	`Nepal@123`
Token	`123456`

Khalti sandbox is handled automatically via your sk_test_... PayBridgeNP key.

​Requirements

​Installation

​How it works

​Backend: create a session

​Usage

​usePayBridgeNP hook (recommended)

​Pre-built session

​ProviderSheet directly

​API reference

​usePayBridgeNP(options)

​ProviderSheet props

​PayBridgeMobileConfig

​CheckoutResult

​MobileSession

​Sandbox testing

Requirements

Installation

How it works

Backend: create a session

Usage

`usePayBridgeNP` hook (recommended)

Pre-built session

`ProviderSheet` directly

API reference

`usePayBridgeNP(options)`

`ProviderSheet` props

`PayBridgeMobileConfig`

`CheckoutResult`

`MobileSession`

Sandbox testing