Payment lifecycle
Interpret every payment state and confirm the final outcome.
States
| State | Meaning | Final? |
|---|---|---|
queued | Accepted and waiting for dispatch | No |
submitted | Dispatch has begun; confirmation is pending | No |
unknown | The outcome is uncertain and requires confirmation | No |
succeeded | Payment success has been confirmed | Yes |
failed | Payment failure has been confirmed | Yes |
Allowed transitions
queued ──────> submitted ──────> succeeded
│ │
│ ├──────────> failed
│ │
│ └──────────> unknown ──> succeeded
│ └──> failed
└───────────────────────────> failedFinal states do not transition to another payment state. Duplicate provider results are handled as repeat notifications, not new settlements.
What your application should do
Store the payment ID and current status. A 202 response only acknowledges acceptance. Fulfil an order or mark a payout paid after observing succeeded.
For failed, display the failure and allow a deliberate new payment attempt with a new idempotency key. For unknown, keep the original payment open and seek confirmation; do not create an automatic replacement.
Balance implications
A payout reserves its amount and applicable fees while processing. A confirmed failure releases its reservation; an uncertain outcome retains it. Available payout balance can therefore be lower than the merchant's total funds.
A successful collection does not necessarily become immediately available for B2C payouts. Use payout_available_minor from the balance endpoint, and allow for applicable charges.
Polling and webhooks
Use GET payment with backoff, or subscribe to terminal webhooks. Deliveries may be repeated or delayed. Fetch the payment if an event conflicts with your locally stored status.