bKash Checkout (URL Based) Payment Integration

A Node.js/TypeScript library for bKash Checkout (URL Based) payment integration with advanced features including retry mechanisms, event handling, webhook support, and complete transaction lifecycle management.

What This Package Covers

Core Payment Features

Payment Creation: Create secure checkout payments with bKash URL-based integration
Payment Execution: Execute payments after customer authorization through bKash app/USSD
Payment Verification: Verify payment status and retrieve transaction details
Payment Queries: Query payment status with detailed transaction information
Transaction Status Checking: Real-time transaction status monitoring

Advanced Refund System (v2 API)

Full & Partial Refunds: Process complete or partial refunds (up to 10 partial refunds per transaction)
Refund Status Tracking: Check refund transaction status and history
SKU & Reason Tracking: Track refunds with product information and reasons

Transaction Management

Transaction Search: Search transactions by bKash transaction ID with comprehensive details
Transaction History: Access customer details, timing information, and transaction lifecycle
Organization Data: Retrieve merchant and organization information
Customer Information: Access customer MSISDN and transaction references

Security & Authentication

Automatic Token Management: Smart token caching, renewal, and refresh handling
Webhook Security: HMAC SHA256 signature verification for webhook authenticity
Secure API Calls: Built-in request/response validation and error handling
Retry Mechanisms: Automatic retry for failed operations with configurable delays

Developer Experience

Full TypeScript Support: Complete type definitions and IntelliSense support
Event-Driven Architecture: Real-time event emissions for payment lifecycle
Comprehensive Logging: Detailed logging with configurable levels using Winston
Validation: Zod schema validation for all inputs and outputs
Express.js Integration: Ready-to-use examples and middleware support
Test Coverage: Comprehensive Jest test suite with 95%+ coverage

Installation

npm install bkash-js
# or
yarn add bkash-js
# or
pnpm add bkash-js

Configuration Options

interface BkashConfig {
  // Required Authentication
  username: string;           // bKash merchant username
  password: string;           // bKash merchant password
  appKey: string;            // bKash application key
  appSecret: string;         // bKash application secret
  
  // Environment & Behavior
  isSandbox?: boolean;       // Default: false (production)
  timeout?: number;          // Request timeout in ms (default: 30000)
  maxRetries?: number;       // Max retry attempts (default: 3)
  retryDelay?: number;       // Delay between retries in ms (default: 1000)
  log?: boolean;             // Enable detailed logging (default: false)
  
  // Advanced Webhook Configuration
  webhook?: {
    secret: string;          // Webhook signature verification secret
    path?: string;           // Webhook endpoint path
    onEvent?: (event: BkashEvent) => Promise<void>; // Custom event handler
  };
}

Quick Start

import { BkashPayment } from 'bkash-js'; // Uses the refactored SOLID architecture

const bkash = new BkashPayment({
  appKey: 'your_app_key',
  appSecret: 'your_app_secret',
  username: 'your_username',
  password: 'your_password',
  isSandbox: true, // false for production
  log: true, // Enable detailed logging
  timeout: 30000, // Request timeout
  maxRetries: 3, // Retry failed requests
  webhook: {
    secret: 'your_webhook_secret' // For webhook verification
  }
});

// Create payment with enhanced options
const payment = await bkash.createPayment({
  amount: '100.50',
  currency: 'BDT',
  intent: 'sale',
  merchantInvoiceNumber: 'INV-' + Date.now(),
  payerReference: '01712345678',
  callbackURL: 'https://yoursite.com/callback',
  merchantAssociationInfo: 'MI05MID54RF09123456789' // Optional for aggregators
});

// Execute payment after customer authorization
const executed = await bkash.executePayment(payment.paymentID);

Advanced Usage - Individual Services

For advanced use cases, you can use individual services with dependency injection:

import { 
  BkashServiceFactory, 
  PaymentService, 
  TokenManager,
  IPaymentService,
  ITokenManager 
} from 'bkash-js';

// Create service factory
const factory = new BkashServiceFactory(config);

// Use individual services
const tokenManager: ITokenManager = factory.getTokenManager();
const paymentService: IPaymentService = factory.getPaymentService();

// Direct service usage
const token = await tokenManager.getToken();
const payment = await paymentService.createPayment(paymentData);

// Custom implementations (for testing or customization)
class CustomTokenManager implements ITokenManager {
  // Your custom implementation
}

Event-Driven Architecture

Listen to real-time payment events for better integration:

