# 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:


```json
<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):


```json
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.


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

### 4.  Configure the SDK app controller

Within your **React** component or vanilla JavaScript:


```json
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](./hosted-pages-v2-callback-for-hosted-pages).

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

Initiate the iframe:


```json
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:


```json
appController.cleanUp();
```

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