Implementing the App-to-App Redirect Feature

Universal/app links in the Token.io Web App redirect the user directly to the bank/ASPSP app (or website fallback) for authentication and authorization, then back to your app, returning the authorized response payload appropriate to the token request. Because universal links are standard HTTP or HTTPS links, one URL works for both the bank's website and the bank app. If the bank app is not installed on the user's device, the system opens the URL in the device's default browser, where the redirect is handled by the website. For users that have the bank app installed on their device, the system checks a file stored on the bank's webserver to verify that it allows the Token.io Web App to open URLs on its behalf. For TPPs, the advantage here is having the Token.io Web App do all the heavy lifting.

However, there are still a couple of important rules you'll need to follow:

  1. Always open the Token.io Web App in a browser. Do not use an embedded in-app webview like WKWebview for the following reasons:
    • Token.io security policy requires the Token.io webview to open in the same browser each time.
    • On redirect back to the TPP, the bank/ASPSP will always open the Token.io Web App in the device's default browser (i.e., on iOS devices, the browser will always be Safari).

    Caution: This means that, if you launch the Token Web App in an embedded webview, then, on redirect back from the bank, the Web App will detect a different browser that the one it expects and fail the checkout whilst trapping the error and displaying the following screen (click to enlarge).

    Then, as the Web App UI indicates, the user will need to copy the URL and paste it into the browser from which checkout originated. But, if that's an embedded webview, the user will have no way to complete checkout without an address box for input. You should therefore avoid using an embedded webview to open the Token.io Web App.

  2. For iOS only, append the following parameters when opening the Token.io Web App link:
    1. "use-bank-redirection-screen=true" – controls if the optional Screen 1 (bank-redirection screen) is displayed.
    2. "source=app" – indicates that the checkout flow initiates from the TPP's mobile app and supports Universal Links. Setting this parameter displays the optional Screen 1 in compliance with iOS Universal Link policy. If not included, the Token.io Web App will redirect the user back to the TPP's web site, rather than the TPP mobile app.

On redirect back to the TPP, Token.io provides a requestId in its response. You can then use the requestId to check on whether the final result of a token request is available by calling GET /token-requests/{tokenRequestId}/result (see Fetching the Status of a Token Request Result).