数字货币代收

概述

数字货币代收 API 用于向付款人收取链上转账。平台为订单分配一个收款地址，付款人向该地址转入指定数量的数字货币，链上确认后平台回调通知商户。

支持两种下单方式：

下单方式	生产路径	说明
收银台模式	`/crypto/pay/prePay`	默认模式。下单时可不指定币种与链，响应返回 `cashierUrl`，付款人在平台收银台选择「币种-链」后获取收款地址
API 直连模式	`/crypto/pay/orderDirectly`	请求中必须指定 `currency` 与 `netWork`，响应直接返回收款地址 `inAddress`

接入说明

两种模式受商户「收银台开放模式」（availablePayMode）控制：仅开通 H5 才能调用 prePay，仅开通 API 才能调用 orderDirectly，否则返回 0001 并提示 merchant do not support H5/API ordering!（商户不支持 H5/API 下单）。如需开通请联系客服。

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

收银台模式（prePay）

请求路径

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

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

请求头参数

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

请求体参数

字段	必填	类型	描述
mchNo	M	String(32)	商户编号沙箱需使用 `SD` 前缀的沙箱商户号
mchUserId	M	String(32)	商户侧用户标识用于关联商户系统内的付款人
payMoney	M	String	收款数量数字字符串，最多 6 位小数范围受平台预下单限额约束，超出返回 `0001` 示例：`10.5`
downNotifyUrl	M	String(255)	异步通知地址须为可公网访问的 HTTP/HTTPS 地址，见回调通知
timestamp	M	String(13)	请求时间戳（13 位毫秒级），偏差须在 ±5 分钟内
sign	M	String	签名，见签名规则
orderNum	O	String(64)	商户订单号不传时由平台生成；同一商户下不可重复，重复返回 `0001`
currency	O	String(16)	币种收银台模式可不传，由付款人在收银台选择；传入则收银台锁定该币种字符集 `A-Z a-z 0-9 _`，示例：`USDT`
netWork	O	String(100)	链网络与 `currency` 同时传才生效，示例：`TRC20`
expiryPeriod	O	String	订单有效期（分钟）取值 `1`–`9999`，不传默认 1440（24 小时）
orderVersion	O	String(20)	订单版本标识，由平台约定，一般无需传
name	O	String(64)	付款人姓名
email	O	String(64)	付款人邮箱
phone	O	String(32)	付款人电话
tenantCode	O	String(32)	子租户编码，不传使用默认租户
countryCode	O	String(16)	国家码，数字货币场景无需传

请求示例

Content-Type: application/json
Nonce: 8f3c1a92b74e5d60c1f2

{
    "mchNo": "{{mchNo}}",
    "mchUserId": "USER_10001",
    "payMoney": "10.5",
    "orderNum": "CR1788506800926",
    "downNotifyUrl": "https://example.com/notify/pay",
    "expiryPeriod": "1440",
    "name": "Jack Ma",
    "email": "[email protected]",
    "phone": "081234567890",
    "timestamp": "1749451858772",
    "sign": "按签名规则生成后替换"
}

{
    "mchNo": "{{mchNo}}",
    "mchUserId": "USER_10001",
    "payMoney": "10.5",
    "orderNum": "CR1788506800927",
    "currency": "USDT",
    "netWork": "TRC20",
    "downNotifyUrl": "https://example.com/notify/pay",
    "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	平台订单号后续查询与回调的唯一凭据
payMoney	M	Number	收款数量
currency	O	String	币种请求未指定时为 `null`，待付款人在收银台选择后确定
netWork	O	String	链网络，同上
cashierUrl	M	String	收银台地址引导付款人跳转至该地址完成付款
inAddress	O	String	收款地址收银台模式下单时为 `null`，付款人在收银台选定「币种-链」后生成

响应示例

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767840272829,
    "data": {
        "orderNum": "CR1788506800926",
        "platOrderNum": "CR20260904152640640",
        "payMoney": 10.500000,
        "currency": null,
        "netWork": null,
        "cashierUrl": "https://cashier.example.com/CR20260904152640640",
        "inAddress": null
    }
}

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767840272829,
    "data": {
        "orderNum": "CR1788506800927",
        "platOrderNum": "CR20260904152640641",
        "payMoney": 10.500000,
        "currency": "USDT",
        "netWork": "TRC20",
        "cashierUrl": "https://cashier.example.com/CR20260904152640641",
        "inAddress": null
    }
}

