创建订单

创建支付订单，为您的客户生成唯一的支付链接。

概述

支付订单定义支付金额、货币和区块链网络。每个订单生成一个唯一的支付链接，客户可以使用该链接完成支付。

快速开始

JavaScript
Python
API

const order = await client.orders.create({
  merchantOrderId: `order-${Date.now()}`,
  chainCode: 'erc20',
  coinCode: 'usdt',
  amount: 0.01,
  callBackUrl: 'https://your-site.com/api/webhook',
  frontendCallbackUrl: 'https://your-site.com/payment/success',
});

console.log('Payment URL:', order.paymentUrl);

order = client.orders.create(
    merchant_order_id=f'order-{int(time.time())}',
    chain_code='erc20',
    coin_code='usdt',
    amount=0.01,
    callback_url='https://your-site.com/api/webhook',
    frontend_callback_url='https://your-site.com/payment/success'
)

print(f'Payment URL: {order.payment_url}')

curl -X POST 'https://testnet.hashnut.io/api/v3.0.0/pay/createPayOrderOnSplitWalletWithApiKey' \
  -H 'hashnut-request-uuid: <uuid>' \
  -H 'hashnut-request-timestamp: <timestamp>' \
  -H 'hashnut-request-sign: <signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accessKeyId": "YOUR_ACCESS_KEY_ID",
    "merchantOrderId": "order-123",
    "chainCode": "erc20",
    "coinCode": "usdt",
    "amount": 0.01,
    "callBackUrl": "https://your-site.com/api/webhook",
    "frontendCallbackUrl": "https://your-site.com/payment/success"
  }'

订单创建流程

必需参数

参数	类型	描述	示例
`merchantOrderId`	string	您系统中的唯一订单 ID	`"order-123"`
`chainCode`	string	区块链网络代码	`"erc20"`、`"polygon-erc20"`
`coinCode`	string	货币代码（区分大小写）	`"usdt"`、`"usdc"`
`amount`	decimal	支付金额（最小值 0.01）	`0.01`、`1.5`

可选参数

参数	类型	描述	何时使用
`callBackUrl`	string	支付通知的 Webhook URL	始终推荐
`frontendCallbackUrl`	string	支付后的重定向 URL	用于客户重定向
`receiptAddress`	string	自定义接收地址	如果不使用默认地址
`splitterAddress`	string	自定义智能合约地址	高级用例

分步指南

步骤 1：选择链和货币

首先，查询可用选项：

// 获取支持的链
const chains = await client.config.getChains();

// 获取链的支持代币
const tokens = await client.config.getTokens('erc20');

常见组合：

Ethereum + USDT：chainCode: "erc20"，coinCode: "usdt"
Polygon + USDC：chainCode: "polygon-erc20"，coinCode: "usdc"
TRON + USDT：chainCode: "tron-trc20"，coinCode: "usdt"

步骤 2：设置支付金额

重要：

最小值：0.01
格式：基础单位（例如，0.01 表示 0.01 USDT，不是 10000）
精度：四舍五入到 2 位小数

// ✅ 正确
amount: 0.01  // 0.01 USDT

// ❌ 错误
amount: 10000  // 这将是 10,000 USDT！

步骤 3：生成商户订单 ID

要求：

每个商户必须唯一
最多 255 个字符
使用描述性格式

好的示例：

`order-${Date.now()}`
`payment-${userId}-${timestamp}`
`${productId}-${orderNumber}`

不好的示例：

`order-1`  // 不唯一
`test`     // 不描述性

步骤 4：配置回调

后端 Webhook（callBackUrl）：

接收支付状态更新
必须使用 HTTPS
应验证签名

前端重定向（frontendCallbackUrl）：

客户支付后重定向到这里
可以包含订单参数
应显示成功/失败页面

步骤 5：创建订单

JavaScript
Python

try {
  const order = await client.orders.create({
    merchantOrderId: `order-${Date.now()}`,
    chainCode: 'erc20',
    coinCode: 'usdt',
    amount: 0.01,
    callBackUrl: 'https://your-site.com/api/webhook',
    frontendCallbackUrl: 'https://your-site.com/payment/success',
  });
  
  // 在数据库中存储 order.payOrderId
  // 将客户重定向到 order.paymentUrl
  window.location.href = order.paymentUrl;
} catch (error) {
  console.error('Order creation failed:', error);
}

