Unofficial Node.js SDK for EPS (Easy Payment System) Payment Gateway - Bangladesh
npm install eps-gateway-nodejs


A well-maintained, unofficial Node.js package for integrating EPS (Easy Payment System) payments. Provides reliable support for initiating and handling transactions with minimal setup.
Official EPS Website: https://www.eps.com.bd
> Note: This is an unofficial SDK created by the developer community. EPS does not provide an official Node.js SDK.
✅ TypeScript Support - Full TypeScript definitions included
✅ Promise-based API - Modern async/await syntax
✅ Automatic Token Management - Handles JWT token caching and renewal
✅ HMACSHA512 Hash Generation - Built-in secure hash utility
✅ Sandbox & Production - Easy environment switching
✅ Input Validation - Validates all parameters before API calls
✅ Error Handling - Comprehensive error messages
✅ Product List Support - Multiple products in single transaction
✅ Zero Dependencies - Only uses axios for HTTP requests
``bash`
npm install eps-gateway-nodejs
or
`bash`
yarn add eps-gateway-nodejs
`javascript
const { EPS, generateTransactionId } = require('eps-gateway-nodejs');
// Initialize EPS
const eps = new EPS({
username: 'your_username@example.com',
password: 'your_password',
hashKey: 'your_hash_key',
merchantId: 'your-merchant-id',
storeId: 'your-store-id',
sandbox: true // Use sandbox for testing
});
// Initialize payment
const payment = await eps.initializePayment({
customerOrderId: 'ORD123',
merchantTransactionId: generateTransactionId(),
totalAmount: 1000,
successUrl: 'https://yoursite.com/payment/success',
failUrl: 'https://yoursite.com/payment/fail',
cancelUrl: 'https://yoursite.com/payment/cancel',
customerName: 'John Doe',
customerEmail: 'john@example.com',
customerPhone: '01712345678',
customerAddress: 'Dhaka',
customerCity: 'Dhaka',
customerState: 'Dhaka',
customerPostcode: '1200',
productName: 'Test Product'
});
// Redirect user to payment page
console.log('Redirect to:', payment.RedirectURL);
// Verify payment (after callback)
const verification = await eps.verifyPayment({
merchantTransactionId: 'your_transaction_id'
});
if (verification.Status === 'Success') {
console.log('Payment successful!');
}
`
| Parameter | Type | Description |
|-----------|------|-------------|
| username | string | EPS merchant username (usually email) |password
| | string | EPS merchant password |hashKey
| | string | Hash key provided by EPS (base64 encoded) |merchantId
| | string | Merchant ID (UUID format) |storeId
| | string | Store ID (UUID format) |
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| sandbox | boolean | false | Use sandbox environment for testing |timeout
| | number | 30000 | Request timeout in milliseconds |
`bash`
EPS_USERNAME=merchant@example.com
EPS_PASSWORD=your_password
EPS_HASH_KEY=your_hash_key_base64
EPS_MERCHANT_ID=094980ee-xxxx-xxxx-xxxx-xxxxxxxxxxxx
EPS_STORE_ID=35b518f6-xxxx-xxxx-xxxx-xxxxxxxxxxxx
EPS_SANDBOX=true
`javascript`
const eps = new EPS({
username: process.env.EPS_USERNAME,
password: process.env.EPS_PASSWORD,
hashKey: process.env.EPS_HASH_KEY,
merchantId: process.env.EPS_MERCHANT_ID,
storeId: process.env.EPS_STORE_ID,
sandbox: process.env.EPS_SANDBOX === 'true'
});
`javascript`
const payment = await eps.initializePayment(params);
#### Required Parameters
`javascript
{
// Order Information
customerOrderId: 'ORD123', // Your unique order ID
merchantTransactionId: '20240117001', // Unique transaction ID (min 10 digits)
totalAmount: 1000, // Amount in BDT
// Callback URLs
successUrl: 'https://yoursite.com/success',
failUrl: 'https://yoursite.com/fail',
cancelUrl: 'https://yoursite.com/cancel',
// Customer Information
customerName: 'John Doe',
customerEmail: 'john@example.com',
customerPhone: '01712345678', // Bangladesh format: 01XXXXXXXXX
customerAddress: 'House 123, Road 456',
customerCity: 'Dhaka',
customerState: 'Dhaka',
customerPostcode: '1200',
// Product Information
productName: 'Test Product'
}
`
#### Optional Parameters
`javascript
{
// Transaction Type
transactionTypeId: TransactionType.WEB, // WEB=1, ANDROID=2, IOS=3
// Additional Customer Info
customerAddress2: 'Sector 7, Uttara',
customerCountry: 'BD',
// Shipping Information
shipmentName: 'John Doe',
shipmentAddress: 'House 123',
shipmentCity: 'Dhaka',
shipmentState: 'Dhaka',
shipmentPostcode: '1200',
shipmentCountry: 'BD',
// Product Details
productProfile: 'general',
productCategory: 'Electronics',
noOfItem: 1,
// Multiple Products
productList: [
{
ProductName: 'Product 1',
NoOfItem: 2,
ProductPrice: 500,
ProductProfile: 'Description',
ProductCategory: 'Category'
}
],
// Custom Values (for your reference)
valueA: 'custom_data_1',
valueB: 'custom_data_2',
valueC: 'custom_data_3',
valueD: 'custom_data_4',
// Other
shippingMethod: 'NO',
ipAddress: '103.45.67.89'
}
`
#### Response
`javascript`
{
TransactionId: '23e02880-f378-4594-86f8-30ecb5998094',
RedirectURL: 'https://pg.eps.com.bd/PG?data=...',
ErrorMessage: '',
ErrorCode: null
}
`javascript
// Method 1: Verify by merchant transaction ID
const result = await eps.verifyPayment({
merchantTransactionId: '20240117001'
});
// Method 2: Verify by EPS transaction ID
const result = await eps.verifyPayment({
epsTransactionId: 'C2549190401'
});
// Method 3: Quick status check
const isSuccessful = await eps.isPaymentSuccessful('20240117001');
`
#### Response
`javascript
{
MerchantTransactionId: '20240117001',
EpsTransactionId: 'C2549190401',
Status: 'Success', // Success, Failed, Pending
TotalAmount: '1000.00',
TransactionDate: '17 Jan 2024 06:30:15 PM',
TransactionType: 'Purchase',
FinancialEntity: 'OKWallet', // Payment method used
// Customer details
CustomerName: 'John Doe',
CustomerEmail: 'john@example.com',
CustomerPhone: '01712345678',
// Error info (if any)
ErrorCode: '',
ErrorMessage: ''
}
`
`javascript`
const payment = await eps.initializePayment({...});
`javascript`
// Redirect user to EPS payment page
res.redirect(payment.RedirectURL);
EPS will redirect users back to your URLs with transaction details:
#### Success URL
``
https://yoursite.com/payment/success?merchantTransactionId=xxx&status=success
#### Fail URL
``
https://yoursite.com/payment/fail?merchantTransactionId=xxx&status=failed
#### Cancel URL
``
https://yoursite.com/payment/cancel?merchantTransactionId=xxx&status=cancelled
`javascript
router.get('/payment/success', async (req, res) => {
const { merchantTransactionId } = req.query;
// ALWAYS verify with EPS
const verification = await eps.verifyPayment({ merchantTransactionId });
if (verification.Status === 'Success') {
// Payment confirmed - Update your database
await updateOrderStatus(merchantTransactionId, 'PAID');
res.render('success', { transaction: verification });
} else {
res.redirect('/payment/fail');
}
});
`
`javascript
const express = require('express');
const { EPS, generateTransactionId } = require('eps-gateway-nodejs');
const app = express();
const eps = new EPS({...});
// Initiate payment
app.post('/payment/initiate', async (req, res) => {
try {
const payment = await eps.initializePayment({
customerOrderId: req.body.orderId,
merchantTransactionId: generateTransactionId(),
totalAmount: req.body.amount,
successUrl: ${req.protocol}://${req.get('host')}/payment/success,${req.protocol}://${req.get('host')}/payment/fail
failUrl: ,${req.protocol}://${req.get('host')}/payment/cancel
cancelUrl: ,
...req.body.customer,
productName: req.body.productName
});
res.redirect(payment.RedirectURL);
} catch (error) {
res.status(500).json({ error: error.message });
}
});
// Success callback
app.get('/payment/success', async (req, res) => {
const verification = await eps.verifyPayment({
merchantTransactionId: req.query.merchantTransactionId
});
if (verification.Status === 'Success') {
// Update database, send email, etc.
res.render('payment-success', { data: verification });
} else {
res.redirect('/payment/fail');
}
});
`
`javascript
const { generateTransactionId } = require('eps-gateway-nodejs');
const txnId = generateTransactionId();
// Returns: 20240117123456789 (17 digits, timestamp-based)
`
`javascript
const { generateHash } = require('eps-gateway-nodejs');
const hash = generateHash('value_to_hash', 'your_hash_key');
// Returns: Base64 HMACSHA512 hash
`
`javascript
const { EPSError } = require('eps-gateway-nodejs');
try {
const payment = await eps.initializePayment({...});
} catch (error) {
if (error instanceof EPSError) {
console.error('EPS Error:', error.message);
console.error('Error Code:', error.code);
console.error('Response:', error.response);
} else {
console.error('Unknown error:', error);
}
}
`
| Code | Description |
|------|-------------|
| INVALID_CONFIG | Invalid configuration parameters |INVALID_PARAMS
| | Invalid payment parameters |AUTH_ERROR
| | Authentication failed |INIT_ERROR
| | Payment initialization failed |VERIFY_ERROR
| | Transaction verification failed |NETWORK_ERROR
| | Network/connection error |
`typescript
import { EPS, InitializePaymentParams, VerifyPaymentResponse, TransactionType } from 'eps-gateway-nodejs';
const eps = new EPS({
username: 'merchant@example.com',
password: 'password',
hashKey: 'hash_key',
merchantId: 'merchant-id',
storeId: 'store-id',
sandbox: true
});
const params: InitializePaymentParams = {
customerOrderId: 'ORD123',
merchantTransactionId: '20240117001',
totalAmount: 1000,
transactionTypeId: TransactionType.WEB,
// ... other params
};
const payment = await eps.initializePayment(params);
const verification: VerifyPaymentResponse = await eps.verifyPayment({
merchantTransactionId: '20240117001'
});
`
`javascript`
const eps = new EPS({
username: 'sandbox_username',
password: 'sandbox_password',
hashKey: 'sandbox_hash_key',
merchantId: 'sandbox-merchant-id',
storeId: 'sandbox-store-id',
sandbox: true // Important!
});
Contact EPS support to get sandbox credentials for testing.
Check the /examples directory for complete working examples:
- initialize-payment.js - Basic payment initializationverify-payment.js
- - Payment verificationcomplete-flow.js
- - Complete payment flow with Express.js integration
Run examples:
`bash`
npm run build
node examples/initialize-payment.js
node examples/verify-payment.js
node examples/complete-flow.js
Never trust callback URLs alone. Always verify payment status with EPS:
`javascript
// ❌ BAD - Don't trust the callback alone
app.get('/payment/success', async (req, res) => {
// Directly mark as paid - INSECURE!
await markOrderAsPaid(req.query.orderId);
});
// ✅ GOOD - Always verify with EPS
app.get('/payment/success', async (req, res) => {
const verification = await eps.verifyPayment({
merchantTransactionId: req.query.merchantTransactionId
});
if (verification.Status === 'Success') {
await markOrderAsPaid(req.query.orderId);
}
});
`
`javascript`
// Save transaction details before redirecting
await Payment.create({
orderId: 'ORD123',
merchantTransactionId: txnId,
epsTransactionId: payment.TransactionId,
amount: 1000,
status: 'INITIATED'
});
`javascript`
// Never hardcode credentials
const eps = new EPS({
username: process.env.EPS_USERNAME,
password: process.env.EPS_PASSWORD,
hashKey: process.env.EPS_HASH_KEY,
merchantId: process.env.EPS_MERCHANT_ID,
storeId: process.env.EPS_STORE_ID,
sandbox: process.env.NODE_ENV !== 'production'
});
`javascript`
try {
const payment = await eps.initializePayment(params);
res.redirect(payment.RedirectURL);
} catch (error) {
logger.error('Payment initiation failed:', error);
res.render('payment-error', {
message: 'Unable to process payment. Please try again.'
});
}
`javascript
const { generateTransactionId } = require('eps-gateway-nodejs');
// Always generate unique transaction IDs
const txnId = generateTransactionId(); // Timestamp-based, 17 digits
// Or use your own format (minimum 10 digits)
const customTxnId = ${Date.now()}${Math.random().toString().slice(2, 6)};`
Suggestions, improvements, and pull requests are always welcome!
1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)git commit -m 'Add some AmazingFeature'
3. Commit your changes ()git push origin feature/AmazingFeature
4. Push to the branch ()
5. Open a Pull Request
`bash``
git clone https://github.com/imtiaznajim/eps-gateway-nodejs.git
cd eps-gateway-nodejs
npm install
npm run build
npm test
MIT License - see the LICENSE file for details
This is an unofficial SDK. The author is not affiliated with EPS (Easy Payment System). Use at your own risk.
Imtiaz Najim
- GitHub: @imtiaznajim
- Email: imtiaznajim@gmail.com
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- ⭐ Star this repo if you find it helpful!
- Thanks to EPS (Easy Payment System) for providing the payment gateway service
- Built with ❤️ for the Bangladesh developer community
- bkash-payment - bKash Payment Gateway SDK
---
Made with ❤️ for the Bangladesh developer community