Hướng Dẫn Cài Đặt Plugins Doanh Nghiệp (WooCommerce, WHMCS, HostBill)
Hệ sinh thái VietQR Core SDK cung cấp sẵn các bộ plugin cổng thanh toán chuẩn doanh nghiệp dành cho các nền tảng thương mại điện tử và tự động hóa hóa đơn hosting phổ biến nhất:
- WordPress / WooCommerce: Nền tảng bán hàng thương mại điện tử số 1 thế giới.
- WHMCS: Hệ thống quản lý và tự động hóa hóa đơn hosting, tên miền hàng đầu.
- HostBill: Nền tảng thanh toán và quản lý hạ tầng Cloud/VPS/Hosting cho doanh nghiệp viễn thông.
1. Plugin WordPress / WooCommerce
Vị trí: plugins/wordpress-woocommerce/
Tính năng
- Tích hợp chuẩn
WC_Payment_Gateway của WooCommerce.
- Tự động sinh mã VietQR động đúng số tiền đơn hàng và nội dung
WC{order_id}.
- Cơ chế kiểm tra trạng thái đơn hàng thời gian thực qua AJAX: tự động chuyển hướng khách hàng sang trang hoàn tất khi giao dịch thành công.
- Webhook lắng nghe biến động số dư bảo mật HMAC-SHA256 (
/wc-api/wc_gateway_vietqr) tự động chuyển đơn sang trạng thái Processing hoặc Completed.
- Hỗ trợ đầy đủ 5 giao diện VietQR:
compact2, compact, qr_only, print, payos.
- Nút bấm mở ứng dụng ngân hàng tức thì trên điện thoại di động (DeepLink).
Hướng dẫn cài đặt
- Sao chép thư mục
plugins/wordpress-woocommerce vào thư mục plugins của WordPress:
cp -r plugins/wordpress-woocommerce /var/www/html/wp-content/plugins/vietqr-woocommerce
- Đăng nhập vào trang Quản trị WordPress > Plugins (Gói mở rộng) > Installed Plugins.
- Tìm VietQR Payment Gateway for WooCommerce và bấm Kích hoạt (Activate).
- Vào WooCommerce > Cài đặt (Settings) > Thanh toán (Payments) > VietQR (NAPAS 247) > Quản lý (Manage).
- Điền mã BIN ngân hàng (ví dụ:
970422 cho MBBank), số tài khoản, tên chủ tài khoản và Secret Key.
- Bấm Lưu thay đổi.
2. Module Thanh Toán WHMCS
Vị trí: plugins/whmcs/
Tính năng
- Tích hợp chuẩn Gateway Module của WHMCS (
vietqr_MetaData(), vietqr_config(), vietqr_link()).
- Hiển thị khung thanh toán trực quan ngay trên hóa đơn khách hàng (Client Invoice).
- Tự động gạch nợ hóa đơn tức thì khi nhận webhook qua
modules/gateways/callback/vietqr.php.
- Tự động kích hoạt hosting, VPS, tên miền ngay khi khách hàng chuyển khoản thành công.
- Tùy chỉnh tiền tố nội dung chuyển khoản (
INV, WHMCS,…).
- Cơ chế xác thực chữ ký HMAC-SHA256 chống giả mạo thanh toán.
Hướng dẫn cài đặt
- Sao chép các tệp vào thư mục cài đặt WHMCS:
cp plugins/whmcs/modules/gateways/vietqr.php /path/to/whmcs/modules/gateways/
cp plugins/whmcs/modules/gateways/callback/vietqr.php /path/to/whmcs/modules/gateways/callback/
- Truy cập WHMCS Admin Area > System Settings > Payment Gateways.
- Tại tab All Payment Gateways, chọn kích hoạt VietQR.
- Điền mã BIN, số tài khoản, tên chủ tài khoản và Webhook Secret Key.
- Bấm Save Changes.
3. Module Thanh Toán HostBill
Vị trí: plugins/hostbill/
Tính năng
- Kế thừa lớp
PaymentModule tiêu chuẩn của HostBill.
- Giao diện thẻ VietQR chuyên nghiệp, hiển thị số tiền VND chính xác và nút sao chép tiện lợi.
- Tự động ghi nhận giao dịch vào hóa đơn (
addTransaction) và lưu lịch sử kiểm toán (logTransaction).
- Cổng tiếp nhận Webhook bảo mật cao với thuật toán HMAC-SHA256.
Hướng dẫn cài đặt
- Sao chép thư mục module vào HostBill:
cp -r plugins/hostbill/includes/modules/Payment/vietqr /path/to/hostbill/includes/modules/Payment/
- Trong trang HostBill Admin, vào Settings > Modules > Payment Modules.
- Bấm Activate tại mục VietQR.
- Cấu hình thông tin ngân hàng thụ hưởng và Webhook Secret.
- Bấm lưu cấu hình.
4. Định Dạng Webhook Đối Soát Tự Động Chung
Cả 3 plugin đều sử dụng chung một định dạng Webhook JSON chuẩn:
Yêu cầu HTTP:
- Phương thức:
POST
- Tiêu đề (Headers):
Content-Type: application/json
X-VietQR-Signature: <mã-băm-hmac-sha256-của-toàn-bộ-body>
- Nội dung mẫu (Body):
{
"id": "tx_20250505_9988",
"amount": 500000,
"description": "WC1042 thanh toan don hang",
"timestamp": 1746403200
}