跳转到主要内容
所有 API 响应均采用统一的 JSON 结构，HTTP 状态码一般为 200，通过响应体 code 判断业务成败。

​
响应结构

字段名类型描述
codenumber状态码，0-成功，非 0 为失败
msgstring描述信息（支持多语言，见下方说明）
dataobject/array/string返回数据（仅成功时返回；部分接口可能为加密字符串）

​
基础示例

成功响应： 
{
  "code": 0,
  "msg": "Success",
  "data": {
    "access_token": "your_token",
    "expired_time": 1716393600000
  }
}
失败响应： 
{
  "code": 1003,
  "msg": "IP address not allowed"
}

​
多语言支持

msg 字段支持多语言返回，通过请求头 Language 控制：
请求头值返回语言说明
zh_CN中文中文简体
en_US英文英文
不传或其他值英文（默认）默认英文
示例： 
curl --request GET \
     --url https://sandbox-openplatform.keysecure.io/open-api/v1/merchant/token \
     --header 'Api-Key: your_api_key' \
     --header 'Timestamp: 1716307200000' \
     --header 'Language: zh_CN'

​
特殊情况

​
1. 列表类接口

列表类接口的 data 结构为对象，包含 list 数组： 
{
  "code": 0,
  "msg": "Success",
  "data": {
    "list": [
      { "id": "1", "name": "item1" },
      { "id": "2", "name": "item2" }
    ]
  }
}

​
2. 卡隐私信息接口

响应 data 为加密字符串，需商户端使用 MerchantEncryptUtil 解密： 
{
  "code": 0,
  "msg": "Success",
  "data": "Base64EncodedEncryptedString..."
}
解密后得到 JSON 对象： 
{
  "card_no": "C202605220001",
  "card_unique_no": "MERCHANT_CARD_001",
  "cvv": "123",
  "pan": "4111111111111111",
  "exp_year": "2028",
  "exp_month": "12"
}

​
3. 参数校验失败

参数校验失败时，msg 会在文案前附带 snake_case 字段名，格式为 cardholder_no 请求参数不合法。 示例：
  • cardholder_no 请求参数不合法 —— 必填校验失败
  • phone_code 请求参数不合法 —— 国别码格式错误或含 + 号
  • city 仅支持使用英文填写 —— 地址字段英文校验失败
  • address_info.city 请求参数不合法 —— 嵌套对象字段校验失败

​
HTTP 状态码

HTTP 状态码说明
200请求成功（查看 code 字段判断业务成败）
400请求格式错误或参数不合法
401认证失败（Api-Key / Access-Token 无效）
403禁止访问（IP 不在白名单等）
404资源不存在
500服务器错误

​
错误码范围

范围描述
1xxx公共异常、权限异常、鉴权异常、PCI 相关
2xxx会员/持卡人相关异常
3xxx账户、划转相关异常
4xxx卡、卡交易、卡隐私相关异常
详见「附录」→「错误码」。

​
字段名规范

所有 JSON 字段名均为 snake_case（与接口参数 一致）。 示例：
  • cardholder_no —— 持卡人单号
  • card_last_no —— 卡号后四位
  • total_balance —— 账户总资产
  • consume_no —— 消费单号

​
时间戳格式

响应中的时间字段均为 Unix 毫秒时间戳（13 位数字），示例： 
{
  "time": 1716307200000,
  "expired_time": 1716393600000
}
转换示例（JavaScript）： 
const timestamp = 1716307200000; // 毫秒
const date = new Date(timestamp);
console.log(date.toISOString()); // 2024-05-21T12:00:00.000Z