Sumsub Integration

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. No additional Sumsub agreement is required.

Sumsub setup (done once per partner):

1. In your Sumsub dashboard, open the Partners page and go to 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 action is required on your side for registration.

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, selfie, 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, KYC liveness checks require SFSafariViewController — they will not complete in a standard WKWebView even if the customer's Sumsub data has been shared. This applies regardless of which sharing approach you use.