Create a payout [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"&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:

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"
            }
        ]
}