New: Hosted page (UK only)

📘

This feature is in development

Currently the hosted page only supports UK payments. It doesn't support payments in Europe, or mandate authorisation.

The hosted page is a prebuilt user interface you can direct your users to so they can authorise payments. It features a new design that aims to guide users through the payment flow quickly and easily. It also supports a range of new features.

For example, with the hosted page, users can save their bank account with TrueLayer for faster payments in the future. It also allows users to retry failed payments.

To use the hosted page, all you need to do is:

• Change the base URL you currently use with the hosted payment page (HPP) from payment.truelayer.com to app.truelayer.com.
• Change any hash parameters (#)you use in the URL to query parameters (?).

We're automatically starting to redirect some UK payment traffic from the HPP to the new hosted page to improve the user experience. Contact us for more information about this.

Hosted page example

This Figma prototype lets you click through the user payment flow on mobile and desktop. As such, you can see the experience you users would have if you integrate the hosted page.

Select Monzo as the bank to see the flow of a successful payment.

Features

The hosted page supports a range of functionality, such as:

• A bank selection screen
• A consent screen
• A QR code that allows desktop users to continue the payment on their mobile phone
• Built-in payment result screens to inform of success, or to help users with failed payments
• Customisable merchant logos

Limitations

The hosted page offers a better payment experience than the HPP, but it's still in development. As such, there are some features the hosted UI doesn't support:

• Signup+
• Variable recurring payment mandates
• EUR payments
• A localised user interface in non-English languages

If you need any of these features, you can use the HPP.

How to use the hosted page

Any integration for payments in the UK can use the hosted page.

When using the hosed page, we recommend that you enable our payment retry feature, which enables users to retry failed payments within the user flow. If these aren't enabled, we don't display the Retry button, but you can still create a new payment to try again.

Build a hosted page URL

For your user to authorise a payment through the hosted page, you need to redirect them to a hosted page link you've generated.

The hosted page link you generate needs:

• a payment id, which you receive after you create a payment.
• a resource_token, which you also receive after you create a payment.
• a return_uri, which is where your user is redirected after they authorise the payment with their bank.
  This should match one of the entries you've added as a redirect_uri in Console.

As such, in order to generate a valid hosted page link, you need to be able to create a payment through the /v3/payments endpoint.

You also must set your desired return URI in the Application Settings page on Console.

Hosted page URL examples

These are examples of the simplest form of hosted page URL, including the id, resource_token and return_uri. There's examples for both the sandbox and production environments.

https://app.truelayer-sandbox.com/payments?payment_id=8c905ec4-d51c-4ca8-8541-0538403ead0d&resource_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IkRCejExcEFuUGNXVndqaFBNWERuckNyQ0ZrT1p0Y2FqYWtjU21GNmJiVk0iLCJ0eXAiOiJKV1QifQ.eyJzY29wZSI6InBheW1lbnQiLCJjbGllbnRfaWQiOiJzYW5kYm94LXRvbXRlc3QtYTRkNDMyIiwianRpIjoiOGM5MDVlYzQtZDUxYy00Y2E4LTg1NDEtMDUzODQwM2VhZDBkIiwibmJmIjoxNzIwMDk4NzgyLCJleHAiOjE3MjAwOTk2ODIsImlzcyI6Imh0dHBzOi8vYXBpLnRydWVsYXllci1zYW5kYm94LmNvbS9wYXltZW50cy1nYXRld2F5IiwiYXVkIjoiaHR0cHM6Ly9hcGkudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.ZAEz21ZrTgGNZwVwfhquxCN2aO6qyizSb2sri89s3ywkF7c0lw2fhwfgTpv1aPmVbd8YwBur7vgvMa2xQFhAgzTMqfWEZ_Xy6-zjxYGlkNVkysrF1gOPYlGvPnizOZipPU_qekPnQUpe7VT2MldCggpOKip6iIwM5SBK4vfHZxOkg36fa1-gQLmfLxamCjeqz7PiK7e_yQAR6BmxZuuNsCEVCaY0ivIjborBYVGWM5fDcYO3paqvdjmqSLuEENiHnA0sMaoahXrPK-fSSXESxHhtc-_3P3Y1_Dm1ogj-xoLhuky0SLYWThnd2757aqoFR_v2XbTwt86QzY5OnZNdUg&return_uri=https://example.com/redirect/v3

https://app.truelayer.com/payments?payment_id=8c905ec4-d51c-4ca8-8541-0538403ead0d&resource_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IkRCejExcEFuUGNXVndqaFBNWERuckNyQ0ZrT1p0Y2FqYWtjU21GNmJiVk0iLCJ0eXAiOiJKV1QifQ.eyJzY29wZSI6InBheW1lbnQiLCJjbGllbnRfaWQiOiJzYW5kYm94LXRvbXRlc3QtYTRkNDMyIiwianRpIjoiOGM5MDVlYzQtZDUxYy00Y2E4LTg1NDEtMDUzODQwM2VhZDBkIiwibmJmIjoxNzIwMDk4NzgyLCJleHAiOjE3MjAwOTk2ODIsImlzcyI6Imh0dHBzOi8vYXBpLnRydWVsYXllci1zYW5kYm94LmNvbS9wYXltZW50cy1nYXRld2F5IiwiYXVkIjoiaHR0cHM6Ly9hcGkudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.ZAEz21ZrTgGNZwVwfhquxCN2aO6qyizSb2sri89s3ywkF7c0lw2fhwfgTpv1aPmVbd8YwBur7vgvMa2xQFhAgzTMqfWEZ_Xy6-zjxYGlkNVkysrF1gOPYlGvPnizOZipPU_qekPnQUpe7VT2MldCggpOKip6iIwM5SBK4vfHZxOkg36fa1-gQLmfLxamCjeqz7PiK7e_yQAR6BmxZuuNsCEVCaY0ivIjborBYVGWM5fDcYO3paqvdjmqSLuEENiHnA0sMaoahXrPK-fSSXESxHhtc-_3P3Y1_Dm1ogj-xoLhuky0SLYWThnd2757aqoFR_v2XbTwt86QzY5OnZNdUg&return_uri=https://example.com/redirect/v3

📘

Note that the hosted page uses the same structure as the hosted payment page. The difference is that the base URL is app.truelayer.com, not payment.truelayer.com.

Payment retries and the attempt_failed status

You should enable payment retries through the attempt_failed status if you use the hosted page. This enables the hosted page to provide a better experience for your users, where the can retry failed payments more easily.

The attempt_failed status is an intermediary status that applies to payments that are in the process of failing. This status means that a payment that would otherwise fail can be retried without the need to create a new payment.

The resource_token linked to a payment expires after 15 minutes, after which a payment cannot be retried anymore.

To enable payment retries, you need to include the payment_method.retry{} parameter in your payment creation request. The parameter should be empty, like line 19 in the example below:

{
  "amount_in_minor": 100,
  "currency": "GBP",
  "payment_method": {
    "provider_selection": {
      "type": "user_selected"
    },
    "filter": {
      "countries": [
        "GB"
      ]
    },
    "type": "bank_transfer",
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "{merchant_account_id}",
      "reference": "Test payment"
    },
    "retry": {}
  },
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
    "name": "Jonathan Sandbridge",
    "email": "[email protected]",
    "phone": "+44123456789",
    "date_of_birth": "1992-11-28",
    "address": {
      "address_line1": "40 Finsbury Square",
      "city": "London",
      "state": "London",
      "zip": "EC2A 1PX",
      "country_code": "GB"
    }
  }
}

The hosted page user flow

The hosted page enables your users to save their account to enable faster future payments. This means that there are two different main flows your user might experience:

• A longer flow when a user pays for the first time, as they have to select their bank.
• A shorter flow when the user returns and chooses to pay with their saved bank.
  The returning user flow is very similar to the flow for a payment with preselected provider selection.

In order for your users to save their details, they need to select the Pay faster next time checkbox when they make a payment.

User flow without a saved bank

The first time a user pays through the hosted page, they need to select a bank (or provider). After they select the bank, they have the option to select Pay faster next time on the payment confirmation screen. If they select this, their bank is saved for future payments made through TrueLayer.

In order to use this flow for your users, you need to contact us to enable it. You also need to include user information such as name and email address in your payment requests.

User flow with a saved bank

If you user selected Pay faster next time on the payment confirmation screen in a previous payment, they no longer need to select a bank as part of the payment flow. This makes paying easier, and generally improves the user flow.

However, sometimes a user might want to pay through a different bank. They can still do this if they select Change on the saved provider selection screen.

If you know what provider a user wants to pay through, you can achieve a similar payment flow by using preselected as the provider selection method. However, with the hosted page, you can achieve the same improvements to the user flow without the need to change your integration.