PAX Payment SDK for Node.js

Official Node.js SDK for the PAX Payment Gateway - A unified payment gateway aggregator supporting multiple payment providers.

Installation

npm install @techsavvyash/pax
# or
yarn add @techsavvyash/pax
# or
bun add @techsavvyash/pax

Features

• Multiple payment gateway support (Razorpay, PayU, Paytm)
• TypeScript support with full type definitions
• Idempotency key support for safe retries
• Credit balance management
• Transaction management (initiate, fetch, list, refund)
• Built-in error handling
• Configurable timeout and API endpoints

Quick Start

import { PaxClient } from '@techsavvyash/pax';

// Initialize the client
const pax = new PaxClient({
  apiKey: 'your_api_key',
  apiUrl: 'https://api.pax.example.com', // Optional, defaults to production
  timeout: 30000 // Optional, defaults to 30 seconds
});

// Initiate a payment
const payment = await pax.initiatePayment({
  amount: 100,
  currency: 'INR',
  user_id: '[email protected]',
  metadata: {
    order_id: 'order_123',
    product: 'Premium Plan'
  },
  success_url: 'https://yourapp.com/payment/success',
  failure_url: 'https://yourapp.com/payment/failure'
});

console.log('Payment URL:', payment.redirect_url);
console.log('Transaction ID:', payment.transaction_id);

API Reference

Client Initialization

const pax = new PaxClient({
  apiKey: string;      // Required: Your PAX API key
  apiUrl?: string;     // Optional: API endpoint URL
  timeout?: number;    // Optional: Request timeout in milliseconds
});

Methods

initiatePayment(request, idempotencyKey?)

Creates a new payment transaction.

const payment = await pax.initiatePayment(
  {
    amount: 500,
    currency: 'INR',
    user_id: '[email protected]',
    metadata: { order_id: 'order_123' },
    success_url: 'https://yourapp.com/success',
    failure_url: 'https://yourapp.com/failure',
    gateway: 'razorpay' // Optional: specify gateway
  },
  'unique-idempotency-key' // Optional: for safe retries
);

Response:

{
  transaction_id: string;
  redirect_url: string;
  status: 'initiated' | 'pending' | 'processing' | 'completed' | 'failed';
  amount: number;
  currency: string;
  gateway: string;
}

getTransaction(transactionId)

Fetches details of a specific transaction.

const transaction = await pax.getTransaction('transaction_id');

Response:

{
  transaction_id: string;
  user_id: string;
  amount: number;
  currency: string;
  status: TransactionStatus;
  gateway: string;
  external_order_id?: string;
  metadata?: Record<string, any>;
  created_at: string;
  updated_at: string;
}

listTransactions(filters?)

Lists transactions with optional filters.

const transactions = await pax.listTransactions({
  user_id: '[email protected]',
  status: 'completed',
  limit: 10,
  offset: 0
});

refundTransaction(transactionId, request)

Initiates a refund for a transaction.

const refund = await pax.refundTransaction('transaction_id', {
  amount: 100, // Optional: partial refund amount
  reason: 'Customer request'
});

getCreditBalance(userId)

Fetches credit balance for a user.

const balance = await pax.getCreditBalance('[email protected]');
console.log('Available credits:', balance.balance);

TypeScript Support

The SDK is written in TypeScript and provides comprehensive type definitions:

import {
  PaxClient,
  PaxConfig,
  InitiatePaymentRequest,
  InitiatePaymentResponse,
  Transaction,
  TransactionStatus,
  RefundRequest,
  RefundResponse
} from '@techsavvyash/pax';

Error Handling

The SDK throws PaxSDKError for all API-related errors:

import { PaxClient, PaxSDKError } from '@techsavvyash/pax';

try {
  const payment = await pax.initiatePayment({
    amount: 100,
    currency: 'INR',
    user_id: '[email protected]'
  });
} catch (error) {
  if (error instanceof PaxSDKError) {
    console.error('PAX Error:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Response:', error.response);
  }
}

Idempotency

Use idempotency keys to safely retry payment requests:

const idempotencyKey = `order_${orderId}`;

// First request
const payment1 = await pax.initiatePayment(request, idempotencyKey);

// Retry with same key returns same response
const payment2 = await pax.initiatePayment(request, idempotencyKey);

// payment1.transaction_id === payment2.transaction_id

Complete Example: E-commerce Checkout

import { PaxClient } from '@techsavvyash/pax';
import express from 'express';

const app = express();
const pax = new PaxClient({
  apiKey: process.env.PAX_API_KEY!,
  apiUrl: process.env.PAX_API_URL
});

app.post('/checkout', async (req, res) => {
  const { orderId, amount, customerEmail } = req.body;

  try {
    const payment = await pax.initiatePayment(
      {
        amount,
        currency: 'INR',
        user_id: customerEmail,
        metadata: { order_id: orderId },
        success_url: `${process.env.BASE_URL}/payment/success`,
        failure_url: `${process.env.BASE_URL}/payment/failure`
      },
      `order_${orderId}` // Idempotency key
    );

    res.json({
      success: true,
      paymentUrl: payment.redirect_url,
      transactionId: payment.transaction_id
    });
  } catch (error) {
    console.error('Payment initiation failed:', error);
    res.status(500).json({
      success: false,
      error: 'Failed to initiate payment'
    });
  }
});

app.get('/payment/success', async (req, res) => {
  const { transaction_id } = req.query;

  const transaction = await pax.getTransaction(transaction_id as string);

  if (transaction.status === 'completed') {
    res.send('Payment successful!');
  } else {
    res.send('Payment pending...');
  }
});

Configuration

Environment Variables

PAX_API_KEY=your_api_key_here
PAX_API_URL=https://api.pax.example.com  # Optional

Gateway Support

PAX supports multiple payment gateways:

• Razorpay
• PayU
• Paytm

Specify a gateway in the payment request or let PAX choose automatically.

License

MIT

Support

For issues and questions:

• GitHub Issues: Report an issue
• Documentation: Full API docs

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.