Create 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 return 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 must include the following hash parameters:

Hash parameterDescription
payment_id or mandate_idReturned by Payments API on payment creation or mandate creation.
resource_tokenReturned on payment creation.
return_uriWhere the user is redirected when they exit the payment flow. Can be any of the entries in your return URI allowlist in Console.

Important: you need to add a return_uri to the Console App Settings or the Payment will eventually fail.

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

EnvironmentPayment typeURL structure
SandboxPaymenthttps://payment.truelayer-sandbox.com/payments#payment_id={payment_id}&resource_token={resource_token}&return_uri={return_uri}
SandboxPayment on a mandatehttps://payment.truelayer-sandbox.com/mandates#mandate_id={payment_id}&resource_token={resource_token}&return_uri={return_uri}
ProductionPaymenthttps://payment.truelayer.com/payments#payment_id={payment_id}&resource_token={resource_token}&return_uri={return_uri}
ProductionPayment on a mandatehttps://payment.truelayer.com/mandates#mandate_id={payment_id}&resource_token={resource_token}&return_uri={return_uri}

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

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

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

https://payment.truelayer.com/payments#payment_id=6755dacf-7dd8-4577-ba11-667b6aca8474&resource_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJwZW5ueWRldi1lNTkzOGEiLCJqdGkiOiI2NzU1ZGFjZi03ZGQ4LTQ1NzctYmExMS02NjdiNmFjYTg0YmYiOjE2MzQ2Mzk1NDQsImV4cCI6MTYzNDY0MDQ0NCwiaXNzIjoiaHR0cHM6Ly9hcGkmRldiIsImF1ZCI6Imh0dHBzOi8vYXBpLnQ3ci5kZXYifQ.vlEvoSdFv8g7t21RlXYyus01uEZlalK89P4Ii7Avl_8&return_uri=http://www.yourwebaddress.com/redirect
<https://payment.truelayer.com/mandates#mandate_id={payment_id}&resource_token={resource_token>)&return_uri={return_uri}\`

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.

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

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

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.