# Hosted Pages user journeys

Token.io's HP guide the user through request initiation to consent and authentication with the bank. Here are example of user journeys using UK and EU banks, on both mobile and desktop.

### EU bank - new mobile user - branch selection - redirect integration

This example shows what happens when a new mobile user initiates 'Pay by Bank' with a bank in the EU that has branch selection, with redirect integration implemented.

As this is a new user, the onboarding screen is displayed (screen 1).

The user can choose to [search](#search-for-banks-by-name-bic-iban-or-bank-code) for their bank or choose from the most popular banks, which are displayed by default. The user can also save their choice for the next time they select **Pay by Bank** (screen 2).

Additional screens are displayed to enable users to select their bank branch (screens 3 and 4).

This user journey also shows the status screen (screen 9) where the current status of the transaction is displayed to the user; in this example **Payment submitted**.

|  |  |  |  |  |
|  --- | --- | --- | --- | --- |
| 1. Initiate pay by bank

 | 1. Select your bank

 | 1. Select your branch

 | 1. Choose your branch

 | 1. Redirect to your bank

 |
|  |  |  |  |  |
| 1. Enter your ID

 | 1. Confirm your login

 | 1. Authentication completed

 | 1. Payment confirmation

 | 1. Merchant acknowledgement

 |


|  |  |  |
|  --- | --- | --- |
| 1.  Initiate pay by bank | 2.  Scan the QR code with your phone | 3.  The user journey continues on your phone |


|  |  |
|  --- | --- |
| 4.  Continue on your phone and keep the desktop window open | 5.  Return to the desktop from your phone |


### Language change

The user can change the language in the HP by clicking the **Language** button in the top right corner of the screen and then selecting the required language from the list.

|  |  |
|  --- | --- |
| 1.  Click language button | 2.  Select language from list |


### Country change

The user can change the country in the HP by clicking the **Country** button on the **Select your bank** dropdown and then selecting the required country from the list.

|  |  |
|  --- | --- |
| 1.  Click country button | 2.  Select country from list |


### Country selection

The following settings determine which countries the user can see, or select from, in Hosted Pages v2.

- **Bank selection in the dashboard** (available in both Payments v1 and v2) - This limits the banks shown in the Hosted Pages and can be as granular as including or excluding specific banks, or controlling the countries that can be accessed.
See [WebApp - Bank selection]((./../../integration-considerations/dashboard-config#webapp--bank-selection)) for more details.
- **Countries array in the API** (available in Payments v1 only) - This limits the selectable countries in the Hosted Pages.
See the [countries](../../api/reference/Requests-for-Payments-v1-or-AIS#operation/GatewayService.StoreTokenRequest!path=requestPayload/0/countries&t=request) array in the API reference for more details.
- **Country query parameter** (available in both Payments v1 and v2) - preselects the country but allows the end user to switch countries, within the limits defined by the bank selection in the dashboard and the countries array in the API.
See [Localization parameters](./hosted-pages-v2-redirect-integration#localization-parameters) for more details.


### Browser back button behavior - redirect integration

This screen is displayed in a redirect integration if the browser back button is clicked during authentication and consent after redirecting to the bank.

|  |
|  --- |
| Navigation restriction |


This screen gives you the options to return to the merchant or a redirect option. The redirect button's behavior will depend on the type of bank integration:

- **one-step integration** (bank-initiated payments) – the user is directed to the TPP-provided redirect URL.
- **two-step integration** (TPP-initiated payments) – the user is returned to the bank selection process, where they can choose to go back to the same bank or back to the TPP.


### Payment failed

This screen is displayed when the final status of the transaction has been reached and the payment has failed.

|  |
|  --- |
| Payment failed |


### Request expired

This screen is displayed when the user experiences an expired request, *e.g.*, `SESSION_EXPIRED`. It's displayed when the `requestId` or `paymentId` expires, usually within 20 minutes of the `requestId` or `paymentId` being generated.

|  |
|  --- |
| Request expired |


### Unexpected error

This screen is displayed when the user experiences as an error. This is a 'catch all' screen for when an unexpected error from the API is received, it is not related to any payment status.

|  |
|  --- |
| Unexpected error |


### Service unavailable

This screen is displayed when the service (Token.io's A2A payments infrastructure) is unavailable.

|  |
|  --- |
| Service unavailable |


### IBAN validation

Before the Token.io Hosted Pages redirect to the bank for authorization, the user's IBAN is validated. Until IBAN validation succeeds, Hosted Pages redirect to the selected bank is paused.

### Search for banks by name, BIC, IBAN or bank code

Users can search the list of banks by entering a full or partial bank name, BIC, IBAN or bank code (*e.g.*, BLZ). If a full bank name, BIC, IBAN or bank code is provided and a match is found, a single result is displayed.

|  |  |
|  --- | --- |
| Search for your bank | Bank not found |


When multiple matches are found for a partial string, all matching results are listed for user selection.

If you have any feedback about the developer documentation, please contact [devdocs@token.io](mailto:devdocs@token.io)