📦 vnpayjs

🇻🇳 Tiếng Việt | 🇺🇸 English

🚀 Thư viện Node.js hiện đại cho tích hợp cổng thanh toán VNPay vào ứng dụng của bạn.

Hỗ trợ TypeScript • Tree-shaking • Modular imports • Minimal dependencies

✨ Tính năng nổi bật

| 🎯 Dễ sử dụng | 🧩 Modular | 📘 TypeScript | ⚡ Tối ưu | | :----------------------: | :----------------: | :---------------: | :----------------: | | API đơn giản & trực quan | Import theo module | Full type support | Tree-shaking ready |

🆕 Mới trong v2.4.0

• 📦 Import theo module - Giảm kích thước bundle lên đến 80%
• 🎯 Types-only imports - 0KB runtime cho TypeScript projects
• ⚡ Tối ưu build - Code splitting và tree-shaking
• 🔧 Flexible endpoints - Custom API endpoints

📚 Tài liệu

| 📖 Tài liệu | 🔗 Link | 📝 Mô tả | | :------------------ | :--------------------------------------------------------------------- | :-------------------------- | | Docs chính thức | vnpay.js.org | Tài liệu chi tiết với ví dụ | | VNPay API | sandbox.vnpayment.vn/apis | Tài liệu chính thức VNPay | | GitHub | github.com/lehuygiang28/vnpay | Source code & Issues |

🚀 Cài đặt

[!TIP] NestJS users: Sử dụng nestjs-vnpay - wrapper tích hợp sẵn cho NestJS.

# NPM
npm install vnpay

# Yarn
yarn add vnpay

# PNPM
pnpm install vnpay

📦 Import Options (v2.4.0+)

🏆 Import toàn bộ (Backward Compatible)

import { VNPay, HashAlgorithm, ProductCode } from 'vnpay';

🦩 Import theo module (Recommended)

import { VNPay } from 'vnpay/vnpay';
import { HashAlgorithm, ProductCode } from 'vnpay/enums';
import { VNP_VERSION, PAYMENT_ENDPOINT } from 'vnpay/constants';
import { resolveUrlString, dateFormat } from 'vnpay/utils';

📘 Types-only (TypeScript)

import type { VNPayConfig, BuildPaymentUrl, Bank } from 'vnpay/types-only';

[!WARNING] ⚠️ QUAN TRỌNG: Sử dụng trên Client-side (Frontend)

Thư viện VNPay chỉ dành cho Node.js backend vì sử dụng các module như fs, crypto và các API chỉ có trên server.

❌ KHÔNG làm thế này trong React/Vue/Angular components:

import { VNPay } from 'vnpay'; // Error: Module not found: Can't resolve 'fs'

✅ SỬ DỤNG như thế này cho frontend:

import type { VNPayConfig, BuildPaymentUrl, Bank, VerifyReturnUrl } from 'vnpay/types-only';

• Backend (Node.js): Sử dụng import bình thường để xử lý thanh toán
• Frontend (React/Vue/Angular): Chỉ import types để type checking
• API calls: Gọi backend APIs từ frontend thay vì import trực tiếp

💡 Cách sử dụng

🔧 Khởi tạo VNPay

import { VNPay, ignoreLogger } from 'vnpay';

const vnpay = new VNPay({
    // ⚡ Cấu hình bắt buộc
    tmnCode: '2QXUI4B4',
    secureSecret: 'your-secret-key',
    vnpayHost: 'https://sandbox.vnpayment.vn',

    // 🔧 Cấu hình tùy chọn
    testMode: true, // Chế độ test
    hashAlgorithm: 'SHA512', // Thuật toán mã hóa
    enableLog: true, // Bật/tắt log
    loggerFn: ignoreLogger, // Custom logger

    // 🔧 Custom endpoints
    endpoints: {
        paymentEndpoint: 'paymentv2/vpcpay.html',
        queryDrRefundEndpoint: 'merchant_webapi/api/transaction',
        getBankListEndpoint: 'qrpayauth/api/merchant/get_bank_list',
    },
});

💳 Tạo URL thanh toán

const paymentUrl = vnpay.buildPaymentUrl({
    vnp_Amount: 100000, // 100,000 VND
    vnp_IpAddr: '192.168.1.1',
    vnp_ReturnUrl: 'https://yourapp.com/return',
    vnp_TxnRef: 'ORDER_123',
    vnp_OrderInfo: 'Thanh toán đơn hàng #123',
});

console.log('Payment URL:', paymentUrl);

✅ Xác thực thanh toán

// Xác thực URL return
const verify = vnpay.verifyReturnUrl(req.query);
if (verify.isSuccess) {
    console.log('✅ Thanh toán thành công!', verify.message);
} else {
    console.log('❌ Thanh toán thất bại:', verify.message);
}

🤝 Hỗ trợ & Đóng góp

🎉 vnpayjs là dự án mã nguồn mở và hoàn toàn miễn phí!

Nếu thư viện giúp ích cho bạn, hãy tặng cho project này một ⭐ hoặc mời một ly cà phê ☕ và nhấn vào các quảng cáo trên để mình nhận được 1 khoản tiền nhỏ để duy trì project

🛠️ Tham gia đóng góp

| 📋 Bước | 🔗 Hành động | | :---------: | :------------------------------------------------------------------------------ | | 1 | Đọc Hướng dẫn đóng góp | | 2 | Fork repo và tạo Pull Request | | 3 | Tham gia thảo luận trong Issues |

👥 Contributors

Cảm ơn tất cả những người đã đóng góp cho dự án:

📄 Giấy phép

MIT License © Lê Huy Giang

Made with ❤️ in Vietnam