Make a test payout (Closed-loop)

🚧

This guide assumes that you have read the Make a test payment quickstart guide.

To make a closed-loop payout, you need to make a payment into your merchant account first.

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

After the initial payment has settled, a closed-loop payout can be divided into three stages from end to end:

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

Before you start

• Create a Console account and make a payment into your sandbox merchant account.
• Make sure that Insomnia is configured and that you are in the sandbox environment.
• When the payment reaches the settled status, store the payment_source.id value. You can find this in the payment_settled webhook notification, or in Console’s payments view.
• The user_idalso returned in the Payment Settled webhook notification, which corresponds to the user_id value being passed within the Pay-In creation call.

{
  "type": "payment_settled",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "payment_method": {
    "type": "bank_transfer",
    "provider_id": "mock-payments-de-redirect",
    "scheme_id": "sepa_credit_transfer"
  },
  "settled_at": "2021-12-25T15:00:00.000Z",
  "payment_source": {
    "account_identifiers": [
      {
        "type": "iban",
        "iban": "DE79370400440532013000"
      }
    ],
    "id": "1f111d3c-9427-43be-1111-1111219d111c",
    "account_holder_name": "HOLDER NAME"
  },
  "user_id": "ec01ece1-1dbe-48f1-82b2-bce8cfa44d08"
}

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 Payment Source.

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

In full, the request looks like this:

curl --request POST \
     --url https://api.truelayer-sandbox.com/v3/payouts \
     --header 'accept: application/json; charset=UTF-8' \
     --header 'content-type: application/json; charset=UTF-8' \
     --data '
{
  "currency": "GBP",
  "beneficiary": {
    "type": "payment_source",
    "account_identifier": {
      "type": "sort_code_account_number"
    },
    "reference": "reference",
    "payment_source_id": "example-payment-source",
    "user_id": "example-user-id"
  },
  "merchant_account_id": "AB8FA060-3F1B-4AE8-9692-4AA3131020D0",
  "amount_in_minor": 1
}
'

A successful response contains an id for the payout itself, and look 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.

1. Go to Insomnia > Payouts > 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 Create Payout to Payment Source response.

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

Congratulations. You have now successfully completed a test closed-loop payout.