Token.io Web App

This section is for customers using the Hosted payments page (Token.io Web App).

Token.io's Web App is available as a standard or customized user interface that bridges TPP service initiation with the bank's SCA and consent mechanisms. As described in Authentication, the Token.io Web App supports the Redirect model, the Decoupled model and the Embedded model. The SDK can be used to whitelabel/customize the Web App with your logo and color scheme.

The white label feature, however, first requires permission from Token.io to create the customization.

Web App flow

Token.io's Web App UX (click to enlarge) guides the user through request initiation to consent and authentication with the bank.

As a TPP you can't change the web app flow, but you can customize the UI with your own logo and color scheme.

The Web App's Payment Confirmation page is now displayed upon consent authorization.

Search for banks by name or BIC

Users can search the list of banks by entering a full or partial bank name or BIC. If a full BIC or bank name is provided and a match is found, a single result is displayed.

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

Remember, prior to customer redirect to the Web App, you can filter the search list with a GET v2/banks call. See Bank Selection.

Customer cancellation during bank selection

A user choosing not to proceed with PSU consent during bank selection can click/tap Decline.

This returns the user to where the redirect originated in the TPP's UI.

Change the bank before confirming payment details

Prior to confirming payment for a redirect to the bank for consent authorization, users can change the selected bank, either by clicking Change on the Payment confirmation screen or by entering a full or partial IBAN search string.

Pictured above (click to enlarge), clicking Change returns the user to the Select Your Bank screen to pick a different country and bank within that country, whereas entering a full or partial IBAN presents a bank list of the closest matches, if any.

To enable this feature from the dashboard, go to Settings > Configuration > Web App – General and turn on Enable user to change pre-selected bank on Consent page.

Web App status messages

