Enterprise E-Commerce & Billing Plugins Guide
The VietQR Core SDK suite provides official, production-ready payment gateway plugins for the world’s most widely used e-commerce and billing platforms:
- WordPress / WooCommerce: The standard e-commerce platform powering millions of online storefronts.
- WHMCS: The leading web hosting automation and billing management system.
- HostBill: High-performance enterprise hosting, VPS, and cloud billing software.
1. WordPress / WooCommerce Plugin
Location: plugins/wordpress-woocommerce/
Features
- Native integration as a WooCommerce Payment Gateway (
WC_Payment_Gateway).
- Dynamic QR code generation matching the exact order total and reference memo
WC{order_id}.
- Real-time AJAX order status polling: automatically redirects customers to the Order Received page once payment is detected.
- Secure HMAC-SHA256 Webhook listener (
/wc-api/wc_gateway_vietqr) for automated instant order status completion.
- Support for all 5 visual templates (
compact2, compact, qr_only, print, payos).
- Direct banking app launch button on mobile devices (Deeplink support).
Installation
- Copy the
plugins/wordpress-woocommerce folder into your WordPress plugins directory:
cp -r plugins/wordpress-woocommerce /var/www/html/wp-content/plugins/vietqr-woocommerce
- Navigate to WordPress Admin > Plugins > Installed Plugins.
- Locate VietQR Payment Gateway for WooCommerce and click Activate.
- Go to WooCommerce > Settings > Payments > VietQR (NAPAS 247) > Manage.
- Fill in your Bank BIN (e.g.
970422 for MB), Account Number, Beneficiary Name, and Webhook Secret Key.
- Click Save Changes.
2. WHMCS Payment Gateway Module
Location: plugins/whmcs/
Features
- Native WHMCS Third-Party Gateway Module implementation (
vietqr_MetaData(), vietqr_config(), vietqr_link()).
- Embeds a clean, responsive payment card directly onto client invoices.
- Automated instant invoice reconciliation via
modules/gateways/callback/vietqr.php.
- Instant provisioning of hosting, VPS, and domain registrations upon payment receipt.
- Support for invoice prefix customization (
INV, WHMCS, etc.).
- HMAC-SHA256 / Shared Secret signature verification.
Installation
- Copy the files to your WHMCS root directory:
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/
- Access WHMCS Admin Area > System Settings > Payment Gateways.
- Under the All Payment Gateways tab, click on VietQR.
- Set your Bank BIN, Account Number, Account Name, and Webhook Secret.
- Save changes.
3. HostBill Payment Module
Location: plugins/hostbill/
Features
- Implements HostBill’s
PaymentModule abstract class.
- Renders an inline invoice payment block with QR code, formatted VND amount, and one-click copy fields.
- Automated invoice marking (
addTransaction) and audit logging (logTransaction).
- Webhook callback endpoint with HMAC-SHA256 verification.
Installation
- Copy the module directory into HostBill:
cp -r plugins/hostbill/includes/modules/Payment/vietqr /path/to/hostbill/includes/modules/Payment/
- In HostBill Admin, go to Settings > Modules > Payment Modules.
- Click Activate on VietQR.
- Configure Bank BIN, Account Number, Beneficiary Name, and Webhook Secret.
- Save settings.
4. Webhook Reconciliation Specification
All three plugins share a unified, secure JSON webhook format for automated reconciliation:
Webhook Request:
- HTTP Method:
POST
- Headers:
Content-Type: application/json
X-VietQR-Signature: <hmac-sha256-hash-of-body>
- Body:
{
"id": "tx_99887766",
"amount": 500000,
"description": "WC1042 thanh toan don hang",
"timestamp": 1746403200
}
Signature Verification Algorithm:
Compute the HMAC-SHA256 signature using the shared secret key:
\(\text{Signature} = \text{HMAC-SHA256}(\text{raw\_body}, \text{secret\_key})\)
Compare in constant time using hash_equals().