CashPay Node.js SDK

Official Node.js SDK for integrating with CashPay Payment Gateway.

Installation

npm install @cashpayyy/sdk
# or
yarn add @cashpayyy/sdk

Quick Start

import CashPay from '@cashpayyy/sdk';

const cashpay = new CashPay({
  apiKey: 'cpk_live_xxx',
  apiSecret: 'cps_live_xxx',
  environment: 'production' // or 'sandbox'
});

Usage Examples

Check Balance

// Get unified balance
const balance = await cashpay.balance.get();
console.log(`Total Balance: ₹${balance.totalBalance / 100}`);

// Get settlement balance
const settlement = await cashpay.balance.getSettlement();
console.log(`Available for withdrawal: ₹${settlement.availableWithdrawalAmount / 100}`);

// Get payout balance
const payout = await cashpay.balance.getPayout();
console.log(`Payout Balance: ₹${payout.payoutBalance / 100}`);

Payins (Check Payment Status)

// Get payin by order ID
const payin = await cashpay.payins.getByOrderId('ORDER_12345');
console.log(`Status: ${payin.status}, UTR: ${payin.utr}`);

// Get payin status by payment ID
const status = await cashpay.payins.getStatus('payment-uuid');

// Create an Intent Payment (Minimal)
const minimalIntent = await cashpay.payins.createIntent({
  amount: 1000, 
  orderId: 'ORDER_12345'
});

// Create an Intent Payment (Full)
const intent = await cashpay.payins.createIntent({
  amount: 5000,
  orderId: 'ORDER_67890',
  customerName: 'John Doe',
  customerPhone: '9999999999',
  customerEmail: '[email protected]',
  returnUrl: 'https://yoursite.com/payment/result'
});
console.log(`Intent URL: ${intent.intentUrl}`);

// Create a Hosted Payment Page (Direct Redirect Flow)
const page = await cashpay.payins.createPaymentPage({
  amount: 10000, // ₹100.00
  orderId: 'ORDER_54321', // Your custom order ID
  customerName: 'John Doe',
  customerEmail: '[email protected]',
  customerPhone: '9999999999',
  description: 'Purchase of premium subscription',
  returnUrl: 'https://yoursite.com/payment/result' 
});
console.log(`Hosted Checkout URL: ${page.paymentUrl}`);

// Create a Card Payment
const card = await cashpay.payins.createCard({
  amount: 5000,
  orderId: 'ORDER_444',
  cardNumber: '4111222233334444',
  cvv: '123',
  expiryMonth: '12',
  expiryYear: '2026',
  cardHolderName: 'John Doe',
  customerPhone: '9999999999'
});

// Create a NetBanking Payment
const netbanking = await cashpay.payins.createNetBanking({
  amount: 2500,
  orderId: 'ORDER_555',
  bankCode: 'HDFC',
  customerPhone: '9999999999',
  returnUrl: 'https://yoursite.com/done'
});

// Create a UPI Collect Payment
const upiCollect = await cashpay.payins.createUpiCollect({
  amount: 1500,
  orderId: 'ORDER_666',
  vpa: 'john@upi'
});

// Create a Wallet Payment
const wallet = await cashpay.payins.createWallet({
  amount: 800,
  orderId: 'ORDER_777',
  walletProvider: 'PAYTM',
  customerPhone: '9999999999'
});

Payouts

// Create a payout
const payout = await cashpay.payouts.create({
  beneficiaryId: 'ben_xxx',
  amount: 10000, // ₹100 in paise
  referenceId: 'PAY-001',
  narration: 'Salary payment',
  mode: 'IMPS'
}, 'unique-idempotency-key');

console.log(`Payout ID: ${payout.id}, Status: ${payout.status}`);

// Create bulk payouts (max 100)
const bulkResult = await cashpay.payouts.createBulk([
  { beneficiaryId: 'ben_1', amount: 10000, referenceId: 'PAY-001' },
  { beneficiaryId: 'ben_2', amount: 20000, referenceId: 'PAY-002' },
], 'bulk-idempotency-key');

console.log(`Success: ${bulkResult.successCount}, Failed: ${bulkResult.failureCount}`);

// List payouts
const payouts = await cashpay.payouts.list({ page: 1, limit: 20, status: 'COMPLETED' });

// Get payout by ID
const payoutDetails = await cashpay.payouts.get('payout-uuid');

// Get payout by reference ID
const payoutByRef = await cashpay.payouts.getByReferenceId('PAY-001');

// Cancel payout
const cancelled = await cashpay.payouts.cancel('payout-uuid');

Settlements

