PayNotify Node.js SDK

The official Node.js Server SDK for PayNotify — the zero-MDR, automated, lifetime-free UPI payment gateway engine.

Designed for enterprise reliability, this SDK provides seamless integration with the PayNotify architecture, enabling Dynamic Cent Masking for payment concurrency management and Cryptographic HMAC-SHA256 Webhook Verification using stable string formatting to guarantee bank-grade security against replay and JSON mutation attacks.

✨ Features

Dynamic Cent Masking (Penny Drop)

Automatically resolves payment concurrency (for example, multiple users checking out with ₹49 simultaneously) by generating unique fractional amounts through an atomic database lock.

Cryptographic Webhook Security (Stable String)

Built-in Express middleware validates X-PayNotify-Signature using HMAC-SHA256. It securely signs a fixed string template:

orderId:amount:status:timestamp

This completely prevents JSON parsing drift vulnerabilities and replay attacks.

Client-Side Idempotency

Automatically handles network retries by generating and sending deterministic idempotency keys, preventing duplicate or orphaned orders.

Bi-Directional Reconciliation

Supports Just-In-Time (JIT) verification for fast-paying customers and improved payment confirmation reliability.

First-Class TypeScript Support

Fully typed APIs for excellent developer experience, editor autocomplete, and static analysis.

Installation

Using npm:

npm install paynotify-node

Using Yarn:

yarn add paynotify-node

Using pnpm:

pnpm add paynotify-node

Quick Start

Initialization

Initialize the PayNotify client using your secret API key.

Security Warning: Never expose your API key in frontend or client-side code.

import { PayNotify } from 'paynotify-node';

const paynotify = new PayNotify({
  apiKey: process.env.PAYNOTIFY_API_KEY || 'your-secure-api-key'
});

Creating a Payment Order

When a user initiates checkout, create an order on your backend. The SDK communicates with the PayNotify Engine to lock in a concurrency-safe amount.

app.post('/api/checkout', async (req, res) => {
  try {
    const { baseAmount, userName } = req.body;

    const orderData = await paynotify.createOrder({
      baseAmount,
      customerName: userName,
      // ⚠️ IMPORTANT: You must provide a stable idempotencyKey (e.g., your DB cart ID or session UUID).
      // This prevents duplicate orders and double-charging if a network timeout causes a retry.
      idempotencyKey: 'unique-transaction-id-123'
    });

    // Save orderId and assigned amount in your database.
    res.json(orderData);

  } catch (error) {
    console.error(
      'PayNotify Checkout Error:',
      error.message
    );

    res.status(503).json({
      error:
        'Payment Gateway is warming up. Please try again.'
    });
  }
});

Securing Webhooks (Express Middleware)

PayNotify sends real-time webhooks whenever a payment is verified. Every incoming request must be authenticated before processing.

The SDK provides plug-and-play middleware that automatically verifies the X-PayNotify-Signature header using HMAC-SHA256 against a stable string payload.

Invalid signatures are immediately rejected with 401 Unauthorized.

import express from 'express';

const app = express();

app.use(express.json());

app.post(
  '/api/webhook',
  paynotify.verifyWebhook(),
  async (req, res) => {
    const {
      orderId,
      amount,
      status,
      sender_name,
      sender_upi,
      timestamp
    } = req.paynotify;

    if (status === 'VERIFIED') {
      console.log(
        `Payment of ${amount} received from ${sender_name}`
      );

      return res.status(200).json({
        success: true,
        message: 'Order processed successfully.'
      });
    }

    return res.status(200).json({
      message: 'Ignored.'
    });
  }
);

API Reference

new PayNotify(options)

Creates a new PayNotify client instance.

Options

| Property | Type | Required | Description | | -------- | -------- | -------- | ----------------------------- | | apiKey | string | ✅ | Your secret PayNotify API key |

createOrder(payload)

Creates a new payment order atomically.

Request Payload

| Property | Type | Required | Description | | ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------- | | baseAmount | number | ✅ | Original payment amount | | customerName | string | ❌ | Customer name shown in dashboards | | idempotencyKey | string | ✅ | Prevents duplicate orders during retries. Must be a unique string per transaction. |

Response

{
  success: boolean;
  orderId: string;
  amount: number;
  status: string;
}

verifyWebhook()

Returns Express middleware that validates webhook signatures using the following stable string format:

orderId:amount:status:timestamp

The middleware automatically:

• Verifies X-PayNotify-Signature
• Rejects invalid requests with 401 Unauthorized
• Attaches validated payload data to req.paynotify

Security Best Practices

• Never expose API keys in frontend applications.
• Always verify webhook signatures using the provided middleware.
• Store orderId and assigned payment amounts in your database.
• Process only payments with status VERIFIED.
• Use HTTPS in all production environments.
• Implement proper logging and reconciliation workflows.
• Rotate API credentials periodically.

TypeScript Support

The SDK ships with built-in TypeScript definitions.

import { PayNotify } from 'paynotify-node';

const client = new PayNotify({
  apiKey: process.env.PAYNOTIFY_API_KEY!
});

No additional typings are required.

License

MIT License.

Copyright (c) PayNotify.