Hosted Pages (HP) integration

Token.io offers the Redirect integration HP option for Data (AIS).

The Redirect integration directs the user from your website to open Token.io's HP in a new tab, using a redirect URL. Redirect integration for Data (AIS) is available for HP v1.

Redirect integration (HP v1)

The Redirect integration directs the user from your website to open Token.io's HP in a new tab, using a redirect URL. Redirect integration for Data (AIS) is available for HP v1.

This section describes the integration where the TPP uses Token.io's HP for some of the steps in the user journey. Authentication methods will be handled entirely by the HP.

The image below shows a simplified swim lane diagram of the integration flow.

Details of the steps within the integration flow are shown below.

1. TPP initiates AIS request

The TPP initiates the AIS request with Token.io using the POST /token-requests call. Token.io responds by acknowledging the details of the request.

a. TPP -> Token.io - The TPP creates the AIS request using the POST /token-requests call.

b. Token.io -> TPP - Token.io generates a response to the AIS request.

2. TPP redirects user to Token.io

The TPP redirects the user to the Token.io HP.

a. TPP -> Token.io - The TPP redirects the user to the Token.io HP at:
https://{{base-url}}/app/request-token/{tokenRequestId}.

See Hosted Pages for details on how to construct the redirect URL.

3. User selects bank

The user selects the bank from the Token.io HP.

a. Token.io -> User - Token.io displays the bank selection screen.

You can limit the countries available for selection in the HP by sending the countries parameter in the the POST /token-requests request. If you limit it to just one, it effectively becomes pre-populated.

You can also pre-populate the country in the HP by including the country code in the HP URL.

See Token.io Hosted Pages v1 for more information.

b. User -> Token.io - The user selects the bank.

Token.io collects consent from the user.

a. User -> Token.io - The user provides consent to Token.io.

If the selected bank uses the redirect flow, clicking on Accept will initiate the redirect to the user’s bank at this point.

5. User completes authorization with bank

The user completes authorization with the bank using the appropriate method; redirect, embedded or decoupled.

a. Bank -> User - The bank displays the authorization page to the user.

b. User -> Bank - The user authorizes the AIS request with the bank.

6. TPP obtains access token

The TPP calls GET /token-requests/{tokenRequestId}/result to obtain the access token.

a. TPP -> Token.io - The TPP calls Token.io using GET /token-requests/{tokenRequestId}/result to obtain the access token.

b. Token.io -> TPP - Token.io responds with details of the access token.

7. TPP obtains account IDs

The TPP calls GET /tokens/{tokenId} using the access token ID obtained in the previous step. The response contains the account IDs used for calls to the endpoints in the next step.

a. TPP -> Token.io - The TPP calls Token.io using GET /tokens/{tokenId} to obtain the account IDs to use to retrieve the AIS data.

b. Token.io -> TPP - Token.io responds with details of the account IDs.

8. TPP receives AIS data

Depending on your use case, you can use one or more of the Accounts endpoints to retrieve relevant account information.

See HTTP errors for information on HTTP error status codes.

Callback response for Hosted Pages integration

The following is an example callback response for AIS with Hosted Pages v1:

Example callback for AIS v1 HP v1 redirect authentication flow



    "request-id": "rq:bshuWJZ4JRuYPrrn5pvu5ALpRuA:5zKtXEAq",

    "token-id": "tt:7C5z19gjMir3pYHZnS39bXC3pJHP9vaEsiPHLNGZXWiG:3VMczyq7r7b6HwC"

    "signature": {

        "memberId": "m:2MsNiHgYNphSz2j9GbE83Yqr7iod:5zKtXEAq",

        "keyId": "1x7df4vuFUHYQCa7",

        "signature": "s4INmvY_d5GpYD21Vvma76mz5MpM___B2svn6RSS7fC5p1-WhNJjYQziD6wlw8Ab0bS-gvvGwaP8vYB2JGywBg"

    }

    "status": "PROCESSED",

    "state": "%7B%22innerState%22%3A%7B%22a%22%3A1%7D%7D"

The request-id is always returned in the callback for AIS.

token-id is not always returned, for example, if there is an error and the token isn't created, there will be no token-id, as shown below:

Example callback for AIS v1 HP v1 redirect authentication flow with error



    "error": "EXCEPTION_INITIATE_BANK_AUTH",

    "message": "INTERNAL: InitiateBankAuth failed for TokenRequest: rq:7oJUVi8s129JcYdzK1uGo2PTw81:5zKtXEAq due to INVALID_ARGUMENT: Expected username or OTP credential.",

    "request-id": "rq:7oJUVi8s129JcYdzK1uGo2PTw81:5zKtXEAq"

For Hosted Pages v1, the state is not returned, except in specific cases where this is flagged as a feature.

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