Create payments or mandates with the HPP

Before you start

Before you get started with the hosted payment page, there are a couple of steps to cover first.

Set up payments in your Console account, and ensure you've set a redirect_uri. Your user is redirected back to your website or application at the end of the payment journey and this redirect_uri defines where they are redirected to.
Set up your integration with Payments API v3. You don't need to consume all of the Payments API endpoints, but you do need to be able to either create a payment or create a variable recurring payment mandate, and then register for webhook notifications to consume the result.

Build a hosted payment page URL

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

Hash parameter	Description	Required
`payment_id` or `mandate_id`	Returned by Payments API on payment creation or mandate creation.	Yes
`resource_token`	Returned on payment creation.	Yes
`return_uri`	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.	Yes

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

Environment	URL structure
Sandbox	For payments: `https://payment.truelayer-sandbox.com/payments#payment_id={payment_id}&resource_token={resource_token)&return_uri={return_uri}` For VRP mandates: `https://payment.truelayer-sandbox.com/mandates#mandate_id={payment_id}&resource_token={resource_token)&return_uri={return_uri}`
Production	For payments: `https://payment.truelayer.com/payments#payment_id={payment_id}&resource_token={resource_token)&return_uri={return_uri}` For VRP mandates: `https://payment.truelayer.com/mandates#mandate_id={payment_id}&resource_token={resource_token)&return_uri={return_uri}`

Here is an example of a hosted payment page link built correctly:

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

Direct your user to the HPP

Direct your user to the hosted payment page URL you've just built.

Typically, you direct your users to the hosted payment page through a button in your app named Instant Bank Transfer. Learn more about how to design your user experience and interface.

Confirm the payment result

After the user has successfully authorised their payment they are redirected to the return_uri specified in your hosted payment page URL. The payment_id is appended as a query parameter to your return_uri.

For example: http://www.yourwebaddress.com/redirect?payment_id=6755dacf-7dd8-4577-ba11-667b6aca8474

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

For example: http://www.yourwebaddress.com/redirect?payment_id=6755dacf-7dd8-4577-ba11-667b6aca8474&error=tl_hpp_abandoned

In order to communicate the payment result to your user, you can retrieve the payment status via webhooks notifications.