请求头参数

所有 API 请求均需在 HTTP 请求头中携带以下参数（除特殊说明外）：

字段名	描述	必填	说明
Api-Key	apiKey（商户凭证，与 IP 白名单绑定）	是*	除获取 Token 外必填；获取 Token 仅需此项
Timestamp	Unix 时间戳（毫秒）	是*	与服务器时间差须在 60 秒内，且不接受未来时间戳
Access-Token	登录标识	是*	除获取 Token 外必填；不接受未来时间戳时返回 1005
Signature	签名值	否	平台→商户回调时使用
Sign-Version	签名算法版本	否	默认 V1（回调时使用）
Timezone	时区	否	默认 UTC+8，影响列表查询时间边界
Language	响应 `msg` 语言	否	如 `zh_CN` / `en_US`；影响错误码多语言
Content-Type	请求内容类型	是	固定值：`application/json`

使用说明

认证模式

获取 Token：仅需 Api-Key + Timestamp，无需 Access-Token
其他接口：均需 Api-Key + Timestamp + Access-Token

时间校验

Timestamp 必须为 Unix 毫秒时间戳（13 位数字）
与服务器时间差须在 60 秒内，否则返回 1005（时间戳已失效）
不接受未来时间戳；时间偏差过大返回 1005

IP 白名单

请求来源 IP 须在 Api-Key 对应的 IP 白名单内
非白名单 IP 返回 1003（IP 地址不正确）

时区和列表查询

带 start_time / end_time 的列表接询建议携带 Timezone 请求头（默认 UTC+8）
影响日界计算；可选 Language: zh_CN 或 en_US 控制错误信息语言

curl 调用示例

基础示例（获取 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'

完整示例（带 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"
     }'

域名替换

下文各接口 curl 示例中的 https://api.example.com 请替换为实际 API 域名：

沙盒环境：https://sandbox-openplatform.keysecure.io
生产环境：https://openplatform.keysecure.io（请联系商务获取）

错误说明

错误码	中文描述	英文描述
1002	Api-Key 不能为空	Api-Key is required
1003	IP 地址不正确	IP address not allowed
1005	时间戳已失效	Timestamp invalid or expired
1006	Access-Token 不能为空	Access-Token is required
1007	Access-Token 已失效	Access-Token invalid or expired

接入指引

API文档

附录

使用说明

认证模式

时间校验

IP 白名单

时区和列表查询

curl 调用示例

域名替换

错误说明

​使用说明

​认证模式

​时间校验

​IP 白名单

​时区和列表查询

​curl 调用示例

​域名替换

​错误说明

使用说明

认证模式

时间校验

IP 白名单

时区和列表查询

curl 调用示例

域名替换

错误说明