跳到主要内容

订单状态

了解订单状态对于构建可靠的支付集成至关重要。HashNut 使用数字状态系统来跟踪订单的整个生命周期。

状态概述​

活动状态（进行中）​

状态 0：未支付​

代码：0
状态：unpaid

描述：订单已创建但尚未收到支付。

发生的情况：

  • 订单正在等待客户支付
  • 支付链接处于活动状态
  • 客户可以继续支付

商户操作：

  • ✅ 查看支付链接
  • ✅ 取消订单
  • ✅ 监控订单状态

下一个状态：

  • → 1（未完成）- 客户发起支付
  • → -2（已过期）- 订单过期
  • → -3（已取消）- 商户取消

状态 1：未完成​

代码：1
状态：notCompleted

描述：支付交易已发起但尚未完成。

发生的情况：

  • 客户已开始支付
  • 交易正在准备中
  • 等待钱包确认

商户操作：

  • ✅ 监控订单
  • ✅ 如需要可以取消
  • ⚠️ 等待完成

下一个状态：

  • → 2（等待确认）- 交易已广播
  • → -1（失败）- 交易被拒绝

状态 2：等待区块链确认​

代码：2
状态：waitingForBlockchainConfirmation

描述：交易已广播到区块链，等待确认。

发生的情况：

  • 交易在区块链上
  • 等待区块包含
  • 确认数增加

商户操作：

  • ✅ 监控确认进度
  • ✅ 在区块链浏览器上检查交易
  • ⚠️ 等待确认

下一个状态：

  • → 3（确认中）- 区块已确认
  • → -1（失败）- 交易失败

状态 3：确认中​

代码：3
状态：confirming

描述：交易已在区块链上确认，系统正在验证支付详情。

发生的情况：

  • 交易已确认
  • HashNut 正在验证：
    • 金额是否匹配
    • 地址是否正确
    • 代币是否正确
    • 确认数是否足够

商户操作：

  • ✅ 订单正在处理中
  • ⚠️ 等待验证

下一个状态：

  • → 4（成功）- 支付已验证
  • → -1（失败）- 验证失败

状态 4：成功​

代码：4
状态：success

描述：支付已成功接收并验证，订单已完成。

发生的情况：

  • ✅ 支付已验证
  • ✅ 资金在智能合约中
  • ✅ 已发送 Webhook（如果已配置）
  • ✅ 订单完成

商户操作：

  • ✅ 履行订单
  • ✅ 更新数据库
  • ✅ 处理业务逻辑

下一个状态：无（终端状态）

终端状态（最终）​

状态 -1：失败​

代码：-1
状态：failed

描述：支付交易失败或被拒绝。

常见原因：

  • 客户拒绝交易
  • 余额不足
  • 交易执行失败
  • 网络错误

商户操作：

  • ✅ 查看失败原因
  • ✅ 如需要创建新订单
  • ✅ 如需要联系客户

下一个状态：无（终端状态）

状态 -2：已过期​

代码：-2
状态：expired

描述：订单在配置的时间限制内未支付而过期。

发生的情况：

  • 订单不再有效
  • 支付链接处于非活动状态
  • 客户无法支付

商户操作：

  • ✅ 如需要创建新订单
  • ✅ 通知客户
  • ✅ 清理过期订单

下一个状态：无（终端状态）

状态 -3：已取消​

代码：-3
状态：cancelled

描述：订单已被商户或系统取消。

发生的情况：

  • 订单被有意取消
  • 支付链接处于非活动状态
  • 无法进行支付

商户操作：

  • ✅ 订单已关闭
  • ✅ 如需要创建新订单

下一个状态：无（终端状态）

状态参考表​

状态代码状态值类型描述
未支付0unpaid活动等待支付
未完成1notCompleted活动支付已发起
等待确认2waitingForBlockchainConfirmation活动交易已广播
确认中3confirming活动验证支付中
成功4success终端支付完成
失败-1failed终端支付失败
已过期-2expired终端订单已过期
已取消-3cancelled终端订单已取消

在代码中处理状态​

检查订单状态​

const order = await client.orders.query({
  payOrderId,
  merchantOrderId,
  accessSign,
});

// 处理不同状态
switch (order.state) {
  case 0:
    console.log('Order unpaid - waiting for payment');
    break;
  case 1:
  case 2:
  case 3:
    console.log('Payment in progress...');
    break;
  case 4:
    console.log('Payment successful!');
    await fulfillOrder(merchantOrderId);
    break;
  case -1:
    console.log('Payment failed');
    await handlePaymentFailure(merchantOrderId);
    break;
  case -2:
    console.log('Order expired');
    await handleExpiredOrder(merchantOrderId);
    break;
  case -3:
    console.log('Order cancelled');
    break;
}

Webhook 状态处理​

app.post('/webhook', async (req, res) => {
  const { state, merchantOrderId } = req.body;
  
  // 仅处理终端状态
  if (state === 4) {
    // 支付成功
    await fulfillOrder(merchantOrderId);
  } else if (state < 0) {
    // 支付失败、过期或已取消
    await handleOrderTermination(merchantOrderId, state);
  }
  // 活动状态 (0-3) 仅用于信息
  
  res.send('success');
});

状态转换​

正常流程​

0 (未支付) 
  → 1 (未完成) 
  → 2 (等待确认) 
  → 3 (确认中) 
  → 4 (成功)

失败流程​

0 (未支付) 
  → 1 (未完成) 
  → -1 (失败)  [交易被拒绝]
0 (未支付) 
  → 1 (未完成) 
  → 2 (等待确认) 
  → -1 (失败)  [交易失败]

过期流程​

0 (未支付) 
  → -2 (已过期)  [超时]

取消流程​

0 (未支付) 
  → -3 (已取消)  [手动取消]

最佳实践​

状态监控​

  1. 轮询活动订单：定期检查状态为 0-3 的订单
  2. 处理终端状态：始终处理状态 4、-1、-2、-3
  3. 幂等性：确保状态更改是幂等的
  4. 日志记录：记录所有状态转换以便调试

基于状态的操作​

const stateHandlers = {
  0: () => console.log('Waiting for payment'),
  1: () => console.log('Payment initiated'),
  2: () => console.log('Transaction confirming'),
  3: () => console.log('Verifying payment'),
  4: async (orderId) => {
    await fulfillOrder(orderId);
    await sendConfirmationEmail(orderId);
  },
  '-1': async (orderId) => {
    await notifyCustomer(orderId, 'Payment failed');
    await createRetryOrder(orderId);
  },
  '-2': async (orderId) => {
    await notifyCustomer(orderId, 'Order expired');
  },
  '-3': () => console.log('Order cancelled'),
};

下一步​

了解状态？ 了解订单管理 →