提现与退款
登记商户自行转出的资金，提交交易哈希完成链上核验。
资金模式
充值确认后仍自动归集到商户主钱包。提现与退款由商户自行使用自己的钱包转账，平台只登记、核验和记录，不代为出款，也不会冻结平台余额。
控制台入口：提现与退款。订单退款也可以从订单记录中已支付订单的详情发起。
登记转账
POST /v1/withdrawals使用标准 API 签名请求头。推荐携带 X-Idempotency-Key，不提供时使用 request_no 作为幂等键。
| 字段 | 必填 | 说明 |
|---|---|---|
request_no | 是 | 商户业务单号，当前商户内唯一，最长 128 字节 |
asset | 是 | BEP20-USDT |
amount | 是 | 大于零的十进制字符串，最多 18 位小数 |
destination | 是 | 收款人确认的 BSC 地址 |
kind | 否 | withdrawal（默认）或 refund |
order_id | 退款必填 | 本商户已支付订单的 UUID |
note | 否 | 备注，最长 500 字节 |
{
"request_no": "REFUND-1001",
"asset": "BEP20-USDT",
"amount": "5.00",
"destination": "<收款人确认的BSC地址>",
"kind": "refund",
"order_id": "<已支付订单UUID>",
"note": "订单部分退款"
}示例占位符不能直接提交。登记结果如下：
{
"data": {
"id": "<平台转账记录UUID>",
"status": "pending",
"source_address": "<登记时的商户主钱包>",
"settlement_mode": "external"
}
}请先查询记录，确认 source_address 后再自行转账。后续修改主钱包不会改变已有记录的付款地址。
同一订单可分次退款；已登记且未取消、未失败的退款金额之和不能超过已支付金额。平台不会把付款来源地址自动当作退款目标，请与收款人核对地址。
提交交易核验
POST /v1/withdrawals/{id}/verify{
"tx_hash": "<0x开头的完整交易哈希>"
}平台核验 BSC 主网、官方 USDT 合约、交易执行成功、实际 Transfer 日志、付款主钱包、目标地址和精确金额。退款交易还必须不早于关联订单的支付时间。同一交易哈希只能认领一次，不能用于多笔提现或退款记录。
{
"data": {
"status": "processing",
"confirmations": 3,
"required_confirmations": 15
}
}匹配成功但确认数不足时为 processing，后台会继续核验；达到配置要求（至少 15 个确认）后为 completed。未打包、失败或参数不匹配的交易会返回错误，不会记为完成。
查询记录
GET /v1/withdrawals/{id}响应包含 id、request_no、kind、amount、asset、source_address、destination、status、payment_order_id、tx_hash、confirmations、verified_at 与 last_error 等字段。查询接口同样需要 API 签名。
| 状态 | 含义 |
|---|---|
pending | 已登记，等待商户提交交易 |
processing | 已匹配链上交易，等待足够确认 |
completed | 链上核验通过并记录完成 |
rejected | 商户已取消尚未关联交易的记录 |
failed | 处理失败，查看记录中的原因 |
控制台允许取消未关联交易的待处理记录。取消只影响记录，不会撤销链上转账。
幂等与账单
重试登记时保持业务单号、幂等键、类型、关联订单、资产、金额和目标地址不变，每次生成新的时间戳、Nonce 与签名。更改核心参数后复用幂等键返回 HTTP 409。幂等登记响应可能只包含已有 id，请通过查询接口获取当前状态。
资金账单分别记录充值、自动归集和已核验商户转出，不代表平台托管余额。HTTP 200 只表示接口受理成功，最终应以记录 completed 和链上结果为准。