Cancel a payment

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, Ireland and Germany, 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.

Below is an example of an error response after you or your user calls the /cancel endpoint when a payment cannot be cancelled:

If the cancellation request is successful, you receive an empty 202 response. This means that we will attempt to cancel the payment. However, we may not be able to successfully cancel that payment. Listen for a webhook event to tell you if the payment was successfully cancelled or if cancellation failed.

202 Accepted

If you call the /cancel endpoint, but the payment has already moved to a non-cancelable status, you receive an error with a 4xx error code. You can successfully call this endpoint until the payment reaches the authorized state in the UK and Germany, and the authorizing state for other geographies. If you send a request at this point or later, you receive a 400 error.

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

If the payment has already moved out of a cancellable state, at this point you can opt to queue a refund which will automatically take place once the payment has settled.

Webhooks

Cancellation success

After you receive a success response from the /cancel endpoint, expect one or more of the following webhook events:

• payment_cancellation_failed, which means that the cancel request was processed, but couldn’t be completed.
  Possible reasons for this are bank downtime, TrueLayer internal errors, or the payment moving out of a cancellable state.
• payment_executed, which means that the payment has already moved out of the payer’s bank account. Usually, this webhook comes after a payment_cancellation_failed webhook.
  In this case, you may want to queue up a refund for the payment.
• payment_failed, which means that the payment did not go through. Sometimes this happens even if the payment could not be successfully cancelled.
  Inside this webhook is a failure_reason field.

Your integration should handle all webhook types to reflect the correct end state.

When you cancel a payment or a payment expires, the payment moves into the failed status. You receive a payment_failed webhook, usually with a failure_reason of canceled.

{
  "type": "payment_failed",
  "event_version": 1,
  "payment_method": {
    "type": "mandate",
    "mandate_id": "d65f3521-fa55-44fc-9a75-ba43456de7f2"
  },
  "payment_source": {
    "account_holder_name": "HOLDER NAME",
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": "111111",
        "account_number": "00000111"
      }
    ]
  },
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "failed_at": "2021-12-25T15:00:00.000Z",
  "failure_stage": "authorizing",
  "failure_reason": "canceled"
}

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

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.

Cancellation failed

If we cannot cancel the payment, in the UK and Germany only, you receive a payment_cancellation_failed webhook notification to let you know.

{
"type": "payment_cancellation_failed",
"event_version": 1,
"event_id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70",
"payment_id": "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
"cancellation_failed_at": "2024-06-15T10:30:00.000Z"
}