@glomopay/react-native-sdk 2.0.2 → 3.1.0

package/README.md

@@ -1,135 +1,107 @@
-# GlomoPay React Native SDK 💳
+# GlomoPay React Native SDK
 
 [![npm version](https://img.shields.io/npm/v/@glomopay/react-native-sdk.svg)](https://www.npmjs.com/package/@glomopay/react-native-sdk)
 [![License](https://img.shields.io/npm/l/@glomopay/react-native-sdk.svg)](LICENSE)
 
 Official React Native SDK for integrating GlomoPay payment checkout flows into your mobile applications.
 
-## ✨ Features
-
-- 📱 **Cross-Platform** - Works seamlessly on both iOS and Android
-- 🔷 **TypeScript Support** - Full type definitions included
-- ⚡ **Simple Integration** - Minimal configuration required
-- 🔒 **Secure** - WebView-based checkout with signature verification
-- 🛡️ **Device Security Compliance** - Prevents unsafe/non-compliant devices from initiating checkouts as per regulatory policies
-- 💰 **Flexible** - Support for multiple payment methods through GlomoPay
-
-## 📋 Prerequisites
-
-Before using this SDK, you need:
+## Prerequisites
 
 - API credentials (Public Key) from your GlomoPay dashboard
+- An order ID created via the GlomoPay API
 
-## 🛠️ System Requirements
-
-- React Native >= 0.68.0
-- React >= 17.0.0
-- Node.js >= 16.0.0
-- npm >= 8.0.0
+## System Requirements
 
-## 📦 Installation
+| Requirement            | Version      |
+| ---------------------- | ------------ |
+| Node.js                | >= 16.0.0    |
+| npm                    | >= 8.0.0     |
+| React                  | >= 17.0.0    |
+| React Native           | >= 0.68.0    |
+| react-native-webview   | ^13.0.0      |
+| jail-monkey (optional) | ^2.6.0       |
 
-### 📲 1. Standard React Native CLI project
+## Installation
 
-For standard installations, this SDK requires `react-native-webview` as a peer dependency. Install it first:
+### React Native CLI
 
 ```bash
-npm install react-native-webview
+npm install @glomopay/react-native-sdk react-native-webview
+cd ios && pod install
 ```
 
-Then install the SDK
+### Expo
 
 ```bash
-npm install @glomopay/react-native-sdk
+npx expo install @glomopay/react-native-sdk react-native-webview
 ```
 
-**🔒 Recommended: Enhanced Security Compliance**
+### Recommended: Device Security Compliance
 
-For enhanced device security compliance (rooted/jailbroken device detection), we HIGHLY recommend installing the peer dependency `jail-monkey`:
+For rooted/jailbroken device detection (strongly recommended for regulated flows):
 
 ```bash
 npm install jail-monkey
 ```
 
-**Note:** The SDK works without `jail-monkey`, but installing it enables automatic device security compliance checks that help meet regulatory requirements. See [Device Security Compliance](#device-security-compliance-) section for more details.
-
-### 🔧 2. Expo Projects
-
-This SDK is compatible with Expo projects. Install with:
-
-```bash
-npx expo install react-native-webview
-npx expo install @glomopay/react-native-sdk
-```
-
-**Note**: Requires custom dev client or EAS Build. Not compatible with Expo Go app.
-
-For Expo Go limitations, see [Expo documentation](https://docs.expo.dev/workflow/customizing/).
-
-## 🚀 Quick Start
-
-Before start the checkout flow, you'll need to create an LRS order using other Glomo SDKs and obtain the Order ID (Alphanumeric, starts with `order_`).
+The SDK works without `jail-monkey`, but installing it enables automatic device security checks. Without it, the SDK logs a warning on every `start()` call.
 
-### Breaking Changes (latest)
-
-- `educationURL` has been removed from the public API. The SDK now manages any educational content behavior internally.
-
-### 1. Import the SDK
+## Quick Start
 
 ```tsx
+import React, { useRef } from "react";
+import { View, Button } from "react-native";
 import {
-  GlomoLrsCheckout,
-  type GlomoLrsCheckoutRef,
+  GlomoCheckout,
+  type GlomoCheckoutRef,
+  type GlomoCheckoutPayload,
   type SdkError,
-} from '@glomopay/react-native-sdk';
-```
-
-### 2. Add the Component to Your App
-
-```tsx
-import React, { useState, useRef } from 'react';
-import { View } from 'react-native';
-import {
-  GlomoLrsCheckout,
-  type GlomoLrsCheckoutRef,
-} from '@glomopay/react-native-sdk';
+} from "@glomopay/react-native-sdk";
 
-function CheckoutScreen()
-{  
-  const [orderId, setOrderId] = useState('YOUR_ORDER_ID');
-  const checkoutRef = useRef<GlomoLrsCheckoutRef>(null);
+export default function PaymentScreen() {
+  const checkoutRef = useRef<GlomoCheckoutRef>(null);
 
-  const startLrsCheckout = () => {
-    const started = checkoutRef.current?.start();
+  const handlePay = async () => {
+    const started = await checkoutRef.current?.start();
     if (!started) {
-      const status = checkoutRef.current?.getStatus();
-      console.log('Checkout could not be started. Current status:', status);
+      console.log("Checkout could not start - check onSdkError for details");
     }
   };
 
   return (
-    <View>
-      <GlomoLrsCheckout
+    <View style={{ flex: 1 }}>
+      <Button title="Pay Now" onPress={handlePay} />
+
+      <GlomoCheckout
         ref={checkoutRef}
-        publicKey={'YOUR_PUBLIC_KEY'}
-        orderId={orderId}
-        onPaymentSuccess={(payload) => {
-          console.log('Payment successful!', payload);
-          // Handle successful payment
+        publicKey="live_pk_abc123"
+        orderId="order_xyz789"
+        onPaymentSuccess={(payload: GlomoCheckoutPayload) => {
+          console.log("Payment success:", payload.paymentId);
+        }}
+        onPaymentFailure={(payload: GlomoCheckoutPayload) => {
+          console.log("Payment failed:", payload.paymentId);
         }}
-        onPaymentFailure={(payload) => {
-          console.log('Payment failed!', payload);
-          // Handle failed payment
+        onPaymentTerminate={() => {
+          console.log("User dismissed checkout");
         }}
         onConnectionError={(error) => {
-          console.log('Could not open LRS checkout!', error);
-          // Handle connection/network errors
+          console.log("Connection error:", error);
+        }}
+        onBankTransferSubmitted={(payload) => {
+          console.log("Bank transfer submitted:", payload?.transactionReference);
+        }}
+        onPayViaBankCompleted={(payload) => {
+          console.log("Pay via bank completed:", payload.status);
+        }}
+        onPayViaBankBankConnectionSuccessful={(payload) => {
+          console.log("Bank connected:", payload?.bankName);
         }}
-        onSdkError={(errors) => {
-          errors.forEach((error) => {
-            console.error('SDK Error:', error.message);
-            // Handle validation errors
-          });
+        onUserRefusedCameraPermissions={() => {
+          console.log("User refused camera - cannot proceed with bank authentication");
+        }}
+        onSdkError={(errors: SdkError[]) => {
+          errors.forEach((e) => console.error(e.type, e.message, e.field));
         }}
       />
     </View>
@@ -137,314 +109,374 @@ function CheckoutScreen()
 }
 ```
 
-## 📚 API Reference
+## Breaking Changes (v3)
 
-### `GlomoLrsCheckout` Component
+- `GlomoLrsCheckout` has been replaced by `GlomoCheckout` - the new component now works for all checkout orders (including LRS)
+- `start()` is now async - returns `Promise<boolean>` instead of `boolean`
+- All LRS-specific exports have been renamed (e.g. `GlomoLrsCheckoutRef` -> `GlomoCheckoutRef`)
 
-#### Props
+For migration details, see the [Migration from v2](#migration-from-v2) section below or MIGRATION.md included in this package.
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `publicKey` | `string` | Yes | Your public key. If it starts with `test_`, mock mode will be enabled automatically. Otherwise, live mode is used. |
-| `orderId` | `string` | Yes | The order ID for this transaction. Must start with `order_` |
-| `onPaymentSuccess` | `(payload: GlomoLrsCheckoutPayload) => void` | Yes | Callback function called when the payment is successful |
-| `onPaymentFailure` | `(payload: GlomoLrsCheckoutPayload) => void` | Yes | Callback function called when the payment fails |
-| `onConnectionError` | `(error: unknown) => void` | No | Will be called on network connection problems. The checkout modal will automatically close before this is triggered. |
-| `onPaymentTerminate` | `() => void` | No | Callback called when checkout is terminated. Triggered when the `checkout.closed` event is received from the WebView or when the user dismisses the modal (iOS swipe down) or presses the back button (Android) |
-| `onSdkError` | `(errors: SdkError[]) => void` | No | Callback for SDK validation errors and configuration issues. Receives an array of `SdkError` objects when validation fails. |
-| `devMode` | `boolean` | No | Enable debug logging (default: `false`) |
-| `visible` | `boolean` | No | Control modal visibility manually (advanced usage only). It is HIGHLY recommended to not use this prop directly. |
+## Subscriptions Checkout
 
-### Ref Methods
+To process subscription payments, pass a `subscriptionId` instead of an `orderId`:
 
 ```tsx
-interface GlomoLrsCheckoutRef {
-  start: () => boolean;  // Starts the checkout flow. Returns true if started, false if it cannot be started.
-  getStatus: () => LrsCheckoutStatus;  // Returns the current checkout status
-}
+<GlomoCheckout
+  ref={checkoutRef}
+  publicKey="live_pk_abc123"
+  subscriptionId="sub_xyz789"
+  onPaymentSuccess={(payload) => {
+    console.log("Subscription payment success:", payload.paymentId);
+  }}
+  onPaymentFailure={(payload) => {
+    console.log("Subscription payment failed:", payload.paymentId);
+  }}
+  onSdkError={(errors) => {
+    errors.forEach((e) => console.error(e.type, e.message));
+  }}
+/>
 ```
 
-Usage:
+When `subscriptionId` is provided:
+- The SDK skips order type detection (no API call)
+- The `subscriptionId` must start with `sub_`
+- Bank transfer callbacks (`onBankTransferSubmitted`, `onPayViaBankCompleted`) are not applicable - subscriptions are card-only
+- Do not pass both `orderId` and `subscriptionId` - the SDK will fire `onSdkError`
+- The `detecting_order_type` status is not emitted for subscription flows
+
+## Features
+
+- **Cross-platform** - works on both iOS and Android
+- **TypeScript** - full type definitions for all exports
+- **Unified checkout** - renders the correct checkout flow automatically based on your order
+- **Bank transfer support** - callback for bank transfer submission events
+- **Pay via bank** - bank payment flow completion and connection callbacks
+- **Camera permissions** - built-in handling for bank authentication
+- **Device security** - optional **(but strongly recommended)** `jail-monkey` integration for rooted/jailbroken device detection
+- **Input validation** - publicKey and orderId format enforcement before checkout starts
+- **Mock mode** - test with `test_` / `mock_` prefixed keys without hitting production
+
+## useGlomoCheckout Hook (Deprecated)
+
+> **Deprecated** - Legacy hook, will be removed in a future major version.
+
+`useGlomoCheckout` is a legacy placeholder from the v1.x hook-based API. In v1.x, the equivalent
+hook (`useLrsCheckout`) provided reactive WebView state and rendering primitives that merchants used
+to build custom checkout UIs. In v3, the inner checkout components are no longer exported, making
+this hook ineffective for custom rendering.
+
+The hook's public return type (`UseGlomoCheckoutReturn`) exposes:
+- `start()` - identical to `GlomoCheckoutRef.start()`. Returns `Promise<boolean>`.
+- `getStatus()` - returns a point-in-time `CheckoutStatus` snapshot. **Not reactive** - does not
+  trigger re-renders when status changes.
+
+**Use the `GlomoCheckout` component with a ref instead:**
+
 ```tsx
-const checkoutRef = useRef<GlomoLrsCheckoutRef>(null);
-
-// Start checkout - returns true if successful, false otherwise
-const started = checkoutRef.current?.start();
-if (started) {
-  console.log('Checkout started successfully');
-} else {
-  console.log('Checkout could not be started. Check the status.');
-}
+import React, { useRef } from "react";
+import { GlomoCheckout, type GlomoCheckoutRef } from "@glomopay/react-native-sdk";
+
+const checkoutRef = useRef<GlomoCheckoutRef>(null);
+
+// Start checkout
+const started = await checkoutRef.current?.start();
+
+// Check status (point-in-time, same as hook)
+const status = checkoutRef.current?.getStatus();
+```
+
+The component-based API provides the same functionality with proper lifecycle management.
+
+## API Reference
 
-// Check status
-const currentStatus = checkoutRef.current?.getStatus();
+### GlomoCheckout Component
+
+The unified checkout component. Place it in your render tree and control it via a ref.
+
+```tsx
+<GlomoCheckout ref={checkoutRef} {...props} />
 ```
 
-**Note:**
-  - The `start()` method returns `true` if the checkout was started successfully, `false` otherwise
-  - The `start()` method performs device compliance checks first (before any other validation) **if `jail-monkey` is installed**.
-    - If the device is rooted or jailbroken and `jail-monkey` is available, it will return `false` and trigger the `onSdkError` callback with a `device_forbidden` error.
-    - If `jail-monkey` is not installed, compliance checks are skipped and checkout proceeds normally.
-  - The `start()` method may be used to restart an LRS checkout for an existing order,
-    - If the user cancelled the payment midway (`"payment_cancelled"` status) by pressing the back button on Android, or dismissing the modal on iOS
-    - Or if the payment failed or timed-out (`"payment_failed"` status)
-  - After an LRS checkout for an `orderId` is successful, further calls to the `start()` method will return false, and will not re-trigger an LRS checkout (`"payment_successful"` status)
-  - Changing the `orderId`/`publicKey` props resets the flow, and `start()` can be triggered again
-
-#### `GlomoLrsCheckoutPayload`
-
-
-```typescript
-interface GlomoLrsCheckoutPayload {
-  orderId: string;    // Order identifier (e.g., "order_abc123")
-  paymentId: string;  // Payment id from GlomoPay
-  signature: string;  // Signature for verification
+#### Props (`GlomoCheckoutProps`)
+
+| Prop                             | Type                                            | Required | Description                                                         |
+| -------------------------------- | ----------------------------------------------- | -------- | ------------------------------------------------------------------- |
+| `publicKey`                      | `string`                                        | Yes      | Your GlomoPay public key (must start with `live_`, `mock_`, or `test_`) |
+| `orderId`                        | `string`                                        | No*      | Order ID from the GlomoPay API (must start with `order_`)          |
+| `subscriptionId`                 | `string`                                        | No*      | Subscription ID (must start with `sub_`). Bypasses order type detection. |
+| `onPaymentSuccess`               | `(payload: GlomoCheckoutPayload) => void`       | Yes      | Called when payment succeeds                                        |
+| `onPaymentFailure`               | `(payload: GlomoCheckoutPayload) => void`       | Yes      | Called when payment fails                                           |
+| `onConnectionError`              | `(error: unknown) => void`                      | No       | Called on network/connection errors                                 |
+| `onPaymentTerminate`             | `() => void`                                    | No       | Called when user dismisses checkout (back button or swipe)          |
+| `onSdkError`                     | `(errors: SdkError[]) => void`                  | No       | Called on validation errors or device compliance failures           |
+| `onBankTransferSubmitted`        | `(payload: GlomoBankTransferPayload \| null \| undefined) => void` | No | Called when user submits bank transfer details |
+| `onPayViaBankCompleted`          | `(payload: { status: string }) => void`         | No       | Called when pay via bank flow completes         |
+| `onPayViaBankBankConnectionSuccessful` | `(payload: GlomoPayViaBankConnectionPayload \| null \| undefined) => void` | No | Called when bank connection is established during pay via bank flow |
+| `onUserRefusedCameraPermissions` | `() => void`                                    | No       | Called when user denies camera access needed for bank authentication                |
+
+*Exactly one of `orderId` or `subscriptionId` must be provided. If both or neither are set, `onSdkError` fires and `start()` returns `false`.
+
+#### Ref Methods (`GlomoCheckoutRef`)
+
+| Method       | Signature                | Description                                                                                               |
+| ------------ | ------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `start()`    | `() => Promise<boolean>` | Validates inputs, and opens the checkout modal. Resolves `true` if successful, `false` otherwise.         |
+| `getStatus()`| `() => CheckoutStatus`   | Returns the current checkout status.                                                                      |
+
+#### CheckoutStatus
+
+| Status                     | Description                                                    |
+| -------------------------- | -------------------------------------------------------------- |
+| `ready`                    | Initial state - checkout can be started                        |
+| `detecting_order_type`     | Order type detection in progress (after `start()`, before checkout opens) |
+| `payment_in_progress`      | Checkout modal is open, user is interacting                    |
+| `payment_successful`       | Payment completed successfully. Cannot restart with same order |
+| `payment_failed`           | Payment failed. Can retry with same order                      |
+| `payment_cancelled`        | User dismissed checkout mid-flow. Can retry                    |
+| `bank_transfer_submitted`  | User submitted bank transfer details                           |
+| `pay_via_bank_completed`   | Pay via bank flow completed                                    |
+
+### Type Definitions
+
+#### GlomoCheckoutPayload
+
+```ts
+interface GlomoCheckoutPayload {
+  orderId: string;
+  paymentId: string;
+  signature: string;
 }
 ```
 
-The payload is returned for both successful and failed LRS payments.
+#### GlomoBankTransferPayload
 
-#### `SdkError`
+```ts
+interface GlomoBankTransferPayload {
+  orderId: string;
+  senderAccountNumber: string;
+  transactionReference: string;
+}
+```
 
-The SDK provides validation and error reporting through the `onSdkError` callback:
+#### GlomoPayViaBankConnectionPayload
 
-```typescript
+```ts
+interface GlomoPayViaBankConnectionPayload {
+  bankIdentifier: string;
+  cooldownPeriodInMinutes: number;
+  bankName: string;
+  bankImageSrc: string;
+  bankImageAlt: string;
+}
+```
+
+#### SdkError
+
+```ts
 interface SdkError {
   type: "validation_error" | "device_forbidden";
   message: string;
-  field?: "publicKey" | "orderId" | "baseCheckoutUrl";
+  field?: "publicKey" | "orderId" | "subscriptionId" | "baseCheckoutUrl" | "generatedCheckoutUrl";
 }
 ```
 
-**Error Types:**
-- `validation_error`: Input validation failed (invalid publicKey, orderId, or server/baseCheckoutUrl)
-- `device_forbidden`: Device does not meet compliance requirements (LRS checkout is not permitted on compromised/rooted devices per regulatory policies).
+## Bank Transfer Support
+
+When the checkout flow includes a bank transfer option, the user submits transfer details (account number, reference) through the checkout UI. The SDK fires `onBankTransferSubmitted` with a `GlomoBankTransferPayload`:
 
-**Example:**
 ```tsx
-<GlomoLrsCheckout
-  onSdkError={(errors) => {
-    errors.forEach((error) => {
-      console.error(`SDK Error [${error.type}]:`, error.message);
-      if (error.field) {
-        console.error(`Field: ${error.field}`);
-      }
-    });
-    // Handle validation errors appropriately
-  }}
-  // ... other props
-/>
+onBankTransferSubmitted={(payload) => {
+  // payload may be null/undefined if the checkout page omits it
+  console.log("Transfer ref:", payload?.transactionReference);
+}}
 ```
 
-**Note:** The SDK validates all inputs when `start()` is called. Validation errors are reported through `onSdkError` and `start()` will return `false` if validation fails.
+The checkout status transitions to `bank_transfer_submitted`.
 
-##### Checkout Status System 📊
+## Pay via Bank Support
 
-The SDK provides a status system to track the checkout lifecycle. Access the current status using the `getStatus()` method on the component ref:
+The SDK fires `onPayViaBankCompleted` when the pay-via-bank journey completes:
 
 ```tsx
-const checkoutRef = useRef<GlomoLrsCheckoutRef>(null);
-const currentStatus = checkoutRef.current?.getStatus();
+onPayViaBankCompleted={(payload) => {
+  // payload.status - e.g. "success", "failed", "unknown"
+  console.log("Pay via bank status:", payload.status);
+}}
 ```
 
-#### Status Values
+The checkout status transitions to `pay_via_bank_completed`. The SDK deduplicates this event internally - the callback fires only once per checkout session.
 
-The `LrsCheckoutStatus` type includes the following values:
+Additionally, `onPayViaBankBankConnectionSuccessful` fires when a bank account is successfully connected when initiating a pay-via-bank checkout, before the actual payment completes. This is informational only - it does not change the checkout status. Can be used to show a "bank connected" confirmation UI if desirable, while the payment continues in the background:
+
+```tsx
+onPayViaBankBankConnectionSuccessful={(payload) => {
+  // payload may be null/undefined if the checkout page omits it
+  console.log("Connected to:", payload?.bankName);
+  console.log("Cooldown:", payload?.cooldownPeriodInMinutes, "minutes");
+}}
+```
 
-| Status | Description |
-|--------|-------------|
-| `"ready"` | Checkout is ready to be started |
-| `"payment_in_progress"` | Checkout flow is active and ongoing |
-| `"payment_successful"` | Payment completed successfully |
-| `"payment_failed"` | Payment failed (`glomoLrsCheckoutRef.current?.start()` can be reused with the same `orderId`) |
-| `"payment_cancelled"` | User cancelled the checkout midway (`glomoLrsCheckoutRef.current?.start()` can be reused with the same `orderId`) |
+## Camera Permissions
 
-#### Status Lifecycle
+Some checkout flows may require camera access for bank authentication. The SDK handles permission prompts automatically, but you must declare the permissions in your native project config.
 
+### Android
+
+Add to `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.CAMERA" />
 ```
-ready → payment_in_progress → payment_successful (order complete)
-         ↓                           ↑                    ↑
-  payment_cancelled (can call start() again to restart)   |
-         ↓                           ↑                    ↑
-  payment_failed (can call start() again to retry) → _____⌟
+
+### iOS
+
+Add to `ios/<YourApp>/Info.plist`:
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Camera access is required for identity verification during checkout</string>
 ```
 
-## 📱 Platform-Specific Behavior
+### Behavior
 
-### 🍎 iOS
-- Checkout appears inside a modal within a `pageSheet`
-- Users can dismiss `GlomoLrsCheckout` component by swiping down
-- `onPaymentTerminate` is called when modal is dismissed
+- **Android**: SDK prompts the user via a native permission dialog. If denied, checkout closes and `onUserRefusedCameraPermissions` fires.
+- **iOS**: SDK grants the WebView permission request; iOS shows its own system prompt. If the user denies at the system level, the WebView handles the denial.
 
-### 🤖 Android
-- Checkout appears in full-screen mode
-- Users can press the hardware back button to close the full-screen `GlomoLrsCheckout` component
-- Back button triggers `onPaymentTerminate` and closes checkout
+## Platform Behavior
 
-## 🔧 Troubleshooting
+- **iOS**: Checkout opens as a `pageSheet` modal (swipe-down to dismiss). Dismissing fires `onPaymentTerminate`.
+- **Android**: Checkout opens fullscreen. The hardware back button dismisses it and fires `onPaymentTerminate`.
 
-### Common Issues
+## Device Security Compliance
 
-#### 1. Checkout not appearing
-**Solution**: 
-- Ensure `start()` is called via ref and check its return value
-- If `start()` returns `false`, check the current status using `getStatus()`
-- The checkout status must be `"ready"`, `"payment_cancelled"`, or `"payment_failed"` for `start()` to succeed
-- The checkout status must NOT be `"payment_successful"` (successful payments cannot be restarted)
-- **Device Security Compliance**: If peer dependency `jail-monkey` is installed and the device does not meet compliance requirements (the device is rooted/jailbroken), `start()` will return `false`. Check `onSdkError` callback for `device_forbidden` errors.
-  - However, if `jail-monkey` has not been installed, security compliance checks will be skipped.
-- Check that `orderId` is provided and valid (must start with `order_`)
-- Ensure `publicKey` is valid (must start with `live_`)
-- Implement `onSdkError` callback to receive validation and device compliance error details
+The SDK optionally integrates with `jail-monkey` to detect rooted (Android) or jailbroken (iOS) devices.
 
-#### 2. Expo Go "Invariant Violation" error
-**Solution**:
-- Expo Go doesn't support native modules
-- Use custom dev client: `npx expo prebuild`
-- Or use EAS Build for testing
+- If `jail-monkey` is installed and the device is compromised: `start()` returns `false` and `onSdkError` fires with `type: "device_forbidden"`.
+- If `jail-monkey` is installed and the device is clean: checkout proceeds normally.
+- If `jail-monkey` is not installed: SDK logs a warning and proceeds without checking. This is not recommended for production deployments handling regulated transactions.
 
+## Mock Mode
 
-### Debugging Mode 🛠️
+The SDK infers mock mode from the `publicKey` prefix:
 
-Enable detailed logging:
+| Prefix   | Mode  | Environment          |
+| -------- | ----- | -------------------- |
+| `live_`  | Live  | Production           |
+| `test_`  | Mock  | Test/sandbox         |
+| `mock_`  | Mock  | Test/sandbox         |
 
-```tsx
-<GlomoLrsCheckout
-  devMode={true}
-  // ... other props
-/>
-```
-Remember to disable this in production.
+Mock mode keys route to the sandbox backend. No real transactions are created.
 
-### Mock Mode Testing 🧪
+## Connection Handling
 
-Mock mode is automatically enabled based on your `publicKey`:
+The SDK detects connection errors from the WebView and fires `onConnectionError`:
 
-- If your `publicKey` starts with `test_` (case-insensitive), mock mode is automatically enabled and the checkout URL will include `mode=mock`
-- Otherwise, live mode is used and the checkout URL will include `mode=live`
+- **iOS**: NSURLErrorDomain codes (-1001 timeout, -1003 host not found, -1004 connection refused, -1009 offline)
+- **Android**: ERR_EMPTY_RESPONSE, ERR_CONNECTION_REFUSED, ERR_NAME_NOT_RESOLVED, ERR_INTERNET_DISCONNECTED, ERR_CONNECTION_TIMED_OUT, ERR_NETWORK_CHANGED
 
-**Example:**
-```tsx
-// Mock mode (publicKey starts with "test_")
-<GlomoLrsCheckout
-  publicKey="test_abc123..."
-  // ... other props
-/>
+The checkout modal is automatically dismissed on connection errors.
 
-// Live mode (publicKey does not start with "test_")
-<GlomoLrsCheckout
-  publicKey="live_xyz789..."
-  // ... other props
-/>
-```
+## Input Validation
 
-Note that `devMode` is separate and only controls console logging, not the payment mode.
+The SDK validates inputs before starting the checkout:
 
-### Connection Handling 🚨
+| Field            | Rule                                            |
+| ---------------- | ----------------------------------------------- |
+| `publicKey`      | Must start with `live_`, `mock_`, or `test_`. Min 6 characters. |
+| `orderId`        | Must start with `order_`. Min 7 characters. Required when `subscriptionId` is absent. |
+| `subscriptionId` | Must start with `sub_`. Trimmed and checked for emptiness. Required when `orderId` is absent. |
 
-The SDK provides an (optional) `onConnectionError` callback for connection error events. The checkout modal/page will be dismissed/closed, before this callback is triggered.
+Validation failures fire `onSdkError` with `type: "validation_error"` and the relevant `field` name. `start()` returns `false`.
 
-**Scenarios:**
-- Connection failures
-- Internet unavailability
-- DNS resolution failures
+Providing both `orderId` and `subscriptionId` (or neither) also fires `onSdkError`.
 
-**Note:** HTTP `4xx`/`5xx` errors will not be captured as connection errors.
+## Migration from v2
 
-**Example:**
-```tsx
-<GlomoLrsCheckout
-  onConnectionError={(error) => {
-    // Handle connection/network errors
-    // The modal will be automatically closed before this callback is triggered
-    Alert.alert('Connection Error', 'Unable to connect to the GlomoPay servers. Please check your internet connection.');
-  }}
-  // ... other props
-/>
-```
+v3 replaces the LRS-only `GlomoLrsCheckout` with a unified `GlomoCheckout`.
 
-**Note:** `onConnectionError` is for network/connection errors only. Payment-specific failures should be handled by `onPaymentFailure`.
+### Renamed Exports
 
-### Device Security Compliance 🛡️
+| v2                         | v3                        |
+| -------------------------- | ------------------------- |
+| `GlomoLrsCheckout`         | `GlomoCheckout`           |
+| `GlomoLrsCheckoutRef`      | `GlomoCheckoutRef`        |
+| `GlomoLrsCheckoutProps`    | `GlomoCheckoutProps`      |
+| `GlomoLrsCheckoutPayload`  | `GlomoCheckoutPayload`    |
+| `GlomoLrsServer`           | `GlomoServer`             |
 
-**⚠️ Important:** The SDK provides automatic device security compliance checking via the `jail-monkey` library. For enhanced security compliance and to meet regulatory requirements, we **strongly recommend** installing the optional peer dependency `jail-monkey`.
+### Breaking Changes
 
-#### Installation
+- **`start()` is now async**: Returns `Promise<boolean>` instead of `boolean`. Update call sites to `await ref.current?.start()`.
+- **New statuses**: `bank_transfer_submitted` and `pay_via_bank_completed` are new additions to `CheckoutStatus`.
+- **New callbacks**: `onBankTransferSubmitted`, `onPayViaBankCompleted`, and `onUserRefusedCameraPermissions` are available.
 
-```bash
-npm install jail-monkey
-```
+See MIGRATION.md included in this package for a standalone migration guide with before/after code examples.
 
-#### How It Works
+## Troubleshooting
 
-- **With `jail-monkey` installed:** The SDK automatically performs device security compliance checks before allowing an LRS checkout to start. Rooted (Android) or jailbroken (iOS) devices are prevented from starting checkouts.
-- **Without `jail-monkey`:** The SDK skips automatic compliance checks, and allows checkout to proceed normally. Regulatory compliance would have to be enforced manually.
+### `start()` returns `false`
 
-#### Features
+Check `onSdkError` for details. Common causes:
+- Invalid `publicKey` format (must start with `live_`, `mock_`, or `test_`)
+- Invalid `orderId` format (must start with `order_`)
+- Invalid `subscriptionId` format (must start with `sub_`, non-empty after trimming)
+- Both `orderId` and `subscriptionId` provided (or neither)
+- Device is rooted/jailbroken (when `jail-monkey` is installed)
 
-An automatic device security compliance check:
-- Runs synchronously as the **first validation step** in the `start()` method
-- Blocks checkout on non-compliant devices to meet regulatory requirements
-- Works on both iOS and Android platforms
-- Triggers the `onSdkError` callback with a `device_forbidden` error if a non-compliant device is detected
+### Checkout opens but shows a blank screen
 
-**Example:**
-```tsx
-<GlomoLrsCheckout
-  onSdkError={(errors) => {
-    errors.forEach((error) => {
-      if (error.type === 'device_forbidden') {
-        Alert.alert(
-          'Device Unsafe',
-          'LRS checkout is not permitted on rooted or jailbroken devices per regulatory compliance requirements.'
-        );
-      }
-    });
-  }}
-  // ... other props
-/>
-```
+- Verify network connectivity
+- Check that the `publicKey` and `orderId` are valid
 
+### Camera permission denied
 
-### Input Validation 🔍
+- Ensure `AndroidManifest.xml` and `Info.plist` include camera permission declarations
+- The `onUserRefusedCameraPermissions` callback will fire when the user denies
 
-The SDK automatically validates all inputs:
+### `onPayViaBankCompleted` not firing
 
-- **`publicKey`**: Must start with `live_` and have a minimum length of 6 characters
-- **`orderId`**: Must start with `order_` and have a minimum length of 7 characters
+- Ensure you are passing `onPayViaBankCompleted` as a prop to `GlomoCheckout`
 
-Validation errors are reported through the `onSdkError` callback. The SDK validates inputs when `start()` is called:
-- Device security compliance check (first, before any other validation)
-- Input validation (publicKey, orderId, and server environment)
-- Checkout URL validation (before building the final URL)
+## Exports
 
-**Example:**
-```tsx
-<GlomoLrsCheckout
-  onSdkError={(errors) => {
-    if (errors.length > 0) {
-      // Handle validation errors
-      Alert.alert(
-        'Configuration Error',
-        errors.map(e => e.message).join('\n')
-      );
-    }
-  }}
-  // ... other props
-/>
+```ts
+// Components
+export { GlomoCheckout } from "@glomopay/react-native-sdk";
+
+// Hooks (deprecated - use GlomoCheckout component with ref instead)
+export { useGlomoCheckout } from "@glomopay/react-native-sdk";
+
+// Types
+export type {
+  GlomoCheckoutRef,
+  GlomoCheckoutProps,
+  GlomoCheckoutPayload,
+  CheckoutStatus,
+  GlomoBankTransferPayload,
+  GlomoPayViaBankConnectionPayload,
+  UseGlomoCheckoutReturn,  // deprecated
+  SdkError,
+} from "@glomopay/react-native-sdk";
 ```
 
-## 💬 Support
+## Security
+
+The SDK loads checkout pages in an isolated WebView. No PAN, CVV, or sensitive payment data passes through the React Native bridge - all sensitive input is handled within the WebView's sandboxed context.
+
+Device integrity checking is available via optional `jail-monkey` integration (see [Device Security Compliance](#device-security-compliance)).
+
+To report a security vulnerability, email security@glomopay.com. Do not open a public GitHub issue for security reports.
+
+## Contributing
+
+This SDK is maintained by GlomoPay. We do not accept external contributions at this time.
 
-### Documentation
-- 📖 API Documentation: https://docs.glomopay.com
-- 🎛️ Dashboard: https://dashboard.glomopay.com
+## Support
 
-### Contact Us
-- ✉️ Email: developer@glomopay.com
-- 🎟️ GitHub Issues: https://github.com/glomopay/glomopay-rn-sdk/issues
-- 🌐 Website: https://glomopay.com
+- GitHub Issues: https://github.com/glomopay/glomopay-rn-sdk/issues
+- Email: developer@glomopay.com
 
-## License 📄
+## License
 
-This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.
+Apache-2.0. See [LICENSE](LICENSE) for details.