Payment States

Every payment — and payout — moves through a defined lifecycle. Understanding state transitions helps you handle them correctly.

State Machine#

States#

ACTIVE

Payment link created, waiting for customer to initiate. Can be cancelled or will expire.

PROCESSING

Customer selected chain/token and initiated payment. Waiting for on-chain confirmation.

SUCCESSFUL

On-chain transaction confirmed. Funds distributed to merchant (and sellers if split).

Terminal state

FAILED

Transaction reverted or bundler error. The payment did not complete.

Terminal state

EXPIRED

Payment reached its expiresAt time before being initiated.

Terminal state

CANCELLED

Merchant cancelled the payment via API.

Terminal state

State Transitions#

From	To	Trigger
ACTIVE	PROCESSING	Customer selects chain/token and initiates payment
ACTIVE	CANCELLED	Merchant cancels via API
ACTIVE	EXPIRED	Payment reaches expiresAt
PROCESSING	SUCCESSFUL	On-chain transaction confirmed
PROCESSING	FAILED	Transaction reverts or bundler error

Important Notes#

PROCESSING never expires

Once a customer initiates payment, the payment cannot expire anymore. It must either succeed or fail PROCESSING.

Only ACTIVE can be cancelled

You can only cancel payments that haven't been initiated yet. Use DELETE /v1/payments/:id.

Terminal states are final

SUCCESSFUL, FAILED, EXPIRED, and CANCELLED are permanent. No further transitions occur.

Payouts share this lifecycle

Payouts use the same states and transitions. Only ACTIVE payouts can be cancelled (DELETE /v1/payouts/:id), a PROCESSING payout never expires, and payouts emit the matching payout.* webhook events.