// Listen to all bKash events
bkash.on('bkash:event', (event) => {
  console.log(`Event Type: ${event.type}`);
  console.log('Event Data:', event.data);
  console.log('Timestamp:', event.timestamp);
});

// Available event types:
// - payment.created      - Payment request created
// - payment.success      - Payment executed successfully
// - payment.failed       - Payment execution failed
// - payment.cancelled    - Payment cancelled by user
// - refund.success       - Refund processed successfully
// - refund.failed        - Refund processing failed
// - refund.status.checked - Refund status retrieved
// - refund.status.failed  - Refund status check failed

// Handle specific events
bkash.on('bkash:event', (event) => {
  switch (event.type) {
    case 'payment.success':
      console.log('✅ Payment completed:', event.data.trxID);
      // Update database, send notifications, etc.
      break;
      
    case 'payment.failed':
      console.log('❌ Payment failed:', event.data.statusMessage);
      // Handle failed payment, retry logic, etc.
      break;
      
    case 'refund.success':
      console.log('💰 Refund processed:', event.data.refundTrxId);
      // Update order status, notify customer, etc.
      break;
  }
});

API Documentation

Payment Operations

`createPayment(data: PaymentData)`

Creates a new checkout payment request with complete API response.

Parameters:

payerReference - Customer mobile number or reference
callbackURL - URL for payment status callbacks
amount - Payment amount as string (e.g., "100.50")
currency - Currency code (currently only "BDT")
intent - Payment intent (typically "sale")
merchantInvoiceNumber - Unique merchant invoice number
merchantAssociationInfo - Optional for aggregators (max 255 chars)
mode - Payment mode (default: "0011" for checkout)

Returns: Complete payment response with bKash URL and callback URLs

const payment = await bkash.createPayment({
  payerReference: '01712345678',
  callbackURL: 'https://yoursite.com/callback',
  amount: '250.75',
  currency: 'BDT',
  intent: 'sale',
  merchantInvoiceNumber: 'INV-' + Date.now(),
  merchantAssociationInfo: 'MI05MID54RF09123456789'
});

console.log('Payment ID:', payment.paymentID);
console.log('Redirect to:', payment.bkashURL);
console.log('Success callback:', payment.successCallbackURL);

`executePayment(paymentID: string)`

Finalizes a payment after customer completes authorization in bKash app.

Returns: Complete execution response with transaction details

const result = await bkash.executePayment(payment.paymentID);

if (result.transactionStatus === 'Completed') {
  console.log('✅ Payment successful!');
  console.log('Transaction ID:', result.trxID);
  console.log('Customer:', result.customerMsisdn);
  console.log('Amount:', result.amount, result.currency);
  console.log('Completed at:', result.paymentExecuteTime);
} else {
  console.log('❌ Payment failed:', result.statusMessage);
}

`queryPayment(paymentID: string)`

Retrieves comprehensive payment status and details.

Returns: Complete payment information including verification status

const status = await bkash.queryPayment(paymentID);

console.log('Transaction Status:', status.transactionStatus);
console.log('User Verification:', status.userVerificationStatus);
console.log('Payment Created:', status.paymentCreateTime);

if (status.transactionStatus === 'Completed') {
  console.log('Transaction ID:', status.trxID);
  console.log('Executed at:', status.paymentExecuteTime);
}

`verifyPayment(paymentId: string)`

Verifies payment completion and retrieves verification details.

const verification = await bkash.verifyPayment(paymentId);
console.log('Verification status:', verification.status);

Advanced Refund System (v2 API)

`refundPayment(data: RefundData)`

Process full or partial refunds with enhanced tracking (supports up to 10 partial refunds).

Parameters:

paymentId - Original payment ID from create payment
trxId - Original transaction ID from execute payment
refundAmount - Refund amount as string with max 2 decimals
sku - Product/service identifier (max 255 chars)
reason - Refund reason (max 255 chars)

const refund = await bkash.refundPayment({
  paymentId: 'TR0001xt7mXxG1718274354990',
  trxId: 'BFD90JRLST',
  refundAmount: '50.25', // Partial refund
  sku: 'PRODUCT-SKU-001',
  reason: 'Customer requested partial refund for damaged item'
});

if (refund.refundTransactionStatus === 'Completed') {
  console.log('✅ Refund successful!');
  console.log('Refund Transaction ID:', refund.refundTrxId);
  console.log('Original Amount:', refund.originalTrxAmount);
  console.log('Refunded Amount:', refund.refundAmount);
  console.log('Completed at:', refund.completedTime);
}

