Skip to content
Creative Payments

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

StatusMeaningFinal
createdWaiting for the buyer to choose a method.no
pendingThe buyer chose a method; the payment is under way at the provider.no
paidThe payment was paid in time.yes
paid_lateThe payment had expired, but the money arrived anyway. The seller confirms it by hand: nothing is paid out or announced for it automatically.yes
failedThe payment failed at the provider.yes
canceledThe payment was canceled, for example with the cancel call.yes
expiredThe time ran out before the buyer paid. Nothing was charged.yes

Status changes and events

When the payment becomesWebhook event
paidpayment.paid
failedpayment.failed with reason: "failed"
canceledpayment.failed with reason: "canceled"
expiredpayment.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

Cancel a paymentcurl
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 created payment, or a pending one that has not reached a provider yet, is canceled at once.
  • A pending payment at its provider is canceled there first. If the provider cannot be reached the answer is 502 provider_error with Retry-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:

Retrieve a paymentcurl
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.