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 authorization_required or authorizing status indefinitely, they expire after 15 minutes. They will move to the failed status, with the failure reason expired.

In the UK and Ireland, payments can expire up to, and at, the authorizing status. However, in the rest of Europe, payments cannot expire after the point at which they transition to authorizing.

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. This works until the payment reaches the authorized state -- at this point, you receive a 400 error.

Below is an example of an error response after you or your user calls the /cancel endpoint when a payment cannot 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 3 months ago