vnpay Node.js Library

The vnpay library is strictly for Node.js backend environments. It cannot be used directly in frontend frameworks (React, Vue, Angular) because it relies on Node.js-specific modules like fs, crypto, and path, and contains sensitive logic for secureSecret.

Recommended Architecture

To use VNPay correctly, you must implement a client-server pattern:

1. Frontend: Handles UI and user interaction. It should only import types from the library. It communicates with your backend via API calls.
2. Backend: A Node.js server that hosts the vnpay library. It handles payment URL generation, transaction verification, and IPN (Instant Payment Notification) processing.

Data Flow:

• Frontend $\rightarrow$ API Call $\rightarrow$ Backend (Generates Payment URL)
• Backend $\rightarrow$ JSON Response $\rightarrow$ Frontend (Redirects user to VNPay)
• VNPay $\rightarrow$ IPN Webhook $\rightarrow$ Backend (Updates database)

⚠️ IMPORTANT: Backend Only

The vnpay library is designed exclusively for Node.js backends. It uses Node.js modules like fs, crypto, and path, which are not available in browsers. Do not import the main vnpay package into frontend code (React, Vue, Angular, etc.), as it will cause build errors.

How to use in Frontend

To maintain type safety in your frontend without breaking the build:

1. Only import types: Use import type from vnpay/types-only or the main package.
2. Call Backend APIs: Instead of running VNPay logic in the browser, call your own backend API to handle payment creation and redirection.

// ✅ CORRECT: Only import types for type checking
import type {
  VNPayConfig,
  BuildPaymentUrl,
  Bank,
  VerifyReturnUrl
} from 'vnpay/types-only';

// ✅ CORRECT: Call your backend API to get the payment URL
const handleCreatePayment = async () => {
  const response = await fetch('/api/create-payment', {
    method: 'POST',
    body: JSON.stringify({ amount: 100000 }),
    headers: { 'Content-Type': 'application/json' }
  });

  const { paymentUrl } = await response.json();
  window.location.href = paymentUrl;
};

Use the generateQr method to request a QR code from VNPay. This method sends a signed GET request to the VNPay payment gateway with vnp_Command = genqr.

Key behaviors:

• Amount Handling: Unlike the raw VNPay specification which requires the amount to be multiplied by 100, this library accepts the "normal" amount (e.g., 10000) and automatically handles the multiplication for you.
• Environment: This must be executed on a Server (requires secureSecret) in a Node.js environment that supports fetch (Node 18+).
• Response: Returns a JSON object containing a status code, a message, and the qrcontent string used to render the QR code or initiate a deep-link.

Important Note: For specific field lengths, error codes, and merchant conditions, always refer to the official "Merchant hosted QR" documentation provided by VNPay.

import { ProductCode, VnpLocale, dateFormat } from 'vnpay';

const start = new Date();
const end = new Date(start.getTime() + 15 * 60 * 1000); // expires after 15 minutes

const result = await vnpay.generateQr({
    vnp_Amount: 10000,
    vnp_IpAddr: '192.168.1.1',
    vnp_TxnRef: 'ORD-123456',
    vnp_OrderInfo: 'Thanh toan don hang ORD-123456',
    vnp_OrderType: ProductCode.Other,
    vnp_ReturnUrl: 'https://merchant.example.com/return',
    vnp_Locale: VnpLocale.VN,
    vnp_CreateDate: dateFormat(start),
    vnp_ExpireDate: dateFormat(end),
});

if (result.code === '00' && result.qrcontent) {
    // Use result.qrcontent to draw the QR code or use as a deep-link
} else {
    // Handle error: result.qrcontent is typically empty when code is not '00'
}

You can provide a logger object in the options argument of buildPaymentUrl to track the generation process.

• Use type: 'all' to log everything.
• Use type: 'pick' with a fields array to log only specific keys.
• Use type: 'omit' to log everything except specific keys.
• Provide a custom loggerFn to direct logs to your own systems (e.g., a database or external logging service).

import { ProductCode, VnpLocale } from 'vnpay';

const paymentUrl = vnpay.buildPaymentUrl(
    {
        vnp_Amount: 10000,
        vnp_IpAddr: '1.1.1.1',
        vnp_TxnRef: '123456',
        vnp_OrderInfo: 'Thanh toan don hang 123456',
        vnp_OrderType: ProductCode.Other,
        vnp_ReturnUrl: returnUrl,
    },
    {
        logger: {
            type: 'pick', // Modes: 'pick', 'omit', or 'all'
            fields: ['createdAt', 'method', 'paymentUrl'],
            loggerFn: (data) => logToDatabase(data), // Implement your own logging logic
        },
    },
);