Error and status reporting from the Web App are consistent with the codes listed in Payment Status. However, in the case of the Token.io Web App, transfer/transaction status includes both the error code and the bank-transmitted message text ("NSF," canceled by user," "Account Closed," etc.). These are included in the callback (see Handling the Token ID/Transfer ID Callback for , Handling the Token ID Callback for , and Handle the Token ID Callback for , respectively).

Invalid bank ID error messages

When the Web App is invoked and a Bank ID is not supported, the following error messages are sent to the TPP:

Error Messages
Message	Explanation
Selected payment scheme: ABC is not supported by XYZ Bank.	The default Bank ID passed does not support the specified payment rail.
Merchant DEF has restricted the permission to access XYZ Bank.	The default Bank ID passed is not configured by the merchant.
Merchant DEF is not set up to connect to XYZ Bank.	The default Bank ID passed is not configured for the merchant from the platform.
Bank ID: XYZ is invalid.	The default Bank ID passed is not supported

The response payload takes the following form:

{

"error": "access_denied",

"message": "Selected payment scheme: ABC is not supported by XYZ Bank.",

"requestId": "rq:44mQvLm38qyagkb7Wwi7p6T8UA9V:5zKtXEAq"

}

Error response fields defined:

error is the server error.
message explains the reason for the error.
requestId is generated and returned with the token payload in response to your token request submission.

Browser back button behaviour during user redirect

If the browser's back button is clicked during authentication and consent after redirect to the bank, the back button's behaviour will depend on the bank flow:

bank-initiated payments, also known as 'one-step' payments – the user is directed to the TPP provided redirect Url.
TPP-initiated payments, also known as 'two-step' 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.

See Customer Cancellation During Bank Selection for more information.

Support for query parameters

Query parameters are a defined set of parameters attached to the end of a URL. They are extensions of the URL that are used to help define specific content or actions based on the data being passed. To append query parameters to the end of a URL, a question mark ('? ') is added, followed by the parameter.

A number of query parameters are supported for Web App redirect. These include parameters that improve the UX by eliminating unnecessary or extraneous user selection, as well as authentication and session parameters using direct references to existing and/or stored TPP requests.

Localization parameters

Supported query parameters for localization currently comprise language (lang) and country (country).

You can specify a particular language by passing its alpha-2 language code (lang=country-code) as a query parameter appended to the redirect URI. Here's an example for passing the desired ISO 639-1 language code for German (de).

https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?lang=de

As pictured next, the user can always override the language preselect in the Web App by clicking the language button in the top-right.

Similarly, to specify a desired country, append an ISO alpha-2 country code to the URI using the country parameter (country=country-code). Austria, for example, would be:

https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?country=at

Concatenation

You can concatenate multiple query parameters for the same URL by separating them with an ampersand ('&'). For example:

https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?lang=de&country=at

IBAN validation

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

Supported browsers

Web browser versions supported by Token.io's Dashboard and Web App, respectively, are listed in the table below and color-coded green. Browsers and versions that are not supported are listed with a color code of red. A yellow color code signifies that a browser version is generally compatible with web products and tools within the Token.io ecosystem provided by Token.io. However, the level or degree of compatibility indicated is provisional and may, at some point in the future, require the user to upgrade to a more recent version of the browser software.

Testing and issue resolution considerations are captured in the legend.

Legend
Support Status	Tested by Token.io(Yes/No)	Issue Resolution	Testing Coverage
Supported	Yes	Issues raised will be resolved	Testing on iPhone and Android will not cover every device version
Not Supported	No	Issues raised will not be resolved; user must change/upgrade to supported browser
Compatible	No	For P1/P2 (critical) issues raised, a workaround will be provided. If the issue is not critical, the user will need to change/upgrade browser

Supported Browsers
Device	OS	Browser	Browser Version
Laptop/Desktop	Windows 10	Edge	Latest
		Chrome	Latest GA-ed
		Firefox	Latest GA-ed
		IE 11	Latest GA-ed
		Edge Legacy	Latest GA-ed
		Other	Latest GA-ed
	Windows 8.1	All	Latest GA-ed
	Windows 7	All	Latest GA-ed
	Mac Big Sur Mac Catalina Mac Mojave	Safari	Latest GA-ed
		Chrome	Latest GA-ed
		Firefox	Latest GA-ed
		Other	Latest GA-ed
	Mac High Sierra Mac Sierra	Safari	Latest GA-ed
		Chrome	Latest GA-ed
		Firefox	Latest GA-ed
		Other	Latest GA-ed
iPhone 7 and above	iOS 13 and above	Safari	Latest GA-ed
		Chrome	Latest GA-ed
		Firefox	Latest GA-ed
		Other	Latest GA-ed
iPhone 6	iOS 13 and above	Safari	Latest GA-ed
		Chrome	Latest GA-ed
		Firefox	Latest GA-ed
iPhone older than iPhone 6	iOS 13 and above	All	Latest GA-ed
Android Smartphones (Samsung Galaxy, Huawei, Xianomi, et al)	Android 6.0 and above	Chrome	Latest GA-ed
	Android versions older than 6.0	Chrome	Latest GA-ed
iPad	iOS 13 and above	Chrome	Latest GA-ed
	iOS 13 and above	Safari	Latest GA-ed
	older than iOS 13	Chrome	Latest GA-ed
	older than iOS 13	Safari	Latest GA-ed
Tablets – Samsung, Huawei, Amazon	Android versions older than 6.0	Chrome	Latest GA-ed
Tablets – Samsung, Huawei, Amazon	Android versions older than 6.0	Chrome	Latest GA-ed

For App-to-App flows on mobile devices, the browser will always open Token.io webviews in the device's native browser (i.e., the OEM's proprietary browser). For instance, on iOS devices, the browser opened by the bank will always be Safari.

When the user's device settings are set to a different browser other than the device's native browser, the Token.io webview will detect this and interrupt the user's authorization and consent flow to display the following prompt, telling the user to copy-paste the URL provided into the address bar of the browser with which they began the authorization flow in order to correctly return to the TPP application.

See Implementing the App-to-App Redirect Feature for more on this and additional details concerning app-to-app integration.