Generate a payments access token
Create an access token to use to authenticate payments requests.
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 testingIf you're testing scopes using our Payments API Insomnia collection, you add scopes in TrueLayer Payments V3 > Authentication > Generate Access Token > Form.
Legacy scopesThere are also scopes for our legacy products,
payouts
andpaydirect
. 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.
Updated 28 days ago