Generate a payments access token

Before you can create any payments, you must generate a payments access token to authenticate your requests.

Each access token grants you access to the Payments API for 60 minutes, during which you can create as many payments as you like.

How to generate a payments access token

To generate an access_token, make a POST request to the /connect/token/ endpoint and include these body parameters in your request:

Body parameter name	Description
`grant_type`	This parameter specifies the type of access token you want to generate. For a payments access token, use a value of `client_credentials`. For an initial Data API access token, you use `authorization_code`, and to refresh it, `refresh_token`.
`client_id`	The `client_id` associated with the merchant account the payment relates to. You can find this in App Settings in Console.
`client_secret`	The `client_secret` linked to your `client_id`, which was generated when you created your app on Console.
`scope`	Each scope you include in your access token request represents different payment products you want to enable for payments created using the scope. For any requests to the Payments API, you must include a minimum of the `payments` scope. You can include additional scopes also to enable features such as mandates or Signup+. All scopes for an access token must be provided in a space-separated list.

The Client Credentials Grant Request section in the API reference for the /connect/token endpoint contains information about what to include in your request and examples.

You can reuse an access token until it expires, which usually takes an hour (see the expires_in field in the response). We recommend that you cache the access token for as long as it is valid, minus the amount of time it takes to renew the token. Allow for time to retry the request in case of errors as well.

Example request and response

This is an example of a request to generate an access token:

curl -X POST \
    -d grant_type=client_credentials \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d scope=payments \
    https://auth.truelayer.com/connect/token

If your request is successful, you receive a response with the following format (the access_token is just an example):

{
	"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTk4OUIwNTdDOUMzMzg0MDc4MDBBOEJBNkNCOUZFQjMzRTk1MTBSUzI1NiIsIng1dCI6IkZGbUpzRmZKd3poQWVBQ291bXk1X3JNLWxSQSIsInR5cCI6ImF0K2p3dCJ9.eyJpc3MiOiJodHRwczovL2F1dGgudHJ1ZWxheWVyLXNhbmRib3guY29tIiwibmJmIjoxNzA4NTMyNDQ2LCJpYXQiOjE3MDg1MzI0NDYsImV4cCI6MTcwODUzNjA0NiwiYXVkIjoicGF5bWVudHNfYXBpIiwic2NvcGUiOlsicGF5bWVudHMiXSwiY2xpZW50X2lkIjoic2FuZGJveC10b210ZXN0LWE0ZDQzMiIsImp0aSI6IkQxODk5OTk3NDI2RTRCRDA3QTMwRTRFREQ5MTk2QkI0In0.T_DyO7kuxGP22iFjbjosi3nTa3ZX_Q2XgnETIMbVuTD3ihNWyvMZE_hcWcIloKLKTqo5ggoX6u3nI730xK83QCo0PaapYnN7ynogLlcyi6YBV7svAtfuhVpigtWSehw10G9Gnun_CTccUo0JR9S1PXJ8uZLsV3vVqMMw5FbNCOOUezkOYb1DarqrGtZHRL4OkEwRCt5rQvoocWGPFCTuTTHp4jyCSXE7of2AhsBRwXy7svikxQVYtw-4aQq3XqhQnCwega6A1ZKqwdHHw1GLm_LMZOtkTy1PM9CX-nWRfl91vqoBz2EFsJqPoGrosrUWd3T8vTHt6A4-TlUFT21bHA",
	"expires_in": 3600,
	"token_type": "Bearer",
	"scope": "payments"
}

Scopes in payment access tokens

The values you include in the scope parameter in your access token request determine what Payments API features you can use.

You must include the payments scope to make any requests to the Payments API. You can include extra scopes such as recurring_payments:sweeping or signupplus to enable extra functionality. These scopes should be provided as a space-separated list within the scope parameter.

This table contains all scopes currently available for the Payments API:

`scope`	Description
`payments`	Required to make single payments or payouts.
`recurring_payments:sweeping`	Required to create sweeping VRP mandates. Include the `payments` scope when you create a VRP mandate, to ensure payments can be made on the mandate later.
`recurring_payments:commercial`	Required to create commercial VRP mandates. Include the `payments` scope when you create a VRP mandate, to ensure payments can be made on the mandate later.
`signupplus`	Required to collect user details through a payment using the Signup+ API.

📘
Insomnia testing
If you're testing scopes using our Payments API Insomnia collection, you add scopes in TrueLayer Payments V3 > Authentication > Generate Access Token > Form.
Legacy scopes
There are also scopes for our legacy products, payouts and paydirect. See our legacy API documentation for more information.

How to use a payments access token

The access_token you receive is a bearer token. This means you need to include it as a bearer header in any related payments requests.

You also need to sign requests to most payments endpoints.