Sumsub Integration

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

Banxa supports two approaches for sharing Sumsub KYC data. They differ in how much of the customer's verified profile Banxa can retrieve.

Banxa retrieves the customer's basic verification data from Sumsub using a share token. Any fields not retrieved can be collected separately — Banxa's checkout will prompt the customer for any outstanding information during the flow.

Reusable KYC uses Sumsub's Reusable KYC via API feature. You share data with Banxa as the donor, and Banxa receives it as the recipient.

Sumsub setup (done once per partner):

1. Sign Sumsub's Reusable KYC agreement. Reusable KYC must be enabled on your Sumsub account before you can share applicants with Banxa. No other Sumsub agreement is required.
2. Ask your account manager for Banxa's Sumsub partner token.
3. In your Sumsub dashboard, open the Partners page and go to the Recipients tab.
4. Click Add recipient, enter Banxa's partner token and confirm.

Partner tokens expire 30 days after they are created and only work in the Sumsub environment they were created in, so use a sandbox token for sandbox and a production token for production.

When a customer passes KYC on your platform, generate a share token using Banxa's clientId:

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'   // Must be Banxa's clientId
  })
});

const { token } = await response.json();

You must use Banxa's clientId when generating the token. Using a different clientId will block Banxa from accessing the token.

banxa.com_5335

→ Refer to Sumsub documentation for the authoritative share token API reference.

Pass the generated token to the Banxa identity endpoint. See KYC Sharing for the full endpoint reference and request body.

curl -X POST "https://api.banxa-sandbox.com/{partnerRef}/v2/identities/token/share" \
  -H "Authorization: Bearer API_KEY:SIGNATURE:NONCE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "externalCustomerId": "user_12345",
    "mobileNumber": "+61412345678",
    "email": "[email protected]",
    "provider": {
      "vendor": "sumsub",
      "token": "_act-sbx-jwt-eyJhbGciOiJub25lIn0..."
    }
  }'

Call this at KYC verification time — not at order creation. If called at order creation, the data may not be processed in time for the customer's checkout session.

The Sumsub share token has an expiry. Generate a fresh token close to the time you send it to Banxa.

Banxa copies the customer's applicant record directly from your Sumsub account. Copy Applicant is a separate Sumsub product — see Sumsub Copy Applicant for Sumsub's documentation.

Banxa currently retrieves: name, DOB, liveness check, document, address, and TIN. Proof of address and other fields are not currently extracted — any outstanding requirements can be supplemented via the identity endpoint if needed.

What Banxa can retrieve depends on what your KYC flow collected. Fields not present in your Sumsub applicant record will not be available regardless of which approach is used.

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

Banxa retrieves the applicant data automatically when the customer enters checkout.

On iOS 15 and later, KYC liveness checks work inside a standard WKWebView. On iOS versions before 15, liveness checks cannot complete in WKWebView — use SFSafariViewController if you need to support pre-iOS 15 devices. This applies regardless of which sharing approach you use.