# Migration Guide

- [v1 to v4](#v1-to-v4) - for merchants currently using v1
- [v3 to v4](#v3-to-v4) - for merchants currently using v3
- [v1 to v3](#v1-to-v3) - historical reference


## v1 to v4

v4 replaces the LRS-only `GlomoLrsCheckout` with a unified `GlomoCheckout` that auto-detects order type (LRS, Standard, or Subscriptions) and provides a single `onUserJourneyCompleted` callback for all asynchronous payment flows.

> For the complete v4 API reference, see the [React Native SDK v4 documentation](/product-guide/sdk/react-native-sdk/v4).
For the full list of changes, see the [Changelog](/product-guide/sdk/react-native-sdk/changelog).


### Renamed Exports

| v1 | v4 |
|  --- | --- |
| `GlomoLrsCheckout` | `GlomoCheckout` |
| `GlomoLrsCheckoutRef` | `GlomoCheckoutRef` |
| `GlomoLrsCheckoutProps` | `GlomoCheckoutProps` |
| `GlomoLrsCheckoutPayload` | `GlomoCheckoutPayload` |
| `GlomoLrsServer` | `GlomoServer` |
| `LrsCheckoutStatus` | `CheckoutStatus` |
| `useLrsCheckout` | `useGlomoCheckout` (deprecated - use component ref instead) |


### Breaking Changes

- **`start()` is now async** - returns `Promise<boolean>` instead of `boolean`. Update call sites to `await ref.current?.start()`.
- **Asynchronous payment callbacks** - v4 uses a single `onUserJourneyCompleted` callback with an `ASYNC_PAYMENT_EVENTS` enum instead of separate per-flow callbacks. (These callbacks did not exist in v1, so no migration needed - just be aware of the v4 API when adding them.)
- **New statuses** - `detecting_order_type`, `bank_transfer_submitted`, and `pay_via_bank_completed` are additions to `CheckoutStatus`.
- **`onSdkError` is now required** - was optional in v1. Must be provided in v4 to surface validation errors, device compliance failures, and configuration issues.


### Before / After

**v1:**

```tsx
import { GlomoLrsCheckout, type GlomoLrsCheckoutRef } from "@glomopay/react-native-sdk";

const ref = useRef<GlomoLrsCheckoutRef>(null);
const started = ref.current?.start(); // boolean
```

**v4:**

```tsx
import {
  GlomoCheckout,
  ASYNC_PAYMENT_EVENTS,
  type GlomoCheckoutRef,
} from "@glomopay/react-native-sdk";

const ref = useRef<GlomoCheckoutRef>(null);
const started = await ref.current?.start(); // Promise<boolean>

// In your component JSX:
<GlomoCheckout
  ref={ref}
  publicKey="live_pk_abc123"
  orderId="order_xyz789"
  onPaymentSuccess={(payload) => console.log("Success:", payload.paymentId)}
  onPaymentFailure={(payload) => console.log("Failed:", payload.paymentId)}
  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;
    }
  }}
/>
```

### Platform Configuration

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.

### New in v4 (no v1 equivalent)

- **Subscriptions checkout** - pass `subscriptionId` instead of `orderId`. See [Subscriptions Checkout](/product-guide/sdk/react-native-sdk/v4#subscriptions-checkout).
- **Asynchronous payment flows** - `onUserJourneyCompleted` callback with `ASYNC_PAYMENT_EVENTS` enum. See [Asynchronous Payment Flows](/product-guide/sdk/react-native-sdk/v4#asynchronous-payment-flows).
- **Camera permissions handling** - `onUserRefusedCameraPermissions` callback. See [Camera Permissions](/product-guide/sdk/react-native-sdk/v4#camera-permissions).
- **Order type auto-detection** - the SDK determines the checkout flow automatically. The `detecting_order_type` status is emitted during detection.
- **Mock mode extended** - `mock_` prefix keys now supported in addition to `test_`.


## v3 to v4

v4 consolidates the asynchronous payment flow callbacks into a single generic callback.

> For the full list of changes, see the [Changelog](/product-guide/sdk/react-native-sdk/changelog).
For the complete v4 API reference, see the [React Native SDK v4 documentation](/product-guide/sdk/react-native-sdk/v4).


### 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
/>
```

## v1 to v3

v3 replaces the LRS-only `GlomoLrsCheckout` with a unified `GlomoCheckout` that auto-detects order type (LRS, Standard, or Subscriptions).

> For the complete v3 API reference, see the [React Native SDK v3 documentation](/product-guide/sdk/react-native-sdk/v3).
For the full list of changes, see the [Changelog](/product-guide/sdk/react-native-sdk/changelog).


### Renamed Exports

| v1 | v3 |
|  --- | --- |
| `GlomoLrsCheckout` | `GlomoCheckout` |
| `GlomoLrsCheckoutRef` | `GlomoCheckoutRef` |
| `GlomoLrsCheckoutProps` | `GlomoCheckoutProps` |
| `GlomoLrsCheckoutPayload` | `GlomoCheckoutPayload` |
| `GlomoLrsServer` | `GlomoServer` |
| `LrsCheckoutStatus` | `CheckoutStatus` |
| `useLrsCheckout` | `useGlomoCheckout` |


### 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`, `onPayViaBankBankConnectionSuccessful`, and `onUserRefusedCameraPermissions` are available.


### Before / After

**v1:**

```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 the [Changelog](/product-guide/sdk/react-native-sdk/changelog).

### New in v3

The following features are new in v3 and have no v1 equivalent. No migration is needed for these - they are additive.

- **Subscriptions checkout** - pass `subscriptionId` instead of `orderId` to process subscription payments. See [Subscriptions Checkout](/product-guide/sdk/react-native-sdk/v3#subscriptions-checkout).
- **Bank transfer support** - `onBankTransferSubmitted` callback for bank transfer flows. See [Bank Transfer Support](/product-guide/sdk/react-native-sdk/v3#bank-transfer-support).
- **Pay via bank support** - `onPayViaBankCompleted` and `onPayViaBankBankConnectionSuccessful` callbacks. See [Pay via Bank Support](/product-guide/sdk/react-native-sdk/v3#pay-via-bank-support).
- **Camera permissions handling** - `onUserRefusedCameraPermissions` callback. See [Camera Permissions](/product-guide/sdk/react-native-sdk/v3#camera-permissions).
- **Order type auto-detection** - the SDK determines the checkout flow automatically. The `detecting_order_type` status is emitted during detection.
- **Mock mode extended** - `mock_` prefix keys now supported in addition to `test_`.


## Related

- [React Native SDK v4 documentation](/product-guide/sdk/react-native-sdk/v4) - complete v4 API reference
- [React Native SDK v3 documentation (Archived)](/product-guide/sdk/react-native-sdk/v3) - v3 API reference
- [Changelog](/product-guide/sdk/react-native-sdk/changelog) - all release notes
- [React Native SDK v1 (Archived)](/product-guide/sdk/react-native-sdk/v1) - legacy version documentation