Order States

This page documents all possible states of a HashNut payment order and the transitions between them.

State Diagram

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

State Reference

Value	Name	Description
0	INIT	Order created, waiting for customer payment
1	PAID	Payment transaction detected on-chain, pending confirmation
2	CONFIRMING	Transaction is being confirmed (waiting for block confirmations)
3	SUCCESS	Payment confirmed, order completed successfully
4	FINISH	Post-processing complete (e.g., fund collection executed)
-1	FAILED	Payment verification failed (invalid transaction, wrong amount, etc.)
-2	EXPIRED	Order expired before payment was received
-3	CANCELED	Order canceled by the merchant

State Transitions

From	To	Trigger
INIT (0)	PAID (1)	Payment transaction detected on-chain
INIT (0)	EXPIRED (-2)	Order expiration timer elapsed
INIT (0)	CANCELED (-3)	Merchant calls Cancel Order
PAID (1)	CONFIRMING (2)	Block confirmations in progress
CONFIRMING (2)	SUCCESS (3)	Required block confirmations reached
CONFIRMING (2)	FAILED (-1)	Transaction reverted or verification failed
SUCCESS (3)	FINISH (4)	Fund collection completed

Terminal States

The following states are final and cannot transition further:

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

WARNING

SUCCESS (3) is not a terminal state. It transitions to FINISH (4) after fund collection. However, for most merchant integrations, SUCCESS is the state where you should fulfill the customer's order.

Webhook Notification States

Webhook notifications are sent for the following state transitions:

New State	When Notified
PAID (1)	Payment detected
SUCCESS (3)	Payment confirmed
FAILED (-1)	Verification failed
EXPIRED (-2)	Order expired

TIP

The most important state to handle is SUCCESS (3). This is when you should deliver the product or service to the customer. See Notifications for webhook payload details.

Checking States in Code

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
}