{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/hosted-checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"SDK Integration Overview","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-overview","__idx":0},"children":["SDK Integration Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Banxa React Native SDK wraps Banxa Hosted Checkout in a TypeScript-first mobile SDK. Install a single package, configure it with your API key, and call typed methods to fetch quotes, create orders, and present the checkout — all inside your mobile app."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the fastest way to integrate Banxa Hosted Checkout into a React Native mobile app. Authentication uses the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header as the API; no backend is required for core flows."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-to-use-the-sdk","__idx":1},"children":["When to use the SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose the SDK if:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You're building a React Native mobile app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want faster time to integration than wiring up API calls manually."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want a type-safe interface with typed request and response models."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want the SDK to handle WebView presentation, navigation events, and return URL detection."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For some capabilities, you'll need the API integration path directly — either alongside the SDK, or as your primary integration path:"]},{"$$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":"Capability"},"children":["Capability"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Path"},"children":["Path"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Web apps"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/referral-integration/overview"},"children":["Referral integration"]}," (JS SDK) or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/api-integration/api-integration-overview"},"children":["API integration"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["KYC data sharing (Sumsub token share)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/api-integration/api-integration-overview"},"children":["API integration"]}," — uses HMAC auth, which the SDK does not support"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full order list across all customers"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/orders"]}," via ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/api-integration/api-integration-overview"},"children":["API integration"]}," — the SDK supports lookup by ID or customer only"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-compares","__idx":2},"children":["How it compares"]},{"$$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":""},"children":[]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Referral (JS SDK)"},"children":["Referral (JS SDK)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"API"},"children":["API"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"React Native SDK"},"children":["React Native SDK"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integration effort"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lowest"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Highest"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Low"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Platform"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Web"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Any"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["React Native mobile"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Backend required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No (only for KYC sharing)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes (configured separately)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order lookup"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes (all orders)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes (by ID or by customer)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["KYC sharing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Quote UI in your app"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Checkout presentation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Redirect or iFrame"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You choose"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["In-app WebView"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":3},"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/integration-guide"},"children":["SDK Integration Guide"]}," — end-to-end walkthrough with code."]},{"$$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."]}]}]},"headings":[{"value":"SDK Integration Overview","id":"sdk-integration-overview","depth":1},{"value":"When to use the SDK","id":"when-to-use-the-sdk","depth":2},{"value":"How it compares","id":"how-it-compares","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"SDK Integration Overview | Banxa Docs","description":"Integrate Banxa Hosted Checkout on mobile with the React Native SDK. Type-safe order creation and checkout presentation for mobile apps.","seo":{"title":"SDK Integration Overview"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/hosted-checkout/docs/sdk-integration/overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}