softmint-bbps-sdk
v2.0.1
Published
Premium Vanilla JS BBPS v2 Web SDK Widget
Readme
softmint-bbps-sdk
A premium, highly-customizable, responsive Vanilla JS SDK widget for integrating Bharat BillPay (BBPS) services into your web application. Compatible with ES Modules, CommonJS, and plain HTML integrations (CDN).
Key Features
- ⚡ Lightweight & Fast: Built with pure Vanilla JS and CSS for maximum compatibility and minimal overhead.
- 🎨 Modern Design: Beautiful UI with Outfit typography, smooth animations, and native support for light and dark modes.
- 🔄 Auto-Fetch Bill: Form fields dynamically adapt based on operator requirements (FASTag, Electricity, Gas, etc.) with automatic bill lookup.
- 🔒 Encrypted Payloads: Transactions are secured client-side using AES-256-GCM encryption and request integrity signatures using SHA-256.
- 🎫 Voucher Detection: Automatically extracts voucher/redeem codes (e.g. Google Play recharge codes) directly from the transaction remarks.
- 🖨️ Receipt Generation: Native receipt viewer layout with quick copy shortcuts and instant print options.
Installation
Install the package via npm:
npm install softmint-bbps-sdkUsage Guide
1. Bundler Integration (Vite, Webpack, etc.)
For React, Vue, Next.js, or any modern bundler environment:
import { BbpsSDK } from 'softmint-bbps-sdk';
import 'softmint-bbps-sdk/style.css';
// Initialize the SDK widget
const sdkInstance = BbpsSDK.init({
selector: '#bbps-widget-mount',
token: 'YOUR_BEARER_TOKEN_HERE',
baseUrl: 'https://api.yourbbpsgateway.com/',
partnerId: 'YOUR_PARTNER_ID',
vid: 'YOUR_VENDOR_ID',
secretKey: 'YOUR_32_CHAR_AES_SECRET_KEY',
theme: 'light', // 'light' | 'dark'
merchantName: 'Softmint Retailer', // Optional
onSuccess: (receiptData) => {
console.log('Payment Successful:', receiptData);
},
onError: (error) => {
console.error('Payment Error:', error.message);
}
});2. Browser Integration (CDN)
For standard HTML pages, you can include the script and stylesheet directly from a CDN (such as unpkg or jsdelivr):
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>BBPS SDK Integration</title>
<!-- Link SDK CSS -->
<link rel="stylesheet" href="https://unpkg.com/softmint-bbps-sdk@latest/dist/bbps-sdk.css" />
<style>
#bbps-widget-mount {
max-width: 500px;
margin: 40px auto;
}
</style>
</head>
<body>
<!-- Mount Container -->
<div id="bbps-widget-mount"></div>
<!-- Load SDK Javascript -->
<script src="https://unpkg.com/softmint-bbps-sdk@latest/dist/bbps-sdk.js"></script>
<script>
// Access global BbpsSDK
BbpsSDK.init({
selector: '#bbps-widget-mount',
token: 'YOUR_BEARER_TOKEN_HERE',
baseUrl: 'https://api.yourbbpsgateway.com/',
partnerId: 'YOUR_PARTNER_ID',
vid: 'YOUR_VENDOR_ID',
secretKey: 'YOUR_32_CHAR_AES_SECRET_KEY',
theme: 'dark', // 'light' | 'dark'
onSuccess: function(receipt) {
alert('Payment Success: ' + receipt.rrn);
},
onError: function(err) {
alert('Payment Failed: ' + err.message);
}
});
</script>
</body>
</html>SDK Configuration Options
The BbpsSDK.init(config) method accepts a configuration object with the following properties:
| Property | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| selector | string | HTMLElement | Yes | null | The CSS selector string (e.g., '#bbps-widget-mount') or the direct DOM element where the widget will render. |
| token | string | Yes | null | Bearer token passed to API requests under Authorization header. |
| baseUrl | string | Yes | null | The base URL of the backend BBPS endpoints. |
| partnerId | string | Yes | null | Partner Identification key. |
| vid | string | Yes | null | Vendor ID (merchant-specific identifier). |
| secretKey | string | Yes | null | 32-character encryption key for payloads protection. |
| theme | string | No | 'light' | Theme style. Can be 'light' or 'dark'. |
| merchantName| string | No | 'Softmint Retailer' | Display name of the merchant inside the transaction request. |
| onSuccess | function | No | noop | Callback triggered on successful recharges/payments. |
| onError | function | No | noop | Callback triggered on payment errors or failed lookups. |
Cryptography & Security
The SDK performs secure end-to-end client-side encryption before payloads hit your backend.
Request Integrity Hash
A header signature verification is performed to validate request authentication:
- Hash Algorithm:
SHA-256 - Hash String Pattern:
(partnerId + vid + requestId).toLowerCase() - Header Key:
hash
Request Encryption
The request parameters are encrypted before transit using:
- Encryption Algorithm:
AES-256-GCMwith a 128-bit authentication tag. - IV (Initialization Vector): 16-character alphanumeric string generated randomly per request.
- Header Key:
iv - Request Body Payload:
{ "body": "BASE64_ENCRYPTED_STRING" }
Event Callback Schemas
onSuccess(receiptData)
Receives a detailed object with the transaction details:
{
"status": "SUCCESS",
"operatorName": "Electricity Biller",
"cn": "1234567890",
"amount": "1500.00",
"rrn": "RRN998822331122",
"bankRefId": "BK88271625",
"partnerRefId": "REF16283921822",
"timestamp": "12/06/2026, 6:15:00 PM",
"remark": "-googleVoucherCode- 9PNWX5JR288EL67V"
}onError(error)
Fired when lookups fail or a transaction is declined. The error object contains enhanced transaction state if failed after submission:
onError: (err) => {
console.log(err.message); // E.g., "Transaction Failed"
console.log(err.status); // E.g., "FAILED" or "PENDING"
console.log(err.receipt); // Full transaction details object (if available)
}License
MIT License. Copyright © 2026 Softmint.