接口清单 - Payment-guide

接口清单（merchant-api）

所有接口路径前缀均为 /open-api。除 获取 Token 外，其余接口均需请求头：Api-Key、Timestamp、Access-Token。

1. 通用接口（授信 / 授权模式均可调用）

授信模式和授权模式均支持的通用接口。

模块	方法	路径	说明
认证	GET	/open-api/v1/merchant/token	获取 Access-Token（仅需 Api-Key，无需 Access-Token）
持卡人	POST	/open-api/v1/cardholder/apply	持卡人认证申请
持卡人	POST	/open-api/v1/cardholder/list	持卡人列表
持卡人	GET	/open-api/v1/cardholder//info	持卡人详情
卡	POST	/open-api/v1/card/apply	开卡（授信传 `package_no`，授权传 `card_bin_no`）
卡	POST	/open-api/v1/card/list	卡列表
卡	GET	/open-api/v1/card//detail	卡详情
卡	GET	/open-api/v1/card//private/info	卡隐私 JSON（`data` 为AES加密字符串）
卡	POST	/open-api/v1/card/active	实体卡激活（`cvv` 须 AES 加密）
卡	POST	/open-api/v1/card/status/update	修改卡状态（Frozen / Activated / Delete）
卡	POST	/open-api/v1/card/pin/set	设置实体卡 PIN（`pin` 须 AES 加密）
消费	GET	/open-api/v1/card/consume//info	消费详情
消费	POST	/open-api/v1/card/consume/list	消费列表
PCI	GET	/open-api/v1/merchant/client//token	颁发 PCI Client Access Token（ifram集成时调用）

2. 授信模式接口（CREDIT_EXTENSION）

仅对接模式为 授信扩展 的商户可调用。

模块	方法	路径	说明
账户	POST	/open-api/v1/account/transfer	持卡人金额划转（固定 TUSDT）
账户	GET	/open-api/v1/account//info	持卡人账户列表
账户	POST	/open-api/v1/account/transfer/list	账户划转流水列表
卡	POST	/open-api/v1/card/package/list	卡套餐列表

3. 授权模式接口（AUTHORIZATION）

仅对接模式为授权的商户可调用。

模块	方法	路径	说明
卡	POST	/open-api/v1/card/support/bins	支持的卡 BIN 列表

4. 交易模拟接口（Webhook 造数）

联调/测试用接口，查库组包后向业务系统模拟 Webhook 回调。不使用 请求头参数中的 Api-Key / Access-Token 鉴权。路径前缀：

沙盒：https://sandbox-openplatform.keysecure.io/open-api/v1/simulate

模块	方法	路径后缀	说明
模拟	POST	/auth	模拟授权
模拟	POST	/consumption_clear	模拟消费清算成功
模拟	POST	/consumption_fail	模拟消费失败
模拟	POST	/reversal	模拟冲正/撤销
模拟	POST	/refund	模拟退款

快速导航

按业务流程

持卡人流程：

获取 Token → GET /merchant/token
持卡人认证申请 → POST /cardholder/apply
查询持卡人 → POST /cardholder/list 或 GET /cardholder/{cardholder_no}/info

开卡流程：

获取卡套餐/BIN → POST /card/package/list 或 POST /card/support/bins
申请开卡 → POST /card/apply
查询卡列表 → POST /card/list 或获取卡详情 → GET /card/{card_no}/detail
激活实体卡 → POST /card/active（实体卡需要）
设置 PIN → POST /card/pin/set（实体卡可选）

交易流程：

查询消费详情 → GET /consume/{consume_no}/info
查询消费列表 → POST /consume/list

账户流程（授信模式）：

查询账户信息 → GET /account/{cardholder_no}/info
执行划转 → POST /account/transfer
查询划转流水 → POST /account/transfer/list

按HTTP方法

GET 方法：

/merchant/token —— 获取 Token
/cardholder/{cardholder_no}/info —— 持卡人详情
/card/{card_no}/detail —— 卡详情
/card/{card_no}/private/info —— 卡隐私信息（PCI）
/consume/{consume_no}/info —— 消费详情
/account/{cardholder_no}/info —— 账户信息
/merchant/client/{card_no}/token —— PCI Client Token

POST 方法：

/cardholder/apply —— 持卡人申请
/cardholder/list —— 持卡人列表
/card/apply —— 开卡申请
/card/list —— 卡列表
/card/active —— 卡激活
/card/status/update —— 修改卡状态
/card/pin/set —— 设置 PIN
/card/package/list —— 卡套餐（授信）
/card/support/bins —— 支持 BIN（授权）
/consume/list —— 消费列表
/account/transfer —— 划转（授信）
/account/transfer/list —— 划转流水（授信）
/merchant/pci/card/detail —— PCI 卡敏感信息

权限和前置条件

认证要求

接口	需要 Api-Key	需要 Access-Token	说明
获取 Token	✓	✗	仅需 Api-Key + Timestamp
其他接口	✓	✓	需要完整认证

前置条件

开卡前：

持卡人必须存在且 KYC 已认证成功（状态为 Approved）
否则返回 2002（持卡人不存在）或 2005（认证信息未通过）

卡隐私接口（5.6）：

需商户开通 PCI
未开通返回 1013
卡状态须为 Activated

实体卡激活：

卡状态须为 ToActivate
CVV 须 AES 加密后传入

设置 PIN：

仅支持实体卡
卡状态须为 Activated
PIN 须 AES 加密后传入

错误处理

所有错误响应遵循统一格式：

{
  "code": 1003,
  "msg": "IP address not allowed"
}

常见错误码（详见「附录」→「错误码」）：

错误码	含义	常见原因
1003	IP 地址不正确	请求 IP 不在白名单内
1005	时间戳已失效	时间戳与服务器偏差超过 60 秒
1007	Access-Token 已失效	Token 已过期或无效
2002	持卡人不存在	持卡人不存在
4005	当前卡状态不允许此操作	卡状态不支持该操作

更多错误码见「附录」→「错误码」章节。

​接口清单（merchant-api）

​1. 通用接口（授信 / 授权模式均可调用）

​2. 授信模式接口（CREDIT_EXTENSION）

​3. 授权模式接口（AUTHORIZATION）

​4. 交易模拟接口（Webhook 造数）

​快速导航

​按业务流程

​按HTTP方法

​权限和前置条件

​认证要求

​前置条件

​错误处理