@glomopay/react-native-sdk 3.0.1 → 4.0.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] - 2026-06-11
+
+### Breaking Changes
+
+- **Consolidated async payment callbacks**: `onBankTransferSubmitted` and `onPayViaBankCompleted` have been replaced by a single `onUserJourneyCompleted` callback. The new callback receives a `GlomoUserJourneyCompletedPayload` with a `journeyType` field from the `ASYNC_PAYMENT_EVENTS` enum.
+- **Removed `onPayViaBankBankConnectionSuccessful`**: This informational callback has been removed. It may be reintroduced in a future version if merchant demand warrants it.
+- **Removed types**: `GlomoBankTransferPayload` and `GlomoPayViaBankConnectionPayload` are no longer exported.
+- **`onSdkError` is now required**: Previously optional, `onSdkError` must now be provided. This ensures validation errors, device compliance failures, and configuration issues are handled properly.
+
+### Added
+
+- **`ASYNC_PAYMENT_EVENTS` enum**: Enumeration of asynchronous payment event types (`BANK_TRANSFER_SUBMITTED`, `PAY_VIA_BANK_COMPLETED`).
+- **`GlomoUserJourneyCompletedPayload` type**: Flat payload interface with `journeyType`, `orderId?`, `status?`, `senderAccountNumber?`, `transactionReference?`.
+- **`onUserJourneyCompleted` callback**: Single callback for all asynchronous payment flow completions.
+
+### Unchanged
+
+- `CheckoutStatus` values `bank_transfer_submitted` and `pay_via_bank_completed` remain for granular `getStatus()` state checks.
+
+## [3.1.0] - 2026-06-08
+
+### Added
+
+- **Subscriptions checkout support** - new `subscriptionId` prop on `GlomoCheckout`. When provided, the SDK bypasses order type detection and renders the subscriptions checkout flow directly. No API call is made - the inner checkout component mounts immediately. The `detecting_order_type` status is not emitted for subscription flows.
+- **Mutual exclusion validation** - `GlomoCheckout` validates that exactly one of `orderId` or `subscriptionId` is provided. If both or neither are set, `onSdkError` fires with a clear message and `start()` returns `false`.
+
+### Changed
+
+- **`orderId` is now optional** on `GlomoCheckoutProps` - required only when `subscriptionId` is absent.
+
+### Deprecated
+
+- **`useGlomoCheckout` hook** - use the `GlomoCheckout` component with a ref instead. The hook does not provide reactive state - `getStatus()` returns a point-in-time snapshot. Will be removed in a future major version.
+
 ## [3.0.1] - 2026-06-02
 
 ### Added
@@ -59,6 +93,8 @@ Checkout flows with camera-based bank authentication require native permissions:
 
 These are only required for flows that use camera-based bank authentication.
 
-## [2.0.2]
+## [2.0.2] - 2025-11-26
+
+Private v2 release candidate with experimental features. Not available for general use.
 
-Last v2 release.
+Backwards compatible with `v1.x`

package/MIGRATION.md

