--- title: "Start authorization flow" method: POST path: "/v3/payments/{id}/authorization-flow" tags: ["Payments"] --- # Start authorization flow `POST /v3/payments/{id}/authorization-flow` ## Request - Base URL: `https://api.truelayer-sandbox.com` - URL: `https://api.truelayer-sandbox.com/v3/payments/{id}/authorization-flow` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `https://auth.truelayer.com/connect/token` scopes: `payments` - HTTP bearer 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. ## Path parameters - `id` string, required: Unique ID for the Payment ## Headers - `Idempotency-Key` string - `Tl-Signature` string - `X-Forwarded-For` string - `X-Device-User-Agent` string ## Request body - StartPaymentAuthorizationFlow: 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. - `icon` Icon - `type` 'default' | 'extended' | 'extended_small' | 'extended_medium' | 'extended_large': Configuration for the type of icon. Available options are: - `default`: Default icon with no background (SVG). - `extended`: Extended as a square with an appropriate background colour (SVG). - `extended_small`: Extended icon with a 192x192 pixel resolution (JPEG). - `extended_medium`: Extended icon with a 432x432 pixel resolution (JPEG). - `extended_large`: Extended icon with an 864x864 pixel resolution (JPEG). - `branches` BranchesAuthorizationFlow - `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. - `return_uri` string, url, required: During the flow, the end user authorises the payment on a third-party site, such as a bank. The return URI you set is where the user is redirected to after they complete authorisation on the third-party site. You must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris). - `direct_return_uri` string, url: Only applicable if you're regulated and have a direct return URI registered with UK providers. If you're regulated, you can specify a `direct_return_uri` to attempt the authorization flow via a direct redirect from the provider authorization page to your page without going via TrueLayer. We recommend that your `return_uri` is a URI that can handle a non-direct return scenario. This ensures that if the `direct_return_uri` isn't registered with the user's chosen provider, the payment can still be authorized through a TrueLayer domain. - `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. - `input_types` AdditionalInputType[], required: The types of input that your UI can render a form to collect. - `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. - `action_type` 'explicit' | 'adjacent': How you will capture consent as part of the authorisation flow: - `explicit` (default): The authorisation flow returns an explicit `consent` action for you to respond to at an appropriate moment in the flow. - `adjacent`: You provide the consent information alongside other actions in the flow. This enables the UI to combine capturing consent alongside with other actions, if you indicate consent is gathered when you respond to those actions. Note this is currently only supported on `form` actions. - `requirements` ConsentSupported: The details of the consents supported to be captured from the user. - `pis` ConsentSupportedPis, required - `ais` ConsentSupportedAis - `scopes` AisScope[], 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. ## Response `200` Payment - union - PaymentAuthorizationFlowAuthorizing - `authorization_flow` PaymentAuthorizationFlow, required: Contains information regarding the nature and the state of the authorization flow - `actions` object, required - `next` union, required: The next action can be performed via `POST /v3/payments/{id}/authorization_flow/action/{action_name}` - check its documentation for relevant examples. - ActionSpecProviderSelection: Provider selection represents the end user action of selecting a provider - `type` 'provider_selection', required - `providers` Provider[], required: List of providers to be presented to the end user - … - ActionSpecSchemeSelection: Scheme selection represents the end user action of selecting a scheme - `type` 'scheme_selection', required - `schemes` Scheme[], required: List of schemes to be presented to the end user - … - ActionSpecRedirect - `type` 'redirect', required - `uri` string, url, required: URL the end user must be redirected to. - ActionSpecWaitForOutcome: Indication that there are currently no actions to perform. Clients must poll the `GET /v3/payment/{id}` endpoint until the status changes, or the next action is available. - `type` 'wait', required - `display_message` DisplayText - … - ActionSpecForm: Form action represents the end user action of entering further details into the UI. - `type` 'form', required - `inputs` ActionSpecAdditionalInput[], required: The inputs to be presented to the end user in the UI. - … - ActionSpecConsent - `type` 'consent', required - `requirements` ConsentRequirements, required: The details of the consents required to be captured from the user. - … - `subsequent_action_hint` 'redirect' | 'form' | 'wait', required - ActionSpecUserAccountSelection: Provides the end user with a list of previously saved user accounts for reuse. - `type` 'user_account_selection', required - `user_accounts` UserAccountDetails[], required: List of user accounts to be presented to the end user - … - ActionSpecRetry - `type` 'retry', required - `retry_options` RetryOption[], required: List of retry options available - ActionSpecBranchSelection: Branch selection represents the end user action of selecting a branch of the provider - `type` 'branch_selection', required - `branches` Branch[], required: List of branches to be presented to the end user - … - `adjacent` AdjacentActions: Actions that can be submitted alongside the next action - `consent` object - `requirements` ConsentRequirements, required: The details of the consents required to be captured from the user. - … - `status` 'authorizing', required - PaymentAuthorizationFlowAuthorizationFailed - `status` 'failed', required - `failure_stage` 'authorization_required' | 'authorizing' | 'authorized' | 'executed', required: The status the payment was in when it failed. - `failure_reason` string, required: The reason that the payment failed. ## Other responses - `400`: Invalid Request - `401`: Unauthenticated - `403`: Forbidden - `404`: Payment Not Found - `409`: Conflict - `422`: Idempotency-Key Reuse - `500`: Unknown Error --- [API](https://skmtc.dev/truelayer/apis/payments-api-v3.md) - [All operations](https://skmtc.dev/truelayer/apis/payments-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/truelayer/apis/payments-api-v3/revisions/a7c585fc9b84?raw)