{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/hosted-checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"KYC Sharing","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":"kyc-sharing","__idx":0},"children":["KYC Sharing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your platform uses Sumsub for identity verification, you can share the customer's verified KYC data with Banxa before they enter checkout. Banxa retrieves the data directly from Sumsub — reducing or eliminating the verification steps the customer needs to complete in the Banxa checkout."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your platform uses Sumsub for identity verification."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The identity endpoint must be enabled for your account (requires Banxa approval)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have completed the Sumsub token sharing agreement with Banxa."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Only share data for customers who have ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["already been KYC verified"]}," on your platform."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":2},"children":["How it works"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant P as Partner Platform\n participant B as Banxa Identity API\n participant S as Sumsub\n participant C as Customer\n\n Note over P,C: At KYC verification time (recommended)\n C->>P: Completes KYC on partner platform\n P->>S: Generate share token
(clientId: banxa.com_5335)\n S-->>P: Share token\n P->>B: POST /v2/identities/token/share
{externalCustomerId, provider.token, ...}\n B-->>P: 202 Accepted\n\n Note over P,C: When customer initiates a transaction\n C->>P: Initiates buy or sell\n P->>B: POST /v2/buy or /v2/sell\n B-->>P: checkoutUrl\n P->>C: Redirect to checkoutUrl\n C->>B: Enters Banxa checkout\n B->>S: Retrieve KYC data using stored token\n S-->>B: Customer KYC data\n B->>C: Checkout with KYC pre-filled\n","diagramHtml":"CustomerSumsubBanxa Identity APIPartner PlatformCustomerSumsubBanxa Identity APIPartner PlatformAt KYC verification time (recommended)When customer initiates a transactionCompletes KYC on partner platformGenerate share token(clientId: banxa.com_5335)Share tokenPOST /v2/identities/token/share{externalCustomerId, provider.token, ...}202 AcceptedInitiates buy or sellPOST /v2/buy or /v2/sellcheckoutUrlRedirect to checkoutUrlEnters Banxa checkoutRetrieve KYC data using stored tokenCustomer KYC dataCheckout with KYC pre-filled","diagramHtmlDark":"CustomerSumsubBanxa Identity APIPartner PlatformCustomerSumsubBanxa Identity APIPartner PlatformAt KYC verification time (recommended)When customer initiates a transactionCompletes KYC on partner platformGenerate share token(clientId: banxa.com_5335)Share tokenPOST /v2/identities/token/share{externalCustomerId, provider.token, ...}202 AcceptedInitiates buy or sellPOST /v2/buy or /v2/sellcheckoutUrlRedirect to checkoutUrlEnters Banxa checkoutRetrieve KYC data using stored tokenCustomer KYC dataCheckout with KYC pre-filled"},"children":["sequenceDiagram\n participant P as Partner Platform\n participant B as Banxa Identity API\n participant S as Sumsub\n participant C as Customer\n\n Note over P,C: At KYC verification time (recommended)\n C->>P: Completes KYC on partner platform\n P->>S: Generate share token
(clientId: banxa.com_5335)\n S-->>P: Share token\n P->>B: POST /v2/identities/token/share
{externalCustomerId, provider.token, ...}\n B-->>P: 202 Accepted\n\n Note over P,C: When customer initiates a transaction\n C->>P: Initiates buy or sell\n P->>B: POST /v2/buy or /v2/sell\n B-->>P: checkoutUrl\n P->>C: Redirect to checkoutUrl\n C->>B: Enters Banxa checkout\n B->>S: Retrieve KYC data using stored token\n S-->>B: Customer KYC data\n B->>C: Checkout with KYC pre-filled\n"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When a customer is KYC-verified on your platform, generate a Sumsub share token using Banxa's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]}," and call the Banxa identity endpoint. Do this at verification time — not at order creation, as the data may not be processed in time for the customer's session."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Banxa stores the token and associates it with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When the customer enters the Banxa checkout, Banxa retrieves their KYC data from Sumsub. Their details are pre-populated and some verification steps may be skipped."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Banxa still performs its own KYC due diligence. Additional information may be requested if required by compliance processes."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["→ See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/identity-compliance/sumsub-integration"},"children":["Sumsub Integration"]}," for how to generate the share token and for details on Copy Applicant, which extracts a fuller profile including address and TIN."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"endpoint","__idx":3},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /{partnerRef}/v2/identities/token/share\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint uses ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HMAC authentication"]},", not the standard ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header. HMAC signing must be done server-side — never embed your API secret in frontend or mobile code."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/getting-started/authentication-and-environments"},"children":["Authentication & Environments"]}," for the signing algorithm, code examples, and error codes."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-body","__idx":4},"children":["Request body"]},{"$$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":"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":["externalCustomerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your stable customer identifier. Must match the value used in order creation."]}]},{"$$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":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer's email address."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mobileNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer's mobile number including country code (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+61412345678"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["provider.vendor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sumsub"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["provider.token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Sumsub share token generated using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId: banxa.com_5335"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-request","__idx":5},"children":["Example request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.banxa-sandbox.com/{partnerRef}/v2/identities/token/share\" \\\n -H \"Authorization: Bearer API_KEY:SIGNATURE:NONCE\" \\\n -H \"Accept: application/json\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"externalCustomerId\": \"user_12345\",\n \"mobileNumber\": \"+61412345678\",\n \"email\": \"customer@example.com\",\n \"provider\": {\n \"vendor\": \"sumsub\",\n \"token\": \"_act-sbx-jwt-eyJhbGciOiJub25lIn0...\"\n }\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response","__idx":6},"children":["Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["202 Accepted"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"externalCustomerId\": \"user_12345\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}," response confirms Banxa has received and queued the identity data for processing. It does not guarantee immediate availability in the checkout."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"important-notes","__idx":7},"children":["Important notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}," must be the same value used in order creation. Using different values for the same customer creates separate identities in the Banxa system."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Banxa may still collect additional information from the customer during checkout if required by compliance processes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Only submit data for verified customers. Do not pass unverified or provisional data."]}]}]},"headings":[{"value":"KYC Sharing","id":"kyc-sharing","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Endpoint","id":"endpoint","depth":2},{"value":"Request body","id":"request-body","depth":2},{"value":"Example request","id":"example-request","depth":2},{"value":"Response","id":"response","depth":2},{"value":"Important notes","id":"important-notes","depth":2}],"frontmatter":{"title":"KYC Sharing via Sumsub | Banxa Docs","description":"Share Sumsub KYC verification data with Banxa before checkout using POST /v2/identities/token/share. Requires HMAC auth. Full request body reference.","seo":{"title":"KYC Sharing"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/hosted-checkout/docs/identity-compliance/kyc-sharing","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}