New: Hosted page

📘

This feature is in development

Currently the hosted page only supports payments in the UK, France, Ireland and Germany.

It does not support mandate authorisation.

The hosted page is a prebuilt user interface you can direct your users to so they can authorise payments.

To use the hosted page, change any hash parameters (#) you use in the URL to query parameters (?).

We're automatically starting to redirect some UK payment traffic from the HPP to the new hosted page to improve the user experience. Contact us for more information about this.

The hosted page user flow

In the UK, France and Ireland, the user flow is almost always a redirect flow. In this flow, your user is redirected from your checkout page to a screen on which they can choose their bank. When they choose their bank, they are redirected again to their bank app where they can supply their login credentials to authorise the payment. Finally, they are taken back to your app and a screen displays to inform them of the payment result.

The hosted page also enables your users to save their account to enable faster future payments. This means that there are two different flows your user might experience:

• A longer flow when a user pays for the first time, as they have to select their bank.
• A shorter flow when the user returns and chooses to pay with their saved bank.
  The returning user flow is very similar to the flow for a payment with preselected provider selection.

In order for your users to save their details, they need to select the Pay faster next time checkbox when they make a payment.

Redirect flow for first-time users

The first time a user pays through the hosted page, they need to select a bank (or provider). After they select the bank, they have the option to select Pay faster next time on the payment confirmation screen. If they select this, their bank is saved for future payments made through TrueLayer.

In order to use this flow for your users, you need to contact us to enable it. You also need to include user information such as name and email address in your payment requests.

Redirect flow for returning users

If your user has made a previous payment, they no longer need to select a bank as part of the payment flow. This makes paying easier, and generally improves the user flow.

However, sometimes a user might want to pay through a different bank. They can still do this if they select Change on the saved provider selection screen.

If you know what provider a user wants to pay through, you can achieve a similar payment flow by using preselected as the provider selection method. However, with the hosted page, you can achieve the same improvements to the user flow without the need to change your integration.

📘

Limitations

The hosted page offers a better payment experience than the HPP, but it's still in development. As such, there are some features the hosted UI doesn't support:

• Variable recurring payment mandates
• EUR payments
• A localised user interface in non-English languages

If you need any of these features, use the HPP.

German hosted page flows

In Germany, you may encounter other kinds of user flows besides redirect:

• The embedded flow, in which your user inputs their bank login credentials on TrueLayer screens, rather than going to their bank app to log in. Some banks enable you to make an AIS request for data such as a user's IBAN, so they do not have to input that information themselves
• The decoupled flow, in which your user authorises the payment via an app or device independent from the online banking frontend (for example, by sending a push notification with transaction details to a dedicated mobile app)

AIS + PIS embedded flow

Your user may move through the AIS + PIS user experience if:

• they're paying with a bank that uses the embedded flow and
• they would need to input their IBAN as well as their bank login credentials.

In this situation, you can opt to make an AIS request (an API request for their bank account data) to retrieve their IBAN. This means that the user does not need to input the IBAN themselves when moving through the flow.

PIS only embedded flow

In this flow, the user inputs their IBAN manually in addition to their bank login credentials.

Decoupled flow

Create a payment with the hosted page

Any integration for payments in the UK, France or Ireland can use the hosted page.

When using the hosted page, we recommend that you enable our payment retry feature, which enables users to retry failed payments within the user flow.

Build a hosted page URL

For your user to authorise a payment through the hosted page, you need to redirect them to a hosted page link you've generated.

The hosted page link that you generate must include:

• a payment id, which you receive after you create a payment.
• a resource_token, which you also receive after you create a payment.
• a return_uri, which is where your user is redirected after they authorise the payment with their bank.
  This should match one of the entries you've added as a redirect_uri in Console.

As such, in order to generate a valid hosted page link, you need to be able to create a payment through the /v3/payments endpoint.

You also must set your desired return URI in the Application Settings page on Console.

Hosted page URL examples

These are examples of the simplest form of hosted page URL, including the id, resource_token and return_uri. There's examples for both the sandbox and production environments.

https://payment.truelayer-sandbox.com/payments?payment_id=8c905ec4-d51c-4ca8-8541-0538403ead0d&resource_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IkRCejExcEFuUGNXVndqaFBNWERuckNyQ0ZrT1p0Y2FqYWtjU21GNmJiVk0iLCJ0eXAiOiJKV1QifQ.eyJzY29wZSI6InBheW1lbnQiLCJjbGllbnRfaWQiOiJzYW5kYm94LXRvbXRlc3QtYTRkNDMyIiwianRpIjoiOGM5MDVlYzQtZDUxYy00Y2E4LTg1NDEtMDUzODQwM2VhZDBkIiwibmJmIjoxNzIwMDk4NzgyLCJleHAiOjE3MjAwOTk2ODIsImlzcyI6Imh0dHBzOi8vYXBpLnRydWVsYXllci1zYW5kYm94LmNvbS9wYXltZW50cy1nYXRld2F5IiwiYXVkIjoiaHR0cHM6Ly9hcGkudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.ZAEz21ZrTgGNZwVwfhquxCN2aO6qyizSb2sri89s3ywkF7c0lw2fhwfgTpv1aPmVbd8YwBur7vgvMa2xQFhAgzTMqfWEZ_Xy6-zjxYGlkNVkysrF1gOPYlGvPnizOZipPU_qekPnQUpe7VT2MldCggpOKip6iIwM5SBK4vfHZxOkg36fa1-gQLmfLxamCjeqz7PiK7e_yQAR6BmxZuuNsCEVCaY0ivIjborBYVGWM5fDcYO3paqvdjmqSLuEENiHnA0sMaoahXrPK-fSSXESxHhtc-_3P3Y1_Dm1ogj-xoLhuky0SLYWThnd2757aqoFR_v2XbTwt86QzY5OnZNdUg&return_uri=https://example.com/redirect/v3

https://payment.truelayer.com/payments?payment_id=8c905ec4-d51c-4ca8-8541-0538403ead0d&resource_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IkRCejExcEFuUGNXVndqaFBNWERuckNyQ0ZrT1p0Y2FqYWtjU21GNmJiVk0iLCJ0eXAiOiJKV1QifQ.eyJzY29wZSI6InBheW1lbnQiLCJjbGllbnRfaWQiOiJzYW5kYm94LXRvbXRlc3QtYTRkNDMyIiwianRpIjoiOGM5MDVlYzQtZDUxYy00Y2E4LTg1NDEtMDUzODQwM2VhZDBkIiwibmJmIjoxNzIwMDk4NzgyLCJleHAiOjE3MjAwOTk2ODIsImlzcyI6Imh0dHBzOi8vYXBpLnRydWVsYXllci1zYW5kYm94LmNvbS9wYXltZW50cy1nYXRld2F5IiwiYXVkIjoiaHR0cHM6Ly9hcGkudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.ZAEz21ZrTgGNZwVwfhquxCN2aO6qyizSb2sri89s3ywkF7c0lw2fhwfgTpv1aPmVbd8YwBur7vgvMa2xQFhAgzTMqfWEZ_Xy6-zjxYGlkNVkysrF1gOPYlGvPnizOZipPU_qekPnQUpe7VT2MldCggpOKip6iIwM5SBK4vfHZxOkg36fa1-gQLmfLxamCjeqz7PiK7e_yQAR6BmxZuuNsCEVCaY0ivIjborBYVGWM5fDcYO3paqvdjmqSLuEENiHnA0sMaoahXrPK-fSSXESxHhtc-_3P3Y1_Dm1ogj-xoLhuky0SLYWThnd2757aqoFR_v2XbTwt86QzY5OnZNdUg&return_uri=https://example.com/redirect/v3

Hosted page user flow

When retry isn’t available for a given payment:

• On the result screen for a failed payment, there are no Try again or Change bank buttons. Just close or done options remain. These no longer trigger a retry.
• On error screens, the Try again button is removed. This leaves only a close button, which no longer triggers a retry.
• On the QR code screen, the back button is removed.
• On the cancel form, there is no option for the user to change their bank.
• If the user does choose to cancel the payment, then we call the /cancel endpoint.
• If a user has paid before but chooses to add a new bank, there is only a close option and no back option on the list of their saved accounts.
• The payment button after the user cancels the payment is displayed in a disabled state.

None of the above changes impact the flow if the retry object is present in the payment request.

📘

Get UX guidance on Prisma

The Prisma site has everything you need to create seamless payment flows for the best user experience. Whether you're looking for the latest bank logos, proven UX patterns, or vertical-specific guidance, you'll find research-backed resources designed to reduce friction and boost conversion rates.

We recommend using Prisma resources alongside a TrueLayer UI, like the hosted page, for an optimal experience across the whole payment journey.