Payment lifecycle
The states a payment moves through, and which ones are final.
created → awaiting_customer → authorized → settled
│ │
├──────────────────┴──→ failed
├─────────────────────→ cancelled
└─────────────────────→ expired| Status | Meaning | Final |
|---|---|---|
created | Recorded; the bank has not been called yet | No |
awaiting_customer | Redirect issued, customer has not paid | No |
authorized | Customer paid; funds not yet settled | No |
settled | Money moved. Fulfil here. | Yes |
failed | Declined or errored | Yes |
cancelled | Abandoned or cancelled | Yes |
expired | Never completed in time | Yes |
Notifications can arrive out of order. Banks
do not guarantee ordering, so a settlement can reach us before the
authorisation. We handle that, and a payment never moves backwards out of a
final state. Build your side the same way: treat the same event twice as a
no-op.
Cancelling
POST
/v1/payments/{id}/cancel
Only while created or awaiting_customer. Once the
bank has authorised, the correct action is a refund.
Methods that settle asynchronously cannot be
cancelled. Multibanco is payable at an ATM days after the customer
leaves your checkout, and nothing we send can stop them paying. Rather than
tell you a payment is dead while the customer's money can still move, we
refuse the cancellation with
cannot_cancel_async_method. Stop waiting on the payment at your
end, and if payment.settled arrives later, treat it as
authoritative: it means the customer paid.