Migration Guide

• v1 to v4 - for merchants currently using v1
• v3 to v4 - for merchants currently using v3
• v1 to v3 - historical reference

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. For the full list of changes, see the Changelog.

• 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.

v1:

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

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

v4:

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;
    }
  }}
/>

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.

• Subscriptions checkout - pass subscriptionId instead of orderId. See Subscriptions Checkout.
• Asynchronous payment flows - onUserJourneyCompleted callback with ASYNC_PAYMENT_EVENTS enum. See Asynchronous Payment Flows.
• Camera permissions handling - onUserRefusedCameraPermissions callback. See 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_.

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

For the full list of changes, see the Changelog. For the complete v4 API reference, see the React Native SDK v4 documentation.

onSdkError was optional in v3. In v4 it is required. If you were not passing it, add it:

onSdkError={(errors) => {
  errors.forEach((e) => console.error(e.type, e.message, e.field));
}}

• CheckoutStatus values bank_transfer_submitted and pay_via_bank_completed remain unchanged. getStatus() continues to return granular status values.

v3:

<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:

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

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. For the full list of changes, see the Changelog.

• 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.

v1:

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

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

v3:

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

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

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.

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.
• Bank transfer support - onBankTransferSubmitted callback for bank transfer flows. See Bank Transfer Support.
• Pay via bank support - onPayViaBankCompleted and onPayViaBankBankConnectionSuccessful callbacks. See Pay via Bank Support.
• Camera permissions handling - onUserRefusedCameraPermissions callback. See 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_.

• React Native SDK v4 documentation - complete v4 API reference
• React Native SDK v3 documentation (Archived) - v3 API reference
• Changelog - all release notes
• React Native SDK v1 (Archived) - legacy version documentation