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:
- A
Bearer access_token
. - A
Tl-Signature
and idempotency key. See more about signing requests in our documentation. - A merchant account.
- At least one transaction from the customer to refund in your merchant account. You also need the payment
id
from that payment with a status ofsettled
.
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:
Field | Description |
---|---|
amount_in_minor | The 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. |
reference | The reference that appears on a bank statement. This must be 18 characters or less. |
payment_id | The 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",
}' \
https://api.truelayer-sandbox.com/v3/payments/{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}" \
https://api.truelayer-sandbox.com/v3/payments/{payment_id}/refunds/{refund_id}
Updated 3 months ago