> ## Documentation Index
> Fetch the complete documentation index at: https://docs-payment-merchant.keysecure.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 请求头参数

所有 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）：

```bash theme={null}
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）：

```bash theme={null}
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 |