KYC requirements

Most flows require validating a user’s Know Your Customer (KYC) level before creating an order. The high-level steps are:

1. Call Get user KYC state with a user’s email and a country.

2. Inspect the returned kycRules to see which KYC tier (basic, advanced, etc.) is required for the intended deposit or payout amounts and currency types.

3. If the user hasn’t already passed the needed tier (passedKycType), prompt them for the document listed in kycDocuments and gather the associated requiredFields.

4. Submit the collected data via Submit user KYC. Continue polling Get user KYC state until currentKycStatus becomes approved.

Tip: The sample data below shows that payouts ≥ 100 USD in crypto require advanced KYC. Your environment will return thresholds appropriate for the country, currency, and operation type.

Sample Get user KYC state response

{
  "passedKycType": null,
  "reachedKycLimit": false,
  "currentKycStatus": null,
  "currentKycStatusDescription": null,
  "kycDocuments": [
    {
      "_id": "67da909b739fc481aa525c43",
      "type": "basic",
      "title": "Voter ID",
      "value": "VOTER_ID",
      "requiredFields": [
        { "key": "first_name", "type": "string", "label": "First Name", "required": true },
        { "key": "last_name", "type": "string", "label": "Last Name", "required": true },
        { "key": "dob", "type": "date", "label": "Date of birth", "required": true },
        {
          "key": "id_number",
          "type": "string",
          "label": "ID number",
          "required": true,
          "format": "0000000000000000000",
          "regexp": "^[a-zA-Z0-9 ]{9,29}$",
          "regexpFlags": "i"
        }
      ]
    },
    {
      "_id": "67da93c0dfd3a00f3380b857",
      "type": "advanced",
      "title": "Driving License",
      "value": "DRIVERS_LICENSE",
      "requiredFields": [
        { "key": "first_name", "type": "string", "label": "First Name", "required": true },
        { "key": "last_name", "type": "string", "label": "Last Name", "required": true },
        { "key": "dob", "type": "date", "label": "Date of birth", "required": true },
        { "key": "images", "type": "smile-identity-images", "label": "Verification images", "required": true }
      ]
    }
  ],
  "kycRules": [
    {
      "operationType": "deposit",
      "currencyType": "crypto",
      "min": 0,
      "max": 100,
      "type": "basic"
    },
    {
      "operationType": "payout",
      "currencyType": "crypto",
      "min": 100,
      "max": "Infinity",
      "type": "advanced"
    }
  ]
}

The "advanced" KYC document requires images. Submit them as an array of objects with image_type_id and image URL. Image URLs must be publicly accessible or contain the image data as a base64-encoded string. The "image_type_id" can accept the following values:

• 0: Selfie

• 1: Document front

• 5: Document back

Sample Submit user KYC request

{
  "userEmail": "[email protected]",
  "countryIsoCode": "NG",
  "documentId": "67da93c0dfd3a00f3380b857",
  "userFields": {
    "first_name": "John",
    "last_name": "Doe",
    "dob": "1990-01-01",
    "images": [
      { "image_type_id": 0, "image": "https://cdn.com/selfie.jpg" },
      { "image_type_id": 1, "image": "https://cdn.com/front.jpg" },
      { "image_type_id": 5, "image": "https://cdn.com/back.jpg" }
    ]
  }
}

Once the user’s KYC status is approved at or above the required tier, proceed with quoting and order creation.