Authorisation flow actions
Learn about the format of, and how to complete, actions in the authorisation flow.
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:
Action name | How to complete the action |
---|---|
redirect | Redirect the user to a redirect URI registered in Console. |
provider_selection | Provide a provider_id that determines the bank through which the payment must be authorised.The user typically selects this through a UI you develop. |
form | Respond to the form action with additional data or a selection based on the structure the form action specifies. The form typically requests that users enter data such as bank credentials, or select an option from several. The required data varies based on bank and regional requirements. |
wait | Wait for the user to complete strong customer authentication (SCA) with their provider (in a different window or app) before returning to an embedded payment flow. |
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
redirect
actionThe 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
redirect
actionThe 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
provider_selection
actionThis 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
provider_selection
actionIn order to complete the provider_selection
action, you must:
- Render the list of providers returned in the
providers
object in a UI that the user can use to select a provider. - 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
form
actionSome 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
form
actionUsually, 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
form
actionCompleting the form action requires the following steps:
- 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. - Collect the input from the user.
- Submit the input to the
.../authorization-flow/actions/form
endpoint as a POST request.
Examples of different types of form
action
form
actionThis 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 typeText input type represents a simple written input from the user. On web it can be rendered as an html element of type input
.

Text input rendered by TrueLayer hosted payment page for a German mock provider
The select
input type
select
input typeSelect 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.

Select input rendered by TrueLayer hosted payment page for a French mock provider
The text_with_image
input type
text_with_image
input typeText 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.

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.
{
"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
wait
actionThe 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
wait
actionTo 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.
Updated about 1 month ago