try:
    order = client.orders.create(
        merchant_order_id=f'order-{int(time.time())}',
        chain_code='erc20',
        coin_code='usdt',
        amount=0.01,
        callback_url='https://your-site.com/api/webhook',
        frontend_callback_url='https://your-site.com/payment/success'
    )
    
    # 在数据库中存储 order.pay_order_id
    # 将客户重定向到 order.payment_url
    return redirect(order.payment_url)
except Exception as e:
    print(f'Order creation failed: {e}')

订单响应

响应字段

{
  "code": 0,
  "msg": "success",
  "data": {
    "payOrderId": "01KBZ292SK2GKFK97916F5EC3B",
    "accessSign": "D3DE7E4002057C0EAED1BE2268DA53CC9058DCFC9DCAF50D999AF270A7B033C5",
    "merchantOrderId": "order-123"
  }
}

支付 URL 构造

构造支付 URL：

https://testnet.hashnut.io/pay?accessSign={accessSign}&merchantOrderId={merchantOrderId}&payOrderId={payOrderId}&chainCode={chainCode}

SDK 方法：

const paymentUrl = order.paymentUrl; // SDK 处理构造

订单类型

DeFi 订单

智能合约模式：

使用智能合约的地址池
资金保存在合约中直到提取
支持多方费用分配

何时使用：

您需要最大安全性
您想要地址池管理
您需要链上验证

CeFi 订单

直接钱包模式：

使用您的直接钱包地址
资金直接发送到钱包
简化的资金管理

何时使用：

您想要立即访问资金
您更喜欢简单的操作
您不需要地址池

最佳实践

订单 ID 管理

使用 UUID 或时间戳：确保唯一性
存储在数据库中：保存 payOrderId 和 merchantOrderId 映射
幂等性：创建前检查现有订单
格式：使用一致的命名约定

金额处理

验证最小值：确保金额 >= 0.01
四舍五入到 2 位小数：避免浮点数问题
货币精度：考虑代币小数位数（USDT = 6，ETH = 18）
显示格式：显示用户友好的金额

错误处理

try {
  const order = await client.orders.create({...});
} catch (error) {
  if (error.code === -2) {
    // 认证或参数错误
    console.error('Invalid request:', error.msg);
  } else {
    // 其他错误
    console.error('Order creation failed:', error);
  }
}

常见用例

电商结账

// 在结账流程中
const order = await client.orders.create({
  merchantOrderId: `checkout-${cartId}-${Date.now()}`,
  chainCode: 'erc20',
  coinCode: 'usdt',
  amount: cartTotal,
  callBackUrl: `${API_URL}/webhook`,
  frontendCallbackUrl: `${FRONTEND_URL}/checkout/success`,
});

// 重定向到支付
router.redirect(order.paymentUrl);

订阅支付

//  recurring payment
const order = await client.orders.create({
  merchantOrderId: `subscription-${userId}-${subscriptionId}-${billingCycle}`,
  chainCode: 'polygon-erc20',
  coinCode: 'usdc',
  amount: subscriptionAmount,
  callBackUrl: `${API_URL}/webhook/subscription`,
  frontendCallbackUrl: `${FRONTEND_URL}/subscription/payment-success`,
});

捐赠/一次性支付

// 简单捐赠
const order = await client.orders.create({
  merchantOrderId: `donation-${Date.now()}`,
  chainCode: 'erc20',
  coinCode: 'usdt',
  amount: donationAmount,
  callBackUrl: `${API_URL}/webhook`,
  frontendCallbackUrl: `${FRONTEND_URL}/thank-you`,
});

订单过期

订单可能会在一段时间后过期。如果支付延迟，请定期检查订单状态。

下一步

管理订单：查看和筛选订单
订单状态：了解订单生命周期
Webhook 集成：设置支付通知

订单已创建？ 了解订单管理 →

概述​

快速开始​

订单创建流程​

必需参数​

可选参数​

分步指南​

步骤 1：选择链和货币​

步骤 2：设置支付金额​

步骤 3：生成商户订单 ID​

步骤 4：配置回调​

步骤 5：创建订单​

订单响应​

响应字段​

支付 URL 构造​

订单类型​

DeFi 订单​

CeFi 订单​

最佳实践​

订单 ID 管理​

金额处理​

错误处理​

常见用例​

电商结账​

订阅支付​

捐赠/一次性支付​

订单过期​

下一步​

概述