Authorise a payment mandate

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:

1. Start the authorisation flow to receive next steps.
2. Submit information required for the next step – in this case provider selection.
3. Receive the return URI for end user mandate authorisation.
4. Redirect the end user to this URI.
5. Once the user has given their consent, they will be redirected to TrueLayer.
6. TrueLayer will finalise the mandate authorisation with the user's provider.
7. 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"
        }
      }'

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

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.