Skip to content
Last updated

KYC Token Sharing

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

This page applies to Banxa Native API only

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.

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: true at first transaction.
  • In response to an eligibility requirement — if eligibility returns SELFIE or DOCUMENT, token sharing is one way to satisfy it. If you don't run your own KYC program, use Standalone KYC.

Two approaches

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 retrievesName, DOB, liveness check, documentName, DOB, liveness check, document, address, TIN
Requirements satisfiedNAME, DOB, SELFIE, DOCUMENTNAME, DOB, SELFIE, DOCUMENT, ADDRESS, TIN
Requirements still needing PATCHAny others returned by eligibilityAny others returned by eligibility
Sumsub productReusable KYCCopy Applicant (separate Sumsub product)
SetupAdd Banxa as a recipient in Sumsub (Donors tab)Sign Copy Applicant agreement with Sumsub; contact Banxa to configure
Configured byPartnerBanxa (per partner account)

Contact Banxa to confirm which approach is configured for your account.

KYC sharing must be enabled

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.

SELFIE means a liveness check

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.


Requirements coverage

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.

RequirementReusable KYCCopy ApplicantIf 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

Setup

Reusable KYC uses Sumsub's shared token mechanism. No additional Sumsub agreement is required.

One-time setup in your Sumsub dashboard:

  1. Go to the Partners page and open the Donors tab.
  2. Click Add Donor.
  3. Copy your Partner Token and share it with Banxa.

Banxa will add you as a recipient. No further registration action is required.

Generating the share token

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_5335
const 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.

Calling the endpoint

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.

Errors when sharing a token

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"
}
CodeMessageCauseWhat to do
4005KYC sharing not enabledKYC sharing isn't enabled for your account.Contact your Banxa integration manager.
4023The customer reference is already in useThe customer reference is already used by another customer.Check you're sending the right identityReference for this customer.
4024The KYC sharing token is already in useThe token was already shared for a different customer.Generate a new share token for this customer's own Sumsub applicant.
4025The customer is blocked and cannot be usedThe customer is blocked by Banxa.Don't retry. The customer can't transact with Banxa.
4026This customer has already completed KYC sharing and it cannot be repeatedAn earlier token share for this customer already passed.Don't send another token. Re-check eligibility and submit anything outstanding with PATCH.

Sending a new token

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.status is ACTION_REQUIRED or REJECTED after the share. The reasons tell you what to fix.
  • kyc.status is VERIFIED, but eligibility still returns SELFIE or DOCUMENT. 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.


Copy Applicant

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.

Setup

  1. Sign the Copy Applicant agreement with Sumsub. Copy Applicant is a separate Sumsub product — contact your Sumsub account manager to enable it.
  2. Contact Banxa to configure Copy Applicant on your partner account. No code changes are required on your side.

After token sharing — async flow

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.


When a token share fails

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:

  1. Wait for the KYC webhook with kyc.status ACTION_REQUIRED or REJECTED. The webhook carries the status only, not the reasons.
  2. Get the reasons. Call GET /eapi/v0/identities/{identityReference} and read kyc.rejectionReasons.
  3. Act on each reason using the table below. For ACTION_REQUIRED, fix the problem in your Sumsub flow and send a new token. For REJECTED, 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:

FieldDescription
reasonWhat went wrong. Use this, or error_code, to decide what to do.
error_codeA numeric code for the specific problem.
messageA short description of the reason.
typeWhat 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.
internalReasonSumsub's rejection label. For your logs.

Reasons for a failed token share

reasonerror_codekyc.statusWhat happenedWhat to do
share_token_invalid4401ACTION_REQUIREDSumsub rejected the share token as expired, invalid or already used.Generate a new share token and send it.
wrong_document_retry4201ACTION_REQUIREDThe 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_retry4202ACTION_REQUIREDThe document's issuing country isn't accepted.As above.
wrong_document_retry4203ACTION_REQUIREDThe document is a duplicate of one already used.As above.
wrong_document_retry4208ACTION_REQUIREDThe document has expired.As above.
bad_selfie_retry4001ACTION_REQUIREDThe liveness check or face match failed.Have the customer redo the liveness check in your Sumsub flow, then send a new token.
additional_document_required4301ACTION_REQUIREDAnother 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_data2202REJECTEDThe customer doesn't meet the age requirement.The customer can't be verified.
bad_applicant_data2205REJECTEDThe customer's details don't match across the applicant's data.The customer can't be verified with these details.
applicant_blocked3007REJECTEDThe 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.status is REJECTED.
  • A customer who is already VERIFIED stays VERIFIED if a later token share fails.