Authorise a payment mandate
Configure the authorisation flow so your users can authorise payment mandates.
After you create a mandate, you have a resource_token
and an id
for the mandate.
{
...
"id": "mandate_identifier",
"resource_token": "a-secret-token"
}
Both values are required to start the end user authorisation journey.
End-user authorisation
To complete mandate creation, your end user must authorise account linking with their banking provider. To do this, you must use a browser redirect. Some flows may differ slightly but generally the flow will be:
- Start the authorisation flow to receive next steps.
- Submit information required for the next step – in this case provider selection.
- Receive the return URI for end user mandate authorisation.
- Redirect the end user to this URI.
- Once the user has given their consent, they will be redirected to TrueLayer.
- TrueLayer will finalise the mandate authorisation with the user's provider.
- TrueLayer will then redirect the end user back to you.
Start the authorisation flow
Start auth request
curl --request POST \
--url https://api.truelayer.com/v3/mandates/$id/authorization-flow \
--header 'Accept: application/json; charset=UTF-8' \
--header 'Authorization: Bearer $resource_token' \
--header 'Content-Type: application/json; charset=UTF-8' \
--header 'Idempotency-Key: $idempotency_key' \
--data '{
"provider_selection": {},
"redirect": {
"return_uri": "$return_uri"
}
}'
value | description |
---|---|
$id | The mandate id returned from create mandate. |
$resource_token | The authentication token returned from create mandate. |
$idempotency_key | unique value to distinguish this specific request and avoid duplication/replay issues. |
$return_uri | The URL to send your user to after mandate authorisation is complete. |
Start auth response
The response contains the list of providers that can be used to support the authorisation flow.
{
"authorization_flow": {
"actions": {
"next": {
"type": "provider_selection",
"providers": [
{
"provider_id": "ob-bank-name",
"display_name": "Bank Name",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icon/generic.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/generic.svg",
"bg_color": "#000000",
"country_code": "GB"
}
]
}
}
},
"status": "authorizing"
}
Provider selection request
Continue the auth flow by submitting the provider to be used.
curl --request POST \
--url https://api.truelayer.com/v3/mandates/$id/authorization-flow/actions/provider-selection\
--header 'Accept: application/json; charset=UTF-8' \
--header 'Authorization: Bearer $resource_token' \
--header 'Content-Type: application/json; charset=UTF-8' \
--header 'Idempotency-Key: $idempotency_key' \
--data '{
"provider_id" : "$provider_id"
}'
value | description |
---|---|
$provider_id | The provider_id as found in the start auth response. |
Provider selection response
This documentation shows the expected response for the UK providers that offer VRP. However, if a provider does require more information then the response will not be as documented here. You should be able to refer to the API reference to determine what to do in this case.
With a provider selected, you should receive an authorisation URL that will take the user to their bank to
authorise the recurring payment mandate. In some cases though the response may ask again for provider selection or to await the outcome of authorisation (in the case where the call has already been initiated)
{
"type" : "redirect",
"url" : "https://awesomebank.co.uk/auth?state=somestate"
}
Generally consent will either be authorised or rejected within a few moments. Depending on your integration you may find that it's suitable to rely on webhook notifications and a final redirect back to your site/app. If necessary you may also poll for status of the authorisation. Read more about mandate statuses here.
Updated 9 days ago