Information Flow

This page is about how the order state advances: which states an order passes through from creation to completion, what triggers each transition, and at which step you get notified.

Its counterpart, Fund Flow, is about where the money goes. The division of labor is:

	Fund flow	Information flow
Concerned with	Where the money is now and where it goes next	Which order a payment belongs to, and how far along the order is
Driven by	The merchant, who initiates claims and withdrawals	HashNut, which detects on-chain arrivals, advances state and sends notifications
Carried by	On-chain transactions	Order state + webhook notifications

TIP

An order reaching SUCCESS only means the payment has been received and you can fulfil the order. It does not mean the money is already in your withdraw address — that still requires you to claim and release. See Fund Flow.

Every term used on this page is defined in the Glossary.

Sequence Diagram

Step-by-Step

Step	Action	Description
1	Create Order	Merchant calls POST /v4.0.0/api/orders/create. HashNut returns receiptAddress and payOrderId.
2	Display Payment	Redirect customer to payUrl, or build your own page with receiptAddress and amount.
3	Customer Pays	Customer sends the token amount to receiptAddress on the specified chain.
4	Detection	HashNut detects the transfer. Order state → PAID (1).
5	Confirmations	HashNut waits for required block confirmations. State → CONFIRMING (2), then SUCCESS (3).
6	Webhook	HashNut POSTs to the merchant's Notify URL with the payment result.
7	Query Back	Merchant verifies the signature first, then calls Query Order with the payOrderId + accessSign from the notification and updates the local order from the query result.
8	Acknowledge	Merchant responds with HTTP 200 + body success.

WARNING

Step 7 is not optional. The notification payload carries only four fields — payOrderId, merchantOrderId, accessSign and state — so do not fulfil an order based on the state in the payload alone. The authoritative amount, transaction hash and supplement status all come from the query API. Acknowledge with success only after the query succeeds: that way, if your handler fails, HashNut will deliver the notification again according to its retry policy.

State Flow

When the Amount Doesn't Match

When the amount paid differs from the order amount, what happens to the order state is decided by the overpay / underpay policy on the api key.

Underpayment

If the customer sends less than the required amount, the order stays at PAID(1) and HashNut creates a supplement order for the remaining balance.

Scenario	Behavior
Partial payment	Supplement order created for the difference
Multiple partials	Each partial generates a new supplement until full amount covered
Query supplements	Use Query Supplements API

Whether you are notified at that point is decided by the underpay policy: NOTIFY (default) notifies you, SILENT waits quietly for the top-up.

WARNING

Supplement orders share the same payOrderId. Always check the supplement list when the order state does not progress to SUCCESS.

Overpayment

If the customer sends more than the order amount, the overpay policy decides what happens:

Policy	Order state
AUTO_CONFIRM (default)	Moves straight to CONFIRMING(2) and is treated as paid
MANUAL	Stays in its current state, awaiting manual handling

WARNING

The excess is claimed into the split wallet along with everything else and is split by share. HashNut does not refund the difference automatically — settle any refund with the customer yourself.

Order Expiration

• Default expiration: configurable via expireDuration (max 259,200 seconds = 3 days)
• Expired orders release their receipt address back to the pool
• Expired orders cannot be resumed — create a new order

DANGER

Do NOT reuse receipt addresses from expired orders. Always create a new order to get a fresh address.

TIP

Releasing an address does not affect funds that already arrived — the money stays at that on-chain receipt address and can still be claimed. For what happens to funds from an expired order, see Fund Flow · Where the money ends up in edge cases.

Next

• Fund Flow — how the funds you receive are claimed and withdrawn
• Notifications — payload structure, signature verification and retry policy
• Order States — the full table of state values and transitions