收银台不支持支付完成回跳

数字货币收银台不支持支付完成后自动跳回商户页面。付款人完成链上转账后需自行返回商户站点，商户请通过回调通知或订单查询确认支付结果。

API 直连模式（orderDirectly）

商户在请求中指定 currency 与 netWork，平台直接向通道申请收款地址并在响应中返回 inAddress，无需跳转收银台。

请求路径

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

环境	地址
沙箱	`https://openapi.toppayment.com/crypto/sandbox/pay/directlyPay`
生产	`https://openapi.toppayment.com/crypto/pay/orderDirectly`

沙箱路径差异

沙箱直连下单路径为 /crypto/sandbox/pay/directlyPay，与生产的 /crypto/pay/orderDirectly 不同名，但请求体与响应体完全一致。

请求体参数

与收银台模式相比，差异如下：

字段	必填	类型	描述
currency	M	String(16)	币种直连模式必传，示例：`USDT`
netWork	M	String(100)	链网络直连模式必传，示例：`TRC20`

其余字段与收银台模式相同。currency 或 netWork 缺失返回 0001；该币种无可用通道返回 0003。

请求示例

Content-Type: application/json
Nonce: 2b7de401a5c96f83d0e1

{
    "mchNo": "{{mchNo}}",
    "mchUserId": "USER_10001",
    "payMoney": "10.5",
    "orderNum": "CRAPI1788506800931",
    "currency": "USDT",
    "netWork": "TRC20",
    "downNotifyUrl": "https://example.com/notify/pay",
    "expiryPeriod": "1440",
    "timestamp": "1749451858772",
    "sign": "按签名规则生成后替换"
}

响应体参数

字段与收银台模式一致，直连模式重点关注：

字段	必填	类型	描述
inAddress	M	String	收款地址请引导付款人向该地址转入 `payMoney` 数量的 `currency`
cashierUrl	O	String	收银台地址直连模式仍会返回，但请以 `inAddress` 为准

响应示例

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767840272829,
    "data": {
        "orderNum": "CRAPI1788506800931",
        "platOrderNum": "CR20260904152640642",
        "payMoney": 10.500000,
        "currency": "USDT",
        "netWork": "TRC20",
        "cashierUrl": "https://cashier.example.com/CR20260904152640642",
        "inAddress": "TP5wzCqNsJFNT83m1VXdF2Aj1ageFWgqW2"
    }
}

注意事项

转账数量必须与订单一致

链上转账数量必须与 payMoney 完全一致，且必须使用订单指定的 currency 与 netWork。数量不符、跨链或转错币种可能导致订单无法自动入账，需人工介入处理。

收款地址与订单绑定，请勿复用历史订单的 inAddress。
订单在 expiryPeriod 后过期，过期订单查询返回状态 EXPIRED。
同一 mchNo + orderNum 重复下单返回 0001（The order already exists!）；短时间并发同单返回 0004。

后续步骤

订单状态与手续费：数字货币订单查询
支付结果通知：数字货币回调通知

数字货币代收

# 概述

# 收银台模式（prePay）

# 请求路径

# 请求头参数

# 请求体参数

# 请求示例

# 响应体参数

# 响应示例

# API 直连模式（orderDirectly）

# 请求路径

# 请求体参数

# 请求示例

# 响应体参数

# 响应示例

# 注意事项

# 后续步骤

概述

收银台模式（prePay）

请求路径

请求头参数

请求体参数

请求示例

响应体参数

响应示例

API 直连模式（orderDirectly）

请求路径

请求体参数

请求示例

响应体参数

响应示例

注意事项

后续步骤