For the complete documentation index, see llms.txt. Append
.mdto any page URL for its markdown version.
On Banxa Hosted Checkout the endpoint is POST /{partnerRef}/v2/identities/token/share. Note the path segments are reversed from the Native API path used on this page.
The contract also differs. On Native API you are responsible for satisfying any outstanding eligibility requirements. On Hosted Checkout, Banxa collects anything missing during checkout.
- Hosted Checkout: KYC Sharing
If your users have already completed identity verification with Sumsub, you can share that outcome with Banxa rather than requiring them to verify again. Banxa retrieves the verification data from Sumsub, which satisfies one or more eligibility requirements without additional data collection in your UX.
Token sharing can be called at two points:
- At onboarding — share the token as soon as a user passes KYC on your platform. This pre-populates their Banxa identity so eligibility is more likely to return
paymentReady: trueat first transaction. - In response to an eligibility requirement — if eligibility returns
SELFIEorDOCUMENT, token sharing is one way to satisfy it. If you don't run your own KYC program, use Standalone KYC.
Banxa supports two Sumsub integration approaches. The difference is how much of the user's verified profile Banxa can retrieve.
| Reusable KYC (default) | Copy Applicant | |
|---|---|---|
| What Banxa retrieves | Name, DOB, liveness check, document | Name, DOB, liveness check, document, address, TIN |
| Requirements satisfied | NAME, DOB, SELFIE, DOCUMENT | NAME, DOB, SELFIE, DOCUMENT, ADDRESS, TIN |
| Requirements still needing PATCH | Any others returned by eligibility | Any others returned by eligibility |
| Sumsub product | Reusable KYC | Copy Applicant (separate Sumsub product) |
| Setup | Add Banxa as a recipient in Sumsub (Donors tab) | Sign Copy Applicant agreement with Sumsub; contact Banxa to configure |
| Configured by | Partner | Banxa (per partner account) |
Contact Banxa to confirm which approach is configured for your account.
POST /eapi/v0/identities/share/token, POST /eapi/v0/identities/share/documents and PATCH /eapi/v0/identities only work when KYC sharing is enabled for your account. Until it is, they return 400 with code 4005 and the message KYC sharing not enabled. Contact your Banxa integration manager to enable it.
Banxa's Sumsub verification level requires a liveness check, not a static selfie photo. The eligibility requirement is named SELFIE, but a shared applicant satisfies it only if that applicant passed a liveness check in your Sumsub flow. If your flow captures a still selfie only, the token share will not satisfy SELFIE.
After a successful token share and kyc.status = VERIFIED, re-check eligibility. Outstanding requirements not covered by token sharing must be submitted via PATCH /eapi/v0/identities/{identityReference}, except SELFIE: a liveness check cannot be uploaded, so it needs a Sumsub liveness check or Standalone KYC.
| Requirement | Reusable KYC | Copy Applicant | If not covered |
|---|---|---|---|
NAME | ✓ | ✓ | PATCH |
DOB | ✓ | ✓ | PATCH |
SELFIE | ✓ | ✓ | Sumsub liveness check or Standalone KYC. Not by PATCH |
DOCUMENT | ✓ | ✓ | PATCH |
ADDRESS | — | ✓ | PATCH |
TIN | — | ✓ | PATCH |
POA | — | — | Always PATCH |
SOURCE_FUNDS | — | — | Always PATCH |
PURPOSE_OF_TX | — | — | Always PATCH |
Reusable KYC uses Sumsub's shared token mechanism. No additional Sumsub agreement is required.
One-time setup in your Sumsub dashboard:
- Go to the Partners page and open the Donors tab.
- Click Add Donor.
- Copy your Partner Token and share it with Banxa.
Banxa will add you as a recipient. No further registration action is required.
When a user passes KYC on your platform, generate a Sumsub share token using Banxa's clientId. You must use Banxa's clientId — using a different value will prevent Banxa from accessing the token.
banxa.com_5335const response = await fetch('https://api.sumsub.com/resources/accessTokens/-/shareToken', {
method: 'POST',
headers: {
'X-App-Token': YOUR_SUMSUB_APP_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
userId: customerSumsubApplicantId,
clientId: 'banxa.com_5335'
})
});
const { token } = await response.json();The share token has an expiry — generate it close to the time you send it to Banxa.
POST /eapi/v0/identities/share/token{
"identityReference": "user-abc123",
"email": "[email protected]",
"mobileNumber": "+61431000001",
"provider": {
"vendor": "sumsub",
"token": "eyJhbGciOiJub25lIn0..."
}
}Response: 202 Accepted — the token has been received and queued for processing. Verification is asynchronous.
If Banxa can't accept the token, the request fails straight away with 400 and nothing is saved. Fix the problem and send the request again.
{
"message": "The KYC sharing token is already in use",
"code": 4024,
"traceId": "2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f"
}| Code | Message | Cause | What to do |
|---|---|---|---|
4005 | KYC sharing not enabled | KYC sharing isn't enabled for your account. | Contact your Banxa integration manager. |
4023 | The customer reference is already in use | The customer reference is already used by another customer. | Check you're sending the right identityReference for this customer. |
4024 | The KYC sharing token is already in use | The token was already shared for a different customer. | Generate a new share token for this customer's own Sumsub applicant. |
4025 | The customer is blocked and cannot be used | The customer is blocked by Banxa. | Don't retry. The customer can't transact with Banxa. |
4026 | This customer has already completed KYC sharing and it cannot be repeated | An earlier token share for this customer already passed. | Don't send another token. Re-check eligibility and submit anything outstanding with PATCH. |
If a share didn't give Banxa what it needs, fix the problem in your Sumsub flow and send a new share token for the same customer. Banxa accepts it and processes it. Send a new token when:
kyc.statusisACTION_REQUIREDorREJECTEDafter the share. The reasons tell you what to fix.kyc.statusisVERIFIED, but eligibility still returnsSELFIEorDOCUMENT. The applicant you shared was approved in Sumsub but was missing that step, for example the liveness check.
Once a share has passed with nothing missing, Banxa refuses further tokens for that customer with 400 and code 4026. Submit any other outstanding requirements with PATCH.
Sending the same token again for the same customer, for example after a timeout, returns 202 without processing it a second time. It is safe to retry.
Banxa copies the user's applicant record directly from your Sumsub account. Banxa currently retrieves: name, DOB, liveness check, document, address, and TIN. Proof of address and other fields are not currently extracted — any requirements not covered will still need to be submitted via PATCH.
What Banxa can retrieve depends on what your KYC flow collected. Fields not present in your Sumsub applicant record will not be available.
Copy Applicant is a separate Sumsub product — see Sumsub Copy Applicant for Sumsub's documentation.
- Sign the Copy Applicant agreement with Sumsub. Copy Applicant is a separate Sumsub product — contact your Sumsub account manager to enable it.
- Contact Banxa to configure Copy Applicant on your partner account. No code changes are required on your side.
Token sharing is processed asynchronously. Do not assume verification is complete immediately after the 202 response.
Using the KYC webhook:
Banxa sends a webhook when verification status changes. Wait for kyc.status = VERIFIED before re-checking eligibility. See the Webhooks article in this documentation for payload shape and verification.
If you are polling:
Call GET /eapi/v0/identities/{identityReference} to check kyc.status. Poll at intervals of 30–60 seconds minimum — the endpoint returns 429 if called too frequently. ACTION_REQUIRED and REJECTED are stable states; back off further on these.
After VERIFIED:
Re-check eligibility. kyc.status = VERIFIED means document and liveness checks passed — it does not guarantee the transaction can proceed. Eligibility is the authoritative signal.
If eligibility still returns SELFIE or DOCUMENT after VERIFIED, the shared Sumsub applicant didn't include that step. See Sending a new token.
If Banxa can't verify the customer from the shared token, kyc.status becomes ACTION_REQUIRED or REJECTED. It doesn't stay PENDING. To find out why and what to do:
- Wait for the KYC webhook with
kyc.statusACTION_REQUIREDorREJECTED. The webhook carries the status only, not the reasons. - Get the reasons. Call
GET /eapi/v0/identities/{identityReference}and readkyc.rejectionReasons. - Act on each reason using the table below. For
ACTION_REQUIRED, fix the problem in your Sumsub flow and send a new token. ForREJECTED, don't ask the customer to try again with the same details.
An example response, showing only the fields used here:
{
"identityReference": "user-abc123",
"kyc": {
"status": "ACTION_REQUIRED",
"rejectionReasons": [
{
"type": "PASSPORT",
"internalReason": "FOREIGNER",
"reason": "wrong_document_retry",
"message": "Wrong document (retry)",
"error_code": 4202
}
]
}
}Each reason has these fields:
| Field | Description |
|---|---|
reason | What went wrong. Use this, or error_code, to decide what to do. |
error_code | A numeric code for the specific problem. |
message | A short description of the reason. |
type | What the reason relates to: the document type, such as PASSPORT; SELFIE for a liveness or face-match problem; or PERSONAL_DETAILS when the share token itself was rejected. Can be null. |
internalReason | Sumsub's rejection label. For your logs. |
reason | error_code | kyc.status | What happened | What to do |
|---|---|---|---|---|
share_token_invalid | 4401 | ACTION_REQUIRED | Sumsub rejected the share token as expired, invalid or already used. | Generate a new share token and send it. |
wrong_document_retry | 4201 | ACTION_REQUIRED | The document type isn't accepted, or the document didn't pass Sumsub's checks. | Have the customer submit an accepted document in your Sumsub flow, then send a new token. |
wrong_document_retry | 4202 | ACTION_REQUIRED | The document's issuing country isn't accepted. | As above. |
wrong_document_retry | 4203 | ACTION_REQUIRED | The document is a duplicate of one already used. | As above. |
wrong_document_retry | 4208 | ACTION_REQUIRED | The document has expired. | As above. |
bad_selfie_retry | 4001 | ACTION_REQUIRED | The liveness check or face match failed. | Have the customer redo the liveness check in your Sumsub flow, then send a new token. |
additional_document_required | 4301 | ACTION_REQUIRED | Another Sumsub check failed, or Banxa couldn't get the check results. | Check the applicant in your Sumsub dashboard, complete what's missing, then send a new token. |
bad_applicant_data | 2202 | REJECTED | The customer doesn't meet the age requirement. | The customer can't be verified. |
bad_applicant_data | 2205 | REJECTED | The customer's details don't match across the applicant's data. | The customer can't be verified with these details. |
applicant_blocked | 3007 | REJECTED | The customer is on a Sumsub blocklist. | The customer can't be verified. |
- A response can carry more than one reason. If any reason is
REJECTED,kyc.statusisREJECTED. - A customer who is already
VERIFIEDstaysVERIFIEDif a later token share fails.