Hosted Payment Page

🚧

This feature is in private beta and is currently available to a limited number of customers. To join our private beta, contact Client Care.

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.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.

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
  • Redirection to your user's banking website or app

Supported browsers

We've built the Hosted Payment Page to work best on:

  • Chrome
  • Edge
  • Firefox
  • Safari

Payment journey

  1. The user selects Pay By Bank.
  2. Your backend creates a payment with TrueLayer and gets a payment resource token back.
  3. Your user sees the HPP url, selects their bank on the screen, and confirms.
  4. The HPP redirects your user to their bank's website or app.
  5. Your user authorises the payment in their bank's website or app.
  6. Once the authorisation is complete, the bank redirects the user to your redirect_url.
Image containing a diagram that shows the payment journey with HPP integration.Image containing a diagram that shows the payment journey with HPP integration.

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

Before you begin

Before you can use the Hosted Payment Page, you'll need to:

  1. Create a payment using the Payments API v3.

  2. Register a redirect_uri from our developer console. Your user will be redirected back to your website or application at the end of the payment journey.

Step 1: 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 parameter

Description

Required

payment_id

Returned on Payment Creation

:white-check-mark:

resource_token

Returned on Payment Creation

:white-check-mark:

return_uri

Where the user is redirected when they exit the payment flow

:white-check-mark:

https://checkout.truelayer-sandbox.com/payments#payment_id=6755dacf-7dd8-4577-ba11-667b6aca8474&resource_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJwZW5ueWRldi1lNTkzOGEiLCJqdGkiOiI2NzU1ZGFjZi03ZGQ4LTQ1NzctYmExMS02NjdiNmFjYTg0YmYiOjE2MzQ2Mzk1NDQsImV4cCI6MTYzNDY0MDQ0NCwiaXNzIjoiaHR0cHM6Ly9hcGkmRldiIsImF1ZCI6Imh0dHBzOi8vYXBpLnQ3ci5kZXYifQ.vlEvoSdFv8g7t21RlXYyus01uEZlalK89P4Ii7Avl_8&return_uri=http://www.localhost:3000/redirect

Step 2: Direct your user to the HPP

Redirect your user to the Hosted Payment Page URL built in the previous step.

Step 3: 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.

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_cancelled.

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

Customise your HPP

You can customise your Hosted Payments Page to match the look and feel of your brand. Go to our 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 Payments Page.

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

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

Customise the colour scheme

The Hosted Payments 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=bbbbb.

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 features of primary background and tertiary link and hover colours.

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 bank selection screen with the customisable feature of tertiary input and illustration 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 payment confirmation screen with the customisable features of secondary button and tertiary link 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.Image showing a screen redirecting the user to their bank with the customisable feature of secondary loader 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.

Did this page help you?