API 参考

接口总览

#	接口	路径	幂等键	说明
1	列卡头	/api/v1/openapi/card_headers/list	—	查看可申请的卡头列表
2	列卡配置	/api/v1/openapi/card_configs/list	—	查看卡头下的套餐
3	列出银行卡	/api/v1/openapi/cards/list	—	列出商户名下的卡（状态/日期/余额过滤）
4	申请虚拟卡	/api/v1/openapi/card/apply	✅ 必填	异步开卡
5	首充预览	/api/v1/openapi/card/first_deposit/preview	—	试算首充手续费 / 冻结额
6	创建充值	/api/v1/openapi/card/recharge	✅ 必填	异步充值
7	查询卡片信息	/api/v1/openapi/card/info	—	状态轮询
8	Webhook 事件历史	/api/v1/openapi/webhook_events/list	—	排查 webhook 投递
9	查询所有交易明细	/api/v1/openapi/transactions/list	—	名下所有卡的交易明细
10	查询单卡交易明细	/api/v1/openapi/card/transactions/list	—	单张卡的交易明细
11	冻结卡片	/api/v1/openapi/card/freeze	—	冻结一张活跃虚拟卡
12	解冻卡片	/api/v1/openapi/card/unfreeze	—	解冻用户主动冻结的卡

通用约定

• 方法：所有接口都是 POST
• Content-Type：application/json（请求与响应均是）
• 鉴权：每次请求 4 个签名头（详见 HMAC 鉴权）
• 国际化：通过 Accept-Language: zh-CN | en-US 切换 message 文案
• 响应包络：

{
  "code": 200,           // HTTP 状态码同步
  "message": "成功",
  "message_key": "...",  // 仅错误时返回
  "data": { ... }        // 业务数据
}

分页约定

所有 */list 接口（除 /card_configs/list）支持分页：

字段	类型	默认	限制
page	int	1	≥ 1
page_size	int	20	≤ 100

响应包含：

{
  "list": [...],
  "total": 12,
  "page": 1,
  "page_size": 20,
  "total_pages": 1,
  "has_next": false,
  "has_prev": false
}