Payment status
Every payment has one status. Five of them are final: a final payment does not change again, except that an expired payment becomes paid_late if the money still arrives.
On this page
Statuses
| Status | Meaning | Final |
|---|---|---|
created | Waiting for the buyer to choose a method. | no |
pending | The buyer chose a method; the payment is under way at the provider. | no |
paid | The payment was paid in time. | yes |
paid_late | The payment had expired, but the money arrived anyway. The seller confirms it by hand: nothing is paid out or announced for it automatically. | yes |
failed | The payment failed at the provider. | yes |
canceled | The payment was canceled, for example with the cancel call. | yes |
expired | The time ran out before the buyer paid. Nothing was charged. | yes |
Status changes and events
| When the payment becomes | Webhook event |
|---|---|
paid | payment.paid |
failed | payment.failed with reason: "failed" |
canceled | payment.failed with reason: "canceled" |
expired | payment.expired |
A payment expires after expires_in_minutes (24 hours by default). A method that takes days, such as Multibanco, a bank transfer or a cash voucher, moves expires_at once, later, when the buyer picks it. Read expires_at again after the buyer has chosen.
Canceling a payment
curl -sS -X POST https://payments.example.com/api/v1/payments/pay_0123456789abcdefghjkmnpq/cancel \
-H "Authorization: Bearer cp_test_..."The request takes no body. The answer is the payment with status canceled.
- A
createdpayment, or apendingone that has not reached a provider yet, is canceled at once. - A
pendingpayment at its provider is canceled there first. If the provider cannot be reached the answer is502 provider_errorwithRetry-After: nothing changed, and the call is safe to repeat. - A payment in a final status, and a pending payment at a provider without a cancel (a Payssion payment, a test-mode payment), answers
409 not_cancellable.
Confirming a payment
Treat a webhook as a hint that something changed. Before you act on it, for example before you ship an order, read the payment and use what the API returns:
curl -sS https://payments.example.com/api/v1/payments/pay_0123456789abcdefghjkmnpq \
-H "Authorization: Bearer cp_test_..."To list payments, use GET /v1/payments with pagination. A recurring charge of a subscription is an ordinary payment with subscription_id set.