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
}