Authorisation flow actions

Depending upon how you configure your payment creation request, sometimes the Payments API v3 returns actions in the payment response. There are four different actions you must complete to authorise a payment (if they apply). These actions are:

In order to directly integrate authorisation with the Payments API, you need to develop logic and UIs that can complete these actions.

📘

Simpler integration with TrueLayer UIs

User authorisation is separate to request signing and payment or mandate creation, and there is no TrueLayer library for it.

However, authorisation and the related actions are handled automatically if you integrate with the hosted payment page, embedded payment page or a TrueLayer mobile UI.

How to complete actions

You complete the actions required for authorisation by returning certain data via a POST request. For example, you need to provide a provider_id for the provider_selection action.

The actions you must complete to authorise a payment change based on several factors such as region and provider selection method. For example, some European banks such as those in Germany require that the user submit additional information. In this case, you need to complete the form action. Learn more about the different flows you can integrate.

The actions.next.type object you receive in each response after you start the authorisation flow indicates what action is required next. The object also contains the information you need to complete the action.

You can see an example of this in the response from the /start-payment-authorisation-flow endpoint below:

{
  "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",
            "country_code": "AT",
            "search_aliases": [
              "string"
            ]
          }
        ]
      }
    }
  },
  "status": "authorizing"
}

This response says that the next required action is provider_selection and returns a list of possible providers (in this case, a single bank with the ID ob-bank-name).

The redirect action

The redirect action does not require that you submit information via POST request. It's typically the last step of authorisation.

This is the format of the redirect object:

{
    "type": "redirect",
    "uri": "http://some-uri"
}

How to complete the redirect action

The redirect action means that you need to redirect your user to the uri returned in the object, which must be registered in Console. You should redirect your user here regardless of whether they are on desktop or mobile.

When you redirect a user on a mobile device, this often opens the provider's mobile application where the user can authorize the payment. After authorisation, depending on the type of payment, the user is guided back to the merchant's domain.

The provider_selection action

This is needed when the next action has a type of provider_selection. When the actions.next.type object states this action is required, it also contains a list of providers.

The list of providers is based on what you provide for the provider_selection.filter object when you create the payment.

Generally, this is the format of the provider_selection object:

{
        "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",
            "country_code": "GB"
          },
          {
            "id": "ob-bank-name-2",
            "display_name": "Bank Name 2",
            "icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icon/generic-2.svg",
            "logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/generic-2.svg",
            "bg_color": "#000000",
            "country_code": "GB"
          }
        ]
      }

How to complete the provider_selection action

In order to complete the provider_selection action, you must:

1. Render the list of providers returned in the providers object in a UI that the user can use to select a provider.
2. Submit the id of the provider the user selected as a POST request to the .../authorization-flow/actions/provider-selection endpoint.

To help you render the list of providers, for each provider the providers object includes a:

• Display name.
• Link to an SVG icon.
• Link to an SVG logo.
  This usually contains the icon and the provider's name as text.
• Suggested background colour for the provider as a hex colour code.

The form action

Some providers need to collect additional data as part of authorisation, especially in Germany, where the redirect action is not used. When a provider requires additional data as part of authorisation, it returns form as the next action.

The form action contains information about the format of the additional information the user must provide and any constraints that apply (such as unpermitted special characters). The three types of form action are:

• text: Requires the user to complete one or more text fields.
• select: Requires the user to select a single value from several.
• text_with_image: Requires the user to complete a text field that is accompanied by an image.
  This image is typically a QR code, which enables the user to retrieve the value to complete the text field from their provider.

Example of a form action

Usually, a form action for a bank that requires branch information follows the submission of a provider_selection action. Below is an example of the response you could receive when you complete theprovider_selection action.

{
    "status": "authorizing",
    "authorization_flow": {
        "actions": {
            "next": {
                "type": "form",
                "inputs": [
                    {
                        "type": "select",
                        "id": "branch-name",
                        "mandatory": true,
                        "display_text": {
                            "key": "branch-name.display-text",
                            "default": "Branch Name"
                        },
                        "options": [
                            {
                                "id": "branch-a",
                                "display_text": {
                                    "key": "branch-name.branch-a",
                                    "default": "Branch A"
                                }
                            },
                            {
                                "id": "branch-b",
                                "display_text": {
                                    "key": "branch-name.branch-b",
                                    "default": "Branch B"
                                }
                            }
                        ]
                    }
                ]
            }
        }
    }
}

In this example, the form has a type of select. This means you need to create a UI that enables the user to select between the valid options in the response. In this case, branch-a and branch-b.

How to complete the form action

Completing the form action requires the following steps:

1. Render the form as a UI for your user based on the type of the input.
   The different types of input are explained in the section below.
2. Collect the input from the user.
3. Submit the input to the .../authorization-flow/actions/form endpoint as a POST request.

Examples of different types of form action

This section contains some examples of how your UI could look to complete the three different types of form action.

The text input type

Text input type represents a simple written input from the user. On web it can be rendered as an html element of type input.

The select input type

Select input type represents a dropdown multiple choice box. On html it can be rendered as an input type also defined as select. This can be required by German and French providers.

The text_with_image input type

Text with image will come with an image to render and also a text input for the user to enter the expected value based on the image they observe. Mainly required by German providers.

Request body during submission needs to be a map with ID of the input as the key and the user input as value.

{
    "branch-name": "branch-a"
}

Key should be the ID of the input, and the value should be the ID of the value if it was for a multiple choice input type.

The wait action

The wait action only applies to a small proportion of payment authorisation flows. Specifically, it is returned in response to a form action when a decoupled strong customer authentication step is required.

As such, it only applies to integrators who are PISP-licensed and need to accommodate authorisation via a separate banking provider as part of an embedded flow.

This is an example of a response that contains the wait action.

{
    "status": "authorizing",
    "authorization_flow": {
        "actions": {
            "next": {
                "type": "wait"
            }
        }
    }
}

How to complete the wait action

To complete the wait action, you should develop a UI that indicates an authorisation step is being completed in a separate app or website.

The object that contains the wait action also contains a display_message object, which you can display while the user completes authentication with their provider. While the user completes this, you can poll the Payments API to check progress.

When the payment status changes to either executed or failed, display a screen that informs the user of the payment's success or failure.

To ensure a good user experience while the user completes provider authentication in another app or web page, your UI should display a loader while you poll to check whether authentication has been completed.