`checkRefundStatus(data: RefundStatusRequest)`

Check status of all refunds for a specific transaction.

const refundStatus = await bkash.checkRefundStatus({
  paymentId: 'TR0001xt7mXxG1718274354990',
  trxId: 'BFD90JRLST'
});

console.log('Original Transaction:', refundStatus.originalTrxId);
console.log('Original Amount:', refundStatus.originalTrxAmount);
console.log('Total Refunds:', refundStatus.refundTransactions.length);

// Check each refund
refundStatus.refundTransactions.forEach((refund, index) => {
  console.log(`Refund ${index + 1}:`);
  console.log(`  Status: ${refund.refundTransactionStatus}`);
  console.log(`  Amount: ${refund.refundAmount}`);
  console.log(`  Completed: ${refund.completedTime}`);
});

🔍 Transaction Management

`searchTransaction(data: SearchTransactionData)`

Search transactions with comprehensive details including customer information.

const result = await bkash.searchTransaction({
  trxID: '6H7XXXXTCT'
});

console.log('Transaction Details:');
console.log('- ID:', result.trxID);
console.log('- Status:', result.transactionStatus);
console.log('- Type:', result.transactionType);
console.log('- Amount:', result.amount, result.currency);
console.log('- Customer:', result.customerMsisdn);
console.log('- Merchant:', result.organizationShortCode);
console.log('- Initiated:', result.initiationTime);
console.log('- Completed:', result.completedTime);

if (result.transactionReference) {
  console.log('- Reference:', result.transactionReference);
}

Advanced Authentication & Token Management

`grantToken()`

Get new access token with complete response details.

const tokenResponse = await bkash.grantToken();

console.log('Access Token:', tokenResponse.id_token);
console.log('Expires in:', tokenResponse.expires_in, 'seconds');
console.log('Refresh Token:', tokenResponse.refresh_token);
console.log('Token Type:', tokenResponse.token_type);

`refreshToken(refreshToken: string)`

Refresh expired access token.

const newToken = await bkash.refreshToken(existingRefreshToken);
console.log('New Access Token:', newToken.id_token);

Webhook Integration & Security

`handleWebhook(payload: unknown, signature?: string)`

Process webhook notifications with automatic signature verification.

// Express.js webhook endpoint
app.post('/webhook/bkash', async (req, res) => {
  try {
    const signature = req.headers['x-bkash-signature'] as string;
    await bkash.handleWebhook(req.body, signature);
    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook verification failed:', error.message);
    res.status(400).send('Unauthorized');
  }
});

`verifyWebhookSignature(payload: string, signature: string)`

Manually verify webhook signatures for enhanced security.

const payload = JSON.stringify(req.body);
const signature = req.headers['x-bkash-signature'] as string;

if (bkash.verifyWebhookSignature(payload, signature)) {
  console.log('✅ Webhook signature is valid');
  // Process webhook safely
} else {
  console.log('❌ Invalid webhook signature');
  // Reject the webhook
}

`createWebhookEvent(type: BkashEventType, data: any)`

Create standardized webhook events for testing or simulation.

// Simulate webhook events for testing
const webhookEvent = bkash.createWebhookEvent('payment.success', {
  paymentID: 'TEST123',
  transactionStatus: 'Completed',
  amount: '100.00'
});

await bkash.handleWebhook(webhookEvent);

API Response Examples

Create Payment Response

{
  "paymentID": "TR0001xt7mXxG1718274354990",
  "paymentCreateTime": "2024-06-13T12:32:35:033 GMT+0600",
  "transactionStatus": "Initiated",
  "amount": "100.50",
  "currency": "BDT",
  "intent": "sale",
  "merchantInvoiceNumber": "INV-1718274354990",
  "bkashURL": "https://checkout.sandbox.bka.sh/v1.2.0-beta/checkout/payment/create/TR0001xt7mXxG1718274354990",
  "callbackURL": "https://yoursite.com/callback",
  "successCallbackURL": "https://checkout.sandbox.bka.sh/v1.2.0-beta/checkout/payment/callback/success/TR0001xt7mXxG1718274354990",
  "failureCallbackURL": "https://checkout.sandbox.bka.sh/v1.2.0-beta/checkout/payment/callback/failure/TR0001xt7mXxG1718274354990",
  "cancelledCallbackURL": "https://checkout.sandbox.bka.sh/v1.2.0-beta/checkout/payment/callback/cancel/TR0001xt7mXxG1718274354990",
  "statusCode": "0000",
  "statusMessage": "Successful"
}

