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.

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.

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.

First-time user flow

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.

Returning user flow

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.

Demo

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.

📘

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, use the HPP.

Create a payment with the hosted page

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

When using the hosted page, we recommend that you enable our payment retry feature, which enables users to retry failed payments within the user flow.

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 that you generate must include:

• 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"
    }
  }
}

Hosted page user flow without retries

When retry isn’t available for a given payment:

• On the result screen for a failed payment, there are no Try again or Change bank buttons. Just close or done options remain. These no longer trigger a retry.
• On error screens, the Try again button is removed. This leaves only a close button, which no longer triggers a retry.
• On the QR code screen, the back button is removed.
• On the cancel form, there is no option for the user to change their bank.
• If the user does choose to cancel the payment, then we call the /cancel endpoint.
• If a user has paid before but chooses to add a new bank, there is only a close option and no back option on the list of their saved accounts.
• The payment button after the user cancels the payment is displayed in a disabled state.

None of the above changes impact the flow if the retry object is present in the payment request.