Create payments or mandates with the HPP

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:

building a HPP URL
directing your users to the HPP URL
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 parameter	Description
`payment_id` or `mandate_id`	Returned by Payments API on payment creation or mandate creation.
`resource_token`	Returned on payment creation.
`return_uri`	Where the user is redirected when they exit the payment flow. Can be any of the entries in your return URI allowlist in Console.

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

Environment	Payment type	URL structure
Sandbox	Payment	`https://payment.truelayer-sandbox.com/payments#payment_id={payment_id}&resource_token={resource_token}&return_uri={return_uri}`
Sandbox	Payment on a mandate	`https://payment.truelayer-sandbox.com/mandates#mandate_id={payment_id}&resource_token={resource_token}&return_uri={return_uri}`
Production	Payment	`https://payment.truelayer.com/payments#payment_id={payment_id}&resource_token={resource_token}&return_uri={return_uri}`
Production	Payment on a mandate	`https://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.