Refund a payment

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, which means they:

• Must be made to the original payment account.
• Cannot exceed the original payment amount.
• Can be issued over multiple payments.

With the Payments API v3, you can fully or partially refund payments made into your TrueLayer merchant accounts.

Before you start

To create a refund, you must have:

• An access_token, which you provide as a Bearer header.
• A Tl-Signature header to sign your request.
• An Idempotency-Key header so you can retry your request if necessary.
• A merchant account and at least one transaction from a customer to your merchant account.
  You also need the payment id from that payment, which must have a status of settled.

To enable 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 webhooks to get real-time status updates for your refunds.

Make a full or partial refund

To make a refund, make a POST request to the /v3/payments/{payment_id}/refunds endpoint that contains the following parameters:

POST /v3/payments/{PAYMENT_ID}/refunds HTTP/1.1
Content-Type: application/json
Idempotency-Key: {RANDOM_UUID}
Tl-Signature: {SIGNATURE}
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com

{
"amount_in_minor": 10000,
"reference": "Refund-12345"
}

If successful, you get an 202 HTTP response that contains the refund id.

{
	"id": "a843eb32-291a-4e63-948f-947ebc7f8ac8"
}

Note that a refund can take up to 24 hours to reach a terminal state.

Make multiple refunds for a single payment

To make multiple refunds for a single payment, make a refund request as detailed above. Then, specify a value for the amount_in_minor parameter that is less than the original payment. The amount you refund is subtracted from the original payment value. The total of all refunds for a single payment cannot exceed the value of the original payment.

If a refund fails ands its status changes to failed, it does not 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, providing the payment and refund IDs as path parameters:

GET /v3/payments/{PAYMENT_ID}/refunds/{REFUND_ID} HTTP/1.1
Tl-Signature: {SIGNATURE}
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com

The response you receive contains various information about the refund, such as the value, status, and timing of the refund:

{
	"id": "a843eb32-291a-4e63-948f-947ebc7f8ac8",
	"amount_in_minor": 1,
	"currency": "EUR",
	"status": "executed",
	"reference": "My reference",
	"created_at": "2024-03-01T17:37:04.284282854Z",
	"authorized_at": "2024-03-01T17:37:04.581048454Z",
	"executed_at": "2024-03-01T17:37:05.550Z"
}

Get the details of multiple refunds

If you have made multiple refunds for a single payment, you can get the details for all of them. To do so, make a GET request to the /v3/payments/{id}/refunds endpoint, providing the payment ID as a path parameter:

GET /v3/payments/{PAYMENT_ID}/refunds HTTP/1.1
Tl-Signature: {SIGNATURE}
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com

The response you receive contains an array with all refunds made for the given payment. This contains information about the refunds, such as value, status, and timing of the refunds:

{
	"items": [
		{
			"id": "b5ca499c-9e81-4ad3-b109-f9c9525bed7d",
			"amount_in_minor": 1,
			"currency": "EUR",
			"status": "executed",
			"reference": "My reference",
			"created_at": "2024-03-04T10:30:46.432653724Z",
			"authorized_at": "2024-03-04T10:30:46.677259390Z",
			"executed_at": "2024-03-04T10:30:47.547Z"
		},
		{
			"id": "eb4845b3-abb3-4b6e-8a5d-e430a70a4d30",
			"amount_in_minor": 10000,
			"currency": "EUR",
			"status": "executed",
			"reference": "My reference",
			"created_at": "2024-03-04T10:30:58.685250411Z",
			"authorized_at": "2024-03-04T10:30:58.903183614Z",
			"executed_at": "2024-03-04T10:30:59.860Z"
		},
		{
			"id": "2be80403-8458-4a8d-beb8-48baf02bb925",
			"amount_in_minor": 9999,
			"currency": "EUR",
			"status": "executed",
			"reference": "My reference",
			"created_at": "2024-03-04T10:31:11.002158930Z",
			"authorized_at": "2024-03-04T10:31:11.255087350Z",
			"executed_at": "2024-03-04T10:31:12.160Z"
		},
		{
			"id": "38e71f3b-a28d-4d64-8887-a0e111b38a70",
			"amount_in_minor": 10000,
			"currency": "EUR",
			"status": "executed",
			"reference": "My reference",
			"created_at": "2024-03-04T10:31:02.333858735Z",
			"authorized_at": "2024-03-04T10:31:02.623027761Z",
			"executed_at": "2024-03-04T10:31:03.523Z"
		}
	]
}