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:
- 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.
Updated 3 days ago