Make a payout to an account that paid in

In a closed-loop payout, a payment is made to a user id that has paid into your merchant account before.

For example, if you want to make a payment back to an iGaming customer who has won money, closed-loop payouts are useful.

Before you start

A closed-loop payout requires:

A Payments access token
A merchant account and its id
A payment_source_id and associated user_id
Enough money in your merchant account to make the payout
A client credentials access_token and valid Tl-Signature HTTP header
An idempotency key

Send a payout creation request

To create a closed-loop payout, make a POST request to the /v3/payouts endpoint, providing the parameters below.

Specifically, you must select payment_source as the beneficiary.type to make a closed-loop payout.

Parameter	Description
`merchant_account_id`	The unique ID of the merchant account to pay out from.
`amount_in_minor`	The amount to pay out in minor units. Minor units are the smallest units of a currency. For example: 1 GBP = 100 pence.
`currency`	The currency of the payment in ISO 4217. Note: you cannot make a payment in GBP to a EUR account, as specified in the `payment_method.beneficiary.account_identifier` field.
`beneficiary.type`	Must have a value of `payment_source`.
`beneficiary.reference`	A reference for the payout.
`beneficiary.payment_source_id`	The `id` of the account that made the original deposit. Find this in the [status body] for the original `settled` payment.
`beneficiary.user_id`	The `id` of the user that made the original deposit.

Below is an example request:

POST /v3/payouts HTTP/1.1
Content-Type: application/json
Idempotency-Key: random
Tl-Signature: {SIGNATURE}
Authorization: Bearer {TOKEN}
Host: api.truelayer-sandbox.com
{
    "merchant_account_id": "merchant_account_id",
    "amount_in_minor": 1000,
    "currency": "GBP",
    "beneficiary":
    {
        "type": "payment_source",
        "user_id": "user_id_here",
        "payment_source_id": "payment_source_id_here",
        "reference": "Payout0001"
    }
}

Below is an example of a successful response, including the id of the payout:

{
  "id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20"
}

Monitor the status of a payout

To keep track of the status of a closed-loop payout, you can:

Make a GET request to the /v3/payouts/{id} endpoint, which retrieves data about an individual payout, including its status.
Set up webhooks to track payout webhook notifications.

To make a GET Payout API call, store the id of the payout you want to see the details of. Add it to the end of the URL you are making the call to.

curl --request GET \
     --url https://api.truelayer.com/v3/payouts/id \
     --header 'accept: application/json; charset=UTF-8'

An example response for a successful closed-loop payout with a status of executed is below:

{
	"id": "5e4c6f80-7b70-47ac-8fd8-c6397ddc1fbf",
	"merchant_account_id": "af6b1163-14bb-4491-afc7-abeb67adc07f",
	"amount_in_minor": 1,
	"currency": "GBP",
	"beneficiary": {
		"type": "payment_source",
		"user_id": "57e9ae89-01fd-4779-8775-5b7de9a85a64",
		"payment_source_id": "c93bf50c-1c9c-40f1-80c9-cc55c0402fe8",
		"reference": "PayOutRef",
		"account_holder_name": "JOHN SANDBRIDGE",
		"account_identifiers": [
			{
				"type": "iban",
				"iban": "GB75CLRB04066800000871"
			}
		]
	},
	"scheme_id": "internal_transfer",
	"status": "executed",
	"created_at": "2023-02-08T11:50:39.477358288Z",
	"authorized_at": "2023-02-08T11:50:39.686232017Z",
	"executed_at": "2023-02-08T11:50:40.583Z"
}

🚧
Troubleshooting
If you get the error message "Authorization: The JWT was not able to be validated: InvalidAudience" when creating a payout, go to Insomnia > Generate access token > Form. For the payout to be authorised, you must set the scope to payments.