@@ -0,0 +1,129 @@
+# Migration Guide
+
+## v3 to v4
+
+v4 consolidates the asynchronous payment flow callbacks into a single generic callback.
+
+### Removed Callbacks
+
+| v3 | v4 |
+|---|---|
+| `onBankTransferSubmitted` | Use `onUserJourneyCompleted` with `journeyType: ASYNC_PAYMENT_EVENTS.BANK_TRANSFER_SUBMITTED` |
+| `onPayViaBankCompleted` | Use `onUserJourneyCompleted` with `journeyType: ASYNC_PAYMENT_EVENTS.PAY_VIA_BANK_COMPLETED` |
+| `onPayViaBankBankConnectionSuccessful` | Removed (no replacement) |
+
+### Removed Types
+
+| v3 | v4 |
+|---|---|
+| `GlomoBankTransferPayload` | Use `GlomoUserJourneyCompletedPayload` |
+| `GlomoPayViaBankConnectionPayload` | Removed |
+
+### New Types
+
+| Type | Purpose |
+|---|---|
+| `ASYNC_PAYMENT_EVENTS` | Enum of asynchronous payment event types |
+| `GlomoUserJourneyCompletedPayload` | Payload for `onUserJourneyCompleted` callback |
+
+### `onSdkError` is now required
+
+`onSdkError` was optional in v3. In v4 it is required. If you were not passing it, add it:
+
+```tsx
+onSdkError={(errors) => {
+  errors.forEach((e) => console.error(e.type, e.message, e.field));
+}}
+```
+
+### Unchanged
+
+- `CheckoutStatus` values `bank_transfer_submitted` and `pay_via_bank_completed` remain unchanged. `getStatus()` continues to return granular status values.
+
+### Before / After
+
+**v3:**
+```tsx
+<GlomoCheckout
+  onBankTransferSubmitted={(payload) => {
+    console.log("Transfer ref:", payload?.transactionReference);
+  }}
+  onPayViaBankCompleted={(payload) => {
+    console.log("Pay via bank:", payload.status);
+  }}
+  onPayViaBankBankConnectionSuccessful={(payload) => {
+    console.log("Bank connected:", payload?.bankName);
+  }}
+  // ...other props
+/>
+```
+
+**v4:**
+```tsx
+import { ASYNC_PAYMENT_EVENTS } from "@glomopay/react-native-sdk";
+
+<GlomoCheckout
+  onUserJourneyCompleted={(payload) => {
+    switch (payload.journeyType) {
+      case ASYNC_PAYMENT_EVENTS.BANK_TRANSFER_SUBMITTED:
+        console.log("Transfer ref:", payload.transactionReference);
+        break;
+      case ASYNC_PAYMENT_EVENTS.PAY_VIA_BANK_COMPLETED:
+        console.log("Pay via bank:", payload.status);
+        break;
+    }
+  }}
+  // ...other props
+/>
+```
+
+---
+
+## v2 to v3
+
+v3 replaces the LRS-only `GlomoLrsCheckout` with a unified `GlomoCheckout` that auto-detects order type.
+
+### Renamed Exports
+
+| v2                         | v3                        |
+| -------------------------- | ------------------------- |
+| `GlomoLrsCheckout`         | `GlomoCheckout`           |
+| `GlomoLrsCheckoutRef`      | `GlomoCheckoutRef`        |
+| `GlomoLrsCheckoutProps`    | `GlomoCheckoutProps`      |
+| `GlomoLrsCheckoutPayload`  | `GlomoCheckoutPayload`    |
+| `GlomoLrsServer`           | `GlomoServer`             |
+
+### Breaking Changes
+
+- **`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.
+
+### Before / After
+
+**v2:**
+```tsx
+import { GlomoLrsCheckout, type GlomoLrsCheckoutRef } from "@glomopay/react-native-sdk";
+
+const ref = useRef<GlomoLrsCheckoutRef>(null);
+const started = ref.current?.start(); // boolean
+```
+
+**v3:**
+```tsx
+import { GlomoCheckout, type GlomoCheckoutRef } from "@glomopay/react-native-sdk";
+
+const ref = useRef<GlomoCheckoutRef>(null);
+const started = await ref.current?.start(); // Promise<boolean>
+```
+
+### Platform Configuration (New in v3)
+
+Checkout flows with camera-based bank authentication require native permissions:
+
+- **Android** (`AndroidManifest.xml`): `<uses-permission android:name="android.permission.CAMERA" />`
+- **iOS** (`Info.plist`): `NSCameraUsageDescription` key
+
+These are only required for flows that use camera-based bank authentication.
+
+For the full changelog, see CHANGELOG.md included in this package.

package/README.md

@@ -1,28 +1,16 @@
-# 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 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
-
-## 📋 Prerequisites
+## Prerequisites
 
 - API credentials (Public Key) from your GlomoPay dashboard
 - An order ID created via the GlomoPay API
 
-## 🛠️ System Requirements
+## System Requirements
 
 | Requirement            | Version      |
 | ---------------------- | ------------ |
@@ -33,15 +21,7 @@ Official React Native SDK for integrating GlomoPay payment checkout flows into y
 | react-native-webview   | ^13.0.0      |
 | jail-monkey (optional) | ^2.6.0       |
 
-## ⚠️ Breaking Changes (v3)
-
-- `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`)
-
-For the full list of changes and migration details, see [CHANGELOG.md](./CHANGELOG.md) and [Migration from v2](#-migration-from-v2).
-
-## 📦 Installation
+## Installation
 
 ### React Native CLI
 
@@ -66,13 +46,14 @@ npm install jail-monkey
 
 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.
 
-## 🚀 Quick Start
+## Quick Start
 
 ```tsx
 import React, { useRef } from "react";
 import { View, Button } from "react-native";
 import {
   GlomoCheckout,
+  ASYNC_PAYMENT_EVENTS,
   type GlomoCheckoutRef,
   type GlomoCheckoutPayload,
   type SdkError,
@@ -108,14 +89,15 @@ export default function PaymentScreen() {
         onConnectionError={(error) => {
           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);
+        onUserJourneyCompleted={(payload) => {
+          switch (payload.journeyType) {
+            case ASYNC_PAYMENT_EVENTS.BANK_TRANSFER_SUBMITTED:
+              console.log("Bank transfer submitted:", payload.transactionReference);
+              break;
+            case ASYNC_PAYMENT_EVENTS.PAY_VIA_BANK_COMPLETED:
+              console.log("Pay via bank completed:", payload.status);
+              break;
+          }
         }}
         onUserRefusedCameraPermissions={() => {
           console.log("User refused camera - cannot proceed with bank authentication");
@@ -129,7 +111,90 @@ export default function PaymentScreen() {
 }
 ```
 
-## 📚 API Reference
+## Breaking Changes (v4)
+
+- `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`)
+- `onBankTransferSubmitted` and `onPayViaBankCompleted` replaced by a single `onUserJourneyCompleted` callback
+- `onPayViaBankBankConnectionSuccessful` removed entirely
+- `GlomoBankTransferPayload` and `GlomoPayViaBankConnectionPayload` types removed
+- `onSdkError` is now **required** - previously optional, now must be provided to ensure validation and device compliance errors are always surfaced
+- New exports: `ASYNC_PAYMENT_EVENTS` enum and `GlomoUserJourneyCompletedPayload` type
+- `CheckoutStatus` values `bank_transfer_submitted` and `pay_via_bank_completed` are unchanged
+
+For migration details, see MIGRATION.md included in this package.
+
+## Subscriptions Checkout
+
+To process subscription payments, pass a `subscriptionId` instead of an `orderId`:
+
+```tsx
+<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));
+  }}
+/>
+```
+
+When `subscriptionId` is provided:
+- The SDK skips order type detection (no API call)
+- The `subscriptionId` must start with `sub_`
+- 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
+- **Asynchronous payment flows** - single `onUserJourneyCompleted` callback for bank transfer and pay via bank events
+- **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
+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
 
 ### GlomoCheckout Component
 
@@ -144,17 +209,18 @@ The unified checkout component. Place it in your render tree and control it via
 | Prop                             | Type                                            | Required | Description                                                         |
 | -------------------------------- | ----------------------------------------------- | -------- | ------------------------------------------------------------------- |
 | `publicKey`                      | `string`                                        | Yes      | Your GlomoPay public key (must start with `live_`, `mock_`, or `test_`) |
-| `orderId`                        | `string`                                        | Yes      | Order ID from the GlomoPay API (must start with `order_`)          |
+| `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 |
+| `onSdkError`                     | `(errors: SdkError[]) => void`                  | Yes      | Called on validation errors or device compliance failures           |
+| `onUserJourneyCompleted`         | `(payload: GlomoUserJourneyCompletedPayload) => void` | No | Called when an asynchronous payment flow completes (bank transfer submission, pay via bank completion). Check `payload.journeyType` to determine the 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                                                                                               |
@@ -167,6 +233,7 @@ The unified checkout component. Place it in your render tree and control it via
 | 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                      |
@@ -186,25 +253,24 @@ interface GlomoCheckoutPayload {
 }
 ```
 
-#### GlomoBankTransferPayload
+#### ASYNC_PAYMENT_EVENTS
 
 ```ts
-interface GlomoBankTransferPayload {
-  orderId: string;
-  senderAccountNumber: string;
-  transactionReference: string;
+enum ASYNC_PAYMENT_EVENTS {
+  BANK_TRANSFER_SUBMITTED = "bank_transfer_submitted",
+  PAY_VIA_BANK_COMPLETED = "pay_via_bank_completed",
 }
 ```
 
-#### GlomoPayViaBankConnectionPayload
+#### GlomoUserJourneyCompletedPayload
 
 ```ts
-interface GlomoPayViaBankConnectionPayload {
-  bankIdentifier: string;
-  cooldownPeriodInMinutes: number;
-  bankName: string;
-  bankImageSrc: string;
-  bankImageAlt: string;
+interface GlomoUserJourneyCompletedPayload {
+  journeyType: ASYNC_PAYMENT_EVENTS;
+  orderId?: string;
+  status?: string;
+  senderAccountNumber?: string;
+  transactionReference?: string;
 }
 ```
 
@@ -214,47 +280,40 @@ interface GlomoPayViaBankConnectionPayload {
 interface SdkError {
   type: "validation_error" | "device_forbidden";
   message: string;
-  field?: string;
+  field?: "publicKey" | "orderId" | "subscriptionId" | "baseCheckoutUrl" | "generatedCheckoutUrl";
 }
 ```
 
-## 💰 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`:
-
-```tsx
-onBankTransferSubmitted={(payload) => {
-  // payload may be null/undefined if the checkout page omits it
-  console.log("Transfer ref:", payload?.transactionReference);
-}}
-```
-
-The checkout status transitions to `bank_transfer_submitted`.
+## Asynchronous Payment Flows
 
-## 🏦 Pay via Bank Support
-
-The SDK fires `onPayViaBankCompleted` when the pay-via-bank journey completes:
+The SDK fires `onUserJourneyCompleted` when an asynchronous payment flow completes. Use `payload.journeyType` to determine which flow triggered the callback:
 
 ```tsx
-onPayViaBankCompleted={(payload) => {
-  // payload.status - e.g. "success", "failed", "unknown"
-  console.log("Pay via bank status:", payload.status);
+onUserJourneyCompleted={(payload) => {
+  switch (payload.journeyType) {
+    case ASYNC_PAYMENT_EVENTS.BANK_TRANSFER_SUBMITTED:
+      /**
+       * User submitted bank transfer details.
+       * Relevant fields: orderId, senderAccountNumber, transactionReference
+       * Note: fields may be absent if the checkout page omits them.
+       */
+      console.log("Transfer ref:", payload.transactionReference);
+      break;
+    case ASYNC_PAYMENT_EVENTS.PAY_VIA_BANK_COMPLETED:
+      /**
+       * Pay via bank journey completed.
+       * Relevant fields: orderId, status
+       * The SDK deduplicates this event - fires only once per session.
+       */
+      console.log("Pay via bank status:", payload.status);
+      break;
+  }
 }}
 ```
 
-The checkout status transitions to `pay_via_bank_completed`. The SDK deduplicates this event internally - the callback fires only once per checkout session.
-
-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");
-}}
-```
+The checkout status transitions to `bank_transfer_submitted` or `pay_via_bank_completed` respectively. Use `getStatus()` for granular programmatic checks.
 
-## 📷 Camera Permissions for bank authentication
+## Camera Permissions
 
 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.
 
@@ -280,12 +339,12 @@ Add to `ios/<YourApp>/Info.plist`:
 - **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.
 
-## 📱 Platform Behavior
+## Platform Behavior
 
 - **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`.
 
-## 🔒 Device Security Compliance
+## Device Security Compliance
 
 The SDK optionally integrates with `jail-monkey` to detect rooted (Android) or jailbroken (iOS) devices.
 
@@ -293,7 +352,7 @@ The SDK optionally integrates with `jail-monkey` to detect rooted (Android) or j
 - 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
+## Mock Mode
 
 The SDK infers mock mode from the `publicKey` prefix:
 
@@ -305,7 +364,7 @@ The SDK infers mock mode from the `publicKey` prefix:
 
 Mock mode keys route to the sandbox backend. No real transactions are created.
 
-## 🌐 Connection Handling
+## Connection Handling
 
 The SDK detects connection errors from the WebView and fires `onConnectionError`:
 
@@ -314,46 +373,33 @@ The SDK detects connection errors from the WebView and fires `onConnectionError`
 
 The checkout modal is automatically dismissed on connection errors.
 
-## 🛡️ Input Validation
+## Input Validation
 
 The SDK validates inputs before starting the checkout:
 
-| Field       | Rule                                            |
-| ----------- | ----------------------------------------------- |
-| `publicKey` | Must start with `live_`, `mock_`, or `test_`. Min 6 characters. |
-| `orderId`   | Must start with `order_`. Min 7 characters.     |
+| 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. |
 
 Validation failures fire `onSdkError` with `type: "validation_error"` and the relevant `field` name. `start()` returns `false`.
 
-## 🔄 Migration from v2
-
-v3 replaces the LRS-only `GlomoLrsCheckout` with a unified `GlomoCheckout`.
-
-### Renamed Exports
+Providing both `orderId` and `subscriptionId` (or neither) also fires `onSdkError`.
 
-| v2                         | v3                        |
-| -------------------------- | ------------------------- |
-| `GlomoLrsCheckout`         | `GlomoCheckout`           |
-| `GlomoLrsCheckoutRef`      | `GlomoCheckoutRef`        |
-| `GlomoLrsCheckoutProps`    | `GlomoCheckoutProps`      |
-| `GlomoLrsCheckoutPayload`  | `GlomoCheckoutPayload`    |
-| `GlomoLrsServer`           | `GlomoServer`             |
+## Migration from v1/v3
 
-### Breaking Changes
+See MIGRATION.md included in this package for migration guides with before/after code examples.
 
-- **`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.
-
-For the full list of changes, see [CHANGELOG.md](./CHANGELOG.md).
-
-## 🚨 Troubleshooting
+## Troubleshooting
 
 ### `start()` returns `false`
 
 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)
 
 ### Checkout opens but shows a blank screen
@@ -364,38 +410,42 @@ Check `onSdkError` for details. Common causes:
 ### Camera permission denied
 
 - Ensure `AndroidManifest.xml` and `Info.plist` include camera permission declarations
-- The `onUserRefusedCameraPermissions` callback will fire when the user denies
-
-### `onPayViaBankCompleted` not firing
-
-- Ensure you are passing `onPayViaBankCompleted` as a prop to `GlomoCheckout`
+- The `onUserRefusedCameraPermissions` callback will fire when the user denies camera permissions to your app
 
-## 🔍 Exports
+## Exports
 
 ```ts
-// Component
+// Components
 export { GlomoCheckout } from "@glomopay/react-native-sdk";
 
+// Hooks (deprecated - use GlomoCheckout component with ref instead)
+export { useGlomoCheckout } from "@glomopay/react-native-sdk";
+
+// Enums
+export { ASYNC_PAYMENT_EVENTS } from "@glomopay/react-native-sdk";
+
 // Types
 export type {
   GlomoCheckoutRef,
   GlomoCheckoutProps,
   GlomoCheckoutPayload,
   CheckoutStatus,
-  GlomoBankTransferPayload,
-  GlomoPayViaBankConnectionPayload,
+  GlomoUserJourneyCompletedPayload,
+  UseGlomoCheckoutReturn,  // deprecated
   SdkError,
 } from "@glomopay/react-native-sdk";
-
-// Hook (advanced usage)
-export { useGlomoCheckout } from "@glomopay/react-native-sdk";
 ```
 
-## 💬 Support
+## Security
+
+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.
+
+## Support
 
-- GitHub Issues: https://github.com/glomopay/glomopay-rn-sdk/issues
 - Email: developer@glomopay.com
 
-## 📄 License
+## License
 
 Apache-2.0. See [LICENSE](LICENSE) for details.

package/lib/glomo-checkout.d.ts

@@ -1,6 +1,7 @@
 /**
- * The unified GlomoPay Checkout Component (v3).
+ * The unified GlomoPay Checkout Component (v4).
  * Detects order type (LRS vs Standard) and delegates rendering to the appropriate inner component.
+ * Enforces error handling via `onSdkError()` as a mandatory prop.
  */
 import React from "react";
 import { type GlomoCheckoutRef, type GlomoCheckoutProps } from "./types/checkout";

package/lib/glomo-checkout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glomo-checkout.d.ts","sourceRoot":"","sources":["../src/glomo-checkout.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAA0C,MAAM,OAAO,CAAC;AAG/D,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AA8DlF,eAAO,MAAM,aAAa,6FAA2E,CAAC"}
+{"version":3,"file":"glomo-checkout.d.ts","sourceRoot":"","sources":["../src/glomo-checkout.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAsE,MAAM,OAAO,CAAC;AAG3F,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAqHlF,eAAO,MAAM,aAAa,6FAA2E,CAAC"}