Skip to content
Get started
/
Hosted Pages (HP)
/
/
Integrate Token.io's Host...
Last updated

Integrate Token.io's Hosted Pages v2 using an iframe

Here we outline the steps for you to integrate Token.io's Hosted Pages v2 into your website using an iframe.

1. Installation

Add the following script tag in your website's <head> section to load the HP v2 SDK:

<script src="https://app-sdk.token.io/2.0.4/token.min.js">

2. Initialize the SDK

To start integrating, initialize the SDK using the following code in your React component (or equivalent i.e., vanilla JavaScript):

appSdk =  window.TokenApp({ env: 'sandbox' });

Set the env to sandbox for testing and production for live environments.

3. Create an iframe container

Create a container element in your HTML where the HP v2 iframe will be embedded.

<div id="tokenWebAppIframe"></div>

4. Configure the SDK app controller

Within your React component or vanilla JavaScript:

appController = appSdk.buildController({
onDone,
onError,
});

onError callback

  • The onError callback is triggered for all known errors during the HP v2 journey with error parameters. The onError callback implies that the transaction has been unsuccessful.

  • The onError callback is invoked when a user clicks the Cancel (x) button in the Hosted Pages and the optional dialogue screen to capture the user’s reason for the cancellation is enabled. If the user clicks “Yes, I am sure” then onError is called and the user is returned to the merchant screen. This is also true if the user cancels the payment on the bank's page after they have been redirected to the bank.

  • The onError callback is also triggered in the event a network error occurs on the user’s side (in the browser), or if Token.io's API is unreachable due to network issues. However, this does not affect the actual status of the session, provided the network error occurs before a transaction request is sent to the server. In these cases, a new session can be initiated.

onDone callback

  • The onDone callback is triggered for successful payment completions as well as for unknown errors. It includes the request or payment ID needed to fetch the actual status of the token-request, transfer, or payment.

  • Please note that triggering the onDone callback does not constitute a successful payment. Payment statuses should still be retrieved from the API or webhook.

For details of the parameters returned with the onError and onDone callbacks see Callbacks for Hosted Pages.

5. Load the iframe with a token request URL or payment request id

Initiate the iframe:

webAppIframeEl = window.document.getElementById('tokenWebAppIframe');
 appIframe = appController.initAppIframe({ parentEl: webAppIframeEl })();
     {
         { data: tokenRequestUrl } = await fetchTokenRequestId();
        appIframe.navigateToUrl(tokenRequestUrl);
    }
     (error) {
        handleError(error);
    }

  • webAppIframeEl: This is the HTML element (div) where the iframe will be embedded. Make sure this element exists in your DOM.

  • appController.initAppIframe: Initializes the HP v2 iframe with a loading screen under the specified container (parentEl) until the session is generated. The loading screen ensures a seamless user experience while the session ID (token request ID) is being created.

  • Await the fetchTokenRequestId() API call to the merchant server: This asynchronous operation generates a session ID on the merchant's end using the payment amount and authentication keys. It is recommended to perform authentication calls server-side to avoid exposing sensitive authentication keys.

  • Once the token request URL has been generated, TPPs can call:
       appIframe.navigateToUrl(tokenRequestUrl);
    in order to load the session data inside iframe.

6. Clean up after use

Ensure that the modal is properly cleaned up after the flow is complete or upon failure:

appController.cleanUp();

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

Previous page
Next page