> ## Documentation Index
> Fetch the complete documentation index at: https://developer.transactbridge.com/llms.txt
> Use this file to discover all available pages before exploring further.
# v1.1
Advanced iframe integration with event subscriptions.
## Setup your development
To manually load **Checkout.js**, simply add the script link to the **\** of any page.
```js theme={null}
```
## Overview
**TBIframe v1.1** introduces an event-driven architecture using `.on()` and `.off()`.
This version supports:
* Multiple event listeners
* KYC lifecycle tracking
* Popup & redirection handling
* Better iframe lifecycle control
***
## Required HTML Elements
Make sure to add the following elements to your page:
> **Note:** Root container must have the ID `tb_root`.
```html theme={null}
```
***
## Quick Start Example
```js theme={null}
/**
* Custom Functions
* */
function onSessionUpdate(data: object) {...};
function onTransactionUpdate(data: object) {...};
function onKycStatusUpdate(data: object) {...};
function onClose(data: object) {...};
const tbIframe = new TBIframe();
tbIframe.init("https://www.example.com/session/abc123",onSessionUpdate, onClose, onTransactionUpdate, {
frameStyles: {
minWidth: '340px',
height: '600px',
border: 'none'
},
mode: 'sandbox', // 'sandbox' | 'production'
redirectionTarget: '_blank' | '_self'
});
// You can also subscribe the events like this
tbIframe.on('sessionUpdate', onSessionUpdate);
tbIframe.on('transactionUpdate', onTransactionUpdate);
tbIframe.on('close', onClose);
// Kyc events can only be subscribed like this
tbIframe.on('kycStatusUpdate', onKycStatusUpdate);
```
### ⚠️ Important Note on Mandatory Handlers
Currently, the following handlers are mandatory parameters when calling `init()`:
* `onSessionUpdate`
* `onClose`
* `onTransactionUpdate`
```js theme={null}
tbIframe.init(
payUrl,
onSessionUpdate, // Required
onClose, // Required
onTransactionUpdate, // Required
options,
);
```
These handlers must be provided during initialization, even if you also
register them using the .on() method.
### 🔄 Upcoming Change (Future Versions)
In a future release, these handlers will no longer be required in the `init()` method.
Instead, all event subscriptions will be handled exclusively using the event-driven pattern:
```js theme={null}
tbIframe.on("sessionUpdate", onSessionUpdate);
tbIframe.on("transactionUpdate", onTransactionUpdate);
tbIframe.on("close", onClose);
```
### 1. Create Instance ( Constructor ).
```js theme={null}
const tbIframe = new TBIframe();
```
***
### 2. Initialization & Its Behavior
The `init()` method can only be executed once per `TBIframe` instance.
If you need to load a new session, create a new instance.
```js theme={null}
/**
* Custom Functions
* */
function onSessionUpdate(data: object) {...};
function onClose(data: object) {...};
function onTransactionUpdate(data: object) {...};
const payUrl = "https://www.example.com/session/abc123"; // Replace with your session URL
const options = {
frameStyles: {
minWidth: '340px',
height: '600px',
border: 'none'
},
mode: 'sandbox', // 'sandbox' | 'production'
redirectionTarget: '_blank' // opens bank page on new page
};
tbIframe.init(payUrl, onSessionUpdate, onClose, onTransactionUpdate, options);
```
#### Parameters for `init(...)`:
| Name | Type | Description |
| --------------------- | ------------------------ | ------------------------------------------------------------------- |
| `url` | `string` | The URL of the payment session. |
| `onSessionUpdate` | `(data: object) => void` | Triggered when payment session updates (e.g., success, failure). |
| `onClose` | `(data: object) => void` | Triggered when iframe is closed manually or automatically. |
| `onTransactionUpdate` | `(data: object) => void` | Triggered when a transaction is initiated. Returns transaction IDs. |
| `options` | `TBIframeOptions` | Object to customize iframe style and behavior. |
#### Options (`TBIframeOptions`)
| Property | Type | Description |
| ------------------- | ------------------------------ | ---------------------------------- |
| `frameStyles` | `Partial` | CSS styles to apply to the iframe. |
| `mode` | `sandbox or production` | Application Environment |
| `redirectionTarget` | `_self \| _blank` | Target for bank page. |
***
### 3. Register Handlers using `on`
```js theme={null}
tbIframe.on('sessionUpdate', (data: object) => {
console.log(data);
// Do something with the data.
});
```
**Supported Events**
| Event | Description |
| ------------------- | ---------------------- |
| `sessionUpdate` | Payment status updates |
| `transactionUpdate` | Transaction creation |
| `close` | Iframe closed |
| `kycStatusUpdate` | KYC lifecycle updates |
#### Parameters for `on(...)`:
| Parameter | Type | Description |
| ------------- | ---------------------------------------------------------------------- | ----------------------------------------- |
| `handlerName` | `sessionUpdate` \| `kycStatusUpdate` \| `close` \| `transactionUpdate` | Handler Name |
| `callbackFn` | `function` | Custom function to set with handler name. |
***
### 4. Remove Handlers using `off`
```js theme={null}
tbIframe.off("sessionUpdate");
```
#### Parameters for `off(...)`:
| Parameter | Type | Description |
| ------------- | ---------------------------------------------------------------------- | ------------ |
| `handlerName` | `sessionUpdate` \| `kycStatusUpdate` \| `close` \| `transactionUpdate` | Handler Name |
***
### `close()`
Closes the iframe manually and triggers the `onClose` callback (if set).
```js theme={null}
function closeIframe() {
tbIframe.close();
}
document.getElementById("close_button").addEventListener("click", closeIframe);
```
***
## Handler Reference
> Functions that can be registered using the `on` method.
| Name | Type | Description |
| ------------------- | ------------------------ | ------------------------------------------------------------------- |
| `sessionUpdate` | `(data: object) => void` | Triggered when payment session updates (e.g., success, failure). |
| `close` | `(data: object) => void` | Triggered when iframe is closed manually or automatically. |
| `transactionUpdate` | `(data: object) => void` | Triggered when a transaction is initiated. Returns transaction IDs. |
| `kycStatusUpdate` | `(data: object) => void` | Triggered during the life cycle of KYC. Returns KYC Status. |
***
## Example Output
```txt theme={null}
Session Data: {
tbId: "abc123",
status: "CLOSED",
type: "billingSession",
supplierRefId: "ref__001"
}
Transaction Data: {
txnIds: ["txn_0011223344"],
checkoutData: {
payMethod: "UPI"
}
}
Iframe closed: {
tbId: "abc123",
status: "CLOSED",
type: "billingSession",
supplierRefId: "ref__001"
}
KYC Data: {
kycStatus: "PENDING" | "IN_PROGRESS" | "REVIEW_REQUIRED" | "DECLINED" | "VERIFIED" | "EXPIRED"
}
```
***
## Notes
* The `tb_root` container must be present in your DOM for the iframe to be injected.
* You must provide a valid session URL for payments to work.
***