Skip to main content
All API requests must include the following parameters in the HTTP request headers (unless otherwise specified):
Field NameDescriptionRequiredNotes
Api-KeyapiKey (merchant credential, bound to IP whitelist)Yes*Required for all except Get Token; Get Token only needs this field
TimestampUnix timestamp in millisecondsYes*Deviation from server time must be within 60 seconds, and future timestamps are not accepted
Access-TokenLogin tokenYes*Required for all except Get Token; returns 1005 when future timestamp is rejected
SignatureSignature valueNoUsed for platform → merchant callbacks
Sign-VersionSignature algorithm versionNoDefaults to V1 (used in callbacks)
TimezoneTimezoneNoDefaults to UTC+8, affects list query time boundaries
LanguageResponse msg languageNoe.g. zh_CN / en_US; affects multilingual error messages
Content-TypeRequest content typeYesFixed value: application/json

​
Usage Notes

​
Authentication Modes

  • Get Token: Only requires Api-Key + Timestamp; no Access-Token needed.
  • Other interfaces: All require Api-Key + Timestamp + Access-Token.

​
Timestamp Validation

  • Timestamp must be a Unix millisecond timestamp (13 digits).
  • Deviation from server time must be within 60 seconds, otherwise 1005 (timestamp invalid or expired) is returned.
  • Future timestamps are not accepted; excessive deviation returns 1005.

​
IP Whitelist

  • The requesting IP must be in the IP whitelist associated with the Api-Key.
  • Non-whitelisted IPs return 1003 (IP address not allowed).

​
Timezone and List Queries

  • List interfaces with start_time / end_time should include the Timezone header (defaults to UTC+8).
  • This affects day boundary calculation; use Language: zh_CN or en_US to control the language of error messages.

​
curl Examples

Basic example (Get Token): 
curl --request GET \
     --url https://sandbox-openplatform.keysecure.io/open-api/v1/merchant/token \
     --header 'Content-Type: application/json' \
     --header 'Api-Key: your_api_key' \
     --header 'Timestamp: 1716307200000'
Full example (with Access-Token): 
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' \
     --header 'Timezone: UTC+8' \
     --header 'Language: zh_CN' \
     --data '{
       "cardholder_no": "",
       "cardholder_unique_no": "MERCHANT_USER_001",
       "sumsub_share_token": "your_sumsub_share_token"
     }'

​
Domain Replacement

Replace https://api.example.com in the curl examples below with the actual API domain:
  • Sandbox environment: https://sandbox-openplatform.keysecure.io
  • Production environment: https://openplatform.keysecure.io (contact your account manager to obtain)

​
Error Codes

CodeChinese DescriptionEnglish Description
1002Api-Key 不能为空Api-Key is required
1003IP 地址不正确IP address not allowed
1005时间戳已失效Timestamp invalid or expired
1006Access-Token 不能为空Access-Token is required
1007Access-Token 已失效Access-Token invalid or expired