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 /payouts endpoint, providing the parameters below.

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

Below is an example request:

POST /payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: random
Tl-Signature: {SIGNATURE}
Authorization: Bearer {TOKEN}
Host: api.truelayer-sandbox.com
{
  "amount_in_minor": 1000,
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "beneficiary": {
      "type": "external_account",
      "account_holder_name": "",
      "reference": "reference",
      "account_identifier": {
        "type": "sort_code_account_number",
        "sort_code": "xx-xx-xx",
        "account_number": "xxxxxxx"
      }
    },
    "provider_selection": {
      "type": "user_selected"
    }
  },
  "user": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

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 /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/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.