Pocket Pay BN

A Node.js client library for integrating with the Pocket Pay API (v4.0.3). This package provides a simple and intuitive interface for handling payment transactions, order management, and transaction status checking.

Features

• 🔒 Secure API key and salt authentication
• 🌍 Support for both test and production environments
• 💳 Create and manage payment transactions
• 🔍 Check transaction status
• ❌ Void transactions
• 🎯 Generate order IDs and hashed data
• ⚡ Promise-based API with async/await support
• 🛡️ Built-in error handling

Installation

npm install pocket-pay-bn

Quick Start

import PocketPayAPI from 'pocket-pay-bn';

// Initialize the API client
const pocketPay = new PocketPayAPI({
  apiKey: 'YOUR_API_KEY',
  salt: 'YOUR_SALT',
  environment: 'production' // or 'test'
});

// Create a transaction
const transaction = await pocketPay.createTransaction({
  amount: 100,
  currency: 'BND',
  // ...other transaction data
});

Configuration

Constructor Options

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | apiKey | string | Yes* | Your Pocket Pay API key | | salt | string | Yes* | Your Pocket Pay salt | | environment | string | Yes | Environment to use: 'test' or 'production' |

Note: When using 'test' environment, the API key and salt are automatically set to test credentials, so you don't need to provide them.

Example: Test Environment

const pocketPay = new PocketPayAPI({
  apiKey: '', // Not required for test environment
  salt: '',   // Not required for test environment
  environment: 'test'
});

Example: Production Environment

const pocketPay = new PocketPayAPI({
  apiKey: 'your-production-api-key',
  salt: 'your-production-salt',
  environment: 'production'
});

API Methods

createTransaction(data)

Creates a new payment transaction.

Parameters:

• data (Object): Transaction data including amount, currency, and other required fields

Returns: Promise - Transaction details including order_ref and success_indicator

Example:

try {
  const transaction = await pocketPay.createTransaction({
    amount: 100.50,
    currency: 'BND',
    description: 'Payment for order #12345',
    customer_email: '[email protected]',
    // Add other required fields as per API documentation
  });
  
  console.log('Order Ref:', transaction.order_ref);
  console.log('Success Indicator:', transaction.success_indicator);
} catch (error) {
  console.error('Status:', error.status);
  console.error('Message:', error.message);
}

getNewOrderId()

Generates a new unique order ID.

Returns: Promise - New order ID data

Example:

try {
  const orderData = await pocketPay.getNewOrderId();
  console.log('New Order ID:', orderData);
} catch (error) {
  console.error('Error:', error.message);
}

generateHashedData(data)

Generates hashed data for secure transactions.

Parameters:

• data (Object): Data to be hashed

Returns: Promise - Hashed data

Example:

try {
  const hashedData = await pocketPay.generateHashedData({
    amount: 100,
    currency: 'BND',
    order_id: 'ORDER123'
  });
  
  console.log('Hashed Data:', hashedData);
} catch (error) {
  console.error('Error:', error.message);
}

getTransactionStatus(orderId)

Retrieves the current status of a transaction.

Parameters:

• orderId (string): The order ID to check

Returns: Promise - Transaction status information

Example:

try {
  const status = await pocketPay.getTransactionStatus('ORDER123');
  console.log('Transaction Status:', status);
} catch (error) {
  console.error('Error:', error.message);
}

voidTransaction({ orderId, orderRef, cref, adminName, reason })

Voids an existing transaction. If orderRef is not provided, the method will automatically fetch it using the orderId.

Parameters:

• orderId (string): Order ID - used to fetch orderRef if orderRef is not provided
• orderRef (string): Order reference to void (optional if orderId is provided)
• cref (string): Customer reference
• adminName (string): Name of the admin performing the void
• reason (string): Reason for voiding the transaction

Returns: Promise - Void transaction result

Examples:

Using orderRef directly:

try {
  const result = await pocketPay.voidTransaction({
    orderRef: 'ORDER_REF_123',
    cref: 'CUST_REF_456',
    adminName: 'Admin User',
    reason: 'Customer requested refund'
  });
  
  console.log('Transaction voided:', result);
} catch (error) {
  console.error('Error:', error.message);
}

Using orderId (orderRef will be fetched automatically):

try {
  const result = await pocketPay.voidTransaction({
    orderId: 'ORDER123',
    cref: 'CUST_REF_456',
    adminName: 'Admin User',
    reason: 'Customer requested refund'
  });
  
  console.log('Transaction voided:', result);
} catch (error) {
  console.error('Error:', error.message);
}

Error Handling

The library provides structured error handling. All errors are returned in the following format:

{
  status: number,    // HTTP status code (e.g., 400, 500)
  message: string    // Error message
}

Example:

try {
  const transaction = await pocketPay.createTransaction({
    // transaction data
  });
} catch (error) {
  if (error.status === 401) {
    console.error('Authentication failed:', error.message);
  } else if (error.status === 400) {
    console.error('Invalid request:', error.message);
  } else {
    console.error('Error:', error.message);
  }
}

Environment URLs

• Test Environment: http://pay.threeg.asia
• Production Environment: https://pocket-pay.threeg.asia

The library automatically selects the correct URL based on the environment parameter.

Requirements

• Node.js 14.x or higher
• ES Modules support (uses import/export)

Dependencies

• axios - HTTP client for making API requests

License

ISC

Author

Dev By Jae

Support

For issues, questions, or contributions, please visit the GitHub repository.

Changelog

v4.0.3

• Updated package main entry point from v3.js to v4.js
• Documentation improvements

v4.0.2

• Updated package main entry point from v3.js to v4.js
• Improved code stability and performance

v4.0.1

• Updated voidTransaction() to accept an object parameter with orderId, orderRef, cref, adminName, and reason
• Added automatic orderRef fetching in voidTransaction() when only orderId is provided
• Added orderRef and paymentStatus instance properties
• Changed createTransaction() response to return order_ref instead of order_id
• Updated getNewOrderId() to store the order ID in the instance's orderId property

v4.0.0

• Initial release
• Support for Pocket Pay API v4.0.0
• Transaction creation, status checking, and voiding
• Order ID generation
• Hash generation for secure data
• Test and production environment support