Order States

Interpret sms4sats order lifecycle states and know when to stop polling.

Always use server state as the source of truth. Do not infer order status from elapsed time, payment-wallet UI, or the presence of a phone number alone.

Bearer-token SMS and rentals

State	Meaning	Client action
pending_payment	Invoice created; payment not accepted	Present invoice; allow immediate cancellation
paid	Hold accepted	Poll
allocating	Provider allocation in progress	Poll; do not cancel unless API marks eligible
waiting_for_sms	Number assigned, waiting for message	Display number; poll
code_received	Message durably recorded; settlement pending	Preserve message; poll
rent_active	Rental allocated and active	Display number/messages; poll until end
settlement_pending	Fulfillment recorded; hold settlement retrying	Poll; do not create replacement
release_pending	Hold release retrying	Poll; do not create replacement
expiring	Expiry cleanup in progress	Poll
cancelling	Cancellation cleanup in progress	Poll
completed	Fulfilled and finalized	Stop
cancelled	User cancellation finalized	Stop
expired	Timed out and finalized	Stop
failed	Fulfillment failed and payment cleanup completed or recorded	Stop; inspect response/error

L402 SMS and rentals

The implemented L402 states are pending_payment, paid, allocating_number, waiting_for_sms, rent_active, cancel_pending, refund_pending, refunded, refund_failed, completed, and failed.

Terminal L402 states are completed, refunded, refund_failed, and failed.

Email

State	Meaning
pending_payment	Hold invoice awaits payment
paid	Payment accepted; allocation starting
waiting_for_email	Address assigned; waiting for code/message
code_received	Delivery stored; settlement may still be retrying
completed	Delivery and settlement finalized
cancelled	User cancellation and hold release finalized
failed	Allocation/provider flow failed
expired	Timed out without delivery

Robust polling

1. Poll every 5–10 seconds with the same order credential.

2. Use expiresAt for display, not as permission to create a duplicate.

3. Continue through transitional payment and cleanup states.

4. Stop only on a documented terminal state.

5. If a request fails transiently, retry polling with exponential backoff and jitter.