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:
- 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 can include the following hash parameters:
| Hash parameter | Required? | Description |
|---|---|---|
payment_id or mandate_id | Yes | Returned by Payments API on payment creation or mandate creation. |
resource_token | Yes | Returned on payment creation. |
return_uri | Yes | Where 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_result | No | A 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. |
signup | No | A 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:
| 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
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&max_wait_for_result=30
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}\`
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&max_wait_for_result=30
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:
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.
Updated 6 months ago