Set up payouts to your account [Payouts API]

Set up and top up your account to pay with Payouts.

As soon as you get access to our Payouts API, a collection of accounts will be created for you: one for each currency and payment rail we support (for example, euro on SEPA, sterling on Faster Payments, and so on).

Top up your account

To create payouts you will need to firstly add funds to those accounts. To add funds, you need their IBANs. You can retrieve both IBANs and account balances querying our /balances endpoint. It will return an array of balances detailing the account details and balance currently held in the account.

curl -H "Authorization: Bearer ${access_token}" \
https://payouts.truelayer-sandbox.com/v1/balances

Fund accounts by sending a payment to the iban specified in the balance response over the same payment rail (for example, a bank transfer over Faster Payments for sterling accounts, a bank transfer over SEPA for euro accounts). Upon settling into the account, funds will become immediately available and can be used to initiate a payout with.

{
    "results": 
        [
            {
                "currency": "GBP",
                "iban": "GB33BUKB20201555555555",
                "status": "enabled",
                "current_balance_in_minor": 50000000,
                "available_balance_in_minor": 49998000
            },
            {
                "currency": "EUR",
                "iban": "FR1420041010050500013M02606",
                "status": "disabled",
                "current_balance_in_minor": 20000000,
                "available_balance_in_minor": 20000000
            }
        ]
}

Set up a payout

To send money to an end user, you will need to setup a payout on the API.
Payout creation is asynchronous. You'll receive webhooks for payout status changes, including failures. All POST requests to Payouts API have to be signed.

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 on success.

Receive webhooks

To receive webhooks you'll need to add a webhook_uri to the developer console in the Payouts API area.

Payout Authorised is the first event you will receive on your webhook_uri when creating a payout on an account holding sufficient funds. You will then receive a Payout Submitted and a Payout Settled event.

If you did not have enough funds or an AML check failed, you should expect a Payout Rejected event.

All other failure scenarios will instead trigger a Payout Failed event.

X-TL-Webhook-Timestamp: 2020-05-18T10:17:52Z

{
  "event_type": "payout_authorised",
  "event_id":  "33c9fc5b-69d7-4de0-83a9-8177f9af79d2",
  "event_body": 
    {
        "transaction_id": "cc328607-e02e-49e2-81c9-5bd044c8f7d7",
        "authorised_at": "2019-10-01T17:00:00.0000000Z",
    }
}

Query your transactions

You can use our reporting endpoint to query your transactions for each currency account, filtering by date, type of transaction, and 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"

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

Updated 9 months ago