# 📦 vnpayjs
[🇻🇳 Tiếng Việt](./README.md) | [🇺🇸 English](./README_en-US.md)
[](https://www.npmjs.com/package/vnpay)
[](https://www.npmjs.com/package/vnpay)
[](https://www.npmjs.com/package/vnpay)
[](https://github.com/lehuygiang28/vnpay)
[](https://github.com/lehuygiang28/vnpay/issues)
[](https://codecov.io/gh/lehuygiang28/vnpay)
**🚀 Thư viện Node.js hiện đại cho tích hợp cổng thanh toán [VNPay](https://vnpay.vn) 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](https://vnpay.js.org/) | Tài liệu chi tiết với ví dụ |
| **VNPay API** | [sandbox.vnpayment.vn/apis](https://sandbox.vnpayment.vn/apis) | Tài liệu chính thức VNPay |
| **GitHub** | [github.com/lehuygiang28/vnpay](https://github.com/lehuygiang28/vnpay) | Source code & Issues |
---
## 🚀 Cài đặt
> [!TIP]
> **NestJS users**: Sử dụng [`nestjs-vnpay`](https://github.com/lehuygiang28/nestjs-vnpay) - wrapper tích hợp sẵn cho NestJS.
```bash
# NPM
npm install vnpay
# Yarn
yarn add vnpay
# PNPM
pnpm install vnpay
```
---
## 📦 Import Options (v2.4.0+)
### 🏆 Import toàn bộ (Backward Compatible)
```typescript
import { VNPay, HashAlgorithm, ProductCode } from 'vnpay';
```
### 🦩 Import theo module (Recommended)
```typescript
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)
```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:**
>
> ```typescript
> import { VNPay } from 'vnpay'; // Error: Module not found: Can't resolve 'fs'
> ```
>
> **✅ SỬ DỤNG như thế này cho frontend:**
>
> ```typescript
> 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**
```typescript
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**
```typescript
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**
```typescript
// 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);
}
```
---
[](https://gitads.dev/v1/ad-track?source=lehuygiang28/vnpay@github)
---
## 🤝 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_
[](https://github.com/lehuygiang28/vnpay)
| 📋 **Bước** | 🔗 **Hành động** |
| :---------: | :------------------------------------------------------------------------------ |
| **1** | Đọc [Hướng dẫn đóng góp](.github/CONTRIBUTING.md) |
| **2** | Fork repo và tạo Pull Request |
| **3** | Tham gia thảo luận trong [Issues](https://github.com/lehuygiang28/vnpay/issues) |
### 👥 **Contributors**
_Cảm ơn tất cả những người đã đóng góp cho dự án:_
[](https://github.com/lehuygiang28/vnpay/graphs/contributors)
---
## 📄 Giấy phép
**[MIT License](LICENSE) © [Lê Huy Giang](https://github.com/lehuygiang28)**
_Made with ❤️ in Vietnam_