Make a payout to an account that paid in

Learn about closed-loop payouts and how to make one.

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:

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.

ParameterDescription
merchant_account_idThe unique ID of the merchant account to pay out from.
amount_in_minorThe amount to pay out in minor units. Minor units are the smallest units of a currency.

For example: 1 GBP = 100 pence.
currencyThe 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.typeMust have a value of payment_source.
beneficiary.referenceA reference for the payout.
beneficiary.payment_source_idThe id of the account that made the original deposit. Find this in the [status body] for the original settled payment.
beneficiary.user_idThe 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:

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.