转入 / 转出

POST {API_URL}/v1/transfers

Idempotency-Key 必须与 body 中的 external_id 完全相同。仅适用于转账钱包商户。

请求参数（body）

参数	必填	类型	说明
external_id	是	string	商户订单号，字符集 [A-Za-z0-9._:-]，长度 1–128，永久唯一
player_id	是	string	平台玩家 ID（UUID），来自创建或取得玩家
currency	是	string	币种代码
direction	是	string	IN：商户转入平台；OUT：平台转出给商户
amount	是	decimal string	大于 0，小数位数不超过币种的 decimal_scale

{
  "external_id": "order-20260923-0001",
  "player_id": "0192f6a4-3c1e-7b2a-9d40-5e8f1a2b3c4d",
  "currency": "USD",
  "direction": "IN",
  "amount": "100.00"
}

这就是签名示例中使用的请求。

成功响应 201

字段	类型	说明
transaction_id	string	平台交易 ID，用于查单和对账
external_id	string	与请求相同
status	string	SUCCEEDED、FAILED、PENDING 或 UNKNOWN
direction	string	与请求相同
amount	decimal string	与请求相同
currency	string	与请求相同
created_at	string	UTC RFC3339

{
  "data": {
    "transaction_id": "0192f6c1-2b3a-7d4e-8f50-6a7b8c9d0e1f",
    "external_id": "order-20260923-0001",
    "status": "SUCCEEDED",
    "direction": "IN",
    "amount": "100.00",
    "currency": "USD",
    "created_at": "2026-09-23T08:00:00Z"
  },
  "request_id": "0192f6c1-req-0001"
}

HTTP 201 不代表资金成功

201 只表示平台已经登记了这笔交易，资金结果要看 status。PENDING 或 UNKNOWN 时，请查询交易状态，直到进入 SUCCEEDED 或 FAILED。

失败响应

HTTP	error.code	说明
404	RESOURCE_NOT_FOUND	玩家不存在或不属于当前商户
409	INSUFFICIENT_FUNDS	转出时平台余额不足。没有扣款
409	FUNDS_UNAVAILABLE	玩家有结果未确认的资金占用，暂时不能转出。稍后重试
409	IDEMPOTENCY_CONFLICT	同一个 external_id 已用于不同内容的请求
409	REQUEST_IN_PROGRESS	同一请求还在处理中，请查单
422	VALIDATION_FAILED	金额精度超出 decimal_scale，或 Idempotency-Key 与 external_id 不一致等
422	CURRENCY_NOT_SUPPORTED	币种未开通
422	UNSUPPORTED_CAPABILITY	当前商户不是转账钱包模式

平台已经受理、但最终被拒绝的请求（例如余额不足），错误响应的 error.details 中会带上 transaction_id 和 external_id，之后也可以查到这笔 FAILED 交易。受理之前就被拒绝的请求（格式错误、签名错误等）不会产生交易。

完整错误码见通用错误码。

重复请求

同一个 external_id 且内容相同时，平台返回首次结果，并带响应头 Idempotency-Replayed: true，不会再转一次。所以超时后可以放心用同一个 external_id 原样重发（签名要用新的 X-Timestamp）。