tnextpay-nodejs

Enterprise-ready Node.js SDK for integrating with the TnextPay payment gateway.

tnextpay-node provides a secure, signed-request client for creating payment orders and verifying transactions, with environment-aware configuration, debug observability, and robust fallback behavior for route differences across deployments.

Table of Contents

• Key Features
• Requirements
• Installation
• Quick Start
• Configuration
• API Reference
• Error Handling
• Security Best Practices
• Troubleshooting
• Development
• Release & Versioning
• License

Key Features

• HMAC-SHA256 request signing with canonical header composition
• Automatic request digest generation (SHA-256=...)
• Payment creation endpoint support
• Payment verification with route fallback support across environments
• Staging and production environment support
• Debug mode with full request/response traces for faster incident triage
• Simple Promise-based API built on Axios

Requirements

• Node.js 16+ (Node.js 18+ recommended)
• npm 8+

Installation

npm install tnextpay-node

Quick Start

1) Initialize the client

const TnextPayClient = require('tnextpay-nodejs');

const client = new TnextPayClient({
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
  merchantId: process.env.MERCHANT_ID,
  environment: 'staging', // or 'live'
  // baseURL: 'http://your-local-gateway:8094', // optional override
  debug: false,
});

2) Create a payment order

const response = await client.createPayment({
  orderId: `ORDER_${Date.now()}`,
  amount: '10.00',
  currency: 'BDT',
  ipnUrl: 'https://merchant.example.com/ipn',
  successUrl: 'https://merchant.example.com/success',
  cancelUrl: 'https://merchant.example.com/cancel',
  failureUrl: 'https://merchant.example.com/failure',
  customerInfo: {
    name: 'Jane Doe',
    email: '[email protected]',
    contact_number: '01700000000',
  },
});

console.log(response);

3) Verify a payment

const verification = await client.verifyPayment('PAYMENT_ORDER_ID');
console.log(verification);

Configuration

Create the client with:

| Field | Type | Required | Default | Description | |---|---|---:|---|---| | apiKey | string | Yes | - | TnextPay API key | | apiSecret | string | Yes | - | TnextPay API secret used for HMAC signature | | merchantId | string | Yes | - | Merchant identifier | | environment | 'staging' \| 'live' | No | 'staging' | Selects hosted base URL | | baseURL | string | No | from environment | Override API host (useful for local/private gateway) | | debug | boolean | No | false | Enables verbose request/response logs | | useHostnameOnly | boolean | No | false | Signs host as hostname[:port] instead of full URL | | includeTrailingNewline | boolean | No | false | Appends trailing newline to canonical signing string | | stripVersionPrefix | boolean | No | true | Removes /payment/api/v1 from signed target path |

Environment URLs

• Staging: https://api-stage.tnextpay.com
• Live: https://api.tnextpay.com

API Reference

createPayment(params)

Creates a new payment order.

Required fields

• orderId (string)
• amount (number | string)
• currency (string, e.g. BDT)
• ipnUrl (string)
• successUrl (string)

Optional fields

• cancelUrl, failureUrl
• promotionInformation
• customerInfo
• shippingInfo
• mdf1, mdf2, mdf3, mdf4

Returns a Promise resolving to TnextPay response payload.

verifyPayment(paymentOrderId)

Verifies payment status using the provided payment order ID.

• Primary route: /payment/api/v1/p/service/api/payment/processing/verify
• Fallback route: /p/service/api/payment/processing/verify

Returns a Promise resolving to TnextPay response payload.

Error Handling

The SDK throws an Error when upstream responses indicate failure.

try {
  const res = await client.verifyPayment(paymentOrderId);
} catch (error) {
  console.error(error.message);

  // available for HTTP errors from gateway
  console.error(error.status);        // number | undefined
  console.error(error.responseData);  // object | string | undefined
}

Security Best Practices

• Never hardcode apiSecret in source code.
• Store credentials in environment variables or a secrets manager.
• Rotate API keys on a defined schedule.
• Restrict IPs and network paths to trusted infrastructure when possible.
• Keep debug: false in production to avoid exposing sensitive metadata in logs.

Troubleshooting

INVALID_SIGNATURE or 401 UNAUTHORIZED

Validate these items first:

• apiKey, apiSecret, and merchantId are correct for the target environment
• baseURL matches the environment where those credentials are provisioned
• system clock is accurate (NTP synchronized)
• canonical signing settings match gateway expectations:
  • useHostnameOnly
  • includeTrailingNewline
  • stripVersionPrefix

403 on verify

Some deployments block non-versioned verify routes. The SDK tries the versioned path first and falls back automatically.

404 Route Not Found

Usually indicates environment/route mismatch. Recheck baseURL and verify endpoint availability in that deployment.

Development

Install dependencies

npm install

Run tests

npm test

Run examples

npm run example:create
npm run example:verify

Release & Versioning

• Versioning follows semantic versioning principles.
• Backward-compatible changes are released as minor/patch updates.
• Breaking API changes are released as major versions.

License

MIT