Authorisation and actions

In a payment flow, the payment made is authorised before it can be considered to have been completed. You'll have to consider payment authorisation irrespective of your integration type (direct API integration, HPP or mobile SDK). If you're using HPP and/or mobile SDKs, the authorisation action is handled automatically through the integration.

When a payment is created, it has the status authorization_required. To continue with the payment flow, make a POST request to payments/{id}/authorization-flow. You'll get the next steps for the authorisation in the response to this request.

Actions

Payments API provides a chain of actions for the client to handle in order to carry the payment through its authorisation lifecycle. Once the authorisation flow is started, Payments API will start providing actions to be handled some of which will need to be submitted through their respective POST endpoints. Upon submission, the response will include the next action to be handled.

17431743

Diagram showing the API providing actions to be handled when the client makes POST requests, and the responses including the next actions.

Different regions in the world requires different actions to be handled. Information regarding actions is presented in a field called authorization_flow in various different response objects. You can observe this data through:

  • GET /payments/{id}
  • Response to submission of an action

Object relating to action will look like following:

{
  "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": "GB"
          }
        ]
      }
    },
    "configuration": {
      "provider_selection": {},
      "redirect": {
        "return_uri": "string"
      }
    }
  }
}

actions.next displays the next action that needs to be handled, and submitted if the action is submittable. In this example you can see that the next action is provider_selection which is inferred via the type field and a submission needs to be made to /payments/{id}/authorization-flow/actions/provider-selection. The specification of this endpoint can also be found in our API reference.

Each action will have additional information within the object related to the context of what the action requires to be done. For example provider_selection action comes with a field named providers which is a list describing all the available providers to be selected by the user. Other actions such as form will have inputs that need to be collected and sent.

Provider selection action

Represented by type provider_selection, this action will come with a list of providers which are available for the user to select based on the configuration that was provided when the payment was created. A typical provider_selection object will look like following

{
        "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"
          }
        ]
      }

Handling provider selection means

  • Rendering the list of providers for taking a selection from the user
  • Submitting the selected provider's ID to /payments/{id}/authorization-flow/actions/provider-selection with a POST request. The specs for the endpoint can be found here

To help the rendering process, the action provides links to an icon, logo and suggested background color for the provider.

Redirect action

Redirect action is the only unsubmittable action our API provides. Redirect action object will be as following:

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

Handling redirect means

  • Redirect the user to the value of uri field on web and mobile

On mobile redirection will more often than not trigger opening of the provider's mobile application where the user can authorize the payment. After the authorisation depending on the nature of the payment, the user will follow a certain path to come back to the client's domain.

Form action

Some providers require some data to be collected before the payment can be initiated (mainly in European region), and some providers require data to be collected during authorisation, especially in Germany, where redirect action is not used. Payments API achieves this via an action called form. API will provide a form action object as the next action, with a set of input to be collected, whenever user input is necessary.

A typical form action for a bank that requires branch information, will follow submission of a provider-selection action. Response of the submission will look as the following

{
    "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"
                                }
                            }
                        ]
                    }
                ]
            }
        }
    }
}

Handling the form action will include following steps

  • Render the form based on the type of the input
  • Collect the input from the user
  • Submit the input to payments/{id}/authorization-flow/actions/form as a POST request

Form action consists of one or more inputs. Currently supported input types are text, select and text_with_image`.

1. Text

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

607607

Text input rendered by TrueLayer hosted payment page for a German mock provider

2. Select

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

610610

Select input rendered by TrueLayer hosted payment page for a French mock provider

3. Text with image
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.

608608

Text with image rendered by TrueLayer hosted payment page for a German mock provider. In Germany user would be required to use an app to scan the QR code and enter found value.

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

Request body:

{
    "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.


Did this page help you?