Customise the HPP user flow

Learn how to customise the hosted payment page user flow and improve the experience for users.

Country selection

The currency of a payment defines which countries a user can pick to pay from. So for a payment in euros, there are range of countries that the user can choose between. To help simplify that choice, HPP will pick a default country based on the browser locale, but allows the user to switch to a different country if needed.

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.

You can control which countries are available for your user to choose from, by setting a provider filter when you create the payment with the Payments API.

Bank selection

On the selection screen, banks are sorted by the highest market share first.

Banks are also assigned a release channel based on the maturity level of our integration. You can choose whether or not you want to include those that are in a beta release channel by using the provider filter when you create the payment with the Payments API.


The HPP selects the best language to display the user interface in, based on the browser locale. It supports the following languages:

  • English
  • Spanish
  • French
  • German
  • Dutch
  • Portuguese
  • Polish
  • Finnish
  • Lithuanian

If you need to, you can override the automatic language selection with a query parameter in the URL: ?lng=xx, where xx is the two-character Unicode 639-1 language code.


If the payment is part of a Signup+ onboarding flow, then you may want to use HPP to point out the additional data collected, and how it is used. If you set the Signup+ option to true when you start the payment flow, then the Review Payment screen shows an additional message.


To enable the Signup+ message, add the query parameter signup=true to your hosted payment page URL.

Additional inputs

Some banks outside the UK require us to provide additional information about the paying user in order to initiate the payment. That can include their branch or their IBAN. When necessary, HPP will ask the user to enter these details. A limited number of banks also require that the user log in to their bank account through the HPP screens, which it also securely handles.


Entering their IBAN can be a cause of friction for your users, but luckily this can be simplified. If you already have a record of your user's IBAN, then you can provide it to the Payments API when you create the payment in order to prevent the user from being asked to enter it as part of the payment. This is done using the preselected type of provider_selection. See Provider Selection for more information.

QR codes

For many banks, the authorisation experience is much easier from the bank's mobile app. In these cases, HPP will automatically open the app if the user is on their phone, or fallback to the website if they don't have the app installed. If the user is paying from a laptop, then HPP will show a QR code that the user can scan to launch the payment authorisation in their bank app, or else they can choose to continue to the bank's website on their laptop.