数字货币代付

概述

数字货币代付 API 用于将商户余额中的数字货币转出至指定链上地址。下单成功后订单进入「已接单（处理中）」状态，平台完成出款后通过回调通知商户最终结果。

出款结果以异步结果为准

下单成功仅代表平台受理成功，响应固定返回 status = 1（已接单处理中），随后由平台发起链上出款。因此不能以下单响应判断出款结果，请以回调或查询接口为准。

公共请求头（含必填 Nonce）、公共请求体字段与统一响应结构见数字货币接入总览。

请求路径

域名：推荐使用统一域名 openapi.toppayment.com（路径不变）；原数字货币域名（global-digit-openapi.toppayment.com）仍可用。

环境	地址
沙箱	`https://openapi.toppayment.com/crypto/sandbox/disbursement/cash`
生产	`https://openapi.toppayment.com/crypto/disbursement/cash`

请求头参数

字段	必填	类型	描述
Content-Type	M	String	固定值：application/json
Nonce	M	String(16-64)	防重放随机串，10 分钟内不可重复，不参与签名

IP 白名单

代付接口受出口 IP 白名单管控。请提前将调用方出口 IP 提交客服加入白名单，否则返回 1001（IP 白名单异常）或 1004（IP 白名单未配置）。

请求体参数

字段	必填	类型	描述
mchNo	M	String(32)	商户编号沙箱需使用 `SD` 前缀的沙箱商户号
orderNum	M	String(64)	商户订单号同一商户下不可重复，重复返回 `0001`
money	M	String	代付数量数字字符串，最多 6 位小数示例：`10.5`
currency	M	String(16)	币种字符集 `A-Z a-z 0-9 _`，示例：`USDT`
netWork	M	String(100)	链网络示例：`TRC20` 必须与 `inAddress` 所属链一致
inAddress	M	String(255)	收款地址链上收款方地址，请务必校验格式与所属链
feeType	M	String	手续费承担方式 `0`：手续费从代付数量中扣除，收款方实收 `money - fee` `1`：手续费另计，账户扣除 `money + fee`，收款方实收 `money`
downNotifyUrl	M	String(255)	异步通知地址须为可公网访问的 HTTP/HTTPS 地址，见回调通知
timestamp	M	String(13)	请求时间戳（13 位毫秒级），偏差须在 ±5 分钟内
sign	M	String	签名，见签名规则
name	O	String(64)	收款人姓名
email	O	String(64)	收款人邮箱
phone	O	String(32)	收款人电话
tenantCode	O	String(32)	子租户编码，不传使用默认租户
countryCode	O	String(16)	国家码，数字货币场景无需传

feeType 计费说明

以 money = 100、fee = 1 为例：

feeType	账户扣除	收款方实收	适用场景
`0`	100	99	手续费由收款方承担
`1`	101	100	手续费由商户承担，保证收款方到账整数

fee 由商户费率模板（固定费 + 费率 × 数量）计算，实际值以下单响应与回调中的 fee 为准。若未匹配到可用费率模板或通道，返回 0003。

请求示例

Content-Type: application/json
Nonce: c41f7ae9028b56d3f1a4

{
    "mchNo": "{{mchNo}}",
    "orderNum": "CW1788506801001",
    "money": "10.5",
    "currency": "USDT",
    "netWork": "TRC20",
    "inAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "feeType": "0",
    "downNotifyUrl": "https://example.com/notify/loan",
    "name": "Jack Ma",
    "email": "[email protected]",
    "phone": "081234567890",
    "timestamp": "1749451858772",
    "sign": "按签名规则生成后替换"
}

响应体参数

字段	必填	类型	描述
success	M	Boolean	是否成功
code	M	String	响应状态码 9999：成功；其他见异常码
msg	O	String	响应消息，成功时为 `null`
timeStamp	M	Number	服务器响应时间（毫秒级）
data	M	Object	响应数据对象
orderNum	M	String	商户订单号
platOrderNum	M	String	平台订单号后续查询与回调的唯一凭据
amount	M	Number	代付数量与请求 `money` 一致
fee	M	Number	手续费
feeType	M	Number	手续费承担方式 `0`：代付数量内扣除；`1`：手续费另计
status	M	Number	订单状态码下单成功固定为 `1`（已接单处理中），取值见下表
statusMsg	M	String	订单状态描述下单与查询接口返回统一展示状态（如 `PENDING`）回调返回明细状态（如 `ORDER_RECEIVED_PROCESSING`），两者取值集合不同
currency	M	String	币种
netWork	M	String	链网络

代付状态码

status	明细状态（回调 statusMsg）	统一展示状态（下单/查询 statusMsg）	说明	是否终态
`0`	`INITIAL_STATE_PENDING_ORDERS`	`PENDING`	初始态（待接单）	否
`1`	`ORDER_RECEIVED_PROCESSING`	`PENDING`	已接单（处理中）	否
`2`	`PROCESSED_SUCCESSFULLY`	`SUCCESS`	出款成功	是
`3`	`CANCELED_SUCCESSFULLY`	`CANCELLED`	已撤销（资金已解冻退回）	是
`4`	`PROCESSING_FAILED`	`FAILED`	出款失败（资金已解冻退回）	是
`5`	`LOANING`	`PROCESSING`	链上出款中	否
`99`	`PENDING_ORDER`	`PENDING`	待接单	否

statusMsg 的两套取值

同一个 status 在不同接口下 statusMsg 文案不同：下单与查询返回统一展示状态（PENDING / PROCESSING / SUCCESS / FAILED / CANCELLED），回调返回明细状态（ORDER_RECEIVED_PROCESSING / PROCESSED_SUCCESSFULLY 等）。建议业务判断以数值 status 为准，statusMsg 仅用于展示与日志。

响应示例

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767840272829,
    "data": {
        "orderNum": "CW1788506801001",
        "platOrderNum": "CW20260825143024553",
        "amount": 10.500000,
        "fee": 0.700000,
        "feeType": 0,
        "status": 1,
        "statusMsg": "PENDING",
        "currency": "USDT",
        "netWork": "TRC20"
    }
}

{
    "success": false,
    "code": "1002",
    "msg": "[1002]Insufficient available balance!",
    "timeStamp": 1767840272829,
    "data": null
}

注意事项

地址与链必须匹配

inAddress 与 netWork 必须属于同一条链。跨链地址会导致资产不可找回，平台无法追回错误地址的转账。请在提交前完成地址格式校验。

下单成功即冻结相应余额（含手续费），撤销或失败后自动解冻。
余额不足返回 1002；沙箱环境传 money = 20000000 可稳定触发该错误用于联调。
同一 mchNo + orderNum 重复下单返回 0001（The order already exists!）；短时间并发同单返回 0004。
下单响应仅代表受理成功，最终结果请以回调通知或订单查询为准。

后续步骤

订单状态与出款哈希：数字货币订单查询
出款结果通知：数字货币回调通知

数字货币代付

# 概述

# 请求路径

# 请求头参数

# 请求体参数

# feeType 计费说明

# 请求示例

# 响应体参数

# 代付状态码

# 响应示例

# 注意事项

# 后续步骤

概述