API Reference
Asset librariesConsole

Start authorization flow

post
https://api.truelayer-sandbox.com/v3/payments//authorization-flow

Start the authorization flow for a payment.

This API can be called:

  • using the resource_token associated with the payment you are trying to fetch;
  • using a backend bearer token.
📘

Endpoint path changes

All Payments API v3 endpoints now start with /v3/. The old endpoints still work, but you must use the new path for all new integrations.

Alternative method to start authorisation flow

For single payments (which have a payment_method.type of bank_transfer), you can start the authorisation flow without this endpoint.

To do so, include the authorization_flow parameter when you create a payment through the /v3/payments endpoint. You should include each object within the parameter if your authorisation UI is capable of rendering it and you want the user to be able to complete the action.

Path Params
string
required

ID of the payment

Body Params

This object contains a declaration of the client UI's capabilities. The API will adjust the flow depending on this declaration and filter out unsupported providers.

provider_selection
object

Can your UI render a provider selection screen?

In payments where you set provider_selection as user_selected, your UI must be able to render a screen where the user can select their payments provider. This parameter is required for payments with user_selected provider selection. For preselected provider selection, it's optional.

Use the provider_selection.filter parameter at payment creation to determine the list of providers you can choose to display in your UI.

scheme_selection
object

Can your UI render a scheme selection screen?

For payments where you set scheme_selection as user_selected, your UI must be able to render a screen where the user can select their payments scheme.

This field is required for payments with user_selected scheme selection. For other scheme selection types, it's optional.

branch_selection
object

Can your UI render a branch selection screen?

For payments where you set branch_selection as user_selected, your UI must be able to render a screen where the user can select their payments branch.

This field is required for payments with user_selected branch selection. For other branch selection types, it's optional.

redirect
object

Can your UI redirect the user to a third-party page?

For most providers, the user authorises the payment after they're redirected to their chosen provider's page. There, they can sign in with their credentials and approve the payment. This parameter states whether your UI can handle such a redirect.

form
object

Can your UI render form inputs for the user to interact with?

Some providers require additional inputs, such as the remitter name and account details, to be provided before or during payment authorization. To facilitate this, the API may return a form action as part of the authorization flow, which means your UI must be able to collect the required inputs.

This parameter states whether your UI supports the form action. If you omit this parameter, the API returns only providers that don't require additional inputs.

If the provider has been preselected and requires additional inputs, this field is required.

consent
object

Can your UI capture the user's consent?

This parameter states whether your UI can explicitly capture and report the end user's consent for initiating the payment.

If you omit this, the API may restrict the available providers if explicit consent is required.

user_account_selection
object

Can your UI render a user account selection screen?

If the user has previously consented to saving their bank account details with TrueLayer, they can choose from their saved accounts to speed up following payments.

This field states whether your UI can render a selection screen for these saved accounts. If you omit this, the user isn't presented with this option.

Headers
string

An idempotency key to allow safe retrying without the operation being performed multiple times.
The value should be unique for each operation (we strongly advise to use a UUID v4), with the same key being sent on a retry of the same request.

string

A JWS with detached content, signed with your private key.
See Request Signing.

Required with a OAuth2 token.

string

Used to collect and record end-user IP address.
The first IP address in the list will be used as the end-user IP address.

string

Used to improve end-user's authentication experience based on device type.
If omitted, the User-Agent header will be used instead.

string
enum
Defaults to application/json; charset=UTF-8

Generated from available response content types

Allowed:
Responses

Updated about 1 month ago

Language
Credentials
URL
LoadingLoading…
Response
Choose an example:
application/json; charset=UTF-8
application/problem+json; charset=UTF-8

Updated about 1 month ago