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.

FieldTypeDescription
transaction_iduuidThe 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_namestringThe 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_ibanstringThe 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_referencestringAn 18 character reference that will appear on the account holder's bank statement.
currencyISO 4217 Currency Code StringThe 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_minorintegerThe 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_codestringThe 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:

FieldTypeDescription
transaction_iduuidThe unique ID of the payout.
beneficiary_namestringThe name of the account holder you are sending funds to.
beneficiary_ibanstringThe full IBAN of the account holder you are sending funds to.
beneficiary_referencestringAn 18 character reference that will appear on the account holder's bank statement.
currencyISO 4217 Currency Code StringThe currency you are sending the payment in.
amount_in_minorintegerThe 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_codestringThe code to describe why you are making the payout. A full list of these can be found below.
statusstringThe 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:

FieldTypeDescription
authorised_atTimestampThe date and time that the payout was authorised at.

When the payout status is submitted, you will also get:

FieldTypeDescription
authorised_atTimestampThe date and time that the payout was authorised at.
submitted_atTimestampThe date and time that the payout was submitted to the scheme.

When the payout status is settled, you will also get:

FieldTypeDescription
authorised_atTimestampThe date and time that the payout was authorised at.
submitted_atTimestampThe date and time that the payout was submitted to the scheme.
settled_atTimestampThe date and time that the payout was settled into the beneficiary account.

When the payout status is failed, you will also get:

FieldTypeDescription
authorised_atTimestampThe date and time that the payout was authorised at.
submitted_atTimestamp (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_atTimestampThe date and time that the payout status changed to failed.

When the payout status is rejected, you will also get:

FieldTypeDescription
rejected_atTimestampThe 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:

FieldMandatoryTypeDescription
fromMandatoryTimestampTimestamp as a string for the start of the range you are querying
toMandatoryTimestampTimestramp as a string for the end of the range you are querying
typeOptionalStringFilter transactions by type, the available types are topup and payout. If omitted, both payouts and topups will be returned.
currencyOptionalISO 4217 Currency Code StringFilter 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"&currency="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:

FieldTypeDescription
currencyISO 4217 Currency Code StringThe currency of the account. Accounts can only hold 1 currency each.
ibanstringThe IBAN of the account that can be used to send funds to the account.
statusstringDenotes whether the account is active or not, the field can be enabled or disabled.
current_balance_in_minorintegerThe current balance of the account in the smallest denomination including transactions that are pending or in transit.
available_balance_in_minorintegerThe balance available to spend in the smallest denomination.
account_ownerstringThe 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"
            }
        ]
}