⚡ Quickstart: 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 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. Confirm that the payout 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.
• Store the payment_source.id value you receive when the payment reaches the settled status. You can find this in the payment_settled webhook notification, or in Console’s payments view.
• Store the user_id you receive in thee payment_settled webhook notification.
  This also corresponds to the user_id you passed in the pay-In creation call (if you did pass one).

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

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 the 1. Authentication > 1A. Generate access token request.

Use the payments scope for your access token. You can set scopes in in the scope field within the Form tab if you have the 1A. Generate access token request open.

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 the 4. Payouts > 4A. Create payout to payment source request.

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

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 payments.

1. In Insomnia, run the 4. Payouts > 4D. Get payout request.
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 4A. Create payout to a 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.