Authorise a payment mandate

After you create a mandate, you receive a response that contains a resource_token, a user id and a mandate id.

{
  "id": "{The mandate ID}",
  "user": {
    "id": "{The user ID}"
  },
  "resource_token": "The resource token for teh mandate"
}

You need both values to start the authorisation journey for your user.

Like with a payment, your user must authorise any mandates you create before any money can be sent. They do this by authorising the mandate with their their banking provider. To do this, use a browser redirect to send the user to their bank.

There are two options for authorisation: a prebuilt TrueLayer UI, or a direct API integration.

Authorise a mandate with a TrueLayer UI

The first option is to use a TrueLayer web or mobile UI for authorisation. These are simpler to integrate than building your own authorisation UI and customisable to match your brand.

TrueLayer authorisation UIs use the resource_token you get when you generate a mandate and display screens for your user to authorise the mandate. They include extra information so your user can understand what a mandate is, and are compliant with any applicable regulation.

Authorise a mandate with a direct API integration

The second option is to build your own UI with a direct API integration. In this case, you use the /v3/mandates/{id}/authorization-flow endpoint. This returns a sequence of actions you need to complete in order to authorise a mandate.]

Learn more about actions and how to complete them in our guide to building your own authorisation UI.

This an example of the most common authorisation flow:

Start the authorisation flow to the receive next steps as actions.
Submit any information required for each next step (for example, provider selection).
Receive the redirect URL.
Redirect the end user to this URL.
The user gives their consent for the mandate to their bank, and is redirected to TrueLayer.
TrueLayer confirms the mandate authorisation with the bank.
TrueLayer redirects the end user back to you.

Example direct API mandate authorisation flow

This is an example of a direct API integration flow for mandate authorisation when the mandate uses user_selected provider selection.

1. Mandate creation request

In order to start the mandate authorisation flow, you first need to create a mandate. In this example, you should specify user_selected for the mandate.provider_selection.type parameter.

You receive a mandate id and resource_token in the response. You use the resource_token as a bearer header to authenticate the rest of your authorisation-related requests, and the id as a path parameter.

2. Start mandate authorisation flow request

To start the authorisation flow, make a POST request to the /v3/mandates/{id}/authorization-flow endpoint. You must also include a redirect_uri in the body of your request. You must register the redirect URI you use in Console.

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 mandate authorisation flow response

The response you receive after you start the mandate authorisation flow depends on the format of the mandate you created. Specifically, mandates with user selected provider selection return a value of provider_selection for the actions.next.type object. It also contains a list of providers, which is based on the filters you specified at mandate creation. This contains information such as the provider id, assets such as logos and display names, and the availability of the provider:

{
  "status": "authorizing",
  "authorization_flow": {
    "actions": {
      "next": {
        "type": "provider_selection",
        "providers": [
          {
            "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",
            "schemes": [
              {
                "id": "faster_payments_service"
              }
            ],
            "availability": {
              "recommended_status": "healthy",
              "updated_at": "2024-04-09T15:21:46.856Z"
            },
            "country_code": "AT",
            "search_aliases": [
              "string"
            ]
          }
        ]
      }
    }
  }
}

Based on the list of providers in the response (this example only contains one), you need to render a provider selection UI for your user.

Provider selection request

The next step of authorisation is to send the provider id of the provider the user selects in a request to the /v3/mandates/{id}/authorization-flow/actions/provider-selection endpoint:

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

After your user selects their provider, you receive an authorisation URL that will take the user to their bank:

{
  "type" : "redirect",
  "url" : "https://awesomebank.co.uk/auth?state=somestate"
}

On that page, they log in and consent to authorise the mandate. In some cases, the response may ask again for provider selection or for the user to wait for the outcome of authorisation (where the call has already been initiated).

Generally, consent will either be authorised or rejected within a few moments.

We recommend that you monitor the process and status of the mandate using webhook notifications and a final redirect back to your site/app.