数字货币接入总览
大约 3 分钟
概述
数字货币（Crypto）开放 API 与法币开放 API 同源，签名规则、统一响应结构完全一致，但路径前缀与部分字段不同（推荐与法币共用统一域名）：
- 路径前缀固定为
/crypto（法币为/{countryCode}，如/ph、/id）。 - 请求头必须携带防重放随机串
Nonce（法币接口不需要）。 - 金额为链上数量而非法币金额，最多 6 位小数；余额与回调金额按 8 位小数返回。
- 交易维度由
currency+netWork（币种 + 链网络）确定，例如USDT+TRC20。
字段名大小写
线上字段名为 netWork（W 大写），不是 network。请求、响应与签名拼接时必须与文档示例完全一致。
环境与域名
数字货币不按国家区分，路径前缀固定为 /crypto。
| 类型 | 域名 | 说明 |
|---|---|---|
| 统一域名（推荐） | openapi.toppayment.com | 与法币同一 Host；路径仍为 /crypto/... |
| 原数字货币域名（兼容） | global-digit-openapi.toppayment.com | 仍可继续使用 |
路径模板（{host} 按上表选择）：
沙箱：
https://{host}/crypto/sandbox/...
生产：https://{host}/crypto/...
示例（推荐）：
沙箱：
https://openapi.toppayment.com/crypto/sandbox/...
生产：https://openapi.toppayment.com/crypto/...
接口一览
| 场景 | 沙箱地址 | 生产地址 | 文档 |
|---|---|---|---|
| 代收 — 收银台预下单 | https://openapi.toppayment.com/crypto/sandbox/pay/prePay | https://openapi.toppayment.com/crypto/pay/prePay | 数字货币代收 |
| 代收 — API 直连下单 | https://openapi.toppayment.com/crypto/sandbox/pay/directlyPay | https://openapi.toppayment.com/crypto/pay/orderDirectly | 数字货币代收 |
| 代收 — 订单查询 | https://openapi.toppayment.com/crypto/sandbox/pay/query | https://openapi.toppayment.com/crypto/pay/query | 订单查询 |
| 代付 — 下单 | https://openapi.toppayment.com/crypto/sandbox/disbursement/cash | https://openapi.toppayment.com/crypto/disbursement/cash | 数字货币代付 |
| 代付 — 订单查询 | https://openapi.toppayment.com/crypto/sandbox/disbursement/query | https://openapi.toppayment.com/crypto/disbursement/query | 订单查询 |
| 余额查询 | https://openapi.toppayment.com/crypto/sandbox/balance/v1 | https://openapi.toppayment.com/crypto/balance/v1 | 余额查询 |
| 回调通知 | 由商户提供 downNotifyUrl | 由商户提供 downNotifyUrl | 回调通知 |
沙箱路径差异
生产直连下单路径为 /crypto/pay/orderDirectly，沙箱为 /crypto/sandbox/pay/directlyPay。请求体与响应体两者一致。
公共请求头
所有数字货币接口均为 POST + JSON。
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | 固定值：application/json |
| Nonce | M | String(16-64) | 防重放随机串 字符集 A-Z a-z 0-9 _ -，长度 16–64同一 mchNo 下 10 分钟内不可重复，重复返回 0001不参与 sign 计算沙箱环境不校验，但建议按生产规则携带 |
公共请求体字段
以下字段所有接口共用，各接口文档中不再重复列出。
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| mchNo | M | String(32) | 商户编号 沙箱环境需使用 SD 前缀的沙箱商户号 |
| timestamp | M | String(13) | 请求时间戳（13 位毫秒级） 与服务器时间偏差须在 ±5 分钟内，超出返回 0001 |
| sign | M | String | 签名，见 签名规则 |
| tenantCode | O | String(32) | 子租户编码 不传使用商户默认租户 |
| countryCode | O | String(16) | 国家码，数字货币场景无需传 |
统一响应结构
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| success | M | Boolean | 是否成功 |
| code | M | String | 响应状态码 9999：成功；其他见 异常码 |
| msg | O | String | 响应消息，成功时为 null，失败时形如 [0002]signature verification failed! |
| timeStamp | M | Number | 服务器响应时间（毫秒级） |
| data | O | Object | 业务数据，结构见各接口 |
支持的币种与链网络
currency 与 netWork 的可用组合由运营在平台侧开通，请以商户后台或客服提供的清单为准。常见取值：
| currency | 常见 netWork |
|---|---|
USDT | TRC20、ERC20 |
USDC | TRC20、ERC20 |
TRX | TRC20 |
ETH | ERC20 |
BTC | BTC |
收银台的 method 表示法
一级收银台中「支付方式」以 {currency}-{netWork} 形式表示，例如 USDT-TRC20；下划线写法 USDT_TRC20 同样被接受。
沙箱说明
- 商户号需带
SD前缀（正式123456→ 沙箱SD123456），并在商户后台上传沙箱商户公钥。 - 沙箱不请求真实链上通道，代收收款地址为
SANDBOX_{platOrderNum}形式的模拟地址。 - 沙箱手续费固定按 1% 计算。
- 沙箱代付传
money = 20000000可稳定触发余额不足（1002），便于异常分支联调。 - 沙箱余额查询返回固定余额
2000000，且响应结构与生产不同，详见 余额查询。