Skip to main content

​
接口清单（merchant-api）

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

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

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

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

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

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

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

​
4. 交易模拟接口

沙盒联调用接口：模拟卡片交易并向商户回调地址推送 Webhook。不使用 请求头中的 Api-Key / Access-Token。详见 交易模拟说明。 路径前缀：
  • 沙盒：https://sandbox-openplatform.keysecure.io/open-api/v1/simulate

​
快速导航

​
按业务流程

持卡人流程：
  1. 获取 Token → GET /merchant/token
  2. 持卡人认证申请 → POST /cardholder/apply
  3. 查询持卡人 → POST /cardholder/list 或 GET /cardholder/{cardholder_no}/info
开卡流程：
  1. 获取卡套餐/BIN → POST /card/package/list 或 POST /card/support/bins
  2. 申请开卡 → POST /card/apply
  3. 查询卡列表 → POST /card/list 或获取卡详情 → GET /card/{card_no}/detail
  4. 激活实体卡 → POST /card/active（实体卡需要）
  5. 设置 PIN → POST /card/pin/set（实体卡可选）
交易流程：
  1. 查询消费详情 → GET /consume/{consume_no}/info
  2. 查询消费列表 → POST /consume/list
账户流程（授信模式）：
  1. 查询账户信息 → GET /account/{cardholder_no}/info
  2. 执行划转 → POST /account/transfer
  3. 查询划转流水 → POST /account/transfer/list
交易模拟流程：
  1. 模拟授权 → POST /simulate/auth
  2. 模拟清算成功 / 失败 → POST /simulate/consumption_clear 或 POST /simulate/consumption_fail
  3. 模拟冲正 / 退款 → POST /simulate/reversal 或 POST /simulate/refund

​
按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 卡敏感信息

​
权限和前置条件

​
认证要求

​
前置条件

开卡前：
  • 持卡人必须存在且 KYC 已认证成功（状态为 Approved）
  • 否则返回 2002（持卡人不存在）或 2005（认证信息未通过）
卡隐私接口（5.6）：
  • 需商户开通 PCI
  • 未开通返回 1013
  • 卡状态须为 Activated
实体卡激活：
  • 卡状态须为 ToActivate
  • CVV 须 AES 加密后传入
设置 PIN：
  • 仅支持实体卡
  • 卡状态须为 Activated
  • PIN 须 AES 加密后传入

​
错误处理

所有错误响应遵循统一格式：
常见错误码（详见「附录」→「错误码」）： 更多错误码见「附录」→「错误码」章节。