{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/hosted-checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"JavaScript Native Payments 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## When to use Banxa\n\nReach for Banxa when a product needs to let people **buy crypto with fiat or sell crypto for fiat** without the partner holding money-transmitter or VASP licences. Banxa is the licensed counterparty: it takes the payment, runs compliance, and delivers the asset. Typical fits are wallets, exchanges, dApps, gaming platforms and fintech apps adding an on-ramp or off-ramp.\n\nPick the product by who owns KYC:\n\n- **Banxa Native API** - the partner already runs its own KYC and wants no Banxa screens at all. Headless, HMAC-signed server-to-server, partner owns the entire interface. Needs a backend. Days to weeks to integrate.\n- **Banxa Hosted Checkout** - the partner does not want to run KYC. Banxa handles identity, payment and delivery in its own flow, reached by redirect, embedded iFrame, or React Native SDK. No backend required for the referral path. Hours to days to integrate.\n- **Legacy API** - existing integrations only. Do not start here.\n\nBanxa is not the right tool for crypto-to-crypto swaps, custody or wallet infrastructure, or for any flow where the partner wants to settle funds itself.\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"}}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"javascript-native-payments-sdk-reference","__idx":0},"children":["JavaScript Native Payments SDK Reference"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the complete documentation index, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/llms.txt"},"children":["llms.txt"]},". Append ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".md"]}," to any page URL for its markdown version."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Banxa JavaScript Native Payments SDK is a TypeScript-first interface to Banxa for web apps. It's the web counterpart to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/sdk-integration/sdk-reference"},"children":["React Native SDK"]},": a Node-safe API client plus browser web components. For Banxa Hosted Checkout, it wraps the API in typed methods and provides a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<banxa-hosted-checkout>"]}," web component that embeds the checkout in an iframe, so you don't have to wire up the iframe by hand."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication uses the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header as the API. Keep your API key server-side."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is a different package from the referral ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/referral-integration/javascript-sdk"},"children":["JavaScript SDK"]},", which only builds referral URLs. This SDK creates orders and embeds checkout."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Why 'Native Payments' in the name?"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The package name refers to its Banxa Native payment sheet capability, a separate feature for partners who run their own KYC. For Hosted Checkout, you're using it to create orders and embed the hosted checkout iframe, not the native payment sheet. Ignore the \"Native Payments\" framing unless you later move to Banxa Native."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$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/javascript-native-payments-sdk\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@primer-io/primer-js"]}," peer dependency is only needed for the native payment sheet, which is a Banxa Native feature (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#native-payment-sheet-primer"},"children":["Native payment sheet"]}," below). For a Hosted Checkout iframe integration you do not need it."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"entry-points","__idx":2},"children":["Entry points"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dual module output (ESM + CJS) with separate server and browser entry points, so backend code never pulls in DOM or web component code."]},{"$$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":"Import"},"children":["Import"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Exports"},"children":["Exports"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@banxa-official/javascript-native-payments-sdk"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Node / server"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BanxaApiClient"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BanxaApiError"]},", API types"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@banxa-official/javascript-native-payments-sdk/api"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Node / server"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same as above"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@banxa-official/javascript-native-payments-sdk/web"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Browser"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["registerBanxaCheckout"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["registerBanxaHostedCheckout"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["runBuyCheckoutFlow"]},", checkout types"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The web entry does not auto-register custom elements. Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["registerBanxaCheckout()"]}," (or register components individually) before using them."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-an-api-client","__idx":3},"children":["Creating an API client"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { BanxaApiClient } from '@banxa-official/javascript-native-payments-sdk';\n\nconst client = new BanxaApiClient({\n  apiKey: process.env.BANXA_API_KEY,\n  partner: process.env.BANXA_PARTNER,\n  environment: 'sandbox', // or 'production'\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-options","__idx":4},"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 v2 API key from the merchant 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":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Selects the environment base URL."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requests use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," authentication. Keep the API key server-side, never in browser or client-side code."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"buy","__idx":5},"children":["Buy"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"createorder","__idx":6},"children":["createOrder"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a buy order. The response includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}," to load in the iframe."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const order = await client.createOrder({\n  externalCustomerId: 'user-123',\n  fiat: 'AUD',\n  crypto: 'USDT',\n  fiatAmount: '100', // or cryptoAmount, at least one is required\n  walletAddress: '0x1234567890abcdef...',\n  redirectUrl: 'https://yoursite.com/order-complete',\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Maps to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /{partner}/v2/buy"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}," is required. Use one stable identifier per customer, not per order. Provide either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]},"; if both are set, Banxa uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]},". Pricing is indicative, the SDK does not accept a locked ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}," is valid for 1 minute from order creation and must be loaded within that window. Once loaded it does not expire. Create the order when the customer confirms and load it immediately. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/reference/faq"},"children":["FAQ"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"getorder","__idx":7},"children":["getOrder"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve a single order by its Banxa order ID."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const orderDetails = await client.getOrder(order.id);\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Maps to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /{partner}/v2/orders/{orderId}"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hosted-checkout-component","__idx":8},"children":["Hosted checkout component"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<banxa-hosted-checkout>"]}," web component embeds the Banxa checkout (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.checkoutUrl"]},") in an iframe and detects return navigation for you."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<script type=\"module\">\n  import { registerBanxaHostedCheckout } from '@banxa-official/javascript-native-payments-sdk/web';\n\n  registerBanxaHostedCheckout();\n</script>\n\n<banxa-hosted-checkout id=\"checkout\"></banxa-hosted-checkout>\n\n<script type=\"module\">\n  const response = await fetch('/api/create-order', { method: 'POST' });\n  const { checkoutUrl } = await response.json();\n\n  const checkout = document.getElementById('checkout');\n  checkout.setAttribute('checkout-url', checkoutUrl);\n  checkout.setAttribute('return-url', `${window.location.origin}/checkout/return`);\n\n  checkout.addEventListener('banxa:checkout-success', () => { /* completed */ });\n  checkout.addEventListener('banxa:checkout-failure', () => { /* failed */ });\n  checkout.addEventListener('banxa:checkout-cancelled', () => { /* cancelled */ });\n</script>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"attributes","__idx":9},"children":["Attributes"]},{"$$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":"Attribute"},"children":["Attribute"]},{"$$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":["checkout-url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required. Hosted checkout URL from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createOrder"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["return-url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Redirect URL base used to detect success, failure, and cancel navigation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["return-url-success"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional override for success detection."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["return-url-failure"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional override for failure detection."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["return-url-cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional override for cancel detection."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iframe-title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Accessible iframe title (default: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Banxa checkout"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom-styles"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CSS injected into the shadow root."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"events","__idx":10},"children":["Events"]},{"$$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":"Event"},"children":["Event"]},{"$$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":["banxa:checkout-success"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The iframe navigated to the return success URL."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:checkout-failure"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The iframe navigated to the return failure URL."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:checkout-cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The iframe navigated to the return cancel URL."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For camera permissions during KYC, the embedding page must grant ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["camera"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["microphone"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/checkout-experience/iframe/webview-mobile"},"children":["Embedded Checkout, Mobile"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"eligibility-aware-buy-flow","__idx":11},"children":["Eligibility-aware buy flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["runBuyCheckoutFlow"]}," creates the order and mounts the right component automatically. For a Hosted Checkout integration this resolves to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<banxa-hosted-checkout>"]}," iframe."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { BanxaApiClient } from '@banxa-official/javascript-native-payments-sdk';\nimport { runBuyCheckoutFlow } from '@banxa-official/javascript-native-payments-sdk/web';\n\nconst client = new BanxaApiClient({ apiKey, partner, environment: 'sandbox' });\nconst container = document.getElementById('checkout');\n\nconst { mode, order, element } = await runBuyCheckoutFlow({\n  client,\n  request: {\n    externalCustomerId: 'user-123',\n    fiat: 'AUD',\n    crypto: 'USDT',\n    fiatAmount: '100',\n    walletAddress: '0xabc',\n    redirectUrl: `${window.location.origin}/checkout/return`,\n  },\n  container,\n});\n\nelement.addEventListener('banxa:checkout-success', () => { /* hosted iframe completed */ });\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," on your checkout page origin so the iframe can detect return navigation when Banxa redirects after KYC or payment."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quotes","__idx":12},"children":["Quotes"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const quote = await client.getQuote({\n  fiat: 'AUD',\n  crypto: 'USDT',\n  blockchain: 'TRON',\n  paymentMethodId: 'debit-credit-card',\n  fiatAmount: '100',\n}, 'buy');\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Maps to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /{partner}/v2/quotes/{orderType}"]},". Either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}," is required, along with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiat"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["crypto"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["blockchain"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethodId"]},". Quotes are indicative and carry no quote ID."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-methods-currencies-and-countries","__idx":13},"children":["Payment methods, currencies, and countries"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const paymentMethods = await client.getPaymentMethods('AUD', 'USDT', 'AU');\nconst currencies = await client.getCurrencies('buy');\nconst fiats = await client.getFiatCurrencies('buy');\nconst crypto = await client.getCryptoCurrencies('buy');\nconst countries = await client.getCountries();\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":14},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API failures throw ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BanxaApiError"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { BanxaApiClient, BanxaApiError } from '@banxa-official/javascript-native-payments-sdk';\n\ntry {\n  const order = await client.createOrder({ /* ... */ });\n} catch (error) {\n  if (error instanceof BanxaApiError) {\n    console.error('Status code:', error.statusCode);\n    console.error('Response body:', error.responseBody);\n    console.error('Errors:', error.errors);\n  } else {\n    console.error('Unknown error:', error);\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"banxaapierror-properties","__idx":15},"children":["BanxaApiError 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":["statusCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP status code from the API response."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["responseBody"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional raw response body."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional array of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BanxaApiErrorItem"]}," with per-field detail."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For error codes and their meanings, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/reference/error-codes"},"children":["Error Codes"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"native-payment-sheet-primer","__idx":16},"children":["Native payment sheet (Primer)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK also provides a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<banxa-primer-checkout>"]}," web component that renders a native payment sheet for card, Apple Pay, and Google Pay directly in your page, with no iframe. This is a Banxa Native feature 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":"not-available-in-the-sdk","__idx":17},"children":["Not available in the SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the following capabilities, use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/api-integration/api-integration-overview"},"children":["Banxa API"]}," directly:"]},{"$$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":"Reason"},"children":["Reason"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Alternative"},"children":["Alternative"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["KYC data sharing (Sumsub token share)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Requires HMAC authentication, which the SDK does not use"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/identity-compliance/kyc-sharing"},"children":["KYC Sharing"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full order list (all orders across all customers)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not exposed in the SDK"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /{partner}/v2/orders"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"typescript-support","__idx":18},"children":["TypeScript support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK is written in TypeScript and ships with type definitions for both entry points."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { BanxaApiClient } from '@banxa-official/javascript-native-payments-sdk';\nimport type { CreateOrderRequest, Order, Quote } from '@banxa-official/javascript-native-payments-sdk';\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"environment-urls","__idx":19},"children":["Environment URLs"]},{"$$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":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Base URL"},"children":["Base URL"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sandbox"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.banxa-sandbox.com/{partner}/v2"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Production"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.banxa.com/{partner}/v2"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":20},"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/javascript-native-payments-sdk-guide"},"children":["JS Native Payments SDK Integration Guide (Web)"]},": end-to-end walkthrough with code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/sdk-integration/overview"},"children":["SDK Integration Overview"]},": how the SDKs compare."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/api-integration/api-integration-overview"},"children":["Banxa API Reference"]},": for capabilities not in the SDK."]}]}]},"headings":[{"value":"JavaScript Native Payments SDK Reference","id":"javascript-native-payments-sdk-reference","depth":1},{"value":"Installation","id":"installation","depth":2},{"value":"Entry points","id":"entry-points","depth":2},{"value":"Creating an API client","id":"creating-an-api-client","depth":2},{"value":"Configuration options","id":"configuration-options","depth":3},{"value":"Buy","id":"buy","depth":2},{"value":"createOrder","id":"createorder","depth":3},{"value":"getOrder","id":"getorder","depth":3},{"value":"Hosted checkout component","id":"hosted-checkout-component","depth":2},{"value":"Attributes","id":"attributes","depth":3},{"value":"Events","id":"events","depth":3},{"value":"Eligibility-aware buy flow","id":"eligibility-aware-buy-flow","depth":2},{"value":"Quotes","id":"quotes","depth":2},{"value":"Payment methods, currencies, and countries","id":"payment-methods-currencies-and-countries","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"BanxaApiError properties","id":"banxaapierror-properties","depth":3},{"value":"Native payment sheet (Primer)","id":"native-payment-sheet-primer","depth":2},{"value":"Not available in the SDK","id":"not-available-in-the-sdk","depth":2},{"value":"TypeScript support","id":"typescript-support","depth":2},{"value":"Environment URLs","id":"environment-urls","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"JavaScript Native Payments SDK Reference | Banxa Docs","description":"Complete reference for the Banxa JavaScript Native Payments SDK: a TypeScript SDK for web that wraps the Banxa API and embeds Hosted Checkout in an iframe.","seo":{"title":"JavaScript Native Payments SDK Reference"}},"lastModified":"2026-08-20T06:59:29.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/hosted-checkout/docs/sdk-integration/javascript-native-payments-sdk-reference","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}