Every transaction in Banxa Native is tied to a verified customer identity. Before a ramp can be created, Banxa needs to know who the user is and whether they meet the compliance requirements for that transaction.
This page explains how identity works in Banxa Native, the four models available for establishing it, and how to decide which one fits your integration.
Identity in Banxa Native is built around a single concept: the identityReference. This is your stable, unique identifier for each user — the same value you use across all API calls for that person.
When a user transacts, Banxa looks up their identityReference to retrieve their compliance state: what they've previously verified, what tier they're on, and whether they can proceed with the current transaction. Identity records accumulate over time — verification completed once is reused for future transactions.
Eligibility is the control plane. After establishing identity, you call eligibility before every transaction. Eligibility checks the current state of the user's identity against the specific transaction context (amount, method, jurisdiction) and returns either paymentReady: true or a list of outstanding requirements. Partners should rely on eligibility responses — not assumptions — to determine when and what to collect.
Banxa Native supports four ways to establish and verify a customer's identity. These are not mutually exclusive — a single user can move between models as their transaction needs grow.
| Model | Who it's for | What Banxa receives | KYC performed by |
|---|---|---|---|
| Basic Identity Creation | All partners | Minimal personal data (name, DOB, etc.) | None — Banxa uses transaction risk tiers |
| KYC Provider Token Sharing | Partners using Sumsub | A verification token Banxa uses to pull KYC data | Your KYC provider (Sumsub) |
| Identity Reliance | Regulated entities with their own compliance program | Confirmation that partner has verified the user | Your compliance team |
| KYC Submission | Partners without their own KYC | Identity documents and personal data | Banxa |
Create a lightweight identity record without submitting verification documents. Banxa uses transaction risk thresholds to determine whether this is sufficient for a given transaction — for low-value or low-risk transactions in supported jurisdictions, users can transact without completing full KYC.
Best for: Fast onboarding. Partners who want to start low and escalate only when required. First-time users who may not yet need full verification.
How it works: You call POST /identities/basic with the user's identityReference and any available personal details (name, DOB, address). If eligibility later requires more, the same identity is upgraded — no restart.
If your users have already completed verification with Sumsub, you can share that outcome with Banxa. Banxa retrieves the verification data directly from Sumsub, meaning your users don't need to verify twice.
Best for: Wallets and exchanges that already run their own KYC with Sumsub. Maximum UX control — no Banxa-branded verification screens.
How it works: When a user passes KYC on your platform, generate a Sumsub share token using Banxa's clientId and call POST /identities/share/token. Banxa processes the token asynchronously. Once kyc.status is VERIFIED, re-check eligibility to confirm the user can proceed.
If you use a different KYC provider, contact Banxa to discuss supported options.
For regulated entities with their own compliance program, Banxa can rely on your existing KYC outcomes rather than independently re-verifying the user. When reliance is established, applicable verification requirements are treated as satisfied for the agreed scope.
Best for: Financial institutions, exchanges, and fintechs that operate their own AML / KYC frameworks and want to avoid duplication. Requires a prior reliance agreement with Banxa.
How it works: Configured at the account level by agreement between Banxa and the partner. No separate API call at the user level — reliance is applied to the identity based on your account configuration.
Submit identity information and documentation directly to Banxa via API. Banxa performs the verification. Submitted information is associated with the identity and reused for future transactions.
Best for: Partners that do not run their own KYC flows. Suitable for document-based verification use cases.
Note: Some verification capabilities — such as selfie or liveness capture — may require additional coordination. Contact Banxa if your use case depends on these.
A single identity can move through multiple models over time:
- Start with Basic Identity Creation for fast onboarding
- Share a KYC token (or submit documents) when eligibility requires higher verification
- Previously completed verification is retained — identity is never recreated
This progressive approach means users only face friction when the transaction actually requires it.
| If you... | Use |
|---|---|
| Want the fastest onboarding with no upfront KYC | Basic Identity Creation |
| Already verify users with Sumsub | KYC Provider Token Sharing |
| Are a regulated entity with your own compliance program | Identity Reliance |
| Don't run KYC and want Banxa to handle it | KYC Submission to Banxa |
Most partners start with Basic Identity Creation and add token sharing or reliance as needed. Contact Banxa if you're unsure which model fits your regulatory context.
Regardless of which identity model you use, eligibility is the step that determines whether a specific transaction can proceed.
- Create or reference an identity using a persistent
identityReference - Check eligibility for the intended transaction
- Collect and submit additional information only if eligibility requires it
- Re-check eligibility before proceeding with the transaction
This ensures users are only asked for additional information when it is actually required for their transaction context. See Interpreting Eligibility for the full requirements dictionary and handling guidance.