vietqr-core-sdk

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:

  1. WordPress / WooCommerce: The standard e-commerce platform powering millions of online storefronts.
  2. WHMCS: The leading web hosting automation and billing management system.
  3. HostBill: High-performance enterprise hosting, VPS, and cloud billing software.

1. WordPress / WooCommerce Plugin

Location: plugins/wordpress-woocommerce/

Features

Installation

  1. Copy the plugins/wordpress-woocommerce folder into your WordPress plugins directory:
    cp -r plugins/wordpress-woocommerce /var/www/html/wp-content/plugins/vietqr-woocommerce
    
  2. Navigate to WordPress Admin > Plugins > Installed Plugins.
  3. Locate VietQR Payment Gateway for WooCommerce and click Activate.
  4. Go to WooCommerce > Settings > Payments > VietQR (NAPAS 247) > Manage.
  5. Fill in your Bank BIN (e.g. 970422 for MB), Account Number, Beneficiary Name, and Webhook Secret Key.
  6. Click Save Changes.

2. WHMCS Payment Gateway Module

Location: plugins/whmcs/

Features

Installation

  1. 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/
    
  2. Access WHMCS Admin Area > System Settings > Payment Gateways.
  3. Under the All Payment Gateways tab, click on VietQR.
  4. Set your Bank BIN, Account Number, Account Name, and Webhook Secret.
  5. Save changes.

3. HostBill Payment Module

Location: plugins/hostbill/

Features

Installation

  1. Copy the module directory into HostBill:
    cp -r plugins/hostbill/includes/modules/Payment/vietqr /path/to/hostbill/includes/modules/Payment/
    
  2. In HostBill Admin, go to Settings > Modules > Payment Modules.
  3. Click Activate on VietQR.
  4. Configure Bank BIN, Account Number, Beneficiary Name, and Webhook Secret.
  5. Save settings.

4. Webhook Reconciliation Specification

All three plugins share a unified, secure JSON webhook format for automated reconciliation:

Webhook Request:

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().