{"templateId":"markdown","versions":[{"version":"v0-beta","label":"Beta (v0)","link":"/products/native-api/docs/sdk/javascript-native-payments-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":"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## 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":"javascript-native-payments-sdk-reference","__idx":0},"children":["JavaScript Native Payments SDK Reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Banxa JavaScript Native Payments SDK is the payment execution layer of Banxa Native for web. It's the web counterpart to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/sdk/sdk-reference"},"children":["React Native SDK"]},": used alongside the Native API to present native card and wallet payments in the browser, 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 parts 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: the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<banxa-primer-checkout>"]}," web component renders the native payment sheet in your page, gated on the eligibility ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady"]}," flag."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The full API surface 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/javascript-native-payments-sdk\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For native payment checkout, install the Primer peer dependency:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npm install @primer-io/primer-js\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@primer-io/primer-js"]}," is an optional peer dependency, required only for the native checkout web component."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"entry-points","__idx":2},"children":["Entry points"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK ships 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":["registerBanxaPrimerCheckout"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["registerBanxaHostedCheckout"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["runBuyCheckoutFlow"]},", checkout and Primer 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":"Heading","attributes":{"level":2,"id":"creating-an-api-client","__idx":3},"children":["Creating an API client"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BanxaApiClient"]}," is Node-safe and handles all Banxa API requests from your backend."]},{"$$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 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":["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":"Heading","attributes":{"level":2,"id":"backend-create-an-order","__idx":5},"children":["Backend: create an order"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a buy order from your backend, then return the payment token to your frontend."]},{"$$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  paymentMethodId: 'debit-credit-card', // optional\n  blockchain: 'TRON', // optional\n});\n\n// Native payments: pass this token to the checkout web component\nconst nativeToken = order.nativeToken;\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createOrder"]}," maps to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/buy"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"createorderrequest","__idx":6},"children":["CreateOrderRequest"]},{"$$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":"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":["externalCustomerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your customer reference. Use the same value across identity and eligibility flows."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiat"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fiat currency code (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["crypto"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Crypto currency code (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USDT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BTC"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["walletAddress"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer wallet address."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URL the customer returns to after checkout completes, fails, or is cancelled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One of"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fiat amount to buy."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One of"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Crypto amount to buy."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethodId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pre-select a payment method (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["debit-credit-card"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["blockchain"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blockchain network for the crypto token."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["walletAddressTag"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Memo or tag for wallets that require it."]}]},{"$$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":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your order reference."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discountCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Promotion or discount code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pre-fill the customer email."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Opaque string returned on order lookup."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subPartnerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Channel identifier (exchange, wallet, web, and so on)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pricing is indicative. The SDK does not accept a locked ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]},", so re-quote close to order creation to minimise rate drift."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"order-response","__idx":7},"children":["Order response"]},{"$$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":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Banxa order ID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nativeToken"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Primer client token for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<banxa-primer-checkout>"]}," (native payments)."]}]},{"$$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":["Hosted checkout URL, used for the fallback flow when native payments are not available."]}]},{"$$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 amounts and assets."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer and external references."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"backend-check-eligibility","__idx":8},"children":["Backend: check eligibility"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check whether an order can proceed before presenting the native payment sheet. The response's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady"]}," field determines whether to render native Primer checkout or fall back to hosted checkout."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const eligibility = await client.checkOrderEligibility({\n  externalCustomerId: 'user-123',\n  fiat: 'AUD',\n  crypto: 'USDT',\n  fiatAmount: '100',\n  walletAddress: '0x1234567890abcdef...',\n  redirectUrl: 'https://yoursite.com/order-complete',\n}, 'buy');\n\nif (eligibility.paymentReady) {\n  // safe to render native Primer checkout\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkOrderEligibility"]}," maps to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eligibility"]}," and takes the same body as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createOrder"]}," plus the order type."]},{"$$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":["eligible"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether the order context is eligible."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", the customer can use native Primer checkout."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requirements"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Outstanding KYC or compliance requirements when not payment-ready."]}]},{"$$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":["Optional human-readable detail."]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady"]}," to choose between native Primer checkout and the hosted fallback. Do not rely on other fields for gating."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"frontend-native-payment-checkout","__idx":9},"children":["Frontend: native payment checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<banxa-primer-checkout>"]}," web component renders the native payment sheet in your page. No redirect, no Banxa-hosted screen."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<script type=\"module\">\n  import { registerBanxaPrimerCheckout } from '@banxa-official/javascript-native-payments-sdk/web';\n\n  registerBanxaPrimerCheckout();\n</script>\n\n<banxa-primer-checkout id=\"checkout\" locale=\"en\"></banxa-primer-checkout>\n\n<script type=\"module\">\n  const response = await fetch('/api/create-order', { method: 'POST' });\n  const { nativeToken } = await response.json();\n\n  const checkout = document.getElementById('checkout');\n  checkout.clientToken = nativeToken;\n\n  checkout.addEventListener('banxa:payment-success', (event) => {\n    console.log('Payment successful', event.detail);\n  });\n\n  checkout.addEventListener('banxa:payment-failure', (event) => {\n    console.error('Payment failed', event.detail);\n  });\n</script>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set the token via the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientToken"]}," property (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client-token"]}," attribute) after your backend returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nativeToken"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createOrder"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"attributes","__idx":10},"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":["client-token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required. Primer client token (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.nativeToken"]}," 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":["locale"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Locale string (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["layout-mode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preset"]}," (default), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auto"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment-methods"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Comma-separated Primer types for preset mode (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_CARD,APPLE_PAY"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loader-disabled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Disable the loading placeholder."]}]},{"$$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 string injected into the component shadow root."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"properties","__idx":11},"children":["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":["clientToken"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get or set the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client-token"]}," attribute."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locale"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get or set the locale."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["layoutMode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get or set the layout mode."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethods"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get or set the preset payment methods."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutLayout"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Programmatic ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutLayoutConfig"]},", merged with attributes."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutTemplate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Raw HTML for custom layout mode."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loaderDisabled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get or set the loading placeholder."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customStyles"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get or set custom CSS."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"methods","__idx":12},"children":["Methods"]},{"$$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":"Method"},"children":["Method"]},{"$$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":["refreshSession()"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delegates to the Primer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refreshSession()"]}," when available."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"events","__idx":13},"children":["Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Primer events are re-emitted on the host element with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:"]}," prefix. Use native ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addEventListener"]},"."]},{"$$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:ready"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Checkout ready."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:payment-start"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment started."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:payment-success"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment succeeded."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:payment-failure"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment failed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:payment-cancel"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment cancelled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:state-change"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Primer SDK state changed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:methods-update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Available payment methods updated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:card-success"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:card-error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Card validation events."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:bin-data-available"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:bin-data-loading-change"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Card BIN lookup events."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout-error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The SDK failed to load or initialise (not prefixed)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Event ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}," objects are sanitised for JSON serialisation: DOM nodes and circular references are replaced with string placeholders."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"layout-modes","__idx":14},"children":["Layout modes"]},{"$$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":"Mode"},"children":["Mode"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Behaviour"},"children":["Behaviour"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preset"]}," (default)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Builds markup from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethods"]}," (default: card plus Apple Pay). Card payments use a standalone Primer card form with slotted fields."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auto"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Omits the payments slot so Primer renders all session payment methods."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutTemplate"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutLayout.mainHtml"]},", or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<template slot=\"checkout-layout\">"]}," child for full control."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Custom card forms must use Primer hosted input components only. Raw HTML inputs cannot host PCI card data. In preset mode a custom ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardFormHtml"]}," is ignored with a console warning; use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom"]}," layout mode or the checkout-layout slot instead."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { registerBanxaPrimerCheckout, PrimerPaymentMethodTypes } from '@banxa-official/javascript-native-payments-sdk/web';\n\nregisterBanxaPrimerCheckout();\n\nconst checkout = document.querySelector('banxa-primer-checkout');\ncheckout.checkoutLayout = {\n  mode: 'preset',\n  paymentMethods: [\n    { type: PrimerPaymentMethodTypes.PAYMENT_CARD },\n    { type: PrimerPaymentMethodTypes.APPLE_PAY },\n  ],\n};\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"eligibility-aware-buy-flow","__idx":15},"children":["Eligibility-aware buy flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["runBuyCheckoutFlow"]}," checks eligibility, creates the order, and selects the right UI automatically: native Primer checkout when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", or the hosted fallback when it isn't."]},{"$$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    paymentMethodId: 'debit-credit-card',\n  },\n  container,\n});\n\nif (mode === 'primer') {\n  element.addEventListener('banxa:payment-success', () => { /* ... */ });\n} else {\n  element.addEventListener('banxa:checkout-success', () => { /* hosted fallback completed */ });\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":"paymentReady"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"nativeToken"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nativeToken"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Result"},"children":["Result"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["present"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<banxa-primer-checkout>"]}," (native payment sheet)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," or no token"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}," present"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<banxa-hosted-checkout>"]}," (hosted fallback iframe)"]}]}]}]}]},{"$$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":"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":["skipEligibilityCheck"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Skip the eligibility call and assume payment-ready."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primerCheckoutOptions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pass-through for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locale"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["layoutMode"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutLayout"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutTemplate"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loaderDisabled"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customStyles"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," on your checkout page origin so the fallback iframe can detect return navigation after payment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quotes","__idx":16},"children":["Quotes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve indicative pricing."]},{"$$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":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getQuote"]}," 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"]}," 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"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-methods-currencies-and-countries","__idx":17},"children":["Payment methods, currencies, and countries"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// Payment methods, optionally filtered by source, target, and country\nconst paymentMethods = await client.getPaymentMethods('AUD', 'USDT', 'AU');\n\n// Currencies (default order type is 'buy')\nconst currencies = await client.getCurrencies('buy');\nconst fiats = await client.getFiatCurrencies('buy');\nconst crypto = await client.getCryptoCurrencies('buy');\n\n// Countries\nconst countries = await client.getCountries();\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retrieve-an-order","__idx":18},"children":["Retrieve an order"]},{"$$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":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getOrder"]}," maps to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /orders/{orderId}"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":19},"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":20},"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":["Show user-facing messages only from validated error fields. Do not expose raw error strings that may include internal detail."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"typescript-support","__idx":21},"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":"Heading","attributes":{"level":2,"id":"environment-urls","__idx":22},"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"]}]}]}]}]}]}]},"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":"Backend: create an order","id":"backend-create-an-order","depth":2},{"value":"CreateOrderRequest","id":"createorderrequest","depth":3},{"value":"Order response","id":"order-response","depth":3},{"value":"Backend: check eligibility","id":"backend-check-eligibility","depth":2},{"value":"Frontend: native payment checkout","id":"frontend-native-payment-checkout","depth":2},{"value":"Attributes","id":"attributes","depth":3},{"value":"Properties","id":"properties","depth":3},{"value":"Methods","id":"methods","depth":3},{"value":"Events","id":"events","depth":3},{"value":"Layout modes","id":"layout-modes","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":"Retrieve an order","id":"retrieve-an-order","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"BanxaApiError properties","id":"banxaapierror-properties","depth":3},{"value":"TypeScript support","id":"typescript-support","depth":2},{"value":"Environment URLs","id":"environment-urls","depth":2}],"frontmatter":{"title":"JavaScript Native Payments SDK Reference","description":"Complete reference for the Banxa JavaScript Native Payments SDK, the web payment execution layer for Banxa Native, configuration, API client, web components, and error handling.","seo":{"title":"JavaScript Native Payments SDK Reference"}},"lastModified":"2026-07-08T07:23:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/native-api/docs/sdk/javascript-native-payments-sdk-reference","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}