Authorise a payment mandate

After calling mandate creation, you will 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 we must use a browser redirect. Some flows may differ slightly but generally the flow will be:

1. Start authorisation flow to receive next steps
2. Submit information required for next step - in this case provider selection.
3. Receive redirect URL for end user mandate authorisation
4. Redirect the end user to this URL
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-sandbox.com/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 will contain 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-sandbox.com/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"
      }'

You will notice the request shares many similarities to the previous one. In this case ...

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 should that be the 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.