Payment 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 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:

🚧

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 transition diagram