Vnpay
An open-source nodejs library support to payment with VNPay (vnpay.vn)
Install / Use
/learn @lehuygiang28/VnpayREADME
📦 vnpayjs
🚀 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
</div>✨ Tính năng nổi bật
<div align="center">| 🎯 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 |
</div>🆕 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
<div align="center">| 📖 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 |
</div>🚀 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,cryptovà 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);
}
<!-- GitAds-Verify: AS4WTM39TY1WOG94V1FIXPB924R4LHF1 -->
🤝 Hỗ trợ & Đóng góp
<div align="center">🎉 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
<br/>
🛠️ Tham gia đóng góp
<div align="center">| 📋 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 |
</div>👥 Contributors
<div align="center">Cảm ơn tất cả những người đã đóng góp cho dự án:
📄 Giấy phép
<div align="center">Made with ❤️ in Vietnam
</div>