Authorisation flow actions

Depending upon how you configure your payment creation request, sometimes the /v3/payments/{id}/authorization-flow endpoints return actions.

There are six different actions that you may need to complete to authorise a payment. To set up a direct integration with the Payments API, you need to develop logic and UIs to complete these actions.

Read below for more detailed information on how to complete each type of action.

How to complete actions

To complete the actions required for authorisation, send the required data in a POST request. For example, you send a provider_id in the POST request for the provider_selection action.

The actions.next.type object 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 provider_selection action

The provider_selection action is needed if you create a payment with the value user_selected for provider_selection.type.

You complete this action when actions.next.type has the value provider_selection. This is accompanied by a list of providers as an array.

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

This is the general format of the providers array:

{
        "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 array in a UI that the user can use to select a provider.
   You can use the information in the availability object to render a UI that reflects when a provider is currently unavailable.
2. Submit the id of the provider the user selected in a POST request to the .../authorization-flow/actions/provider-selection endpoint.

The providers object includes the following information for each provider:

• id of the provider.
• Display name.
• Link to an SVG icon.
• Link to an SVG logo.
  This usually contains the icon and the provider's name as text.
• Description of whether the provider is available or not.
• Suggested background colour for the provider as a hex colour code.

📘

Image format

We supply all icons and logos as SVGs for maximum image quality and scalability.

The scheme_selection action

The scheme_selection action is needed if you create a payment with the value user_selected for scheme_selection.type.

You complete this action when actions.next.type has the value scheme_selection. This is accompanied by a list of schemes as an array.

This is the general format of the schemes array:

{
				"type": "scheme_selection",
				"schemes": [
					{
						"id": "sepa_credit_transfer"
					},
					{
						"id": "sepa_credit_transfer_instant"
					}
				]
			}

How to complete the scheme_selection action

In order to complete the scheme_selection action, you must:

1. Render the list of schemes returned in the schemes array in a UI that the user can use to select a scheme (alternatively, if only one scheme is available, you can just submit that).
2. Submit the id of the scheme the user selected in a POST request to the .../authorization-flow/actions/scheme-selection endpoint.

There are three payment schemes that payments can be made over: faster_payments_service in the UK, and sepa_credit_transfer_instant, and sepa_credit_transfer in the EU.

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 action:

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

Complete the redirect action

The redirect action means that you need to redirect your user to the uri returned in the object. Register this URI in Console. This URI does not change if your user chooses to pay via mobile or desktop.

The form action

Some providers in the EU need to collect additional data as part of authorisation. Also, users sometimes need to submit their banking credentials within an embedded flow.

When either of these is the case, the Payments API returns form as the next action. Possible types of form action are text, text_with_image and select.

The form action contains the required format of the additional information the user must provide and any constraints that apply (such as forbidden special characters).

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 or 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.

form action formats

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

The type of form that applies to a payment is specified in the actions.next.input.type object.

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.

When you submit the user's response to a form to the .../authorization-flow/actions/form endpoint, the request body must be a map with the type of input as the key and the user input as value. For example:

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

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.

The consent action

The consent action is an optional step you can add to your authorisation flow. Its completion indicates that you've gained informed consent from the user for TrueLayer to initiate a payment on their behalf.

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

{
	"status": "authorizing",
	"authorization_flow": {
		"actions": {
			"next": {
				"type": "consent",
				"subsequent_action_hint": "redirect",
				"requirements": {
					"pis": {}
				}
			}
		}
	}
}

How to complete the consent action

To complete the consent action, you should:

1. Display a screen that explains to the user that they are giving consent for TrueLayer to initiate a payment from their bank account.
   This is typically be part of a payment review or confirmation screen, which contains more information about payment initiation, and the TrueLayer terms of service and privacy policy. Learn more about consent for pay-ins and VRP mandates.
2. Send a POST request to the .../authorization-flow/actions/consent endpoint.

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 whether authentication has been completed.

Implement actions within an auth flow

For some examples of how to implement auth flows, including provider_selection, redirect and form actions, see the page on example direct API authentication flows.