Example direct API integration flows
These examples show the sequence of requests you need to make to authorise a payment as part of a direct API integration.
UK single provider redirect flow
Below is an example of a redirect flow in the UK. It consists of:
- The POST request sent to the
/v3/payments/{id}/authorization-flowendpoint to start the authorisation flow. - The response returned from the
/v3/payments/{id}/authorization-flowendpoint, which contains a list of possible providers. This example only contains a single provider, but it can contain more depending on the filters in the initial payment creation request. - The POST request sent to the
.../authorization-flow/actions/provider-selectionendpoint to submit the provider the user selected. - The response returned from the
.../authorization-flow/actions/provider-selectionendpoint, which contains theredirectaction. This will redirect the user to their bank's login page, where they can input the credentials.
{
"provider_selection": {},
"redirect": {
"return_uri": "https://console.truelayer.com/redirect-page"
}
}
{
"status": "authorizing",
"authorization_flow": {
"actions": {
"next": {
"type": "provider_selection",
"providers": [
{
"id": "mock-payments-gb-redirect",
"display_name": "Mock UK Payments - Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/uk/icons/mock-payments-gb-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/uk/logos/mock-payments-gb-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "GB"
}
]
}
}
}
}
{
"provider_id": "mock-payments-gb-redirect"
}
{
"status": "authorizing",
"authorization_flow": {
"actions": {
"next": {
"type": "redirect",
"uri": "https://pay-mock-connect.truelayer-sandbox.com/login/0bd4f72a-b508-4643-b5a0-eb90eab0f887#token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIwYmQ0ZjcyYS1iNTA4LTQ2NDMtYjVhMC1lYjkwZWFiMGY4ODciLCJzY29wZSI6InBheS1tb2NrLWNvbm5lY3QtYXBpIiwibmJmIjoxNjc5NDEyMjk4LCJleHAiOjE2Nzk0MTU4OTgsImlzcyI6Imh0dHBzOi8vcGF5LW1vY2stY29ubmVjdC50cnVlbGF5ZXItc2FuZGJveC5jb20iLCJhdWQiOiJodHRwczovL3BheS1tb2NrLWNvbm5lY3QudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.ksBNQV6H_Xhf7t6I9z9ZROblBFwwFz1HpM42autp37A"
}
}
}
}
EU provider selection with form flow
Below is an example of a flow within the EU which requires additional inputs from the user. It consists of:
- A POST request sent to the
/v3/payments/{id}/authorization-flowendpoint to start the authorisation flow. - The response returned from the
/v3/payments/{id}/authorization-flowendpoint. This contains a list of possible providers. This example contains 12 sandbox providers used to test different payment integrations. - A POST request sent to the
.../authorization-flow/actions/provider-selectionendpoint to submit the provider the user selected. - The response from the
.../authorization-flow/actions/provider-selectionendpoint. This contains extra information about what's required for the form. In this case, the user is asked to input their branch code, account number and sub-account number.
If theredirectaction is needed at this step, redirect the user to the link in theactions.next.uriobject. - A POST request sent to the
.../authorization-flow/actions/formendpoint to submit additional information for the form. - An example of the response after you submit the additional information needed for the form if there are no extra form actions to complete.
{
"provider_selection": {},
"redirect": {
"return_uri": "https://console.truelayer.com/redirect-page"
},
"form": {
"input_types": [
"text",
]
}
}
{
"status": "authorizing",
"authorization_flow": {
"actions": {
"next": {
"type": "provider_selection",
"providers": [
{
"id": "mock-payments-de-embedded",
"display_name": "Mock European Payments – Embedded Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-de-embedded.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-de-embedded.svg",
"bg_color": "#FFFFFF",
"country_code": "DE"
},
{
"id": "mock-payments-de-redirect",
"display_name": "Mock German Payments – Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "DE"
},
{
"id": "mock-payments-de-redirect-additional-input-text",
"display_name": "Mock German Payments – Redirect Flow with additional inputs",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "DE"
},
{
"id": "mock-payments-es-redirect",
"display_name": "Mock Spain Payments – Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "ES"
},
{
"id": "mock-payments-fr-redirect",
"display_name": "Mock France Payments – Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "FR"
},
{
"id": "mock-payments-fr-redirect-additional-input",
"display_name": "Mock France Payments – Redirect Flow - Additional Input",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "FR"
},
{
"id": "mock-payments-ie-redirect",
"display_name": "Mock Ireland Payments – Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "IE"
},
{
"id": "mock-payments-it-redirect",
"display_name": "Mock Italy Payments – Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "IT"
},
{
"id": "mock-payments-lt-redirect",
"display_name": "Mock Lithuania Payments – Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "LT"
},
{
"id": "mock-payments-nl-redirect",
"display_name": "Mock Netherlands Payments – Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "NL",
"search_aliases": [
"Mock Dutch Payments - Redirect Flow"
]
},
{
"id": "mock-payments-pl-redirect",
"display_name": "Mock Poland Payments – Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "PL"
},
{
"id": "mock-payments-pt-redirect",
"display_name": "Mock Portugal Payments – Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "PT"
}
]
}
}
}
}
{
"provider_id": "mock-payments-de-redirect-additional-input-text"
}
{
"status": "authorizing",
"authorization_flow": {
"actions": {
"next": {
"type": "form",
"inputs": [
{
"type": "text",
"id": "psu-branch-code",
"mandatory": true,
"display_text": {
"key": "psu-branch-code.display-text",
"default": "Branch"
},
"format": "any",
"sensitive": false,
"min_length": 3,
"max_length": 3,
"regexes": [
{
"regex": "^\\d{3}$",
"message": {
"key": "psu-branch-code.regex",
"default": "Value is invalid."
}
}
]
},
{
"type": "text",
"id": "psu-account-number",
"mandatory": true,
"display_text": {
"key": "psu-account-number.display-text",
"default": "Account"
},
"format": "numerical",
"sensitive": false,
"min_length": 7,
"max_length": 7,
"regexes": [
{
"regex": "^\\d{7}$",
"message": {
"key": "psu-account-number.regex",
"default": "Value is invalid."
}
}
]
},
{
"type": "text",
"id": "psu-sub-account",
"mandatory": true,
"display_text": {
"key": "psu-sub-account.display-text",
"default": "Sub-account"
},
"format": "numerical",
"sensitive": false,
"min_length": 2,
"max_length": 2,
"regexes": [
{
"regex": "^\\d{2}$",
"message": {
"key": "psu-sub-account.regex",
"default": "Value is invalid."
}
}
]
}
]
}
}
}
}
{
"inputs": {
"psu-branch-code": "123",
"psu-account-number":"1234567",
"psu-sub-account":"12"
}
}
{
"status": "authorizing",
"authorization_flow": {
"actions": {
"next": {
"type": "redirect",
"uri": "https://pay-mock-connect.truelayer-sandbox.com/login/bed1030c-b2c5-4f49-ad67-d63a0d51e854#token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJiZWQxMDMwYy1iMmM1LTRmNDktYWQ2Ny1kNjNhMGQ1MWU4NTQiLCJzY29wZSI6InBheS1tb2NrLWNvbm5lY3QtYXBpIiwibmJmIjoxNjc5NTgyODk5LCJleHAiOjE2Nzk1ODY0OTksImlzcyI6Imh0dHBzOi8vcGF5LW1vY2stY29ubmVjdC50cnVlbGF5ZXItc2FuZGJveC5jb20iLCJhdWQiOiJodHRwczovL3BheS1tb2NrLWNvbm5lY3QudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.9Sc660VEPaYP-dDAqJ_0uhXyOCqNIV4dHOVdm35g4UE"
}
}
}
}
EU form flow with provider and scheme selection
In this example, a payment is made to an EU provider which requires that the user select their branch. The payment also includes provider selection, scheme selection, and the optional consent action.
This payment is made in the sandbox environment with placeholder values. This means you can test this payment yourself.
To complete the payment, you need to complete the steps explained in the guide below.
How to use this guide
To go full screen, click the full screen icon in the top-right corner of the guide panel. Navigate by clicking the Next and Back interactive elements or arrow keys.
Expand this to access the requests and responses from this guide as plain text
{
"amount_in_minor": 1,
"currency": "EUR",
"payment_method": {
"type": "bank_transfer",
"provider_selection": {
"type": "user_selected",
"filter": {
"countries": [
"ES",
"FR",
"GB"
],
"release_channel": "public_beta"
},
"scheme_selection": {
"type":"user_selected"
}
},
"beneficiary": {
"type": "merchant_account",
"account_holder_name": "Merchant account name",
"merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
}
},
"user": {
"id": "2332d268-3c16-11ee-be56-0242ac120002 ",
"name": "Test user",
"email": "[email protected]",
"phone": "+441234567890"
}
}
{
"id": "b3886e6a-54d4-40b0-88be-e73126b5eaf3",
"user": {
"id": "dc913bd6-e6d2-49e7-a587-5653e5f329e2"
},
"resource_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6InBheW1lbnQiLCJjbGllbnRfaWQiOiJzYW5kYm94LXRvbXRlc3QtYTRkNDMyIiwianRpIjoiYjM4ODZlNmEtNTRkNC00MGIwLTg4YmUtZTczMTI2YjVlYWYzIiwibmJmIjoxNjkyMTc2NDkwLCJleHAiOjE2OTIxNzczOTAsImlzcyI6Imh0dHBzOi8vYXBpLnRydWVsYXllci1zYW5kYm94LmNvbSIsImF1ZCI6Imh0dHBzOi8vYXBpLnRydWVsYXllci1zYW5kYm94LmNvbSJ9.aBr5QHM3gFR5O_Hp7tagDHjc1cPlh018cJHqE3jkuiM",
"status": "authorization_required"
}
{
"provider_selection": {},
"scheme_selection": {},
"redirect": {
"return_uri": "{{ _.RETURN_URI }}"
},
"form": {
"input_types": [
"text",
"text_with_image",
"select"
]
},
"consent": {}
}
{
"status": "authorizing",
"authorization_flow": {
"actions": {
"next": {
"type": "provider_selection",
"providers": [
{
"id": "mock-payments-es-redirect",
"display_name": "Mock Spain Payments – Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "ES",
"schemes": [
{
"id": "sepa_credit_transfer"
},
{
"id": "sepa_credit_transfer_instant"
}
]
},
{
"id": "mock-payments-fr-redirect",
"display_name": "Mock France Payments – Redirect Flow",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "FR",
"schemes": [
{
"id": "sepa_credit_transfer"
},
{
"id": "sepa_credit_transfer_instant"
}
]
},
{
"id": "mock-payments-fr-redirect-additional-input",
"display_name": "Mock France Payments – Redirect Flow - Additional Input",
"icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock-payments-es-redirect.svg",
"logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock-payments-es-redirect.svg",
"bg_color": "#FFFFFF",
"country_code": "FR",
"schemes": [
{
"id": "sepa_credit_transfer"
},
{
"id": "sepa_credit_transfer_instant"
}
]
}
]
}
}
}
}
{
"provider_id": "mock-payments-fr-redirect-additional-input"
}
{
"status": "authorizing",
"authorization_flow": {
"actions": {
"next": {
"type": "scheme_selection",
"schemes": [
{
"id": "sepa_credit_transfer"
},
{
"id": "sepa_credit_transfer_instant"
}
]
}
}
}
}
{
"scheme_id": "sepa_credit_transfer_instant"
}
{
"status": "authorizing",
"authorization_flow": {
"actions": {
"next": {
"type": "consent",
"subsequent_action_hint": "form",
"requirements": {
"pis": {}
}
}
}
}
}
{}
{
"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"
},
"search_aliases": [
"Alpha",
"First",
"Main"
]
},
{
"id": "branch-b",
"display_text": {
"key": "branch-name.branch-b",
"default": "Branch B"
},
"search_aliases": [
"Bravo",
"BrB"
]
},
{
"id": "branch-c",
"display_text": {
"key": "branch-name.branch-c",
"default": "Branch C"
},
"search_aliases": [
"Charlie"
]
},
{
"id": "branch-d",
"display_text": {
"key": "branch-name.branch-d",
"default": "Branch D"
},
"search_aliases": [
"Delta"
]
},
{
"id": "branch-e",
"display_text": {
"key": "branch-name.branch-e",
"default": "Branch E"
},
"search_aliases": [
"Echo"
]
},
{
"id": "branch-f",
"display_text": {
"key": "branch-name.branch-f",
"default": "Branch F"
}
},
{
"id": "branch-g",
"display_text": {
"key": "branch-name.branch-g",
"default": "Branch G"
}
},
{
"id": "branch-h",
"display_text": {
"key": "branch-name.branch-h",
"default": "Branch H"
}
},
{
"id": "branch-i",
"display_text": {
"key": "branch-name.branch-i",
"default": "Branch I"
}
},
{
"id": "branch-j",
"display_text": {
"key": "branch-name.branch-j",
"default": "Branch J"
}
}
]
}
]
}
}
}
}
{
"inputs": {
"branch-name": "branch-a"
}
}
{
"status": "authorizing",
"authorization_flow": {
"actions": {
"next": {
"type": "redirect",
"uri": "https://pay-mock-connect.truelayer-sandbox.com/login/25378d52-bc5f-404b-8e92-3eeec2dd2fbb#token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyNTM3OGQ1Mi1iYzVmLTQwNGItOGU5Mi0zZWVlYzJkZDJmYmIiLCJzY29wZSI6InBheS1tb2NrLWNvbm5lY3QtYXBpIiwibmJmIjoxNjkwOTg4MjQ2LCJleHAiOjE2OTA5OTE4NDYsImlzcyI6Imh0dHBzOi8vcGF5LW1vY2stY29ubmVjdC50cnVlbGF5ZXItc2FuZGJveC5jb20iLCJhdWQiOiJodHRwczovL3BheS1tb2NrLWNvbm5lY3QudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.Y2E8mypsRQLhDlF_D2BKSVGpD4M0EcTKNKiLAMGQ6dI"
}
}
}
}
Updated 2 months ago