Inttegro SDK for React Native

The Inttegro SDK for React Native presents Inttegro's native iOS and Android payment sheet from a typed React Native facade. The native SDKs own presentation, accessibility, authentication, payment collection, and lifecycle state.

Start with MCP

Before writing SDK code, connect your MCP client and ask MCP to design the integration for your mobile checkout flow. Use the resulting plan to define the boundary between your server, this SDK, and the Inttegro API.

Current payment methods

The published SDK currently supports mobile money. Card payments, Apple Pay, and Google Pay are not exposed in this version.

Requirements

React Native 0.82 or later with the New Architecture enabled
iOS 16 or later
Android API 26 or later
A merchant-backend endpoint that creates and finalizes an Inttegro order and returns its client-safe Order ID

Install the package, then rebuild the native application so Codegen and autolinking can run. Expo applications require a development build; Expo Go cannot load the native module.

npm install @inttegro/react-native

Payment lifecycle

Subscribe before presentingaddPaymentSheetEventListener()

Merchant backend
Create and finalize the order
Seal the cart, amount, currency, and payment settings before handing checkout to the app.
requires_payment
Return the Order ID
Mobile app
Initialize checkoutinitializePaymentSheet()
Provide the client-safe Order ID and configure the native payment sheet.
Mobile app
Present the payment sheetpresentPaymentSheet()
Open the native sheet. The SDK loads the checkout projection and renders payment collection.
Lifecycle hookevent.type === 'presented'
Customer and Inttegro SDK
Run a payment attempt
Collect the payment method, confirmation, and authorization inside the sheet.
Lifecycle hookevent.type === 'paymentAttemptStarted'
Payment attempt outcome?
Recoverable failureevent.type === 'paymentAttemptFailed'The sheet explains the failure and allows another attempt.↩ Retry step 4
Successful paymentresult.type === 'completed'Return a terminal result to the mobile app.Continue ↓
Confirmation and authorization
event.type === 'paymentActionRequired'Checkout guides confirmation, authorization, or a redirect.
event.type === 'paymentProcessing'The submitted payment remains pending.
↩ Re-evaluate the outcome
Mobile app
Handle the terminal resultPaymentSheetResult
Update the immediate UI for completion, cancellation, or an unrecoverable failure.
Verify authoritative state
Merchant backend
Verify before fulfillment
Confirm the owner-scoped Order state before releasing goods or services.
Order lookup or webhook

Your backend creates the order with its secret Inttegro API key, finalizes it to seal the amount and activate checkout, and returns only the resulting Order ID to the app. That handoff must finish before the app initializes or presents the payment sheet. “Finalized” means ready for payment—not paid or fulfilled.

const { orderId } = await merchantBackend.createCheckoutOrder(cart)

initializePaymentSheet validates and stores the configuration. The checkout network load begins after presentPaymentSheet opens the native sheet.

Start from a Buy link

Return a Buy link's public Purchase Intent ID to the app and initialize the same native sheet with purchaseIntentId instead of orderId:

await initializePaymentSheet({
  purchaseIntentId: buyLink.purchaseIntentId,
  returnURL: 'merchant-app://inttegro-return',
})

The sheet gathers the Buy-link choices and payment details without creating an Order. When the payer presses Pay, Inttegro creates the finalized Order and starts the payment attempt together. Customer-selected pricing uses the currency, minimum, optional maximum, and suggested amounts returned by Checkout. Supply exactly one of orderId or purchaseIntentId; suggestions do not limit other valid values inside the range.

Native payment sheet

The Inttegro React Native SDK presents a native payment sheet inside your app. Customers can choose a saved payment method or enter Mobile Money details, review the amount, and see when payment completes.

iOS
Android

5 steps

Light mode. Native Inttegro payment sheet presented over the Kora Market iOS demo, showing Mobile Money account entry for a payer without an attached payment method. — iOSLight
**Start the payment**Enter a Mobile Money account number when there is no attached payment method.

Light mode. Native Inttegro payment sheet on iOS with a complete Mobile Money account number, MTN selected, and the Pay action available. — iOSLight
**Review the account and provider**The suggested network remains selectable for ported numbers. A valid account makes Pay available.

Light mode. Native Inttegro payment sheet on iOS asking for the six-digit code sent by SMS to the customer’s masked Mobile Money number. — iOSLight
**Confirm with a code**Enter the one-time code sent to the masked recipient before continuing to provider approval.

Light mode. Native Inttegro payment sheet on iOS waiting for the customer to approve the payment in their Mobile Money prompt. — iOSLight
**Check your phone**Keep the sheet open while the customer approves the payment from their Mobile Money prompt.

Light mode. Native Inttegro payment sheet confirming a completed GHS 50 Mobile Money payment to Kora Market. — iOSLight
**Finish with confirmation**The terminal state confirms the paid amount and merchant before returning control to the host app.

React Native and Flutter use these same native payment sheets instead of reimplementing checkout. The Android robot is reproduced from work created and shared by Google and used according to the Creative Commons 3.0 Attribution License.

Present the payment sheet

import { addPaymentSheetEventListener } from '@inttegro/react-native/events'
import {
  initializePaymentSheet,
  presentPaymentSheet,
} from '@inttegro/react-native/payment-sheet'