// Create settlement with saved bank account
const settlement = await cashpay.settlements.create({
  amount: 100000, // ₹1000 in paise
  bankAccountId: 'bank_xxx',
  referenceId: 'SET-001'
}, 'unique-idempotency-key');

// Create settlement with direct bank details
const directSettlement = await cashpay.settlements.create({
  amount: 100000,
  accountNumber: '50100123456789',
  ifsc: 'HDFC0001234',
  accountHolderName: 'John Doe',
  referenceId: 'SET-002'
});

// Create bulk settlements
const bulkSettlements = await cashpay.settlements.createBulk([
  { amount: 50000, bankAccountId: 'bank_1', referenceId: 'SET-001' },
  { amount: 75000, bankAccountId: 'bank_2', referenceId: 'SET-002' },
]);

// List settlements
const settlements = await cashpay.settlements.list({ status: 'COMPLETED' });

// Get settlement by ID
const settlementDetails = await cashpay.settlements.get('settlement-uuid');

// Cancel settlement
const cancelledSettlement = await cashpay.settlements.cancel('settlement-uuid');

Payment Links

// Create a payment link
const link = await cashpay.paymentLinks.create({
  amount: 50000, // ₹500
  description: 'Invoice #001',
  customerName: 'John Doe',
  customerPhone: '9876543210',
  type: 'one-time', // or 'reusable'
  outputType: 'link', // 'link' or 'qr'
});
console.log(`Payment Link: ${link.shortUrl}`);

// List payment links
const links = await cashpay.paymentLinks.list({ page: 1, limit: 10, status: 'active' });

// Get link details
const linkDetails = await cashpay.paymentLinks.get('link-uuid');

// Deactivate link
const inactiveLink = await cashpay.paymentLinks.deactivate('link-uuid');

// Download QR Code buffer
const qrBuffer = await cashpay.paymentLinks.downloadQr('link-uuid', 500); // 500px size

// List Available Gateways
const { gateways } = await cashpay.paymentLinks.getGateways();

Beneficiaries

// Create a beneficiary
const beneficiary = await cashpay.beneficiaries.create({
  name: 'John Doe',
  email: '[email protected]',
  phone: '9999999999'
});

// List beneficiaries
const beneficiaries = await cashpay.beneficiaries.list({ page: 1, limit: 10 });

// Get beneficiary by ID
const benDetails = await cashpay.beneficiaries.get('ben_xxx');

// Update beneficiary
const updatedBen = await cashpay.beneficiaries.update('ben_xxx', {
  name: 'John Smith'
});

// Delete beneficiary
await cashpay.beneficiaries.delete('ben_xxx');

Bank Accounts

// Add a bank account to a beneficiary
const account = await cashpay.bankAccounts.create({
  beneficiaryId: 'ben_xxx',
  accountNumber: '50100123456789',
  ifsc: 'HDFC0001234',
  accountHolderName: 'John Doe'
});

// List bank accounts
const accounts = await cashpay.bankAccounts.list();

// Get bank account by ID
const accountDetails = await cashpay.bankAccounts.get('bank_xxx');

// Delete bank account
await cashpay.bankAccounts.delete('bank_xxx');

Webhook Verification

import express from 'express';

const app = express();

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const payload = req.body.toString();
  
  const isValid = cashpay.verifyWebhook(payload, signature, 'your-webhook-secret');
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  switch (event.type) {
    case 'payin.completed':
      console.log('Payment completed:', event.data);
      break;
    case 'payout.completed':
      console.log('Payout completed:', event.data);
      break;
    case 'settlement.completed':
      console.log('Settlement completed:', event.data);
      break;
  }
  
  res.status(200).send('OK');
});

Error Handling

import CashPay, { CashPayError } from '@cashpayyy/sdk';

try {
  const payout = await cashpay.payouts.create({
    beneficiaryId: 'invalid-id',
    amount: 10000
  });
} catch (error) {
  if (error instanceof CashPayError) {
    console.error(`Error: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);
    console.error(`Code: ${error.code}`);
    console.error(`Details:`, error.details);
  }
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your API key (cpk_live_xxx or cpk_test_xxx) | | apiSecret | string | required | Your API secret | | environment | 'sandbox' | 'production' | 'production' | API environment | | baseUrl | string | auto | Custom API base URL | | timeout | number | 30000 | Request timeout in ms |

TypeScript Support

This SDK is written in TypeScript and includes full type definitions.

import CashPay, { 
  Payout, 
  Settlement, 
  Balance,
  CreatePayoutParams,
  CashPayError 
} from '@cashpayyy/sdk';

Support

• Documentation: https://docs.cashpay.com
• Email: [email protected]
• GitHub Issues: https://github.com/cashpayyy/cashpay-node-sdk/issues