KYCImplementation GuideCountry-Specific Documents

Chinese Documents

The FrankieOne KYC v2 API supports some Chinese documents for identity verification. This guide provides details on how to handle these documents effectively.

Supported Chinese Documents

The FrankieOne KYC v2 API supports the following Chinese documents:

DocumentCode
National IDNATIONAL_ID

Chinese National ID Card (身份证)

Chinese National ID Cards (身份证) are official identification documents issued by the Chinese government that confirm an individual’s identity and citizenship. They include personal details such as the individual’s name, date of birth, ID card number, and expiration date.

Required Fields

Field NameFieldNotes
Document TypetypeMust be NATIONAL_ID.
CountrycountryMust be CHN (China).
Date of BirthdateOfBirthFormat: YYYY-MM-DD.
Family NamefamilyNamePinyin family name in uppercase (e.g., ZHANG).
Given NamegivenNamePinyin given name (may include middle name), in uppercase (e.g., WEIMING).
Chinese NamehomeCountryFullNameFull name in Chinese characters, provided in supplementaryData.homeCountryFullName.
  • Always provide both Pinyin and Chinese character versions of the name.
  • Maintain correct character order in both formats.
  • Use uppercase for all Pinyin names.
  • Ensure UTF-8 encoding for Chinese characters.
  • All fields must be completed accurately to avoid validation errors.

Name Handling Guidelines:

Provide the applicant’s name in Pinyin using uppercase letters, matching the order on the ID card.

1{
2  "familyName": "ZHANG",     // Family name in uppercase Pinyin
3  "givenName": "WEIMING"     // Given name (and middle name, if any) in uppercase Pinyin
4}
  • Use uppercase letters for all Pinyin names.
  • Ensure the order and spelling match the official ID card.
  • Do not include spaces or special characters.

Provide the full name in Chinese characters exactly as it appears on the ID card, using UTF-8 encoding.

1{
2  "supplementaryData": {
3    "homeCountryFullName": "张伟明" // Full name in Chinese characters
4  }
5}
  • The Chinese name must match the ID card precisely, including character order.
  • Place this value in supplementaryData.homeCountryFullName.
  • Ensure correct encoding to avoid data loss.

Example Document Structure

1{
2  "document": {
3    "class": "IDENTITY", // Document class type, always "IDENTITY" for ID cards
4    "documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7", // Unique identifier for this document in your system
5    "primaryIdentifier": "000734130", // Official 18-digit National ID number (should be 18 digits, no spaces)
6    "type": "NATIONAL_ID", // Document type code, must be "NATIONAL_ID"
7    "country": "CHN" // Country code, must be "CHN" for China
8  },
9  "supplementaryData": {
10    "type": "NATIONAL_ID", // Supplementary document type, repeat "NATIONAL_ID"
11    "homeCountryFullName": "张伟明" // Full name in Chinese characters, as shown on the ID
12  }
13}
Important Considerations for National ID

The Chinese National ID number contains encoded information including region code, birth date, sequence number, and checksum digit. Ensure the full number is provided without spaces or special characters.

Common validation issues to avoid:

  • Using incorrect order or casing for Pinyin names
  • Omitting the Chinese character version of the name
  • Missing or incorrectly formatted date of birth (YYYY-MM-DD)
  • Providing an invalid or incomplete ID number (should be 18 digits, no spaces)