--- title: "React Native SDK" description: "Integrate and observe Inttegro’s native payment sheet from React Native." canonical: "https://studio.inttegro.com/mobile/react-native" format: inttegro-machine-docs/v1 language: "TypeScript" sdk_version: "v12.0.0" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/typescript/readers/index.json" reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations." preamble_estimated_tokens: 573 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "curated" recommended_mcp_tools: ["design_integration","check_integration_readiness"] estimated_tokens: 3430 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** React Native presents native mobile-money Checkout from a backend-created Order ID, but this adapter is still a developer preview and must not be presented as ready for live payments. ### Five questions #### Q1. Is this adapter ready for production payments? No. The [React Native guide](https://studio.inttegro.com/machine/typescript/mobile/react-native.md) labels the package a developer preview not yet published for live payments. Its exposed flow is mobile money, not card, Apple Pay, or Google Pay; avoid promising unsupported methods. #### Q2. Which React Native environment can run the sheet? Use React Native 0.82+ with the New Architecture and supported iOS or Android minimums. An Expo development build can load the native module; Expo Go cannot. See [requirements](https://studio.inttegro.com/machine/typescript/mobile/react-native.md#requirements). #### Q3. What crosses from the backend to the device? The backend creates and finalizes the order, then returns only the client-safe Order ID. Keep the API key, amount decisions, and customer payment details off the device. See [payment lifecycle](https://studio.inttegro.com/machine/typescript/mobile/react-native.md#payment-lifecycle). #### Q4. What does a completed sheet result prove? It provides immediate client UI feedback, not independent proof of a paid order. Ask the backend to [look up the order](https://studio.inttegro.com/machine/typescript/api/orders.md#lookup-an-order) before fulfillment; cancellation and recoverable failures follow their documented result paths. See [present the sheet](https://studio.inttegro.com/machine/typescript/mobile/react-native.md#present-the-payment-sheet). #### Q5. What should an AI coding agent use first? With an authenticated MCP connection, [design_integration](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#design_integration) can plan the backend/mobile boundary, then [check_integration_readiness](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#check_integration_readiness) can inspect declared controls. Use the [Flutter mobile guide](https://studio.inttegro.com/machine/typescript/mobile/flutter.md) only if the app is actually Flutter; do not copy its symbols into React Native. ## Document content # Inttegro SDK for React Native The [Inttegro SDK for React Native](https://github.com/inttegro/inttegro-sdk-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. :::tip Start with MCP Before writing SDK code, [connect your MCP client](https://studio.inttegro.com/machine/typescript/inttegro-mcp/connect.md) and ask MCP to [design the integration](https://studio.inttegro.com/machine/typescript/inttegro-mcp/design-integration.md) for your mobile checkout flow. Use the resulting plan to define the boundary between your server, this SDK, and the Inttegro API. ::: :::note 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](https://reactnative.dev/architecture/landing-page) enabled - [iOS 16](https://developer.apple.com/documentation/ios-ipados-release-notes) or later - [Android API 26](https://developer.android.com/tools/releases/platforms) 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](https://reactnative.dev/docs/the-new-architecture/using-codegen) and autolinking can run. Expo applications require a [development build](https://docs.expo.dev/develop/development-builds/introduction/); Expo Go cannot load the native module. ```shell npm install @inttegro/react-native ``` ## Payment lifecycle > Mobile Payment Lifecycle is interactive content. Use the canonical page to view it. 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. ```typescript 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`: ```typescript 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. > Mobile Sdk Screenshots is interactive content. Use the canonical page to view it. ## Present the payment sheet ```typescript 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`](https://react-native.inttegro.dev/v0.6.0/interfaces/PaymentSheetFeatures.html) 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`](https://react-native.inttegro.dev/v0.6.0/interfaces/PaymentSheetFeatures.html#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`](https://react-native.inttegro.dev/v0.6.0/interfaces/PaymentSheetFeatures.html#showinvoicedownload) | `false` | Offers the invoice after a successful payment when Checkout returns a secure invoice URL. | | [`showLineItems`](https://react-native.inttegro.dev/v0.6.0/interfaces/PaymentSheetFeatures.html#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`](https://react-native.inttegro.dev/v0.6.0/interfaces/PaymentSheetFeatures.html#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. > Mobile Sdk Feature Screenshots is interactive content. Use the canonical page to view it. 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](https://studio.inttegro.com/machine/typescript/api/authentication.md#store-credentials-safely) must never be included in the application bundle. :::warning 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](https://studio.inttegro.com/machine/typescript/demos/react-native-expo.md) 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: ```typescript import { addPaymentSheetTelemetryListener } from '@inttegro/react-native/telemetry' const diagnostics = addPaymentSheetTelemetryListener(recordInttegroDiagnostic) ``` > Mobile Sdk Observability is interactive content. Use the canonical page to view it. 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. ## Continue - [Browse the generated API reference](https://react-native.inttegro.dev/v0.6.0/) - [Browse the preview source](https://github.com/inttegro/inttegro-sdk-react-native) - [Run the React Native and Expo storefront](https://studio.inttegro.com/machine/typescript/demos/react-native-expo.md) - [Create and finalize orders](https://studio.inttegro.com/machine/typescript/api/orders.md#create-an-order)