Skip to navigation

Transak KYC using APIs

Collect KYC details in your own interface and submit them to Transak with the Whitelabel KYC APIs.
View as Markdown

This document provides a detailed explanation of KYC flows, covering Simple KYC, Standard KYC and Enhanced KYC, along with the required API interactions and processes. KYC is a mandatory step in compliance with regulatory requirements before users can place orders on Transak.

KYC Flow Chart

KYC Chart
KYC TypeRequirements
Simple KYCPersonal Details, Address Details, SSN (for US users only), FCA (for UK users only) (not available to EEA users)
Standard KYCPersonal Details, Address Details, SSN (for US users only), FCA (for UK users only), MiCA Consent (for EEA users who completed KYC before MiCA), Source of Income (for EEA users), ID Proof Upload, Liveness Check (Selfie)
Enhanced KYCPersonal Details, Address Details, SSN (for US users only), FCA (for UK users only), MiCA Consent (for EEA users who completed KYC before MiCA), Source of Income, Proof Document Upload, ID Proof Upload, Liveness Check (Selfie)

Fetch KYC Requirement Based on Quote ID

The KYC requirements are determined dynamically using the quote ID. Transak supports multi-level KYC, meaning different users may have different requirements based on country, regulations, and transaction limits.

When fetching KYC Requirement, there can be four statuses:

KYC StatusDescription
APPROVEDKYC is done and approved by Transak. User can proceed with the order creation flow.
SUBMITTEDKYC personal and address details or additional forms are submitted.
NOT_SUBMITTEDKYC personal and address details are not submitted.
ADDITIONAL_FORMS_REQUIREDAll details are submitted but some more additional requirements need to be fulfilled for KYC approval.
  • Personal Details → First name, last name, mobile number, and date of birth.
  • Address Details → User’s residential details (address, city, state, zip code).
  • Purpose of Usage → Used for compliance with regulations.
  • ID Proof → Required only if Standard or Enhanced KYC is needed.
  • SSN → Required only for US KYC users.
  • FCA → Required only for UK KYC users.
  • MiCA Consent → Required only for existing EEA KYC users who completed KYC before MiCA.
  • Source of Income → Required if Enhanced KYC is needed, and for all EEA KYC users (with employment status and nationality).
  • Proof Document → Required only if Enhanced KYC is needed.

All forms must be submitted in the sequence provided in the Get Additional Requirements API.

KYC Flow - Step-by-Step Guide

1

Fetch KYC Status

Call Get KYC Requirement with the quoteId to fetch current status of the user’s KYC.

ConditionNext step

data.kyc.status = APPROVED

Move forward with the Create Order Flow

data.kyc.status = NOT_SUBMITTED

Follow Step 2

data.kyc.status = ADDITIONAL_FORMS_REQUIRED

Follow Step 3

EEA users: a user who was APPROVED before MiCA can return ADDITIONAL_FORMS_REQUIRED or NOT_SUBMITTED until they complete the MiCA steps or a KYC refresh. Do not cache the KYC status. Call this step with a fresh quoteId before every order.

2

Patch User Details

Call Patch User Details to collect and submit the user’s personal and address information.

Once submitted, return to Step 1 to re-fetch the updated KYC status.

3

Get Additional Requirements

Call Get Additional Requirements to check which forms still need to be completed.

Check if additional information must be provided for KYC Approval. Multiple forms may appear and must be submitted in the sequence provided in the API response:

  1. If type = PURPOSE_OF_USAGE → Follow Step 4
  2. If type = IDPROOF → Follow Step 5
  3. If type = US_SSN → Follow Step 6
  4. If type = FCA → Follow Step 7
  5. If type = CONSENT → Follow Step 8
  6. If type = SOURCE_OF_INCOME → Follow Step 9
  7. If type = DOCUMENT_PROOF → Follow Step 10

1. CONSENT is usually returned first. Existing EEA users get the CONSENT form. Process forms in the order they are returned. New EEA users, who complete KYC after MiCA, never get CONSENT: their first forms are the usual ones, such as PURPOSE_OF_USAGE.

{
"data": {
"formsRequired": [
{ "type": "CONSENT" }
]
}
}

After the consent is submitted in Step 8, call Get Additional Requirements again to get the next forms. Do this after each form you submit: more forms (for example IDPROOF) can appear until Get KYC Requirement returns APPROVED.

2. SOURCE_OF_INCOME has extra options for EEA users. Besides the source of funds options, metadata includes employmentStatusOptions and countryOfCitizenshipOptions. Build a dropdown from each list and send the selected value in Step 9.

Transak decides whether a new user is an EEA user from the address country sent in Step 2 (Patch User Details), not from the fiat currency. Until an EEA address is submitted, the SOURCE_OF_INCOME form and its EEA options are not returned, so call Get Additional Requirements again after Step 2.