Execute Payment Response

{
  "paymentID": "TR0001xt7mXxG1718274354990",
  "statusCode": "0000",
  "statusMessage": "Successful",
  "customerMsisdn": "01712345678",
  "payerReference": "01712345678",
  "paymentExecuteTime": "2024-06-13T12:35:42:127 GMT+0600",
  "trxID": "BFD90JRLST",
  "transactionStatus": "Completed",
  "amount": "100.50",
  "currency": "BDT",
  "intent": "sale",
  "merchantInvoiceNumber": "INV-1718274354990"
}

Refund Response

{
  "originalTrxId": "BFD90JRLST",
  "refundTrxId": "BFE91KSMTU",
  "refundTransactionStatus": "Completed",
  "originalTrxAmount": "100.50",
  "refundAmount": "50.25",
  "currency": "BDT",
  "completedTime": "2024-06-13T13:15:28:456 GMT+0600",
  "sku": "PRODUCT-SKU-001",
  "reason": "Customer requested partial refund"
}

Error Handling

import { BkashError } from 'bkash-js';

try {
  const payment = await bkash.createPayment(paymentData);
} catch (error) {
  if (error instanceof BkashError) {
    console.error('bKash Error:', {
      message: error.message,
      code: error.code,
      details: error.details
    });
    
    // Handle specific error codes
    switch (error.code) {
      case 'TOKEN_ERROR':
        console.log('Authentication failed - check credentials');
        break;
      case 'PAYMENT_CREATE_ERROR':
        console.log('Payment creation failed - check payment data');
        break;
      case 'PAYMENT_EXECUTE_ERROR':
        console.log('Payment execution failed - payment may be expired');
        break;
      case 'REFUND_ERROR':
        console.log('Refund failed - check refund eligibility');
        break;
      default:
        console.log('Unknown bKash error occurred');
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Fork and clone the repository
git clone https://github.com/ShejanMahamud/bkash-js.git
cd bkash-js

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build the project
npm run build

# Run linting
npm run lint

# Format code
npm run format

Reporting Issues

Please use the GitHub Issues page to report bugs or request features.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

bKash Limited for providing the payment gateway API
The Node.js and TypeScript communities for excellent tooling
All contributors who help improve this package

Support

Email: [email protected]
Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: API Reference

⭐ If this package helped you, please give it a star on GitHub! ⭐

Made with ❤️ by Shejan Mahamud

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
examples		examples
scripts		scripts
src		src
.editorconfig		.editorconfig
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsconfig.prod.json		tsconfig.prod.json

License

ShejanMahamud/bkash-js

Folders and files

Latest commit

History

Repository files navigation

bKash Checkout (URL Based) Payment Integration

What This Package Covers

Core Payment Features

Advanced Refund System (v2 API)

Transaction Management

Security & Authentication

Developer Experience

Installation

Configuration Options

Quick Start

Advanced Usage - Individual Services

Event-Driven Architecture

API Documentation

Payment Operations

createPayment(data: PaymentData)

executePayment(paymentID: string)

queryPayment(paymentID: string)

verifyPayment(paymentId: string)

Advanced Refund System (v2 API)

refundPayment(data: RefundData)

checkRefundStatus(data: RefundStatusRequest)

🔍 Transaction Management

searchTransaction(data: SearchTransactionData)

Advanced Authentication & Token Management

grantToken()

refreshToken(refreshToken: string)

Webhook Integration & Security

handleWebhook(payload: unknown, signature?: string)

verifyWebhookSignature(payload: string, signature: string)

createWebhookEvent(type: BkashEventType, data: any)

API Response Examples

Create Payment Response

Execute Payment Response

Refund Response

Error Handling

🤝 Contributing

Development Setup

Reporting Issues

License

Acknowledgments

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

`createPayment(data: PaymentData)`

`executePayment(paymentID: string)`

`queryPayment(paymentID: string)`

`verifyPayment(paymentId: string)`

`refundPayment(data: RefundData)`

`checkRefundStatus(data: RefundStatusRequest)`

`searchTransaction(data: SearchTransactionData)`

`grantToken()`

`refreshToken(refreshToken: string)`

`handleWebhook(payload: unknown, signature?: string)`

`verifyWebhookSignature(payload: string, signature: string)`

`createWebhookEvent(type: BkashEventType, data: any)`

Packages