{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/hosted-checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"SDK Integration Guide","description":"Official Banxa API documentation – on-ramp and off-ramp transfers with identity verification and compliance.","llmstxt":{"title":"Banxa Developer Documentation","description":"Integrate crypto-fiat exchange with Banxa's licensed infrastructure: payments, KYC, compliance, and settlement handled. 150+ countries, 45 global licences.","details":{"content":"Two integration products: **Banxa Native API** for partners who manage their own KYC and want full UX control (headless, HMAC server-to-server, no Banxa-hosted screens); **Banxa Hosted Checkout** for partners who want Banxa to handle KYC and payments (three paths: Referral URL, API, or React Native SDK). Both use the same sandbox and production environments at `https://api.banxa-sandbox.com` and `https://api.banxa.com`.\n\n## Constraints\n\n- **Authentication**: HMAC credentials must be stored server-side only, never expose in frontend, mobile, or client-side code. HMAC is required for all Native API calls and for KYC sharing in Hosted Checkout; `x-api-key` is used for all other Hosted Checkout endpoints.\n- **`externalCustomerId`**: Required on every buy and sell order. Use a stable opaque identifier, never PII.\n- **`identityReference`**: Must remain constant for the same user across all requests. Must not contain PII. If you attempt to create an identity for an email that already exists, you will receive a 422 / code 81, so retrieve the existing record rather than retrying creation. Use `GET /eapi/v0/identities/{identityReference}?email=user@example.com` to look up the real `identityReference` linked to an email.\n- **`quoteId`**: Only supported by `POST /eapi/v0/ramps` (bank transfer). The React Native SDK and Embedded Payment Button do not accept a `quoteId`, so use indicative pricing (`GET /eapi/v0/price`) for SDK and Embedded Payment Button flows.\n- **Quotes**: Indicative prices are not rate-locked, so refresh close to order creation to minimise rate drift. Locked quotes (`GET /eapi/v0/quote`) expire after approximately 3 minutes and are only valid for bank transfer ramp creation.\n- **Eligibility gate**: Never create a ramp or invoke the SDK when `paymentReady` is `false`. Always check eligibility and satisfy all requirements before payment execution.\n- **Webhooks**: Verify all inbound webhook signatures with HMAC-SHA256 before processing. Return HTTP 200 immediately and process asynchronously.\n- **Product selection**: Banxa Native is for partners who manage their own KYC. Banxa Hosted Checkout is for partners who do not do KYC. These are separate products with separate flows: do not mix endpoints across products.\n- **SDK scope**: The React Native SDK has no `banxa.customerIdentity` module. Identity and KYC are handled through the Native API only. `primerCallbacks` and `primerSettings` are Native context only and must not be referenced in Hosted Checkout integrations.\n- **Payment method naming**: Never use \"eAPI\" or \"EAPI\" as a product name. The correct name is \"Banxa Native API\". The URL path prefix `/eapi/` is correct and should not be changed.\n"},"hide":false,"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"sdk-integration-guide","__idx":0},"children":["SDK Integration Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide walks through a complete Banxa Hosted Checkout integration using the React Native SDK. By the end, you'll have a working buy flow: fetch a live quote, create an order, present the checkout in a WebView, and retrieve the final order status."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":1},"children":["Before you start"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A React Native mobile app (iOS, Android, or both)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your Banxa partner reference and API key (sandbox for development, production after approval)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A configured webhook endpoint (optional but recommended for order status tracking)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"install-the-sdk","__idx":3},"children":["Install the SDK"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npm install @banxa-official/react-native-sdk react-native-webview\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For iOS, install the pods:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"cd ios && pod install\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["react-native-webview"]}," is a peer dependency."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1--initialise-the-sdk","__idx":4},"children":["Step 1 — Initialise the SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a single ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Banxa"]}," client instance at app startup. Keep it in a shared service or context so it can be reused across screens."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { Banxa } from '@banxa-official/react-native-sdk';\n\nconst banxa = new Banxa({\n  apiKey: 'YOUR_API_KEY',\n  partner: 'your-partner-id',\n  environment: 'sandbox', // or 'production'\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your Banxa API key."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your partner identifier (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["binance"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metamask"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["environment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'sandbox'"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'production'"]},". Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'production'"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["baseUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional. Overrides the environment-derived base URL."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2--get-a-quote","__idx":5},"children":["Step 2 — Get a quote"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call the Quote API to retrieve live pricing before presenting an amount to the customer. Call this close to when you show the price — crypto rates move quickly, and stale quotes can differ from the final checkout price."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const quote = await banxa.prices.getBuyQuote({\n  fiat: 'USD',\n  crypto: 'BTC',\n  fiatAmount: '100',\n  paymentMethodId: '1',\n  blockchain: 'bitcoin',\n});\n\nconsole.log('Crypto amount:', quote.cryptoAmount);\nconsole.log('Processing fee:', quote.processingFee);\nconsole.log('Network fee:', quote.networkFee);\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}," must be provided. For sell quotes, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa.prices.getQuote('sell', { ... })"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3--create-an-order","__idx":6},"children":["Step 3 — Create an order"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a buy order once the customer confirms."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const order = await banxa.buy.createOrder({\n  externalCustomerId: 'user-123',\n  fiat: 'USD',\n  crypto: 'BTC',\n  fiatAmount: '100',\n  paymentMethodId: '1',\n  walletAddress: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',\n  redirectUrl: 'https://yourapp.com/success',\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"required-fields","__idx":7},"children":["Required fields"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}," — your stable customer identifier, used by Banxa to recognise returning customers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiat"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["crypto"]},", and either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethodId"]}," — pre-selects the payment method."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["walletAddress"]}," — the customer's receiving wallet address."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," — where the customer is returned after checkout."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response","__idx":8},"children":["Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"checkoutUrl\": \"https://partner.banxa.com/portal?expires=xxx&oid=xxx&signature=xxx\",\n  \"id\": \"191fa5b4b1f45e1cf784422e09317d56\",\n  \"externalOrderId\": \"a4b427ccb872a1744b317456bd0d165f\",\n  \"externalCustomerId\": \"user-123\",\n  \"fiat\": \"CAD\",\n  \"fiatAmount\": \"1000.00\",\n  \"crypto\": \"USDC\",\n  \"cryptoAmount\": null,\n  \"blockchain\": \"TRON\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Banxa-hosted checkout URL to present to the customer."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Banxa order ID. Store this — you'll use it for order lookup."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalOrderId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your internal order reference, if provided at creation. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," if not."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your customer identifier as supplied."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiat"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["crypto"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["blockchain"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order parameters as supplied. If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}," wasn't provided, it will be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4--present-the-checkout","__idx":9},"children":["Step 4 — Present the checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initializeCheckoutWebView"]}," to configure the props for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutWebView"]}," component, then render it."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { CheckoutWebView } from '@banxa-official/react-native-sdk';\nimport { useState } from 'react';\n\nfunction BuyCryptoScreen() {\n  const [webViewProps, setWebViewProps] = useState(null);\n\n  const handleBuyPress = async () => {\n    const order = await banxa.buy.createOrder({\n      externalCustomerId: 'user-123',\n      fiat: 'USD',\n      crypto: 'BTC',\n      fiatAmount: '100',\n      paymentMethodId: '1',\n      walletAddress: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',\n      redirectUrl: 'https://yourapp.com/success',\n    });\n\n    const props = banxa.buy.initializeCheckoutWebView(order, {\n      onClose: () => setWebViewProps(null),\n      onSuccess: (url) => { /* payment succeeded */ setWebViewProps(null); },\n      onFailure: (url) => { /* payment failed */ setWebViewProps(null); },\n      returnUrlOnSuccess: 'https://yourapp.com/success',\n      returnUrlOnFailure: 'https://yourapp.com/failure',\n    });\n\n    setWebViewProps(props);\n  };\n\n  return (\n    <>\n      <Button onPress={handleBuyPress} title=\"Buy BTC\" />\n      {webViewProps && <CheckoutWebView {...webViewProps} />}\n    </>\n  );\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The WebView detects navigation to your return URLs automatically and triggers the corresponding callback."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-methods-that-cant-run-in-a-webview","__idx":10},"children":["Payment methods that can't run in a WebView"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some payment methods — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["iDEAL, Klarna, and PayPal"]}," — cannot complete inside a WebView. These methods require the customer to be redirected outside your app to the provider (bank, Klarna, or PayPal). There is no automatic return, so partners should design a post-payment UX — for example, a confirmation screen with a link back to the app."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"native-payment-sheet-primer","__idx":11},"children":["Native payment sheet (Primer)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK also supports a native payment sheet via Primer for card, Apple Pay, and Google Pay payments. This is a more advanced integration designed for partners who verify their own users and run their own KYC — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://banxa-enterprise.redocly.app/enterprise-api/v0-beta"},"children":["Banxa Native"]},". Talk to Banxa if you'd like to discuss whether this is relevant for your integration."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5--look-up-order-status","__idx":12},"children":["Step 5 — Look up order status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the customer completes checkout, retrieve the final order status via the SDK."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const orderDetails = await banxa.buy.getOrder(order.id);\n\nif (orderDetails.status === 'complete') {\n  // Notify the user, update your database, etc.\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the full list of order statuses and their meanings, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/transaction-lifecycle/order-statuses"},"children":["Order Statuses"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"retrieving-orders-by-customer","__idx":13},"children":["Retrieving orders by customer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To list buy orders for a specific customer:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const userOrders = await banxa.buy.getOrdersByAccount('user-123');\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This returns orders tied to that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]},". For a full list of all orders across all customers (reconciliation, reporting), use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/api-integration/api-integration-overview"},"children":["Banxa API"]}," directly — this isn't exposed through the SDK."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6--handle-webhooks-recommended","__idx":14},"children":["Step 6 — Handle webhooks (recommended)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," callback fires when the customer completes checkout, but for reliable order status tracking you should configure webhooks on your backend."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks fire for every order status change. Configure your webhook URL in the Partner Dashboard."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["→ See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/transaction-lifecycle/webhooks"},"children":["Webhooks"]}," for payload structure and security."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The typical pattern:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["SDK ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," callback → optimistic UI update (\"your order is processing\")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Webhook to your backend → authoritative order state."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Backend pushes update to the app (or app re-fetches order on resume)."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":15},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wrap SDK calls in try/catch. The SDK throws ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BanxaSDKError"]}," objects for API and network failures."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { Banxa, BanxaSDKError } from '@banxa-official/react-native-sdk';\n\ntry {\n  const order = await banxa.buy.createOrder({ /* ... */ });\n} catch (error) {\n  if (error instanceof BanxaSDKError) {\n    console.error('Banxa API error:', error.message);\n    console.error('Error code:', error.code);\n    console.error('Status code:', error.statusCode);\n  } else {\n    console.error('Unknown error:', error);\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Show user-facing messages only from validated error fields — don't expose raw error strings that may include internal detail."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"testing","__idx":16},"children":["Testing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the sandbox environment for all development and testing:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const banxa = new Banxa({\n  apiKey: 'YOUR_SANDBOX_API_KEY',\n  partner: 'your-partner-id',\n  environment: 'sandbox',\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For test credentials (mobile numbers, card numbers, PIN codes, KYC data), see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/testing/sandbox-test-data"},"children":["Sandbox Test Data"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":17},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/sdk-integration/sdk-reference"},"children":["SDK Reference"]}," — full method reference."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/transaction-lifecycle/webhooks"},"children":["Webhooks"]}," — configure webhook notifications."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/transaction-lifecycle/order-statuses"},"children":["Order Statuses"]}," — full status reference."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/testing/sandbox-test-data"},"children":["Sandbox Test Data"]}," — credentials and test values for testing."]}]}]},"headings":[{"value":"SDK Integration Guide","id":"sdk-integration-guide","depth":1},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":3},{"value":"Install the SDK","id":"install-the-sdk","depth":3},{"value":"Step 1 — Initialise the SDK","id":"step-1--initialise-the-sdk","depth":2},{"value":"Step 2 — Get a quote","id":"step-2--get-a-quote","depth":2},{"value":"Step 3 — Create an order","id":"step-3--create-an-order","depth":2},{"value":"Required fields","id":"required-fields","depth":3},{"value":"Response","id":"response","depth":3},{"value":"Step 4 — Present the checkout","id":"step-4--present-the-checkout","depth":2},{"value":"Payment methods that can't run in a WebView","id":"payment-methods-that-cant-run-in-a-webview","depth":3},{"value":"Native payment sheet (Primer)","id":"native-payment-sheet-primer","depth":3},{"value":"Step 5 — Look up order status","id":"step-5--look-up-order-status","depth":2},{"value":"Retrieving orders by customer","id":"retrieving-orders-by-customer","depth":3},{"value":"Step 6 — Handle webhooks (recommended)","id":"step-6--handle-webhooks-recommended","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Testing","id":"testing","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"SDK Integration Guide — React Native | Banxa Docs","description":"End-to-end React Native SDK integration for Banxa Hosted Checkout: install, configure, quote, create order, present checkout, handle completion.","seo":{"title":"SDK Integration Guide"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/hosted-checkout/docs/sdk-integration/integration-guide","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}