📦 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 chúng tôi một ⭐ và mời một ly cà phê ☕

🛠️ 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