Refund a payment

Create a refund and learn the differences between payouts and refunds.

Sometimes a customer isn't satisfied with the items or services that they've purchased. In this situation, you may have to refund them.

While both payouts and refunds are payments made from your account to a customer's account, they are not the same.

A payout is a payment made from your merchant account to a user's account.

A refund is a repayment of a payment made to your merchant account. Refunds are tied to a specific payment id. They:

  • Must be made to the original payment account.
  • Can be issued across multiple payments.
  • Cannot exceed the original payment amount.

With the Payments API v3, you can fully or partially refund payments made into your TrueLayer merchant accounts.


Set up refunds in Console

You can also make refunds directly from the payments view in Console, if you have the right permissions within your application to do so. This allows you to refund payments without needing to integrate with the Payments endpoint.

Create a refund

Before you start

To create a refund, you must have:

To let your users make payments to your merchant account, follow the instructions in our guide to setting up single payments.

We recommend that you use refund webhook notifications to get real-time status updates for your refunds.

Make a full or a partial refund on a single payment

Make a POST request to the the /v3/payments/{payment_id}/refunds endpoint with the following parameters:

amount_in_minorThe amount to refund in the smallest possible denomination. If transacting in GBP, for example, this will be in pennies.

This is not a required field. If it is not specified, TrueLayer will assume you are requesting a full refund (so the requested payment refund amount is the same as the payment amount by default).

The amount in this field can never be greater than the amount of the original payment.
referenceThe reference that appears on a bank statement.

This must be 18 characters or less.
payment_idThe ID of the original payment that you want to refund.
curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     -H "X-TL-Signature: ${signature}" \
     -H "Idempotency-Key: ${idempotency_key}" \
     --data '{
        "amount_in_minor": 10000,
        "reference": "Withdrawal 204",
}' \{payment_id}/refunds

If successful, you get an HTTP 202 response along with the refund id.


Refunds can take time

Once a refund is accepted by TrueLayer, it can take up to 24 hours for the refund to reach a terminal state.

Make multiple refunds for a single payment

When you make a refund request, the amount you specify will be subtracted from the total refundable amount — unless the refund status changes to failed. If a refund fails, it won't count towards the total refundable amount.

Get the details of a single refund

To get the details of a refund, make a GET request to the .../v3/payments/{payment_id}/refunds/{refund_id} endpoint.

curl -X GET
     -H "Authorization: Bearer ${access_token}" \
     -H "X-TL-Signature: ${signature}" \{payment_id}/refunds/{refund_id}