# KYC Sharing

If your platform uses Sumsub for identity verification, you can share the customer's verified KYC data with Banxa before they enter checkout. Banxa retrieves the data directly from Sumsub — reducing or eliminating the verification steps the customer needs to complete in the Banxa checkout.

## Prerequisites

- Your platform uses Sumsub for identity verification.
- The identity endpoint must be enabled for your account (requires Banxa approval).
- You have completed the Sumsub token sharing agreement with Banxa.
- Only share data for customers who have **already been KYC verified** on your platform.


## How it works


```mermaid
sequenceDiagram
    participant P as Partner Platform
    participant B as Banxa Identity API
    participant S as Sumsub
    participant C as Customer

    Note over P,C: At KYC verification time (recommended)
    C->>P: Completes KYC on partner platform
    P->>S: Generate share token<br/>(clientId: banxa.com_5335)
    S-->>P: Share token
    P->>B: POST /v2/identities/token/share<br/>{externalCustomerId, provider.token, ...}
    B-->>P: 202 Accepted

    Note over P,C: When customer initiates a transaction
    C->>P: Initiates buy or sell
    P->>B: POST /v2/buy or /v2/sell
    B-->>P: checkoutUrl
    P->>C: Redirect to checkoutUrl
    C->>B: Enters Banxa checkout
    B->>S: Retrieve KYC data using stored token
    S-->>B: Customer KYC data
    B->>C: Checkout with KYC pre-filled
```

1. When a customer is KYC-verified on your platform, generate a Sumsub share token using Banxa's `clientId` and call the Banxa identity endpoint. Do this at verification time — not at order creation, as the data may not be processed in time for the customer's session.
2. Banxa stores the token and associates it with the `externalCustomerId`.
3. When the customer enters the Banxa checkout, Banxa retrieves their KYC data from Sumsub. Their details are pre-populated and some verification steps may be skipped.
4. Banxa still performs its own KYC due diligence. Additional information may be requested if required by compliance processes.


→ See [Sumsub Integration](/products/hosted-checkout/docs/identity-compliance/sumsub-integration) for how to generate the share token and for details on Copy Applicant, which extracts a fuller profile including address and TIN.

## Endpoint


```
POST /{partnerRef}/v2/identities/token/share
```

This endpoint uses **HMAC authentication**, not the standard `x-api-key` header. HMAC signing must be done server-side — never embed your API secret in frontend or mobile code.

See [Authentication & Environments](/products/hosted-checkout/docs/getting-started/authentication-and-environments) for the signing algorithm, code examples, and error codes.

## Request body

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `externalCustomerId` | string | Yes | Your stable customer identifier. Must match the value used in order creation. |
| `email` | string | Yes | Customer's email address. |
| `mobileNumber` | string | Yes | Customer's mobile number including country code (e.g., `+61412345678`). |
| `provider.vendor` | string | Yes | Must be `sumsub`. |
| `provider.token` | string | Yes | The Sumsub share token generated using `clientId: banxa.com_5335`. |


## Example request


```bash
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": "customer@example.com",
    "provider": {
      "vendor": "sumsub",
      "token": "_act-sbx-jwt-eyJhbGciOiJub25lIn0..."
    }
  }'
```

## Response

**202 Accepted**


```json
{
  "externalCustomerId": "user_12345"
}
```

A `202` response confirms Banxa has received and queued the identity data for processing. It does not guarantee immediate availability in the checkout.

## Important notes

- `externalCustomerId` must be the same value used in order creation. Using different values for the same customer creates separate identities in the Banxa system.
- Banxa may still collect additional information from the customer during checkout if required by compliance processes.
- Only submit data for verified customers. Do not pass unverified or provisional data.