Create a 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 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:

FieldDescription
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 will appear on your bank statement.

This must 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 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:

StatusDefinition
pendingThe refund has been created with TrueLayer's API, but it has not yet been authorized and sent to the payment scheme for execution.
authorizedThe refund has been created via TrueLayer's API and sent to the payment scheme for execution.
executedThe refund was executed. The refund amount has been deducted from your merchant account.
failedThe refund failed. The refund amount has not been deducted from your merchant account.

Here's a diagram that illustrates a refund lifecycle:

16321632

Refund status transitions