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:
- A Payments access token
- A merchant account and its
id
- A
payment_source_id
and associateduser_id
- Enough money in your merchant account to make the payout
- A client credentials
access_token
and validTl-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.
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 /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
/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 thescope
topayments
.
Updated 14 days ago