Cancel a payment
Use webhooks to get notified when a payment is cancelled or expires.
Payments can be cancelled by you or your users. A payment can be cancelled until it enters the executed
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 authorize 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 theauthorizing
state, including payments initiated with the bank. - For EUR payments, you can call the
/cancel
endpoint up to theauthorizing
state, as long as the payment has not already been initiated with the user's bank.
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 | The user cancelled the payment on the HPP or EPP. |
user_canceled_at_provider | An error occurred when the user |
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