支付流程
从创建订单到结算的完整支付生命周期。
时序图
查看流程图源码
sequenceDiagram
participant M as Merchant Server
participant H as HashNut API
participant B as Blockchain
participant C as Customer
M->>H: 1. Create Order
H-->>M: payOrderId, receiptAddress, payUrl
M->>C: 2. Redirect to payUrl / show receiptAddress
C->>B: 3. Transfer tokens to receiptAddress
B-->>H: 4. Detect incoming transfer
Note over H: Order state → PAID (1)
B-->>H: 5. Block confirmations
Note over H: Order state → CONFIRMING (2)
Note over H: Order state → SUCCESS (3)
H->>M: 6. POST webhook to Notify URL
M-->>H: 7. HTTP 200 "success"
分步说明
| 步骤 | 操作 | 说明 |
|---|---|---|
| 1 | 创建订单 | 商户调用 POST /v4.0.0/api/orders/create。HashNut 返回 receiptAddress 和 payOrderId。 |
| 2 | 展示支付信息 | 将客户重定向至 payUrl，或使用 receiptAddress 和 amount 构建自定义支付页面。 |
| 3 | 客户付款 | 客户在指定链上将代币金额发送至 receiptAddress。 |
| 4 | 到账检测 | HashNut 检测到转账。订单状态变为 PAID (1)。 |
| 5 | 区块确认 | HashNut 等待所需的区块确认数。状态变为 CONFIRMING (2)，然后变为 SUCCESS (3)。 |
| 6 | Webhook 通知 | HashNut 向商户的 Notify URL 发送 POST 请求，包含支付结果。 |
| 7 | 确认收到 | 商户返回 HTTP 200 + 响应体 success。 |
状态流转
查看流程图源码
stateDiagram-v2
[*] --> INIT: Create Order
INIT --> PAID: Payment detected
INIT --> EXPIRED: Timeout
INIT --> CANCELED: Merchant cancels
PAID --> CONFIRMING: Tx in block
CONFIRMING --> SUCCESS: Confirmations reached
CONFIRMING --> FAILED: Tx reverted
SUCCESS --> FINISH: Funds settled
不足额支付处理
如果客户支付的金额少于所需金额，HashNut 会为差额部分创建一个补单。
| 场景 | 处理方式 |
|---|---|
| 部分支付 | 为差额创建补单 |
| 多次部分支付 | 每次部分支付都会生成新的补单，直到覆盖全部金额 |
| 查询补单 | 使用查询补单 API |
WARNING
补单与原订单共享相同的 payOrderId。当订单状态未进入 SUCCESS 时，请务必检查补单列表。
订单过期
- 默认过期时间：可通过
expireDuration配置（最长 259,200 秒 = 3 天） - 过期订单会将其收款地址释放回地址池
- 过期订单不可恢复 —— 需创建新订单
DANGER
不要复用过期订单的收款地址。请始终创建新订单以获取新的地址。