{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/hosted-checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Identity & Compliance — Overview","description":"Official Banxa API documentation – on-ramp and off-ramp transfers with identity verification and compliance.","llmstxt":{"title":"Banxa Developer Documentation","description":"Integrate crypto-fiat exchange with Banxa's licensed infrastructure: payments, KYC, compliance, and settlement handled. 150+ countries, 45 global licences.","details":{"content":"Two integration products: **Banxa Native API** for partners who manage their own KYC and want full UX control (headless, HMAC server-to-server, no Banxa-hosted screens); **Banxa Hosted Checkout** for partners who want Banxa to handle KYC and payments (three paths: Referral URL, API, or React Native SDK). Both use the same sandbox and production environments at `https://api.banxa-sandbox.com` and `https://api.banxa.com`.\n\n## Constraints\n\n- **Authentication**: HMAC credentials must be stored server-side only, never expose in frontend, mobile, or client-side code. HMAC is required for all Native API calls and for KYC sharing in Hosted Checkout; `x-api-key` is used for all other Hosted Checkout endpoints.\n- **`externalCustomerId`**: Required on every buy and sell order. Use a stable opaque identifier, never PII.\n- **`identityReference`**: Must remain constant for the same user across all requests. Must not contain PII. If you attempt to create an identity for an email that already exists, you will receive a 422 / code 81, so retrieve the existing record rather than retrying creation. Use `GET /eapi/v0/identities/{identityReference}?email=user@example.com` to look up the real `identityReference` linked to an email.\n- **`quoteId`**: Only supported by `POST /eapi/v0/ramps` (bank transfer). The React Native SDK and Embedded Payment Button do not accept a `quoteId`, so use indicative pricing (`GET /eapi/v0/price`) for SDK and Embedded Payment Button flows.\n- **Quotes**: Indicative prices are not rate-locked, so refresh close to order creation to minimise rate drift. Locked quotes (`GET /eapi/v0/quote`) expire after approximately 3 minutes and are only valid for bank transfer ramp creation.\n- **Eligibility gate**: Never create a ramp or invoke the SDK when `paymentReady` is `false`. Always check eligibility and satisfy all requirements before payment execution.\n- **Webhooks**: Verify all inbound webhook signatures with HMAC-SHA256 before processing. Return HTTP 200 immediately and process asynchronously.\n- **Product selection**: Banxa Native is for partners who manage their own KYC. Banxa Hosted Checkout is for partners who do not do KYC. These are separate products with separate flows: do not mix endpoints across products.\n- **SDK scope**: The React Native SDK has no `banxa.customerIdentity` module. Identity and KYC are handled through the Native API only. `primerCallbacks` and `primerSettings` are Native context only and must not be referenced in Hosted Checkout integrations.\n- **Payment method naming**: Never use \"eAPI\" or \"EAPI\" as a product name. The correct name is \"Banxa Native API\". The URL path prefix `/eapi/` is correct and should not be changed.\n"},"hide":false,"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"identity--compliance--overview","__idx":0},"children":["Identity & Compliance — Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Banxa is a regulated financial services provider. Every customer who transacts through Banxa must pass identity verification (KYC) and comply with anti-money laundering (AML) requirements. This happens automatically within the Banxa checkout flow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As an integration partner, you do not need to manage KYC — Banxa handles all identity verification, document collection, and regulatory compliance. However, there are optional ways to streamline the customer experience if you already collect identity information."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-kyc-works-in-the-checkout","__idx":1},"children":["How KYC works in the checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a customer enters the Banxa checkout for the first time, they will be asked to provide:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Personal details (name, date of birth, address)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Identity document (passport, driver's licence, or national ID)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In some cases, a liveness check (selfie video)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For returning customers, Banxa recognises them and may not require re-verification, depending on the transaction amount and jurisdiction."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verification-levels","__idx":2},"children":["Verification levels"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The level of verification required depends on the transaction amount and the customer's jurisdiction. Higher-value transactions require more thorough verification. Thresholds vary by jurisdiction and are not published — contact Banxa for details applicable to your markets."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["→ See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/identity-compliance/verification-flow-and-tiers"},"children":["Verification Flow"]}," for details on how the flow works."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"streamlining-kyc-for-your-customers","__idx":3},"children":["Streamlining KYC for your customers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your platform already collects and verifies customer identity, you can share that information with Banxa to reduce or eliminate the KYC steps your customers need to complete in the checkout."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TD\n A{Does your platform\\nverify customer identity?} -->|No| B[Banxa handles all KYC\\nin checkout — no action needed]\n A -->|Yes| C{Which KYC\\nprovider?}\n C -->|Sumsub| D[Sumsub token sharing\\nSee Sumsub Integration]\n C -->|Other or in-house| E[KYC data sharing\\nor contact Banxa]\n D --> F([Customer may skip KYC\\nin Banxa checkout])\n E --> F\n B --> G([Customer completes KYC\\nin Banxa checkout])\n","diagramHtml":"

No

Yes

Sumsub

Other or in-house

Does your platform
verify customer identity?

Banxa handles all KYC
in checkout — no action needed

Which KYC
provider?

Sumsub token sharing
See Sumsub Integration

KYC data sharing
or contact Banxa

Customer may skip KYC
in Banxa checkout

Customer completes KYC
in Banxa checkout

","diagramHtmlDark":"

No

Yes

Sumsub

Other or in-house

Does your platform
verify customer identity?

Banxa handles all KYC
in checkout — no action needed

Which KYC
provider?

Sumsub token sharing
See Sumsub Integration

KYC data sharing
or contact Banxa

Customer may skip KYC
in Banxa checkout

Customer completes KYC
in Banxa checkout

"},"children":["flowchart TD\n A{Does your platform\\nverify customer identity?} -->|No| B[Banxa handles all KYC\\nin checkout — no action needed]\n A -->|Yes| C{Which KYC\\nprovider?}\n C -->|Sumsub| D[Sumsub token sharing\\nSee Sumsub Integration]\n C -->|Other or in-house| E[KYC data sharing\\nor contact Banxa]\n D --> F([Customer may skip KYC\\nin Banxa checkout])\n E --> F\n B --> G([Customer completes KYC\\nin Banxa checkout])\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two ways to do this:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-kyc-data-sharing","__idx":4},"children":["1. KYC data sharing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pass customer identity data (name, address, document details) to Banxa before creating an order. This reduces the information the customer needs to re-enter."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-sumsub-token-sharing","__idx":5},"children":["2. Sumsub token sharing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your platform uses Sumsub for KYC, you can pass a Sumsub share token to Banxa. Banxa retrieves the customer's verification data directly from Sumsub — the customer may be able to skip KYC entirely."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["→ See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/identity-compliance/kyc-sharing"},"children":["KYC Sharing"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/identity-compliance/sumsub-integration"},"children":["Sumsub Integration"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites-for-kyc-sharing","__idx":6},"children":["Prerequisites for KYC sharing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["KYC sharing must be enabled for your partner account before you can use the identity endpoint. Contact Banxa to:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Complete the Banxa questionnaire to confirm solution fit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Receive approval and activation of the identity endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If using Sumsub: complete the token sharing agreement."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"customer-transparency","__idx":7},"children":["Customer transparency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When using KYC sharing, inform your customers that their personal details and KYC documents will be shared with Banxa. This prevents confusion if Banxa needs to contact the customer for additional documentation."]}]},"headings":[{"value":"Identity & Compliance — Overview","id":"identity--compliance--overview","depth":1},{"value":"How KYC works in the checkout","id":"how-kyc-works-in-the-checkout","depth":2},{"value":"Verification levels","id":"verification-levels","depth":2},{"value":"Streamlining KYC for your customers","id":"streamlining-kyc-for-your-customers","depth":2},{"value":"1. KYC data sharing","id":"1-kyc-data-sharing","depth":3},{"value":"2. Sumsub token sharing","id":"2-sumsub-token-sharing","depth":3},{"value":"Prerequisites for KYC sharing","id":"prerequisites-for-kyc-sharing","depth":2},{"value":"Customer transparency","id":"customer-transparency","depth":2}],"frontmatter":{"title":"KYC & Compliance Integration Overview | Banxa Docs","description":"Banxa handles KYC and AML compliance automatically in checkout. Optionally share verified customer identity to reduce friction and improve conversion rates.","seo":{"title":"Identity & Compliance — Overview"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/hosted-checkout/docs/identity-compliance/overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}