{"templateId":"markdown","versions":[{"version":"v0-beta","label":"Beta (v0)","link":"/products/native-api/docs/sdk/sdk-reference","default":true,"active":true,"folderId":"e4cb5a06"}],"sharedDataIds":{"sidebar":"sidebar-products/native-api/@v0-beta/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"React Native SDK Reference","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":"react-native-sdk-reference","__idx":0},"children":["React Native SDK Reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Banxa React Native SDK is the payment execution layer of Banxa Native. It's used alongside the Native API to present native payment sheets for cards, Apple Pay, and Google Pay — the payment methods that can't be handled through the API alone due to PCI requirements."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Bank transfers are handled directly by the Native API and don't involve the SDK. For the end-to-end integration walkthrough, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/guides/foundations"},"children":["Integration Guide"]},"."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Which SDK modules are relevant for Banxa Native?"]}," ","In a Banxa Native integration, your backend handles pricing, identity, and eligibility via the Native API. The SDK's role is limited to payment execution — specifically ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa.buy"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createOrderAndShowPrimerCheckout"]}," for card and wallet payments."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The full module reference is documented below for completeness."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"installation","__idx":1},"children":["Installation"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npm install @banxa-official/react-native-sdk @primer-io/react-native react-native-webview\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@primer-io/react-native"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["react-native-webview"]}," are peer dependencies. For iOS, run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pod install"]}," after installing."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-a-banxa-client","__idx":2},"children":["Creating a Banxa client"]},{"$$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":"Heading","attributes":{"level":3,"id":"configuration-options","__idx":3},"children":["Configuration options"]},{"$$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":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$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":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your Banxa API key from the Partner Dashboard."]}]},{"$$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":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your partner identifier."]}]},{"$$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'"]}," | ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'production'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom base URL — overrides the environment-derived URL."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primerCallbacks"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Primer checkout callbacks: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCheckoutComplete"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onDismiss"]},". Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["console.log"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primerSettings"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Partial<PrimerSettings>"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Primer base settings (UI options, payment method options) merged into all Primer flows."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"primer-customisation","__idx":4},"children":["Primer customisation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkout UI for card, Apple Pay, and Google Pay is provided by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@primer-io/react-native"]},". Pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primerSettings"]}," on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Banxa"]}," constructor — the SDK merges them into Primer's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configure()"]}," for checkout flows. The TypeScript type is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PrimerSettings"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@primer-io/react-native"]}," (typically passed as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Partial<PrimerSettings>"]},")."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"theme","__idx":5},"children":["Theme"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primerSettings.uiOptions.theme"]}," accepts optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["colors"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["darkModeColors"]},". Each is a color set with the same optional keys. Every color uses the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IRgbaColor"]}," shape: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ red, green, blue, alpha }"]}," with values from 0–255."]},{"$$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":"Key"},"children":["Key"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Role"},"children":["Role"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mainColor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Primary brand / accent."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contrastingColor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contrasting surface to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mainColor"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["background"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Screen / sheet background color."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Primary text color."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contrastingText"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Text color on strong colored surfaces."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["borders"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Borders and dividers color."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["disabled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Disabled controls color."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error state emphasis color."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example--theme-and-ui-flags","__idx":6},"children":["Example — theme and UI flags"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const banxa = new Banxa({\n  apiKey: 'YOUR_API_KEY',\n  partner: 'your-partner-id',\n  environment: 'sandbox',\n  primerSettings: {\n    uiOptions: {\n      appearanceMode: 'SYSTEM', // or 'LIGHT' / 'DARK'\n      theme: {\n        colors: {\n          mainColor: { red: 7, green: 138, blue: 88, alpha: 255 },\n          contrastingColor: { red: 255, green: 255, blue: 255, alpha: 255 },\n          background: { red: 216, green: 242, blue: 240, alpha: 255 },\n          text: { red: 7, green: 138, blue: 88, alpha: 255 },\n          contrastingText: { red: 255, green: 255, blue: 255, alpha: 255 },\n          borders: { red: 209, green: 96, blue: 209, alpha: 255 },\n          disabled: { red: 100, green: 100, blue: 100, alpha: 255 },\n          error: { red: 235, green: 126, blue: 16, alpha: 255 },\n        },\n        darkModeColors: {\n          mainColor: { red: 1, green: 255, blue: 1, alpha: 255 },\n          background: { red: 255, green: 1, blue: 255, alpha: 255 },\n        },\n      },\n    },\n  },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"buy","__idx":7},"children":["Buy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa.buy"]}," module handles buy orders (fiat → crypto). Endpoints use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/buy"]}," path."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"createorder","__idx":8},"children":["createOrder"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a new buy order."]},{"$$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\nconsole.log('Order created:', order.id);\nconsole.log('Checkout URL:', order.checkoutUrl);\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"checkeligibility","__idx":9},"children":["checkEligibility"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check whether an order can proceed before creating it. The response's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady"]}," field determines whether to use the Primer native sheet or fall back to the WebView."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const orderRequest = {\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\nconst eligibility = await banxa.buy.checkEligibility(orderRequest);\n\nif (eligibility.paymentReady) {\n  const checkoutResult = await banxa.buy.createOrderAndShowPrimerCheckout(orderRequest);\n  // Primer shown; see createOrderAndShowPrimerCheckout below for the result shape\n} else {\n  const order = await banxa.buy.createOrder(orderRequest);\n  const webViewProps = banxa.buy.initializeCheckoutWebView(order, { /* ... */ });\n  // render <CheckoutWebView {...webViewProps} />\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady"]}," from the eligibility response to choose between Primer and WebView. Do not rely on other fields for gating."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"createorderandshowprimercheckout","__idx":10},"children":["createOrderAndShowPrimerCheckout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create an order and present the Primer native payment sheet in a single call. Falls back to a WebView result if the created order lacks a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nativeToken"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import {\n  isPrimerCheckoutWebViewResult,\n  type PrimerCheckoutPaymentMethod,\n} from '@banxa-official/react-native-sdk';\n\nconst result = await banxa.buy.createOrderAndShowPrimerCheckout(orderRequest);\n\nif (isPrimerCheckoutWebViewResult(result)) {\n  // No nativeToken; checkoutUrl returned instead\n  const { order, webViewProps } = result;\n  // render <CheckoutWebView {...webViewProps} />\n} else {\n  // Primer was shown; result is the Order\n  const order = result;\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also pick the Primer flow explicitly:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const method: PrimerCheckoutPaymentMethod = 'applePay'; // 'card' | 'applePay' | 'googlePay' | 'universal'\n\nawait banxa.buy.createOrderAndShowPrimerCheckout(orderRequest, {\n  paymentMethod: method,\n  callbacks: {\n    onCheckoutComplete: () => { /* ... */ },\n    onError: () => { /* ... */ },\n    onDismiss: () => { /* ... */ },\n  },\n  // WebView fallback options, used only if nativeToken is missing\n  webViewProps: {\n    returnUrlOnSuccess: 'https://yourapp.com/success',\n    onClose: () => { /* ... */ },\n  },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the order has neither ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nativeToken"]}," nor ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]},", the method throws."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"getorder","__idx":11},"children":["getOrder"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve a single buy order."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const orderDetails = await banxa.buy.getOrder(order.id);\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"getordersbyaccount","__idx":12},"children":["getOrdersByAccount"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve buy orders associated with a specific ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const userBuyOrders = await banxa.buy.getOrdersByAccount('user-123');\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"initializecheckoutwebview","__idx":13},"children":["initializeCheckoutWebView"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure props for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutWebView"]}," component when falling back to the hosted checkout flow."]},{"$$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\nconst [showCheckout, setShowCheckout] = useState(false);\n\nconst webViewProps = banxa.buy.initializeCheckoutWebView(order, {\n  onClose: () => setShowCheckout(false),\n  onSuccess: (url) => {\n    console.log('Payment successful', url);\n    setShowCheckout(false);\n  },\n  onFailure: (url) => {\n    console.log('Payment failed', url);\n    setShowCheckout(false);\n  },\n  returnUrlOnSuccess: 'https://yourapp.com/success',\n  returnUrlOnFailure: 'https://yourapp.com/failure',\n});\n\n// In your component render:\n{showCheckout && <CheckoutWebView {...webViewProps} />}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prices","__idx":14},"children":["Prices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa.prices"]}," module retrieves live quotes. Maps to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /quotes/{orderType}"]},". Either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}," must be provided; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethodId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["blockchain"]}," are also required."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"getquote","__idx":15},"children":["getQuote"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve a quote for a specific order type (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'buy'"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'sell'"]},")."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const quote = await banxa.prices.getQuote('buy', {\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('Fiat amount:', quote.fiatAmount);\nconsole.log('Processing fee:', quote.processingFee);\nconsole.log('Network fee:', quote.networkFee);\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"getbuyquote","__idx":16},"children":["getBuyQuote"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Convenience method for buy quotes."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const buyQuote = await banxa.prices.getBuyQuote({\n  fiat: 'USD',\n  crypto: 'BTC',\n  fiatAmount: '100',\n  paymentMethodId: '1',\n  blockchain: 'bitcoin',\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-methods","__idx":17},"children":["Payment Methods"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa.paymentMethods"]}," module retrieves supported payment methods."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// All payment methods\nconst paymentMethods = await banxa.paymentMethods.getPaymentMethods();\n\n// Filtered by currency pair\nconst methods = await banxa.paymentMethods.getPaymentMethods('USD', 'BTC');\n\n// Single payment method by ID\nconst method = await banxa.paymentMethods.getPaymentMethod(1);\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"countries","__idx":18},"children":["Countries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa.countries"]}," module retrieves supported countries."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const countries = await banxa.countries.getCountries();\nconst country = await banxa.countries.getCountry('US');\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"currencies","__idx":19},"children":["Currencies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa.currencies"]}," module retrieves supported fiat and crypto currencies. Fiat and crypto come from separate endpoints (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /fiats/{orderType}"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /crypto/{orderType}"]},") — availability can differ between buy and sell flows."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// Defaults to order type 'buy'\nconst fiatCurrencies = await banxa.currencies.getFiatCurrencies();\nconst cryptoCurrencies = await banxa.currencies.getCryptoCurrencies();\n\n// Explicit order type — use 'sell' for sell flows\nconst sellFiats = await banxa.currencies.getFiats('sell');\nconst sellCrypto = await banxa.currencies.getCrypto('sell');\n\n// No single-currency endpoint — look up from the list\nconst btc = cryptoCurrencies.find((c) => c.id === 'BTC');\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"checkoutwebview-component","__idx":20},"children":["CheckoutWebView component"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutWebView"]}," renders the hosted checkout when the native payment sheet isn't used."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { CheckoutWebView } from '@banxa-official/react-native-sdk';\n\n<CheckoutWebView {...webViewProps} />\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa.buy.initializeCheckoutWebView(order, options)"]}," to generate the props. The component detects navigation to your return URLs and triggers the appropriate callback."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":21},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK throws ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BanxaSDKError"]}," 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":"Heading","attributes":{"level":3,"id":"banxasdkerror-properties","__idx":22},"children":["BanxaSDKError properties"]},{"$$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":"Property"},"children":["Property"]},{"$$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":["message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable error description."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Banxa error code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["statusCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP status code from the API response."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"typescript-support","__idx":23},"children":["TypeScript support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK is written in TypeScript and ships with type definitions."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { Banxa, Order, Quote, PaymentMethod } from '@banxa-official/react-native-sdk';\n\nconst banxa = new Banxa({ /* ... */ });\n\nconst order: Order = await banxa.buy.createOrder({ /* ... */ });\nconst quote: Quote = await banxa.prices.getBuyQuote({ /* ... */ });\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"react-native-compatibility","__idx":24},"children":["React Native compatibility"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Uses the standard ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fetch"]}," API (available in React Native)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["react-native-webview"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@primer-io/react-native"]}," are required peer dependencies."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For iOS: run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cd ios && pod install"]}," after installing."]}]}]},"headings":[{"value":"React Native SDK Reference","id":"react-native-sdk-reference","depth":1},{"value":"Installation","id":"installation","depth":2},{"value":"Creating a Banxa client","id":"creating-a-banxa-client","depth":2},{"value":"Configuration options","id":"configuration-options","depth":3},{"value":"Primer customisation","id":"primer-customisation","depth":2},{"value":"Theme","id":"theme","depth":3},{"value":"Example — theme and UI flags","id":"example--theme-and-ui-flags","depth":3},{"value":"Buy","id":"buy","depth":2},{"value":"createOrder","id":"createorder","depth":3},{"value":"checkEligibility","id":"checkeligibility","depth":3},{"value":"createOrderAndShowPrimerCheckout","id":"createorderandshowprimercheckout","depth":3},{"value":"getOrder","id":"getorder","depth":3},{"value":"getOrdersByAccount","id":"getordersbyaccount","depth":3},{"value":"initializeCheckoutWebView","id":"initializecheckoutwebview","depth":3},{"value":"Prices","id":"prices","depth":2},{"value":"getQuote","id":"getquote","depth":3},{"value":"getBuyQuote","id":"getbuyquote","depth":3},{"value":"Payment Methods","id":"payment-methods","depth":2},{"value":"Countries","id":"countries","depth":2},{"value":"Currencies","id":"currencies","depth":2},{"value":"CheckoutWebView component","id":"checkoutwebview-component","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"BanxaSDKError properties","id":"banxasdkerror-properties","depth":3},{"value":"TypeScript support","id":"typescript-support","depth":2},{"value":"React Native compatibility","id":"react-native-compatibility","depth":2}],"frontmatter":{"title":"React Native SDK Reference","description":"Complete reference for the Banxa React Native SDK — configuration, modules, types, and error handling.","seo":{"title":"React Native SDK Reference"}},"lastModified":"2026-06-01T06:52:05.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/native-api/docs/sdk/sdk-reference","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}