Create a payout [Payouts API]
Learn how to create payouts and sign requests to the Payouts API.
POST requests to /v1/payouts
have to be signed. See the guide to request signing in the Payouts API for more details.
Field | Type | Description |
---|---|---|
transaction_id | uuid | The unique id of the payout you want to create. If two POST /payouts requests are submitted with the same transaction_id only the first one will be processed. transaction_id can therefore be used to ensure idempotency for payout creation. |
beneficiary_name | string | The name of the account holder you are sending funds to. This name must match the name associated with the account, otherwise the payout will fail validation. It must be at most 18 characters long. |
beneficiary_iban | string | The full IBAN of the account holder you are sending funds to. The IBAN must be accessible by the Faster Payments Scheme if transacting in GBP. |
beneficiary_reference | string | An 18 character reference that will appear on the account holder's bank statement. |
currency | ISO 4217 Currency Code String | The currency you are sending the payment in. Each currency is associated with its own account, therefore the currency denotes which account the funds will be sent from. |
amount_in_minor | integer | The amount to send to the account holder in the smallest denomination of the currency specified. For example, if transacting in GBP this will be in pennies. |
context_code | string | The code to describe why you are making the payout. |
curl -X POST \
-H "Authorization: Bearer ${access_token}" \
-H "X-TL-Signature: ${signature}" \
--data '{
"transaction_id": "<UUID>",
"beneficiary_name": "John Smith",
"beneficiary_iban": "GB33BUKB20201555555555",
"beneficiary_reference": "Withdrawal 204",
"currency": "GBP",
"amount_in_minor": 10000,
"context_code": "withdrawal"
}' \
https://payouts.truelayer-sandbox.com/v1/payouts
You'll get a HTTP 202 response.
Query a single payout
curl -H "Authorization: Bearer ${access_token}" \
https://payouts.truelayer-sandbox.com/v1/payouts/{transaction_id}
A set of core fields is available on all payouts, regardless of their statuses:
Field | Type | Description |
---|---|---|
transaction_id | uuid | The unique ID of the payout. |
beneficiary_name | string | The name of the account holder you are sending funds to. |
beneficiary_iban | string | The full IBAN of the account holder you are sending funds to. |
beneficiary_reference | string | An 18 character reference that will appear on the account holder's bank statement. |
currency | ISO 4217 Currency Code String | The currency you are sending the payment in. |
amount_in_minor | integer | The amount to send to the account holder in the smallest denomination of the currency specified. For example, if transacting in GBP this will be in pennies. |
context_code | string | The code to describe why you are making the payout. A full list of these can be found below. |
status | string | The current status of the payout. Learn about the different possible states of the state machine. |
When the payout status is authorised
, you will also get:
Field | Type | Description |
---|---|---|
authorised_at | Timestamp | The date and time that the payout was authorised at. |
When the payout status is submitted
, you will also get:
Field | Type | Description |
---|---|---|
authorised_at | Timestamp | The date and time that the payout was authorised at. |
submitted_at | Timestamp | The date and time that the payout was submitted to the scheme. |
When the payout status is settled
, you will also get:
Field | Type | Description |
---|---|---|
authorised_at | Timestamp | The date and time that the payout was authorised at. |
submitted_at | Timestamp | The date and time that the payout was submitted to the scheme. |
settled_at | Timestamp | The date and time that the payout was settled into the beneficiary account. |
When the payout status is failed
, you will also get:
Field | Type | Description |
---|---|---|
authorised_at | Timestamp | The date and time that the payout was authorised at. |
submitted_at | Timestamp (Optional) | The date and time that the payout was submitted to the scheme. A payout status can transition to failed before or after scheme submission. |
failed_at | Timestamp | The date and time that the payout status changed to failed . |
When the payout status is rejected
, you will also get:
Field | Type | Description |
---|---|---|
rejected_at | Timestamp | The date and time that the payout was rejected by TrueLayer. |
{
"result": {
"transaction_id": "cc328607-e02e-49e2-81c9-5bd044c8f7d7",
"authorised_at": "2019-10-01T17:00:00.0000000Z",
"submitted_at": "2019-10-01T17:00:00.0000000Z",
"settled_at": "2019-10-01T17:00:00.0000000Z",
"beneficiary_name": "John Smith",
"beneficiary_iban": "GB33BUKB20201555555555",
"beneficiary_reference": "Withdrawal 204",
"amount_in_minor": 10000,
"currency": "GBP",
"context_code": "withdrawal",
"status": "settled"
}
}
Query multiple transactions
The type
field can be used to distinguish between top-ups and payouts.
Query parameters:
Field | Mandatory | Type | Description |
---|---|---|---|
from | Mandatory | Timestamp | Timestamp as a string for the start of the range you are querying |
to | Mandatory | Timestamp | Timestramp as a string for the end of the range you are querying |
type | Optional | String | Filter transactions by type, the available types are topup and payout . If omitted, both payouts and topups will be returned. |
currency | Optional | ISO 4217 Currency Code String | Filter transactions by currency. |
curl -H "Authorization: Bearer ${access_token}" \
https://payouts.truelayer-sandbox.com/v1/transactions?from="2019-10-01T17:00:00.0000000Z"&to="2019-10-02T17:00:00.0000000Z"&type="Payout"¤cy="GBP"
You'll get a response like the following:
{
"results":
[
{
"transaction_id": "cc328607-e02e-49e2-81c9-5bd044c8f7d7",
"type": "payout",
"authorised_at": "2019-10-01T17:00:00.0000000Z",
"submitted_at": "2019-10-01T17:00:00.0000000Z",
"settled_at": "2019-10-01T17:00:00.0000000Z",
"beneficiary_name": "John Smith",
"beneficiary_iban": "GB33BUKB20201555555555",
"beneficiary_reference": "Withdrawal 204",
"amount_in_minor": 10000,
"currency": "GBP",
"context_code": "withdrawal",
"status": "settled"
},
{
"transaction_id": "gg328607-e02e-49e2-81c9-5bd044c8f7d8",
"type": "payout",
"authorised_at": "2019-10-01T15:00:00.0000000Z",
"submitted_at": "2019-10-01T15:00:00.0000000Z",
"settled_at": "2019-10-01T15:00:00.0000000Z",
"beneficiary_name": "Jane Doe",
"beneficiary_iban": "GB43BUKB20201555555555",
"beneficiary_reference": "Withdrawal 205",
"amount_in_minor": 20000,
"currency": "GBP",
"context_code": "withdrawal",
"status": "settled"
}
]
}
Query account balances
curl -H "Authorization: Bearer ${access_token}" \
https://payouts.truelayer-sandbox.com/v1/balances
You'll get a response with the following:
Field | Type | Description |
---|---|---|
currency | ISO 4217 Currency Code String | The currency of the account. Accounts can only hold 1 currency each. |
iban | string | The IBAN of the account that can be used to send funds to the account. |
status | string | Denotes whether the account is active or not, the field can be enabled or disabled . |
current_balance_in_minor | integer | The current balance of the account in the smallest denomination including transactions that are pending or in transit. |
available_balance_in_minor | integer | The balance available to spend in the smallest denomination. |
account_owner | string | The name of the account owner. |
{
"results":
[
{
"currency": "GBP",
"iban": "GB33BUKB20201555555555",
"status": "enabled",
"current_balance_in_minor": 50000000,
"available_balance_in_minor": 49998000,
"account_owner": "Owner Name"
},
{
"currency": "EUR",
"iban": "FR1420041010050500013M02606",
"status": "disabled",
"current_balance_in_minor": 20000000,
"available_balance_in_minor": 20000000,
"account_owner": "Owner Name"
}
]
}
Updated 7 months ago