curl --request POST \
--url https://sandbox-openplatform.keysecure.io/open-api/v1/cardholder/apply \
--header 'Content-Type: application/json' \
--header 'Api-Key: your_api_key' \
--header 'Timestamp: 1716307200000' \
--header 'Access-Token: your_access_token' \
--data '{
"cardholder_no": "",
"cardholder_unique_no": "MERCHANT_USER_001",
"sumsub_share_token": "your_sumsub_share_token"
}'
{
"code": 0,
"msg": "Success",
"data": {
"cardholder_no": "",
"cardholder_unique_no": ""
}
}
Cardholder
Cardholder Authentication Application
POST
/
open-api
/
v1
/
cardholder
/
apply
curl --request POST \
--url https://sandbox-openplatform.keysecure.io/open-api/v1/cardholder/apply \
--header 'Content-Type: application/json' \
--header 'Api-Key: your_api_key' \
--header 'Timestamp: 1716307200000' \
--header 'Access-Token: your_access_token' \
--data '{
"cardholder_no": "",
"cardholder_unique_no": "MERCHANT_USER_001",
"sumsub_share_token": "your_sumsub_share_token"
}'
{
"code": 0,
"msg": "Success",
"data": {
"cardholder_no": "",
"cardholder_unique_no": ""
}
}
Creates or updates a cardholder KYC authentication application.
KYC authentication is unavailable in certain restricted regions. Before submitting an application, review the KYC restricted-region list in Restricted Scenarios/Regions.
KYC reviews take time to complete: approximately 1 business day in the production environment and approximately 10 minutes in the sandbox environment. If a review remains pending significantly longer, contact technical support.
Request Headers
string
required
apiKey (merchant credential, bound to IP whitelist)
string
required
Unix timestamp in milliseconds. The deviation from the server time must be within 60 seconds, and future timestamps are not accepted.
string
required
Login token (required for all interfaces except Get Token).
string
default:"application/json"
Fixed to
application/jsonRequest Body
string
Cardholder order number (required when updating authentication).
string
required
Merchant-side unique cardholder number.
string
required
Sumsub shareToken.
- Create new: Do not pass
cardholder_no; providecardholder_unique_no+sumsub_share_token. - Update authentication: Pass
cardholder_no, andcardholder_unique_nomust match the record on the platform.
Field Validation Guidelines
Information can be entered in other languages in Sumsub. The following fields must be available from theshareToken.
Sumsub generates the corresponding English fields, and the generated English fields must meet the following rules.
- Street / City / State or Province: Validation fails if the value is empty, contains only digits, or contains only one character after spaces are removed. By default, symbols are also removed and the value is checked again.
- Digits only:
^\d+$ - Remove symbols:
[^\p{L}\p{N}]
- Digits only:
- Postal code: An empty value passes validation. A non-empty value must match the lenient postal-code pattern (approximately 3–10 alphanumeric characters, with spaces or hyphens allowed in the middle).
^[A-Za-z0-9][A-Za-z0-9\-\s]{1,8}[A-Za-z0-9]$
- Full address: Validation fails if the value is empty or does not match the address pattern.
^[0-9a-zA-Z\u4e00-\u9fa5,， ]+$
- Name: Validation fails if the value does not match the Chinese/English letters and spaces pattern.
^[\u4e00-\u9fa5a-zA-Z ]+$
- Email format: Validation fails if the value is empty or does not match the email pattern.
^[A-Za-z0-9.\_%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$
- Email consistency: When a registered user exists, the email must match the registered email, ignoring case. This check is skipped when creating a cardholder without an associated user.
- Phone number: Validation fails if the value is empty or is not a valid international phone number.
- Document type: Only
ID_CARD/PASSPORTare allowed. No regular expression is used; values are compared as case-insensitive strings. - Gender: Male or female.
- Identity document photo: The photo must be clear and legible. ID cards and passports are currently supported. Submit the applicable document according to the KYC restricted-region requirements.
- Proof of address: Required for certain countries.
Response Parameters
number
Response status code.
0 indicates success.string
Response message.
object
curl --request POST \
--url https://sandbox-openplatform.keysecure.io/open-api/v1/cardholder/apply \
--header 'Content-Type: application/json' \
--header 'Api-Key: your_api_key' \
--header 'Timestamp: 1716307200000' \
--header 'Access-Token: your_access_token' \
--data '{
"cardholder_no": "",
"cardholder_unique_no": "MERCHANT_USER_001",
"sumsub_share_token": "your_sumsub_share_token"
}'
{
"code": 0,
"msg": "Success",
"data": {
"cardholder_no": "",
"cardholder_unique_no": ""
}
}