Order lifecycle

The states a collection order moves through, the edge states, and the one event you credit on.

A collection order is the thing you drive to completion. Its progress is reflected in the webhook event names, and the order object itself is always the ground truth for where a payment stands.

The happy path

collection.order.created
  → collection.deposit.detected
  → collection.deposit.confirmed
  → disbursement.completed

Edge states

Alongside the happy path, these can occur at any point:

• collection.amount.underpaid / collection.amount.overpaid — the received amount fell outside the quoted asset_amount (see Amounts).
• collection.deposit.wrong_chain — funds arrived on the wrong network; the order is still payable on the correct one.
• collection.order.expired — the quote lapsed before a deposit (re-lock via Rates and quotes).
• collection.order.failed — the order could not complete.

The order object is ground truth

The order carries status, amount_status, deposit, disbursement, and quote. Retrieve it any time with pulse.collectionOrders.retrieve(orderId) — in the current preview, lifecycle is observed by polling this rather than by webhook. The sandbox can simulate every state above against a real order.

Credit only on disbursement.completed

Credit a customer only after a verified disbursement.completed webhook. Client-side callbacks such as onSuccess are UX signals — they can be spoofed. The signed webhook is the only source of truth for crediting a user.

Where to go next

• Webhooks — verify, de-duplicate, and credit off a verified event
• Webhook events — every event and its payload
• Amounts and precision — how amount_status is decided