{
"data": {
"formsRequired": [
{
"type": "SOURCE_OF_INCOME",
"metadata": {
"sourceOfFundsTypeOptions": [
{ "name": "Salary payments", "value": "salary_payment" }
],
"employmentStatusOptions": [
{ "name": "Student", "value": "student" },
{ "name": "Retired", "value": "retired" },
{ "name": "Unemployed", "value": "unemployed" },
{ "name": "Self Employed", "value": "self_employed" },
{ "name": "Junior/Entry-Level Employee", "value": "junior_entry_level_employee" },
{ "name": "Mid-Level Employee", "value": "mid_level_employee" },
{ "name": "Management Role", "value": "management_role" },
{ "name": "Executive Role", "value": "executive_role" }
],
"countryOfCitizenshipOptions": [
{ "name": "Austria", "value": "AT" },
{ "name": "Germany", "value": "DE" },
{ "name": "India", "value": "IN" }
]
}
}
]
}
}
OptionsValues
sourceOfFundsTypeOptionssalary_payment, savings, property_sale, sale_of_crypto, inheritance, pension, loan, dividends, gift_or_donation, income_from_services_provided, stock_share_sale (shortened in the example above). options carries the same list for older integrations.
employmentStatusOptionsstudent, retired, unemployed, self_employed, junior_entry_level_employee, mid_level_employee, management_role, executive_role
countryOfCitizenshipOptionsAll countries, as ISO 3166-1 alpha-2 codes (for example DE, FR, IN). The user can be a national of any country, not only an EEA country. Shortened in the example above.

EEA users submit employmentStatus and countryOfCitizenship on the SOURCE_OF_INCOME form, together with the source of funds. They do not get a separate form for these fields.

3. ID proof may be requested again. If the user’s ID document has expired or their KYC is older than 12 months, IDPROOF can be returned. Handle it as in Step 5.

MiCA Changes for EEA Users
4

Post Purpose of Usage

Call Update Purpose of Usage to record the user’s reason for buying crypto.

5

Complete ID Proof & Liveness Check (For Standard KYC)

Redirect the user to the Transak-hosted KYC Widget using the kycUrl returned in the Additional Requirements response.

ID Proof Upload
action

Upload a photo ID — Passport, Driver’s License, or National ID

Liveness Check
action

Submit a selfie for real-time identity validation

6

Submit SSN (US Users Only)

Call Submit SSN to validate the user’s identity using their Social Security Number.

7

Submit FCA (UK Users Only)

FCA (Financial Conduct Authority) compliance is required for all UK users. The flow covers three sequential steps — investor categorization, a compliance agreement, and a risk assessment.

See the dedicated guide for the full API sequence, status handling, and step-by-step integration details:

How to Submit KYC FCA Requirements
9

Submit Source of Income (For Enhanced KYC and EEA Users)

Call Submit Source of Income to capture the user’s primary income source. Required for higher transaction limits, and for all EEA users. EEA users must also send employmentStatus and countryOfCitizenship.

10

Upload Proof Document (For Enhanced KYC)

Call Upload Proof Document to submit supporting documentation for the income source selected in the previous step.

Different KYC Levels Guide

KYC TypeKYC StatusUser StatusAction
nullNOT_SUBMITTEDACTIVECall GET KYC Requirement API → Complete KYC Forms
SIMPLESUBMITTEDACTIVEPoll GET User Details API
SIMPLEAPPROVEDACTIVECall GET KYC Requirement API → If APPROVED place order → If ADDITIONAL_FORMS_REQUIRED call Get Additional Requirements API → If NOT_SUBMITTED patch user details
SIMPLEREJECTEDACTIVECall GET KYC Requirement API → If ADDITIONAL_FORMS_REQUIRED call Get Additional Requirements API → If NOT_SUBMITTED patch user details
STANDARDSUBMITTEDACTIVEPoll GET User Details API
STANDARDAPPROVEDACTIVECall GET KYC Requirement API → If APPROVED place order → If ADDITIONAL_FORMS_REQUIRED call Get Additional Requirements API
STANDARDREJECTEDACTIVECall GET KYC Requirement API → If APPROVED place order → If ADDITIONAL_FORMS_REQUIRED call Get Additional Requirements API → If NOT_SUBMITTED patch user details
STANDARDREJECTEDDISABLEDShow static screen — Contact Support
ENHANCEDSUBMITTEDACTIVEPoll GET User Details API
ENHANCEDAPPROVEDACTIVECall GET KYC Requirement API → If APPROVED place order
ENHANCEDREJECTEDACTIVECall GET KYC Requirement API → If APPROVED place order → If ADDITIONAL_FORMS_REQUIRED call Get Additional Requirements API → If NOT_SUBMITTED patch user details
ENHANCEDREJECTEDDISABLEDShow static screen — Contact Support

API Overview

See Error Codes for the KYC errors (30xx) these APIs return.