2.5 钱包转入 / 转出

http

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 不会重复生效

json

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

TIP

ticket_id 为幂等键：相同 ticket_id 重复请求时，在请求内容（amount、currency）完全一致的前提下，系统直接回传首次成功时的原始响应（含当时的 balance），不会重复入账；内容不一致则返回 10050。该 balance 为首次处理时的快照，不反映当前余额，如需最新余额请调用余额查询 API。

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

响应 data

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

json

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

幂等与去重规则

IMPORTANT

ticket_id 的去重键为「玩家 + ticket_id + 交易类型」，含交易类型。同一个 ticket_id 用在转入与转出会各自生效一次——它不是全局唯一的交易编号，请勿跨方向复用。

去重键不含金额与币种，两者是与首次记录逐笔比对的：

情境	结果
相同 ticket_id，`amount` 与 `currency` 完全一致	回传首次成功的原始响应，不重复入账
相同 ticket_id，`amount` 或 `currency` 不同	返回 `10050`，不可重试；如需变更金额请改用新的 `ticket_id`
相同 ticket_id 的另一笔请求仍在处理中	返回 `10040`；不会重复入账，稍后以完全相同的请求重送即可取得首次结果

TIP

X-Idempotency-Key 不参与转账的幂等判定——转账的幂等键是 ticket_id。因此同一组 X-Idempotency-Key 用在 deposits 与 withdrawals 上不会互相影响，它在本接口仅是必填的签名字段。

仅登录 API 会用该 header 做幂等：相同 key 在 token 有效期内会返回同一个 token，因此每次登录请求请带入新的 key。

转账相关错误码

code	含义	处理方式
10040	相同 ticket_id 的另一笔请求正在处理中	不会重复入账。稍后以完全相同的请求重送，即可取得首次处理结果
10050	相同 ticket_id 已被使用，但本次带入的金额或币种不同	不可重试。如需变更金额，请改用新的 `ticket_id`
20160	玩家余额不足，无法完成转出	确认余额后再发起

10050 的 message 会指出不符的字段与两次的数值，例如：

ticket_id already used with a different amount (recorded 100, requested 100.5)

交易失败与退款处理

IMPORTANT

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

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

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

2.5 钱包转入 / 转出 ​

请求 Body（JSON） ​

响应 data ​

幂等与去重规则 ​