{"templateId":"markdown","versions":[{"version":"v0-beta","label":"Beta (v0)","link":"/products/native-api/docs/how-it-works/standalone-kyc","default":true,"active":true,"folderId":"e4cb5a06"}],"sharedDataIds":{"sidebar":"sidebar-products/native-api/@v0-beta/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Standalone KYC | Banxa Native API","siteUrl":"https://docs.banxa.com","description":"Have Banxa verify a customer in Banxa-hosted identity screens before any order, then take payment with Banxa Native in your own UI.","image":"https://docs.banxa.com/images/social/docs.png","meta":[{"name":"twitter:card","content":"summary_large_image"}],"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, chosen by how much of the payment experience the partner owns: **Banxa Native API** for payments that happen inside the partner's product (headless bank transfers, HMAC server-to-server; card, Apple Pay and Google Pay on a native sheet via SDK, no Banxa-hosted screens); **Banxa Hosted Checkout** for a Banxa-run payment flow with the broadest payment method coverage (three paths: Referral URL, API, or SDK). Either product can run KYC on either side. Both use the same sandbox and production environments at `https://api.banxa-sandbox.com` and `https://api.banxa.com`.\n\n## When to use Banxa\n\nReach for Banxa when a product needs to let people **buy crypto with fiat or sell crypto for fiat** without the partner holding money-transmitter or VASP licences. Banxa is the licensed counterparty: it takes the payment, runs compliance, and delivers the asset. Typical fits are wallets, exchanges, dApps, gaming platforms and fintech apps adding an on-ramp or off-ramp.\n\nPick the product by how much of the payment experience the partner wants to own. KYC is configurable on both and does not decide it.\n\n- **Banxa Native API** - the payment experience lives inside the partner's product. Bank transfers run completely headless through the API; card, Apple Pay and Google Pay run on a native payment sheet through a Banxa SDK, with no redirect or webview. Needs a backend. Days to weeks to integrate.\n- **Banxa Hosted Checkout** - Banxa runs the payment flow, reached by redirect, embedded iFrame, or SDK. Broadest payment method coverage. No backend required for the referral path. Hours to days to integrate.\n- **Alternative payment methods** (PayPal, iDEAL, Klarna, PIX, VietQR and local methods) are not supported headless. Native integrations offer them by creating those orders through Hosted Checkout, so most Native integrations use both products.\n- **Legacy API** - existing integrations only. Do not start here.\n\nBanxa is not the right tool for crypto-to-crypto swaps, custody or wallet infrastructure, or for any flow where the partner wants to settle funds itself.\n\n## Constraints\n\n- **Authentication**: HMAC credentials must be stored server-side only, never expose in frontend, mobile, or client-side code. HMAC is required for all Native API calls and for KYC sharing in Hosted Checkout; `x-api-key` is used for all other Hosted Checkout endpoints.\n- **`externalCustomerId`**: Required on every buy and sell order. Use a stable opaque identifier, never PII.\n- **`identityReference`**: Must remain constant for the same user across all requests. Must not contain PII. If you attempt to create an identity for an email that already exists, you will receive a 422 / code 81, so retrieve the existing record rather than retrying creation. Use `GET /eapi/v0/identities/{identityReference}?email=user@example.com` to look up the real `identityReference` linked to an email.\n- **`quoteId`**: Only supported by `POST /eapi/v0/ramps` (bank transfer). The React Native SDK and Embedded Payment Button do not accept a `quoteId`, so use indicative pricing (`GET /eapi/v0/price`) for SDK and Embedded Payment Button flows.\n- **Quotes**: Indicative prices are not rate-locked, so refresh close to order creation to minimise rate drift. Locked quotes (`GET /eapi/v0/quote`) expire after approximately 3 minutes and are only valid for bank transfer ramp creation.\n- **Eligibility gate**: Never create a ramp or invoke the SDK when `paymentReady` is `false`. Always check eligibility and satisfy all requirements before payment execution.\n- **Webhooks**: Verify all inbound webhook signatures with HMAC-SHA256 before processing. Return HTTP 200 immediately and process asynchronously.\n- **Product selection**: Choose by payment experience, not by KYC — both products support partner-run or Banxa-run KYC. Banxa Native is for payments rendered inside the partner's product; Banxa Hosted Checkout is for a Banxa-run payment flow. They are separate surfaces with separate credentials and base paths, so never substitute one product's endpoint for the other's. Combining them is expected in one case only: alternative payment methods are not supported headless, so a Native integration creates those specific orders through Hosted Checkout.\n- **SDK scope**: The React Native SDK has no `banxa.customerIdentity` module. Identity and KYC are handled through the Native API only. `primerCallbacks` and `primerSettings` are Native context only and must not be referenced in Hosted Checkout integrations.\n- **Payment method naming**: Never use \"eAPI\" or \"EAPI\" as a product name. The correct name is \"Banxa Native API\". The URL path prefix `/eapi/` is correct and should not be changed.\n"}}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"standalone-kyc","__idx":0},"children":["Standalone KYC"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the complete documentation index, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/llms.txt"},"children":["llms.txt"]},". Append ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".md"]}," to any page URL for its markdown version."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Standalone KYC lets Banxa verify a customer's identity ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["before"]}," they place an order. The customer completes verification in Banxa-hosted identity screens, which you show in an iframe or webview, or by redirecting the customer. Once the customer is verified, eligibility returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady: true"]}," and you take payment with Banxa Native, in your own UI."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Standalone KYC if you don't run your own KYC and don't want to build document, selfie, and liveness capture yourself."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Standalone KYC vs Quick start"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/guides/foundations"},"children":["Integration Guide"]},"'s Quick start path, Banxa may route a user into a hosted WebView ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["during checkout"]},", after an order is created. Standalone KYC runs ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["before"]}," any order, so the checkout itself stays fully native."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":1},"children":["Before you start"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Standalone KYC enabled for your account."]}," Contact your Banxa integration manager. Until it's enabled, session requests return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["KYC webhooks enabled."]}," The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/transaction-lifecycle/webhooks#3-kyc-webhooks"},"children":["KYC webhook"]}," is how you learn the verification result. Ask your Banxa integration manager to confirm it's on for your account."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["How you'll show the flow."]}," Tell Banxa whether you'll use an iframe, a webview, or a redirect, so your account is set up to send the right ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#completion-signals"},"children":["completion signal"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Two sets of API credentials."]}," Standalone KYC uses two Banxa APIs, so you need both:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Native API"]}," HMAC key and secret, for eligibility and ramps"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hosted Checkout API key"]},", sent in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header, for the session endpoint ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /{partnerRef}/v2/kyc/sessions"]},". It's the same key and partner reference you initialise the Banxa payment SDKs with."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you don't have a Hosted Checkout API key, contact your Banxa integration manager."]}]}]},{"$$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 App as Your app\n participant BE as Your backend\n participant Banxa\n BE->>Banxa: POST /{partnerRef}/v2/kyc/sessions\n Banxa-->>BE: 201 redirectUrl, expiresAt\n BE-->>App: redirectUrl\n App->>Banxa: Show redirectUrl (iframe, webview, or redirect)\n Note over App,Banxa: Customer enters email and country, then completes the identity steps\n Banxa-->>App: banxa:kyc-complete message or redirect to returnUrl\n Banxa-->>BE: KYC webhook (kyc.status)\n BE->>Banxa: POST /eapi/v0/identities/transactions/eligibility\n Banxa-->>BE: paymentReady: true\n","diagramHtml":"","diagramHtmlDark":""},"children":["sequenceDiagram\n participant App as Your app\n participant BE as Your backend\n participant Banxa\n BE->>Banxa: POST /{partnerRef}/v2/kyc/sessions\n Banxa-->>BE: 201 redirectUrl, expiresAt\n BE-->>App: redirectUrl\n App->>Banxa: Show redirectUrl (iframe, webview, or redirect)\n Note over App,Banxa: Customer enters email and country, then completes the identity steps\n Banxa-->>App: banxa:kyc-complete message or redirect to returnUrl\n Banxa-->>BE: KYC webhook (kyc.status)\n BE->>Banxa: POST /eapi/v0/identities/transactions/eligibility\n Banxa-->>BE: paymentReady: true\n"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your backend creates a session, passing the user's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}," as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Banxa returns a link and its expiry. The link is valid for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["1 hour"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You show the link to the customer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer enters their email and country (and an email one-time code, if that's enabled for your account). They then complete only the identity steps their verification level needs and that they haven't already completed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When nothing is left to collect, the customer sees ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["\"Your account is under review\""]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your app receives a completion signal. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["This means the customer finished, not that they passed."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Banxa sends a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/transaction-lifecycle/webhooks#3-kyc-webhooks"},"children":["KYC webhook"]}," when the result is known."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/how-it-works/interpreting-eligibility"},"children":["eligibility"]},". If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", continue with your payment method guide."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-your-identityreference-as-externalcustomerid","__idx":3},"children":["Use your identityReference as externalCustomerId"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}," are the same identifier. Pass the user's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}," as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]},", so the verification attaches to the identity you check eligibility against. The KYC webhook returns the same value as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity_reference"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If no identity exists yet for that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]},", creating the session creates one."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"The email the customer enters decides the identity"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Banxa matches the customer by the email they enter in the hosted screens. If that email belongs to a different Banxa customer than the one your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}," currently points to, your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}," moves to that customer. Eligibility then reflects that customer, not the one you created earlier."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure the customer uses the same email you used when you created the identity. If a customer you know is verified comes back as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady: false"]},", check whether they used a different email."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-session","__idx":4},"children":["Create a session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint uses your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hosted Checkout API key"]},", not HMAC. Create sessions ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["from your backend"]},", so the key never ships in your app or web page."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /{partnerRef}/v2/kyc/sessions\nx-api-key: YOUR_HOSTED_CHECKOUT_API_KEY\nContent-Type: application/json\n\n{\n \"externalCustomerId\": \"partner-abc123\",\n \"country\": \"AU\",\n \"tier\": \"standard\",\n \"returnUrl\": \"https://yourapp.com/kyc/done\"\n}\n","lang":"http"},"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":"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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}," for the user. Up to 255 characters. Longer values are rejected, not truncated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The customer's country of residence, as a 2-letter ISO 3166-1 code. The hosted screens still ask the customer for their country. Banxa saves a country only if the customer doesn't already have one, so whichever arrives first, yours or the customer's, is the one that's kept."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tier"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["standard"]}," (default), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enhanced"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["express"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#verification-levels"},"children":["Verification levels"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https"]}," URL or an app deep link, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["myapp://kyc-done"]},". Where the customer goes when they finish. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#completion-signals"},"children":["Completion signals"]},". If you leave it out, the default return URL set for your account in the Merchant Dashboard is used, if there is one."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"redirectUrl\": \"https://...\",\n \"expiresAt\": \"2026-08-21T08:10:00+00:00\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Repeat calls are safe."]}," If you call again for the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}," while the link is still valid, you get the same link and expiry back. A new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tier"]}," takes effect the next time the customer loads a screen. A new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}," is only used if the customer doesn't have one yet. A new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]}," only takes effect once the current link expires and you create a new one."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Errors"]}]},{"$$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":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid Hosted Checkout API key, or the key doesn't belong to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{partnerRef}"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Standalone KYC isn't enabled for your account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A field failed validation, for example an unsupported ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tier"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Temporary upstream error. Retry with backoff."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/openapi"},"children":["API reference"]}," for the full schema."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verification-levels","__idx":5},"children":["Verification levels"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You request a level with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tier"]},". Banxa combines it with the customer's country to decide exactly what to collect. Banxa's compliance team sets these requirements, and they can change."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["standard"]}]}," (default): personal details, an ID document, and a selfie with a liveness check, plus any region-specific items such as a tax ID, purpose of transaction, or occupation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enhanced"]}]},": everything in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["standard"]},", plus further items such as source of funds or proof of address, depending on the region."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["express"]}]},": personal details only, plus a tax ID in some regions. No ID document or selfie. Express must be enabled by Banxa for your account and for each country, and it isn't available in every country. If express isn't available, the customer gets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["standard"]}," and you don't receive an error. Banxa always falls back to more verification, never less."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the customer's country isn't covered by a regional level, they get a catch-all level that asks for more than most regions. Customers in some regions may also be asked to complete a cooling-off period before their first order."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Whichever level you request, always rely on ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/how-it-works/interpreting-eligibility"},"children":["eligibility"]}," to decide whether a specific transaction can proceed."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"show-the-flow","__idx":6},"children":["Show the flow"]},{"$$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":"How you show it"},"children":["How you show it"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What you do"},"children":["What you do"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Completion signal"},"children":["Completion signal"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["iframe"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Embed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," in an iframe with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allow=\"camera; microphone\""]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postMessage"]}," to your page"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webview"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Load ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," in a webview with camera and microphone access."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Redirect to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Redirect"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send the browser to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Redirect to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Banxa doesn't close the iframe or webview. Close it yourself after the completion signal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#using-the-banxa-sdks"},"children":["Banxa SDKs"]}," handle the webview, camera and microphone setup, and the completion signal for you."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"completion-signals","__idx":7},"children":["Completion signals"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["iframe:"]}," Banxa posts these messages to your page with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postMessage"]},". These are the only messages the iframe sends."]},{"$$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":"type"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Payload"},"children":["Payload"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When"},"children":["When"]}]}]},{"$$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:loading"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"type\": \"banxa:loading\", \"status\": \"loading\" }"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The flow is loading"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"type\": \"banxa:error\", \"code\": \"...\", \"message\": \"...\" }"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Something went wrong. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," describe the error"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:kyc-complete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"type\": \"banxa:kyc-complete\", \"status\": \"complete\" }"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The customer reached the end of the flow"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:kyc-complete"]}," payload is always the same. It never says whether the customer passed. Only accept messages whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event.origin"]}," matches the origin of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]},". Banxa needs to enable embedded mode for your account and register your page's domain. Without embedded mode, the iframe sends no messages at all."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Banxa SDKs report a few more events of their own, such as KYC errors and rejected messages. See your ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#using-the-banxa-sdks"},"children":["SDK reference"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webview or redirect:"]}," when the customer finishes, they see the \"Your account is under review\" screen. If auto-redirect is enabled for your account, they're sent to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]}," straight away. Otherwise, the screen shows a \"Return to [your name]\" button that takes them there. If you didn't send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]},", your account's default return URL is used instead. With neither set, the customer stays on the under-review screen."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-the-result","__idx":8},"children":["Get the result"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The \"under review\" screen and the completion signal don't tell you the outcome. Use:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The KYC webhook."]}," Banxa sends it when the customer's verification status changes. It identifies the customer with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity_reference"]}," and carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kyc.status"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/transaction-lifecycle/webhooks#3-kyc-webhooks"},"children":["KYC webhooks"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Eligibility."]}," Before creating a ramp, call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eapi/v0/identities/transactions/eligibility"]}," with the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]},". Proceed only when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"No status endpoint"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At the moment there's no endpoint to query a Standalone KYC result, and no session status endpoint. Don't call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /eapi/v0/identities/{identityReference}"]}," to get the status of a Standalone KYC verification. Use the KYC webhook and eligibility only."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"using-the-banxa-sdks","__idx":9},"children":["Using the Banxa SDKs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Banxa SDKs can show a Standalone KYC session and report when the customer finishes. Create the session on your backend and pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," to your app, then use your SDK's KYC view:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/sdk/sdk-reference#standalone-kyc"},"children":["React Native SDK"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/sdk/ios-sdk-reference#standalone-kyc"},"children":["iOS SDK"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/sdk/android-sdk-reference#standalone-kyc"},"children":["Android SDK"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/sdk/flutter-sdk-reference#standalone-kyc"},"children":["Flutter SDK"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/sdk/javascript-native-payments-sdk-reference#standalone-kyc"},"children":["JS Native Payments SDK"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDKs don't poll for a result. Their completion callback means the customer finished, not that they passed. Wait for the KYC webhook or check eligibility before creating an order."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"testing-in-sandbox","__idx":10},"children":["Testing in sandbox"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the sandbox base URL: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.banxa-sandbox.com/{partnerRef}/v2/kyc/sessions"]},". In production, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.banxa.com"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["new email address for each test customer"]},". If you reuse an email, Banxa treats the session as that existing customer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test the document and selfie steps on a real device. Simulators don't provide a real camera."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you use an iframe, check that you receive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa:kyc-complete"]}," exactly once."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":11},"children":["Troubleshooting"]},{"$$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":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Likely cause"},"children":["Likely cause"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to do"},"children":["What to do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," when creating a session"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or wrong ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{partnerRef}"]}," doesn't match the account the key belongs to"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use your Hosted Checkout API key (not your Native API HMAC credentials) and the matching partner reference"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," when creating a session"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Standalone KYC isn't enabled for your account"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask your Banxa integration manager to enable it"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," when creating a session"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A field failed validation, for example an unsupported ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tier"]},", or an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}," longer than 255 characters"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix the field named in the error response"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The link has expired"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Links last 1 hour"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a session again for the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}," to get a new link. The customer isn't asked again for anything they've already completed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The camera doesn't work during the document or selfie step"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The iframe or webview has no camera or microphone access"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["iframe: add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allow=\"camera; microphone\""]},". Webview or app: grant camera and microphone permissions. See your ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#using-the-banxa-sdks"},"children":["SDK reference"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Nothing happens in your app when the customer finishes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The completion signal isn't set up for how you show the flow"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["iframe: ask Banxa to enable embedded mode for your domain. Webview or redirect: send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]},", and ask Banxa to enable auto-redirect so the customer doesn't have to tap Return"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No KYC webhook arrives"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["KYC webhooks or your webhook URL aren't set up for your account"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask your Banxa integration manager to enable KYC webhooks and confirm your webhook URL"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Eligibility returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady: false"]}," right after the customer finished"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Completion only means the customer finished, not that they passed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wait for the KYC webhook, then check eligibility again"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You requested ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["express"]},", but the customer got the full document and selfie check"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Express isn't enabled for your account in the customer's country, or it isn't offered in that country"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask your Banxa integration manager whether express can be enabled for that country. Otherwise this is expected: Banxa falls back to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["standard"]}]}]}]}]}]}]},"headings":[{"value":"Standalone KYC","id":"standalone-kyc","depth":1},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Use your identityReference as externalCustomerId","id":"use-your-identityreference-as-externalcustomerid","depth":2},{"value":"Create a session","id":"create-a-session","depth":2},{"value":"Verification levels","id":"verification-levels","depth":2},{"value":"Show the flow","id":"show-the-flow","depth":2},{"value":"Completion signals","id":"completion-signals","depth":3},{"value":"Get the result","id":"get-the-result","depth":2},{"value":"Using the Banxa SDKs","id":"using-the-banxa-sdks","depth":2},{"value":"Testing in sandbox","id":"testing-in-sandbox","depth":2},{"value":"Troubleshooting","id":"troubleshooting","depth":2}],"frontmatter":{"seo":{"title":"Standalone KYC | Banxa Native API","description":"Have Banxa verify a customer in Banxa-hosted identity screens before any order, then take payment with Banxa Native in your own UI."}},"lastModified":"2026-11-04T07:25:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/native-api/docs/how-it-works/standalone-kyc","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}