创建订单
创建一个新的支付订单。此接口使用请求头 HMAC 签名。
接口
POST /v4.0.0/api/orders/create请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
accessKeyId | string | 是 | 您的商户 Access Key ID |
merchantOrderId | string | 是 | 您的唯一订单标识符（最长 64 字符） |
merchantChannel | string | 否 | 商户渠道，默认为 default |
blockChain | string | 是 | 区块链名称（如 ETH、TRON、BSC、POLYGON） |
tokenSymbol | string | 是 | 代币符号（如 usdt、usdc） |
amount | string | 是 | 支付金额，十进制字符串（如 "10.50"）最多精确到小数点后2位 |
splitterAddress | string | 是 | 您的分账钱包合约地址 |
subject | string | 否 | 订单主题 / 描述（最长 256 字符） |
expireDuration | integer | 否 | 过期时间（秒），默认 3600 |
callbackUrl | string | 否 | 前端自定义跳转链接，如果不指定则以api key配置的callbackURL为准 |
remark | string | 否 | 订单备注 |
extra | string | 否 | 订单额外信息 |
param1 | string | 否 | 订单额外参数1 |
param1 | string | 否 | 订单额外参数2 |
WARNING
callbackURL 是支付完成后展示给客户的前端跳转地址。后端通知请使用 notifyURL。详见 Notify URL 与 Callback URL 的区别。
请求示例
json
{
"accessKeyId" : "01...RF",
"merchantOrderId" : "8b7eb554-b847-4450-9",
"merchantChannel" : null,
"blockChain" : "TRON",
"tokenSymbol" : "usdt",
"amount" : "0.01",
"splitterAddress" : "TJDc...3U7",
"subject" : "Test Order - API Doc",
"expireDuration" : 3600,
"callbackUrl" : null,
"remark" : null,
"extra" : null,
"param1" : null,
"param2" : null
}响应示例
json
{
"code" : 0,
"msg" : "success",
"ui" : null,
"version" : null,
"count" : 0,
"data" : {
"merchantAddress" : "TC8H...zPi",
"merchantChannel" : "default",
"chain" : "TRON",
"blockChain" : "TRON",
"tokenSymbol" : "usdt",
"createChannel" : 1,
"accessChannel" : 0,
"merchantOrderId" : "8b7eb554-b847-4450-9",
"payOrderId" : "01KWCGJ443GX4SCBQK53CTF04A",
"tokenAddress" : "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"receiptAddress" : "TX5PLEFrEdBETP3Xp3DBcTCt58FNuDGL8h",
"amount" : 0.01,
"state" : 0,
"accessSign" : "BE333D8F1A561EFFCA7C0DCB88BC60C1EE67A00E6FBE02333270B8C68564679E",
"confirmCount" : "0",
"walletConnectEnable" : false,
"bridgeServerAddress" : "https://bridge.hashnut.io",
"eip712ChainId" : "0",
"chainId" : "0",
"createTime" : 1782831452288,
"rate" : 80,
"obtainAmount" : 0.00992,
"platformFee" : 8.0E-5,
"expireDuration" : 3600,
"payWebType" : 0,
"flagAmount" : 0,
"underPaid" : false,
"paidAmount" : 0,
"supplementCount" : 0
}
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 0 表示成功，非零表示错误 |
msg | string | 可读的消息文本 |
data.payOrderId | string | HashNut 生成的订单 ID |
data.merchantOrderId | string | 您的原始订单 ID |
data.tokenAddress | string | 支付token的合约地址 |
data.receiptAddress | string | 客户付款的区块链收款地址 |
data.blockChain | string | 区块链名称（如 ETH、TRON、BSC、POLYGON） |
data.tokenSymbol | string | 代币符号（如 usdt、usdc） |
data.amount | string | 支付金额 |
data.state | integer | 订单状态（0 = INIT）。参见订单状态 |
data.expireDuration | string | 过期时间 |
TIP
请在您的系统中同时保存 payOrderId 和 merchantOrderId。使用 merchantOrderId 将 HashNut 订单与您的内部记录关联。
错误码
| 错误码 | 说明 |
|---|---|
0 | 成功 |
1001 | 参数无效 |
1002 | 认证失败 |
1003 | merchantOrderId 重复 |
1004 | 没有可用的收款地址 |
1005 | 不支持的链或代币 |