Authorise payments or mandates with the HPP

Learn how to create a hosted payment page link, direct your users to it, and how to check the payment.

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

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

Once you have registered for Console, added a redirect_uri, and integrated the Payments API v3, there are three steps to creating payments. These are:

  1. building a HPP URL
  2. directing your users to the HPP URL
  3. confirming the payment result.

1. Build a HPP URL

After creating a payment or a payment on a mandate with the Payments API, you can build a hosted payment page URL for the transaction. The URL can include the following hash parameters:

Hash parameterRequired?Description
payment_id or mandate_idYesReturned by Payments API on payment creation or mandate creation.
resource_tokenYesReturned on payment creation.
return_uriYesWhere the user is redirected when they exit the payment flow. This should match one of the entries you've added to your redirect_uri allow list in Console.
max_wait_for_resultNoA value in seconds that specifies how long to wait to display the payment result screen after authorisation. Cannot be used with mandates.

If omitted, the default value is 3 seconds. The maximum possible value is 60 seconds. A value over 60 is treated as 60 seconds.
signupNoA Boolean parameter that determines whether or not to display additional wording as part of a Signup+ flow. Must have a value of true or false.

To build the URL, substitute these parameters for the text and enclosing curly brackets in the URLs below:

EnvironmentPayment typeURL structure
SandboxPayment on a mandate{payment_id}&resource_token={resource_token)&return_uri={return_uri}
ProductionPayment on a mandate{payment_id}&resource_token={resource_token)&return_uri={return_uri}

Here are examples of hosted payment page links built correctly in sandbox:

Here are examples of hosted payment page links built correctly in production:

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 is specified in your hosted payment page URL. The payment or mandate id is appended as a query parameter to your return_uri. For single payments and mandates, examples of the return_uri are as below:

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

Mandate: http://localhost:3000/redirect?mandate_id=7fbd4cb8-0924-4a3d-a72c-f3d3a82ac7c8

If your user chooses not to complete the payment and cancels on the hosted payment page, an extra error query parameter is appended, tl_hpp_abandoned. For example:


In order to communicate either the payment or mandate result to your user, you must retrieve its status via webhooks. Learn how to receive webhook notifications for your payments or mandates.