订单状态

本页记录了 HashNut 支付订单的所有可能状态及其之间的转换关系。

状态图

                          ┌──────────────┐
                          │  INIT (0)    │
                          └──────┬───────┘
                                 │
                    ┌────────────┼────────────┐
                    │            │            │
                    v            v            v
            ┌──────────┐  ┌──────────┐  ┌───────────┐
            │CANCELED   │  │EXPIRED   │  │ PAID (1)  │
            │  (-3)     │  │  (-2)    │  └─────┬─────┘
            └──────────┘  └──────────┘        │
                                              v
                                      ┌──────────────┐
                                      │CONFIRMING (2)│
                                      └──────┬───────┘
                                             │
                                    ┌────────┴────────┐
                                    v                 v
                            ┌────────────┐    ┌────────────┐
                            │SUCCESS (3) │    │FAILED (-1) │
                            └──────┬─────┘    └────────────┘
                                   │
                                   v
                            ┌────────────┐
                            │FINISH (4)  │
                            └────────────┘

状态参考

值	名称	说明
0	INIT	订单已创建，等待客户付款
1	PAID	链上检测到支付交易，待确认
2	CONFIRMING	交易确认中（等待区块确认）
3	SUCCESS	支付已确认，资金已经到账
4	FINISH	后处理完成，通知商户并得到商户确认响应
-1	FAILED	支付验证失败（无效交易、金额不符等）
-2	EXPIRED	订单在收到付款前已过期
-3	CANCELED	订单被商户取消

状态转换

起始状态	目标状态	触发条件
INIT (0)	PAID (1)	链上检测到支付交易
INIT (0)	EXPIRED (-2)	订单过期计时器到期
INIT (0)	CANCELED (-3)	商户调用取消订单
PAID (1)	CONFIRMING (2)	区块确认进行中
CONFIRMING (2)	SUCCESS (3)	达到所需区块确认数
CONFIRMING (2)	FAILED (-1)	交易回滚或验证失败
SUCCESS (3)	FINISH (4)	通知商户并得到商户确认响应

终态

以下状态为最终状态，不会再发生转换：

• FINISH (4)
• FAILED (-1)
• EXPIRED (-2)
• CANCELED (-3)

WARNING

SUCCESS (3) 不是终态。它会在通知商户并得到商户响应后变为 FINISH (4)。但对于大多数商户集成场景，SUCCESS 是您应当履行客户订单的状态。

Webhook 通知状态

以下状态转换时会发送 Webhook 通知：

新状态	通知时机
PAID (1)	检测到支付
SUCCESS (3)	支付已确认
FAILED (-1)	验证失败
EXPIRED (-2)	订单已过期

TIP

最重要的状态是 SUCCESS (3)。这是您应当向客户交付商品或服务的时机。有关 Webhook 载荷详情，请参阅通知。

在代码中检查状态

const (
	StateInit       = 0
	StatePaid       = 1
	StateConfirming = 2
	StateSuccess    = 3
	StateFinish     = 4
	StateFailed     = -1
	StateExpired    = -2
	StateCanceled   = -3
)

// After querying an order
switch result.State {
case StateSuccess, StateFinish:
	// Fulfill the order
case StatePaid, StateConfirming:
	// Still processing, wait
case StateFailed:
	// Handle failure
case StateExpired:
	// Order expired, prompt customer to create a new order
case StateCanceled:
	// Order was canceled
default:
	// INIT - still waiting for payment
}