{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/hosted-checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Getting Access","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":"getting-access","__idx":0},"children":["Getting Access"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-you-get","__idx":1},"children":["What you get"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you begin your Banxa integration, you'll receive access to two things:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.banxa.com/"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Partner Dashboard"]}]}," — your self-service portal for configuring your integration, managing users, monitoring orders, and switching between environments."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sandbox environment"]}," — a fully functional test environment where you can build and validate your integration before going live. No real transactions are processed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your sandbox credentials are separate from production credentials. Production access is enabled by Banxa once you have completed testing and received approval."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No sandbox access yet? ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://banxa.com/talk-to-our-team/"},"children":["Talk to our team →"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"two-decisions-before-you-build","__idx":2},"children":["Two decisions before you build"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before writing any code, you need to make two independent decisions. Each one can be changed later, but will require rework."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"decision-1--checkout-display","__idx":3},"children":["Decision 1 — Checkout display"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["iFrame"]}," embeds the Banxa checkout flow directly inside your application. The customer never leaves your product."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Redirect"]}," opens the Banxa checkout in a new tab or browser window. Banxa hosts the page, which can be co-branded with your styling."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["→ See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/getting-started/choose-visualisation"},"children":["Checkout Visualisation: iFrame vs. Redirect"]}," for a full comparison."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"decision-2--integration-method","__idx":4},"children":["Decision 2 — Integration method"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API integration"]}," gives you full control. You call Banxa's APIs to fetch quotes, create orders, and receive webhook notifications. This approach supports KYC sharing and lets you build a quote experience within your own UI."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Referral integration"]}," is URL-based. You construct a Banxa URL with parameters and redirect the customer to it. No server-to-server calls required. Best for teams who want to move fast without backend complexity."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["React Native SDK"]}," wraps the API for mobile apps. Install a single package and call typed methods for quotes, orders, and checkout presentation — no backend required for core flows."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["→ See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/getting-started/choose-integration-method"},"children":["Integration Method: API vs. Referral vs. SDK"]}," for a full comparison."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"your-path-from-sandbox-to-production","__idx":5},"children":["Your path from sandbox to production"]},{"$$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":"Stage"},"children":["Stage"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What happens"},"children":["What happens"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sandbox access"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Banxa provides your sandbox credentials and dashboard access"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Dashboard setup"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configure webhooks, supported crypto/blockchains, and UI settings"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Build & integrate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Implement your chosen integration method and checkout visualisation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["End-to-end testing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Complete a full test purchase using sandbox test credentials"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Production launch"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Notify Banxa to enable your production environment and receive production credentials"]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Changes made in the dashboard take approximately 15 minutes to propagate to your integration."]}]}]},"headings":[{"value":"Getting Access","id":"getting-access","depth":1},{"value":"What you get","id":"what-you-get","depth":2},{"value":"Two decisions before you build","id":"two-decisions-before-you-build","depth":2},{"value":"Decision 1 — Checkout display","id":"decision-1--checkout-display","depth":3},{"value":"Decision 2 — Integration method","id":"decision-2--integration-method","depth":3},{"value":"Your path from sandbox to production","id":"your-path-from-sandbox-to-production","depth":2}],"frontmatter":{"title":"Sandbox Access & Integration Decisions | Banxa Docs","description":"Receive sandbox access and Partner Dashboard credentials. Understand the two decisions every Banxa integration starts with: checkout UI and backend method.","seo":{"title":"Getting Access"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/hosted-checkout/docs/getting-started/access-and-setup","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}