const lifecycleSubscription = addPaymentSheetEventListener((event) => {
  switch (event.type) {
    case 'presented':
      onPaymentFlowStarted()
      break
    case 'paymentAttemptStarted':
      onPaymentAttemptStarted()
      break
    case 'paymentAttemptFailed':
      // Recoverable: the native sheet explains the failure and permits retry.
      onPaymentAttemptFailed({ category: event.failure.code })
      break
    case 'paymentActionRequired':
      onPaymentActionRequired(event.action.type)
      break
    case 'paymentProcessing':
      onPaymentProcessing(event.order)
      break
  }
})

await initializePaymentSheet({
  orderId,
  returnURL: 'merchant-app://inttegro-return',
  telemetry: activeTraceContext,
  features: {
    showLineItems: true,
    showInvoiceDownload: true,
    showReceiptDownload: true,
    allowPaymentMethodChange: false,
  },
})

try {
  const result = await presentPaymentSheet()

  switch (result.type) {
    case 'completed':
      onPaymentCompleted({ order: result.order })
      await merchantBackend.verifyOrderPayment(result.order.id)
      break
    case 'canceled':
      onPaymentCanceled()
      break
    case 'failed':
      onPaymentSheetFailed(result.failure)
      break
  }
} finally {
  lifecycleSubscription.remove()
}

Optional feature states

The features member accepts a PaymentSheetFeatures object. These properties change what the native sheet presents; they cannot change the Order, its shipping address, its amount, or the customer that owns an attached payment method. Start with the defaults, then add only the context or follow-up actions that make the payment easier to understand.

Property	Default	What changes
`allowPaymentMethodChange`	`true`	Set to `false` to keep an attached method selected and remove the replacement action. If the Order has no attached method, the payer can still enter one.
`showInvoiceDownload`	`false`	Offers the invoice after a successful payment when Checkout returns a secure invoice URL.
`showLineItems`	`false`	Offers a collapsed Order summary when Checkout returns line items. Opening it moves the sheet to its full-height detent before revealing the items.
`showReceiptDownload`	`false`	Offers the receipt after a successful payment when Checkout returns a secure receipt URL.

The opening capture combines showLineItems: true with allowPaymentMethodChange: false. The attached method and pay action remain in view while the Order summary stays out of the way until the payer opens it. The completion capture enables both download properties. After payment succeeds, the sheet returns to its compact height and shows only the document actions for URLs Checkout actually supplied; the primary exit action remains immediately available.

iOS
Android

2 steps

Light mode. Native Inttegro payment sheet on iOS offering a collapsed one-item Order summary above a fixed attached MTN Mobile Money account. — iOSLight
**`showLineItems` with a fixed method**`allowPaymentMethodChange` is `false`, so the attached account stays visible without a replacement action. The summary expands the sheet only when the payer opens it.

Light mode. Native Inttegro payment sheet on iOS confirming payment and offering invoice and receipt download actions. — iOSLight
**`showInvoiceDownload` + `showReceiptDownload`**After a successful payment, available Checkout URLs become secure download actions while the success sheet returns to its compact height.

Every lifecycle event includes type, occurredAt, flowId, and sequence. The complete event set is presented, ready, change, orderPrepared, paymentAttemptStarted, paymentActionRequired, paymentProcessing, paymentAttemptFailed, completed, canceled, and failed. Events about an Order carry its full client-safe representation; there is no separate payment ID. presentPaymentSheet returns the exact terminal event already delivered to the lifecycle listener.

The callbacks above belong to your application; replace them with state updates, analytics, or navigation appropriate to your checkout. A recoverable payment attempt failure does not resolve presentPaymentSheet, because the customer can retry inside the sheet. The SDK owns confirmation, provider authorization, and redirects while your app can use the sanitized events for timely UI and analytics. A secret Inttegro API key must never be included in the application bundle.

Verify before fulfillment

completed is suitable for immediate client UI, but the mobile app is not the authoritative payment source. Your backend must confirm the owner-scoped Order state—using an Order lookup or webhook—before releasing goods or services.

See it in a complete app

The React Native and Expo storefront demo shows a shopper choosing a product and paying through Inttegro's native payment sheet. Follow the guide to run the development build with its Next.js demo backend and see the full boundary between the mobile experience and server-owned commerce.

Observability

Use addPaymentSheetTelemetryListener only when you want low-level Checkout and network diagnostics:

import { addPaymentSheetTelemetryListener } from '@inttegro/react-native/telemetry'

const diagnostics = addPaymentSheetTelemetryListener(recordInttegroDiagnostic)

addPaymentSheetEventListener provides typed, application-facing stages for each presentation. Use it for checkout UI, analytics, and recoverable-attempt notifications. The terminal result returned by the presentation method remains the source for completion, cancellation, and terminal-failure handling.

addPaymentSheetTelemetryListener is the separate diagnostic stream. It adds Checkout operation, HTTP status, safe request identifier, and bounded error-category fields for your application-owned telemetry pipeline. Diagnostic events are not authoritative payment state.

You can pass the active W3C trace context traceparent and optional tracestate when initializing the sheet. Inttegro does not install an exporter or send the event stream anywhere by itself.

Event data-safety contract

Lifecycle and diagnostic events contain bounded status and correlation metadata. They never contain order or payment IDs, customer or payer data, payment-method details, request or response bodies, redirect URLs, or raw error messages. Do not use flowId or requestId as metric labels.

The root @inttegro/react-native import remains supported for existing applications. Focused entry points keep payment presentation, lifecycle events, telemetry, and shared types on separate API-reference pages without creating separate native implementations or versions.