Make a test payout (Open-loop)

An open-loop payout is a payment that you make to an account which has not paid you before. This guide explains how to make an open-loop payout in sandbox, using the Payments v3 Insomnia collection.

A complete open-loop payout can be divided into three stages:

In this guide, you will be making a simulated payout to a UK (GBP) account. A payout to an EU (EUR) account is very similar: see below for more.

Before you start

Create a Console account.
Make sure that you have configured Insomnia and that you are in the sandbox Payments v3 environment.

Authenticate the payout

Generate an access token

Just like a payment, a payout requires an access token. Note that each payout you create requires its own token.

To generate an access token, make a POST request to the /token endpoint, as you did for a pay-in. In the Payments v3 Insomnia collection, go to Authentication > Generate Access Token)

Use the payments scope (go to Form > scope in Insomnia to set scopes).

A request looks like this:

curl --request POST \
     --url https://auth.truelayer.com/connect/token \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "grant_type": "client_credentials",
  "client_id": "example",
  "client_secret": "example",
  "scope": "payments"
}
'

A successful response contains the access token itself, and looks like this:

{
	"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTk4OUIwNTdDOUMzMzg0MDc4MDBBOEJBNkNCOUZFQjMzRTk1MTBSUzI1NiIsIng1dCI6IkZGbUpzRmZKd3poQWVBQ291bXk1X3JNLWxSQSIsInR5cCI6ImF0K2p3dCJ9.eyJpc3MiOiJodHRwczovL2F1dGgudHJ1ZWxheWVyLXNhbmRib3guY29tIiwibmJmIjoxNjk3NDQ5NjU5LCJpYXQiOjE2OTc0NDk2NTksImV4cCI6MTY5NzQ1MzI1OSwiYXVkIjoicGF5bWVudHNfYXBpIiwic2NvcGUiOlsicGF5bWVudHMiXSwiY2xpZW50X2lkIjoic2FuZGJveC1oZWxsb2lhbXRlc3RpbmctNzQzZTBiIiwianRpIjoiM0UxQzEzODBENDA0Qzk2NEE3OTQ5MThEOUZCMjVEMjYifQ.fSWQSA0SoGI8d3m6PqMSPDwxR1iYDjMd6w06Mxhnr7wh4pgUAFKqlAZltYvDpAn4bDbc4ZYbzEWOaNWCVjqMbLQRtHI-4yH0NVqEVD9Xfn23UJ8q4htlPjOERDdUPJ47KxFiudIjM1_wIEDC_HN0P3B7QiClg8C3dVHLkcY9e8Jd9eX9omjw29WgjFLci6uAVC4ss2pz9ItsaWPeU2CiK0vLA1UKdS7XHb-3t2C0dvGmuIytuDK43Uag0RN3aH5NCXwG22a3uTBEf9-b_nM4ZMxKfefANhV85JvokyuIdHXGDXB8WN2SeJrkbzbouaj2wYKrjjBJpralYEEBeJceaw",
	"expires_in": 3600,
	"token_type": "Bearer",
	"scope": "payments"
}

Initiate the payout

Make a call to the `/payouts` endpoint

In Insomnia, navigate to Payouts > Create Payout to External Account.

Make a POST request to the /v3/payouts endpoint. To populate the request, Insomnia will automatically request these values after you click Send:

Value	Description	Where to find it
`merchant_account_id`	The UUID for the merchant account that you are paying out from.	Console > Payments > Merchant Account > Details
`beneficiary.account_holder_name`	The name of the beneficiary (or the name associated with the bank account that you are paying out to)	Your user’s account
`beneficiary.date_of_birth`	The birth date of the user you are paying out to.	Your user’s account
`sort_code`	The sort code of the account that you are paying out to.	Your user’s account
`account_number`	The account number of the account that you are paying out to.	Your user’s account

You can also change the value of the payout by changing the amount_in_minor value.

In full, the request looks like this:

{
  "currency": "GBP",
  "beneficiary": {
    "type": "external_account",
    "account_identifier": {
      "type": "sort_code_account_number",
      "sort_code": 560029,
      "account_number": 26207729
    },
    "address": {
      "address_line1": "40 Finsbury Square",
      "city": "London",
      "country_code": "GB",
      "zip": "EC2A 1PX",
      "state": "London"
    },
    "reference": "reference",
    "account_holder_name": "eg-name",
    "date_of_birth": "1990-01-31"
  }
}

For EU payouts, the process is very similar. Instead of supplying the sort code and account number of the beneficiary, you provide the IBAN.

{
  "currency": "EUR",
  "beneficiary": {
    "type": "external_account",
    "account_identifier": {
      "type": "iban",
      "iban": "GB32CLRB04066800012315"
    },
    "address": {
      "address_line1": "40 Finsbury Square",
      "city": "London",
      "country_code": "GB",
      "zip": "EC2A 1PX",
      "state": "London"
    },
    "reference": "reference",
    "account_holder_name": "eg-name",
    "date_of_birth": "1990-01-31"
  }
}

In a successful response, you receive the id of the payout itself, which looks like this:

{
  "id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20"
}

Check that the payout is executed

📘
In this walkthrough, you are only retrieving the status of a single payout, so use the GET Payout API call in Insomnia. For live payouts, we strongly recommend using webhooks to monitor payments.

Go to Insomnia > Payouts > Get Payout.
Insomnia will prompt you to enter the id of the payout that you want to see the status of. Input the payout id you received in the Create Payout to External Account response.

You can also check the payments view in Console to see the status of the payout. Note that the terminal status of a successful payout is executed, not settled.

Congratulations. You have now made a complete open-loop payout in sandbox.

Before you start

Authenticate the payout

Generate an access token

Initiate the payout

Make a call to the /payouts endpoint

Check that the payout is executed

📘

Make a call to the `/payouts` endpoint