建立充值

非同步充值介面。返回 transaction_id 與初始 status: 1 (processing)；最終結果透過 card.recharged / card.recharge_failed webhook 推送。

端點

項	值
Method	POST
Path	/api/v1/openapi/card/recharge
鑑權	HMAC
冪等鍵	必填 Idempotency-Key 頭

請求欄位

欄位	型別	必填	說明
card_id	string	✅	card_<id> 格式
amount	string (decimal)	✅	充值金額（卡內幣種單位）

請求示例

{ "card_id": "card_12345", "amount": "100.00" }

請求頭必須含：

Idempotency-Key: 7b3e9d5c-1a2b-4f3e-8c7d-6f5e4a3b2c1d

響應欄位

欄位	型別	說明
transaction_id	string	txn_<...> 格式
card_id	string	回顯
amount	string	客戶請求金額
currency	string	卡內幣種
status	int	1=processing 2=success 3=failed
status_desc	string	英文描述
created_at	string	RFC3339 時間

響應示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "transaction_id": "txn_OO20260429120000xyz",
    "card_id": "card_12345",
    "amount": "100.00",
    "currency": "USD",
    "status": 1,
    "status_desc": "processing",
    "created_at": "2026-04-29T12:00:00Z"
  }
}

典型錯誤

HTTP	message_key	說明
400	amount_required	amount 缺失
400	insufficient_balance	餘額不足
400	openapi_invalid_card_id	卡 ID 錯誤
400	openapi_idempotency_key_required	缺冪等鍵
401	openapi_invalid_credentials	鑑權失敗
404	card_not_found	卡不存在
409	openapi_idempotency_key_conflict	同 key 不同 body
500	openapi_recharge_failed	服務端異常

注意事項

• 不要在前端用同一個 Idempotency-Key 重複發起多筆不同金額充值（會 409）
• 同 key 的安全重試（網路重試）→ 返回原響應
• transaction_id 是 txn_<...>（視為不透明字串），請用此值與 webhook 中的 transaction_id 對賬