Create a refund

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 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.

👍

API reference

See the API reference for more about refunds.

Before you make a refund

You must have at least one transaction from the customer you want to refund in your merchant account. This is because 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 setting up single payments.

We encourage you to use webhooks to get real-time status notifications on your refunds.

🚧

Signing requests

All the requests in this guide must be signed on your 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:

📘

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 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 details of a single refund

To get the details of a refund, make a GET request to /payments/{payment_id}/refunds/{refund_id}. See the API reference for more about refund details.

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 possible statuses during its lifecycle:

Here's a diagram that illustrates a refund lifecycle: