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


## 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 retrieves | Name, DOB, selfie, document | Name, DOB, selfie, 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.

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

| Requirement | Reusable KYC | Copy Applicant | If not covered |
|  --- | --- | --- | --- |
| `NAME` | ✓ | ✓ | PATCH |
| `DOB` | ✓ | ✓ | PATCH |
| `SELFIE` | ✓ | ✓ | 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
```


```javascript
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
```


```json
{
  "identityReference": "user-abc123",
  "email": "user@example.com",
  "mobileNumber": "+61431000001",
  "provider": {
    "vendor": "sumsub",
    "token": "eyJhbGciOiJub25lIn0..."
  }
}
```

**Response:** `202 Accepted` — the token has been received and queued for processing. Verification is asynchronous.

## Copy Applicant

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](https://docs.sumsub.com/docs/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.

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