2.5 钱包转入 / 转出

POST /api/v1/user/exchange/wallets/{external_player_id}/deposits
POST /api/v1/user/exchange/wallets/{external_player_id}/withdrawals

• deposits：钱包转入
• withdrawals：钱包转出

请求 Body（JSON）

字段	必填	类型	说明
currency	TRUE	string	须与该代理绑定币种一致；见支援币种列表
amount	TRUE	string	金额变动，字符串表示；单笔上限 10,000,000，最多 8 位小数
ticket_id	TRUE	string	幂等键，唯一字符串，最长 256 字符；相同 ticket_id 不会重复生效

{
  "currency": "CNY",
  "amount": "10",
  "ticket_id": "3e2178ba-269c-4649-2fdb-a2099d6479a6"
}

TIP

ticket_id 为幂等键：相同 ticket_id 重复请求时，系统直接回传首次成功时的原始响应（含当时的 balance），不会重复入账。该 balance 为首次处理时的快照，不反映当前余额，如需最新余额请调用余额查询 API。

玩家在游戏中不影响转账操作，可正常发起转入 / 转出。

响应 data

字段	类型	说明
wallet.currency	string	币种
wallet.balance	string	本次交易处理后的余额快照
created_at	string	首次处理时间（RFC 3339，纳秒精度）

{
  "code": 0,
  "message": "success",
  "data": {
    "wallet": {
      "currency": "CNY",
      "balance": "251080.82"
    },
    "created_at": "2026-06-18T05:00:02.962216637Z"
  }
}

交易失败与退款处理

IMPORTANT

在执行退款或补单前，必须先调用 交易状态查询 API 确认原始交易的最终状态，避免重复退款或对未实际扣款的交易进行退款。

遇到超时、网络异常或响应不明确时，不可直接发起退款。正确处理流程：

1. 以原始 ticket_id 调用交易状态查询 API，确认该交易是否已成功入账。
2. 确认未成功后，再以新的 ticket_id 发起退款（转入）。
3. 确认已成功则无需操作，或依业务需求另行发起退款流程。