创建充值

异步充值接口。返回 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 对账