跳至主要內容

数字货币代收

TOPPAY Team大约 4 分钟

概述

数字货币代收 API 用于向付款人收取链上转账。商户在下单请求中指定 currency 与 netWork,平台为订单分配收款地址 inAddress,付款人向该地址转入指定数量的数字货币,链上确认后平台回调通知商户。

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


代收下单(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 不同名,但请求体与响应体完全一致。

请求头参数

字段必填类型描述
Content-TypeMString固定值:application/json
NonceMString(16-64)防重放随机串,10 分钟内不可重复,不参与签名

请求体参数

字段必填类型描述
mchNoMString(32)商户编号
沙箱需使用 SD 前缀的沙箱商户号
mchUserIdMString(32)商户侧用户标识
用于关联商户系统内的付款人
payMoneyMString收款数量
数字字符串,最多 6 位小数
范围受平台预下单限额约束,超出返回 0001
示例:10.5
currencyMString(16)币种
字符集 A-Z a-z 0-9 _,示例:USDT
netWorkMString(100)链网络
示例:TRC20
downNotifyUrlMString(255)异步通知地址
须为可公网访问的 HTTP/HTTPS 地址,见 回调通知
timestampMString(13)请求时间戳(13 位毫秒级),偏差须在 ±5 分钟内
signMString签名,见 签名规则
orderNumOString(64)商户订单号
不传时由平台生成;同一商户下不可重复,重复返回 0001
expiryPeriodOString订单有效期(分钟)
取值 1–9999,不传默认 1440(24 小时)
orderVersionOString(20)订单版本标识,由平台约定,一般无需传
nameOString(64)付款人姓名
emailOString(64)付款人邮箱
phoneOString(32)付款人电话
tenantCodeOString(32)子租户编码,不传使用默认租户
countryCodeOString(16)国家码,数字货币场景无需传

currency 或 netWork 缺失返回 0001;该币种无可用通道返回 0003。

请求示例

Content-Type: application/json
Nonce: 2b7de401a5c96f83d0e1

响应体参数

字段必填类型描述
successMBoolean是否成功
codeMString响应状态码
9999:成功;其他见 异常码
msgOString响应消息,成功时为 null
timeStampMNumber服务器响应时间(毫秒级)
dataMObject响应数据对象
orderNumMString商户订单号
请求未传时为平台生成的订单号
platOrderNumMString平台订单号
后续查询与回调的唯一凭据
payMoneyMNumber收款数量
currencyMString币种
netWorkMString链网络
inAddressMString收款地址
请引导付款人向该地址转入 payMoney 数量的 currency

响应示例

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767840272829,
    "data": {
        "orderNum": "CRAPI1788506800931",
        "platOrderNum": "CR20260904152640642",
        "payMoney": 10.500000,
        "currency": "USDT",
        "netWork": "TRC20",
        "inAddress": "TP5wzCqNsJFNT83m1VXdF2Aj1ageFWgqW2"
    }
}

注意事项

转账数量必须与订单一致

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

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

后续步骤