KYC sharing via SumSub

If your users have already completed identity verification (KYC) on your platform via SumSub, you can pass their verification data to BTC Direct using a KYC share token. This allows users to skip re-verification on our platform.

Prerequisites

• A working checkout integration. See Quick start: buy (F2C).
• A SumSub integration on your platform that completes KYC for your users.
• Access to the SumSub Share Token API.

How it works

1. Your platform completes KYC for the user via SumSub.
2. You generate a share token through the SumSub Share Token API.
3. You pass the token in the POST /api/v2/buy/checkout request as kycShareToken.
4. The token is embedded in the checkout URL.
5. When the user registers on the BTC Direct checkout page, the token is used to import their existing KYC data.

Note

The SumSub share token is single-use. Once consumed during checkout registration, it cannot be reused. Generate a new token for each checkout session.

Example

curl -X POST https://api-sandbox.btcdirect.eu/api/v2/buy/checkout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "baseCurrency": "BTC",
    "quoteCurrency": "EUR",
    "paymentMethod": "creditCard",
    "quoteCurrencyAmount": 50,
    "walletAddress": "bc1...",
    "kycShareToken": "_act-sbx-jwt-your-token"
  }'

Try it out

Create a checkout session with a KYC share token.

Authorization (partner JWT token) Request body { "baseCurrency": "BTC", "quoteCurrency": "EUR", "paymentMethod": "creditCard", "quoteCurrencyAmount": 50, "walletAddress": "bc1...", "kycShareToken": "_act-sbx-jwt-your-token" }

POST /api/v2/buy/checkout Copy as curl

Response

The token will appear as a query parameter in the returned checkoutUrl. You do not need to handle it further. The checkout page processes it automatically during user registration.

Requirements

• The share token must be generated from a SumSub applicant that has been approved (verification level: individual).
• Only individual KYC is supported. KYB (business verification) share tokens are not supported.
• The token is validated by SumSub when consumed. Expired, invalid, or already-used tokens are silently ignored. The user will go through standard verification instead.

Scenario	Result
Valid share token provided	User’s KYC data is imported at registration. Verification steps are skipped or reduced.
Invalid or expired token	Token is ignored. User goes through standard KYC verification.
No token provided	Standard flow. No change in behavior.

Caution

Share tokens should be treated as sensitive data. Generate them server-side and do not expose them in client-side code. The share token is not included in the HMAC signature. It is a self-protecting, single-use token validated by SumSub.

See the checkout endpoint specification for the full request schema.