Payment refund
Learn how to make refunds on a payment.
Sometimes a customer isn't satisfied with the items or services that they've purchased. In such a situation, you often have to provide them with a refund, which is a repayment of the funds back to the customer (payer).
With our Payments API, you can either fully or partially refund payments made into your TrueLayer-managed merchant accounts. Follow this guide to learn how to make refunds with Payments API v3.
While both payouts and refunds are payments made from your account to a customer's account, they are not the same.
A refund is not a payout
A payout refers to the expected financial returns from investments or other activities. A payout may be expressed on an overall or periodic basis.
A refund refers to a repayment tied to a specific payment. A few properties that makes a refund different to a payout:
- A refund has to be made to the original payment method.
- A refund can not exceed the original payment amount.
- Multiple refunds can be made to one payment.
Check out the API reference for Payments API v3
Refer to the API reference for further information on creating a refund.
Before you make a refund
You must have at least one settled transaction from the relevant customer in your merchant account. You can only process a refund if you can associate it with an existing settled payment.
To let your users make payments to your merchant account, follow the instructions in our guide to set up single payments.
We encourage you to use webhooks to get real-time status notifications on your refunds.
Requests should be signed
All the requests in this guide should be signed on your server/backend.
Make a full or a partial refund on a single payment
Make a POST
request to /payments/{payment_id}/refunds
endpoint with the following parameters:
Field | Description |
---|---|
| The amount to refund in the smallest denomination of the currency specified. For example, if transacting in GBP, this will be in pennies. As this is not a required field, when it is not specified, TrueLayer assumes you are requesting for a full refund i.e. the requested payment refund amount is the same as the payment amount. |
| The reference that will appear on your bank statement. Note: this can only be 18 characters or less. |
Idempotency
To create a refund the request must include an idempotency key. You can learn more about API idempotency.
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",
}' \
https://payouts.truelayer-sandbox.com/payments/{payment_id}/refunds
You'll get an HTTP 202
response with the created refund id
.
Time to complete a refund
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 on a single payment
When you make a refund request, the specified amount will be removed from the available payment amount to refund unless the refund status changes to failed
. At that point, the refund amount will be reallocated to the available payment amount to refund.
Get details of a single refund
To get a refund make a GET
request to /payments/{payment_id}/refunds/{refund_id}
. Refer to the API reference for further information on getting a refund
curl -X GET
-H "Authorization: Bearer ${access_token}" \
-H "X-TL-Signature: ${signature}" \
https://payouts.truelayer-sandbox.com/payments/{payment_id}/refunds/{refund_id}
Refund statuses
A refund has four different statuses during its lifecycle, as detailed below:
Status | Definition |
---|---|
| The refund has been created with TrueLayer's API but it has not yet been authorized and sent to the payment scheme for execution. |
| The refund has been created via TrueLayer's API and has been sent to the payment scheme for execution. |
| The refund was executed. The payment refund amount has been deduced from your Merchant Account. |
| The refund failed. The payment refund amount has not been deduced from your Merchant Account. |
Status transition diagram


Refund status transitions
Updated 16 days ago