Order lifecycle

The diagram below shows the high-level state machine. All status values shown correspond exactly to the values returned by the API.

State diagram

stateDiagram-v2
    [*] --> initialized: Create order request
    
    initialized --> canceled: manual cancellation
    initialized --> awaiting_payment: validate and create deposit instructions
    
    awaiting_payment --> canceled: manual cancellation
    awaiting_payment --> paid: full amount received
    awaiting_payment --> partially_paid: partial amount received
    awaiting_payment --> expired: expired

    partially_paid --> paid: remaining amount<br> received
    partially_paid --> partially_paid_expired: partially paid <br>and expired

    partially_paid_expired --> paid: manually captured
    partially_paid --> partially_paid: partial payment

    expired --> [*]
    partially_paid_expired --> [*]
    canceled --> [*]
    paid --> [*]

Status definitions

Status	Meaning	Terminal	Notes
`initialized`	Order has been created and is being prepared (validations, rail selection).	No	Deposit instructions may not be available yet.
`awaiting_payment`	Order is ready to receive payments.	No	Deposit instructions are available when applicable.
`partially_paid`	A partial amount has been received, but the order is not fully paid.	No	Requires `capabilities.partial_payments=true`.
`paid`	The order has received the required amount and is complete.	Yes	Additional payments are rejected unless `can_overpay=true`.
`expired`	The order expired before receiving the required amount.	Yes	Further payments are not expected.
`partially_paid_expired`	The order expired with a partial amount received.	Yes	May be manually captured depending on merchant workflows.
`canceled`	The order was canceled by the merchant.	Yes	Late payments may be treated as orphaned or failed depending on the rail.

Common transition triggers

Create order → initialized
Order preparation completed → awaiting_payment
Payment detected:
- partial amount → partially_paid
- full amount → paid
Expiration reached:
- no payments → expired
- partial payments → partially_paid_expired
Merchant cancellation (if can_cancel=true) → canceled
Manual capture → paid from partially_paid_expired

Notes

Status updates are delivered via webhooks and reflected in the Orders API.
Not all transitions are allowed for all orders; capabilities and rail rules apply.
Once an order reaches a terminal state, no further automatic transitions occur.