Integrate with Token.io's modal SDK

Token.io's modal SDK is designed to seamlessly integrate our A2A functionality into your website by providing a convenient modal experience. Incorporating a Pay by Bank button into your checkout experience enables you to initialize the modal when a user clicks on it.

Here we outline the steps for you to integrate the Pay by Bank button into your website.

1. Installation

Add the following script in your project to load the 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 = new window.TokenApp({ env: 'sandbox' });

3. Create the button

Create a button that will trigger the modal:

<button className="PayButton" onClick={handleOnClick}>
<span>{'Pay By Bank'}</span>
</button>

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 modal with a token request URL or payment request id

On button click, initiate the modal:

handleOnClick =  () => {
     appModal = appController.initApp();
     {
         { data: tokenRequestUrl } = await fetchTokenRequestId();
        appModal.navigateToUrl(tokenRequestUrl);
    }
     (error) {   }}
        handleError(error);
    }
};

• const appModal = appController.initApp(); initializes the app within a modal and displays a loading screen 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:
      appModal.navigateToUrl(tokenRequestUrl);
  in order to load the session data inside the app modal.

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