# Environments
Source: https://developer.transactbridge.com/api-reference/environments

Example section for showcasing API endpoints

Sandbox mode secret keys have the prefix **tb\_test\_** and live mode secret keys have the prefix **tb\_live\_**.

## Endpoints

<AccordionGroup>
  <Accordion title="Production" icon="rocket">
    * Production API endpoint	[https://api.transactbridge.com](https://api.transactbridge.com)
    * Production Partner Panel	[https://reseller.transactbridge.com/login](https://reseller.transactbridge.com/login)
    * Production Customer Panel	[https://reseller.transactbridge.com/customer/login](https://reseller.transactbridge.com/customer/login)
  </Accordion>

  <Accordion title="Sandbox" icon="flask">
    * Sandbox API endpoint	[https://sandbox-api.transactbridge.com](https://sandbox-api.transactbridge.com)
    * Sandbox Partner Panel	[https://sandbox.transactbridge.com/login](https://sandbox.transactbridge.com/login)
    * Sandbox Customer Panel	[https://sandbox.transactbridge.com/customer/login](https://sandbox.transactbridge.com/customer/login)
  </Accordion>
</AccordionGroup>

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

We will provide the following credentials to the partner for accessing both APIs and the web panel once the email is provided by the partner. If the partner is creating an account directly on the sandbox environment, the partner would still need to email us so that we can configure the account for UAT purposes.

Partners can use the panel to view all the transactions, subscriptions, sessions, and invoices, create new API keys, add team members, give permission to team members, whitelist server IPs for more security, configure callback URLs, etc.


# Going Live
Source: https://developer.transactbridge.com/api-reference/go-live

Pre-launch integration checklist for going live

Congratulations! on completing the integration with TransactBridge. If the partner's onboarding is complete then we will mail you a newly created a production account for your organization using your email. You can go to [this link](https://reseller.transactbridge.com/forgotPassword) to set your password to use the platform.

Following are some points for you to take a look at so that the customer experience and integration are flawless.

<Steps>
  <Step title="Domain Verification">
    Verify your **root subdomain**, for example netflix.com on the Account Settings page. Once the verification is done we can provide you with subdomain-based redirection URLs. - `OPTIONAL`
  </Step>

  <Step title="Web hooks Setup">
    Please add correct **Callback URLs** in the Account Settings page, so that the customer can be notified promptly. - `MANDATORY`
  </Step>

  <Step title="Checkout theme">
    Please change the **Color Theme** and upload the **Brand Logo** in the Account Settings so that the customer gets the same experience throughout the journey. - `MANDATORY`
  </Step>

  <Step title="Adding Team">
    Do add relevant team members using the **Team Members** page so that other departments of organization can utilize the platform. Each team member can be given different permissions, please assign them accordingly. - `OPTIONAL`
  </Step>

  <Step title="Bank Verification">
    Please add a **bank account** on the User Profile page to which the Partner wants to receive the invoice payables. Please make sure to add the correct details. - `MANDATORY`
  </Step>

  <Step title="Accessing API Credentials">
    The Partner will get the **API credentials** in another email. If the Partner did not receive them, they can go to the API page and send the credentials again. The Partner can also create new APIs from the same page. For added security please whitelist your server IPs. - `OPTIONAL`
  </Step>

  <Step title="Requesting Demo">
    If the Partner wants a **demo** for the operations team to understand the platform, we would be more than happy to guide you through the platform. - `OPTIONAL`
  </Step>
</Steps>

Once the above mandatory action items have been completed from your side, please intimate to this email and we will verify them and enable the platform for production usage.

<Card title="Admin Dashboard" icon="leaf" href="https://reseller.transactbridge.com/login">
  View the OpenAPI specification file
</Card>


# Introduction
Source: https://developer.transactbridge.com/api-reference/introduction

Welcome to the home of our JSON API Documentation

TransactBridge APIs are **REST JSON APIs**. Our API accepts JSON requests and returns JSON responses, and uses standard HTTP response codes, authentication.

You can use our APIs in the sandbox(testing) and production(live) environments. We provide two different API URLs and tokens for **Sandbox** and **Production (live)**.

You can use the API in sandbox mode, which doesn't affect your live data or interact with the banking networks. The API key you use to authenticate the request determines whether the request is in live mode or test mode.

Our API doesn't support bulk updates. You can work on only one object per request.

All the APIs are authenticated and cannot be utilized without sending proper authentication headers.

## Quicklinks

<CardGroup>
  <Card title="API Endpoints" icon="code" href="https://docs.transactbridge.com">
    Check our postman collection with examples and environment variables for easier integration
  </Card>

  <Card title="No Code Integration" icon="code-simple" href="../checkout.js/checkout/overview">
    Use our Checkout.js library to integrate with your website without writing any code
  </Card>

  <Card title="Check Sandbox" icon="screwdriver-wrench" href="https://sandbox.transactbridge.com">
    Test your integration in our sandbox environment
  </Card>

  <Card title="Check Demo Store" icon="stars" href="https://www.transactbridge.com/demo">
    Check our demo store to see how the integration works
  </Card>
</CardGroup>


# Overview
Source: https://developer.transactbridge.com/checkout.js/android-sdk/dropin/overview



The **TransactBridge Android Drop-in SDK** lets you add a complete, secure payment experience to your app with minimal code. It supports card and UPI payments, handles UI, validation, and security, and provides a smooth user experience.

## Integration Methods

You can integrate the SDK in three ways:

* **Direct AAR file:** Build or download the AAR and add it to your app's `libs/` directory.
* **Maven Local:** Publish the SDK to your local Maven repository and add it as a dependency.
* **Maven Central:** (Coming soon) Add the SDK as a dependency from Maven Central.

See [Quick Start](/checkout.js/android-sdk/dropin/quickstart) for step-by-step instructions for each method.

## What does the Drop-in SDK provide?

The Drop-in SDK offers:

* Pre-built payment sheet (UPI, Terms & Conditions)
* PCI-compliant, secure payment handling
* UPI app listing and deep linking
* Customizable theming
* Device and network security checks
* Simple callback-based integration

## How the Drop-in SDK Works

1. Add the SDK to your project (AAR or Maven)
2. Initialize the SDK with your publishable key and endpoints
3. Add the Terms & Conditions view to your layout
4. Launch the payment sheet with a config object
5. Handle payment results via callback

## Key Concepts

* **PaymentSDK**: Entry point for all payment operations. Handles initialization and launching the payment sheet.
* **PaymentConfig**: Holds all parameters for a payment (session, token, T\&C, etc.).
* **PaymentResultCallback**: Interface for handling payment results (success, failure, cancel).
* **TermsAndConditionsView**: UI component for user consent.
* **UPI App Listing**: Utility to list and launch UPI apps for payment.


# Quick Start
Source: https://developer.transactbridge.com/checkout.js/android-sdk/dropin/quickstart



This guide walks you through integrating the **TransactBridge Drop-in SDK** into your Android app.

# Integration Methods

You can integrate the TransactBridge Android Drop-in SDK in two ways:

## Option 1: Direct AAR File

1. **Download the AAR:**

   * Download dropin.aar file by clicking [here](https://cdn.transactbridge.com/sdk/android/v1.0/dropin.aar)

2. **Add the AAR to your project:**
   * Place `dropin.aar` in your app's `libs/` directory.
   * In your `app/build.gradle`:
     ```groovy theme={null}
     android {
         repositories {
             flatDir { dirs 'libs' }
         }
     }
     dependencies {
         implementation(name: 'dropin', ext: 'aar')
     }
     ```

3. **Declare Required Dependencies:**

   ```gradle theme={null}
   dependencies {
       // ... other dependencies

       // TransactBridge SDK dependencies
       implementation 'com.google.code.gson:gson:2.10.1'
       implementation 'com.android.volley:volley:1.2.1'
       implementation 'com.squareup.okhttp3:okhttp:4.12.0'
       implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'
   }
   ```

   * Sync your project with Gradle.

## Option 2: Maven Central (Coming Soon)

Once available, simply add:

```groovy theme={null}
dependencies {
    implementation 'com.transactbridge:transactbridge-sdk:1.0' // Use actual version
}
```

# Usage Example

```java theme={null}
import com.transactbridge.sdk.PaymentSDK;
import com.transactbridge.sdk.Environment;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        PaymentSDK.initialize(this, "YOUR_PUBLISH_KEY", Environment.UAT); // Choose PRODUCTION, SANDBOX, or UAT
    }
}
```

For more details on using the SDK, see the [v1.0](/checkout.js/android-sdk/dropin/v1.0) documentation.


# v1.0
Source: https://developer.transactbridge.com/checkout.js/android-sdk/dropin/v1.0



This guide walks you through integrating the **TransactBridge Drop-in SDK** into your Android app using an AAR file.

## 1. Download the AAR

Download dropin.aar file by clicking on the link below

[Download dropin.aar](https://cdn.transactbridge.com/sdk/android/v1.0/dropin.aar)

## 2. Add the AAR to Your Project

1. **Create a `libs` directory:** In your Android project's `app` module, create a new folder named `libs` if it doesn't already exist. The path should be `app/libs/`.
2. **Place the AAR file:** Copy the `dropin.aar` file into the `app/libs/` directory.
3. **Update `build.gradle` (Module: app):**

   ```gradle theme={null}
   repositories {
       flatDir {
           dirs 'libs'
       }
   }
   dependencies {
       implementation fileTree(dir: 'libs', include: ['*.jar'])
       implementation(name: 'dropin', ext: 'aar')
   }
   ```

## 3. Declare Required Dependencies

Our SDK relies on `Gson` for JSON serialization/deserialization, `OkHttp` and `Volley` for network requests. It's crucial to include these as dependencies in your `app/build.gradle` to ensure compatibility and prevent runtime issues. Please use the exact versions specified by the SDK to avoid dependency conflicts.

```gradle theme={null}
dependencies {
    // ... other dependencies

    // TransactBridge SDK dependencies
    implementation 'com.google.code.gson:gson:2.10.1'
    implementation 'com.android.volley:volley:1.2.1'
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'
}
```

## 4. Initialize the SDK

Initialize the SDK in your Application class or main Activity:

```java theme={null}
import com.transactbridge.sdk.PaymentSDK;
import com.transactbridge.sdk.Environment;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        PaymentSDK.initialize(this, "YOUR_PUBLISH_KEY", Environment.UAT); // Choose PRODUCTION, SANDBOX, or UAT
    }
}
```

## 5. Add Terms & Conditions View

In your layout XML:

```xml theme={null}
<com.transactbridge.sdk.view.TermsAndConditionsView
    android:id="@+id/upi_terms_and_conditions"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_marginTop="16dp" />
```

In your Activity or Fragment, obtain the unique ID:

```java theme={null}
TermsAndConditionsView termsAndConditionsView = findViewById(R.id.upi_terms_and_conditions);
String termsId = termsAndConditionsView.getUniqueId();
```

## 6. List Available UPI Apps

```java theme={null}
List<UpiApp> upiApps = PaymentSDK.getUpiApps(this);
if (upiApps.isEmpty()) {
    // Handle case where no UPI apps are found
} else {
    // Display the list of upiApps to the user
}
```

## 7. Generate Billing Session (Backend)

**Important:** The generation of the billing session, including the `billingSessionId` and `token`, involves sensitive API keys (`x-api-key`, `x-signature`) that **must not be exposed in your mobile application**. This process should be handled securely on your backend server. Your mobile application should call your backend, which then communicates with TransactBridge to obtain these details.

Your backend should make an API call to TransactBridge's `/billingSession/v1.0/generateBillingSession` endpoint. The response from this endpoint will contain the `billingSessionId` and `token` which your backend should then securely relay to your mobile application.

## 8. Launch UPI Payment

```java theme={null}
UpiPaymentRequest request = new UpiPaymentRequest(
        currentBillingSessionId,
        currentToken,
        termsId, // Obtained from TermsAndConditionsView.getUniqueId()
        0, // Sequence number (if applicable, otherwise 0)
        selectedUpiApp,
        1000L // Timeout in milliseconds
);

PaymentSDK.payUpi(this, request, new PaymentResultListener() {
    @Override
    public void onSuccess(PaymentResult result) {
        // Payment successful
        Toast.makeText(YourActivity.this, "Payment Success: " + result.getTransactionId(), Toast.LENGTH_LONG).show();
        // Further actions like verifying payment status with your backend
    }

    @Override
    public void onFailure(PaymentResult result) {
        // Payment failed
        String error = result.getError() != null ? result.getError().getMessage() : "Unknown error";
        Toast.makeText(YourActivity.this, "Payment Failed: " + error, Toast.LENGTH_LONG).show();
    }

    @Override
    public void onCancel() {
        // User cancelled the payment
        Toast.makeText(YourActivity.this, "Payment Cancelled", Toast.LENGTH_LONG).show();
    }
});
```

## 9. Handling Payment Results

The `PaymentResultListener` provides callbacks for `onSuccess`, `onFailure`, and `onCancel`. Handle these outcomes appropriately:

* **onSuccess(PaymentResult result):** The payment was successful. You should typically verify this status with your backend before confirming the order or service to the user. The `result` object contains details like `transactionId`.
* **onFailure(PaymentResult result):** The payment failed. The `result` object will contain error details if available. Inform the user and guide them on next steps.
* **onCancel():** The user cancelled the payment flow. Inform the user that the payment was not completed.


# Overview
Source: https://developer.transactbridge.com/checkout.js/android-sdk/web-view/overview



The **TransactBridge Android SDK** allows you to integrate the TransactBridge checkout flow into your native Android application. It provides a simple and secure way for your users to complete transactions using a web-based interface, while providing you with feedback through a set of listeners.

### It Provides

* Secure checkout flow
* Transaction & session event listeners
* External app redirection support
* Chrome Custom Tab integration

### Key Features

* WebView based checkout
* Transaction status callbacks
* UPI / external payment app support
* Automatic redirection handling


# Quick Start
Source: https://developer.transactbridge.com/checkout.js/android-sdk/web-view/quickstart



## 1. Installation

To integrate the TransactBridge SDK into your Android project, add the following dependency to your app's `build.gradle.kts` or `build.gradle` file.

```java theme={null}
// build.gradle.kts
implementation("com.transactbridge:sdk:1.0.0");
```

```java theme={null}
// build.gradle
implementation 'com.transactbridge:sdk:1.0.0'
```

## 2. Dependencies

The SDK relies on common AndroidX libraries. Ensure your app does not have conflicting versions.

* `androidx.appcompat:appcompat`
* `androidx.webkit:webkit`
* `com.google.code.gson:gson`
* `androidx.browser:browser`


# v1.0
Source: https://developer.transactbridge.com/checkout.js/android-sdk/web-view/v1.0



## 1. Initialization

Initialize the SDK in your Application's `onCreate` method. This only needs to be done once when your application starts. The SDK uses a singleton pattern for all interactions.

```java theme={null}
import com.transactbridge.sdk.TransactBridge;
import android.app.Application;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // Initialize the TransactBridge singleton
        TransactBridge.getInstance().initialize(this, TransactBridge.LogLevel.ERROR); // Or LogLevel.VERBOSE, LogLevel.NONE
    }
}
```

## 2. Configuration

You can configure the SDK instance after initialization.

### 2.1. Log Level

The SDK provides three log levels:

* `TransactBridge.LogLevel.VERBOSE`: Logs all messages.
* `TransactBridge.LogLevel.ERROR`: Logs only error messages. This is the default.
* `TransactBridge.LogLevel.NONE`: Disables all logging.

```java theme={null}
// Set the log level at any time
TransactBridge.getInstance().setLogLevel(TransactBridge.LogLevel.VERBOSE);
```

### 2.2. Auto Close

By default, the checkout view will close automatically when the flow is complete. You can disable this behavior globally:

```java theme={null}
TransactBridge.getInstance().setAutoClose(false);
```

You can also override this setting for a specific session using the `Builder`.

## 3. Usage

To start a checkout session, create a `TransactBridge.Builder` to configure listeners and session-specific settings. Then, call the `open()` method on the `TransactBridge` singleton instance.

```java theme={null}
import com.transactbridge.sdk.TransactBridge;
import com.transactbridge.sdk.listeners.*;
import android.os.Bundle;

// ... inside your Activity or Fragment

TransactBridge.Builder builder = new TransactBridge.Builder()
    .setTransactionListener(transactionData -> {
        // Handle transaction data
    })
    .setSessionListener(sessionData -> {
        // Handle session data
    })
    .setCloseListener(() -> {
        // Handle close event
    })
    .setErrorListener((errorCode, errorMessage, extras) -> {
        // Handle error
    })
    .setAutoClose(true); // Optional: Override global setting for this session

// Start the checkout session
TransactBridge.getInstance().open(this, "YOUR_CHECKOUT_URL", builder);
```

## 4. Event Handling

The SDK uses listeners to notify your application of events for a specific session.

### 4.1. TransactionListener

* `onTxnData(TransactionData transactionData)`: Called with transaction details.

**TransactionData**

| Method              | Description                                      |
| ------------------- | ------------------------------------------------ |
| `getTxnIds()`       | Returns a `List<String>` of transaction IDs.     |
| `getCheckoutData()` | Returns `CheckoutData` with payment method info. |

### 4.2. SessionListener

* `onSessionData(SessionData sessionData)`: Called for session-related events.

**SessionData**

| Method        | Description                                      |
| ------------- | ------------------------------------------------ |
| `getStatus()` | Returns the status of the session as a `String`. |
| `getTbId()`   | Returns the TransactBridge ID as a `String`.     |
| `getType()`   | Returns the type of session event as a `String`. |

### 4.3. CloseListener

* `onClose()`: Called when the sdk is closed.

### 4.4. TransactBridgeErrorListener

* `onError(int errorCode, String message, @Nullable Bundle extras)`: Called when an error occurs.

The `errorCode` provides a specific reason for the error.

| Error Code                   | Value | Description                                                                                                     |
| ---------------------------- | ----- | --------------------------------------------------------------------------------------------------------------- |
| `ERROR_INTENT_LAUNCH_FAILED` | 1001  | Failed to launch an external application, such as a UPI or other payment app.                                   |
| `ERROR_WEBVIEW_LOAD_FAILED`  | 1002  | The WebView failed to load the checkout page due to a network error, SSL issue, or other configuration problem. |
| `ERROR_INVALID_URL`          | 1003  | The URL provided when opening the checkout session was invalid.                                                 |

### 4.5. Advanced Event Handling

The SDK handles several types of events automatically to provide a smooth user experience.

* **URL Redirection**: When a user action in the checkout flow needs to navigate to an external webpage, the SDK automatically opens it in a secure Chrome Custom Tab. This keeps the user within the context of your app while providing a full browser experience.
* **Intent Redirection**: For payment methods that require invoking another app (like a UPI payment app), the SDK will automatically fire the necessary Android Intent to switch to that app.
* **Invoice Downloads**: If the checkout process provides an invoice for download, the SDK will handle the download intent to allow the user to save the invoice.

### 4.6. Deep Link Configuration

The SDK has built-in support for handling deep links. If your app's Activity that integrates the TransactBridge SDK uses a `launchMode` other than `standard` (e.g., `singleTop`, `singleTask`, or `singleInstance`), you must forward deep link intents to the SDK.

In your Activity, override the `onNewIntent` method and pass the `Intent` to the `TransactBridge.handleDeepLink()` method:

```java theme={null}
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    TransactBridge.handleDeepLink(intent);
}
```

## 5. API Reference

### TransactBridge Singleton

| Method                                          | Description                                                                                                                                                                                                                                                       |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getInstance()`                                 | Returns the singleton instance of the SDK.                                                                                                                                                                                                                        |
| `initialize(Context, LogLevel)`                 | Initializes the SDK. Should be called once.                                                                                                                                                                                                                       |
| `setLogLevel(LogLevel)`                         | Sets the log level for the SDK.                                                                                                                                                                                                                                   |
| `setAutoClose(boolean)`                         | Enables or disables automatic closing globally.                                                                                                                                                                                                                   |
| `open(Context, String, TransactBridge.Builder)` | Opens the checkout flow with session-specific listeners and settings.                                                                                                                                                                                             |
| `close()`                                       | Manually closes the `sdk`. (Static method) **Note:** To prevent potential deadlocks, you should not call `TransactBridge.close()` from within the `SessionListener.onSessionData()` callback. The SDK will ignore any `close()` requests made from this callback. |

### TransactBridge.Builder

The builder is used to configure a single checkout session.

| Method                        | Description                                                        |
| ----------------------------- | ------------------------------------------------------------------ |
| `setTransactionListener(...)` | Sets the `TransactionListener` for the session.                    |
| `setSessionListener(...)`     | Sets the `SessionListener` for the session.                        |
| `setCloseListener(...)`       | Sets the `CloseListener` for the session.                          |
| `setErrorListener(...)`       | Sets the `TransactBridgeErrorListener` for the session.            |
| `setAutoClose(boolean)`       | Overrides the global auto-close setting for this specific session. |


# Overview
Source: https://developer.transactbridge.com/checkout.js/checkout/overview

Integrate Payment Links using TransactBridge.

### 🔗 Payment Links (Create Billing Session)

You can generate a unique payment link for a customer using the Billing Session API.
This works similarly to payment link providers like Cashfree, where a secure checkout URL is generated and shared with the customer.

### 🧭 Payment Flow

In this flow, the customer will be redirected first from the partner's website to a domain hosted by Transact Bridge where the customer will enter the requisite information (depending on what compliances) to make payment, and after making payment the customer will be redirected back to the partner's website. The redirection URL will be provided in response to the [Create Session API](https://docs.transactbridge.com/#d4607171-457b-4d24-8277-6d9a79a997dd) requests.

1. Merchant calls Create Billing Session API
2. Transact Bridge returns a checkout URL
3. Merchant shares link with customer
4. Customer completes payment
5. Webhook is triggered
6. Customer is redirected to `returnUrl`

### How to get session url

You can obtain the session url by creating a billing session using the Transact Bridge Sessions API. This API allows you to generate a unique payment session for one-time payments. Refer to the API documentation below for request structure, required parameters, and response details.

**For full flow reference:**

<Card title="One Time Payment API Docs" icon="code" href="https://docs.transactbridge.com/#a393206c-8fae-4f1f-a55f-01b53330ec66">
  View the Postman API Collection
</Card>

### 🚀 Create Payment Link (Billing Session API)

```js theme={null}

POST https://sandbox-api.transactbridge.com/billingSession/v1.0/generateBillingSession

```

### ✅ Required Parameters

| Parameter                      | Type   | Type                                  |
| :----------------------------- | :----- | :------------------------------------ |
| `email`                        | String | Customer email                        |
| `returnUrl`                    | String | Redirect URL after session completion |
| `quoteCurrCode(Currency code)` | String | Currency (USD, EURO, INR, etc)        |
| `items(Product Information)`   | Array  | Product details                       |

### 📦 Sample Request

```json theme={null}
{
  "email": "example@gmail.com",
  "quoteCurrCode": "INR",
  "returnUrl": "https://www.transactbridge.com",(Your website url)
  "userId": "692406f30e7db4832a0a7987",
  "items": [
    {
      "name": "Product name",
      "description": "Product description",
      "amount": 100,
      "quantity": 5,
    }
  ]
}
```


# Cards
Source: https://developer.transactbridge.com/checkout.js/web-sdk/dropin/components/cards



Use the Card Component to collect card information from the customer.

There are four card components as listed below:

### cardNumber

A component to accept card number.

```js theme={null}
const cardNumber = TBDropin.create("tb_cardNumber", {
  placeholder: "Enter card number",
});
```

Returned Value

**cardNumber `Card Number Object`**

```js theme={null}
{
  element: "tb_cardNumber",
  value: {
    brand: null,
    cvvLength: 3
  },
  isValid: false,
  error: null,
  componentUrl: "https://dropin.transactbridge.com/cardNumber"
}
```

| Field         | Type     |
| ------------- | -------- |
| **brand**     | `string` |
| **cvvLength** | `string` |

**Code Snippet for cardNumer component**

```js theme={null}
const TBDropin = window.TBDropin();

await TBDropin.init({
  mode: "sandbox", //  sandbox mode or Production mode
  publishKey: "", // your publish key goes here
  popupConfig: popupOptions,
});
cardComp = TBDropin.create("tb_cardNumber", {
  placeholder: "Enter Card Number",
  styles: inputStyle,
  frameStyle: frameStyle,
  icon: iconConfig,
  fonts,
});
cardComp.mount(`#cardNumber${type.toUpperCase()}`);

cardComp.on("change", (data) => console.log("cardNumber", data));
```

### cardHolder

A component to accept card holder’s name. You can pass values to a component using options cashfree.create(‘componentName’, options).

```js theme={null}
const cardHolder = TBDropin.create("tb_cardHolder", {
  placeholder: "Card holder name",
});
```

**Returned Value**

cardHolder `Card Holder Object`

```js theme={null}
{
  element: "tb_cardHolder",
  value: {
    cardHolder: "Test User"
  },
  isValid: true,
  error: null
}

```

| Field          | Type     |
| -------------- | -------- |
| **cardHolder** | `string` |

**Code Snippet for cardHolder component**

```js theme={null}
const TBDropin = window.TBDropin();

await TBDropin.init({
  mode: "sandbox", //  sandbox mode or Production mode
  publishKey: "", // your publish key goes here
  popupConfig: popupOptions,
});
cardHolderComp = TBDropin.create("tb_cardHolder", {
  placeholder: "Enter Card Holder Name",
  styles: inputStyle,
  frameStyle: frameStyle,
  fonts,
});
cardHolderComp.mount(`#cardHolder${type.toUpperCase()}`);

cardHolderComp.on("change", (data) => console.log("cardHolder", data));
```

### cardExp

A component to accept card expiry. This component does not accept any parameters.

```js theme={null}
const cardExp = TBDropin.create("tb_cardExp");
```

**Returned Value**

cardExp `Card Expirey Object`

```js theme={null}
{
  element: "tb_cardExp",
  value: {
    cardExp: ""
  },
  isValid: false,
  error: {
    message: "INCOMPLETE_EXP",
    code: "INCOMPLETE_EXP"
  },
  componentUrl: "https://dropin.transactbridge.com/cardExp"
}
```

| Field       | Type     |
| ----------- | -------- |
| **cardExp** | `string` |

**Code Snippet for cardHolder component**

```js theme={null}
const TBDropin = window.TBDropin();

await TBDropin.init({
  mode: "sandbox", //  sandbox mode or Production mode
  publishKey: "", // your publish key goes here
  popupConfig: popupOptions,
});
cardCvvComp = TBDropin.create("tb_cardCvv", {
  styles: inputStyle,
  frameStyle: frameStyle,
  fonts,
});
cardCvvComp.mount(`#cardCvv${type.toUpperCase()}`);

cardCvvComp.on("change", (data) => console.log("cardCvv", data));
```

### cardCvv

A component to accept card expiry. This component does not accept any parameters.

```js theme={null}
const cardCvv = TBDropin.create("tb_cardCvv");
```

**Returned Value**

cardCvv `Card CVV Object`

```js theme={null}
{
  element: "tb_cardCvv",
  value: {
    cardCvv: ""
  },
  isValid: false,
  error: {
    message: "INVALID_CVV_LENGTH",
    code: "INVALID_CVV_LENGTH"
  },
  componentUrl: "https://dropin.transactbridge.com/cardCvv"
}
```

| Field       | Type     |
| ----------- | -------- |
| **cardCvv** | `string` |

**Code Snippet for cardHolder component**

```js theme={null}
const TBDropin = window.TBDropin();

await TBDropin.init({
  mode: "sandbox", //  sandbox mode or Production mode
  publishKey: "", // your publish key goes here
  popupConfig: popupOptions,
});
cardExpComp = TBDropin.create("tb_cardExp", {
  styles: inputStyle,
  frameStyle: frameStyle,
  fonts,
});
cardExpComp.mount(`#cardExp${type.toUpperCase()}`);

cardExpComp.on("change", (data) => console.log("cardExp", data));
```

**Next Steps**

* **A Customize component styles**
* **Add multiple payment methods using tabs**
* **Handle payment confirmation on backend**
* **Set up webhooks for payment status**

**Need Help?**

Explore the following sections for more details:

* <a href="/checkout.js/web-sdk/dropin/overview">**Dropin Overview**</a>
* <a href="/checkout.js/web-sdk/dropin/quickstart">**Quickstart**</a>
* <a href="/checkout.js/web-sdk/dropin/customize-your-sdk">**Customization**</a>

  If you need assistance, our support team is here to help 🚀


# Compliance Check
Source: https://developer.transactbridge.com/checkout.js/web-sdk/dropin/components/compliance-checks



The Compliance Check is a secure iframe-based component that is displayed automatically whenever additional customer information is required before initiating a payment.

Merchants do not need to manually create, mount, or manage this component.

The SDK detects whether compliance is required and handles the complete flow automatically.

***

## How Compliance Works

When the merchant calls `TBDropin.pay()`:

1. The SDK validates the payment components.
2. The SDK decodes the provided Session Token.
3. If compliance is not required, the payment flow continues immediately.
4. If compliance is required, the SDK automatically opens a secure Compliance Checks popup.

***

## How Compliance Requirements are Determined

The SDK derives the compliance configuration by decoding the **Session Token** provided to `TBDropin.pay()`.

Based on the decoded configuration, the SDK determines which compliance fields should be displayed.

### Field Availability

* **Customer Name**
* **Email**
* **Mobile Number**
* **PAN**
* **Mobile OTP Verification**

| Field                       | Display Condition                                                                                                |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Customer Name**           | Displayed when **Customer Name Mandatory** is enabled in the compliance configuration.                           |
| **Email**                   | Displayed when its configured compliance conditions are met, such as **Cart Value** and other configured limits. |
| **Mobile Number**           | Displayed when its configured compliance conditions are met, such as **Cart Value** and other configured limits. |
| **PAN**                     | Displayed when its configured compliance conditions are met, such as **Cart Value** and other configured limits. |
| **Mobile OTP Verification** | Displayed only when **Mobile OTP Verification** is enabled in the compliance configuration.                      |

The merchant does not need to configure or render these fields manually. The SDK automatically evaluates the configuration and displays only the required fields.

***

## Automatic Flow

1. Merchant calls `pay()`.
2. SDK validates payment components.
3. SDK decodes the Session Token.
4. SDK determines whether compliance is required.
5. Compliance popup opens automatically.
6. Customer submits the required information.
7. SDK resumes the payment automatically.
8. Payment Status popup is shown.

***

## Security

The Compliance Form follows the same security model as the payment components.

* Rendered inside a secure iframe.
* Merchant never receives raw compliance data.
* Data is encrypted before being sent to the SDK.

***

## Merchant Responsibilities

The merchant only needs to provide:

```js theme={null}
await TBDropin.pay({
  billingSessionId,
  sessionToken,
  payMethod,
});
```

The SDK automatically detects, displays, submits, and manages the Compliance workflow.

***

## Notes

* The Compliance Form appears only when required.
* The popup closes automatically after successful submission.
* If the customer closes the Compliance popup, the payment is cancelled.
* The SDK reuses previously submitted compliance data only for the same payment session.


# Overview
Source: https://developer.transactbridge.com/checkout.js/web-sdk/dropin/components/overview



Learn about the components which are available with Transact bridge.

The **TB Drop-in SDK** provides small, isolated iframe-based payment components such as:

* <a href="/checkout.js/web-sdk/dropin/components/upi#upi-intent">UPI Intent</a>
* <a href="/checkout.js/web-sdk/dropin/components/upi#upi-qr">UPI QR</a>
* <a href="/checkout.js/web-sdk/dropin/components/cards#cardnumber">
    Card Number
  </a>
* <a href="/checkout.js/web-sdk/dropin/components/cards#cardholder">
    Card Holder Name
  </a>
* <a href="/checkout.js/web-sdk/dropin/components/cards#cardexp">Card Expiry</a>
* <a href="/checkout.js/web-sdk/dropin/components/cards#cardcvv">Card CVV</a>
* <a href="/checkout.js/web-sdk/dropin/customize-your-sdk#5-popup-customization-payment-flow">
    Payment status popup (success, failure, processing)
  </a>
* <a href="/checkout.js/web-sdk/dropin/components/compliance-checks">Compliance Checks (rendered only when required)</a>

Each atom runs inside a secure sandboxed iframe and communicates with the parent page using a message-based architecture. The parent page interacts with all atoms using the `TBDropin` SDK.

## Methods

### 1. Mount component

A component can be mounted in DOM container

```js theme={null}
component.mount(querySelector);
```

**Example**

```js theme={null}
component.mount("#componentContainer");
```

### 2. Unmount component

To unmount a component from DOM container. Use component.mount to mount again

```js theme={null}
component.unmount();
```

### 3. Get component data

To get the data and state of a component

```js theme={null}
let data = component.data();
```

#### Return

```js theme={null}
{
  element: string,
  value: object,
  error: object | null,
  isValid: boolean,
  componentUrl: string
}

```

Fields Explained

| Name             | Description                                                                       | Default     |
| ---------------- | --------------------------------------------------------------------------------- | ----------- |
| **element**      | Unique identifier / type of the component (e.g. `tb_cardNumber`, `tb_upiCollect`) | `undefined` |
| **value**        | Current value of the component. Shape depends on component type                   | `{}`        |
| **error**        | Error object returned by the component, if any                                    | `null`      |
| **isValid**      | Indicates whether the component input is valid                                    | `false`     |
| **componentUrl** | URL of the iframe source used to render the component                             | `undefined` |

### 4. Clear component

Trigger clear on component to empty it. Can only be applied if kind of the component is input

```js theme={null}
Syntax: component.clear();
```

### Events

You can register a callback function to various events that occur with a component. The basic syntax is `component.on(eventName, callBackFunction)`

#### ready

Triggers when a component is ready for user interaction

```js theme={null}
component.on("ready", function (data) {
  //data is same as component.data()
});
```

#### change

Triggers on component kind input whenever change happens for the value

```js theme={null}
component.on("change", function (data) {
  //data is same as component.data()
});
```

#### click

Triggers on component kind button when clicked

```js theme={null}
component.on("click", function (data) {
  //data is same as component.data()
});
```

#### close

Triggered when the payment status screen is closed after the transaction finishes.

```js theme={null}
tbInstance.on("close", function (data) {
  //data is same as component.data()
});
```


# Terms and conditions
Source: https://developer.transactbridge.com/checkout.js/web-sdk/dropin/components/terms-and-conditions



Use the TNC component to display Terms & Conditions and capture user consent before initiating payment.

The **TNC Component** allows merchants to display **Terms & Conditions** and obtain customer consent before starting a payment.

It is a **non-payable UI component** that integrates seamlessly with other payment components like Card and UPI.

### tb\_tnc

A component used to render Terms & Conditions text, an acceptance checkbox, and a configurable **Pay button label**.

```js theme={null}
const tnc = TBDropin.create("tb_tnc", {
  buttonText: "Pay",
  styles: {
    fontFamily: fontRoboto,
    fontSize: "12px",
    color: "gray",
  },

  checkboxStyle: {
    WebkitAppearance: 'none',
    MozAppearance: 'none',
    appearance: 'none',
    minWidth: '20px',
    height: '20px',
    borderRadius: '4px',
    accentColor: 'red',
    border: '1px solid red',
    overflow: 'hidden',
    [':checked']: {
      ['::before']: {
        content: '"✓"',
        display: 'block',
        textAlign: 'center',
        color: 'blue',
        backgroundColor: 'red',
        fontSize: '16px',
      },
    },
  },

  link: {
    color: "blue",
    ":hover": {
      color: "red",
    },
  },
  fonts,
});

tnc.mount("#tnc");
```

### Checkbox

The TNC component includes an acceptance checkbox that allows the customer to provide consent to the Terms & Conditions.

The checkbox can be customized using `checkboxStyle`.

By default, the checkbox is displayed.

***

### Returned Value

`tb_tnc` returns a TNC Component Object.

```js theme={null}
{
  element: "tb_tnc",
  value: {
    accepted: true
  },
  isValid: true,
  error: null,
  componentUrl: "https://dropin.transactbridge.com/tnc"
}
```

### TNC Properties

| Field        | Type      | Description                                                    |
| ------------ | --------- | -------------------------------------------------------------- |
| **accepted** | `boolean` | Indicates whether the user has accepted the Terms & Conditions |

<Note>
  Ensure that you initialize the SDK with a valid **Publishable Key**. If the
  publishable key is invalid or incorrect, the T\&C component will return
  `accepted: false` and `isValid: false`.
</Note>


# UPI
Source: https://developer.transactbridge.com/checkout.js/web-sdk/dropin/components/upi



Use the UPI Component to collect UPI information from the customer.

### UPI Intent

A component that allows customers to pay using UPI Intent, which opens a UPI app (such as Google Pay, PhonePe, Paytm, etc.) on the user's device.

<Note>
  UPI Intent works only on mobile devices, since it relies on installed UPI apps
  to complete the payment.
</Note>

```js theme={null}
const upiIntent = TBDropin.create("tb_upiIntent", {
  value: {
    upiAppName: upiApp, // GPAY, PHONEPE etc..
  },
});
```

**Returned Value**

**upiIntent** `UPI Intent Object`

```js theme={null}
{
 element: "tb_upiIntent",
 value: {
   channel: "INTENT"
   upiAppName: upiApp, // GPAY, PHONEPE etc..
 },
 isValid: true,
 ready: false
}
```

| Field          | Type     |
| -------------- | -------- |
| **channel**    | `string` |
| **upiAppName** | `string` |

**Code Snippet for upiIntent component**

```js theme={null}
const gpay = TBDropin.create("tb_upiIntent", {
  value: { upiAppName: "GPAY" },
});

gpay.mount("#gPay");

const phonepe = TBDropin.create("tb_upiIntent", {
  value: { upiAppName: "PHONEPE" },
});

phonepe.mount("#phonePe");

const paytm = TBDropin.create("tb_upiIntent", {
  value: { upiAppName: "PAYTM" },
});

paytm.mount("#payTm");
```

You can view all supported apps here: [Supported UPI Apps](/checkout.js/web-sdk/dropin/customize-your-sdk#10-supported-upi-apps)

### UPI QR

Use the UPI QR Component to collect payments through QR-based UPI flows.

The SDK automatically renders a QR code that customers can scan using any supported UPI application such as PhonePe, Google Pay, Paytm, BHIM, etc.

The QR component supports:

* Popup QR Flow

* Full UI Customization

* Payment Status Handling

<Note>UPI QR payments are supported only on desktop browsers.</Note>

```js theme={null}
const upiQr = TBDropin.create("tb_upiQr", qrOptions);
```

**Returned Value**

upiQr `UPI QR Object`

```js theme={null}
{
 element: "tb_upiQr",
 value: {
  channel: 'QR'
 },
 isValid: true,
 ready: true
}
```

| Field       | Type     |
| ----------- | -------- |
| **channel** | `string` |

### Code Snippet for upiQr component

```js theme={null}
const TBDropin = window.TBDropin();

await TBDropin.init({
  mode: "sandbox", // sandbox or production
  publishKey: "", // your publish key goes here
  popupConfig: popupOptions,
});

const upiQr = TBDropin.create("tb_upiQr", qrOptions);

upiQr.mount("#upiQr");

upiQr.on("ready", (data) => console.log("upiQr", data));
```

### UPI QR Customization

The UPI QR payment UI can be customized using `qrOptions`.

<Card title="Customize Your SDK -> UPI QR" icon="code" href="/checkout.js/web-sdk/dropin/customize-your-sdk#9-upi-qr-qr-based-payments">
  Learn how to customize the UPI QR payment UI
</Card>

`qrOptions` works similarly to popupOptions, but with higher priority.

* Styles defined inside qrOptions overwrite popupOptions
* Missing styles automatically fallback to popupOptions

**Next Steps**

* **A Customize component styles**
* **Add multiple payment methods using tabs**
* **Handle payment confirmation on backend**
* **Set up webhooks for payment status**

**Need Help?**

Explore the following sections for more details:

* <a href="/checkout.js/web-sdk/dropin/overview">**Dropin Overview**</a>
* <a href="/checkout.js/web-sdk/dropin/quickstart">**Quickstart**</a>
* <a href="/checkout.js/web-sdk/dropin/customize-your-sdk">**Customization**</a>

If you need assistance, our support team is here to help 🚀


# Customize Your SDK
Source: https://developer.transactbridge.com/checkout.js/web-sdk/dropin/customize-your-sdk



The TB Drop-in SDK is designed to be highly customizable, allowing merchants to fully align the payment experience with their brand while maintaining security and PCI compliance.

All sensitive inputs are rendered inside secure iframes, but styling, fonts, layout, icons, and popup behavior can be controlled from the parent page.

### What Can Be Customized?

You can customize the SDK at three different levels:

1. Component UI (Inputs & Icons)
2. Iframe & Layout
3. Popup / Payment Status UI

### 1. Input Styling (Component Styles)

Each payment component supports custom styles that control the look and feel of the input field.

**Example**

```js theme={null}
const inputStyle = {
  fontFamily: '"Roboto", sans-serif',
  padding: "12px",
  color: "darkslategray",
  borderRadius: "8px",
  border: "1px solid #d9d9d9",
  height: "38px",
  margin: "3px",

  [":focus"]: {
    border: "1px solid #007aff",
  },

  [":hover"]: {
    border: "1px solid #007aff",
    outline: "3px solid #007aff40",
  },

  ["::placeholder"]: {
    color: "gray",
  },
};
```

**Supported Styling Features**

* Font family
* Text color
* Border & radius
* Padding & height
* Hover & focus states
* Placeholder styles

These styles are applied inside the iframe, ensuring security while giving full UI control.

### 2. Iframe Layout Customization

Each component iframe can be styled independently using `frameStyle`.

**Example**

```js theme={null}
const frameStyle = {
  height: "44px",
  width: "100%",
  borderRadius: "8px",
  border: "none",
};
```

**Use Cases**

* Match your form layout
* Adjust spacing between fields
* Fit responsive containers
* Maintain consistent heights across inputs

### 3. Font Customization

You can load and use custom fonts across all SDK components.

**Example**

```js theme={null}
const fonts = [
  {
    cssSrc:
      "https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap",
  },
  {
    cssSrc:
      "https://fonts.googleapis.com/css2?family=Orbitron:wght@400;600&display=swap",
  },
];
```

```js theme={null}
styles: {
  fontFamily: '"Roboto", sans-serif';
}
```

Fonts are injected into the iframe securely and applied consistently.

### 4. Icon Customization

Payment components like Card Number and UPI support icon configuration.

**Example**

```js theme={null}
const iconConfig = {
  styles: {
    width: "20px",
    height: "20px",
  },
};
```

**Options**

* Show or hide icons
* Control icon size
* Maintain brand consistency

### 5. Popup Customization (Payment Flow)

The SDK popup (used during UPI or redirect flows) is fully customizable using popupConfig.

**Example**

```js theme={null}
const TBDropin = window.TBDropin();

await TBDropin.init({
  mode: "sandbox",
  publishKey: "<your-key>",
  popupConfig: popupOptions,
});
```

```js theme={null}
const popupOptions = {
  fonts,
  components: {
    // Timer
    timer: {
      circle: {
        stroke: "gold !important",
      },
      styles: {
        fontFamily: fontOrbitron,
        color: "dimgray",
        backgroundColor: "white",
      },
    },

    // Status Screens
    success: {
      backgroundColor: "#68c577",
      color: "white",
    },
    failed: {
      backgroundColor: "#e06d6d",
      color: "white",
    },
    processing: {
      backgroundColor: "gold",
      color: "white",
    },

    // Text & Labels
    instruction: {
      fontFamily: fontRoboto,
      color: "gray",
      fontSize: "14px",
    },
    bullet: {
      height: "24px",
      width: "24px",
      backgroundColor: "dimgray",
    },
    label: {
      fontFamily: fontRoboto,
      color: "darkgray",
      fontWeight: "500",
    },
    value: {
      fontFamily: fontRoboto,
      color: "dimgray",
      fontWeight: "normal",
    },
    note: {
      fontFamily: fontRoboto,
      color: "gray",
      fontSize: "10px",
      fontWeight: "500",
    },
    base: {
      fontFamily: fontRoboto,
      backgroundColor: "#fff",
      color: "darkslategray",
    },
    link: {
      color: "blue",
      textDecoration: "none",
      ":hover": {
        cursor: "pointer",
        color: "blueviolet",
      },
    },
    closeButton: {
      color: "darkslategray",
      pointerEvents: "auto",
      backgroundColor: "white",
      height: "24px",
      width: "24px",
    },
  },

  // Popup Frame Styling
  frameStyle: {
    width: "40px",
    height: "60px",
    borderRadius: "15px",
    zIndex: "99999999",
  },
};
```

### 6. Popup Frame Styling

```js theme={null}
frameStyle: {
 width: '40px',
 height: '60px',
 borderRadius: '15px',
 zIndex: '99999999'
}
```

This allows you to:

* Control popup size
* Adjust layering (z-index)
* Match your brand modal design

### 7. Component-Level Customization

Each component can be customized independently.

**Supported Component Options**

* `styles`
* `frameStyle`
* `fonts`
* `icon`
* `skeletonStyle`
* `disableSkeleton`

**Card Example**

```js theme={null}
const skeletonStyle = {
  height: "44px",
  borderRadius: "8px",
  baseColor: "#ebedf0",
  highlightColor: "#f7f8fa",
  animationDuration: "10s",
  lineCount: 1,
};

const cardNumber = TBDropin.create("tb_cardNumber", {
  placeholder: "Enter Card Number",
  styles: inputStyle,
  frameStyle,
  icon: iconConfig,
  fonts,
  skeletonStyle,
});
```

**Disable Skeleton**

```js theme={null}
const tnc = TBDropin.create("tb_tnc", {
  disableSkeleton: true,
});
```

### 8. UPI Intent (App-Based Payments)

UPI Intent allows users to complete payments directly through installed UPI applications such as PhonePe, Google Pay, Paytm, etc.
Instead of entering a UPI ID, the user selects an app and the SDK triggers the UPI intent flow.

**Example**

```js theme={null}
const component = TBDropin.create("tb_upiIntent", {
  value: {
    upiAppName: upiApp?.toUpperCase(),,
  },
});

component.mount('#' + upiApp)
```

### 9. UPI QR (QR-Based Payments)

UPI QR allows users to complete payments by scanning a QR code using any supported UPI application such as PhonePe, Google Pay, Paytm, BHIM, etc.

The SDK automatically renders the QR payment screen and handles the payment flow securely.

### Example

```js theme={null}
const upiQr = TBDropin.create("tb_upiQr", qrOptions);

upiQr.mount("#upiQr");
```

The UPI QR payment UI can be customized using `qrOptions`.

`qrOptions` works similarly to `popupOptions`, but with higher priority.

* Styles defined inside `qrOptions` overwrite `popupOptions`
* Missing styles automatically fallback to `popupOptions`

### Example

```js theme={null}
const qrOptions = {
  fonts,
  components: {
    title: {
      fontFamily: fontRoboto,
      color: "darkslategray",
      fontSize: "16px",
      fontWeight: "500",
      paddingTop: "2rem",
    },
    timer: {
      fontFamily: fontOrbitron,
      color: "dimgray",
      backgroundColor: "white",
    },
    image: {
      width: "220px",
      height: "220px",
    },
    instruction: {
      fontFamily: fontRoboto,
      color: "gray",
      fontSize: "12px",
    },
    bullet: {
      height: "20px",
      width: "20px",
      minWidth: "20px",
      backgroundColor: "dimgray",
    },
    label: {
      fontFamily: fontRoboto,
      color: "darkgray",
      fontWeight: "500",
    },
    value: {
      fontFamily: fontRoboto,
      color: "dimgray",
      fontWeight: "normal",
    },
    note: {
      fontFamily: fontRoboto,
      color: "gray",
      fontSize: "10px",
      fontWeight: "500",
    },
    base: {
      fontFamily: fontRoboto,
      backgroundColor: "#fff",
      color: "darkslategray",
      paddingTop: "1rem",
    },
    closeButton: {
      color: "darkslategray",
      pointerEvents: "auto",
      backgroundColor: "white",
      height: "24px", // min-height: 20px
      width: "24px", // min-width: 20px
    },
  },
  frameStyle: {
    width: "360px", //in px
    height: "560px", //in px
    borderRadius: "15px", //in px
    zIndex: "99999999",
  },
};
```

<Note>
  <b>Future flag:</b> `inline: true` <br />
  Inline mode allows the QR UI to render directly inside your application UI
  instead of opening in a popup. This may be introduced in future SDK releases.
</Note>

#### How It Works

* qrOptions overrides popupOptions
* Any style provided inside qrOptions will take higher priority
* Missing styles automatically fallback to popupOptions

### 10. Supported UPI Apps

The SDK supports the following UPI applications for UPI Intent payments.

| upiAppName (upiAppName) | Logo URL                                                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `PHONEPE`               | [https://cdn.transactbridge.com/Assets/payment-apps/phonepe.webp](https://cdn.transactbridge.com/Assets/payment-apps/phonepe.webp)         |
| `PAYTM`                 | [https://cdn.transactbridge.com/Assets/payment-apps/paytm.webp](https://cdn.transactbridge.com/Assets/payment-apps/paytm.webp)             |
| `GPAY`                  | [https://cdn.transactbridge.com/Assets/payment-apps/gpay.webp](https://cdn.transactbridge.com/Assets/payment-apps/gpay.webp)               |
| `CRED`                  | [https://cdn.transactbridge.com/Assets/payment-apps/cred.webp](https://cdn.transactbridge.com/Assets/payment-apps/cred.webp)               |
| `MOBIKWIK`              | [https://cdn.transactbridge.com/Assets/payment-apps/mobikwik.webp](https://cdn.transactbridge.com/Assets/payment-apps/mobikwik.webp)       |
| `FREECHARGE`            | [https://cdn.transactbridge.com/Assets/payment-apps/freecharge.webp](https://cdn.transactbridge.com/Assets/payment-apps/freecharge.webp)   |
| `JUPITER`               | [https://cdn.transactbridge.com/Assets/payment-apps/jupiter.webp](https://cdn.transactbridge.com/Assets/payment-apps/jupiter.webp)         |
| `NAVI`                  | [https://cdn.transactbridge.com/Assets/payment-apps/navi-money.webp](https://cdn.transactbridge.com/Assets/payment-apps/navi-money.webp)   |
| `PAYZAPP`               | [https://cdn.transactbridge.com/Assets/payment-apps/payzapp.webp](https://cdn.transactbridge.com/Assets/payment-apps/payzapp.webp)         |
| `BHIM`                  | [https://cdn.transactbridge.com/Assets/payment-apps/bhim.webp](https://cdn.transactbridge.com/Assets/payment-apps/bhim.webp)               |
| `SUPERMONEY`            | [https://cdn.transactbridge.com/Assets/payment-apps/super-money.webp](https://cdn.transactbridge.com/Assets/payment-apps/super-money.webp) |
| `AMAZONPAY`             | [https://cdn.transactbridge.com/Assets/payment-apps/amazon.webp](https://cdn.transactbridge.com/Assets/payment-apps/amazon.webp)           |
| `SLICE`                 | [https://cdn.transactbridge.com/Assets/payment-apps/slice.webp](https://cdn.transactbridge.com/Assets/payment-apps/slice.webp)             |
| `OTHERS`                | [https://cdn.transactbridge.com/Assets/payment-apps/bhim.webp](https://cdn.transactbridge.com/Assets/payment-apps/bhim.webp)               |

<Note>
  UPI Intent payments only work on mobile devices. This flow will not work on
  desktop browsers because desktop devices cannot trigger mobile UPI apps.
</Note>

### 11. Terms & Conditions Component

The `tb_tnc` component displays the Terms & Conditions text, links, and acceptance checkbox.

```js theme={null}
const tnc = TBDropin.create("tb_tnc", {
  buttonText: "Pay",

  styles: {
    fontFamily: fontRoboto,
    fontSize: "12px",
    color: "gray",
  },

  checkboxStyle: {
    WebkitAppearance: 'none',
    MozAppearance: 'none',
    appearance: 'none',
    minWidth: '20px',
    height: '20px',
    borderRadius: '4px',
    accentColor: 'red',
    border: '1px solid red',
    overflow: 'hidden',
    [':checked']: {
      ['::before']: {
        content: '"✓"',
        display: 'block',
        textAlign: 'center',
        color: 'blue',
        backgroundColor: 'red',
        fontSize: '16px',
      },
    },
  },

  link: {
    color: "blue",
    ":hover": {
      color: "red",
    },
  },

  fonts
});

tnc.mount('#tnc');
```

| Option       | Type     | Description                                                                                          |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `buttonText` | `string` | Sets the text displayed on the payment button (for example: `"Pay"`, `"Pay Now"`, or `"Subscribe"`). |

**Checkbox Styling**

The `checkboxStyle` option allows you to customize the appearance of the T\&C checkbox.
Supported styling options include:

-Width and height
-Border radius
-Border
-Accent color
-Checked state styling
-Other supported CSS properties

This allows full control over:

* Text styling
* Link colors
* Button labels

### Summary

* TB Drop-in SDK provides deep UI customization
* Works consistently across Card, UPI, and future methods
* Customization does not compromise security
* Same integration works across environments


# Overview
Source: https://developer.transactbridge.com/checkout.js/web-sdk/dropin/overview



TBDropin is a JavaScript-based Drop-in Payments SDK that allows merchants to easily embed secure, PCI-compliant payment components into their web applications.

It provides pre-built payment elements (UPI, Cards, T\&C, etc.) that are rendered inside secure iframes, ensuring sensitive payment data never touches the merchant’s servers.

**With a simple script include and a few lines of JavaScript, merchants can:**

* Collect payment details securely
* Trigger payments with a unified pay() API

### What does the Drop-in SDK provide?

The Drop-in SDK offers a set of ready-to-use payment elements, including:

* <a href="/checkout.js/web-sdk/dropin/components/upi#upi-intent">UPI Intent</a>
* <a href="/checkout.js/web-sdk/dropin/components/upi#upi-qr">UPI QR</a>
* <a href="/checkout.js/web-sdk/dropin/components/cards#cardnumber">
    Card Number
  </a>
* <a href="/checkout.js/web-sdk/dropin/components/cards#cardholder">
    Card Holder Name
  </a>
* <a href="/checkout.js/web-sdk/dropin/components/cards#cardexp">Card Expiry</a>
* <a href="/checkout.js/web-sdk/dropin/components/cards#cardcvv">Card CVV</a>
* <a href="/checkout.js/web-sdk/dropin/customize-your-sdk#5-popup-customization-payment-flow">
    Payment status popup (success, failure, processing)
  </a>
* <a href="/checkout.js/web-sdk/dropin/components/compliance-checks">Compliance Checks (rendered only when required)</a>

### How TBDropin Works

TBDropin follows a component-based architecture similar to modern payment element SDKs.

1. <a href="/checkout.js/web-sdk/dropin/quickstart#1-load-the-sdk">
     Load the SDK
   </a>

2. <a href="/checkout.js/web-sdk/dropin/quickstart#2-initialize-tbdropin">
     Initialize TBDropin
   </a>

3. <a href="/checkout.js/web-sdk/dropin/quickstart#3-create-payment-components">
     Create payment components
   </a>

4. <a href="/checkout.js/web-sdk/dropin/quickstart#4-mount-components-into-the-dom">
     Mount components into the DOM
   </a>

5. <a href="/checkout.js/web-sdk/dropin/quickstart#5-trigger-payment-using-pay">
     Trigger payment using pay()
   </a>

Each payment input (Card Number, UPI ID, CVV, Expiry, etc.) runs inside a sandboxed iframe, isolating sensitive data and improving security.

### Key Concepts

#### 1. Initialization

Before using any component, the SDK must be initialized.

```js theme={null}
const TBDropin = window.TBDropin();

await TBDropin.init({
  mode: "sandbox", // or 'production'
  publishKey: "your_publish_key",
});
```

**Initialization:**

* Sets the environment (sandbox / production)
* Loads payment atom definitions
* Prepares secure message handling between iframes

#### 2. Payment Components (Elements)

TBDropin provides individual payment elements, such as:

* `tb_upiIntent`

* `tb_upiQr`

* `tb_cardNumber`

* `tb_cardExp`

* `tb_cardCvv`

* `tb_cardHolder`

* `tb_tnc`

**Each component:**

* Is created using `TBDropin.create()`

* Is mounted into a DOM container

* Emits lifecycle events like `ready`, `change`, `clear`

```js theme={null}
const upi = TBDropin.create('tb_<component>', {
  placeholder: 'Your placeholder here',
  styles: {...},
  fonts: [...]
});

upi.mount('#<elementId>');
```

#### 3. Component Lifecycle & Events

Every component exposes event hooks:

```js theme={null}
component.on("ready", () => {
  console.log("Component is ready");
});

component.on("change", (data) => {
  console.log("Input changed", data);
});
```

#### 4. Secure Iframe Architecture

All payment fields are rendered inside secure iframes created by the SDK.
The Compliance Checks are also rendered inside a secure iframe when compliance information is required for a payment.

**Benefits:**

* PCI compliance

* No raw card / UPI data exposed to merchant

* Isolated DOM & styles

* Safe cross-origin communication via postMessage

**The SDK handles:**

* Iframe creation

* Styling constraints

* Event communication

* Data aggregation during payment

#### 5. Making a Payment

Once the required components are mounted and valid, payment is initiated using:

```js theme={null}
const response = await TBDropin.pay({
  billingSessionId,
  subscriptionId,
  mandateId,
  payMethod: selectedPaymentMethod,
  cardType: "CC", // only for cards
  sessionToken,
});
```

### How Compliance Flow works

Some payment sessions may require additional customer information before payment can be initiated.

When compliance is required, the SDK automatically opens a secure Compliance Check popup.

The SDK:

* Detects whether compliance is required.
* Displays the Compliance Check automatically.
* Collects the required customer information securely.
* Continues the payment automatically after successful submission.

**Rules:**

* Exactly one of billingSessionId, subscriptionId, or mandateId is required

* T\&C (tb\_tnc) must be visible and accepted

* All required inputs must be valid before payment proceeds

#### 6. Getting Required IDs for Payment

Before calling `TBDropin.pay()`, merchants must obtain one of the following identifiers from the Transact Bridge APIs:

* `billingSessionId`

* `subscriptionId`

* `mandateId`

* `sessionToken`

<Note>
  For Drop-in integration, do not reuse the same session token for every
  request. Always use the latest session token generated for each new session,
  as session tokens are unique and valid only for their respective session
</Note>

These IDs are generated server-side using Transact Bridge APIs and represent different payment flows.

**Important:** Exactly one of these IDs must be provided when calling pay().

You can obtain the billingSessionId by creating a billing session using the Transact Bridge Sessions API. This API allows you to generate a unique payment session for one-time payments. Refer to the API documentation below for request structure, required parameters, and response details.

<Card title="One Time Payment API Docs" icon="code" href="https://docs.transactbridge.com/#a393206c-8fae-4f1f-a55f-01b53330ec66">
  View the Postman API Collection
</Card>


# Quick Start
Source: https://developer.transactbridge.com/checkout.js/web-sdk/dropin/quickstart



Integrate TBDropin into your website in minutes.

This guide provides a step-by-step walkthrough to help you integrate **TBDropin** into your website or application within minutes.

You’ll learn how to load the SDK, initialize it, mount payment components, and trigger a payment.

## Prerequisites

Before you begin, ensure you have:

* A **Billing Session ID**, **Subscription ID**, or **Mandate ID**
* Your **TransactBridge Publishable Key**
* A **Session Token** returned when creating a Billing Session, Subscription, or Mandate

You can obtain all the required credentials and payment identifiers from the TransactBridge platform and APIs. Refer to the documentation below.

<Card title="API Reference" icon="code" href="https://docs.transactbridge.com/#a393206c-8fae-4f1f-a55f-01b53330ec66">
  View the API documentation
</Card>

## 1. Load the SDK

To manually load **Checkout.js**, simply add the script link to the **\<head>** of any page.

```js theme={null}
<script src="https://cdn.transactbridge.com/scripts/v1.0/dropin.js"></script>
```

## 2. Initialize TBDropin

Initialize the SDK using your publishable key and mode (sandbox or production).

```js theme={null}
window.addEventListener("load", async () => {
  const TBDropin = window.TBDropin();

  await TBDropin.init({
    mode: "sandbox", // or production
    publishKey: "YOUR_PUBLISHABLE_KEY",
  });
});
```

| Environment        | Type     | Description                                                                                                                             |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **publishableKey** | `string` | Your TransactBridge publishable key. You can obtain it from the Merchant Dashboard or your TransactBridge account representative.       |
| **mode**           | `string` | Specifies the environment in which the SDK operates. Supported values are `sandbox` for testing and `production` for live transactions. |

## 3. Create payment components

Create container elements in your HTML where components will be mounted.

```js theme={null}
<div id="cardNumber"></div>
<div id="cardHolder"></div>
<div id="cardExp"></div>
<div id="cardCvv"></div>
<div id="tnc"></div>

```

## 4. Mount components into the DOM

All payment fields are created using TBDropin.create()
and attached to the DOM using mount().

**Card Payment Components**

```js theme={null}
const cardNumber = TBDropin.create("tb_cardNumber", {
  placeholder: "Enter card number",
});

const cardHolder = TBDropin.create("tb_cardHolder", {
  placeholder: "Card holder name",
});

const cardExp = TBDropin.create("tb_cardExp");
const cardCvv = TBDropin.create("tb_cardCvv");

cardNumber.mount("#cardNumber");
cardHolder.mount("#cardHolder");
cardExp.mount("#cardExp");
cardCvv.mount("#cardCvv");
```

**Terms & Conditions**

Use the TNC component to display Terms & Conditions and capture user consent before initiating payment.
A component used to render Terms & Conditions text along with a configurable **Pay button label**.

```js theme={null}
const tnc = TBDropin.create("tb_tnc", {
  buttonText: "Pay",
});

tnc.mount("#tnc");
```

## 5. Trigger payment using pay()

Once components are valid, call pay().

```js theme={null}
const result = await TBDropin.pay({
  billingSessionId: "bs_xxxxx", // billingSessionId || subscriptionId || mandateId
  payMethod: cardNumber,
  cardType: "CC"
  sessionToken,
});
```

| Field                     | Type        | Description                                                                                                                                                 |
| ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **billingSessionId**      | `string`    | Used for **one-time payments**.                                                                                                                             |
| **subscriptionId**        | `string`    | Used for **recurring payments (subscriptions)**.                                                                                                            |
| **mandateId**             | `string`    | Used during **mandate setup** for recurring payments.                                                                                                       |
| **sessionToken**          | `string`    | A short-lived token returned when creating a Billing Session, Subscription, or Mandate. It is required to securely initialize the SDK and process payments. |
| **payMethod**             | `Component` | Payment component/interface used to process the transaction.                                                                                                |
| **cardType**              | `string`    | Type of card: **CC (Credit Card)** or **DC (Debit Card)**.                                                                                                  |
| **updateMandateRequired** | `boolean`   | Set to `true` when a subscription is **upgraded or downgraded** and a new mandate setup is required. Use only with `subscriptionId`.                        |

### Response

pay() returns a promise that resolves with the transaction initiation status.

**Example Success Response**

```json theme={null}
{
  "status": "success",
  "data": {
    "reqId": "req_h6rb9f1rc2",
    "tbId": "6a33e9e8436f050db3d44bfd",
    "type": "billingSession",
    "supplierRefId": "6a33e9e8436f050db3d44bfd_10",
    "status": "CLOSED",
    "transactionId": "1648237qr8723r923",
    "transactionStatus": "SUCCESS",
    "error": null
  }
}
```

**Example Failed Response**

```json theme={null}
{
  "status": "error",
  "data": {
    "reqId": "req_xxxxx",
    "tbId": "6a33e9e8436f050db3d44bfd",
    "type": "billingSession",
    "supplierRefId": "6a33e9e8436f050db3d44bfd_9",
    "status": "STARTED",
    "transactionId": "164823712128723923",
    "transactionStatus": "FAILED",
    "error": {
      "code": "DEBIT_HAS_BEEN_FAILED",
      "message": "Debit has been failed"
    }
  }
}
```

<Note>
  Note: The pay() method initiates the payment flow and returns the transaction
  state. The final payment outcome (Success or Failed) is determined through the
  payment status flow and status events.
</Note>

**Next Steps**

* <a href="/api-reference/introduction">**API Reference**</a>
* <a href="/checkout.js/web-sdk/dropin/overview">
    **A Customize component styles**
  </a>

**Need Help?**

If you need assistance, our support team is here to help 🚀


# Overview
Source: https://developer.transactbridge.com/checkout.js/web-sdk/iframe/overview



Integrate Transact Bridge and Retain Seamlessly with checkout.js

**Checkout.js** is a lightweight JavaScript library designed for effortless one-time and subscription billing integration.

With **Checkout.js**, you can:

* Open dynamic checkouts with prefilled customer details
* Build pricing pages with localized taxes and discounts applied automatically
* Interact with checkouts in real time and display relevant information on your page
* Create smooth upgrade workflows using inline checkouts
* Reduce churn effortlessly by integrating with Retain
* Enhance your payment experience with a simple yet powerful solution.

<Note>
  **Checkout.js** seamlessly embeds a payment widget as an iframe on partner
  websites, enabling customers to pay without leaving the page.
</Note>

<Card title="Check Demo flow" icon="desktop" href="https://www.transactbridge.com/demo">
  View the checkout.js rendering as a widget on our Demo Page.
</Card>


# Quick Start
Source: https://developer.transactbridge.com/checkout.js/web-sdk/iframe/quickstart



To start building subscription billing experiences with Transact Bridge, include Checkout.js on your checkout pages and in-app.

## Setup your development

To manually load **Checkout.js**, simply add the script link to the **\<head>** of any page.

```js theme={null}
<script src="https://cdn.transactbridge.com/scripts/v1.1/checkout.js"></script>
```

## Sample HTML File

Here is a sample HTML file that demonstrates how to load Checkout.js on a page.

<Note>
  Please change the **payUrl** and **src** for production. Below sample file
  works on sandbox environment.
</Note>

```html theme={null}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Transact Bridge Sample Demo</title>
  </head>
  <body style="margin: 0px">
    <style>
      #close_button {
        font-size: x-large;
        font-weight: lighter;
        padding: 0;
        width: 25px;
        height: 25px;
        display: inline-flex;
        align-items: center;
        justify-content: center;
        border-radius: 6px;
        background-color: #fff;
        border: 1px solid #007aff;
        color: #007aff;
        position: absolute;
        top: -30px;
        right: -20px;
      }
      #tb_root {
        padding: 6px;
        background: #fff;
        border-radius: 6px;
      }

      dialog {
        background: transparent;
        border: none;
        padding: 0;
        margin-top: 10vw;
        overflow: visible;
      }

      dialog::backdrop {
        background-color: #2b2b2b87;
      }

      .container {
        position: relative;
      }
    </style>
    <button id="buynow">Buy</button>
    <dialog>
      <div class="container">
        <button id="close_button">&#215;</button>
        <div id="tb_root"></div>
      </div>
    </dialog>
    <script>
      const payUrl =
        "https://sandboxpay.transactbridge.com/customer/singlePage/product?billingSessionId=67a472a4a991a5786a5e0bb5"; //replace your link

      const buyButton = document.getElementById("buynow");
      const dialog = document.querySelector("dialog");
      const closeButton = document.getElementById("close_button");

      function closeIframe() {
        dialog.close();
        //do somthing...
      }

      function getSessionData(sessionData) {
        //do somthing...
        console.log({ sessionData });
      }

      function getTxnData(txData) {
        //do somthing...
        console.log({ txData });
      }
    </script>

    <script src="https://cdn.transactbridge.com/scripts/v1.1/checkout.js"></script>
    <script>
      const tbIframe = new TBIframe();

      const options = {
          mode: 'sandbox' // 'sandbox' | 'production'
      };

      function buyNow() {
        dialog.showModal();
        tbIframe.init(payUrl, getSessionData, closeIframe, getTxnData, options);
      }

      buyButton.addEventListener("click", () => {
        buyNow();
      });

      closeButton.addEventListener("click", () => {
        tbIframe.close();
      });
    </script>
  </body>
</html>
```


# v1.0
Source: https://developer.transactbridge.com/checkout.js/web-sdk/iframe/v1.0



TBIframe (Version 1) is a simple JavaScript-based integration that allows merchants to embed Transact Bridge’s hosted payment flow inside an iframe.

<Warning>
  This version of the TransactBridge Web SDK has been deprecated and will be
  removed in a future release. Please use the latest SDK version **v1.1** for new
  integrations.
</Warning>

## Setup your development

To manually load **Checkout.js**, simply add the script link to the **\<head>** of any page.

```js theme={null}
<script src="https://cdn.transactbridge.com/scripts/v1.0/checkout.js"></script>
```

This version focuses on callback-based communication, where the merchant application listens to important payment events through function parameters passed during initialization.

**Using v1.0, you can:**

* Open a secure payment iframe
* Receive payment session updates
* Track transaction creation
* Detect when the iframe is closed (manually or automatically)
  This version is best suited for basic payment flows where advanced event handling or KYC tracking is not required.

## Usage

### 1. Required HTML Structure

Include a **Buy Now** button, a modal dialog, and an iframe container:

> 📝 **Note:** Root element ID **must be** `tb_root` — this is where the iframe will be injected.

```html theme={null}
<button id="buynow">Buy Now</button>
<button id="close_button">&#215;</button>
<div id="tb_root"></div>
```

### 2. Initialize and Use `TBIframe`

When the user clicks Buy Now, the following happens:

1. A **TBIframe** instance is created.
2. **init()** is called with the session URL.
3. The iframe opens and loads the payment flow.
4. During the payment lifecycle:

* **onSessionUpdate** is called when payment status changes
* **onTransactionUpdate** is called when a transaction is initiated
* **onClose** is called when the iframe closes

Create an instance and handle the payment session:

```js theme={null}
const payUrl = "https://www.example.com"; // your session URL

const options = {
  frameStyles: { minWidth: "340px" },
  mode: 'sandbox' // 'sandbox' | 'production'
};

const tbIframe = new TBIframe();

// Callback on iframe close
function onCloseIframe(sessionData) {
  console.log("Iframe closed:", sessionData);
  // do something...
}

// Handle session updates
function getSessionData(sessionData) {
  console.log("Session Data:", sessionData);
  // do something...
}

// Handle transaction updates
function getTxnData(txData) {
  console.log("Transaction Data:", txData);
  // do something...
}

// Open payment iframe
function startIframe() {
  tbIframe.init(payUrl, getSessionData, onCloseIframe, getTxnData, options);
}

document
  .getElementById("buynow")
  .addEventListener("click", () => startIframe());
```

## TBIframe API Reference

### Constructor

```js theme={null}
const tbIframe = new TBIframe();
```

* Initializes the `TBIframe` instance.

***

### Methods

#### 1. `init`

Loads the payment iframe and manages session updates and UI customization.

```js theme={null}
tbIframe.init(url, onSessionUpdate, onClose, onTransactionUpdate, options);
```

##### Parameters:

| Name                  | Type                       | Description                                                                 |
| --------------------- | -------------------------- | --------------------------------------------------------------------------- |
| `url`                 | `string`                   | Session URL.                                                                |
| `onSessionUpdate`     | `(data: object) => void`   | Callback triggered on payment session update (e.g., completion).            |
| `onClose`             | `(data: object) => void`   | Callback triggered when iframe closes manually or automatically.            |
| `onTransactionUpdate` | `(data: string[]) => void` | Callback triggered on payment trigger; returns an array of transaction IDs. |
| `options`             | `TBIframeOptions`          | Object for customizing iframe styles and behavior.                          |

##### Options TBIframeOptions Properties:

| Property      | Type                           | Description                          |
| ------------- | ------------------------------ | ------------------------------------ |
| `frameStyles` | `Partial<CSSStyleDeclaration>` | Custom styles for the iframe itself. |
| `mode`        | `sandbox or production`        | Application Environment              |

##### Example:

```js theme={null}
tbIframe.init(
  "https://www.example.com",
  (sessionData) => console.log("Session:", sessionData),
  (sessionData) => console.log("Iframe closed", sessionData),
  (txnData) => console.log("Transaction:", txnData),
  {
    frameStyles: { minWidth: "340px" },
    mode: 'sandbox' // 'sandbox' | 'production'
  },
);
```

***

#### 2. `close()`

Closes the iframe and removes it from the DOM.\
Also triggers the `onClose` callback if it was provided during `init`.

```js theme={null}
tbIframe.close();
```

##### Example:

```js theme={null}
// Close payment iframe manually
function closeIframe() {
  tbIframe.close();
}

document
  .getElementById("close_button")
  .addEventListener("click", () => closeIframe());
```


# v1.1
Source: https://developer.transactbridge.com/checkout.js/web-sdk/iframe/v1.1



Advanced iframe integration with event subscriptions.

## Setup your development

To manually load **Checkout.js**, simply add the script link to the **\<head>** of any page.

```js theme={null}
<script src="https://cdn.transactbridge.com/scripts/v1.1/checkout.js"></script>
```

## 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}
<button id="buynow">Buy Now</button>
<button id="close_button">&#215;</button>
<div id="tb_root"></div>
```

***

## 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<CSSStyleDeclaration>` | 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.

***


# Overview
Source: https://developer.transactbridge.com/guides/features/admin-dashboard/overview

Gain full control over monitoring & analysing transactions with reports & dashboard 

At Transact Bridge Partner will have fully loaded dashboard to manage their business.
The dashboard is designed to provide a comprehensive overview of all **transactions**, **sales**, **refunds**, **chargebacks**, **settlements**, and **customer data**.
It also includes a **monitoring dashboard** with graphical insights to track key financial metrics in real-time.
Partner can manage their organization details, bank account, and payment settings in their profile.
They can also process **payouts** to suppliers, generate invoices, and manage **customer subscriptions**.
The dashboard provides a centralized platform for Partner to monitor, analyze, and optimize their payment operations efficiently.

## Monitoring Dashboard:

Partner can track key financial metrics in real-time using our monitoring dashboard with graphical insights. It displays transaction volumes, net revenue, refunds, chargebacks, and settlements in one place. This helps Partner analyze trends, detect issues, and make informed decisions efficiently.

## Merchant profile:

Partner can add and manage their organization details and bank account in their profile. This includes company information, business registration, and settlement account setup.

## Transactions/Sales:

This menu shows all customer payment transactions along with their current status. Partner can monitor and export transaction details. Clicking on a Transaction ID provides a detailed view, including item details, transaction amount, fees, and logs.

## Payouts (Coming Soon shortly):

Partner can seamlessly process payouts to suppliers via verified bank accounts or UPI. Manage cash balances efficiently with secure and instant fund transfers. Simplify vendor payments with a streamlined payout solution.

## Invoices:

This menu shows all payment invoices generated after successful transactions and their status. Partner can monitor, export, and download invoice details. Clicking on an Invoice ID shows item details, customer billing and shipping address, transaction amount, and invoice logs.

## Returns/Refunds:

This menu shows all customer refund requests and their current status. Partner can track, export, and download refund details. Clicking on a Refund ID provides a detailed view, including item details, transaction amount, fees, and refund logs.

## Chargebacks:

This menu shows all customer chargeback requests and their status. Partner can track, export, and download chargeback details. Clicking on a Chargeback ID provides a detailed view, including item details, transaction amount, fees, and chargeback logs.

## Billing sessions:

This menu shows all billing sessions created by customers during purchases. Partner can track, export, and download session details. Clicking on a Session ID provides a detailed view, including item details, customer billing and shipping address, transaction amount, and session logs.

## Subscriptions:

This menu shows all customer subscriptions along with their details. Partner can track, export, and download subscription data. Clicking on a Session ID provides a detailed view, including item details, customer billing and shipping address, transaction amount, and session logs.

## Customers/Audience:

This menu shows a list of all created customers along with their basic and payment details. Partner can easily view and manage customer information. It provides a quick overview of customer transactions and payment history.

## Receivables/Settlements:

Partner can track their settlement history and current status on this page. They can also view and download detailed summary reports. This ensures easy monitoring and record-keeping of all settlements.

## Report Center:

Partner can access and download all exported reports and data from this page. They can also view the history of previously generated reports. This helps in easy tracking and record management.

## API Logs:

Partner can view real-time API logs of all activities on their end. This helps track requests, responses, and system interactions.

## Tax details:

Partner can view product tax categories, subcategories, HSN codes, and applicable taxes on this page. This helps in accurate tax calculation and product classification. It ensures seamless tax compliance and reporting.

## Team members:

Partner can add team members to help manage their account with assigned permissions. This allows controlled access based on roles and responsibilities. It ensures secure and efficient account monitoring.

## Action logs:

Partner can track and monitor all actions performed by themselves or the admin. The logs display action type, user role, and timestamps for transparency. This ensures better security and accountability.

## Account settings:

Partner can manage payment methods, upload their organization logo, change colour theme for their checkout page, and configure callback URLs and whitelist domains to be used.


# Branded Checkout
Source: https://developer.transactbridge.com/guides/features/branded-checkout

Create a seamless brand experience for your customers using the our checkout

Strengthen customer loyalty with branded payment experiences.
Customize **invoices**, **checkout pages**, and **transaction notifications** with your logo and brand identity.
Verify your root domain and create payment link URLs that match your brand. For example: [https://netflix.transactbridge.com](https://netflix.transactbridge.com)
Transact Bridge ensures seamless branding across all customer interactions, enhancing trust and recognition.


# Customer Behavior Analysis
Source: https://developer.transactbridge.com/guides/features/customer-behavious-analysis

Monitor and analyze customer interactions to optimize business strategies

Understand your customers better with behavior analysis tools.
We leverage **heatmaps** and **session recording** tools to analyze customer behavior in real time.
Insights help us identify friction points and optimize the payment experience and to provide **actionable insights**.
Continuously improving conversions for a seamless checkout journey

Businesses can optimize pricing, marketing strategies, and fraud prevention based on data-driven analytics.


# GST Verificatioin
Source: https://developer.transactbridge.com/guides/features/customer-verification/gst-verification

Ensure tax compliance and business authenticity with real-time GST verification

Ensure **tax compliance** and **business authenticity** with Transact Bridge’s GST number verification.
Businesses can instantly validate the **Goods and Services Tax (GST)** Identification Number provided by merchants, suppliers, or customers to confirm their legitimacy.
This feature reduces the risk of dealing with fraudulent businesses and ensures accurate tax reporting. By integrating real-time GST verification, businesses can streamline invoicing, tax calculations, and regulatory filings while maintaining credibility.

Whether onboarding new vendors or ensuring compliance, Transact Bridge’s automated GST verification eliminates manual errors, enhances financial transparency, and ensures smooth business transactions.


# Mobile Verificatioin
Source: https://developer.transactbridge.com/guides/features/customer-verification/mobile-verification

Enhance security with mobile number verification for transactions and user authentication

Transact Bridge offers mobile number verification to enhance security and prevent fraudulent transactions.
By sending a **one-time password (OTP)** to the customer’s registered mobile number, businesses can ensure that only verified users proceed with transactions.
This feature helps reduce **fake sign-ups**, **unauthorized access**, and potential fraud risks.
Mobile verification also improves customer engagement, enabling businesses to send real-time transaction updates, OTP confirmations, and personalized offers.

Whether for payments, account creation, or login authentication, Transact Bridge’s mobile verification ensures a secure and reliable way to validate user identities before processing transactions.


# Overview
Source: https://developer.transactbridge.com/guides/features/customer-verification/overview

Enhance security with customer verification tools for KYC compliance and identity verification

Enhance security with customer verification tools.
Transact Bridge offers **KYC compliance**, **identity verification**, and **multi-factor** authentication to prevent fraud.
Businesses can verify user details before processing high-value transactions, ensuring compliance and risk mitigation.


# Pan Verification
Source: https://developer.transactbridge.com/guides/features/customer-verification/pan-verification

Verify PAN details against government databases for compliance and identity authentication

With PAN number verification, Transact Bridge helps businesses ensure **compliance** and **authenticate** customer identities.
By verifying the Permanent Account Number (PAN) against government databases, businesses can prevent **identity fraud** and maintain regulatory adherence.
This feature is essential for financial transactions, **high-value purchases**, and tax reporting, ensuring that the PAN details provided by customers are valid and accurate.

Automated PAN verification minimizes manual errors and speeds up the verification process. Whether for KYC compliance or financial due diligence, Transact Bridge’s secure PAN verification system simplifies identity authentication while protecting businesses from potential fraud risks.


# UPI Verificatioin
Source: https://developer.transactbridge.com/guides/features/customer-verification/upi-verification

Increase success rate and decrease frauds using government enabled tools

Transact Bridge ensures seamless and secure **UPI verification** for hassle-free transactions.
By verifying a customer’s Unified Payments Interface (UPI) ID, businesses can **authenticate** payments, **reduce fraud**, and **enhance trust** in digital transactions.
Our real-time verification system instantly validates UPI credentials, ensuring that payments are processed only through legitimate accounts.
This feature is particularly beneficial for merchants looking to streamline instant fund transfers, refunds, and payouts.

With Transact Bridge, businesses can confidently enable UPI-based transactions while maintaining security, compliance, and fraud prevention, ensuring a smooth and error-free payment experience for both merchants and customers.


# Zipcode Verification
Source: https://developer.transactbridge.com/guides/features/customer-verification/zipcode-verification

Enhance address validation with zip code verification for secure transactions

Transact Bridge enhances address validation with zip code verification, ensuring seamless order fulfillment and fraud prevention.
By verifying the provided postal or zip code against a **valid database**, businesses can confirm customer locations before processing transactions.
This feature helps prevent **shipping errors**, **ensures tax compliance** for regional pricing, and enhances the accuracy of fraud detection systems.
Real-time zip code validation enables businesses to restrict transactions from **high-risk areas**, ensuring secure and legitimate transactions.
Whether for e-commerce, financial services, or location-based verification, Transact Bridge’s zip code verification enhances operational efficiency and customer satisfaction.


# Discount System
Source: https://developer.transactbridge.com/guides/features/discounts

Boost sales and customer engagement with discount management feature

Boost sales and customer engagement with Transact Bridge’s discount management feature.
Businesses can create targeted **promotions**, **coupon codes**, and time-limited offers to incentivize purchases.
Set flexible **discount structures**, including **percentage-based**, **fixed-amount** and apply them to specific products, categories, or customer segments.
The system ensures seamless discount application **during checkout**, enhancing the customer experience.
Automated tracking provides insights into promotional performance, helping businesses refine their strategies.

Whether for seasonal sales, loyalty rewards, or new customer acquisition, Transact Bridge’s discount feature helps businesses attract more customers and increase conversions effortlessly.


# Dynamic Payment Routing
Source: https://developer.transactbridge.com/guides/features/dynamic-payment-routing

Better your success rate using dynamic payment routing to the best payment processor

We have an intelligent transaction routing system that **automatically directs payments** to the most suitable bank for transaction processing.
Intelligent routing adapts to **customer location**, **currency**, and **bank response times** for optimal performance.
This routing is based on multiple factors such as the selected **payment method**, the **transaction amount**, and the success or failure rates of different banks.

The system ensures that each transaction is processed through the most efficient and reliable gateway, maximizing success rates while maintaining a seamless and transparent experience for the customer.


# Fraud & Risk Management
Source: https://developer.transactbridge.com/guides/features/fraud-&-risk-management

Monitor and prevent fraudulent activities with AI-driven risk management

Protect your business with Transact Bridge’s fraud and risk management system.
We use AI-driven analytics to **detect suspicious patterns**, **prevent chargebacks**, and **block high-risk** transactions.
Our real-time monitoring identifies anomalies, reducing fraudulent activities before they occur.
Customizable risk filters and automated alerts allow businesses to take proactive measures.

By analyzing historical transaction data, Transact Bridge continuously enhances its fraud prevention capabilities.

<Steps>
  <Step title="Customer Risk Profiles">
    Our payment gateway creates **risk profiles** for each customer based on payment history, methods, and lifetime value.
    A **dynamic risk** score helps detect fraud by cross-referencing data across merchants.
  </Step>

  <Step title="Dynamic Risk Flags">
    Our risk team identifies risk flags by analyzing past chargebacks and fraud patterns.
    These flags power **real-time risk** filters, ensuring proactive fraud detection.
    A dedicated risk monitoring team oversees transactions 24/7 for maximum security.
  </Step>

  <Step title="Banned item center">
    Ensure compliance by dynamically blocking restricted **products** based on **jurisdiction**.
    Our system detects and prevents transactions for **non-permitted items** in **real-time**. Stay compliant effortlessly while expanding your business in India.
  </Step>

  <Step title="Blocking System">
    Our system blocks **emails**, **mobile numbers**, and **payment details** of customers with **past chargebacks or disputes**.
    A central database cross-verifies data across merchants to enhance risk prevention.
    Protect your business by preventing fraudulent transactions before they happen.
  </Step>
</Steps>


# Invoice & Billing
Source: https://developer.transactbridge.com/guides/features/invoice-&-billing

Manage recurring billing and automate invoice generation

Transact Bridge streamlines **invoice generation** and **billing**, ensuring accurate and automated financial records.
Businesses can create customized invoices with **branding**, **itemized charges**, and **tax calculations**.
The system supports **multiple payment methods**, enabling seamless transactions directly from invoices.
With built-in tracking, businesses can monitor **paid**, **pending**, and **overdue** invoices, improving cash flow management.
Automated reminders help reduce late payments, while real-time reports provide insights into revenue trends.

Whether for one-time purchases or recurring subscriptions, Transact Bridge ensures a smooth billing experience, improving efficiency and reducing manual work.


# One Time Payment
Source: https://developer.transactbridge.com/guides/features/one-time-payment

Seamless, secure one-time payments with multiple methods for quick transactions.

Transact Bridge simplifies **one-time** payments, allowing businesses to process transactions seamlessly.
Customers can quickly complete purchases without the need for subscriptions or recurring billing.
With multiple payment options, including **UPI**, **credit/debit cards**, **digital wallets**, and **bank transfers**, businesses can offer flexibility and convenience.
The secure checkout process ensures fast and hassle-free payments while maintaining compliance with global **PCI-DSS** security standards.
Designed for instant transactions, the system minimizes cart abandonment and enhances customer satisfaction.

Whether you're selling **digital goods**, **services**, or **physical products**, Transact Bridge’s one-time payment solution provides a reliable and frictionless experience for both merchants and customers.

### Key Features

* Configure which payment methods to show to the customer
* Secure Payment Gateway - PCI-DSS compliant
* Configure webhooks for real-time updates
* Use custom logo and colour theme for checkout page
* Product pricing in multiple currencies
* Expire payment links after a set time
* Detailed transaction reports and analytics


# Open Brand Webstore
Source: https://developer.transactbridge.com/guides/features/open-brand-webstore

Create your online store in minutes and start accepting payments instantly

Unlock limitless possibilities with Transact Bridge Custom Commerce, our fully **customizable Direct-to-Consumer (D2C)** web store.
Backed by years of expertise in digital commerce, we understand what it takes to **design**, **launch**, and **scale** a successful online store.
Let us build a seamless, brand-first experience that keeps your customers at the heart of every transaction

Set up a new online store in minutes, integrate products, and start accepting payments instantly.
Our scalable solution allows merchants to manage multiple stores from a single dashboard, ensuring smooth operations and growth.


# Overview
Source: https://developer.transactbridge.com/guides/features/overview

Dwell into the feature list of Transact Bridge to fully utilise payment suites

Transact Bridge empowers businesses with a complete payment and commerce solution.
Easily manage your product catalog, accept **one-time** payments, and set up **subscriptions** with flexible discounts.
Our **invoice & billing** system ensures seamless financial management, while the optimized payment flow enhances customer experience.

Gain full control with an intuitive admin dashboard and robust security & compliance.
Advanced fraud & risk management and **dynamic payment routing** boost transaction success.
Leverage customer behavior analysis for insights, launch new stores instantly, and enhance brand recall.
With **real-time FX conversion** and secure **customer verification**, Transact Bridge ensures smooth, global, and secure transactions.


# Payment Flow
Source: https://developer.transactbridge.com/guides/features/payment-flow

Choose between payment links and checkout widget to streamline the payment process

Optimize the customer payment experience with Transact Bridge’s streamlined payment flow.
Designed for simplicity and security, our checkout process ensures fast and seamless transactions.
Businesses can integrate multiple payment methods, including cards, wallets, and bank transfers, reducing drop-offs.
Smart routing minimizes transaction failures, while real-time fraud detection protects against suspicious activity.
Customers benefit from a smooth, user-friendly checkout, enhancing satisfaction and increasing conversions.

Whether for online stores, service providers, or SaaS platforms, Transact Bridge ensures a frictionless payment process tailored to business needs.

<Steps>
  <Step title="Payment Link">
    Create a **Payment Link** to share with customers via email, SMS, or social media.
  </Step>

  <Step title="Iframe Widget">
    Embed the **Checkout Widget** on your website or app for a seamless payment experience.
  </Step>
</Steps>


# Product Catalogue
Source: https://developer.transactbridge.com/guides/features/product-catalogue

Easily manage, organize, and showcase products with a dynamic catalog system.

Transact Bridge enables businesses to create, manage, and organize their product catalog effortlessly.
Whether selling **digital** or **physical** goods, businesses can categorize products, **set pricing**, and **update inventory in real time**.
The intuitive interface allows for seamless product management, ensuring customers always see the latest offerings.
With flexible customization options, businesses can showcase detailed descriptions, images, and variations.
Integrated with the payment system, the catalog ensures a smooth checkout process.

Whether you're a startup or an enterprise,
Transact Bridge’s scalable catalog solution helps streamline product management, enhance user experience, and maximize sales efficiency across multiple channels.

### Key Features

* Global HSN Code based tax calculations.
* Subscription based products for recurring billing.
* Multiple product variations and attributes.


# Real-time Foreign Exchange Conversion
Source: https://developer.transactbridge.com/guides/features/real-time-FX-conversion

Sell your product in choice of your currency  and collect locally

Accept payments **globally** with **real-time** foreign exchange conversion.
Transact Bridge supports **multiple currencies**, automatically converting payments at competitive rates.
Businesses can display **localized pricing** and ensure seamless international transactions, reducing cart abandonment.


# Security & Compliance
Source: https://developer.transactbridge.com/guides/features/security-&-compliance

Ensure secure transactions and compliance with global standards

Transact Bridge ensures the highest level of security and compliance for all transactions.
Our platform is **PCI DSS certified**, adhering to global payment security standards.
Multi-layered **encryption**, **fraud detection**, and **tokenization** protect sensitive customer data.
Businesses benefit from robust authentication measures, reducing the risk of fraudulent activities.
With **GDPR** and other regulatory compliance, merchants can operate confidently in global markets.

Our proactive security approach safeguards both businesses and customers, ensuring trust and reliability in every transaction.


# Subscriptions
Source: https://developer.transactbridge.com/guides/features/subscriptions

Set up and manage subscription-based billing with flexible options

Easily set up and manage **subscription-based** billing with Transact Bridge.
Businesses can offer recurring payment plans with flexible **billing cycles**, **automated invoicing**, and secure transaction processing.
Customers enjoy uninterrupted access to services, while businesses benefit from predictable revenue.
With **customizable pricing**, **trial periods**, and **renewal options**, subscriptions can be tailored to various needs.
Automated reminders and dunning management reduce churn and ensure timely payments.
The system seamlessly integrates with analytics to track customer retention and revenue growth.

Whether for SaaS, memberships, or content platforms, Transact Bridge provides a robust subscription management system to scale your recurring revenue model.

### Key Features

* Trial periods with and without payment method attached
* Credit adjustments and refunds
* Pro rate based invocing for partial month subscription
* Both prepaid and postpaid based subscription
* Configure which payment methods to show to the customer
* Secure Payment Gateway - PCI-DSS compliant
* Configure webhooks for real-time updates
* Apply Discounts on first or recurring payments
* Use custom logo and colour theme for checkout page
* Product pricing in multiple currencies
* Detailed transaction reports and analytics


# Introduction
Source: https://developer.transactbridge.com/introduction

Welcome to the Transact Bridge's documentation. Here you'll find everything you need to get started with our API.

## What is TransactBridge

We are the best **Merchant of Record (MoR)** solutions provider in India, which enables businesses to navigate the complex Indian market with confidence. Our tailored services are designed to simplify payment processing, ensuring you can focus on growth. Whether you’re in e-commerce, gaming, or any other industry, our solutions allow you to leverage popular Indian payment methods like **UPI**, **Netbanking**, **Cards** or **Wallets**. Partner with us to streamline your operations and unlock new opportunities in India’s dynamic economy.

<CardGroup>
  <Card title="Postman Collection" icon="palette" href="https://docs.transactbridge.com">
    Get started with our Postman collection to quickly test our APIs and start accepting payments
  </Card>

  <Card title="API Reference" icon="code" href="../api-reference/introduction">
    Use our JSON REST APIs to easily integrate payments into your website or app
  </Card>

  <Card title="Subscriptions" icon="screwdriver-wrench" href="../payments/subscriptions/overview">
    Integrate our recurring billing API to enable UPI and card payments for SAAS businesses
  </Card>

  <Card title="Checkout.js" icon="stars" href="../checkout.js/checkout/overview">
    With our Checkout.js, you can easily integrate payment widget in your website or app and start accepting payments
  </Card>
</CardGroup>

**Chat with our AI Solutions Engineer for workflow guidance.**

<a href="https://transactbridge.swytchcode.ai">
  <img alt="Try it Instantly – Swytchcode" />
</a>

<Note>
  For any tech related issues, please reach out to our [Tech Support Team](mailto:tech@transactbridge.com)
</Note>


# Dropin
Source: https://developer.transactbridge.com/one-time-payments/checkout-integrations/dropin



TBDropin is a JavaScript-based Drop-in Payments SDK that allows merchants to easily embed secure, PCI-compliant payment components into their web applications.
It provides pre-built payment elements (UPI, Cards, T\&C, etc.) that are rendered inside secure iframes, ensuring sensitive payment data never touches the merchant’s servers.

## Drop-in Flow for website

1. Merchant injects [**TBdropin SDK**](https://developer.transactbridge.com/checkout.js/web-sdk/dropin/quickstart) and initializes it with Publish key and mode(environemnt).

2. Merchant can now use the SDK on their checkout page.

3. Once the user clicks on buy now/Proceed to pay button at merchants website, now the merchant renders checkout page hosted by them. Where Transact Bridge components are mounted.

4. Merchant calls the [**Create Session API**](https://docs.transactbridge.com/#d4607171-457b-4d24-8277-6d9a79a997dd) to generate a session. Which in return gives a **unique session ID** and a **session token** which is used to complete the payment.

<Note>
  Merchant can generate a session at the time of opening their checkout page or at the time when user clicks on pay button of merchant hosted checkout page.
</Note>

5. Merchant collects the payment details from the customer on their checkout page.

6. Once the user clicks on Pay button. Merchant needs to calls the **pay()** method([**Triggering a Payment**](/checkout.js/web-sdk/dropin/quickstart#triggering-a-payment)) at the checkout with the payment details entered by the user and the session token.

7. Payment is completed, TB shares the status of the txn which merchant can show that on their own customized page.

8. TB triggers a [**Webhook**](https://docs.transactbridge.com/#5ff84b04-3f5d-4e85-a7c8-2c07e1e65536) on the configured server URL provided by the merchant.

   And also the transaction status is also provided in the pay method response.

9. Subsequently, an invoice for a successful transactionis generated and sent to the customer.

## Payment Flow

```mermaid theme={null}
sequenceDiagram
autonumber

    actor User
    participant A as Merchant Website
    participant B as Merchant Backend
    participant C as TB Backend
    participant D as Drop-in SDK

    User->>A: Clicks "Buy Now"
    A->>A: Opens Merchant-hosted Checkout Page

    User->>A: Enters payment details
    User->>A: Clicks "Pay"

    A->>B: Request to create session
    B->>C: Create Session API
    C-->>B: Session Token + Session ID

    B-->>A: Session Token + Session ID

    A->>D: pay(sessionToken, payMethod,sessionId)
    D->>C: Initialize Payment
    C-->>D: Payment result

    D-->>A: Payment status
   
    C->>B: Webhook: Session status update
    B->>B: Process webhook
    B-->>A: Shows payment and session status
    

```

## Workflow for Android SDK

1. Merchant adds the [**AAR**](https://developer.transactbridge.com/checkout.js/android-sdk/dropin/v1.0#1-download-the-aar) file in their project and the [**required dependencies**](https://developer.transactbridge.com/checkout.js/android-sdk/dropin/v1.0#3-declare-required-dependencies)  in app/build.gradle .
2. Now  initialize the TransactBridge PaymentSDK at [**onCreate()**](https://developer.transactbridge.com/checkout.js/android-sdk/dropin/v1.0#4-initialize-the-sdk) method in the main activity file.
3. Merchant can now use the SDK on their checkout screen.
4. Once the user clicks on buy now/Proceed to pay button at checkout screen , where Transact Bridge components are mounted.
5. Merchant calls the [**Create Session API**](https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825) to generate a session. Which in return gives a **unique session ID** and a **session token** which is used to complete the payment.

<Note>
  Merchant can generate a session at the time of opening their checkout screen or at the time when user clicks on pay button of merchant checkout screen.
</Note>

6. Merchant collects the payment details from the customer on their checkout screen.

7. Once the user clicks on Pay button. Merchant needs to calls the [**payUpi()**](https://developer.transactbridge.com/checkout.js/android-sdk/dropin/v1.0#8-launch-upi-payment) method.

8. Payment is completed, TB shares the status of the txn which merchant can show that on their own customized screen.

9. TB triggers a [**Webhook**](https://docs.transactbridge.com/#5ff84b04-3f5d-4e85-a7c8-2c07e1e65536) on the configured server URL provided by the merchant.

   And also the transaction status is also provided in the [**PaymentResultListener**](https://developer.transactbridge.com/checkout.js/android-sdk/dropin/v1.0#9-handling-payment-results)

10. Subsequently, an invoice for a succesfull transaction is generated and sent to the customer.


# Iframe Checkout Solution
Source: https://developer.transactbridge.com/one-time-payments/checkout-integrations/iframe

Learn how to integrate the Transact Bridge iframe checkout solution into your website for a seamless payment experience.

It embeds the Transact Bridge subscription checkout within the merchant's webpage, allowing customers to complete the subscription payment and mandate authorization without leaving the merchant's page

## Workflow for Website

1. The merchant will create a session by calling the [**Create Session API**](https://docs.transactbridge.com/#d4607171-457b-4d24-8277-6d9a79a997dd) at the backend.

2. The API will return a **redirect URL** and a **unique ID** for subscription.

3. The redirect URL is used to render the checkout page by passing the URL in the `init()` method of the `TBIframe` instance.
   Navigate to [TBIframe Quickstart](https://developer.transactbridge.com/checkout.js/web-sdk/iframe/quickstart)

4. This will open an **iframe within the merchant's page**, from where the customer can make the payment.

5. TB will display the **transaction status** in the iframe. However, the merchant can also display the payment status page based on the status/data received through the [**Handler reference**](https://developer.transactbridge.com/checkout.js/web-sdk/iframe/v1.1).

6. TB triggers a [**Webhook**](https://docs.transactbridge.com/#5ff84b04-3f5d-4e85-a7c8-2c07e1e65536) on the configured server URL provided by the merchant.

   The transaction status is also provided through the **Handler references**.

7. Subsequently, an **invoice** is generated for a sucessful transaction and sent to the customer.

<Note>
  * In case the payment fails, TB does not mark the session as FAILED OR CLOSED and allows **multiple transactions** until there is a successful transaction on that session. The customer can retry the transaction within the **same session**.

  * After a successful transaction, the iframe **automatically closes within 10 seconds**.

  * In case there is no activity on the iframe by the customer, or the customer closes the page, the session remains active by default for **24 hours**. However, this timeframe can be customized and reduced to **10 minutes** through backend configuration. To enable this configuration, you need to raise a request with us.
</Note>

## Payment Flow

```mermaid theme={null}
sequenceDiagram
    autonumber

    actor User
    participant A as Merchant Website 
    participant B as Merchant Server
    participant C as TB Server 
    participant D as Iframe SDK 

    User->>A: Clicks on payment button

    A->>B: Request order creation
    B->>C: Create order / payment request
    C-->>B: Returns payment URL
    B-->>A: Returns payment URL

    A->>D: Passes payment URL
    D-->>A: Renders payment iframe on merchant website

    User->>D: Attempts payment in iframe

    Note over B,C: TB processes the payment

    C-->>B: Sends payment webhook
    D-->>A: Sends payment status via callback functions
```

### Workflow for Android SDK

1. The merchant will create a session by calling the [**Create Session API**](https://docs.transactbridge.com/#d4607171-457b-4d24-8277-6d9a79a997dd) at the backend.
2. The API will return a **redirect URL** and a **unique ID** for the session.
3. Initialize the SDK onCreate()  in your main activity file.
4. The redirect URL is used to render the checkout page by passing the URL in the [**open()**](https://developer.transactbridge.com/checkout.js/android-sdk/web-view/v1.0#3-usage) method of the TransactBridge Instance
5. This will open a webview within the merchant app screen. Where merchant can complete the payment process.
6. TB will display the **transaction status** in the webview. However, the merchant can also display the payment status screen based on the status/data received through the [**EVENT HANDLING REFERENCE**](checkout.js/android-sdk/web-view/v1.0#4-event-handling)
7. TB triggers a [**Webhook**](https://docs.transactbridge.com/#5ff84b04-3f5d-4e85-a7c8-2c07e1e65536) on the configured server URL provided by the merchant.
8. Subsequently, an **invoice** is generated for a succesfull transaction and sent to the customer.


# Payment link
Source: https://developer.transactbridge.com/one-time-payments/checkout-integrations/payment-link



One-Time Payment Link Flow

You can generate a unique payment link for a customer using the Create Order / Payment API. This works similarly to payment link providers like Cashfree, where a secure checkout URL is generated and shared with the customer.

## Workflow

1. The merchant creates a session by calling the [**Create Session API**](https://docs.transactbridge.com/#d4607171-457b-4d24-8277-6d9a79a997dd) from the backend.

2. Create Session API in return gives a **unique session ID** and a **redirect URL**.

3. The merchant uses the returned **redirect URL** to redirect the user to the payment page. Or can use the same **redirect url as the Payment Link** and shares it with the customer through email, SMS, WhatsApp, or any other communication channel.

4. The customer lands to  **Transact Bridge hosted checkout page**, where the customer enters their payment details and completes the payment.

5. Once the payment is completed, Transact Bridge processes the payment and updates the session and transaction status.

6. Customer is redirected to the **return url** provided in the create session API call. The return URL can be a success page or a failure page based on the payment status.

7. If the payment is successful and the invoice is generated, the session moves to **CLOSED** state.

8. If the payment/transaction is unsuccessful, the session remains in **STARTED** state.

9. Transact Bridge triggers a [**Webhook**](https://docs.transactbridge.com/#5ff84b04-3f5d-4e85-a7c8-2c07e1e65536) to the server URL configured by the merchant. The webhook contains the relevant session and payment event information.

10. For the successfull transactions an **invoice is generated** by Transact Bridge and sent to the customer.

<Note>
  * In case the payment fails, TB does not mark the session as FAILED OR CLOSED and allows **multiple transactions** until there is a successful transaction on that session. The customer can retry the transaction within the **same session**.
</Note>

<Note>
  * In case the payment fails, the customer can retry the payment from the **same checkout session/payment link**, subject to the configured session and payment validity.
  * The merchant should always verify the final payment status through the **webhook** before fulfilling the order or providing the purchased service.
  * The payment link should be treated as a secure checkout URL and should be shared only with the intended customer.
</Note>

## Payment Flow

```mermaid theme={null}
sequenceDiagram
    autonumber

    actor User
    participant A as Merchant Website
    participant B as Merchant Server
    participant C as TB Server
    participant D as TB Hosted Checkout

    User->>A: Clicks on payment button

    A->>B: Request payment/order creation
    B->>C: Create order / payment request
    C-->>B: Returns Order ID and payment URL
    B-->>A: Returns payment URL

    A->>D: Redirects to TB Hosted Checkout

    User->>D: Enters payment details
    User->>D: Attempts payment

    Note over C,D: TB processes the payment

    C-->>B: Sends payment webhook
    D-->>A: Redirects to return URL

    B->>B: Updates order/payment status
```


# Business use cases
Source: https://developer.transactbridge.com/one-time-payments/getting-started/business-use-cases



One-time payments are ideal for businesses that need to collect a single payment from a customer without setting up recurring billing or a subscription.

## When to Use One-Time Payments

Use one-time payments when:

* The customer is making a single purchase.
* The merchant does not need to charge the customer automatically in the future.
* The product or service has a fixed one-time price.
* The merchant needs a simple checkout experience.

***

## Business Use Cases

### E-commerce

Use one-time payments to collect payment for individual products purchased from an online store.

**Example:**
A customer purchases a product worth ₹2,000. The merchant initiates a one-time payment and the customer completes the payment through checkout.

### Digital Products

Use one-time payments for digital products such as e-books, templates, courses, software licenses, or downloadable content.

**Example:**
A customer purchases an e-book for ₹500. After the payment is successfully completed, the merchant provides access to the e-book.

### Professional Services

Service providers can use one-time payments to collect payment for individual services or projects.

**Example:**
A consultant charges ₹10,000 for a one-time consultation. The customer completes the payment before the consultation is delivered.

### Physical Products

Businesses can collect a single payment for physical products without creating a recurring subscription.

**Example:**
A customer places an order worth ₹5,000. After successful payment, the merchant confirms the order and fulfills it.

### Events and Bookings

One-time payments can be used for event tickets, appointments, reservations, and other single-use bookings.

**Example:**
A customer purchases a conference ticket for ₹3,000. After successful payment, the merchant confirms the booking and provides the ticket.

### Donations

Organizations can use one-time payments to collect individual donations.

**Example:**
A donor chooses to contribute ₹1,000 and completes the payment through checkout. The organization can then confirm the donation and issue a receipt.

```mermaid theme={null}
flowchart TB
    A[Customer selects product] --> B[Merchant creates payment session]
    B --> C[Customer redirected to Checkout]
    C --> D[Customer completes payment]
    D --> E[Payment successful]
    E --> F[Invoice generated]
    E --> G[Webhook sent to Merchant]
    G --> H[Order fulfilled]
```


# Discount
Source: https://developer.transactbridge.com/one-time-payments/getting-started/discount



A discount allows merchants to reduce the amount payable by the customer based on a configured discount value.

Discounts can be configured as either  a **fixed amount**.

## Supported Discount Type

| Discount Type    | Description                                           |
| ---------------- | ----------------------------------------------------- |
| **Fixed Amount** | Deducts a specific amount from the applicable amount. |

### Fixed Amount Discount

For a fixed amount discount, the configured discount amount is directly deducted from the applicable amount.

For example:

```text theme={null}
Product Price = ₹2,000
Discount      = ₹200
```

Therefore:

```text theme={null}
Amount After Discount = ₹2,000 - ₹200
                      = ₹1,800
```

***

## GST-Exclusive Price

For a GST-exclusive price, the discount is applied to the taxable amount first. GST is then calculated on the discounted taxable amount.

For example:

```text theme={null}
Taxable Amount      = ₹2,000
Discount Amount      = ₹200
Discounted Taxable   = ₹1,800
GST Rate             = 18%
```

GST is:

```text theme={null}
GST = ₹1,800 × 18 / 100
    = ₹324
```

Therefore:

```text theme={null}
Total Payable = ₹1,800 + ₹324
             = ₹2,124
```

<Note>
  * The exact application of a discount may depend on the discount configuration and the applicable tax configuration.

  * As of now, Discounts with GST inclusive invoice is not available.
</Note>

## Apply Discount to One-Time Payments

To learn how to apply a discount to one-time payments, refer to the [**Apply Discount**](/one-time-payments/manage-your-payments/apply-discount) section.

***

## Business Use Cases

Discounts can be used with one-time payments to provide promotional pricing, encourage purchases, or offer special pricing to specific customers.

The following use cases demonstrate **discounts**.

### 1. Promotional Offers

Merchants can offer a fixed-amount discount as part of a promotional campaign.

**Example:**

A merchant sells a product for **₹2,000** and offers a **₹200 promotional discount**.

```text theme={null}
Product Price   = ₹2,000
Discount        = ₹200
Final Amount    = ₹1,800
```

This can be used for campaigns such as seasonal sales, product launches, or limited-time promotions.

### 2. Coupon-Based Discounts

Merchants can provide customers with a coupon or promotional code that applies a fixed discount to the one-time payment.

**Example:**

```text theme={null}
Product Price   = ₹2,000
Coupon Discount = ₹300
Final Amount    = ₹1,700
```

The merchant can validate the coupon and apply the corresponding discount to the payment amount.

### 3. Customer-Specific Discounts

Merchants can provide a fixed discount to selected customers.

**Example:**

A merchant offers an existing customer a **₹250 discount** on a product priced at ₹2,000.

```text theme={null}
Product Price       = ₹2,000
Customer Discount   = ₹250
Final Amount        = ₹1,750
```

### 4. Bulk Purchase Discounts

Merchants can offer a fixed discount when a customer purchases multiple products or units in a single transaction.

**Example:**

```text theme={null}
Product Price        = ₹1,000 per unit
Quantity              = 5
Total Product Amount  = ₹5,000
Bulk Purchase Discount = ₹500
Final Amount          = ₹4,500
```

This can encourage customers to purchase multiple units in a single payment.

### 5. Limited-Time Discounts

Merchants can offer a fixed discount for a specific period to create time-sensitive offers.

**Example:**

```text theme={null}
Offer Period  = 1 September – 15 September
Product Price = ₹2,000
Discount      = ₹400
Final Amount  = ₹1,600
```

The discount can be made available only during the configured promotional period.

### 6. First-Time Customer Discounts

Merchants can offer a fixed discount to customers making their first purchase.

**Example:**

```text theme={null}
Product Price            = ₹2,000
First-Purchase Discount  = ₹200
Final Amount             = ₹1,800
```

This can be used as an incentive to acquire new customers.

### 7. Partner or Affiliate Discounts

Merchants can provide a fixed discount to customers referred through partners or affiliate networks.

**Example:**

```text theme={null}
Product Price      = ₹2,000
Partner Discount   = ₹250
Final Amount       = ₹1,750
```

This allows merchants to provide special pricing to customers coming through eligible partners or affiliates.


# Overview
Source: https://developer.transactbridge.com/one-time-payments/getting-started/overview



TransactBridge allows it's partners to monetize their products or services through the merchant of model globally. Depending on the customer's billing country, TransactBridge comply with all the local taxations and compliances on behalf of the partner.

Partners can use the local accquiring capabilities of TransactBridge to price their products in local currencies in different jurisdictions and churn our more reveneue. TransactBridge allows to monetize different customers using different payment methods.

Partner creates a session for a particular customer to monetize their products & services. The customer can try multiple attempts with different payment methods avaialble based on jurisdictions to make the payment so as to receive the products or services. Partner can configure the sessions in multiple different ways to accomodate their monetization strategy.

## Session vs. Transaction

A **Session** represents the overall checkout or payment interaction between the customer and Transact Bridge. It provides the context in which the customer enters payment information and completes the checkout process.

A **Transaction** represents an individual attempt to process a payment within that session. It captures the processing and outcome of that particular payment attempt, such as whether the payment was successful, failed, or is still being processed.

### Example

Suppose a customer is purchasing a product for ₹1,000:

1. Transact Bridge creates a **Session** for the customer's checkout.
2. The customer enters their payment details.
3. Transact Bridge initiates a **Transaction** to collect ₹1,000.
4. If the transaction fails, the customer may retry the payment.
5. The retry can result in another **Transaction**, while the checkout remains associated with the same overall **Session**.

<Note>
  One **Billing Session ID** can have multiple payment attempts (Transactions) associated with it. Each payment attempt is treated as a separate transaction, allowing for retries and tracking of individual payment outcomes within the same session.
  However, this can also be configured to single payment attempt on a single session id. For this configuration please reach out to us.
</Note>

<Card title="One Time Payment API Docs" icon="code" href="https://docs.transactbridge.com/#a393206c-8fae-4f1f-a55f-01b53330ec66">
  View the Postman API Collection
</Card>


# Supported Payment Methods
Source: https://developer.transactbridge.com/one-time-payments/getting-started/supported-payment-methods



Currently, Transact Bridge supports the following payment methods to collect one-time payments:

|      Country      | Payment Method |   Min - Max Amount  |
| :---------------: | :------------: | :-----------------: |
|     **India**     |       UPI      |      ₹5-₹15,000     |
|     **India**     |       NB       |     ₹1-₹5,00,000    |
|     **India**     |       CC       |     ₹1-₹1,00,000    |
|     **India**     |       DC       |     ₹1-₹1,00,000    |
| **United States** |       CC       |   \$0.50-\$50,000   |
| **United States** |       DC       |   \$0.50-\$10,000   |
| **United States** |     CASHAPP    |   \$0.01-\$40,000   |
|     **Brazil**    |       PIX      | R\$ 0.01-R\$ 10,000 |

<Note>
  This Max Limit is inclusive of taxes.
</Note>


# Taxation
Source: https://developer.transactbridge.com/one-time-payments/getting-started/taxation



## Tax Configuration for One-Time Payments

Different countries have different tax rules and regulations for different products. Within the same country, different products may also be taxed differently based on the applicable jurisdiction.

TransactBridge allows merchants to automate tax calculation for **one-time payments** without maintaining tax logic and rules in their own systems. Tax rules can be configured for different products and jurisdictions at our end and are automatically applied during billing.

> Tax configuration helps automate tax calculation for one-time payments, reducing manual effort and improving tax compliance.

## Business Use Cases

| Business Use Case                     | Description                                                                           | Example                                                                                                                            |
| ------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Digital Products**                  | Apply applicable taxes when customers purchase digital products.                      | An eBook priced at ₹500 is purchased by a customer, and the configured GST is automatically added to the payment.                  |
| **Software Licenses**                 | Calculate applicable taxes on one-time software license purchases.                    | A software license priced at ₹5,000 is purchased, and the applicable tax is automatically calculated before payment.               |
| **Online Courses**                    | Apply taxes to one-time purchases of courses and educational content.                 | An online course priced at ₹3,000 is purchased, and the configured GST is added to the final payable amount.                       |
| **Global Merchants Selling in India** | Apply the applicable Indian taxes when selling one-time products to Indian customers. | A US-based merchant sells a digital product to an Indian customer, and the configured Indian tax is automatically applied.         |
| **Invoice Generation**                | Generate invoices containing itemized tax details for each completed payment.         | After a successful payment, the customer receives an invoice showing the product amount, applicable tax, and total payable amount. |
| **Financial Reconciliation**          | Maintain accurate tax records for accounting and reporting.                           | Finance teams can reconcile one-time collections using invoices containing the applicable tax breakdown.                           |

## Example

### Product Price

* Product Price: **₹2,000**
* Applicable GST: **18%**

| Description       |     Amount |
| ----------------- | ---------: |
| Product Amount    |     ₹2,000 |
| GST (18%)         |       ₹360 |
| **Total Payable** | **₹2,360** |

During checkout, the configured tax is automatically applied to the one-time purchase. The generated invoice contains the complete tax breakdown for the customer.

***

## How It Works

1. The merchant configures the applicable tax rules for their products and supported jurisdictions with TransactBridge.
2. The customer initiates a one-time purchase.
3. TransactBridge identifies the applicable tax configuration based on the product and customer's jurisdiction.
4. The applicable tax is automatically calculated and added to the purchase amount.
5. The customer pays the final amount, including the applicable tax.
6. An invoice is generated with the itemized tax breakdown.

***

## GST Inclusive and Exclusive Configuration

TransactBridge supports both **tax-inclusive** and **tax-exclusive** pricing configurations. This configuration determines whether the applicable GST is included in the product price or added separately during billing.

### GST Exclusive

In a **GST-exclusive** configuration, the product price does not include GST. The applicable GST is calculated on the product price and added to the final payable amount.

**Example:**

* Product Price: **₹2,000**
* GST Rate: **18%**
* GST Amount: **₹360**
* Total Payable: **₹2,360**

| Description       |     Amount |
| ----------------- | ---------: |
| Product Price     |     ₹2,000 |
| GST (18%)         |       ₹360 |
| **Total Payable** | **₹2,360** |

> **Calculation:** ₹2,000 + (₹2,000 × 18%) = ₹2,360

<img alt="GST Exclusive" />

### GST Inclusive

In a **GST-inclusive** configuration, the product price already includes GST. TransactBridge calculates the GST component from the total product price instead of adding GST on top of it.

**Example:**

* Product Price: **₹2,000**
* GST Rate: **18%**
* GST included in price: **₹305.09**
* Taxable Amount: **₹1,694.92**
* Total Payable: **₹2,000**

| Description       |     Amount |
| ----------------- | ---------: |
| Taxable Amount    |  ₹1,694.92 |
| GST (18%)         |    ₹305.08 |
| **Total Payable** | **₹2,000** |

> **Calculation:** ₹2,000 ÷ 1.18 = ₹1,694.92 taxable amount

<img alt="GST Inclusive" />

### Inclusive vs. Exclusive

| Configuration     | Product Price | GST Treatment                                | Total Payable |
| ----------------- | ------------: | -------------------------------------------- | ------------- |
| **GST Exclusive** |        ₹2,000 | GST is added to the product price            | **₹2,360**    |
| **GST Inclusive** |        ₹2,000 | GST is already included in the product price | **₹2,000**    |

### How Configuration Works

The tax configuration determines how TransactBridge calculates the final amount during billing.

```mermaid theme={null}
flowchart TD
    A[Product Price] --> B{Tax Configuration}

    B -->|Exclusive| C[Calculate GST on Product Price]
    C --> D[Add GST to Product Price]
    D --> E[Final Amount]

    B -->|Inclusive| F[Extract GST from Product Price]
    F --> G[Separate Taxable Amount and GST]
    G --> E[Final Amount]
```

### Key Difference

> **GST Exclusive:** The configured price is the amount before tax. GST is calculated and added to the price.

> **GST Inclusive:** The configured price is the final amount. GST is calculated as a component of the existing price.

<Note>
  GST inclusive and exclusive configurations help in managing tax calculations effectively based on the business requirements. This is configuration based. To get this configured please reach out to TransactBridge support team.
</Note>

## Benefits

* Automated tax calculation for one-time payments
* Tax-compliant invoice generation
* Reduced manual effort and calculation errors
* Consistent tax application across products and jurisdictions
* Simplified financial reporting and reconciliation
* No need to maintain tax logic and rules in the merchant's system


# Apply Discount
Source: https://developer.transactbridge.com/one-time-payments/manage-your-payments/apply-discount



Transact Bridge **does not provide an inbuilt discount management system**. The merchant owns and manages the discount system.

Merchants can use their existing discount infrastructure while using Transact Bridge for subscription checkout and billing.

Discounts allow merchants to offer reduced pricing for one-time payments. A fixed-amount discount can be applied while creating a one-time payment using the `discount` object in the payment request.

***

## Steps for Integration

* Merchant creates and validates the discount in their own system.
* Merchant passes the discount details in the `discount` object while creating the one-time payment using [**Create Session API**](https://docs.transactbridge.com/#d4607171-457b-4d24-8277-6d9a79a997dd).
* The `discount` object defines how the discount should be applied to the payment.
* For a fixed discount, the merchant specifies the discount amount using `discountQuoteAmount`.
* Transact Bridge receives the discount information along with the payment request.
* Transact Bridge applies the discount to the applicable payment amount.
* Merchant renders the Checkout page using the redirect URL received in the response.
* The customer completes the payment using the discounted amount.

***

## Supported Discount Type

For one-time payments, merchants can configure a **fixed-amount discount**.

| Type    | Description                                              |
| ------- | -------------------------------------------------------- |
| **FIX** | Applies a fixed discount amount to the one-time payment. |

***

## Integration Flow

```mermaid theme={null}
flowchart TB

A["Create<br/>Discount"]
B["Create<br/>One-Time Payment using create session API"]
C["Attach<br/>Discount"]
D["Customer<br/>Checkout"]
E["Discounted<br/>Amount"]
F["Payment<br/>Completed"]

A --> B --> C --> D --> E --> F
```

***

## Request Example

The following example demonstrates a fixed-amount discount of **₹100** applied to a one-time payment. This `discount` object needs to be passed in the [`Create Session API`](https://docs.transactbridge.com/#d4607171-457b-4d24-8277-6d9a79a997dd).

```json theme={null}
{
  "discount": {
        "name" : "Test",
        "quoteAmountOff" : 100

    },
}
```

***

## Example

If the original payment amount is **₹2,000** and the configured fixed discount is **₹100**:

```text theme={null}
Original Amount    = ₹2,000
Fixed Discount     = ₹100
Final Amount       = ₹1,900
```

The customer is redirected to the Checkout page with the applicable discount reflected in the payment amount.

<Note>
  The merchant is responsible for creating and validating the coupon or discount in their own system. Transact Bridge receives the discount details provided by the merchant in the API request and applies the configured discount to the one-time payment.
</Note>


# Create a billing session
Source: https://developer.transactbridge.com/one-time-payments/manage-your-payments/create-a-billing-session



## Sample Request for create Billing Session

```json theme={null}

{
    "returnUrl": "https://www.transactbridge.com",
    "quoteCurrCode": "INR",
    
    "items": [
        {
            "name": "Product Name 1 with very long name",
            "description": "Product Descriptoin with a very long desc <br> here is new line for this desc <br/> this is another line for testing puspose hope this works",
            "amount": 2000,
            "quantity": 1
        }
    ],
    "billTo": {
        "name": "XYZ",
        "postalCode": "110001",
        "state": "Delhi",
        "city": "CENTRAL DELHI",
        "country": "INDIA"
    },
    
    "email": "test@gmail.com"
}
```

### Parameter's Description

* **returnUrl**: The URL to which the customer will be redirected after completing the payment. This is mandatory for all different variants of checkout integration.
* **quoteCurrCode**: Fiat price of the product or service in the currency for which request needs to be initiated. **Quote currency and pay currency for the customer can be different for different jurisdictions.**
* **items**: An array of items being purchased, each with a name, description, amount, and quantity.
* **billTo** : An object containing billing Details of the customer for the invoice. Including name, postal code, state, city, and country(mandatory). **Depending on the billTo country local payment currency and other taxations are calculated.**
* **email**: The customer's email address for sending the invoice and payment confirmation.
* **meta**: An optional object for storing additional metadata related to the billing session. This can include any custom information that the merchant wants to associate with the session, such as order ID, customer ID, or any other relevant data. They will be passed in the webhook and query API as well.
* **discount**: An optional object for applying a discount to the one-time payment. This can include details such as the discount name and the discount amount. The discount will be applied to the total amount of the billing session, reducing the final payable amount for the customer.
* **dropIn**: An optional object for configuring the drop-in checkout experience. This can include settings such as the theme, layout, and other customization options for the checkout page. The drop-in configuration allows merchants to provide a seamless payment experience for their customers. **If this is set to be true then the response will contain token that can be used in the drop-in module. This can only be sent in the request if DropIn module has been enabled for the Partner Account**.


# Invoices
Source: https://developer.transactbridge.com/one-time-payments/manage-your-payments/invoices



An invoice is a billing document generated for a customer against a payment or billing event. It provides a record of the amount charged, applicable taxes, discounts, and the final amount payable.

## How Invoices Work

The invoice is generated based on the payment or billing information provided by the merchant.

The typical invoice flow is:

```mermaid theme={null}
flowchart LR

A["Create Payment"] --> B["Payment Processed"]
B --> C["Invoice Generated"]
C --> D["Invoice Available"]
D --> E["Customer Receives Invoice"]
```

***

## Invoice Information

An invoice can contain billing information such as:

| Field                | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| **Invoice ID**       | Unique identifier of the invoice.                          |
| **Customer Details** | Information associated with the customer.                  |
| **Amount**           | Amount associated with the transaction.                    |
| **Discount**         | Discount applied to the payment, if applicable.            |
| **Tax**              | Applicable tax amount.                                     |
| **Total Amount**     | Final amount payable after applicable discounts and taxes. |
| **Invoice Status**   | Current status of the invoice.                             |
| **Invoice Date**     | Date on which the invoice was generated.                   |

***

## Invoice Calculation

The invoice amount can be represented as:

```text theme={null}
Subtotal
- Discount
+ Tax
= Total Amount
```

For example, if the payment amount is ₹2,000 and a fixed discount of ₹100 is applied:

```text theme={null}
Original Amount = ₹2,000
Discount        = ₹100
Tax             = Applicable tax
Total Amount    = Amount after discount + applicable tax
```

***

## Different available Invoices for one time payments

Invoices are created automatically once the payment is successful for one-time payments. Merchants can retrieve individual invoices, retrieve multiple invoices, process refunds, and email invoices to customers. Created invoices can be fetched using below API's:

### 1. Get Invoice

Use the [**Get Invoice** API](https://docs.transactbridge.com/#4f9b7a56-2989-4fd9-b99c-fb5a825c95df) to retrieve the details of a specific invoice.

This can be used when the merchant needs to:

* Retrieve invoice details.
* Check the invoice status.
* View invoice amount and currency.
* Retrieve customer and billing information.
* Check payment or transaction details associated with the invoice.

### 2. Get All Invoice

Use the [**Get All Invoice** API](https://docs.transactbridge.com/#46ff3912-41ef-4be8-ac89-ca1ce5da3a82) to retrieve invoices associated with the merchant.

This can be used when the merchant needs to:

* Display invoices in an internal dashboard.
* Retrieve multiple invoices.
* Track invoice statuses.
* Search or manage invoice records.

### 3. Refund Invoice

Use the [**Refund Invoice** API](https://docs.transactbridge.com/#ed7480f6-f60d-43f7-a01d-f99b37bcee05) when the merchant needs to refund a payment associated with an invoice.

**Typical Use Cases**

* Customer requests a refund.
* Order or service is cancelled.
* Duplicate payment.
* Incorrect amount charged.
* Merchant decides to provide a full or applicable partial refund.

### 4. Email Invoice

Use the [**Email Invoice** API](https://docs.transactbridge.com/#8fcf1aed-340d-44e8-97fe-8006e488154c) to send an invoice to the customer through email.

This can be used when the merchant wants to:

* Send an invoice to the customer's registered email address.
* Resend an invoice.
* Provide the customer with invoice details after payment.
* Share an invoice for record-keeping purposes.


# Refund
Source: https://developer.transactbridge.com/one-time-payments/manage-your-payments/refund



A refund allows a merchant to return a payment amount to the customer when the service has not been delivered or when a transaction needs to be reversed.

## When to Initiate a Refund

A refund can be initiated when a payment has been successfully collected but the corresponding service has not been delivered to the customer.

Refunds are currently supported at the **invoice level**.

<Note>
  **Partial refunds are not supported for now. A refund can only be initiated against an INVOICE marked as PAID.**
</Note>

***

## Refund for Failed Transaction

In some cases, where amount has been debited however the transcation status shows as failed due to some issue with the acquirer or PSP. And our session remains in OPEN state(as on a single session multiple transaction attempts can be made)
The amount is automatically refunded to the customer, which  is generally processed within **5-7 business days**, depending on the customer's bank and the payment network.

The flow is:

1. Customer makes the payment.
2. Payment is initiated successfully and amount is debited.
3. The session remains in the **`OPEN`** state, however the trasnaction status shows as failed due to an issue with the acquirer or PSP end.
4. The payment is automatically refunded to the customer.
5. The refund is credited to the customer's account within the applicable banking timeframe, generally up to **5-7 business days**.

***

## Ways to Initiate Refund

A merchant can initiate a refund using either of the following methods:

* **Admin Panel:** The merchant can initiate the refund from the Transact Bridge Admin Panel.
* **API:** The merchant can initiate the refund programmatically using the [Refund API](https://docs.transactbridge.com/#ed7480f6-f60d-43f7-a01d-f99b37bcee05).

**When creating a refund**, the merchant can make the refund request to below:

* Back to source
* Account Transfer (where merchant needs to provide the customer account number for refund)

***

## Business Use Cases

Refunds can be used in scenarios such as:

* **Service not delivered:** A customer has made a payment, but the merchant is unable to provide the purchased service.
* **Order or service cancellation:** A customer cancels an eligible purchase and the merchant needs to return the payment.
* **Payment or processing issue:** Amount is debited but the txn status shows failed due to an acquirer or PSP issue. Then the amount is autmatically refunded as per the acquiring bank within 5-7 business days.

> **Note:** Refund availability and processing time may depend on the payment method, acquirer, PSP, and customer's bank.


# Webhook
Source: https://developer.transactbridge.com/one-time-payments/manage-your-payments/webhook



Webhooks are user-configured HTTP callbacks that are triggered when a specific event occurs. They allow two applications to communicate by automatically sending event information from one server to another.

Unlike APIs, where you need to repeatedly check for updates, webhooks automatically provide real-time notifications whenever an event occurs.

TransactBridge sends the event details to the **Webhook URL** configured by the merchant. These webhooks are sent as `POST` requests from the TransactBridge server. Authorization headers are also included so that partners can authenticate that the request originated from the TransactBridge server.

Merchants can configure the Webhook URL from the **TransactBridge Admin Panel** to start receiving webhook events.

<Note>
  [**Admin Panel for Sandbox**](https://sandbox.transactbridge.com/account/accountSetting) Navigate to callback Url's section under the Account settings tab to configure the Webhook URL for sandbox environment.

  [**Admin Panel for Production**](https://reseller.transactbridge.com/account/accountSetting) Navigate to callback Url's section under the Account settings tab to configure the Webhook URL for production environment.
</Note>

***

## Callback Response

Partners must respond to the webhook with the following JSON response and an HTTP `200` status code:

```json theme={null}
{
  "ack": true
}
```

* Only the above response with an HTTP 200 status code will be treated as a successful acknowledgement of the webhook.

* If the merchant does not acknowledge the webhook, TransactBridge will retry sending the webhook. A maximum of 3 attempts will be made.

* If the partner fails to acknowledge the webhook after all 3 attempts, TransactBridge will stop sending subsequent retries for that event.

* Partners can also resend the webhook from the Partner Dashboard if required.

***

## Signature Verification

TransactBridge uses the same method to generate the signature that is included in the authorization headers.

Partners should verify the signature before processing the webhook to ensure that the request originated from the TransactBridge server and that the payload has not been modified.

***

## Sample Session Status

This webhook event is sent to the configured partner URL when the session has a status change. Session status can be **CREATED , STARTED, CLOSED, EXPIRED, FAILED**.

```json theme={null}
{
    "callbackType": "BILLINGSESSION",
    "status": "CLOSED",
    "referenceId": "1708001715",
    "tbId": "65ce09b363f60144efcfbed1",
    "payMethod": "NB",
    "quoteAmount": "199",
    "timestamp": "2024-02-15T12:56:08.810Z",
    "totalTax": "35.81",
    "network": "State bank of India",
    "code": 1033,
    "param1": "paramValue1",
    "param2": "paramValue2",
    "param3": "paramValue3"
}
```

<Note>
  There are other conditional parameters in the billing session api, which can be passed by the merchant at the time of session creation. And these parameters will be sent back to the merchant in the webhook response.
</Note>

***

## Sample Transaction Status

This webhook event is sent to the configured partner URL whenever the **transaction status changes**. The transaction can have one of the following statuses: **`PENDING`**, **`PROCESSING`**, **`SUCCESS`**, or **`FAILED`**.

```json theme={null}
{
    "callbackType": "DEPOSIT",
    "status": "SUCCESS",
    "referenceId": "test-tsp-0047",
    "tbId": "68cc61b6b8814a093b6dfe19",
    "payMethod": "UPI",
    "quoteAmount": "100",
    "settleQuoteAmount": "98",
    "timestamp": "2025-09-18T19:48:46.741Z",
    "param1": "",
    "param2": "",
    "param3": "",
    "rrn": "1758224926335"
}
```

***

## Session Status

* **CREATED:** A session has been created but the link has not been used by the customer to initiate the payment window.
* **STARTED:** When the customer opens the payment link and proceeds with accepting TnC.
* **CLOSED:** Payment has been successfully done by the customer and an invoice has been created.
* **EXPIRED:** In case of non-payment, the link will be expired after a configured interval. Partners can pass the expiry date at the time of session creation. The default expiry date is 24 hours from the time of the creation of the session.
* **REJECTED:** This status needs to be enabled by the Admin Team, once done, if a customer clicks on "Back to Shopping" on the payment page then the billing session will be marked REJECTED and no further attempts will be allowed.
* **FAILED:** If Payment has failed in case where isSingleAttempt is passed as true in create session api only the session will be marked as failed.

<Note>
  - If the transaction status is processing or pending in that case the session will be marked as STARTED.
  - Merchant should rely on session status.
</Note>


# Overview
Source: https://developer.transactbridge.com/one-time-payments/product-based-payment-system/overview



# Product-Based Payment Link

A **product-based payment link** allows merchants to collect payments for a specific product without building or maintaining their own website or payment integration.

This solution is particularly useful for **small businesses, freelancers, and merchants with limited technical knowledge**. Merchants can create a product in the TransactBridge Admin Panel, generate a payment link for that product, and share the link directly with customers.

Customers can use the payment link to view the product details and complete the payment.

## About Product-Based Payment Links

With a product-based payment link, the merchant does not need to:

* Build a website or mobile application.
* Integrate the TransactBridge payment APIs.
* Develop a custom checkout page.
* Implement payment collection logic.

Instead, the merchant can manage the product and generate its payment link directly from the **Admin Panel**.

The payment link is associated with a specific product and can be shared with customers through channels such as **WhatsApp, SMS, email, or other communication platforms**.

> **Note:** Currently, product-specific payment links can only be generated through the TransactBridge Admin Panel.

## How to Generate a Product-Based Payment Link

Follow the steps below to create a product and generate its payment link from the Admin Panel.

### Step 1: Navigate to Products

Log in to the **TransactBridge [Admin Panel](https://reseller.transactbridge.com)** and navigate to the **Products** tab.

### Step 2: Create a Product

1. Navigate to the **Items** tab.
2. Click the **Create** icon.
3. The **Create Product** form will open.
4. Enter the required product details, such as:

   * Product name
   * Product description
   * Product price
   * Discount, either as an **amount** or **percentage**
   * Other applicable product details
5. Click **Create**.

The product will be created and listed in the Admin Panel.

### Step 3: Generate the Payment Link

1. Click the **Product ID** of the product you created.
2. Navigate to the **Actions** tab.
3. Select **Product Pay URL**.
4. Copy the generated payment URL.

You can now share this payment link with your customers to collect payment for the product.

## Product Availability and Quantity

The quantity of a product that a customer can purchase depends on the **available inventory** configured for that product.

For example, if the product has an available inventory of 10 units, customers cannot purchase more than the available quantity.

> **Note:** Product availability and purchase quantity are controlled based on the inventory configured for the product.

## Business Use Cases

Product-based payment links are useful for merchants who want to start accepting online payments without investing in a custom website or technical integration.

### Small Businesses

A small business selling products through social media can create products in the TransactBridge Admin Panel and share the corresponding payment links with customers.

**Example:**
A home-based bakery receives an order through WhatsApp. The merchant creates or selects the product in the Admin Panel, generates the product payment link, and sends it to the customer. The customer opens the link and completes the payment.

### Freelancers and Independent Professionals

Freelancers can use product-based payment links to collect payments for predefined services.

**Example:**
A freelance designer offers a logo-design package for ₹5,000. Instead of creating a website or integrating a payment gateway, the freelancer can create the service as a product and share its payment link with the customer.

### Social Media Sellers

Merchants who sell products through platforms such as Instagram or WhatsApp can use payment links to convert customer inquiries into payments.

**Example:**
A customer sees a product on Instagram and contacts the merchant through direct message. The merchant can share the product payment link directly with the customer instead of asking the customer to visit a separate website.

### Offline Businesses

Businesses that interact with customers offline can also use product payment links to collect digital payments.

**Example:**
A merchant can generate a product payment link and share it with a customer through SMS or WhatsApp after taking an order over the phone.

### Merchants Without Technical Resources

This solution is suitable for merchants who do not have developers or technical resources to integrate payment APIs.

The merchant can manage products and payment links entirely from the Admin Panel.

## Session Status

The payment link creates a payment session for the customer. The session status changes based on the outcome of the payment attempts.

| Payment Scenario       | Session Status | Description                                                                                                                                                                                                                                                                 |
| ---------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Payment is successful  | `CLOSED`       | The session is closed after a successful transaction.                                                                                                                                                                                                                       |
| Transaction fails      | `STARTED`      | The session remains active because multiple transaction attempts can be made against a single session.                                                                                                                                                                      |
| Transaction is pending | `STARTED`      | The session remains in a pending state while the transaction is being processed.                                                                                                                                                                                            |
| No payment is made     | `STARTED`      | The session remains in the `STARTED` state for 24 hours.                                                                                                                                                                                                                    |
| Session expires        | `EXPIRED`      | If no payment is made against a session, the session remains in the **`STARTED`** state for **24 hours**. After 24 hours, the session is automatically marked as **`EXPIRED`**. Once the session has expired, no further payment attempts can be made against that session. |

<Note>
  To understand the difference between a **session** and a **transaction**, refer to [Session vs. Transaction](/one-time-payments/get-started-with-one-time-payments/overview#session-vs-transaction).
</Note>

## Webhook

TransactBridge sends a webhook event to the configured **partner URL** whenever the session status changes.

The session can have any of the following statuses:

* `CREATED`
* `STARTED`
* `CLOSED`
* `EXPIRED`
* `FAILED`

The webhook allows the merchant to receive real-time updates about the payment session and take appropriate action on their side.

For more information, refer to the [Webhook](/one-time-payments/manage-your-payments/webhook) documentation.


# Go to live checklist
Source: https://developer.transactbridge.com/one-time-payments/test-your-payments/go-to-live-checklist



## Integration Checklist

To ensure a smooth customer experience and a seamless TransactBridge integration, please complete the following action items.

Please go to [https://reseller.transactbridge.com/forgotPassword](https://reseller.transactbridge.com/forgotPassword) to set your password to use the platform. Use your business registered email with TransactBridge to set the password. Once you have set the password, you can log in to the platform and complete the following.

### Account Setup

* [ ] **Verify your root subdomain**

  Go to **Account Settings** and verify your root subdomain. Once verified, TransactBridge can provide you with subdomain-based redirection URLs.
  **Optional**

* [ ] **Add Callback URLs**

  Add the correct **Callback URLs** under **Account Settings**. This ensures that your application receives timely notifications about relevant events. And the customer can be notified promptly.
  **Mandatory**

* [ ] **Configure your brand theme**

  Update the **color theme** and upload your **brand logo** under **Account Settings** to provide customers with a consistent brand experience throughout the payment journey.
  **Mandatory**

### Team & Access

* [ ] **Add team members**

  Add relevant team members from the **Team Members** page so that different departments of your organization can access and use the platform. Assign appropriate permissions to each team member based on their role.
  **Optional**

### Payment Configuration

* [ ] **Add a bank account**

  Go to the **User Profile** page and add the bank account where you want to receive invoice payables. Make sure that the bank account details are accurate.
  **Mandatory**

### API Configuration

* [ ] **Set up API credentials**

  API credentials will be shared with you separately by email. If you have not received them, you can resend the credentials from the **API** page. You can also create new API credentials from the same page.
  **Optional**

* [ ] **Whitelist your server IPs**

  For additional security, whitelist the IP addresses of your servers from which API requests will originate.
  **Optional**

### Platform Demo

* [ ] **Request a platform demo**

  If your operations team would like a walkthrough of the TransactBridge platform, our team can provide a demo and guide you through the available features.
  **Optional**

## Production Enablement

Once all **mandatory** action items have been completed, reply to the TransactBridge onboarding email. Our team will verify the configuration and enable the platform for **production usage**.


# Overview
Source: https://developer.transactbridge.com/one-time-payments/test-your-payments/overview



Once the integration is complete, you need to test it on the sandbox environment using the sandbox credentials available at API section of the [Sandbox Admin Panel](https://sandbox.transactbridge.com/) and using the [test payment credentials](https://docs.transactbridge.com/#uat-testing) listed here.

When the test transaction is complete, you can move your code to Live or Production environment with production account details.

### Going Live on Production Environment

Replace your sandbox credentials with production credentials.

* API Key
* Secret Key
* Publish Key

<Note>
  Host Details are different for Sandbox and Production. Please configure accordingly.

  * Sandbox: [https://sandbox-api.transactbridge.com](https://sandbox-api.transactbridge.com)
  * Production: [https://api.transactbridge.com](https://api.transactbridge.com)

  The production account details will be available on the [Reseller Admin Panel](https://reseller.transactbridge.com/) only when your account is approved and created by TransactBridge. Please contact your account manager to get the production account created.
</Note>

<Note>
  IP's for sandbox and production are different. Please configure accordingly.

  <Columns>
    <Card title="Sandbox IP Addresses" icon="flask">
      **Allow the following IP addresses for Sandbox:**

      * `15.197.69.154`
      * `76.223.72.108`
      * `13.127.96.158`
      * `35.154.94.13`
    </Card>

    <Card title="Production IP Addresses" icon="server">
      **Allow the following IP addresses for Production:**

      * `15.197.224.201`
      * `15.206.132.31`
      * `76.223.91.111`
      * `13.127.125.65`
    </Card>
  </Columns>
</Note>


# Quicklinks
Source: https://developer.transactbridge.com/quicklinks

Start integrating API in your application in minutes

<CardGroup>
  <Card title="API Endpoints" icon="code" href="https://docs.transactbridge.com">
    Check our postman collection with examples and environment variables for easier integration
  </Card>

  <Card title="No Code Integration" icon="code-simple" href="../checkout.js/checkout/overview">
    Use our Checkout.js library to integrate with your website without writing any code
  </Card>

  <Card title="Check Sandbox" icon="screwdriver-wrench" href="https://sandbox.transactbridge.com">
    Test your integration in our sandbox environment
  </Card>

  <Card title="Check Demo Store" icon="stars" href="https://www.transactbridge.com/demo">
    Check our demo store to see how the integration works
  </Card>
</CardGroup>

<Note>
  For any tech related issues, please reach out to our [Tech Support Team](mailto:tech@transactbridge.com)
</Note>


# Coupons
Source: https://developer.transactbridge.com/subscription/getting-started/coupons



## What is a Coupon?

A coupon is a promotional discount applied to subscription invoices. Coupons are configured using the optional
couponDetails object in the Create Subscription request.<br />

**A coupon can define**

* **Discount type**: Percentage discount or fixed-amount discount.
* **Duration**: Controls how long the discount remains valid. supported values-ONETIME, LIMITED PERIOD and FOREVER
* **Merchant-managed validation**: Merchants can maintain their own coupon management system. When a customer enters a coupon code during checkout, Transact Bridge invokes the merchant's coupon validation API to verify the code and determine whether it is valid, applicable to the subscription, and what discount should be applied.

Transact Bridge does not provide an inbuilt coupon management system. The coupon system allows partners to continue using their existing coupon management platform without migrating or recreating coupons in Transact Bridge. Instead of maintaining a separate coupon repository, merchants retain full ownership and control over their coupon lifecycle, including coupon creation, eligibility rules, validity periods, usage limits, discount values, and redemption logic.

<Card title="Coupon application on Subscription" icon="refresh-cw" href="/subscription/manage-subs/apply-coupon/index">
  Learn how to apply coupons in subscription.
</Card>

## Business Use Cases for Coupons

| Business Use Case                | Description                                                                | Example                                                                                                    |
| -------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Promotional Campaigns**        | Offer discounts during seasonal or marketing campaigns to increase sales.  | A SaaS company launches a `SUMMER10` coupon that gives **10% off** on subscriptions purchased during July. |
| **New Customer Acquisition**     | Encourage first-time customers to complete their purchase with a discount. | A customer signing up for the first time enters `WELCOME20` and receives **20% off** the initial payment.  |
| **Limited-Time Offers**          | Run promotions that are valid only for a defined period.                   | A coupon gives **15% off for the first 3 months** of a yearly subscription.                                |
| **Percentage-Based Discounts**   | Reduce the payable amount by a percentage.                                 | Original subscription: ₹1,000/month. Coupon: **10% OFF**. Customer pays **₹900/month**.                    |
| **Fixed Amount Discounts**       | Deduct a fixed monetary amount from the order value.                       | Original price: ₹2,000. Coupon: **₹500 OFF**. Final payable amount: **₹1,500**.                            |
| **Subscription Promotions**      | Apply discounts on recurring subscriptions for a specific duration.        | A streaming platform offers **25% off for the first 6 months** of a monthly subscription.                  |
| **Product Launch Offers**        | Promote newly launched products or plans with introductory discounts.      | A newly launched Premium Plan includes a **15% introductory discount** for early adopters.                 |
| **Customer Retention**           | Encourage existing customers to renew their subscriptions.                 | A subscription nearing expiry is offered a `RENEW10` coupon to receive **10% off** on renewal.             |
| **Targeted Marketing Campaigns** | Provide exclusive coupons to selected customers.                           | Customers who have not purchased in the last 90 days receive a `COMEBACK20` coupon via email.              |


# Different checkout integrations
Source: https://developer.transactbridge.com/subscription/getting-started/different-checkout-integrations

Choose the right checkout integration for your subscription business.

# Checkout Solutions for Subscription Businesses

Transact Bridge provides three checkout solutions for collecting subscription payments. All options support recurring billing while allowing businesses to choose the integration approach that best matches their customer experience and technical requirements.

<CardGroup>
  <Card title="Payment Link" icon="link">
    Generate a hosted subscription payment link and share it with customers via email, SMS, WhatsApp, or any other communication channel.
  </Card>

  <Card title="Iframe" icon="browser">
    Embed the Transact Bridge checkout directly within your website or application to provide a seamless in-app payment experience.
  </Card>

  <Card title="Drop in" icon="browser">
    The **Drop-in Checkout** solution provides greater flexibility and customization compared to a traditional iframe integration. While both options allow customers to complete payments without leaving your website, Drop-in Checkout offers tighter integration with your application's user experience.
  </Card>
</CardGroup>

***

## 1. Payment Link

A hosted checkout page that can be generated using the Billing Session or Subscription APIs and shared with customers.

### Business Use Cases

| Business           | Use Case                                                                | Benefit                         |
| ------------------ | ----------------------------------------------------------------------- | ------------------------------- |
| SaaS               | Send subscription renewal links to customers                            | No website integration required |
| EdTech             | Share course subscription links through email or WhatsApp               | Quick customer onboarding       |
| OTT Platform       | Offer monthly or yearly subscription links                              | Fast payment collection         |
| Fitness Membership | Send membership renewal reminders with payment links                    | Improves renewal rate           |
| B2B Software       | Sales team manually shares subscription links with enterprise customers | Suitable for assisted sales     |

<Info>
  **Payment Link** is ideal for businesses that need the fastest integration or collect payments through email, SMS, WhatsApp, invoices, or other offline channels.
  Choose Payment Links when customers do not necessarily begin their journey from your website or when your sales process is assisted by your sales or support team.
</Info>

***

## 2. Iframe

The Iframe Checkout SDK is a JavaScript-based iframe Payment SDK that allows merchants to easily embed the checkout experience directly inside their application or website without the customer leaving your platform.

### Business Use Cases

| Business              | Use Case                                 | Benefit                       |
| --------------------- | ---------------------------------------- | ----------------------------- |
| SaaS Platform         | Customer upgrades from Basic to Pro plan | Seamless checkout experience  |
| Cloud Services        | Customer purchases additional credits    | No page redirection           |
| Gaming Platform       | Subscribe to premium membership          | Higher conversion rate        |
| Productivity Software | Purchase monthly or annual subscription  | Consistent branded experience |
| Streaming Platform    | Upgrade subscription plan                | Reduced checkout abandonment  |

<Info>
  **Iframe Checkout** is suitable for businesses that want to embed a secure payment form within their website with minimal implementation effort.
  Also, when maintaining your application's branding and minimizing customer redirections are important.
</Info>

## 3. Drop-in Checkout for Subscription Businesses

TBDropin is a JavaScript-based Drop-in Payments SDK that allows merchants to easily embed secure & PCI-compliant payment components into their applications.
It provides pre-built payment elements with flexibility of styling them (UPI, Cards, T\&C, etc.) and ensuring sensitive payment data never touches the merchant’s servers to adhere to compliances.

With a simple script include and a few lines of JavaScript, merchants can:

* Create their own checkout experience with pre-built payment components
* Collect payment details securely without handling sensitive data on their servers
* Trigger payments with a unified pay() API to handle all payment methods
* Receive payment status updates through webhooks & SDK events for real-time processing
  ​

### Business Use Cases

| Business              | Subscription Scenario                                 | Why Drop-in Checkout?                                                                     |
| --------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| SaaS Platform         | Customer subscribes to Basic, Pro or Enterprise plans | Embedded checkout provides a seamless upgrade experience without leaving the application. |
| AI Platform           | User purchases monthly AI credits                     | Keeps users inside the product during subscription activation.                            |
| Streaming Platform    | Monthly or annual content subscription                | Branded checkout improves customer trust and conversion.                                  |
| Gaming Platform       | Premium membership purchase                           | Smooth in-app payment experience with recurring billing support.                          |
| Productivity Software | Upgrade from Free to Premium                          | Customers complete payment without page redirects.                                        |
| Membership Portal     | Paid community or professional membership             | Simple onboarding and automatic recurring renewals.                                       |

<Info>
  **Drop-in Checkout** is recommended for businesses seeking a highly customizable, seamless checkout experience with greater control over the customer journey, UI interactions, and subscription workflows.
</Info>

***


# Frequencies
Source: https://developer.transactbridge.com/subscription/getting-started/frequencies



## Subscription Frequencies

The subscription frequency determines how often a subscription billing cycle occurs and when the recurring amount is charged.

### Frequency Options

| Frequency   | **Code**   | Billing Cycle          | Example                    |
| ----------- | ---------- | ---------------------- | -------------------------- |
| Daily       | **`DAIL`** | Every day              | ₹100 every day             |
| Weekly      | **`WEEK`** | Every 7 days           | ₹500 every week            |
| Monthly     | **`MNTH`** | Every month            | ₹999 every month           |
| Bi-Monthly  | **`BIMN`** | Every 15 days          | ₹1,800 every 15 days       |
| Quarterly   | **`QURT`** | Every 3 months         | ₹2,500 every 3 months      |
| Half-Yearly | **`MIAN`** | Every 6 months         | ₹5,000 every 6 months      |
| Yearly      | **`YEAR`** | Every 12 months        | ₹10,000 every year         |
| On-Demand   | **`ONDM`** | Charged when requested | ₹1,000 per service/request |

### Frequency Illustration

The billing frequency determines the start and end of each billing period.

```mermaid theme={null}

flowchart TD
    A[Subscription Starts] --> B{Frequency}

    B -->|DAIL| C[1 Day Billing Cycle]
    B -->|WEEK| D[7 Day Billing Cycle]
    B -->|MNTH| E[1 Month Billing Cycle]
    B -->|BIMN| F[2 Month Billing Cycle]
    B -->|QURT| G[3 Month Billing Cycle]
    B -->|MIAN| H[6 Month Billing Cycle]
    B -->|YEAR| I[12 Month Billing Cycle]
    B -->|ONDM| J[Billing Initiated When Required]

    C --> K[Next Billing Cycle]
    D --> K
    E --> K
    F --> K
    G --> K
    H --> K
    I --> K

    K --> L[Recurring Invoice / Collection]
    L --> M[Next Billing Cycle]

    J --> N[Payment / Invoice<br/>Generated on Demand]
    N --> O[Next On-Demand Billing]
    O --> J
    
```

### Monthly Frequency Example

For a subscription with:

```json theme={null}
{
  "frequency": "MNTH"
}
```

The subscription follows a monthly billing cycle.

For example:

```text theme={null}
August 1
   ↓
Billing Period
August 1 ───────── August 31
   ↓
Renewal
September 1
   ↓
Next Billing Period
September 1 ───── September 30
```

### Weekly Frequency Example

For a weekly subscription:

```text theme={null}
August 1
   ↓
August 1 ─── August 7
   ↓
Next Billing Cycle
August 8 ─── August 14
   ↓
Next Billing Cycle
August 15 ── August 21
```

## Fixed Frequency vs. On-Demand Frequency

| Feature                | Fixed Frequency                                             | On-Demand Frequency                                                    |
| ---------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Definition**         | Follows a predefined recurring billing schedule.            | The merchant generates a payment request whenever billing is required. |
| **Invoice generation** | Automatic, based on the configured frequency.               | Generated only when the merchant initiates billing.                    |
| **Collection**         | Auto-debit is attempted at each billing cycle.              | Collection occurs only after the merchant creates the request.         |
| **Frequency value**    | `DAIL`, `WEEK`, `MNTH`, `BIMN`, `QURT`, `MIAN`, `YEAR`      | `ONDM`                                                                 |
| **Best suited for**    | Fixed recurring schedules.                                  | Variable, usage-based, or pay-per-use billing.                         |
| **Examples**           | Monthly memberships, OTT subscriptions, insurance premiums. | Utility bills, cloud services, usage charges.                          |


# Overview
Source: https://developer.transactbridge.com/subscription/getting-started/overview



# Subscriptions

TransactBridge Subscriptions allow merchants to set up **recurring payments** for products or services. A subscription defines the billing frequency, amount, payment flow, invoice behavior, and rules for handling failed payments.

Customers can subscribe through a [**shareable Payment link**](https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825) that opens a hosted payment page. Once the subscription is created and the customer completes the required payment or payment-method setup, the subscription is reflected in the TransactBridge panel. Webhooks and callbacks can also be configured to receive real-time subscription and payment updates.

## Subscription Types

TransactBridge supports two subscription billing models:

| Type         | Description                                                                                                               | Configuration        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **Prepaid**  | The customer pays before receiving access to the service. The amount is collected at the beginning of the billing period. | `billAtStart: true`  |
| **Postpaid** | The customer uses the service first and is charged at the end of the billing period.                                      | `billAtStart: false` |

## Subscription Lifecycle

A subscription can move through different states during its lifecycle:

```mermaid theme={null}
flowchart LR
    A[PENDING] --> B[TRIAL]
    A --> C[ACTIVE]
    B --> C
    C --> D[PAUSED]
    D --> C
    C --> E[CANCELLED]
    C --> F[EXPIRED]
    A --> G[PENDING_EXPIRED]
    C --> H[FAILED]
```

| Status            | Description                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| `PENDING`         | Subscription is created and the customer can complete the payment or activation process.              |
| `PENDING_EXPIRED` | Customer did not complete the subscription before the configured expiry period.                       |
| `TRIAL`           | Subscription is in its trial period.                                                                  |
| `ACTIVE`          | Subscription is active and recurring billing can take place.                                          |
| `PAUSED`          | Subscription has been temporarily paused, either by the partner or based on configured payment rules. |
| `EXPIRED`         | Subscription has reached its expiration state.                                                        |
| `CANCELLED`       | Subscription has been cancelled by the customer, partner, or system configuration.                    |

## Key Subscription Configurations

When [creating a subscription](https://docs.transactbridge.com/#b075df15-b1ef-49ab-8871-6eaf2224dfb8), merchants can configure several parameters to control billing and payment behavior.

| Parameter                    | Purpose                                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------------------- |
| `frequency`                  | Defines the recurring billing cycle.                                                        |
| `billAtStart`                | Determines whether the subscription is prepaid or postpaid.                                 |
| `maxQuoteAmount`             | Defines the maximum amount that can be auto-debited using the mandate.                      |
| `billingDateAnchor`          | Allows billing to occur on a specific day of the month.                                     |
| `dayUntillDue`               | Defines how long an invoice can remain due before becoming overdue.                         |
| `maxUnpaidInvoices`          | Defines the maximum number of unpaid invoices allowed.                                      |
| `postMaxUnpaidInvoices`      | Defines the subscription status after the unpaid-invoice limit is exceeded.                 |
| `reAttemptConfig`            | Configures retry attempts for failed invoice payments.                                      |
| `trialSettings`              | Configures the subscription trial period and payment-method requirements.                   |
| `discount` / `couponDetails` | Allows discounts or coupons to be applied to the subscription.                              |
| `maxUnpausedInvoiceDueCount` | Controls when a paused subscription can be reactivated after outstanding invoices are paid. |

## Billing Date Anchor

The `billingDateAnchor` parameter allows the merchant to define a fixed billing date.

For example, if:

```json theme={null}
{
  "frequency": "MNTH",
  "billingDateAnchor": "2"
}
```

the invoice is generated on the **2nd day of each month**, instead of using the customer's subscription start date as the billing date.

## Failed Payments and Retries

TransactBridge allows merchants to configure how failed or unpaid invoices should be handled.

The merchant can configure:

* Number of allowed unpaid invoices using `maxUnpaidInvoices`
* Number of days before a due invoice becomes overdue using `dayUntillDue`
* Retry attempts using `reAttemptConfig`
* The subscription state after the unpaid-invoice threshold is reached using `postMaxUnpaidInvoices`

This allows merchants to define whether a subscription should be **paused, expired, cancelled, or retried** when payments remain unpaid.

## Summary

TransactBridge subscriptions provide a flexible recurring billing mechanism that supports:

* Prepaid and postpaid billing
* Multiple billing frequencies
* Trial periods
* Fixed billing dates
* Coupons
* Automatic payment collection
* Failed-payment retries
* Pause, resume, cancellation, and expiration
* Webhooks and callbacks for subscription updates
* Hosted subscription payment links and checkout integrations

This flexibility allows subscriptions to be configured for fixed-price plans as well as usage-based billing models.


# Prepaid And Postpaid Subscription
Source: https://developer.transactbridge.com/subscription/getting-started/prepaid-postpaid

TransactBridge supports two primary subscription billing models: Prepaid and Postpaid.

## PREPAID

Pay first-->Use later
prepaid subscription is a billing model in which the customer pays the subscription amount in advance, and only after the payment is successful is the customer granted access to the service.
A prepaid subscription requires the customer to pay before accessing the service. The recurring amount is also collected before each renewal of the subscription.

### Configuration

**Create Subscription request**

```json theme={null}
{
  "billAtStart": true
}
```

<Info>
  If **billAtStart** is not supplied in the **Create Subscription API**, the backend treats it as `true`, and the subscription follows the prepaid model.
</Info>

Examples include Netflix, Spotify, Microsoft 365, memberships, and other services where access follows successful payment.

***

### Creation and Activation

1. The merchant calls the <a href="https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825">Create Subscription API </a> with `billAtStart: true`.
2. The subscription enters the **PENDING** state.
3. TransactBridge returns the subscription ID and payment URL.
4. The customer completes the initial payment using available payment methods through the hosted checkout at TransactBridge or through SDKs (Dropin or iframe).
5. After successful payment, the subscription becomes **ACTIVE** and service access can begin.

***

### Renewal and Collection

At the start of each renewal cycle, TransactBridge generates the invoice and attempts to collect the amount before the next service period begins. If collection succeeds, access continues. If it fails, the configured retry, due, overdue, and unpaid-invoice policies are applied.

> **Figure** : Prepaid subscription activation and renewal flow

```mermaid theme={null}
flowchart TB

A["Create<br/>billAtStart: true"]
--> B["PENDING"]
--> C["Hosted Checkout<br/>and Initial Payment"]

C --> D{"Payment<br/>Succeeds?"}

D -->|Yes| E["ACTIVE<br/>Service Access Begins"]

B -->|No / Expires| F["If Checkout Expires Before Payment<br/>PENDING_EXPIRED (Terminal)"]

E --> G["Next Cycle Begins<br/>Invoice Generated First"]

G --> H["Automatic Collection<br/>from Saved Mandate"]

H --> I{"Renewal<br/>Payment?"}

I -->|Success| J["Next Billing Cycle"]

J --> G

I -->|Failure| K["Retries, Due Handling,<br/>or Overdue Policy"]

K --> G
```

***

**Example:** Consider a Monthly plan

On **1st August**, the customer pays **₹999** and receives access from **1st August to 31st August**. Before the next period begins on **1st September**, the renewal amount is automatically debited. If the renewal succeeds, access will continue for the next month.

## POSTPAID

Use first-->Pay Later
a postpaid subscription is a billing model where the customer consumes the service first and pays later, at the end of the billing period.
This model is intended for businesses where the final amount depends on the customer's usage during the billing cycle, such as metered or resource-based billing.
A postpaid subscription allows the customer to use the service first and pay later. Charges are determined after the billing period based on the configured billing model, contract, or actual usage.

### Configuration

**Create Subscription request**

```json theme={null}
{
  "billAtStart": false
}
```

<Info>
  Note: No initial full amount is collected at the beginning of the billing period, but to make sure at the end of cycle platform is able to deduct the amount from customer timely, a payment mandate must be authorized by the customer for future debits.
  Examples include cloud services, utilities, and telecom postpaid plans.
</Info>

***

### Creation and Activation

1. The merchant creates the subscription with `billAtStart: false`.
2. The subscription enters the **PENDING** state.
3. TransactBridge returns the subscription ID and payment URL.
4. The customer completes the hosted checkout by adding or authorizing a payment mandate, such as a UPI AutoPay or debit/credit card Mandate.
5. After successful authorization, the subscription becomes **ACTIVE**. The customer does not need to pay the first postpaid invoice to activate the subscription.

***

### Invoice Generation and Approval

* **Billing cycle end:** TransactBridge generates an invoice at the end of the billing cycle.
* **Billing Date Anchor:** If configured, the invoice is generated on the fixed anchor date like 5th of the month irrespective of when the subscription actually starts.
* **Draft invoice webhook:** TransactBridge sends the merchant a draft invoice webhook so that the merchant can update the invoice amount based on actual usage or billing inputs.
* **Approval window:** The merchant has 24 hours to update and approve the draft invoice. If no action is taken within that period, the invoice is automatically marked as approved.
* **Collection:** After approval, TransactBridge attempts to collect the approved invoice amount using the saved payment mandate.

<Info>
  Note: **Draft invoice webhook** & **Approval window** only applies to postpaid subscriptions. Prepaid subscriptions do not have this step as there is no metered billing that would change the invoice amount.
</Info>

> **Figure**:  Postpaid usage, invoice approval, and collection flow

```mermaid theme={null}
flowchart TB

A["Create<br/>billAtStart: false"]
--> B["PENDING"]
--> C["Hosted Checkout<br/>Mandate Authorization"]
--> D["ACTIVE"]
--> E["Customer Uses<br/>Service"]
--> F["Cycle End or<br/>Billing Date Anchor"]

F --> G["Draft Invoice Generated<br/>Webhook Sent"]

G --> H["Merchant Updates &<br/>Approves Within 24 Hours"]

H --> I["Auto-Approved if No<br/>Action Within 24 Hours"]

H --> J["Collection Attempted<br>Using Saved Payment Mandate<br/>"]

I --> J

J --> K{"Payment<br/>Succeeds?"}

K -->|Yes| L["Next Billing Cycle"]

L --> F

K -->|No| M["Retries, Due Handling,<br/>Overdue, or Subscription Action<br/>as per Configuration"]

M --> F
```

**Business Example:** Cloud services

The customer uses cloud resources throughout **August**. At the end of the month, the total usage is calculated and an invoice is generated. The invoice may be updated and approved by the merchant, after which payment is collected using the customer's saved payment mandate.

***

**Comparison between Prepaid & Postpaid**

| Module                      | Prepaid                                 | Postpaid                                           |
| --------------------------- | --------------------------------------- | -------------------------------------------------- |
| Billing timing              | Before the service period               | After the service period or according to usage     |
| Activation requirement      | Successful initial payment              | Successful payment-method or mandate authorization |
| Invoice timing              | Beginning of the billing cycle          | End of the billing cycle                           |
| Create Subscription setting | `billAtStart: true`                     | \`billAtStart: false'                              |
| Typical examples            | OTT, memberships, productivity software | Cloud services, utilities, telecom postpaid plans  |

**Subscription Model Selection**

```mermaid theme={null}
%%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%
flowchart TB

    A([Create Subscription API])
    B[PENDING]
    C{"billAtStart?"}

    D["Prepaid<br/>Customer pays first"]
    E["Postpaid<br/>Customer authorizes mandate"]

    F([ACTIVE])

    G["Checkout not completed<br/>before <b>'pendingExpire'</b>"]
    H["PENDING_EXPIRED<br/><b>Terminal state</b>"]

    A --> B
    B --> C

    C -->|true| D
    C -->|false| E

    D --> F
    E --> F

    B -. timeout .-> G
    G --> H

    classDef pending fill:#f3f4f6,stroke:#6b7280,color:#111827;
    classDef active fill:#e8f5e9,stroke:#2e7d32,color:#111827;
    classDef prepaid fill:#e3f2fd,stroke:#1976d2,color:#111827;
    classDef postpaid fill:#e0f2f1,stroke:#00897b,color:#111827;
    classDef expired fill:#ffebee,stroke:#d32f2f,color:#111827;
    classDef decision fill:#fff8dc,stroke:#b8860b,color:#111827;

    class B pending;
    class C decision;
    class D prepaid;
    class E postpaid;
    class F active;
    class G,H expired;
```

***


# Products
Source: https://developer.transactbridge.com/subscription/getting-started/products



## Product Configuration

Transact Bridge provides flexible product configuration options to support different merchant integration models. Depending on your business requirements, products can either be pre-configured in the Transact Bridge dashboard or created dynamically during checkout.

### Product Listing Options

<CardGroup>
  <Card title="Mandatory Product Listing" icon="package">
    Products are pre-configured in the Transact Bridge dashboard before transactions are processed. This approach is recommended for businesses with a fixed product catalog and predefined pricing and tax rules.
  </Card>

  <Card title="Dynamic Product Listing" icon="sparkles">
    Products are created dynamically using the details passed in the payment or billing session request. This is ideal for businesses with frequently changing products, pricing, or custom orders.
  </Card>
</CardGroup>

***

## Mandatory Product Listing

With Mandatory Product Listing, merchants maintain their product catalogue within Transact Bridge. Each product can be configured with its pricing, tax configuration, and other product attributes in advance.

### Business Benefits

* Centralized product catalogue management.
* Consistent pricing across all sales channels.
* Product-level tax configuration.
* Simplified reporting and reconciliation.

### Tax Configuration

Taxes can be configured at the product level, allowing each product to have its own applicable tax rules.

If a transaction contains multiple products with different tax rates, Transact Bridge automatically determines the applicable tax based on the configured **Product Reference ID** or the associated **Tax ID**, ensuring accurate tax calculation for every item.

***

## Dynamic Product Listing

Dynamic Product Listing enables merchants to create products on demand during checkout without pre-configuring them in the dashboard.

The products and their attributes are supplied as part of the Create Session or Checkout request. After a successful transaction, the products are automatically recorded for reporting and reconciliation purposes.

### Business Use Cases

| Business        | Example                                                |
| --------------- | ------------------------------------------------------ |
| SaaS Platforms  | Custom enterprise pricing generated for each customer. |
| AI Platforms    | Usage-based credits calculated at checkout.            |
| Event Ticketing | Tickets generated dynamically for each event.          |
| E-commerce      | Custom bundles or personalized product combinations.   |
| B2B Sales       | Quote-based orders with merchant-defined pricing.      |

<Info>
  Dynamic Product Listing is recommended when products, pricing, or quantities vary per transaction and maintaining a fixed product catalogue is not practical.
</Info>

***

## Static Product Pricing

Merchants can configure products with a fixed selling price by enabling **Static Quote Price**.

When **Static Quote Price** is set to **true**, the configured **Quote Price** stored for the product becomes the authoritative selling price. Any amount passed for that product in the Create Session API request is ignored, and the transaction is processed using the predefined Quote Price.

### Business Benefits

* Prevents price manipulation from client applications.
* Ensures consistent pricing across all payment channels.
* Simplifies pricing management for fixed-price products.
* Reduces pricing discrepancies during checkout.

<Info>
  Use Static Quote Price when product pricing is controlled by the merchant and should remain consistent regardless of the amount passed during session creation.
</Info>

***

## Choosing the Right Product Configuration

| Requirement                        | Mandatory Product Listing | Dynamic Product Listing |
| ---------------------------------- | ------------------------- | ----------------------- |
| Fixed product catalogue            | ✅ Recommended             |                         |
| Frequently changing products       |                           | ✅ Recommended           |
| Product-level tax configuration    | ✅ Supported               | ✅ Supported             |
| Custom pricing per transaction     |                           | ✅ Supported             |
| Faster checkout configuration      | ✅                         |                         |
| Personalized or quote-based orders |                           | ✅                       |
| Centralized catalogue management   | ✅                         |                         |


# Supported Payment Methods
Source: https://developer.transactbridge.com/subscription/getting-started/supported-payment-method



Currently, transact Bridge supports the following payment methods to collect the recurring payments:

| Payment Mode | Country | Min Limit | Max Limit | Pre-Debit Notify |
| ------------ | ------- | --------- | --------- | ---------------- |
| UPI          | India   | ₹1        | ₹15,000   | 24 Hours         |
| Debit Card   | India   | ₹1        | ₹1,00,000 | 48 Hours         |
| Credit Card  | India   | ₹1        | ₹1,00,000 | 48 Hours         |

<Note>
  * This Max Limit is inclusive of taxes.

  * Depending on the payment method and jurisdiction, a pre-debit notification is sent to the customer before the recurring payment is collected. The notification period varies based on the payment method and local regulations.

  * **Additional Factor of Authentication** is required for cards in India for transactions above <b>Rs. 15000</b>
</Note>


# Taxation
Source: https://developer.transactbridge.com/subscription/getting-started/taxation



Different countries have different tax rules and regulations for different products. Within the same country also, different products are taxes according to different jurisdictions.
TransactBridge allows to automate merchant's entire sales tax, VAT, and GST compliances without the overhead of maintaining tax logic and rules in the merchant's system. We  configure tax rules for different products and jurisdictions at our end, which will be applied automatically during billing.

> Tax configuration helps automate tax calculation during billing, reducing manual effort and improving compliance.

***

## Business Use Cases

| Business Use Case                     | Description                                                                | Example                                                                                                                            |
| ------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Digital SaaS Products**             | Apply GST or applicable taxes on software subscriptions sold to customers. | A SaaS company selling a ₹2,000 monthly subscription automatically adds the configured GST before invoice generation.              |
| **One-Time Digital Purchases**        | Calculate taxes on one-time purchases such as software licenses or eBooks. | A customer purchases an eBook for ₹500, and the applicable tax is automatically included in the final payable amount.              |
| **Recurring Subscriptions**           | Apply tax on every recurring billing cycle without manual intervention.    | A monthly subscription renews every month, and tax is calculated automatically for each invoice.                                   |
| **Global Merchants Selling in India** | Ensure Indian tax compliance while selling to Indian customers.            | A US-based SaaS company uses TransactBridge to calculate and apply taxes for Indian customers without maintaining local tax logic. |
| **Invoice Generation**                | Generate invoices containing itemized tax details for customers.           | Every completed payment includes a downloadable invoice showing subtotal, tax amount, and total payable amount.                    |
| **Financial Reconciliation**          | Maintain accurate tax records for accounting and reporting.                | Finance teams reconcile monthly collections using invoices that already contain tax breakdowns.                                    |

***

## Example

### Product Price

* Subscription Price: **₹2,000**
* Applicable GST: **18%**

| Description         |     Amount |
| ------------------- | ---------: |
| Subscription Amount |     ₹2,000 |
| GST (18%)           |       ₹360 |
| **Total Payable**   | **₹2,360** |

During checkout, the configured tax is automatically added to the order, and the generated invoice contains the complete tax breakdown for the customer.

***

## Benefits

* Automated tax calculation during checkout
* Tax-compliant invoice generation
* Reduced manual effort and calculation errors
* Simplified financial reporting and reconciliation
* Consistent tax application across one-time and recurring payments


# Trials
Source: https://developer.transactbridge.com/subscription/getting-started/trials



A **trial period** allows customers to use the merchant's product or service free of charge for a predefined duration before the first recurring payment is collected.

Transact Bridge supports both:

* Trial without adding a payment mandate.
* Trial with a payment mandate attached for automatic billing after the trial ends.

## Benefits

<CardGroup>
  <Card title="Increase Conversions" icon="rocket">
    Allow customers to experience your product before making a payment decision.
  </Card>

  <Card title="Reduce Friction" icon="user-plus">
    Offer a seamless onboarding experience with optional payment collection.
  </Card>

  <Card title="Automatic Billing" icon="repeat">
    Automatically transition customers from trial to a paid subscription.
  </Card>

  <Card title="Flexible Configuration" icon="settings">
    Configure trial duration according to your business requirements.
  </Card>
</CardGroup>

***

## Supported Trial Types

| Trial Type                 | Payment Mandate Required | Billing Starts                                                |
| -------------------------- | ------------------------ | ------------------------------------------------------------- |
| Free Trial                 | No                       | After customer adds a payment mandate during the trial period |
| Trial with Payment Mandate | Yes                      | Automatically when the trial expires                          |

<Note>
  The [needPayMethod](https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825) parameter in create subs api determines whether the customer must provide a valid payment method and mandate before the trial can be activated.
</Note>

For example:

```json theme={null}
{
  "trialSettings": {
    "freeTrialExpire": "2026-09-01",
    "needPayMethod": true,
    "reminderBeforeTrialEnd": "2"
  }
}
```

## Trial Lifecycle

```mermaid theme={null}
flowchart TB

A[Customer Starts Subscription]
--> B{Payment Mandate Required?}

B -->|Yes| C[Collect Payment Mandate]
B -->|No| D[Start Trial Immediately]

C --> E[Trial Period]
D --> E

E --> F{Trial Ends}

F --> G[Generate First Invoice]
G --> H[Collect Payment]
H --> I[Subscription Active]
```

***

## Example Timeline

```text theme={null}
Day 1
Customer subscribes
│
├── 14 Day Trial Starts
│
Day 14
Trial Ends
│
├── First Invoice Generated
│
├── Payment Collected
│
Day 15
Recurring Billing Begins
```

***

## Business Use Cases

### SaaS Platforms

Offer a **14-day** or **30-day** trial before charging the customer.

Examples include:

* CRM software
* Project Management
* Accounting Software

### Streaming Platforms

Allow customers to watch premium content for 1 week during the trial period before the first payment.

### Membership Platforms

Provide access to premium features for a limited time before recurring billing begins.

***

## Best Practices

<Info>
  Clearly communicate:

  * Trial duration
  * Billing frequency
  * First billing date
  * Cancellation policy
</Info>

## Trial Subscription Notification

For both **Fixed Frequency** billing and **On-Demand** billing, TransactBridge sends the mandatory pre-debit notification before charging the customer depending on the payment mandate according to local jurisdictions laws.

### Fixed Frequency Billing

For Fixed Frequency Billing, the recurring billing date is determined when the subscription is created. Since the billing schedule is known in advance, TransactBridge can automatically schedule the pre-debit notification within the required regulatory timeline.

**Example**

* Trial ends on **5th August**.
* The first recurring payment is scheduled for **5th August**.
* The pre-debit notification is automatically sent on **3rd August** (or as required by the payment method).
* On **5th August**, the payment is automatically processed, provided the mandate remains valid.

This ensures a seamless transition from the trial period to the paid subscription without requiring any additional action from the merchant.

***

### On-Demand Billing

For On-Demand Billing, the billing date is not predetermined. After the trial period ends, the merchant must explicitly initiate the billing request to collect the payment.

Once the merchant submits the billing request:

1. TransactBridge immediately sends the mandatory pre-debit notification to the customer.
2. A mandatory waiting period is observed before the payment can be processed. The duration depends on the payment method (typically **24–48 hours**).
3. After the notification period has elapsed, TransactBridge debits from the customer's active payment mandate.
4. Webhook notifications are sent to the merchant with the final transaction status.

> **Note:** Unlike Fixed Frequency Billing, there is always a delay between the merchant initiating the billing request and the actual payment collection. This delay is required to comply with the mandatory pre-debit notification regulations for recurring payments.

### Example

Suppose a customer's trial ends on **5th August**.

* **Fixed Frequency Billing:** The payment is already scheduled for **5th August**, so the pre-debit notification is sent in advance, allowing the payment to be collected on the scheduled date.
* **On-Demand Billing:** The merchant initiates the billing request only after the trial ends. TransactBridge then sends the pre-debit notification, waits for the required notification period, and processes the payment afterward. As a result, the payment is collected **1–2 days after the merchant raises the billing request**, depending on the payment method.

<Warning>
  If a payment mandate is collected during signup, TB ensures customers are notified before the first recurring charge in accordance with applicable payment network and regulatory requirements.
  for on demand merchant will notify us when the collection needs to be done and accordingly TB will notify
</Warning>

***


# Integration with Merchant API
Source: https://developer.transactbridge.com/subscription/manage-subs/apply-coupon/api



## Coupon Integration

Coupons allow merchants to offer discounted subscription pricing to customers. A coupon is applied during subscription creation using the `discount` object in Create subscription API.

### Steps For Integration

* Merchant creates and validates the coupon at their end in their own system.
* Merchant passes the coupon details in couponDetails object in <a href="https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825">Create Susbcription API</a>, while creating the  subscription.
* This couponDetails object will define how the discount should be applied.
* This object has different keys such as coupon-name, discount type, discount quote amount, duration type, period unit, period etc.
* Transact Bridge receives the coupon information.
* Merchant renders the Hosted checkout page( with the help of redirect url received in response of create subscription API) with coupon already applied.
* The customer completes the payment using the discounted amount.

### Supported Discount Types

The subscription platform supports the following discount configurations:

| Type               | Description                                                         |
| ------------------ | ------------------------------------------------------------------- |
| **One-time**       | Applied only to the first billing cycle.                            |
| **Limited Period** | Applied for a specified number of billing cycles.                   |
| **Lifetime**       | Applied to every billing cycle until the subscription is cancelled. |

### Integration Flow

```mermaid theme={null}
flowchart LR

A["Create<br/>Coupon"]
B["Create<br/>Subscription"]
C["Attach<br/>Discount"]
D["Customer<br/>Checkout"]
E["Subscription<br/>Activated"]
F["Invoice<br/>Generated"]
G["Discount<br/>Applied"]
 
A --> B --> C --> D --> E --> F --> G
```

### Request Example

```json theme={null}
{
  "couponDetails":{
        "coupon": "TEST",
        "applicable" : true,
        "discountType": "FIX",
        "discountQuoteAmount": "100",
        "durationType" : "LIMITED_PERIOD",
        "periodUnit": "MNTH",
        "period": 6
    },
}
```


# Integration at Customer Checkout
Source: https://developer.transactbridge.com/subscription/manage-subs/apply-coupon/checkout



The coupon system allows the partner the flexibility to use their coupon store and let their customer apply coupon codes at the Transact Bridge checkout page.

Since the coupon validation is performed entirely by the merchant, partners can implement any custom business logic, such as:

* Percentage-based or fixed amount discounts.
* Coupons with start and expiry dates.
* One-time or limited-use coupons.
* Customer-specific or segment-specific offers.
* Product or subscription plan-specific discounts.
* Minimum purchase amount requirements.
* Referral, promotional, loyalty, or campaign-based coupons.

## Customer Coupon Verification Flow

```mermaid theme={null}
sequenceDiagram

participant Customer
participant Checkout as TB Checkout
participant Merchant

Customer->>Checkout: Enter Coupon Code
Checkout->>Merchant: Coupon Verify API
Merchant->>Merchant: Validate Coupon
Merchant-->>Checkout: Valid / Invalid Response

alt Coupon Valid
Checkout->>Customer: Discount Applied
else Coupon Invalid
Checkout->>Customer: Invalid Coupon Message
end
```

***

## Steps for Integration

When a customer enters a coupon code on the hosted checkout page:

1. Transact Bridge calls the configured **<a href="https://docs.transactbridge.com/#e794037e-c3be-4250-a54a-470852f07a37">Coupon Verify API</a>**.
2. The merchant validates the coupon code.
3. The merchant returns the discount details.
4. If the coupon is valid, the discount is applied to the checkout.
5. If the coupon is invalid, an appropriate error message is displayed to the customer.

The expected response from the merchant is described in the **<a href="https://docs.transactbridge.com/#e794037e-c3be-4250-a54a-470852f07a37">Coupon Verify API Documentation</a>**.

***

## Configuring the Coupon Verify API

To configure the Coupon Verify API endpoint:

1. Log in to the **Transact Bridge Dashboard**.
2. Navigate to **Account Settings**.
3. Configure the **Coupon Verify Callback URL** under callback urls.
4. Save the configuration.

Once configured, Transact Bridge will invoke this endpoint whenever a customer attempts to apply a coupon on the hosted checkout.


# Coupons
Source: https://developer.transactbridge.com/subscription/manage-subs/apply-coupon/index



Transact Bridge **does not provide an inbuilt coupon management system**. The merchant owns and manages the coupon system.

Merchants can use their existing coupon infrastructure while using Transact Bridge for subscription checkout and billing.

Transact Bridge supports **two ways** of applying coupons:

1. **Merchant-applied coupons** (Coupon passed during subscription creation in the API)
2. **Customer-applied coupons** (Coupon entered on the hosted checkout)

***

## Coupon Flow

```mermaid theme={null}
flowchart TB

A[Merchant Coupon System]

A --> B{Coupon Applied?}

B -->|Merchant Applies| C[Coupon Passed in<br/>Coupon Object]

B -->|Customer Applies| D[Customer Enters Coupon<br/>on Hosted Checkout]

C --> E[Checkout Opens<br/>Coupon Applied Automatically]

D --> F[TB Calls Coupon Verify API]

F --> G[Merchant Validates Coupon]

G -->|Valid| H[Discount Applied]

G -->|Invalid| I[Error Returned]

H --> J[Customer Completes Payment]
I --> D
E --> J
```

***

# Method 1: Merchant-applied Coupon

The merchant can apply a coupon while creating the subscription by passing the coupon details in the **coupon object**.

The coupon is automatically applied when the customer lands on the Transact Bridge hosted checkout page. The customer does not need to enter the coupon code manually.

For step by step integration with method 1 refer to [API ](/subscription/manage-subs/apply-coupon/api) guide.

***

# Method 2: Customer-applied Coupon

The coupon system allows partners the flexibility to use their own coupon store while enabling customers to enter coupon codes directly on the Transact Bridge hosted checkout page.

When a customer enters a coupon code, Transact Bridge calls the **Coupon Verify API** configured by the merchant.

The merchant validates the coupon in their own system and returns the appropriate response.

***

For step by step integration with method 2 refer to [checkout ](/subscription/manage-subs/apply-coupon/checkout) guide.

***

## Comparison

| Feature                     | Merchant-applied Coupon       | Customer-applied Coupon         |
| --------------------------- | ----------------------------- | ------------------------------- |
| Coupon entered by           | Merchant                      | Customer                        |
| Coupon validation           | Merchant                      | Merchant via Coupon Verify API  |
| Coupon visible on checkout  | Already applied               | Entered by customer             |
| Customer enters coupon code | No                            | Yes                             |
| API callback required       | No                            | Yes                             |
| Typical use cases           | Referral, loyalty, promotions | Public offers, campaign coupons |

***

## Notes

* Transact Bridge does not maintain or store coupons.
* Coupon creation, validation, expiry, and business rules are completely managed by the merchant.
* The Coupon Verify API is invoked only when the customer manually enters a coupon code on the hosted checkout.
* Merchants can support fixed amount discounts, percentage-based discounts, and limited-period promotional offers using their own coupon management system.


# Cancel Subscription
Source: https://developer.transactbridge.com/subscription/manage-subs/cancel-subs



The **Cancel Subscription API** allows a merchant to permanently terminate an active subscription. Once cancelled, the subscription will no longer generate invoices or collect recurring payments.
Canceling a subscription works differently for the Prepaid and Postpaid billing cycles. If cancelAtEnd is used, the subscription will remain in ACTIVE state until the end of the billing cycle. At the end of the billing cycle, the subscription will be auto-canceled, and no new invoice will be raised. If ***cancelNow*** is used, it will change the status from **ACTIVE** to **CANCELLED** then only.

For Prepaid, cancelNow will not revert the amount paid at the start of the cycle but will issue adjustment credits for that customer, which can be used in the future for any subscription payments. Therefore, it is recommended to use cancelAtEnd to cancel a ACTIVE subscription.

For Postpaid, cancelNow and cancelAtEnd can be used. If cancelNow is used, it will raise a pro-rate-based invoice and will try to debit the amount using the auto-debit mandate if available.

<Note>A cancelled subscription cannot be resumed. If the customer wishes to subscribe again, a new subscription must be created.</Note>

***

## Common Use Cases

| Scenario                        | Illustration                                                                                   |
| ------------------------------- | ---------------------------------------------------------------------------------------------- |
| Customer requests cancellation  | The customer no longer wishes to continue the subscription service.                            |
| Service discontinued            | The merchant permanently discontinues the subscribed product or service.                       |
| Account closure                 | The customer closes their account and all recurring billing must stop.                         |
| Fraud or policy violation       | The merchant detects fraudulent activity or a breach of terms and terminates the subscription. |
| Migration to a new subscription | The customer is moved to a new subscription plan that requires creating a new subscription.    |
| Compliance requirements         | Regulatory or business policies require the subscription to be permanently cancelled.          |

***

## Mandate after Cancellation

Once the subscription is marked as CANCELLED, the associated payment mandate will be automatically revoked. This ensures that no further payments are collected from the customer for the cancelled subscription.

***

## Cancel Flow

```mermaid theme={null}
sequenceDiagram

participant Merchant
participant TB as Transact Bridge
participant Subscription

Merchant->>TB: Cancel Subscription API
TB->>Subscription: Validate ACTIVE subscription
Subscription-->>TB: Valid
TB->>Subscription: Update subscription status to CANCELLED
TB->>Subscription: Update mandate status to REVOKED
Subscription-->>TB: Stop future billing
TB-->>Merchant: Success Response
```

***

## Cancel API

Refer to <a href="https://docs.transactbridge.com/#ba15b59d-5704-44b0-8d54-5df8d83199d4"> Cancel API </a> to cancel a subscription.

***

## Notes

* Only subscriptions in the **ACTIVE** state can be cancelled.
* Cancelling a subscription permanently stops future recurring billing.
* No additional invoices are generated after the subscription is cancelled.
* A cancelled subscription cannot be resumed using the Unpause API.
* To restart billing, create a new subscription for the customer.


# Configure trials
Source: https://developer.transactbridge.com/subscription/manage-subs/configure-trials



# Trial Subscription

A **trial** is a predefined period during which the customer can access a subscription before the first recurring payment is collected.

Trials are configured using the optional `trialSettings` object in the <a href="https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825">Create Susbcription API</a> request.

During the trial period, the subscription remains in the **TRIAL** state.

## Trial Activation Flow

The following flow illustrates the two supported trial activation options:

* **Trial with a payment mandate**
* **Trial without a payment mandate**

At the end of the trial, the subscription either proceeds with automatic billing (if a valid payment mandate is available) or follows the configured subscription policy.

***

## Trial with Payment Mandate

In this flow, the customer authorizes or adds a payment mandate while activating the trial.

### Behaviour

* The customer provides or authorizes a payment mandate during trial activation.
* No payment is collected when the trial starts.
* The subscription remains in the **TRIAL** state throughout the trial period.
* If the customer has not cancelled the subscription before the trial ends, Transact Bridge automatically attempts the first recurring payment using the saved payment mandate.

<Note>
  No debit is attempted during the trial period.
</Note>

***

## Trial without Payment Mandate

In this flow, the customer starts the trial without providing a payment mandate.

### Behaviour

* The customer starts using the subscription immediately.
* No payment authorization is required during activation.
* The customer can add a payment mandate at any time while the trial is active.
* When the trial ends:
  * If a payment mandate is available, Transact Bridge attempts to collect the first payment.
  * Otherwise, the subscription follows the configured billing or activation policy.

<Warning>
  If no payment mandate has been added by the end of the trial, automatic billing cannot be performed until one is available.
</Warning>

***

## Comparison

| Feature                                    | Trial with Payment Mandate    | Trial without Payment Mandate       |
| :----------------------------------------- | :---------------------------- | :---------------------------------- |
| Payment mandate required at activation     | ✅ Yes                         | ❌ No                                |
| Payment collected at activation            | ❌ No                          | ❌ No                                |
| Customer can use subscription during trial | ✅ Yes                         | ✅ Yes                               |
| Payment mandate can be added later         | Not required                  | ✅ Yes                               |
| Automatic payment at trial end             | ✅ Using saved payment mandate | ✅ If payment mandate has been added |

## Trial Lifecycle

```mermaid theme={null}
flowchart TD

    A[Create Subscription<br/>with trialSettings]

    A --> B{Payment Mandate<br/>Provided?}

    %% WITH PAYMENT MANDATE
    B -->|Yes| C[Customer authorizes<br/>payment mandate]
    C --> D[Subscription enters<br/>TRIAL state]
    D --> E[No payment is<br/>collected during trial]
    E --> F{Trial Ends?}
    F -->|Customer Cancelled| G[Subscription Cancelled<br/>No renewal debit]
    F -->|Active Subscription| H[Attempt first recurring<br/>payment using saved<br/>payment mandate]
    H --> I[Subscription becomes<br/>ACTIVE]

    %% WITHOUT PAYMENT MANDATE
    B -->|No| J[Trial starts without<br/>payment authorization]
    J --> K[Subscription enters<br/>TRIAL state]
    K --> L[Customer may add<br/>payment mandate later]
    L --> M{Trial Ends?}
    M -->|Payment Mandate Added| N[Collect first payment]
    N --> O[Subscription becomes<br/>ACTIVE]
    M -->|No Payment Mandate| P[Follow configured<br/>subscription policy]
```

## API Configuration

Trials are enabled by including the optional `trialSettings` object in the <a href="https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825">Create Susbcription API</a> request.

```json theme={null}
{
  "trialSettings": {
    "trialPeriod": 14,
    "trialPeriodUnit": "DAY"
  }
}
```

Refer to the **Create Subscription API** documentation for all supported `trialSettings` parameters.


# Create subscription
Source: https://developer.transactbridge.com/subscription/manage-subs/create-subscription



## Sample Request for create Subscription

```json theme={null}
{
  {
    
    "returnUrl": "https://www.google.com",
    "quoteCurrCode": "INR",
    "items": [
        {
            "name": "ProductName4",
            "description": "ProductDescriptoin1",
            "amount": 100,
            "quantity": 1
        },
        {
            "name": "ProductName5",
            "description": "ProductDescriptoin2",
            "amount": 60,
            "quantity": 2
        }
       
    ],
    
    "billTo": {
        "name": "XYZ",
        "postalCode": "110001",
        "country": "INDIA"
    },
    "name": "XYZ",
    "email": "customer30@gmail.com",
    
    "description": "Testing first subscription end to end",
    "maxQuoteAmount": "500",
    
    "billAtStart": true,
    "pendingExpire": "120",
    
    "dayUntillDue": "2",
    "frequency": "MNTH",
    "maxUnpaidInvoices" : "2",
    "postMaxUnpaidInvoices": "PAUSED",
    "maxUnpausedInvoiceDueCount" : "1",
    
}
}

```

### Parameter's Description

* **pendingExpire**: Number of minutes after which, if the status of the subscription is PENDING (Customer did not pay), it becomes PENDING\_EXPIRED, which is a terminal state, and now customers cannot pay on the same subscription.

  By default that subs will be marked as expired by the system after 24 hrs. However, with the help of the pendingExpire param, this time can be reduced to a minimum: 10 mins to a max of 7 days.

* **dayUntillDue**: Period of time from the issue date after which DUE invoice is converted into OVERDUE status.

* **maxUnpaidInvoices**: Maximum number of unpaid invoices allowed for a subscription. If the number of unpaid invoices exceeds this limit, the subscription status will be paused.

* **postMaxUnpaidInvoices**: Subscription status after maxUnpaidInvoices the threshold is crossed by the customer.
  Default Value: PAUSED

* **maxUnpausedInvoiceDueCount**: Maximum number of unpaid invoices count allowed after that the subscription is PAUSED by the system. For Ex: If a subscription has been paused due to 3 non payment of invoices and this parameter is set to be 2 then once the customer pays 1 invoice the subscription will be re activated.

* **billTo**: Billing Details of the customer.

* **items**: Items the customer wants to buy.

* **returnUrl**: The URL to which the customer will be redirected after completing the payment. This can be a success page or a failure page based on the payment status.

* **frequency**: Frequency of the subscription renewal period.

* **billAtStart**: If this is true, then the subscription is prepaid based subscription and allows to deduction of money before providing the product to the end customer and generating the invoice at the start of the subscription period. If this is false then it is a postpaid subscription which creates an invoice at the end of the subscription period.

* **billingDateAnchor**: Some types of billing cycles need to be started from a specific date of a month. An example of this is Amazon Web Services, where the invoice will always be raised on the 1st day of the month, even if the customer started using the platform on the 15th of the month.


# Credit adjustments
Source: https://developer.transactbridge.com/subscription/manage-subs/credit-adjustments



# Credit Adjustment on a Prorated Basis

Proration adjusts subscription charges when a plan or service state changes before the current billing cycle ends. Instead of
charging the full amount again, the system calculates the unused value of the current plan and the cost of the new plan or
service period for the remaining days.

* **Day-based calculation**: The `prorate` value on each subscription item enables TransactBridge to calculate the charge
  according to the number of days actually consumed.
* **Net payable**: The customer pays only the difference when the new cost is higher than the unused credit.
* **Credit balance**: When the unused value is higher, the balance can be added to the customer's credit(which can be made
  visible on merchant dashboard) and later applied to another invoice, or shown separately, based on the merchant's policy.
* **Billing anchor use case**: When invoices are always generated on a fixed date, proration ensures that the initial partial
  period is billed fairly.
* **Pause/resume use case**: The merchant may charge only for active days or create a prorated credit.
* **Upgrade/downgrade use case**: The merchant can grant immediate access to the new plan and calculate the charge or
  credit for the remaining period.

**For example**:
A monthly subscription is paused on the 15th and resumed on the 30th. Depending on the merchant's policy, the
customer may be charged only for the active days, or a credit may be created for the unused period.

```text theme={null}
Calculation
Prorate= 1.1 (Merchant shares it upfront in the prorate parameter,
 that means 10% extra cost as prorate is used.)
Basic plan= 500/month
Total no of days=30
No of days for which services were used= 15 days
Credit used is= (500/30)*1.1*15=275 Rs
500-275=225 will be credited.
```

**This is handled by Transact Bridge**

# Credit Adjustment for GST-Inclusive Plans

When a subscription plan is downgraded during an active billing cycle, the unused amount from the current plan can be adjusted against the cost of the downgraded plan for the remaining days of the billing cycle.

### Example

Assume the following:

* **GST:** 18%

* **Billing frequency:** Monthly

* **Original plan price:** ₹500 (GST-inclusive)

* **Subscription start date:** September 1

* **Plan downgrade date:** September 15

* **Days in billing cycle:** 30

* **STEP 1:** Calculate the base amount of the original plan

Since the plan price of ₹500 is GST-inclusive:

**Base Amount = ₹500 / 1.18 = ₹423.72**

* **STEP 2:** Calculate the consumed amount for the first 15 days

The daily base cost is:

**₹423.72 / 30 = ₹14.12 per day**

Assuming a **10% proration adjustment factor**, the prorated cost for 15 days is:

**₹14.12 × 15 × 1.10 = ₹233.05**

Therefore, **₹233.05** is considered the amount consumed during the first 15 days of the billing cycle.

* **STEP 3:** Calculate the unused balance from the original plan

The unused balance is calculated as:

**₹423.72 − ₹233.05 = ₹190.67**

Therefore, **₹190.67** is the remaining balance from the original plan.

* **STEP 4:** Calculate the cost of the downgraded plan

The downgraded plan costs **₹300 (GST-inclusive)**.

Its base amount is:

**₹300 / 1.18 = ₹254.24**

The daily base cost is:

**₹254.24 / 30 = ₹8.47 per day**

The prorated cost for the remaining 15 days is:

**₹8.47 × 15 × 1.10 = ₹139.75**

* **STEP 5:** Calculate the credit adjustment

The credit adjustment is the difference between the unused balance from the original plan and the prorated cost of the downgraded plan:

**₹190.67 − ₹139.75 = ₹50.92**

Therefore, a **credit adjustment of ₹50.92** is generated for the customer.

The credit can be applied to the customer's next billing cycle, according to the subscription's billing configuration.

## Credit Adjustment for GST-Exclusive Plans

When a subscription plan is downgraded during an active billing cycle, the unused amount from the current plan can be adjusted against the cost of the downgraded plan for the remaining days of the billing cycle.

In a **GST-exclusive** configuration, the plan price represents the taxable/base amount, and GST is calculated separately on the applicable amount.

### Example

Assume the following:

* **GST:** 18%

* **Billing frequency:** Monthly

* **Original plan price:** ₹500 (GST-exclusive)

* **Subscription start date:** September 1

* **Plan downgrade date:** September 15

* **Billing cycle:** 30 days

* **Proration factor:** 1.10 (10% additional proration adjustment)

* **STEP 1**: Calculate the total amount for the original plan

Since the original plan price of ₹500 is GST-exclusive:

**Base Amount = ₹500**

**GST = ₹500 × 18% = ₹90**

**Total Amount = ₹500 + ₹90 = ₹590**

* **STEP 2**: Calculate the consumed amount for the first 15 days

The daily base cost is:

**₹500 / 30 = ₹16.67 per day**

The prorated base cost for 15 days is:

**₹16.67 × 15 × 1.10 = ₹275.05**

Therefore, **₹275.05** of the base plan amount is considered consumed during the first 15 days.

* **STEP 3**: Calculate the unused balance from the original plan

The unused base amount is:

**₹500 − ₹275.05 = ₹224.95**

* **STEP 4**: Calculate the cost of the downgraded plan

The merchant downgrades the subscription to a plan priced at **₹300 (GST-exclusive)** on September 15.

**Base Amount = ₹300**

The daily base cost of the downgraded plan is:

**₹300 / 30 = ₹10.00 per day**

The prorated base cost for the remaining 15 days is:

**₹10.00 × 15 × 1.10 = ₹165.00**

* **STEP 5**: Calculate the credit adjustment

The credit adjustment is calculated by subtracting the prorated cost of the downgraded plan from the unused balance of the original plan:

**₹224.95 − ₹165.00 = ₹59.95**

Therefore, a **credit adjustment of ₹59.95** is generated for the customer.

The credit can be applied to the customer's next billing cycle, according to the subscription's billing configuration.

<Note>
  **The credit adjustment is made without GST** in both GST-inclusive and GST-exclusive configurations. The applicable GST is calculated separately based on the subscription's billing configuration.
</Note>

<Note>
  * **Credit Adjustment When a Subscription Is Canceled**

  If the subscription is canceled after the plan change, any applicable unused balance is calculated based on the consumed and remaining portion of the billing cycle.

  The resulting credit adjustment can be applied according to the merchant's configured cancellation and credit adjustment policy.
</Note>

<Note>
  * **Credit Adjustment When a Subscription Is Paused and Unpaused**

  If a subscription is paused during a billing cycle, the days for which the subscription remains paused are excluded from the applicable subscription usage calculation.

  For example:

  * **Subscription paused:** September 10
  * **Subscription resumed:** September 20
  * **Paused period:** 10 days

  The applicable credit adjustment for the **10 paused days** is calculated and applied based on the subscription's billing configuration.
</Note>

<Note>
  * **Credit Adjustment when a subscription remains paused until renewal**

  If a subscription is paused and remains paused when the next renewal date is reached, the credit adjustment for the applicable paused period is calculated as part of the billing cycle.

  The resulting credit can be carried forward and applied to a future billing cycle when the subscription resumes, based on the subscription's billing configuration.
</Note>


# Pause unpause
Source: https://developer.transactbridge.com/subscription/manage-subs/pause-unpause



A merchant can temporarily suspend an **ACTIVE** subscription using the **Pause API**. During the pause period, no scheduled invoices or automatic payment collections are processed.

When the customer is ready to continue the subscription, the merchant can resume it using the **Unpause API**, which changes the subscription back to the **ACTIVE** state.

```mermaid theme={null}
flowchart LR

A[ACTIVE] -->|Pause API| B[PAUSED]
B -->|Unpause API| A
```

## Pause Subscription

The Pause API temporarily suspends an ACTIVE subscription while preserving the subscription configuration. No billing attempts are made until the subscription is resumed.

### Pause Flow

```mermaid theme={null}
sequenceDiagram

participant Merchant
participant TB as Transact Bridge
participant Subscription

Merchant->>TB: Pause Subscription API
TB->>Subscription: Validate ACTIVE subscription
Subscription-->>TB: Valid
TB->>Subscription: Change status to PAUSED
Subscription-->>TB: Status Updated
TB-->>Merchant: Success Response
```

### Common Use Cases

| Scenario                 | Illustration                                                                                       |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| Customer-requested break | A customer pauses a gym membership, meal delivery, or another subscription temporarily.            |
| Seasonal service         | Services such as pool cleaning or AC maintenance are paused during the off-season.                 |
| Payment issue            | Multiple payment failures caused by insufficient funds, expired cards, or invalid payment details. |
| Account review           | Merchant needs to complete fraud checks or customer verification before continuing billing.        |
| Temporary unavailability | Product or service is temporarily unavailable or out of stock.                                     |
| Plan transition          | Subscription is paused while an upgrade or downgrade is being processed.                           |

### Pause API

Refer to the <a href="https://docs.transactbridge.com/#e91a292e-d13c-4a27-a77e-dfbbc63447b7">Pause API</a> to pause an active subscription.

***

## Unpause Subscription

The Unpause API resumes a previously paused subscription. Once resumed, future billing cycles continue according to the subscription schedule.

### Unpause Flow

```mermaid theme={null}
sequenceDiagram

participant Merchant
participant TB as Transact Bridge
participant Subscription

Merchant->>TB: Unpause Subscription API
TB->>Subscription: Validate PAUSED subscription
Subscription-->>TB: Valid
TB->>Subscription: Change status to ACTIVE
Subscription-->>TB: Status Updated
TB-->>Merchant: Success Response
```

### Common Use Cases

| Scenario                 | Illustration                                                                      |
| ------------------------ | --------------------------------------------------------------------------------- |
| Customer resumes service | Customer wants to continue the subscription.                                      |
| Payment method updated   | Customer updates card or bank account details.                                    |
| Outstanding dues cleared | Customer clears overdue invoices that caused the pause.                           |
| Service available again  | Previously unavailable product or service becomes available.                      |
| Verification completed   | Merchant completes KYC or fraud verification.                                     |
| Pause period ends        | Subscription automatically or manually resumes after a predefined pause duration. |

### Unpause API

Refer to <a href="https://docs.transactbridge.com/#3ccbb9e0-c648-42b8-9bd8-de74c38b3743">Unpause API</a> to unpause your paused subscription.

***

## State Transition

```mermaid theme={null}
stateDiagram-v2

[*] --> ACTIVE

ACTIVE --> PAUSED : Pause API
PAUSED --> ACTIVE : Unpause API

ACTIVE --> CANCELLED : Cancel API
```

***

## Notes

* Only subscriptions in the **ACTIVE** state can be paused.
* Only subscriptions in the **PAUSED** state can be resumed.
* Pausing a subscription does **not** cancel the subscription.
* Subscription configuration, billing frequency, mandate, and customer information remain unchanged while paused.
* After resuming, billing continues according to the configured billing schedule.


# Add Payment Mandate
Source: https://developer.transactbridge.com/subscription/manage-subs/payment-mandates/add-a-new-payment-method

Allow customers to add or update a payment mandate for future recurring payments.

The **Add Payment Mandate** flow allows an existing customer to securely add or replace the payment mandate associated with a subscription. This is commonly used when the customer wants to change their payment mandate or when the existing payment mandate has expired or become invalid.

After the payment mandate is successfully authorized, future recurring payments are collected using the newly saved payment mandate.

***

## Common Use Cases

| Scenario                  | Illustration                                                                        |
| ------------------------- | ----------------------------------------------------------------------------------- |
| Expired card              | The customer replaces an expired credit or debit card.                              |
| New bank account          | The customer switches to a different bank account or UPI account.                   |
| Mandate expired           | The existing UPI AutoPay or card mandate has expired and needs to be re-authorized. |
| Payment failures          | The customer updates their payment mandate after recurring payment failures.        |
| Preferred payment mandate | The customer changes the preferred payment mandate for future billing.              |
| Compliance requirement    | The merchant requests re-authentication of the customer's payment mandate.          |

***

## Workflow

```mermaid theme={null}
flowchart TB

A[Merchant Initiates<br/>Add Payment Mandate]
--> B[Generate Billing Session]

B --> C[Hosted Checkout]

C --> D[Customer Selects<br/>Payment Mandate]

D --> E[Customer Completes<br/>Mandate Authorization]

E --> F{"Authorization Successful?"}

F -->|Yes| G[Payment Mandate Saved]

G --> H[Future Recurring Payments<br/>Use Updated Payment Mandate]

F -->|No| I[Authorization Failed]

I --> J[Customer Retries]
```

***

## How It Works

1. The merchant calls <a href="https://docs.transactbridge.com/#b7abc54b-bf8a-4569-8f65-46b613600d47"> Add Mandate </a> API and generates an **Add Payment Mandate** session.
2. Transact Bridge returns a **payURL**.
3. The customer is redirected to the hosted checkout.
4. The customer selects a payment mandate (for example, UPI AutoPay or Card).
5. The customer completes the mandate authorization.
6. Once authorization is successful, the payment mandate is securely stored.
7. All future recurring payments use the newly added payment mandate.

***

## State Transition

```mermaid theme={null}
stateDiagram-v2

[*] --> ACTIVE

ACTIVE --> ACTIVE : Add Payment Mandate

ACTIVE --> ACTIVE : Payment Mandate Updated
```

***

## Notes

* Adding a payment mandate does **not** change the subscription status.
* The subscription remains **ACTIVE** throughout the process.
* The customer must successfully complete the hosted checkout and mandate authorization.
* Future recurring invoices are collected using the updated payment mandate.
* If the authorization fails or is abandoned, the existing payment mandate remains unchanged.


# Payment Mandates
Source: https://developer.transactbridge.com/subscription/manage-subs/payment-mandates/overview

Understand payment mandates and how they are used for recurring subscription payments.

A **payment mandate** is an authorization given by a customer to Transact Bridge and the applicable payment network or payment provider to collect future payments automatically.

Payment mandates are primarily used for **recurring payments and subscriptions**, where Transact Bridge needs to collect payments automatically after the customer has completed the initial authorization.

## How Payment Mandates Work

A payment mandate allows the customer to authorize recurring payments instead of manually making a payment for every billing cycle.

The general flow is:

```mermaid theme={null}
flowchart TD
    C[Customer Authorizes Payment Mandate on Checkout]

    C --> D[Mandate Created]

    D --> E[Subscription Becomes ACTIVE]

    E --> F[Billing Cycle]

    F --> G[Invoice or Recurring Charge]

    G --> H[Transact Bridge Uses Mandate]

    H --> I[Payment Collection]

    I --> J{Payment Successful}

    J -->|Yes| K[Subscription Continues]

    J -->|No| L[Apply Retry or Failure Policy]
```

## Mandate Authorization

The customer authorizes a payment mandate through the Transact Bridge hosted checkout.

Depending on the payment method, the authorization may involve mechanisms such as:

* UPI AutoPay mandate
* Card mandate

The customer does not have to manually initiate every subsequent payment after the mandate has been successfully authorized.

## Mandate in a Prepaid Subscription

For a **prepaid subscription**, the customer pays before accessing the service.

The mandate can be authorized during the subscription checkout so that Transact Bridge can automatically collect the recurring amount for subsequent billing periods.

### Flow

```text theme={null}
Create Subscription
        |
        ↓
billAtStart = true
        |
        ↓
PENDING
        |
        ↓
Hosted Checkout
        |
        ↓
Initial Payment + Mandate Authorization
        |
        ↓
ACTIVE
        |
        ↓
Next Billing Period
        |
        ↓
Automatic Collection Using Mandate
```

### Example

Consider a monthly subscription:

```text theme={null}
Plan Amount: ₹999/month
Billing Frequency: Monthly
```

The customer completes the initial payment of ₹999 and within that transaction TransactBridge also gets authorization for the recurring payment mandate.

The subscription becomes `ACTIVE`.

At the beginning of the next billing period, Transact Bridge can use the authorized mandate to collect the next ₹999.

```text theme={null}
1 August
   |
   ↓
Customer pays ₹999
   |
   ↓
Mandate authorized
   |
   ↓
Subscription ACTIVE
   |
   ↓
1 September
   |
   ↓
₹999 collected using mandate
   |
   ↓
Next billing period
```

## Mandate in a Postpaid Subscription

For a **postpaid subscription**, the customer uses the service first and payment is collected after the billing period.

In this case, the customer does not need to pay the first postpaid invoice to activate the subscription.

Instead, the customer authorizes a payment mandate on checkout. To authorize a payment mandate, a small amount is charged to the customer (Ex: \$0.1), and on successful payment, the mandate is authorized for future collection.

```text theme={null}
Create Subscription
        |
        ↓
billAtStart = false
        |
        ↓
PENDING
        |
        ↓
Hosted Checkout
        |
        ↓
Mandate Authorization
        |
        ↓
ACTIVE
        |
        ↓
Customer Uses Service
        |
        ↓
Billing Period Ends
        |
        ↓
Invoice Generated
        |
        ↓
Invoice Approved
        |
        ↓
Collection Using Mandate
```

## What Happens When Mandate Collection Fails?

A mandate collection may fail for reasons such as:

* Insufficient funds
* Expired or invalid payment credentials
* Bank or payment-network failure
* Mandate-related restrictions
* Customer or bank authorization issues

When collection fails, the subscription does not necessarily terminate immediately.

Transact Bridge can apply the configured **retry, due, overdue, and unpaid-invoice policies**.

```mermaid theme={null}
flowchart TD
    A[Invoice Approved]
    --> B[Collection Using Mandate]

    B --> C{Collection Successful?}

    C -->|Yes| D[Payment Completed]
    D --> E[Subscription Continues]

    C -->|No| F[Payment Failure]

    F --> G[Retry / Due / Overdue Handling]

    G --> H{Payment Recovered?}

    H -->|Yes| E

    H -->|No| I[Apply Configured Subscription Policy]
```

## Important Considerations

* A payment mandate is an authorization for future payment collection.
* The customer must successfully authorize the applicable payment mandate before Transact Bridge can use the mandate for recurring collection.
* Mandates are useful for automating recurring subscription payments.
* In prepaid subscriptions, the mandate can be used to collect the recurring amount before the next service period.
* In postpaid subscriptions, the mandate can be used to collect an approved invoice after the customer has consumed the service.
* If a collection attempt fails, the configured retry and overdue policies determine the subsequent handling.
* A mandate should not be treated as the same thing as an individual payment transaction. The mandate provides the authorization mechanism, while each subsequent collection results in an actual payment transaction.

> **In simple terms:** A payment mandate gives Transact Bridge the customer's authorization to collect future subscription payments automatically, eliminating the need for the customer to manually initiate every recurring payment.


# Manage Payment Mandates
Source: https://developer.transactbridge.com/subscription/manage-subs/payment-mandates/update-a-subs-with-new-primary-payment-method

To manage payment mandates and their actions like making them primary, seconday, or cancelling.

<Note>
  🚧 This feature is **Coming Soon**.

  Documentation for this feature is currently under preparation and will be available in an upcoming release.
</Note>


# Change Subscription Frequency
Source: https://developer.transactbridge.com/subscription/manage-subs/update-subs/change-of-frequency

Understand frequency changes and prorated credit adjustments for prepaid and postpaid subscriptions.

A merchant can change the billing frequency of an existing subscription when the customer's billing requirements change.

A frequency change can be made between different billing intervals, such as:

* Monthly to Quarterly
* Monthly to Yearly
* Quarterly to Monthly
* Yearly to Monthly

When the frequency of an active subscription is changed, the treatment of the current billing period depends on whether the subscription is **prepaid** or **postpaid**.

Transact Bridge uses the applicable **proration basis** to determine the credit or adjustment for the unused portion of the current subscription period.

***

## Prepaid Subscription

In a prepaid subscription, the customer pays for the service before the service period begins.

When the billing frequency is changed during an active billing period, the unused portion of the existing prepaid period can be considered for a **prorated credit adjustment** against the new subscription frequency.

### Scenario 1: Monthly → Quarterly

Consider a customer with a monthly prepaid subscription:

```text theme={null}
Current Plan:
Monthly
Amount: ₹1,000
Billing Period: 1 August – 31 August
```

The customer changes from monthly to quarterly billing on **16 August**.

The customer has already paid for the current monthly period. Since part of the current billing period remains unused, the applicable unused-period value can be calculated on a prorated basis.

The resulting adjustment is applied when calculating the amount due for the new quarterly billing frequency.

### Scenario 2: Monthly → Yearly

A customer has paid for a monthly prepaid subscription and changes to an annual plan before the current monthly period ends.

The unused portion of the current monthly subscription is considered for the applicable prorated credit adjustment.

The adjustment is applied against the amount payable for the new yearly subscription.

### Scenario 3: Quarterly → Monthly

A customer has already paid for a quarterly prepaid subscription but wants to move to monthly billing.

If the frequency change occurs before the end of the current quarterly period, the applicable unused portion can be considered as a prorated credit adjustment.

The credit is then considered when determining the amount payable under the new monthly frequency.

***

## Prepaid Credit Adjustment Flow

For a prepaid subscription, the general flow is:

```mermaid theme={null}
flowchart TB

A["Existing Prepaid Subscription"]
--> B["Frequency Change"]

B --> C["Determine Current Billing Period"]

C --> D["Determine Unused Portion"]

D --> E["Calculate Prorated Credit"]

E --> F["Apply Credit Adjustment"]

F --> G["Calculate Amount for New Frequency"]

G --> H["New Billing Frequency"]
```

The adjustment can be represented conceptually as:

```text theme={null}
Amount Payable for New Frequency
                -
Applicable Prorated Credit
                =
Net Amount Due
```

The exact credit depends on the applicable subscription amount, billing period, frequency change, and remaining portion of the current billing period.

***

# Postpaid Subscription

In a postpaid subscription, the customer uses the service during the billing period and payment is collected after the billing period.

When the billing frequency is changed, the primary consideration is the billing period in which the usage occurred and how the existing period is handled.

### Scenario 1: Monthly → Quarterly

Consider a customer using a monthly postpaid plan.

```text theme={null}
Current Plan:
Monthly
Billing Period: 1 August – 31 August
```

The customer changes to quarterly billing during the current period.

The usage already accumulated under the existing billing period is considered according to the applicable billing and proration rules.

The new quarterly frequency is then used for subsequent billing.

```text theme={null}
Existing Monthly Usage
        │
        ▼
Current Billing Period
        │
        ▼
Frequency Changed
        │
        ▼
Applicable Adjustment
        │
        ▼
New Quarterly Billing Cycle
```

### Scenario 2: Monthly → Yearly

A customer using a monthly postpaid service changes to an annual billing frequency.

The usage accumulated during the applicable billing period is considered before moving to the new billing frequency.

Subsequent usage is then accumulated according to the yearly billing cycle.

### Scenario 3: Quarterly → Monthly

A customer on a quarterly postpaid subscription changes to monthly billing.

The existing billing period and accumulated usage are considered during the frequency change. The subscription then follows the monthly billing cycle for subsequent periods.

***

## Postpaid Credit Adjustment Flow

```mermaid theme={null}
flowchart TB

A["Existing Postpaid Subscription"]
--> B["Frequency Change"]

B --> C["Review Current Billing Period"]

C --> D["Consider Usage / Existing Charges"]

D --> E["Apply Applicable Proration Adjustment"]

E --> F["New Billing Frequency"]

F --> G["Usage Accumulation"]

G --> H["Invoice Generation"]

H --> I["Payment Collection"]
```

***

## Important Considerations

* A frequency change does not necessarily mean that the customer starts a completely new subscription.
* For prepaid subscriptions, the unused portion of the existing billing period may be considered for a prorated credit adjustment.
* For postpaid subscriptions, the existing billing period and accumulated usage/charges need to be considered when changing frequency.
* The applicable credit or adjustment is determined based on the proration rules applicable to the subscription.
* The new billing frequency applies to subsequent billing cycles after the frequency change.


# Update Subscription
Source: https://developer.transactbridge.com/subscription/manage-subs/update-subs/overview

Update an existing subscription by changing the plan, billing frequency, item values, or retry configuration.

The <a href="https://docs.transactbridge.com/#b7abc54b-bf8a-4569-8f65-46b613600d47"> Update Subscription API </a> allows a merchant to modify an existing subscription without creating a new one. Depending on the changes requested, the billing impact is determined by the merchant's business rules and subscription configuration.

The API can be used to upgrade or downgrade plans, modify subscription items, change billing frequency, or update invoice reattempt settings while preserving the existing subscription.

***

## Subscription Update Flow

```mermaid theme={null}
sequenceDiagram

participant Merchant
participant TB as Transact Bridge
participant Subscription

Merchant->>TB: Update Subscription API
TB->>Subscription: Validate subscription
Subscription-->>TB: Subscription found
TB->>Subscription: Apply requested changes
Subscription-->>TB: Subscription updated
TB-->>Merchant: Updated subscription details
```

***

## Common Use Cases

| Use Case                       | Description                                                                                                                                                                         |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plan Upgrade                   | Move a customer from a lower-tier plan to a higher-tier plan (for example, Basic to Premium).                                                                                       |
| Plan Downgrade                 | Move a customer to a lower-priced plan or reduce the subscription commitment.                                                                                                       |
| Update Item Values             | Modify the products, quantities, pricing, or other item-level details associated with the subscription.                                                                             |
| Change Billing Frequency       | Change the billing cycle, such as Monthly to Yearly or Yearly to Monthly.                                                                                                           |
| Update Reattempt Configuration | Modify the retry policy for failed recurring payment attempts.                                                                                                                      |
| Credit on Downgrade            | When moving from a yearly subscription to a monthly subscription, the remaining unused value can be credited to the customer's account according to the merchant's business policy. |

***

## Supported Updates

The Update Subscription API supports modifications such as:

* Subscription plan
* Subscription amount
* Product or item details
* Billing frequency
* Retry (reattempt) configuration
* Billing settings
* Subscription metadata
* Tax configuration (where applicable)

***

## Update Lifecycle

```mermaid theme={null}
flowchart TB

A[ACTIVE Subscription]
--> B[Update Subscription API]

B --> C[Validate Request]

C --> D[Apply Updates]

D --> E[Subscription Updated]

E --> F[Future Billing Uses Updated Configuration]
```

***

## Plan Upgrade Example

```text theme={null}
Basic Plan (₹499/month)
        │
        │ Update Subscription
        ▼
Premium Plan (₹999/month)
```

***

## Plan Downgrade Example

```text theme={null}
Premium Annual Plan
        │
        │ Update Subscription
        ▼
Basic Monthly Plan

Remaining annual balance
        │
        ▼
Merchant Credit Wallet (Optional)
```

***

## Billing Frequency Change

```text theme={null}
Monthly
   │
   ▼
Yearly

or

Yearly
   │
   ▼
Monthly
```

***

## Notes

* The subscription remains the same; only its configuration is updated.
* Future invoices are generated using the updated subscription configuration.
* Billing adjustments, prorations, or credits depend on the merchant's business rules.
* Downgrades may result in customer credits based on the remaining subscription value.
* Updating the billing frequency affects all future billing cycles.
* Changes to the retry configuration apply only to future payment failures.


# Upgrade/Downgrade of Subscriptions
Source: https://developer.transactbridge.com/subscription/manage-subs/update-subs/upgrade-downgrade

Understand plan upgrades, downgrades, and prorated credit adjustments in Transact Bridge.

Transact Bridge allows merchants to change the plan associated with an existing subscription without creating a new subscription.

A plan change can be used to:

* Upgrade a customer to a higher-value plan.
* Downgrade a customer to a lower-value plan.
* Change the products or items included in the subscription.
* Change the billing frequency associated with the plan.
* Adjust the amount based on the unused portion of the current billing period.

When a plan is changed during an active billing period, the applicable adjustment can be calculated on a **prorated, day-consumed basis**.

The `prorate` parameter in the subscription item configuration determines whether an item's amount is partially calculated based on the days consumed.

***

# Upgrade Plan

An **upgrade** occurs when a customer moves from a lower-value plan to a higher-value plan.

For example:

```text theme={null}
Current Plan:
Basic
₹1,000 / month

New Plan:
Premium
₹2,000 / month
```

If the customer upgrades before the end of the current billing period, the unused portion of the current plan can be considered when calculating the amount applicable to the new plan.

### Upgrade Scenario

Consider a monthly prepaid subscription:

```text theme={null}
Current Plan       : Basic
Monthly Amount     : ₹1,000
Billing Period     : 1 August – 31 August
Plan Change Date   : 16 August
New Plan           : Premium
New Monthly Amount : ₹2,000
```

The customer has already consumed part of the Basic plan.

```text theme={null}
1 Aug                         16 Aug                    31 Aug
 |----------------------------|--------------------------|
       Basic Plan Used              Unused Period
```

The unused portion of the Basic plan is considered for the applicable prorated credit. The credit can then be applied against the amount due for the Premium plan.

***

### Upgrade Flow

```mermaid theme={null}
flowchart TB

A["ACTIVE<br/>Basic Plan"]
--> B["Upgrade Plan"]

B --> C["Determine Current<br/>Billing Period"]

C --> D["Determine Days Consumed<br/>and Remaining"]

D --> E["Calculate Applicable<br/>Prorated Credit"]

E --> F["Apply Credit to<br/>New Plan Amount"]

F --> G["Premium Plan"]

G --> H["Continue Billing<br/>on New Plan"]
```

***

### Upgrade Example

```text theme={null}
Current Plan: Basic
Amount: ₹1,000

New Plan: Premium
Amount: ₹2,000

Unused Basic Plan Value: ₹500

New Plan Amount          ₹2,000
Prorated Credit          -₹500
                          -------
Net Adjustment            ₹1,500
```

# Downgrade Plan

A **downgrade** occurs when a customer moves from a higher-value plan to a lower-value plan.

For example:

```text theme={null}
Current Plan:
Premium
₹2,000 / month

New Plan:
Basic
₹1,000 / month
```

If the customer changes the plan before the end of the current billing period, the applicable unused value of the existing Premium plan can be considered as a prorated credit.

Because the new plan has a lower value, the resulting credit can be greater than the amount required for the new plan, depending on the timing and configured billing behavior.

***

### Downgrade Scenario

Consider:

```text theme={null}
Current Plan       : Premium
Monthly Amount     : ₹2,000
Billing Period     : 1 August – 31 August
Plan Change Date   : 16 August
New Plan           : Basic
New Monthly Amount : ₹1,000
```

The customer has consumed 15 days of the Premium plan and has 15 days remaining.

```text theme={null}
1 Aug                         16 Aug                    31 Aug
 |----------------------------|--------------------------|
       Premium Used                 Unused Period
```

The unused Premium value can be calculated on the applicable prorated basis.

```text theme={null}
₹2,000 × 15 / 30 = ₹1,000
```

The applicable ₹1,000 represents the unused value of the existing Premium plan in this illustrative example.

***

### Downgrade Flow

```mermaid theme={null}

flowchart TD

    A[Active Premium Plan] --> B[Downgrade Plan]
    B --> C[Check Current Billing Period]
    C --> D[Calculate Unused Period]
    D --> E[Calculate Prorated Credit]
    E --> F[Apply Credit Adjustment]
    F --> G[Basic Plan]
    G --> H[Continue Billing]
```

***

### Downgrade Example

```text theme={null}
Current Plan: Premium
Amount: ₹2,000

New Plan: Basic
Amount: ₹1,000

Unused Premium Value: ₹1,000

New Plan Amount          ₹1,000
Prorated Credit          -₹1,000
                          -------
Net Adjustment               ₹0
```

The examples above assume a 30-day billing period and a change exactly halfway through the billing period.

# Prepaid Plan Change

For a **prepaid subscription**, the customer has already paid for the current service period.

Therefore, when a plan change occurs before the current period ends:

1. Determine the portion of the current plan already consumed.
2. Determine the unused portion.
3. Calculate the applicable prorated value of the unused portion.
4. Apply the applicable credit toward the new plan.
5. Continue the subscription using the new plan.

```mermaid theme={null}
flowchart TB

A["Prepaid Subscription"]
--> B["Plan Upgrade / Downgrade"]

B --> C["Current Plan Already Paid"]

C --> D["Calculate Unused Period"]

D --> E["Prorated Credit"]

E --> F["New Plan Amount"]

F --> G["Apply Credit Adjustment"]

G --> H["New Plan Active"]
```

***

# Postpaid Plan Change

For a **postpaid subscription**, the customer uses the service during the billing period and payment is collected after billing.

When the plan changes:

1. The existing billing period and consumed usage are considered.
2. The applicable amount is calculated for the current period.
3. The new plan becomes applicable according to the subscription update.
4. Subsequent usage is billed using the new plan configuration.

The proration mechanism can be used to calculate the applicable partial-period amount when the plan change occurs during a billing period.

```mermaid theme={null}
flowchart TB

A["Postpaid Subscription"]
--> B["Plan Upgrade / Downgrade"]

B --> C["Review Current Billing Period"]

C --> D["Determine Consumed Days / Usage"]

D --> E["Calculate Applicable<br/>Prorated Amount"]

E --> F["New Plan"]

F --> G["Continue Usage"]

G --> H["Invoice Generated"]

H --> I["Payment Collection"]
```

***

# Upgrade vs Downgrade

| Scenario          | Existing Plan | New Plan      | Proration Consideration                                                                    |
| ----------------- | ------------- | ------------- | ------------------------------------------------------------------------------------------ |
| Upgrade           | Lower value   | Higher value  | Unused value of the existing plan can be considered as credit against the new plan amount. |
| Downgrade         | Higher value  | Lower value   | Unused value of the existing plan can be considered as credit against the new plan amount. |
| Same-value change | Similar value | Similar value | Applicable adjustment depends on the remaining billing period and plan configuration.      |
| Mid-cycle change  | Existing plan | New plan      | Partial-period amount can be calculated on the applicable day-consumed basis.              |

## PENDING UPDATES

Your customers may need to move between plans mid-cycle — add a product, remove one, or change a quantity/price on an active subscription. You do this with a single API call, sending the **complete new list of items** you want the subscription to have (not just what changed). TransactBridge has no separate "add-on" concept, so every plan change — bigger, smaller, or the same total value — is handled the same way, as an upgrade/downgrade.

Because a plan change can increase what the customer owes, TransactBridge doesn't switch the plan blindly. It first checks whether the change fits inside the payment authorization your customer already gave us:

* **Fits the existing authorization** (or, for prepaid plans, no extra amount is owed) — the plan change applies immediately, in the same API call. No customer action needed.
* **Exceeds the existing authorization**, or an extra payment is due right now (prepaid plans) — the change is held as a **Pending Update**. Your customer must complete a short checkout step — raising their payment authorization or paying the prorated difference — before the new plan takes effect.

### How proration works

Days already used in the current billing period are billed against the old items; days remaining in the period are billed against the new items. Your customer is never charged for the full new plan on a partial month, and never loses value for days already paid on the old plan.

### The same-day window

A Pending Update quotes prices — and, for cross-currency subscriptions, the FX rate — as of the moment it's created. If your customer doesn't finish checkout that same day, the Pending Update automatically expires at midnight India time (IST). It is not silently recalculated or retried later, since the quoted price/FX rate would be stale. You'll need to call the update API again to restart the upgrade/downgrade.

### Integration steps

1. Call <a href="https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825"> Create Subscription API </a> with `subscriptionId` and the full `items` array (`name`, `quantity`, `amount`, and — if your account requires product mapping — `productReferenceId`).
2. Read the response:
   * `updateFlag: true` and `mandateRequired: false` — the plan change is already live.
   * `mandateRequired: true` — send your customer to `redirectUrl` (a hosted TransactBridge checkout page) to authorize the higher payment limit or pay the difference. If you use drop-in checkout, pass `dropIn: true` on the request to receive a `token` instead of a `redirectUrl`.
3. Once your customer completes checkout, TransactBridge applies the new items to the subscription and sends you a webhook (`callbackType: SUBSCRIPTION`) carrying the updated subscription object.
4. If your customer abandons checkout and doesn't return before midnight IST, the Pending Update is discarded — call step 1 again to retry.

**Optional flag:** pass `isCustomerRedirection: true` on the update call to always send the customer through checkout, even when the change would otherwise apply instantly — useful if you want the customer to confirm coupon terms, or to force downgrades through a confirmation step.

<Note>
  * **Pending plan updates are removed at midnight (12:00 AM IST) if the required payment is not completed.**
  * If a plan upgrade or downgrade request is created but the customer does not complete the payment, the pending update request is automatically removed from the system at 12:00 AM IST on the same day.
  * If the customer is redirected to the checkout page to complete the payment for a pending plan update but rejects the payment, the pending update request is also removed at 12:00 AM IST.
  * Once the pending update request is removed, the merchant must initiate a new update request if the customer wants to upgrade or downgrade the plan.
  * Example:
    If a customer requests a plan upgrade at 7:00 PM IST but does not complete the payment, the pending upgrade request is removed from the system at 12:00 AM IST. The merchant must initiate a new plan update request for the upgrade to be processed.
  * **system may have different flows for different jurisdictions, and this is only for India.**
</Note>

### Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> UpdateRequested
 
    UpdateRequested --> AppliedImmediately: Fits the existing\npayment authorization
    UpdateRequested --> PendingCustomerAction: Exceeds authorization,\nor payment due now
 
    PendingCustomerAction --> Applied: Customer completes\ncheckout same day
    PendingCustomerAction --> Expired: No action taken\nbefore midnight IST
 
    AppliedImmediately --> [*]
    Applied --> [*]
    Expired --> [*]
```

*An expired Pending Update is not retried automatically — call `updateSubscription` again to restart the upgrade/downgrade.*

### Integration sequence

```mermaid theme={null}
flowchart TD
    A(["You call Update Subscription\nwith the full new items list"]) --> B{"Does the new price fit the\ncustomer's existing authorization?"}
    B -- Yes --> C["Applied immediately\nupdateFlag = true, mandateRequired = false"]
    B -- No --> D["Pending Update created\nmandateRequired = true, redirectUrl/token returned"]
    D --> E["Customer completes checkout\n(raises authorization or pays the difference)"]
    E --> F{"Completed before\nmidnight IST?"}
    F -- Yes --> G["Plan applied\nWebhook sent - callbackType = SUBSCRIPTION"]
    F -- No --> H["Pending Update expires\nCall Update Subscription again to retry"]
    C --> I(["Subscription now reflects the new plan"])
    G --> I
```

### Important Considerations

* A plan upgrade or downgrade changes the plan associated with the existing subscription.
* The `prorate` configuration controls whether an item's amount is calculated on a partial, day-consumed basis.
* For prepaid subscriptions, the unused portion of the already-paid period can be considered when calculating the applicable credit.
* For postpaid subscriptions, the consumed portion of the billing period and applicable charges are considered when calculating the amount.
* An upgrade generally results in an additional amount being payable when the new plan is more expensive.
* A downgrade can result in a credit adjustment because the new plan has a lower value.
* A prorated credit should not automatically be interpreted as a cash refund. The treatment of any resulting credit depends on the subscription update and billing configuration.
* The exact amount depends on the plan amount, billing period, change date, applicable `prorate` configuration, and other subscription settings.

> **Proration basis:** Transact Bridge documentation specifies that when an invoice needs to be partially paid, the total amount can be calculated using proration on a **day-consumed basis**.


# Webhook
Source: https://developer.transactbridge.com/subscription/manage-subs/webhook



Webhooks are user-configured HTTP callbacks that are triggered when a specific event occurs. They allow two applications to communicate by automatically sending event information from one server to another.

Unlike APIs, where you need to repeatedly check for updates, webhooks automatically provide real-time notifications whenever an event occurs.

TransactBridge sends the event details to the **Webhook URL** configured by the merchant. These webhooks are sent as `POST` requests from the TransactBridge server. Authorization headers are also included so that partners can authenticate that the request originated from the TransactBridge server.

Merchants can configure the Webhook URL from the **TransactBridge Admin Panel** to start receiving webhook events.

<Note>
  [**Admin Panel for Sandbox**](https://sandbox.transactbridge.com/account/accountSetting) Navigate to callback Url's section under the Account settings tab to configure the Webhook URL for sandbox environment.

  [**Admin Panel for Production**](https://reseller.transactbridge.com/account/accountSetting) Navigate to callback Url's section under the Account settings tab to configure the Webhook URL for production environment.
</Note>

## Callback Response

Partners must respond to the webhook with the following JSON response and an HTTP `200` status code:

```json theme={null}
{
  "ack": true
}
```

* Only the above response with an HTTP 200 status code will be treated as a successful acknowledgement of the webhook.

* If the merchant does not acknowledge the webhook, TransactBridge will retry sending the webhook. A maximum of 3 attempts will be made.

* If the partner fails to acknowledge the webhook after all 3 attempts, TransactBridge will stop sending subsequent retries for that event.

* Partners can also resend the webhook from the Partner Dashboard if required.

## Signature Verification

TransactBridge uses the same method to generate the signature that is included in the authorization headers.

Partners should verify the signature before processing the webhook to ensure that the request originated from the TransactBridge server and that the payload has not been modified.

## Sample Subscription Status

This [**webhook**](https://docs.transactbridge.com/#9d2ada6b-d973-4ec6-8552-bc3da0a5cef7) event is sent to the configured partner URL when the subscription has a status change. Subscription status can be PENDING, PENDING\_EXPIRED, TRIAL, ACTIVE, PAUSED, EXPIRED, CANCELLED, FAILED.

```json theme={null}
"request":
{
"callbackType":"SUBSCRIPTION",
"status":"ACTIVE",
"quoteAmount":"15",
"tbId":"667946642f968332ee9a68e5",
"timestamp":"2026-08-26T06:30:07.953Z",
"currentPeriodStart":"2026-08-25T18:30:00.000Z",
"currentPeriodEnd":"2026-09-25T18:30:00.000Z"
"frequency":"MNTH",
"param1":string"",
"param2":string"",
"param3":string""
}
```

## Sample Payment Mandate Status

This [**webhook**](https://docs.transactbridge.com/#785764d3-b378-4da1-9151-c29c6a82d9eb) is sent to the configured partner URL when a mandate status is changed.

```json theme={null}
"request":

{
    "callbackType": "MANDATE",
    "status": "CREATED",
    "tbId": "66ebde6d11107c5eb4a29699",
    "txnId":"68e8cf7db2b6d0610f8cd000",
    "subscriptionId": "68e8cf61b2b6d0610f8cd142",
    "timestamp": "2024-09-19T08:18:53.900Z",
    "payMethod": "UPI",
    "quoteAmount": "100"
}

```


# Dropin
Source: https://developer.transactbridge.com/subscription/subs-checkout/dropin



TBDropin is a JavaScript-based Drop-in Payments SDK that allows merchants to easily embed secure, PCI-compliant payment components into their web applications.
It provides pre-built payment elements (UPI, Cards, T\&C, etc.) that are rendered inside secure iframes, ensuring sensitive payment data never touches the merchant’s servers.

## Subscription Drop-in Flow for website

1. Merchant injects [**TBdropin SDK**](https://developer.transactbridge.com/checkout.js/web-sdk/dropin/quickstart) and initializes it with Publish key and mode(environemnt).

2. Merchant can now use the SDK on their checkout page.

3. Once the user clicks on buy now/Proceed to pay button at merchants website, now the merchant renders checkout page hosted by them. Where Transact Bridge components are mounted.

4. Merchant calls the [**Create Subscription API**](https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825) to generate a session. Which in return gives a **unique subscription ID** and a **session token** which is used to complete the payment.

<Note>
  Merchant can generate a session at the time of opening their checkout page or at the time when user clicks on pay button of merchant hosted checkout page.
</Note>

5. Merchant collects the payment details from the customer on their checkout page.

6. Once the user clicks on Pay button. Merchant needs to calls the **pay()** method([**Triggering a Payment**](/checkout.js/web-sdk/dropin/quickstart#triggering-a-payment)) at the checkout with the payment details entered by the user and the session token.

7. Payment is completed, TB shares the status of the txn which merchant can show that on their own customized page.

8. TB triggers a [**Webhook**](https://docs.transactbridge.com/#9d2ada6b-d973-4ec6-8552-bc3da0a5cef7) on the configured server URL provided by the merchant.

   And also the transaction status is also provided in the pay method response.

9. Subsequently, an invoice based on the subscription (prepaid/postpaid) is generated and sent to the customer.

10. In case the user does not completes the txn on the page. Merchant can rely on the pendingExpire param passed in the create subs api bases on which the status of the subscription can be traced in case of merchant inactivity.

<Note>
  **pendingExpire**: Number of minutes after which, if the status of the subscription is PENDING (Customer did not pay), it becomes PENDING\_EXPIRED, which is a terminal state, and now customers cannot pay on the same subscription.

  By default that subs will be marked as expired by the system after 24 hrs. However, with the help of the pendingExpire param, this time can be reduced to a minimum: 10 mins to a max of 7 days.
</Note>

## Payment Flow

```mermaid theme={null}
sequenceDiagram
autonumber

    actor User
    participant A as Merchant Website
    participant B as Merchant Backend
    participant C as TB Backend
    participant D as Drop-in SDK

    User->>A: Clicks "Buy Now"
    A->>A: Opens Merchant-hosted Checkout Page

    User->>A: Enters payment details
    User->>A: Clicks "Pay"

    A->>B: Request to create subscription
    B->>C: Create Subscription API
    C-->>B: Session Token + Subscription ID

    B-->>A: Session Token + Subscription ID

    A->>D: pay(sessionToken, payMethod,subscriptionId)
    D->>C: Initialize Payment
    C-->>D: Payment result

    D-->>A: Payment status
   
    C->>B: Webhook: Subscription status update
    B->>B: Process webhook
    B-->>A: Shows payment and subscription status
    

```

## Workflow for Android SDK

1. Merchant adds the [**AAR**](https://developer.transactbridge.com/checkout.js/android-sdk/dropin/v1.0#1-download-the-aar) file in their project and the [**required dependencies**](https://developer.transactbridge.com/checkout.js/android-sdk/dropin/v1.0#3-declare-required-dependencies)  in app/build.gradle .
2. Now  initialize the TransactBridge PaymentSDK at [**onCreate()**](https://developer.transactbridge.com/checkout.js/android-sdk/dropin/v1.0#4-initialize-the-sdk) method in the main activity file.
3. Merchant can now use the SDK on their checkout screen.
4. Once the user clicks on buy now/Proceed to pay button at checkout screen , where Transact Bridge components are mounted.
5. Merchant calls the [**Create Subscription API**](https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825) to generate a session. Which in return gives a **unique subscription ID** and a **session token** which is used to complete the payment.

<Note>
  Merchant can generate a session at the time of opening their checkout screen or at the time when user clicks on pay button of merchant checkout screen.
</Note>

6. Merchant collects the payment details from the customer on their checkout screen.

7. Once the user clicks on Pay button. Merchant needs to calls the [**payUpi()**](https://developer.transactbridge.com/checkout.js/android-sdk/dropin/v1.0#8-launch-upi-payment) method.

8. Payment is completed, TB shares the status of the txn which merchant can show that on their own customized screen.

9. TB triggers a [**Webhook**](https://docs.transactbridge.com/#9d2ada6b-d973-4ec6-8552-bc3da0a5cef7) on the configured server URL provided by the merchant.

   And also the transaction status is also provided in the [**PaymentResultListener**](https://developer.transactbridge.com/checkout.js/android-sdk/dropin/v1.0#9-handling-payment-results)

10. Subsequently, an invoice based on the subscription (prepaid/postpaid) is generated and sent to the customer.

11. In case the user does not completes the txn on the page. Merchant can rely on the pendingExpire param passed in the create subs api bases on which the status of the subscription can be traced in case of merchant inactivity.


# Iframe Checkout Solution
Source: https://developer.transactbridge.com/subscription/subs-checkout/iframe

Learn how to integrate the Transact Bridge iframe checkout solution into your website for a seamless payment experience.

It embeds the Transact Bridge subscription checkout within the merchant's webpage, allowing customers to complete the subscription payment and mandate authorization without leaving the merchant's page

## Workflow for Website

1. The merchant will create a subscription by calling the [**Create Subscription API**](https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825) at the backend.

2. The API will return a **redirect URL** and a **unique ID** for subscription.

3. The redirect URL is used to render the checkout page by passing the URL in the `init()` method of the `TBIframe` instance.
   Navigate to [TBIframe Quickstart](https://developer.transactbridge.com/checkout.js/web-sdk/iframe/quickstart)

4. This will open an **iframe within the merchant's page**, from where the customer can make the payment.

5. TB will display the **transaction status** in the iframe. However, the merchant can also display the payment status page based on the status/data received through the [**Handler reference**](https://developer.transactbridge.com/checkout.js/web-sdk/iframe/v1.1).

6. TB triggers a [**Webhook**](https://docs.transactbridge.com/#9d2ada6b-d973-4ec6-8552-bc3da0a5cef7) on the configured server URL provided by the merchant.

   The transaction status is also provided through the **Handler references**.

7. Subsequently, an **invoice based on the subscription (prepaid/postpaid)** is generated and sent to the customer.

<Note>
  * In case the payment fails, TB does not mark the subscription as inactive and allows **multiple transactions** until there is a successful transaction on that session. The customer can retry the transaction within the **same session**.

  * After a successful transaction, the iframe **automatically closes within 10 seconds**.

  * In case there is no activity on the iframe by the customer, or the customer closes the page, the session remains active by default for **24 hours**. However, this timeframe can be customized and reduced to **10 minutes** through backend configuration. To enable this configuration, you need to raise a request with us.
</Note>

## Payment Flow

```mermaid theme={null}
sequenceDiagram
    autonumber

    actor User
    participant A as Merchant Website 
    participant B as Merchant Server
    participant C as TB Server 
    participant D as Iframe SDK 

    User->>A: Clicks on payment button

    A->>B: Request order creation
    B->>C: Create order / payment request
    C-->>B: Returns payment URL
    B-->>A: Returns payment URL

    A->>D: Passes payment URL
    D-->>A: Renders payment iframe on merchant website

    User->>D: Attempts payment in iframe

    Note over B,C: TB processes the payment

    C-->>B: Sends payment webhook
    D-->>A: Sends payment status via callback functions
```

### Workflow for Android SDK

1. The merchant will create a subscription by calling the [**Create Subscription API**](https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825) at the backend.
2. The API will return a **redirect URL** and a **unique ID** for subscription.
3. Initialize the SDK onCreate()  in your main activity file.
4. The redirect URL is used to render the checkout page by passing the URL in the [**open()**](https://developer.transactbridge.com/checkout.js/android-sdk/web-view/v1.0#3-usage) method of the TransactBridge Instance
5. This will open a webview within the merchant app screen. Where merchant can complete the payment process.
6. TB will display the **transaction status** in the webview. However, the merchant can also display the payment status screen based on the status/data received through the [**EVENT HANDLING REFERENCE**](checkout.js/android-sdk/web-view/v1.0#4-event-handling)
7. TB triggers a [**Webhook**](https://docs.transactbridge.com/#9d2ada6b-d973-4ec6-8552-bc3da0a5cef7) on the configured server URL provided by the merchant.
8. Subsequently, an **invoice based on the subscription (prepaid/postpaid)** is generated and sent to the customer.


# Payment link
Source: https://developer.transactbridge.com/subscription/subs-checkout/payment-link



You can generate a unique payment link for a customer using the Billing Session API. This works similarly to payment link providers like Cashfree, where a secure checkout URL is generated and shared with the customer.
​

## Subscription Payment link Flow

1. The merchant creates a subscription by calling the [**Create Subscription API**](https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825) from the backend.

2. Create subs API in return gives a **unique subscription ID** and a **redirect URL**.

3. The merchant uses the returned **redirect URL** to redirect the user to the payment page. Or can use the same **redirect url as the Payment Link** and shares it with the customer through email, SMS, WhatsApp, or any other communication channel.

4. The customer lands to  **Transact Bridge hosted checkout page**, where the customer enters their payment details and completes the payment.

5. Once the payment is completed, Transact Bridge processes the payment and updates the subscription and transaction status.

6. Customer is redirected to the **return url** provided in the create subscription API call. The return URL can be a success page or a failure page based on the payment status.

7. If the payment is successful:
   * The subscription moves to **ACTIVE** state.
   * The customer gets access to the subscribed service according to the subscription configuration.

8. If the payment is unsuccessful, the subscription/payment remains unsuccessful and the appropriate payment status is returned.

9. Transact Bridge triggers a [**Webhook**](https://docs.transactbridge.com/#9d2ada6b-d973-4ec6-8552-bc3da0a5cef7) to the server URL configured by the merchant. The webhook contains the relevant subscription and payment event information.

10. Based on the subscription configuration, an **invoice is generated** by Transact Bridge and sent to the customer.

<Note>
  * In case the payment fails, TB does not mark the subscription as inactive and allows **multiple transactions** until there is a successful transaction on that session. The customer can retry the transaction within the **same session**.
</Note>

## Payment Flow

```mermaid theme={null}

sequenceDiagram
   autonumber

   actor User
   participant A as Merchant Website 
   participant B as Merchant Server
   participant C as TB Server 
   participant D as TB Hosted Checkout

   User->>A: Clicks on payment button

   A->>B: Request order creation
   B->>C: Create order / payment request
   C-->>B: Returns payment URL
   B-->>A: Returns payment URL
  

   A->>D: Redirects to TB Hosted checkout
 

   User->>D: Attempts payment
   
   Note over B,C: TB processes the payment

   C-->>B: Sends payment webhook
   D-->>A: Redirects to return url

```


# Manage Invoice
Source: https://developer.transactbridge.com/subscription/subs-invoice-pay-lifecycle/manage-invoices

Manage, retrieve, update, approve, refund, and email invoices using Transact Bridge.

Transact Bridge provides APIs to manage the complete invoice lifecycle. Merchants can retrieve individual invoices, retrieve multiple invoices, update and approve draft invoices, process refunds, and email invoices to customers.

## Invoice Operations

| Operation                 | Description                                                        |
| ------------------------- | ------------------------------------------------------------------ |
| **Get Invoice**           | Retrieve the details of a specific invoice.                        |
| **Get All Invoice**       | Retrieve a list of invoices associated with the merchant.          |
| **Update Draft Invoice**  | Update the details of an invoice while it is in the `DRAFT` state. |
| **Approve Draft Invoice** | Approve a draft invoice so that it can proceed for collection.     |
| **Refund Invoice**        | Refund a payment associated with an invoice.                       |
| **Email Invoice**         | Send an invoice to the customer's email address.                   |

## Invoice Lifecycle

The following flow illustrates the typical invoice management lifecycle.

```mermaid theme={null}
flowchart TD
    A[Subscription Created] --> B{Billing Type}

    B -->|Prepaid| C[Subscription becomes ACTIVE after successful payment]
    B -->|Postpaid| D[Subscription becomes ACTIVE after payment method authorization]

    C --> E[Billing Period Begins]
    D --> F[Customer Uses Service During Billing Period]

    E --> G[Prepaid Invoice Generated]
    F --> H[Billing Period Ends]
    H --> I[Postpaid Draft Invoice Generated]

    G --> J[Invoice Auto-Approved]
    I --> K[Draft Invoice Webhook Sent to Merchant]

    K --> L[Merchant Reviews Draft Invoice]
    L --> M[Update Draft Invoice if Required]
    M --> N[Approve Draft Invoice]
    N --> O{Approved within 24 Hours?}

    O -->|Yes| P[Invoice Approved]
    O -->|No| P

    J --> Q[Payment Collection]
    P --> Q

    Q --> R{Payment Successful?}

    R -->|Yes| S[Invoice Paid]
    S --> T[Subscription Continues]
    T --> U[Next Billing Cycle]

    R -->|No| V[Retry / Due / Overdue / Unpaid Invoice Policies]
    V --> W{Payment Recovered?}

    W -->|Yes| S
    W -->|No| X[Apply Unpaid Invoice Policy]

    U --> B
```

## 1. Get Invoice

Use the [**Get Invoice** API](https://docs.transactbridge.com/#4f9b7a56-2989-4fd9-b99c-fb5a825c95df) to retrieve the details of a specific invoice.

This can be used when the merchant needs to:

* Retrieve invoice details.
* Check the invoice status.
* View invoice amount and currency.
* Retrieve customer and billing information.
* Check payment or transaction details associated with the invoice.

***

## 2. Get All Invoice

Use the [**Get All Invoice** API](https://docs.transactbridge.com/#46ff3912-41ef-4be8-ac89-ca1ce5da3a82) to retrieve invoices associated with the merchant.

This can be used when the merchant needs to:

* Display invoices in an internal dashboard.
* Retrieve multiple invoices.
* Track invoice statuses.
* Search or manage invoice records.

***

## 3. Update Draft Invoice

Use the [**Update Draft Invoice** API](https://docs.transactbridge.com/#d41f45ed-8581-423a-b96d-af54d339c0bf) to modify an invoice while it is in the `DRAFT` state.

A merchant can use this API when invoice details need to be updated before the invoice is approved.

### Typical Use Cases

* Update the invoice amount based on actual usage.
* Add or modify billing information.
* Update invoice items.
* Apply the final billing amount before approval.

<Note>
  Draft invoice details should be updated before the invoice is approved. Once the invoice has progressed beyond the draft stage, the applicable invoice update rules apply.
</Note>

***

## 4. Approve Draft Invoice

Use the [**Approve Draft Invoice** API](https://docs.transactbridge.com/#7acd088e-1eb1-4056-94f3-d3050e69c517) to approve a draft invoice after the merchant has completed the required updates.

Once approved, the invoice can proceed to the applicable payment collection process.

### Example Scenario

For a postpaid subscription, the merchant may receive the customer's usage information after the billing period.

For example:

| Usage         |     Amount |
| ------------- | ---------: |
| Compute usage |     ₹1,500 |
| Storage usage |       ₹500 |
| Data transfer |       ₹300 |
| **Total**     | **₹2,300** |

The merchant can update the draft invoice with the final amount and then approve it for collection.

***

## 5. Refund Invoice

Use the [**Refund Invoice** API](https://docs.transactbridge.com/#ed7480f6-f60d-43f7-a01d-f99b37bcee05) when the merchant needs to refund a payment associated with an invoice.

### Typical Use Cases

* Customer requests a refund.
* Order or service is cancelled.
* Duplicate payment.
* Incorrect amount charged.
* Merchant decides to provide a full or applicable partial refund.

### Refund Flow

```mermaid theme={null}
flowchart TD
    A[Paid Invoice]
    --> B[Refund Request]

    B --> C{Refund Successful?}

    C -->|Yes| D[Refund Processed]
    C -->|No| E[Refund Failed]
```

<Note>
  The refund amount and applicable refund rules should follow the parameters and business rules defined for the Refund Invoice API.
</Note>

## When to Initiate a Refund

A refund can be initiated when a payment has been successfully collected but the corresponding service has not been delivered to the customer.

Refunds are currently supported at the **invoice level**.

<Note>
  **Partial refunds are not supported for now.**

  * A refund can only be created for a successfull transaction.
</Note>

* **Refund for Transaction status as Failed, howevere amount has been debited**

In some cases, where amount has been debited however the transcation status shows as failed due to some issue with the acquirer or PSP. And our session remains in OPEN state(as on a single session multiple transaction attempts can be made)
The amount is automatically refunded to the customer, which  is generally processed within **5-7 business days**, depending on the customer's bank and the payment network.

The flow is:

1. Customer makes the payment.
2. Payment is initiated successfully and amount is debited.
3. The session remains in the **`OPEN`** state, however the trasnaction status shows as failed due to an issue with the acquirer or PSP end.
4. The payment is automatically refunded to the customer.
5. The refund is credited to the customer's account within the applicable banking timeframe, generally up to **5-7 business days**.

### Ways to Initiate Refund

A merchant can initiate a refund using either of the following methods:

* **Admin Panel:** The merchant can initiate the refund from the Transact Bridge Admin Panel.
* **API:** The merchant can initiate the refund programmatically using the [Refund API](https://docs.transactbridge.com/#ed7480f6-f60d-43f7-a01d-f99b37bcee05).

**When creating a refund**, the merchant can make the refund request to below:

* Back to source
* Account Transfer (where merchant needs to provide the customer account number for refund)

<Note>
  If credit adjustments have been made then there will be no refund avialable for that invoice.
</Note>

***

## 6. Email Invoice

Use the [**Email Invoice** API](https://docs.transactbridge.com/#8fcf1aed-340d-44e8-97fe-8006e488154c) to send an invoice to the customer through email.

This can be used when the merchant wants to:

* Send an invoice to the customer's registered email address.
* Resend an invoice.
* Provide the customer with invoice details after payment.
* Share an invoice for record-keeping purposes.

### Email Flow

```mermaid theme={null}
sequenceDiagram
    participant M as Merchant
    participant TB as Transact Bridge
    participant C as Customer

    M->>TB: Email Invoice request
    TB->>C: Send invoice email
    C-->>TB: Invoice received
    TB-->>M: Email status
```

***


# Postpaid Invoices
Source: https://developer.transactbridge.com/subscription/subs-invoice-pay-lifecycle/postpaid-invoice

Understand how invoices are generated, reviewed, approved, and collected for postpaid subscriptions.

A **postpaid subscription** allows a customer to use a service during the billing period and pay for it after the billing period ends.

In Transact Bridge, the recurring amount is **not collected at the beginning of the billing period**. Instead, an invoice is generated after the billing period based on the configured billing model, contract, or actual usage.

## How Postpaid Invoices Work

The postpaid invoice flow in Transact Bridge follows these steps:

1. The merchant creates a subscription with `billAtStart: false`.
2. The subscription enters the `PENDING` state.
3. The customer completes the hosted checkout and authorizes a payment method, such as a UPI AutoPay mandate or card mandate.
4. After successful authorization, the subscription becomes `ACTIVE`.
5. The customer uses the subscribed service during the billing period.
6. At the end of the billing cycle, Transact Bridge generates a draft invoice.
7. Transact Bridge sends a DRAFT Invoice [**webhook**](https://docs.transactbridge.com/#b688f88f-8d91-4890-85c7-1b0db62458df) to the merchant.
8. The merchant can review and update the  DRAFT invoice amount and line items based on actual usage or billing inputs by calling [Update Draft Invoice](https://docs.transactbridge.com/#d41f45ed-8581-423a-b96d-af54d339c0bf).
9. After updating the invoice, use [Approve Draft Invoice](https://docs.transactbridge.com/#7acd088e-1eb1-4056-94f3-d3050e69c517) to approve the invoice and make it available for the customer.
10. If no action is taken within the approval window, the invoice is automatically approved after 24 hours from the time of DRAFT invoice generation.
11. After approval, Transact Bridge attempts to collect the approved amount using the customer's saved payment mandate.
12. If payment succeeds, the subscription continues into the next billing cycle.
13. If payment fails, the configured retry, due, overdue, and unpaid-invoice policies are applied.

<Note>
  During mandate setup, a nominal authorization amount may be charged by the acquiring bank to verify the customer's payment details and authorize the payment mandate.
</Note>

## Postpaid Invoice Flow

```mermaid theme={null}
flowchart TD
    A[Create Subscription<br/>billAtStart: false]
    --> B[PENDING]

    B --> C[Hosted Checkout<br/>Payment Method Authorization]

    C --> D[ACTIVE]

    D --> E[Customer Uses Service]

    E --> F[Billing Cycle Ends]

    F --> G[Draft Invoice Generated]

    G --> H[Draft Invoice Webhook Sent]

    H --> I[Merchant Reviews Invoice]

    I --> J{Merchant Action<br/>Within Approval Window}

    J -->|Update and Approve| K[Invoice Approved]

    J -->|No Action| L[Auto-Approved]

    K --> M[Collection Attempt]

    L --> M

    M --> N{Payment Successful?}

    N -->|Yes| O[Next Billing Cycle]

    N -->|No| P[Retries / Due / Overdue<br/>or Subscription Action]

    P --> M
```

## Invoice Generation

For a postpaid subscription, the invoice is generated **after the customer has consumed the service for the billing period**.

For example, if the subscription has a monthly billing cycle:

```text theme={null}
1 August
   |
   | Customer uses service
   |
   |-----------------------------|
   |                             |
   |       August Usage          |
   |                             |
   |-----------------------------|
                                31 August
                                    |
                                    ↓
                              Invoice Generated
```

The invoice amount can be based on the applicable billing configuration and actual usage.

## Draft Invoice

Transact Bridge generates a **draft invoice** at the end of the billing cycle. A draft invoice allows the merchant to review and, where applicable, update the amount before collection.
Transact Bridge sends a **draft invoice webhook** to the merchant's configured server URL.
The merchant can use the information in the webhook to:

* Calculate charges based on actual usage.
* Update the invoice amount.
* Apply applicable billing adjustments.
* Approve the invoice for collection.

## Invoice Approval

After the draft invoice is generated, the merchant has an approval window to review and approve the invoice.

The merchant can:

```text theme={null}
Draft Invoice
      |
      ↓
Review Amount
      |
      ├── Update Amount
      |
      └── Approve Invoice
```

If the merchant does not take action within the configured approval window, the invoice is **automatically approved after 24hrs**. Once invoice is marked as APPROVED, Transact Bridge proceeds with payment collection.

## Payment Collection

After the invoice is approved, Transact Bridge attempts to collect the invoice amount using the customer's saved payment mandate.

```text theme={null}
Approved Invoice
       |
       ↓
Collection Attempt
       |
       ↓
Payment Successful?
     /       \
   Yes        No
   |           |
   ↓           ↓
Next Cycle   Retry / Due /
             Overdue Handling
```

If payment succeeds, the subscription continues normally. If payment fails, the configured retry, due, overdue, and unpaid-invoice policies are applied.

# Example: Cloud Service Subscription

Consider a customer subscribed to a monthly cloud service.

### Step 1: Subscription Creation and activation

The merchant creates the subscription with billAtStart": false and initial amount as ₹1,500. Subscription enters the `PENDING` state. The customer does not pay at the beginning of the billing period. Instead, the customer first authorizes a payment method buy making the payment of a nominal amount (₹2 for India). After successful authorization, the subscription becomes `ACTIVE`, and the customer can use the cloud service.

### Step 2: Customer Uses the Service

Assume the customer's billing period is **1<sup>st</sup> August – 1<sup>st</sup> September**. During that billing cycle, the customer uses cloud resources.

For example:

```text theme={null}
Compute usage       ₹1,500
Storage usage       ₹500
Data transfer       ₹300
--------------------------
Total usage         ₹2,300
```

the customer has used the service throughout August, but payment has not yet been collected.

### Step 3: Invoice Generation

At the end of the billing cycle that is on the midnight (UTC) of 31<sup>st</sup> August , Transact Bridge generates a draft invoice.

```text theme={null}
31 August
    |
    ↓
Billing Cycle Ends
    |
    ↓
Draft Invoice Generated
    |
    ↓
Draft Invoice Webhook
```

The draft invoice contains the applicable billing information. Where merchant can review the invoice and update the amount if the final usage calculation requires an adjustment.

### Step 4: Merchant Reviews the Invoice

Suppose the merchant reviews the customer's usage and determines that an additional total invoice that should be charged is ₹2,500.

The invoice can therefore be updated to:

```text theme={null}
Compute usage       ₹1,500
Storage usage       ₹500
Data transfer       ₹300
Additional usage    ₹200
                  ------
Final invoice     ₹2,500
```

The merchant then mark the invoice as APPROVED.

```text theme={null}
Draft Invoice
      ↓
Merchant Review
      ↓
Amount Updated
      ↓
Invoice Approved
```

### Step 5: Collection

After the invoice is approved, Transact Bridge attempts to collect **₹2,500** from the customer's saved payment mandate.

If the payment succeeds, subscription continues for next billing cycle. And in case the payment fails, Transact Bridge applies the configured retry, due, overdue, or unpaid-invoice policies.

## Billing Date Anchor

If a **Billing Date Anchor** is configured, the invoice can be generated according to the configured fixed billing date instead of the subscription billing date.

For example:

```text theme={null}
Subscription Anniversary:
5 August

Billing Date Anchor:
1 September
```

In this case, invoice generation follows the configured billing date anchor.

<Note>
  **In a postpaid subscription, the customer uses the service first. Transact Bridge generates a draft invoice at the end of the billing cycle, sends the draft invoice webhook to the merchant, allows the merchant to review and approve the invoice, and then attempts collection using the customer's saved payment method or mandate.**
</Note>


# Prepaid Invoices
Source: https://developer.transactbridge.com/subscription/subs-invoice-pay-lifecycle/prepaid-invoice

Understand how prepaid invoices are generated and collected in Transact Bridge.

A **prepaid subscription** requires the customer to pay for the subscription before accessing the service.

In Transact Bridge, a prepaid subscription is configured by setting `billAtStart` to `true`.

When `billAtStart` is `true`, Transact Bridge collects the subscription amount **before providing access to the service** and generates the invoice at the start of the subscription period.

## How Prepaid Invoices Work

The prepaid invoice flow works as follows:

1. The merchant creates a subscription with `billAtStart: true`, which enters the `PENDING` state. Post succesfull payment by the customer, the subscription becomes `ACTIVE`.
2. Here, the invoice is generated at the start of the subscription period.
3. The customer receives access to the service for the applicable billing period.
4. Before the next billing period begins, Transact Bridge generates an invoice for renewal which is auto-approved within fraction of seconds. And then Transact Bridge attempts to collect the recurring amount.
5. If the renewal payment succeeds, the subscription continues into the next billing period.
6. If If the collection fails, Transact Bridge applies the configured retry and invoice handling policies. The subscription configuration includes parameters such as `dayUntillDue`, `maxUnpaidInvoices`, `postMaxUnpaidInvoices`, and `reAttemptConfig` to control unpaid-invoice and retry behavior.

## Prepaid Invoice Flow

```mermaid theme={null}
flowchart TD
    A[Create Subscription<br/>billAtStart: true]
    --> B[PENDING]

    B --> C[Hosted Checkout]

    C --> D[Initial Payment]

    D --> E{Payment Successful?}

    E -->|Yes| F[Invoice Generated]

    F --> G[ACTIVE<br/>Service Access Begins]

    E -->|No| H[Payment Retry or<br/>Pending Expiry]

    G --> I[Customer Uses Service]

    I --> J[Next Billing Cycle]

    J --> K[Renewal Invoice Generated]

    K --> L[Automatic Collection<br/>from Saved Mandate]

    L --> M{Renewal Payment Successful?}

    M -->|Yes| N[Next Billing Period]

    N --> I

    M -->|No| O[Retries / Due / Overdue<br/>Policy]

    O --> L
```

## Example: Monthly Prepaid Subscription

Consider a customer subscribing to a monthly plan.

```text theme={null}
Plan:
Monthly Subscription

Amount:
₹999

Frequency:
MNTH

```

### Step 1: Subscription Creation/Activation

The merchant creates the subscription with:

```json theme={null}
{
  "frequency": "MNTH",
  "billAtStart": true,
 
}
```

The subscription is created in the `PENDING` state. The customer receives the payment URL and makes the payment of `₹999`. After successful payment the subscription becomes `ACTIVE`, and the customer can access the service.
The invoice for the subscription period is generated at the start of the subscription period.

### Step 2: Customer Uses the Service

Assume the customer starts the subscription on **1 August**.

```text theme={null}
1 August
   |
   | ₹999 paid
   |
   | Subscription becomes ACTIVE
   |
   | Customer gets access
   |
   |-----------------------------|
   |      August Service         |
   |-----------------------------|
                               31 August
```

The customer has prepaid for the August service period.

### Step 3: Renewal

Before the next billing period begins, Transact Bridge generates the renewal invoice and attempts to collect the recurring amount.

```text theme={null}
31 August
    |
    v
Renewal Invoice
    |
    v
Automatic Collection
    |
    v
₹999 collected
    |
    v
September Access
```

If the payment succeeds, the customer continues to have access during September.

## Prepaid vs Postpaid Invoice

|                    | Prepaid                                     | Postpaid                              |
| ------------------ | ------------------------------------------- | ------------------------------------- |
| Configuration      | `billAtStart: true`                         | `billAtStart: false`                  |
| When customer pays | Before service access                       | After service usage                   |
| Initial activation | Payment required                            | Payment method authorization          |
| Initial invoice    | Generated at start of subscription period   | Generated at end of billing period    |
| Renewal            | Amount collected before next service period | Amount collected after billing period |
| Typical use case   | Fixed-price subscriptions                   | Usage-based or metered services       |


# Single Pay Invoice
Source: https://developer.transactbridge.com/subscription/subs-invoice-pay-lifecycle/single-pay-invoice

Collect one-time payments for add-on features or services using a Single Pay Invoice.

At any point during an active subscription, a merchant may need to collect an additional amount for an add-on feature or service. Instead of modifying the customer's existing subscription, the merchant can use a **Single Pay Invoice** to collect this one-time amount.

A Single Pay Invoice is useful when the additional charge is independent of the customer's recurring subscription amount.

## When to Use a Single Pay Invoice

A Single Pay Invoice can be used when:

* A customer purchases an additional feature.
* A customer requests an upgrade that requires a one-time charge.
* The merchant provides an additional service outside the subscription.
* The customer purchases an add-on that should not become part of the recurring subscription.
* The merchant needs to collect an additional one-time amount during an active subscription.

The customer's existing subscription remains unchanged. The Single Pay Invoice is created separately for the additional charge.
<Note>To change the existing subscription with the additional charge, the merchant should update the subscription plan instead of using a Single Pay Invoice.</Note>

## Business Use Case

Consider a customer subscribed to a SaaS platform with the following plan:

| Item                         | Amount |
| ---------------------------- | -----: |
| Monthly Subscription         |   ₹999 |
| Additional Storage Add-on    |   ₹500 |
| Total One-Time Add-on Charge |   ₹500 |

The customer is already subscribed to the ₹999 monthly plan.

During the billing period, the customer requests an additional storage package. The merchant wants to collect **₹500** for this add-on but does not want the ₹500 to become part of the customer's recurring subscription.

In this scenario, the merchant can create a **Single Pay Invoice** for ₹500.

### Flow

```mermaid theme={null}
flowchart TB
    A[Customer has active subscription] --> B[Customer requests add-on]
    B --> C[Merchant calculates add-on amount]
    C --> D[Merchant creates Single Pay Invoice]
    D --> E[TB returns payment details]
    E --> F[Customer completes payment]
    F --> G{Payment successful?}
    G -->|Yes| H[Add-on activated]
    G -->|No| I[Payment remains unsuccessful]
    H --> J[Existing subscription continues unchanged]
```

### Single pay on subscription API

Merchant can use this [API](https://docs.transactbridge.com/#42bc7a92-82c8-4999-b2da-4226e1ff94a0) to create a new invoice on an ACTIVE subscription, that can be shared with a customer.


# Go to live checklist
Source: https://developer.transactbridge.com/subscription/test-your-subscription/go-to-live-checklist



## Integration Checklist

To ensure a smooth customer experience and a seamless TransactBridge integration, please complete the following action items.

Please go to [https://reseller.transactbridge.com/forgotPassword](https://reseller.transactbridge.com/forgotPassword) to set your password to use the platform. Use your business registered email with TransactBridge to set the password. Once you have set the password, you can log in to the platform and complete the following.

### Account Setup

* [ ] **Verify your root subdomain**

  Go to **Account Settings** and verify your root subdomain. Once verified, TransactBridge can provide you with subdomain-based redirection URLs.
  **Optional**

* [ ] **Add Callback URLs**

  Add the correct **Callback URLs** under **Account Settings**. This ensures that your application receives timely notifications about relevant events. And the customer can be notified promptly.
  **Mandatory**

* [ ] **Configure your brand theme**

  Update the **color theme** and upload your **brand logo** under **Account Settings** to provide customers with a consistent brand experience throughout the payment journey.
  **Mandatory**

### Team & Access

* [ ] **Add team members**

  Add relevant team members from the **Team Members** page so that different departments of your organization can access and use the platform. Assign appropriate permissions to each team member based on their role.
  **Optional**

### Payment Configuration

* [ ] **Add a bank account**

  Go to the **User Profile** page and add the bank account where you want to receive invoice payables. Make sure that the bank account details are accurate.
  **Mandatory**

### API Configuration

* [ ] **Set up API credentials**

  API credentials will be shared with you separately by email. If you have not received them, you can resend the credentials from the **API** page. You can also create new API credentials from the same page.
  **Optional**

* [ ] **Whitelist your server IPs**

  For additional security, whitelist the IP addresses of your servers from which API requests will originate.
  **Optional**

### Platform Demo

* [ ] **Request a platform demo**

  If your operations team would like a walkthrough of the TransactBridge platform, our team can provide a demo and guide you through the available features.
  **Optional**

## Production Enablement

Once all **mandatory** action items have been completed, reply to the TransactBridge onboarding email. Our team will verify the configuration and enable the platform for **production usage**.


# Overview
Source: https://developer.transactbridge.com/subscription/test-your-subscription/overview



Once the integration is complete, you need to test it on the sandbox environment using the sandbox credentials available at API section of the [Sandbox Admin Panel](https://sandbox.transactbridge.com/) and using the [test payment credentials](https://docs.transactbridge.com/#uat-testing) listed here.

When the test transaction is complete, you can move your code to Live or Production environment with production account details.

### Going Live on Production Environment

Replace your sandbox credentials with production credentials.

* API Key
* Secret Key
* Publish Key

<Note>
  Host Details are different for Sandbox and Production. Please configure accordingly.

  * Sandbox: [https://sandbox-api.transactbridge.com](https://sandbox-api.transactbridge.com)
  * Production: [https://api.transactbridge.com](https://api.transactbridge.com)

  The production account details will be available on the [Reseller Admin Panel](https://reseller.transactbridge.com/) only when your account is approved and created by TransactBridge. Please contact your account manager to get the production account created.
</Note>

<Note>
  IP's for sandbox and production are different. Please configure accordingly.

  <Columns>
    <Card title="Sandbox IP Addresses" icon="flask">
      **Allow the following IP addresses for Sandbox:**

      * `15.197.69.154`
      * `76.223.72.108`
      * `13.127.96.158`
      * `35.154.94.13`
    </Card>

    <Card title="Production IP Addresses" icon="server">
      **Allow the following IP addresses for Production:**

      * `15.197.224.201`
      * `15.206.132.31`
      * `76.223.91.111`
      * `13.127.125.65`
    </Card>
  </Columns>
</Note>