KYC & KYB Verification
Overview
Bakkt uses Sumsub for identity verification:
- KYC (Know Your Customer) — required for individual users before they can transact.
- KYB (Know Your Business) — required for corporate entities before they can transact.
You can integrate verification in three ways:
| Approach | When to use | Endpoints involved |
|---|---|---|
| Sumsub Web SDK (recommended) | You can host JS in the user's browser and want Sumsub's hosted UI. | POST /user/kyc/applicant, GET /user/kyc/applicant/token |
| Hosted form URL | You only need to send the user a link (e.g. via email) to a hosted form. | GET /user/kyc/applicant/url (KYC), GET /corporate/{corporate_uuid}/kyb/applicant/url (KYB) |
| API-only (server-to-server) | You collect documents yourself and submit them via API. | POST /user/kyc/applicant, PUT /user/kyc/document, POST /user/kyc/verification |
Already verify users or corporates in your own Sumsub account?
You can reuse those verifications instead of asking users or corporates to verify again. With Sumsub's Reusable KYC, you share a verified applicant from your Sumsub account to Bakkt's Sumsub account with one API call. This requires a one-time setup with Bakkt. See Import an existing KYC applicant and Import an existing KYB applicant.
Before you begin
- Sandbox base URL:
https://sandbox.api.bakkt.com/onboarding- Production base URL:
https://api.bakkt.com/onboarding- Headers on every call:
Authorization: <YOUR_API_KEY>and eitherbakkt-session-id: <SESSION_ID>or, for select read endpoints,user-uuid: <USER_UUID>. See Authentication.
KYC (individual users)
KYC status lifecycle
The happy path:
KYC_NEEDED → PENDING_KYC_DATA → KYC_PENDING → FULL_USERKYC_PENDING can also resolve to a failure state:
SOFT_KYC_FAILED— recoverable; user can retry, looping back toKYC_PENDING.HARD_KYC_FAILED— terminal; contact support.
| Status | Meaning | Next action |
|---|---|---|
KYC_NEEDED | User exists but no KYC application has been created. | POST /user/kyc/applicant |
PENDING_KYC_DATA | Application created; documents not yet collected. | Launch Sumsub SDK or upload via API. |
KYC_PENDING | Documents submitted; Sumsub/compliance is reviewing. | Wait for webhook or poll GET /user/kyc/applicant. |
SOFT_KYC_FAILED | Recoverable failure (bad image, mismatched data, etc.). | User can retry — see Recovering from a soft failure. |
HARD_KYC_FAILED | Terminal failure (compliance hit, fraud signal, etc.). | Contact support; user cannot self-serve. |
FULL_USER | KYC approved; user can transact. Reflected on the user object via GET /user. | — |
Note: The
FULL_USERstatus is exposed on the user object (GET /user), not on the KYC applicant response. The KYC applicant endpoint only returns the in-flight statuses above.
Step 1 — Create a KYC application
This is a one-off call per user. It registers the applicant with Sumsub and unlocks the document-collection endpoints.
Endpoint: POST /user/kyc/applicant — returns 204 No Content.
await fetch('https://sandbox.api.bakkt.com/onboarding/user/kyc/applicant', {
method: 'POST',
headers: {
'Authorization': 'YOUR_API_KEY',
'bakkt-session-id': sessionId,
'Content-Type': 'application/json'
},
body: JSON.stringify({
address: {
address_line_1: '123 Main Street',
post_code: 'SW1A 1AA',
city: 'London',
country: 'GB'
},
date_of_birth: '1990-05-15',
source_of_funds: 'SALARY'
})
});source_of_funds values:
| Value | Description |
|---|---|
SALARY | Employment income |
BUSINESS_INCOME | Self-employed / business revenue |
PENSION | Retirement income |
OTHER | Other legitimate sources |
U.S. users require additional fields in the request body:
ssn(9 digits),ip_address,phone(E.164). See the API reference for the full schema.
Step 2 — Choose a collection method
Pick one of the three options below.
Option A — Sumsub Web SDK (recommended)
Get a short-lived Sumsub access token and embed Sumsub's hosted widget in your page.
Token endpoint: GET /user/kyc/applicant/token
const tokenRes = await fetch('https://sandbox.api.bakkt.com/onboarding/user/kyc/applicant/token', {
headers: {
'Authorization': 'YOUR_API_KEY',
'bakkt-session-id': sessionId
}
});
const { token } = await tokenRes.json();Then initialise the widget. The Sumsub SDK exposes a global snsWebSdk:
<script src="https://static.sumsub.com/idensic/static/sns-websdk-builder.js"></script>
<div id="sumsub-websdk-container"></div>
<script>
async function getNewAccessToken() {
const res = await fetch('https://sandbox.api.bakkt.com/onboarding/user/kyc/applicant/token', {
headers: {
'Authorization': 'YOUR_API_KEY',
'bakkt-session-id': sessionId
}
});
const { token } = await res.json();
return token;
}
const snsWebSdkInstance = snsWebSdk
.init(token, () => getNewAccessToken())
.withConf({ lang: 'en' })
.withOptions({ addViewportTag: false, adaptIframeHeight: true })
.on('idCheck.onStepCompleted', (payload) => {
console.log('Sumsub step completed', payload);
})
.on('idCheck.onApplicantStatusChanged', (payload) => {
console.log('Applicant status changed', payload);
})
.on('idCheck.onError', (error) => {
console.error('Sumsub error', error);
})
.build();
snsWebSdkInstance.launch('#sumsub-websdk-container');
</script>Once the user finishes the Sumsub flow, the applicant moves to KYC_PENDING automatically. You'll receive a webhook on the final outcome — see Webhooks.
For the full SDK API and configuration options, see the Sumsub Web SDK documentation.
Option B — Hosted form URL
Get a short-lived URL to Sumsub's hosted form. Send it to the user (email, deep link, etc.) and they complete verification without you embedding any SDK.
Endpoint: GET /user/kyc/applicant/url
const res = await fetch('https://sandbox.api.bakkt.com/onboarding/user/kyc/applicant/url', {
headers: {
'Authorization': 'YOUR_API_KEY',
'bakkt-session-id': sessionId
}
});
const { url, ttl_in_seconds } = await res.json();This endpoint also accepts
user-uuidinstead ofbakkt-session-idfor server-to-server calls. The URL is short-lived — generate it on demand rather than caching.
Option C — API-only (server-to-server)
Use this if you collect identity documents yourself (no Sumsub UI). You upload each document via API, then explicitly start verification.
Upload endpoint: PUT /user/kyc/document
await fetch('https://sandbox.api.bakkt.com/onboarding/user/kyc/document', {
method: 'PUT',
headers: {
'Authorization': 'YOUR_API_KEY',
'bakkt-session-id': sessionId,
'Content-Type': 'application/json'
},
body: JSON.stringify({
content: base64Image, // base64-encoded image, < 500 KB
document_type: 'PASSPORT',
document_subtype: 'FRONT_SIDE', // required for ID_CARD or DRIVERS
country: 'GB'
})
});Supported document_type values for upload:
| Type | Notes |
|---|---|
SELFIE | Face photo |
PASSPORT | Front page only |
DRIVERS | Requires FRONT_SIDE and BACK_SIDE uploads |
ID_CARD | Requires FRONT_SIDE and BACK_SIDE uploads |
RESIDENCE_PERMIT | Residence permit |
UTILITY_BILL | Proof of address |
After all required documents are uploaded, explicitly start verification:
Endpoint: POST /user/kyc/verification — returns 204 No Content.
await fetch('https://sandbox.api.bakkt.com/onboarding/user/kyc/verification', {
method: 'POST',
headers: {
'Authorization': 'YOUR_API_KEY',
'bakkt-session-id': sessionId
}
});You only need
POST /user/kyc/verificationfor the API-only flow. When using the Sumsub Web SDK or the hosted form URL, verification is started automatically once Sumsub has all the documents.
Step 3 — Check status
Poll until you receive a webhook (see Webhooks) or call:
Endpoint: GET /user/kyc/applicant
const res = await fetch('https://sandbox.api.bakkt.com/onboarding/user/kyc/applicant', {
headers: {
'Authorization': 'YOUR_API_KEY',
'bakkt-session-id': sessionId
}
});
const status = await res.json();Example response:
{
"status": "KYC_PENDING",
"docs_missing": [
{ "doc_type": "ID_CARD" },
{ "doc_type": "SELFIE" }
],
"kyc_enduser_error_message": "Please provide a clear photo of your ID card",
"kyc_reject_label": []
}To know whether the user is fully verified, check status === 'FULL_USER' on GET /user.
Recovering from a soft failure
When a user lands in SOFT_KYC_FAILED, they can retry. Use the same path you used originally:
- If you used Sumsub SDK or hosted URL: request a fresh token (
GET /user/kyc/applicant/token) or a fresh URL (GET /user/kyc/applicant/url) and re-launch the flow. The user updates the failing documents and Sumsub re-runs verification. - If you used the API-only flow: re-upload the failing documents with
PUT /user/kyc/document, then callPOST /user/kyc/verificationagain.
The kyc_reject_label array on GET /user/kyc/applicant tells you exactly which checks failed — surface those to the user before retry.
Import an existing KYC applicant (Sumsub Reusable KYC)
What this does
If you already verify your users in your own Sumsub account, you do not have to collect their documents again for Bakkt. You share the verified applicant from your Sumsub account to Bakkt's Sumsub account, and Bakkt creates the user's KYC applicant from that data. This uses Sumsub's Reusable KYC feature.
Use this instead of Step 1 and Step 2 above. It is a replacement for creating the applicant, not an additional step.
There are two Sumsub accounts in this flow:
| Account | Owner | Role |
|---|---|---|
| Your Sumsub account | You (the merchant) | Donor: verifies the user first and shares the applicant. |
| Bakkt's Sumsub account | Bakkt | Recipient: receives the shared applicant and runs Bakkt's own review on it. |
The flow has a one-time setup, and then one API call for each user.
One-time setup
Do this setup before you import your first user, in sandbox and again in production.
- You opt in to Reusable KYC. Enable Sumsub's Reusable KYC in your own Sumsub account. Contact your Sumsub account manager if it is not available to you.
- Bakkt shares a token with you. Contact Bakkt support. Bakkt gives you a token from Bakkt's Sumsub account. Use it in your Sumsub account to connect your account to Bakkt's as a donor. Without this connection, Bakkt cannot accept share tokens from your account.
- Bakkt shares the verification levels for your merchant. Bakkt tells you which Sumsub verification levels your merchant is configured to use (for example, one level for U.S. users and one for all other users). Configure your own Sumsub KYC flows so that they collect at least the same steps and documents as these levels. If your level collects less than Bakkt's level (for example, no proof of address), the imported applicant has gaps, and the user must provide the missing data to Bakkt before they can be approved.
For each user
- The user completes KYC in your Sumsub account and is approved there.
- Create the user in Bakkt with the same data as in your Sumsub applicant. See User Management. The user must be in
KYC_NEEDEDstatus. Do not callPOST /user/kyc/applicant. - Generate a share token in your Sumsub account for that applicant, with Bakkt's account as the recipient. See Sumsub's Reusable KYC documentation. A share token can be used one time only, so generate a new one for each attempt.
- Send the share token to Bakkt with
POST /user/kyc/applicant/share-token. - Bakkt imports and reviews the applicant (see What Bakkt does with the share token).
- Wait for the result. Listen for Bakkt's KYC webhooks and/or check
GET /user/kyc/applicant. Do not send the share token again after a204.
Your Sumsub account Bakkt
─────────────────── ─────
User verified (approved)
│
Generate share token ───────────────▶ POST /user/kyc/applicant/share-token
│
Check user status and token
Compare applicant data with Bakkt user
Copy applicant into Bakkt's Sumsub
Review against your merchant's level
│
FULL_USER ─or─ more data needed ─or─ rejectedSend the share token
Endpoint: POST /user/kyc/applicant/share-token — returns 204 No Content.
await fetch('https://sandbox.api.bakkt.com/onboarding/user/kyc/applicant/share-token', {
method: 'POST',
headers: {
'Authorization': 'YOUR_API_KEY',
'bakkt-session-id': sessionId,
'Content-Type': 'application/json'
},
body: JSON.stringify({
share_token: 'sumsub-share-token-from-your-account',
source_of_funds: 'SALARY'
})
});| Field | Required | Description |
|---|---|---|
share_token | Yes | The share token from your Sumsub account. |
source_of_funds | No | Same values as in Step 1 (SALARY, BUSINESS_INCOME, PENSION, OTHER). |
Share tokens from a Sumsub account that is not connected to Bakkt's account (see One-time setup) are rejected.
What Bakkt does with the share token
-
Checks the user. The user must be in
KYC_NEEDEDstatus, must not be suspended, and must not already have a KYC applicant. -
Checks the token. Bakkt previews the shared applicant in Sumsub. If the token is not valid, was already used, or comes from an account that is not connected, the request fails.
-
Compares the applicant with the Bakkt user. The KYC data in your Sumsub applicant must match the data that you used to create the user in Bakkt. If you need more details about which data is compared, contact Bakkt support.
If the data does not match, nothing is imported. Correct the user with
PATCH /useror fix the applicant in your Sumsub account, then generate a new share token and try again. -
Copies the applicant into Bakkt's Sumsub account at your merchant's verification level, and links it to the Bakkt user. The user's date of birth and address are taken from the applicant.
-
Runs Bakkt's own review. Bakkt does not accept the approval from your Sumsub account as final. Sumsub checks the copied data against Bakkt's level, and Bakkt's compliance rules apply.
After a
204, do not import again.The
204response means that the import is complete and the review has started. From this point, wait for the result:
- Wait for KYC webhooks (recommended), and/or
- Check the status with
GET /user/kyc/applicant(Get KYC details). To confirmFULL_USER, useGET /user.Do not call
POST /user/kyc/applicant/share-tokenagain for the same user, even if the review takes some time or the user is not approved. The user now has a KYC applicant, so a second import fails withAPPLICANT_EXISTS. If more data is needed, see Finishing verification after import.
A successful import does not guarantee approval. The 204 response only means that the applicant was copied. The final status comes from Bakkt's review:
| Result | Status | What to do |
|---|---|---|
| Approved | FULL_USER | Nothing. The user can transact. |
| More data needed (for example, your level did not collect a document that Bakkt's level requires) | PENDING_KYC_DATA or KYC_PENDING | Collect the missing data in Bakkt's Sumsub account. See Finishing verification after import. |
| Rejected | SOFT_KYC_FAILED / HARD_KYC_FAILED | Same as for any other KYC flow. See Recovering from a soft failure. |
Common errors:
Error name | Cause |
|---|---|
VALIDATION_ERROR | The user is not in KYC_NEEDED status. |
APPLICANT_EXISTS | The user already has a KYC applicant. |
TOKEN_INVALID | The share token is not valid or was already used. Generate a new one. |
APPLICANT_DATA_MISMATCH | The applicant data does not match the Bakkt user. The message lists the fields. |
APPLICANT_MISSING_ADDRESS | The applicant in your Sumsub account has no address. |
APPLICANT_AGE_NOT_ELIGIBLE | The user does not meet the minimum age requirement. |
APPLICANT_IMPORT_FAILED | Sumsub refused the import for a different reason. Contact support. |
Limitations
- One time, at the start only. You can import only for a user who has no KYC applicant yet. You cannot import after KYC was started with the Sumsub Web SDK, hosted form, API-only flow, or an earlier import.
- Only real approvals. The applicant must have been approved by Sumsub's verification. Applicants that were approved manually or force-approved cannot be imported.
- A copy, not a sync. The import copies the applicant as it is at that time. Later changes in your Sumsub account do not go to Bakkt. Track the user's status only through Bakkt's KYC webhooks or
GET /user, not through your own Sumsub account.
Finishing verification after import
After the import, the user's KYC applicant is in Bakkt's Sumsub account. All further verification happens there. This applies when the review needs more data, and also when an imported user later loses FULL_USER status (for example, because a document expires). Do not update the applicant in your Sumsub account, and do not try another import. Continue against the Bakkt applicant with the collection method configured for your merchant:
- API-only: upload the requested document with
PUT /user/kyc/document, then submit it withPOST /user/kyc/verification. - Sumsub-hosted flow: get a hosted form URL from
GET /user/kyc/applicant/url, or get a token fromGET /user/kyc/applicant/tokenand render the Sumsub Web SDK. The user can then provide the requested information through Sumsub.
Non-document ID verification (U.S. only)
For U.S. users who cannot or do not want to upload identity documents, Bakkt supports a non-document verification flow that uses identity-data lookups (name, DOB, SSN, address) instead of physical documents.
- Available only for U.S. users.
- Requires
ssn,ip_address, andphonein the create-applicant payload (the same U.S.-required fields as the document flow). - Contact Bakkt support to enable this flow on your merchant account.
KYB (corporate entities)
KYB status lifecycle
The happy path:
CREATED → KYB_PENDING → ACTIVEKYB_PENDING can also resolve to REJECTED, which is the outcome of a compliance review.
| Status | Meaning | Next action |
|---|---|---|
CREATED | Corporate exists; KYB not yet submitted. | GET /corporate/{corporate_uuid}/kyb/applicant/url, then send the URL to the corporate admin. |
KYB_PENDING | KYB submitted; under compliance review. | Wait for webhook or poll GET /corporate/{corporate_uuid}. |
ACTIVE | KYB approved; corporate can transact. | — |
REJECTED | KYB rejected as a result of a compliance review. | Generally final. Contact compliance to request clarification or raise an appeal. |
SUSPENDED | Suspended manually by Bakkt compliance. | Contact support. |
DEACTIVATED | Corporate has been deactivated. | Contact support. |
REJECTEDis the only KYB failure status. Unlike KYC, KYB does not distinguish soft from hard failures.
Step 1 — Get the KYB form URL
After creating the corporate (User Management → Create a corporate), generate a hosted KYB form URL.
Endpoint: GET /corporate/{corporate_uuid}/kyb/applicant/url
const res = await fetch(
`https://sandbox.api.bakkt.com/onboarding/corporate/${corporateUuid}/kyb/applicant/url`,
{
headers: {
'Authorization': 'YOUR_API_KEY',
'bakkt-session-id': sessionId
}
}
);
const { url } = await res.json();
// Send this URL to the corporate admin
sendEmail(adminEmail, {
subject: 'Complete your KYB verification',
body: `Please complete verification: ${url}`
});Step 2 — Corporate admin completes the form
The admin completes the Sumsub-hosted form externally. The form collects:
- Company documents (certificate of incorporation, articles of association)
- Beneficial-ownership information (anyone with > 25 % ownership)
- Business activity and geographic operations
- Financial information and expected transaction volumes
- Compliance questionnaire
Step 3 — Monitor KYB status
Wait for the KYB webhook or poll the corporate object:
const res = await fetch(
`https://sandbox.api.bakkt.com/onboarding/corporate/${corporateUuid}`,
{
headers: {
'Authorization': 'YOUR_API_KEY',
'bakkt-session-id': sessionId
}
}
);
const corporate = await res.json();
if (corporate.status === 'ACTIVE') {
console.log('KYB approved — corporate can transact');
} else if (corporate.status === 'REJECTED') {
console.log('KYB rejected — contact support');
}Import an existing KYB applicant (Sumsub Reusable KYC)
If you already operate your own Sumsub account and have a verified company applicant for this corporate there, you can import it into Bakkt's Sumsub instance instead of sending the corporate through the hosted KYB form. This uses Sumsub's Reusable KYC feature.
How it works:
- In your Sumsub account, generate a share token for the verified company applicant.
- Send that token to Bakkt via the endpoint below — Bakkt's Sumsub instance ingests the verification and the corporate moves to
KYB_PENDING. - Wait for the KYB webhook (or poll the corporate) for the final
ACTIVEoutcome, exactly as in Step 3 above.
Endpoint: POST /corporate/{corporate_uuid}/kyb/applicant/import — returns 204 No Content.
await fetch(
`https://sandbox.api.bakkt.com/corporate/${corporateUuid}/kyb/applicant/import`,
{
method: 'POST',
headers: {
'Authorization': 'YOUR_API_KEY',
'bakkt-session-id': sessionId,
'Content-Type': 'application/json'
},
body: JSON.stringify({
share_token: 'sumsub-share-token-from-your-account'
})
}
);Use this instead of Step 1 — don't generate a hosted form URL for a corporate you intend to import. Importing is rejected once the corporate has reached a terminal status (
ACTIVEorREJECTED).
This requires prior coordination with Bakkt support to enable cross-account sharing in Sumsub between your Sumsub account and Bakkt's. Tokens generated against an unrelated Sumsub account will not be accepted.
Document requirements by country
Use the reference endpoint to discover which documents are accepted in a given country.
Endpoint: GET /kyc-documents/ — optional country_code query parameter.
const res = await fetch(
'https://sandbox.api.bakkt.com/onboarding/kyc-documents/?country_code=GB',
{ headers: { 'Authorization': 'YOUR_API_KEY' } }
);
const docs = await res.json();
console.log('UK documents:', docs.GB);
// {
// "passport": "FRONT",
// "id_card": "FRONT_AND_BACK",
// "driving_license": "FRONT_AND_BACK"
// }The response is always keyed by country code (e.g. docs.GB, docs.NG), even when you filter by a single country. Without country_code, you get the full map.
Page-requirement values:
| Value | Meaning |
|---|---|
FRONT | Front page only |
FRONT_AND_BACK | Both sides required |
NOT_SUPPORTED | Document type not accepted in that country |
Building dynamic UI from requirements
function getAcceptedDocuments(countryCode, docReqs) {
const docs = docReqs[countryCode] ?? {};
return Object.entries(docs)
.filter(([, requirement]) => requirement !== 'NOT_SUPPORTED')
.map(([type, pages]) => ({ type, pages }));
}
const ukDocs = getAcceptedDocuments('GB', kycRequirements);
// [
// { type: 'passport', pages: 'FRONT' },
// { type: 'id_card', pages: 'FRONT_AND_BACK' },
// { type: 'driving_license', pages: 'FRONT_AND_BACK' }
// ]Sandbox testing
The sandbox lets you simulate any KYC/KYB outcome without going through real verification.
Fast-track KYC
Endpoint: PATCH /user/kyc/verification — sandbox only.
curl -X PATCH https://sandbox.api.bakkt.com/onboarding/user/kyc/verification \
-H "Authorization: YOUR_API_KEY" \
-H "bakkt-session-id: SESSION_ID" \
-H "Content-Type: application/json" \
-d '{ "status": "FULL_USER" }'You can set any status from the lifecycle table above (KYC_NEEDED, PENDING_KYC_DATA, KYC_PENDING, SOFT_KYC_FAILED, HARD_KYC_FAILED, FULL_USER) and an optional rejection_reason for the failure statuses. See the API reference for the full rejection_reason enum.
Fast-track KYB
Endpoint: PATCH /corporate/{corporate_uuid}/kyb/verification — sandbox only.
curl -X PATCH https://sandbox.api.bakkt.com/onboarding/corporate/$CORPORATE_UUID/kyb/verification \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "ACTIVE" }'Sandbox status note: the sandbox
PATCHendpoint acceptsCREATED,KYB_PENDING,ACTIVE, andREJECTED— the same statuses used in production. When settingREJECTEDyou must also supply arejection_reason; conversely,rejection_reasonis only accepted alongsideREJECTED.
Best practices
Most common verification issues
- Same document used for ID and proof of address. The PoA must be a different document than the one used for identity verification.
- Screenshot submitted instead of a photo. Screenshots are not accepted.
- IDs: clear photos only — no scans.
- PoA: clear photos or PDF files.
- PoA document is outdated. Most PoA documents must be issued within the last 6 months. Mobile-operator documents are accepted up to 3 months old.
- Document image is cropped. All four corners of the document must be visible, even if they contain no information.
- Address mismatch. The address on the PoA must exactly match the address provided by the user. Either upload a corrected document or update the user's profile via
PATCH /user.
Document quality checklist
- Images are clear and well lit.
- All four corners of the document are visible.
- No glare or shadows.
- Text is readable.
- Documents are not expired.
- Selfies show a clear face — no sunglasses, hats, or masks.
Privacy and data handling
- KYC/KYB documents are stored by Sumsub, Bakkt's verification provider.
- Documents are encrypted at rest and in transit.
- Access is logged and audited; retention follows applicable regulatory requirements.
- Users have a right to data deletion under GDPR and equivalent regimes.
Rejection reasons
When KYC fails, kyc_reject_label on GET /user/kyc/applicant contains one or more codes describing why. Surface these to the user so they know how to fix the issue.
Document quality
| Code | Meaning |
|---|---|
LOW_QUALITY | Image too blurry or pixelated. |
INCOMPLETE_DOCUMENT | Part of document cut off. |
SCAN | Document was scanned (not allowed). |
DOCUMENT_DAMAGED | Document is torn or damaged. |
UNSATISFACTORY_PHOTOS | Overall poor image quality. |
SCREENSHOTS | Screenshot instead of photo. |
BLACK_AND_WHITE | Color photo required. |
How to fix: retake in good lighting, with all corners visible, in color, on a flat surface — no editing.
Identity-data mismatch
| Code | Meaning |
|---|---|
DATA_MISMATCH | User-entered data doesn't match the document. Often the address from the PoA. |
DOB_DATA_FORMAT_MISMATCH | Date-of-birth format mismatch. |
FULL_NAME_ADDRESS_DATA_MISSING_OR_MISMATCH | Name or address missing or doesn't match. |
DATA_NOT_FOUND_IN_SOURCE | Data could not be verified against external sources. |
How to fix: correct the user's profile via PATCH /user so the entered data matches the documents exactly, or have the user resubmit a document that matches.
Document validity
| Code | Meaning |
|---|---|
MISSING_PAGE / DOCUMENT_PAGE_MISSING | A required page is missing. |
DOCUMENT_EXPIRED | Document is past its expiry date. |
DOCUMENT_INVALID | Document type or format not recognised. |
FORGERY | Tampering detected. |
GRAPHIC_EDITOR | Image was edited / manipulated. |
NOT_DOCUMENT | The upload is not actually a document. |
DOCUMENT_DEPRIVED / DOCUMENT_DAMAGED | Document missing or damaged. |
How to fix: upload an original, unedited photo of a current, undamaged document of the correct type.
Selfie issues
| Code | Meaning |
|---|---|
BAD_SELFIE | Selfie quality issues. |
BAD_VIDEO_SELFIE | Video-selfie problems. |
BAD_FACE_MATCHING / SELFIE_MISMATCH | Face does not match the ID. |
SELFIE_WITH_PAPER | User holding paper / extra object in selfie. |
How to fix: retake in good lighting, looking directly at the camera, with no glasses, hats, or masks.
Compliance
| Code | Meaning |
|---|---|
PEP | Politically Exposed Person. |
ADVERSE_MEDIA | Negative media coverage. |
SANCTIONS | On a sanctions list. |
CRIMINAL | Criminal-record flags. |
BLACKLIST / BLOCKLIST | On a compliance blacklist. |
REGULATIONS_VIOLATIONS | Regulatory violations. |
How to fix: these are typically HARD_KYC_FAILED outcomes and require contacting support; some may allow enhanced due diligence.
Profile-data mismatches
| Code | Meaning |
|---|---|
INCONSISTENT_PROFILE | Profile data doesn't match documents. |
WRONG_ADDRESS | Address verification failed. |
REQUESTED_DATA_MISMATCH | Submitted data doesn't match the request. |
PROBLEMATIC_APPLICANT_DATA | Data quality issues. |
How to fix: ensure profile fields match the ID exactly; verify address with a recent utility bill.
For the full enum of rejection reasons, see the API reference.
Soft vs. hard failures
SOFT_KYC_FAILED— recoverable. The user can resubmit corrected documents or data.HARD_KYC_FAILED— terminal. The user cannot self-serve; merchants should route them to support.
KYB has no soft/hard split — a failed corporate review lands on REJECTED, which is generally final.
KYB verification requirements
Required documents
Corporate documentation typically required:
- Certificate of Incorporation
- Memorandum and Articles of Association
- Register of Directors
- Register of Shareholders
- Proof of business address
- Bank statements (last 3 months)
The exact list varies by jurisdiction and business type — Sumsub's hosted form drives the user through the country-specific requirements.
Beneficial ownership
For every individual with > 25 % ownership, the form collects:
- Full name
- Date of birth
- Nationality
- Address
- ID document
- Percentage ownership
Business information
- Nature of business
- Expected transaction volumes
- Source of funds
- Customer base
- Geographic operations
End-to-end KYC example
async function completeKYC(sessionId) {
await fetch('https://sandbox.api.bakkt.com/onboarding/user/kyc/applicant', {
method: 'POST',
headers: {
'Authorization': API_KEY,
'bakkt-session-id': sessionId,
'Content-Type': 'application/json'
},
body: JSON.stringify({
address: {
address_line_1: '123 Main St',
post_code: 'SW1A 1AA',
city: 'London',
country: 'GB'
},
date_of_birth: '1990-05-15',
source_of_funds: 'SALARY'
})
});
const tokenRes = await fetch(
'https://sandbox.api.bakkt.com/onboarding/user/kyc/applicant/token',
{
headers: {
'Authorization': API_KEY,
'bakkt-session-id': sessionId
}
}
);
const { token } = await tokenRes.json();
const sdk = snsWebSdk
.init(token, async () => {
const r = await fetch(
'https://sandbox.api.bakkt.com/onboarding/user/kyc/applicant/token',
{ headers: { 'Authorization': API_KEY, 'bakkt-session-id': sessionId } }
);
return (await r.json()).token;
})
.withConf({ lang: 'en' })
.on('idCheck.onError', (err) => console.error('Sumsub error', err))
.build();
sdk.launch('#kyc-container');
const interval = setInterval(async () => {
const userRes = await fetch('https://sandbox.api.bakkt.com/onboarding/user', {
headers: { 'Authorization': API_KEY, 'bakkt-session-id': sessionId }
});
const user = await userRes.json();
if (user.status === 'FULL_USER') {
console.log('KYC approved');
clearInterval(interval);
} else if (user.status === 'HARD_KYC_FAILED') {
console.log('KYC failed — contact support');
clearInterval(interval);
}
}, 10_000);
}In production, prefer Webhooks over polling — they fire as soon as the status changes.
Next steps
- Webhooks — receive real-time KYC and KYB status updates.
- User Management — create users and corporates, manage profiles.
- Authentication — session and
user-uuidheaders used in every example above. - API Reference — KYC endpoints
- API Reference — KYB endpoints
- Sumsub Web SDK documentation
Updated 24 days ago
