查询交易状态

交易查询对转账钱包和单一钱包商户都可用。转账钱包用它确认转入、转出的结果；单一钱包可以用它查看平台侧记录的交易。

按 transaction_id 查询

GET {API_URL}/v1/transactions/{transaction_id}

参数	位置	类型	说明
transaction_id	path	string	平台交易 ID（UUID）

成功响应 200

字段	类型	说明
transaction_id	string	平台交易 ID
kind	string	交易类型，例如 TRANSFER_IN、TRANSFER_OUT、BET、PAYOUT
status	string	PENDING、UNKNOWN、SUCCEEDED 或 FAILED
player_id	string	平台玩家 ID
currency	string	币种代码
amount	decimal string	金额，大于 0
created_at	string	创建时间
updated_at	string	最近更新时间
failure	object	仅 FAILED 时出现，{"code":"..."}

{
  "data": {
    "transaction_id": "0192f6c1-2b3a-7d4e-8f50-6a7b8c9d0e1f",
    "kind": "TRANSFER_IN",
    "status": "SUCCEEDED",
    "player_id": "0192f6a4-3c1e-7b2a-9d40-5e8f1a2b3c4d",
    "currency": "USD",
    "amount": "100.00",
    "created_at": "2026-09-23T08:00:00Z",
    "updated_at": "2026-09-23T08:00:00Z"
  },
  "request_id": "0192f6c1-req-0002"
}

UNKNOWN 不是失败

UNKNOWN 是 HTTP 200 响应中的业务状态，表示平台还在确认结果。请稍后再查，直到进入 SUCCEEDED 或 FAILED。

交易不存在或不属于当前商户时，返回 404 RESOURCE_NOT_FOUND。

按 external_id 查询

GET {API_URL}/v1/transactions?external_id={external_id}

转账请求超时、没有拿到 transaction_id 时，用商户订单号查询。

参数	位置	必填	说明
external_id	query	是	转账时传入的 external_id

返回分页结构，items 中最多一条：

{
  "data": {
    "items": [
      {
        "transaction_id": "0192f6c1-2b3a-7d4e-8f50-6a7b8c9d0e1f",
        "kind": "TRANSFER_IN",
        "status": "SUCCEEDED",
        "player_id": "0192f6a4-3c1e-7b2a-9d40-5e8f1a2b3c4d",
        "currency": "USD",
        "amount": "100.00",
        "created_at": "2026-09-23T08:00:00Z",
        "updated_at": "2026-09-23T08:00:00Z"
      }
    ],
    "next_cursor": null,
    "has_more": false
  },
  "request_id": "0192f6c1-req-0003"
}

查不到也不能换 ID 重做

items 为空只说明平台此刻没有这笔交易，原请求可能还在路上。请用同一个 external_id 原样重发转账：如果平台已经受理，会返回首次结果；如果没有受理，才会执行。不要换新的 external_id。