Standalone KYC

For the complete documentation index, see llms.txt. Append .md to any page URL for its markdown version.

Standalone KYC lets Banxa verify a customer's identity 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 paymentReady: true and you take payment with Banxa Native, in your own UI.

Use Standalone KYC if you don't run your own KYC and don't want to build document, selfie, and liveness capture yourself.

• Standalone KYC enabled for your account. Contact your Banxa integration manager. Until it's enabled, session requests return 403.

• KYC webhooks enabled. The KYC webhook is how you learn the verification result. Ask your Banxa integration manager to confirm it's on for your account.

• 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 completion signal.

• Two sets of API credentials. Standalone KYC uses two Banxa APIs, so you need both:

  • your Native API HMAC key and secret, for eligibility and ramps
  • a Hosted Checkout API key, sent in the x-api-key header, for the session endpoint POST /{partnerRef}/v2/kyc/sessions. It's the same key and partner reference you initialise the Banxa payment SDKs with.

  If you don't have a Hosted Checkout API key, contact your Banxa integration manager.

1. Your backend creates a session, passing the user's identityReference as externalCustomerId.
2. Banxa returns a link and its expiry. The link is valid for 1 hour.
3. You show the link to the customer.
4. 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.
5. When nothing is left to collect, the customer sees "Your account is under review".
6. Your app receives a completion signal. This means the customer finished, not that they passed.
7. Banxa sends a KYC webhook when the result is known.
8. Check eligibility. If paymentReady is true, continue with your payment method guide.

externalCustomerId and identityReference are the same identifier. Pass the user's identityReference as externalCustomerId, so the verification attaches to the identity you check eligibility against. The KYC webhook returns the same value as identity_reference.

If no identity exists yet for that identityReference, creating the session creates one.

This endpoint uses your Hosted Checkout API key, not HMAC. Create sessions from your backend, so the key never ships in your app or web page.

POST /{partnerRef}/v2/kyc/sessions
x-api-key: YOUR_HOSTED_CHECKOUT_API_KEY
Content-Type: application/json

{
  "externalCustomerId": "partner-abc123",
  "country": "AU",
  "tier": "standard",
  "returnUrl": "https://yourapp.com/kyc/done"
}

Response 201

{
  "redirectUrl": "https://...",
  "expiresAt": "2026-08-21T08:10:00+00:00"
}

Repeat calls are safe. If you call again for the same externalCustomerId while the link is still valid, you get the same link and expiry back. A new tier takes effect the next time the customer loads a screen. A new country is only used if the customer doesn't have one yet. A new returnUrl only takes effect once the current link expires and you create a new one.

Errors

See the API reference for the full schema.

You request a level with 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.

• 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.
• enhanced: everything in standard, plus further items such as source of funds or proof of address, depending on the region.
• 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 standard and you don't receive an error. Banxa always falls back to more verification, never less.

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.

Whichever level you request, always rely on eligibility to decide whether a specific transaction can proceed.

Banxa doesn't close the iframe or webview. Close it yourself after the completion signal.

The Banxa SDKs handle the webview, camera and microphone setup, and the completion signal for you.

iframe: Banxa posts these messages to your page with postMessage. These are the only messages the iframe sends.

The banxa:kyc-complete payload is always the same. It never says whether the customer passed. Only accept messages whose event.origin matches the origin of 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.

The Banxa SDKs report a few more events of their own, such as KYC errors and rejected messages. See your SDK reference.

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 returnUrl straight away. Otherwise, the screen shows a "Return to [your name]" button that takes them there. If you didn't send a returnUrl, your account's default return URL is used instead. With neither set, the customer stays on the under-review screen.

The "under review" screen and the completion signal don't tell you the outcome. Use:

1. The KYC webhook. Banxa sends it when the customer's verification status changes. It identifies the customer with identity_reference and carries kyc.status. See KYC webhooks.
2. Eligibility. Before creating a ramp, call POST /eapi/v0/identities/transactions/eligibility with the same identityReference. Proceed only when paymentReady is true.

The Banxa SDKs can show a Standalone KYC session and report when the customer finishes. Create the session on your backend and pass redirectUrl to your app, then use your SDK's KYC view:

• React Native SDK
• iOS SDK
• Android SDK
• Flutter SDK
• JS Native Payments SDK

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.

• Use the sandbox base URL: https://api.banxa-sandbox.com/{partnerRef}/v2/kyc/sessions. In production, use https://api.banxa.com.
• Use a new email address for each test customer. If you reuse an email, Banxa treats the session as that existing customer.
• Test the document and selfie steps on a real device. Simulators don't provide a real camera.
• If you use an iframe, check that you receive banxa:kyc-complete exactly once.