Payments or mandates with the HPP

Set up a hosted payment page.

HPP introduction

The hosted payment page (HPP) collects all payment information required from your users and guides them through the payment authorisation journey. We will add any new banks supported by TrueLayer to the HPP, so you don't need to make any updates.


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 includes:

  • A bank selection screen
  • A consent screen
  • Collecting any additional inputs needed from your user
  • A QR code that allows desktop users to continue the payment on their mobile phone
  • Redirection to your user's banking website or app
  • Alternatively, embedded payment authorisation for banks that require it

The flow for setting up a variable recurring payment mandate through the HPP.

Supported countries

The hosted payment page is currently optimised for the UK, Ireland, France, Germany, Spain, the Netherlands, and Lithuania.

Beta testers can also use the 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

When a customer makes a payment through the hosted payment page, it follows this flow:

  1. The user selects the Instant Bank Payment option.
  2. Your integration creates a payment with TrueLayer and gets a payment id and resource_token in response.
  3. Your system uses the ID and token to build the HPP URL and then displays 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, a desktop user will see a QR code. Scanning the code enables them to continue the payment using the banking app on their phone. They can also 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, which you set in Console. Your systems can then confirm the payment result to your user.

A diagram that shows the payment journey with HPP integration.


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

Authorise payments or mandate with the HPP

Before you can get create payments with the hosted payment page, you need to register for Console and add aredirect_uri.

You also need a payment or mandate id and resource_token, which are returned after a successful request to the /payments endpoint. As such, you must have configured the Payments API v3 and be able to create payments before you can use the HPP.

1. Build a HPP URL

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

Hash parameterDescriptionRequired
payment_idReturned on payment creation.Yes
resource_tokenReturned on payment creation.Yes
return_uriWhere the user is redirected when they exit the payment flow. This should be one of the entries you've added to your redirect_uri allow list in Console.

Do not include hash or query parameters in your return_uri.

These parameters should be substituted for the text and enclosing curly brackets in the URL below:{payment_id}&resource_token={resource_token)&return_uri={return_uri}

This is an example of a hosted payment page link built correctly:

2. Direct your user to the HPP

The next step is to guide your user to the HPP URL you built. Once they access it, the HPP takes them through a flow where they can authorise the payment or mandate.

You should direct your users to the HPP through a button that highlights the benefits and convenience of paying through TrueLayer. For example, a button in your app named Instant Bank Payment. Learn more about how to design your user experience and interface.

3. Confirm the payment result

After the user has successfully authorised their payment they are redirected to the return_uri you set in Console, which isspecified in your hosted payment page URL. The payment or mandate id is appended as a query parameter to your return_uri.

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

If your user chooses not to complete the payment or mandate and cancels on the hosted payment page, an extra error query parameter is appended, 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. Learn how to receive webhook notifications for your payments..