⚡ Quickstart: 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:

1. Authenticate the payout
2. Initiate the payout
3. Check that the payout is executed

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.
• Ensure that you have installed Insomnia and our collection, and that you are in the sandbox Payments v3 environment.

1. 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 1. Authentication > 1A. 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"
}

2. Initiate the payout

Make a call to the /payouts endpoint

In Insomnia, navigate to 4. Payouts > 4B. Create payout to an external account - SCAN.

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

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

3. Confirm that the payout 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, use webhooks to monitor payouts.

1. Go to Insomnia > 4. Payouts > 4D. Get payout.
2. 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 4B. Create payout to an external account - SCAN 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.