Skip to content
Get started
/
Hosted Pages (HP)
/
/
Migrating from Hosted Pag...
Last updated

Migrating from Hosted Pages v1 to Hosted Pages v2

Migrating from HP v1 to HP v2 has the following benefits:

Improved bank selection:

  • Banks are sorted by popularity not alphabetically, increasing the proportion of users that can find their bank instantly.

  • A more prominent bank search ensures users don’t think only those banks on screen are available.

  • Where a bank has branches that the user must select, branch selection has been moved to a second step to avoid lengthy scrolling to select the relevant branch.

  • Banks requiring IBAN insertion no longer require branch selection.

Conversion-boosting features:

  • A one-click bank selection journey for redirect banks without branches, with no separate consent screen.

  • Modal integration allows HP to display as an overlay on top of your checkout/payment page, thereby minimising redirects, improving continuity within the journey and keeping users in context of their payment for longer.

  • The ability to complete a transaction on a mobile device using the banking app by transferring the transaction from desktop to the mobile device using a QR code. This makes use of the more frictionless biometric authentication journeys of mobile in a desktop context.

  • Improved implementation of embedded authentication banks with better explanatory prompts.

Easier user navigation:

  • Faster load times.

  • A dedicated desktop view.

  • Improved use of screen real estate for both mobile and desktop views, resulting in reduced scrolling.

  • Support for dark and light modes.

  • A refreshed look and feel with clean visuals.

Enhanced customisation:

  • Easier customization within the Token.io Dashboard.

  • Increased availability of optional screens (e.g., onboarding screen explaining the journey to users).

  • The ability to add images/graphics to the custom footer to drive user trust.

Required changes

For all clients using Payments v1 and Hosted Pages v1 the redirectUrl must be changed from:

web-app.token.io/app/request-token/{requestId}

to:

app.token.io/session/{requestId}

We strongly recommend:

  • pre-selecting the user’s country by adding country={2-letter country code, e.g., GB} as a query parameter to the URL.

  • pre-selecting the user’s language by adding lang={2-letter language code, e.g., EN} as a query parameter to the URL.

Example country and language selection

UK country and English language:
https://app.token.io/session/{requestId}?country=GB&lang=EN

German country and German language:
https://app.token.io/session/{requestId}?country=DE&lang=DE

See Create a redirect URL for more details.

Optional change

If the status is currently retrieved from the HP callback URL query parameters, it's worth considering changing to using webhooks:

  • Webhooks are more efficient and less prone to potential 'status overlap', where the status might have changed while the user is being redirected to the TPP.

  • Webhooks will only be triggered when the status actually changes, making them the preferred option over status polling.

See Webhooks for more details.

If you have any feedback about the developer documentation, please contact devdocs@token.io

Previous page
Next page