KYC Token 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: true at first transaction.
• In response to an eligibility requirement — if eligibility returns SELFIE or DOCUMENT, token sharing is the mechanism to satisfy it. See the Incremental KYC Upgrade article in this documentation.

Banxa supports two Sumsub integration approaches. The difference is how much of the user's verified profile Banxa can retrieve.

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

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}.

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.

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.

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.

Banxa copies the user's applicant record directly from your Sumsub account. Banxa currently retrieves: name, DOB, selfie, 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.

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.

Token sharing is processed asynchronously. Do not assume verification is complete immediately after the 202 response.

If you have the opt-in KYC webhook enabled:

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.

The opt-in KYC webhook must be enabled by Banxa for your account. Contact Banxa to activate it.