Cancel a payment

Use webhooks to get notified when a payment is cancelled or expires.

Either you or your users can cancel a payment. A payment can be cancelled until it enters the authorised status. Payments and mandates which are abandoned also expire.

To cancel a payment, make a POST request to the /v3/payments/{id}/actions/cancel endpoint.

Automatic payment or mandate expiration

An action that a user takes which doesn't authorise a payment or mandate, and doesn't cancel it, is abandoning the payment or mandate. For example, they might navigate to another tab in their browser and leave the payment UI open, or even close the browser completely.

To prevent payments or mandates being stuck in the authorizing status indefinitely, they expire after 15 minutes. They will move to the failed status, with the failure reason expired.

Cancel a payment

User-cancelled

Your user can cancel a payment by clicking a CTA within the payment authorisation UI (such as the hosted or embedded payments page), or by clicking the exit button when they are redirected to their provider. This makes a POST request to the /cancel endpoint.

Merchant-cancelled

To cancel a payment yourself, for example if you notice a payment sitting in authorizing for a long time, you can also call the /cancel endpoint. Supply the id of the payment in the API request.

For GBP payments, you can call the /cancel endpoint for all payments in the authorizing state.
For EUR payments, you can call the /cancel endpoint up to the authorizing state.

Once the payment has moved into the authorized state, it has been sent to the bank and can no longer be cancelled.

Below is an example of an error response where you or your user has called the /cancel endpoint after the stage where a payment can be cancelled:

{
  "type": "https://docs.truelayer.com/docs/error-types#invalid-state",
  "title": "Invalid State",
  "status": 400,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "Status of the payment does not allow this action to be executed."
}

Webhooks

When you cancel a payment or a payment expires, the payment moves into the failed status. You receive a payment_failed webhook.

The reason for the failure is returned in the failure_reason field.

Failure reason	When this happens
`canceled`	You cancelled the payment by calling the `/cancel` endpoint.
`user_canceled_at_provider` `not_authorized`	The user cancelled the payment during provider selection. Depending on the bank, you may receive either of these failure reasons.
`expired`	The payment token expired before the user authorised the payment.

Learn more about other reasons why a payment can fail.

To prevent any new payments being made on a mandate, you can revoke the mandate. Learn more about how.

Updated 11 days ago