Migration guide: Payments v2 to v3

Learn about the key differences between Payments v2 (Single Immediate Payments) and Payments v3, and how to create a payment token.


When using the v2 APIs, the user flow had to be custom-built. No UX/UI components were offered out of the box to build the flow.

With v3 this will still be possible. You can completely re-use your existing UX/UI flow using a Direct API integration, or use one of TrueLayer UI/UX and SDK components.

Create a payment token

Like with Payments v2, you need to generate a Bearer access_token. This is used to get info from your merchant account and to initiate API calls. Use your TrueLayer client_id and client_secret (found in your TrueLayer Console) to request an access_token from our auth server.

The endpoint is the same: https://auth.truelayer.com/connect/token. However, you must only use the payments scope for pay-ins (aka deposits), payouts (aka withdrawals) and refunds.

As with previous API versions, the access_token you generate lasts for 1 hour. Once it expires, you need to generate a new one.


Live endpointSandbox endpoint
curl -X POST \
    -d grant_type=client_credentials \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d scope=payments \
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTk4OUIwNTdDOUMzMzg0MDc4MDBBOEJBNkNCOUZFQjMzRTk1MTBSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IkZGbUpzRmZKd3poQWVBQ291bXk1X3JNLWxSQSJ9.eyJuYmYiOjE2NjAyNDU0NzEsImV4cCI6MTY2MDI0OTA3MSwiaXNzIjoiaHR0cHM6Ly9hdXRoLnRydWVsYXllci1zYW5kYm94LmNvbSIsImF1ZCI6InBheW1lbnRzX2FwaSIsImNsaWVudF9pZCI6InNhbmRib3gtZGFyeWx0ZXN0LTc2YjkwOCIsImp0aSI6IkE0MTNERDhFOENENTJGQUQ5MjcwRTU3QjJCN0RFNjhFIiwiaWF0IjoxNjYwMjQ1NDcxLCJzY29wZSI6WyJwYXltZW50cyJdfQ.hV5Nuqi-X9PqNDOyVftnWZzHhuBIetsjM1zeK-64ZSJ9aTqPdwhqVGiM4zTqLEx0ZfT34MbUfY98cFu00X3SbgS4fV7_Mu2jV_5ofrLdlb_KoIFo82ZG5Y4SNd19vFI5sEIkYIL3KtYnvnjUwP4UZvxgl0siTg1K0kRqws8SqfeOwStgaHsBfYcTUi_w3Z5DSZTspR_G_FixOHGjTPFY48GPACO-wyfH5JZn_uMpARRUam-sadukUpe8yjxFrg1zQ8mqXBhuuBbk8PoG4DCkk5tY-lTjFx92P1NuElMP1RzvIJ_-1qDhdtnNJROLm09_D-l4YX1VIaxL29Wv9kudqQ",
    "expires_in": 3600,
    "scope": "payments",
    "token_type": "Bearer"