Hosted payment page

The hosted payment page (HPP) presents a web user interface that makes it simple and easy to accept payments from your users.


Image showing what the HPP interface looks like. There are two screenshots in the image, one showing the bank selection screen and the other showing the payment confirmation screen.

The HPP collects all payment information required from your users and guides them through the payment authorisation journey. Any new banks supported by TrueLayer will be added to the HPP without any updates needed from your side.

Our HPP includes:

  • A bank selection screen
  • A consent screen
  • A QR code that allows desktop users to continue the payment on their mobile phone
  • Redirection to your user's banking website or app

Supported countries

Hosted payment page is currently optimised for the UK, Ireland, France, Germany, Spain, the Netherlands, and Lithuania. Beta testers can also use HPP for banks in Austria, Belgium, Finland, Poland and Portugal. The user interface can be displayed in English, Spanish, French, German, Dutch, Portuguese, Polish, Finnish and Lithuanian.

Supported browsers

We've built the hosted payment page to work best on:

  • Chrome
  • Edge
  • Firefox
  • Safari

Payment journey

  1. The user selects to pay through an Instant Bank Payment.
  2. Your backend creates a payment with TrueLayer and gets a payment token back (see Create a payment).
  3. Your system uses the payment token to build the HPP url (see Build a hosted payment page URL) and then display it to your user.
  4. Your user selects their bank on the screen, enters any additional information that the bank requires, and confirms.
  5. If their bank supports app-to-app authentication, then a desktop user will see a QR code, allowing them to choose to continue the payment using the banking app on their phone, or else to continue on desktop.
  6. The HPP redirects your user to their bank's website or app.
  7. Your user authorises the payment in their bank's website or app.
  8. Once the authorisation is complete, the bank redirects the user to your redirect_url. Your systems can then confirm the payment result to your user (see Confirm the payment result).

Image containing a diagram that shows the payment journey with HPP integration.


An example user journey, moving from desktop to mobile to complete the payment.

Before you begin

Before you can get started with the hosted payment page, you'll need to register a redirect_uri in our developer console. Your user will be redirected back to your website or application at the end of the payment journey. This redirect_uri defines where they will be redirected to.

Step 1: Create a payment

For each payment you first need to create a payment using the Payments API v3. Follow the instructions in the Single payments section, then continue the steps here to use the hosted payment page.

Step 2: Build a hosted payment page URL

After creating a payment, you will need to build a HPP URL. The URL should include the following hash parameters:

Hash parameterDescriptionRequired
payment_idReturned on payment creation:white-check-mark:
resource_tokenReturned on payment creation:white-check-mark:
return_uriWhere the user is redirected when they exit the payment flow. This should match one of the entries in your redirect_uri allow list on the developer console.:white-check-mark:

Step 3: Direct your user to the HPP

Redirect your user to the hosted payment page URL built in the previous step.

Step 4: Confirm the payment result

After the user has successfully authorised their payment they will be redirected to the return_uri specified in the previous step. The payment_id will be the query parameter in the return_uri.

For example: http://localhost:3000/redirect?payment_id=6755dacf-7dd8-4577-ba11-667b6aca8474

If your user chooses not to complete the payment and cancels on the hosted payment page, then an extra error query parameter will be included with tl_hpp_abandoned.

For example: http://localhost:3000/redirect?payment_id=6755dacf-7dd8-4577-ba11-667b6aca8474&error=tl_hpp_abandoned

In order to communicate the payment result to your user, you can retrieve the payment status via webhooks. See Receive status updates on your resources for more information.

Customise the user experience

The hosted payment page has some options you can use to tailor the user experience to best fit your specific context.

Make the country selection and provider selection more relevant

By default, HPP allows users to pay using any bank that handles the selected currency of the payment. For currencies like the Euro, that can mean that the user has a lot of banks to choose from.

HPP makes it easier for users to find the bank they need by grouping them by country. It uses the browser's locale to guess which country the user is interested in, whilst allowing them to switch to any other country where there are banks that support the selected currency.

If you already know which country the user will be paying from, you can ensure they always see that country first by setting a starting country as a hash parameter in the HPP URL: country_code=xx, where xx = the two character country code. The user will still be able to switch to a different country if they need to.

Another way to make the country selection more relevant is to filter out countries that you don't want your user to choose from. This is set when creating the payment on Payments API v3, using the filter object. Simply list which countries to include or exclude. Filtering to a single country means the user will be guided to only that country, and will not see the country selection screen at all.

You can also use the provider filter to set whether you'd like to include beta providers, and to filter for either retail providers, business providers or corporate providers. That can speed up provider selection for your users, if you already know which kind of bank they need. For more information on provider filters, see the Create Payment API reference.

Skip the provider selection screen altogether

Some businesses ask their customers to register and verify their bank account before they can use it to send payments. For these cases, you can ensure the user doesn't have to select their bank again during the payment flow by setting the provider_selection type to preselected when creating the payment on Payments API v3. You must pass the provider ID here, which ensures your user is fast-tracked through the payment journey. For more information on provider selection types, see the Create Payment API reference.

Simplify your user's journey by passing additional inputs for them

Some providers in Europe need to know the user's IBAN before they can be redirected to authorise the payment. By also including the remitter details when creating the payment, you can ensure that HPP has the user's IBAN and does not need to ask the user to enter it. For more information on the remitter object, see the Create Payment API reference.

Override the user's system language

Hosted payment page uses the browser locale to decide which language to display the user interface in. If there are scenarios where you need to override this (for example, during testing), then you can override this with a query parameter in the URL: ?lng=xx, where xx is the two-character Unicode 639-1 language code.

This approach works for the main hosted payment screens, but does not work for any messages displayed to the user when they are redirected back from their bank. So be careful about relying on this for real users.

Customise the look of your HPP

You can customise your hosted payment page to match the look and feel of your brand. Go to the Payments Customisation section of our developer console to:

  • Upload your merchant logo
  • Update the application name

Updating these settings will automatically be reflected on the hosted payment page.


Image showing bank selection screen with the customisable features of payee account name and app name.

Customise the colour scheme

The hosted payment page accepts 3 optional hash parameters in the URL to override the default colour scheme:

  • c_primary to customise background colour
  • c_secondary to customise button and loader colour
  • c_tertiary to customise input, links and hover colour


The colours must be provided in hexadecimal format. For example, c_primary=bbbbbb.


Image showing bank selection screen with the customisable features of primary background and tertiary link and hover colours.


Image showing bank selection screen with the customisable feature of tertiary input and illustration colours.


Image showing payment confirmation screen with the customisable features of secondary button and tertiary link colours.


Image showing a screen redirecting the user to their bank with the customisable feature of secondary loader colours.

Use HPP with your mobile app


For the best in-app experience, we recommend using our Android SDK and iOS SDK to add a native payment initiation screen to your app.

You can use the HPP in your mobile browser. The browser window also ensures the best compatibility across devices and banks.

Displaying the hosted payment page in your app as a web view can also be an option. The following tips will help you to maximise your payment success rates:

  • Don't use an iframe, as most banks don't support these for security reasons.
  • For Android, use a Chrome Custom Tab. For iOS, use a WKWebView, or Safari View Controller.
  • Provide an option for your user to exit the web view and return to your app, in case there are any problems displaying the HPP.
  • Open the direct bank link outside of the web view to make sure the device is able to open the banking app, where available.