Module: HBL Pay Payment Gateway v1.0.0
What is HBL Pay Payment Gateway?
Enterprise HBL Pay payment gateway integration for Perfex CRM
This module installs into modules/hblpay_gateway/ and adds its own admin menus, permissions, and database tables — without editing Perfex CRM core files.
Who should use this module?
- Admins — activate the module, configure Settings, assign roles, and manage integrations.
- Operators / day-to-day staff — create and update records (orders, attendance, shipments, messages, etc.).
- Managers / approvers — review queues, approve workflows, and monitor dashboards/KPIs.
- Finance / compliance / ops leads — run reports, exports, and audit trails when the module supports them.
What you can achieve
- Keep all related work in one place inside Perfex CRM instead of spreadsheets.
- Control who can view, create, edit, approve, or export with role permissions.
- Use dashboards and reports to see status, bottlenecks, and history.
- Connect to other CRM data (customers, invoices, items, staff) where the module integrates.
Recommended learning path
- Read How to Install and activate the module.
- Skim Features so you know what screens exist.
- Complete the Quick Start checklist on this page (Settings → masters → first sample record).
- Open each screen guide under Screen-by-screen guides when you need step-by-step help.
- Check Version & Changelog after upgrades for new options.
Tip: Train one admin first, then create a limited role for operators so they only see the screens they need.
5-minute Quick Start
Follow this short path the first time you use HBL Pay Payment Gateway:
- Activate — Setup → Modules → activate HBL Pay Payment Gateway (run Upgrade if prompted).
- Permissions — Setup → Staff → Roles → enable view/create/edit (and approve/settings if needed) for this module.
- Settings — Open HBL Pay Payment Gateway → Settings and save company defaults, prefixes, and integrations.
- Master data — Create the first required masters (products, warehouses, templates, channels, accounts, routes, etc.).
- First transaction — Create one sample record end-to-end (save → submit/approve → complete) and confirm it appears in lists/reports.
- Cron — If the module uses alerts, sync, queues, or AI, confirm Perfex CRM cron is scheduled on the server.
Full how-to guide (from module package)
The steps below come from the module author's printable guide — follow them in order for best results.
HOW TO USE — HBL Pay Payment Gateway for Perfex CRM
Author: Nasbix Technologies | Version: 1.0.0
═══════════════════════════════════════════════════════
1. INSTALLATION
═══════════════════════════════════════════════════════
- Extract the main ZIP (Main File).
2. Upload the folder "hblpay_gateway" into:
/your-perfex-root/modules/
- Login as admin → Setup → Modules.
- Click Activate on "HBL Pay Payment Gateway".
- Database tables + email templates + options are created automatically.
6. Assign staff permissions: Setup → Staff → Roles
(View HBL Transactions, Manage HBL Settings, Export HBL Reports).
7. Configure gateway:
Setup → Settings → Payment Gateways → HBL Pay
═══════════════════════════════════════════════════════
2. GATEWAY CONFIGURATION (required)
═══════════════════════════════════════════════════════
Enter from your HBL Pay merchant portal:
• Merchant ID
• Store ID
• API Username
• API Password
• Secret Key
• HBL Public Key (RSA PEM) — if required by your HBL setup
• Merchant Private Key (RSA PEM) — if required by your HBL setup
Then:
• Enable Testing Mode for sandbox OR Live Mode for production
• Optional: override Success URL / Failed URL
• Optional: confirm Sandbox / Production API & Portal URLs
• Copy Callback URL, Success URL, Failed URL
into the HBL Pay merchant portal
• Set gateway Active = Yes
Note: The module will not activate until Merchant ID, Store ID,
API credentials, and Secret Key are configured.
═══════════════════════════════════════════════════════
3. HOW CLIENTS PAY
═══════════════════════════════════════════════════════
1. Create / open an unpaid invoice in a supported currency
(PKR, USD, CAD, GBP, AED, EUR — configurable).
- Client opens the invoice (public link or client portal).
- Click "Pay via HBL Pay".
- Confirm amount → Continue to HBL Pay.
- Complete payment on the HBL Pay secure portal.
- Customer returns to success / failed / pending page.
- Callback updates transaction status and records payment.
═══════════════════════════════════════════════════════
4. ADMIN DAILY USE
═══════════════════════════════════════════════════════
• Dashboard widget — totals and quick overview
• Transactions — list / filter payment attempts
• Transaction detail — gateway response + audit logs
• Reports — run and export PDF reports
• Invoice view — client payment history panel
═══════════════════════════════════════════════════════
5. EMAIL NOTIFICATIONS
═══════════════════════════════════════════════════════
Templates created on install (editable in Setup → Email Templates):
• hblpay-payment-success
• hblpay-payment-failed
• hblpay-payment-pending
═══════════════════════════════════════════════════════
6. UNINSTALL (clean removal)
═══════════════════════════════════════════════════════
1. Setup → Modules → Deactivate
2. Click Uninstall
3. Removes:
- All hblpay_* database tables
- Module email templates
- hblpay_* and paymentmethod_hblpay_* options
4. No core Perfex CRM files are modified
═══════════════════════════════════════════════════════
7. DOCUMENTATION
═══════════════════════════════════════════════════════
Open documentation/index.html inside the module package
for a browser-friendly guide.
Module documentation index
Start here — full guides for HBL Pay Payment Gateway:
- Overview & How to Use — what it is, who uses it, daily workflow
- Quick Start Guide — first 5 minutes + printable how-to
- How to Install — upload, activate, permissions, verify
- Features (Full Detail) — every capability explained
- FAQ & Tips — common questions and best practices
- Version & Changelog — version history
How to use in Perfex CRM (daily operations)
- Sign in to the admin area with a role that includes HBL Pay Payment Gateway permissions.
- Open Hblpay Gateway (sidebar) or search for HBL Pay Payment Gateway in the admin menu.
- Start on the Dashboard (if available) to see open tasks, pending approvals, and KPIs.
- Review Settings after upgrades — new options may need defaults for your company.
- Create or import master data first; most modules block transactions until masters exist.
- Run the main business flow (create → submit → approve → post/complete) using the screens listed in Admin menu below.
- Use Reports / Analytics screens to reconcile stock, finance, compliance, or SLA metrics.
- For integrations (API, EDI, gateways, tax), confirm credentials in Settings and monitor logs or webhook delivery screens.
- Train staff with role-based access — give approvers approve permissions only, operators create/edit on their area.
- If something fails overnight, check Perfex CRM cron ran and open the module log / failed queue screen if present.
Admin menu — where to work
Open the HBL Pay Payment Gateway section in the admin sidebar. Screens your staff may use (depending on role):
- HBL Pay
- HBL Pay Transactions
Detailed guide — features, workflows, API & FAQ
How to Use
- Enter Merchant ID, Store ID, API Username, API Password, and Secret Key from your HBL portal.
- Add RSA keys if your HBL setup requires them.
- Enable Testing Mode for sandbox, or Live Mode for production.
- Copy Callback / Success / Failed URLs into the HBL merchant portal.
- Set gateway Active = Yes.
- Client opens an unpaid invoice → clicks Pay via HBL Pay → completes payment on HBL portal.
- Admin monitors payments under Utilities → HBL Pay Transactions and Reports.
Gateway Settings
| Setting | Description |
|---|---|
| Merchant ID | Provided by HBL Pay |
| Store ID | Provided by HBL Pay |
| API Username / Password | API authentication credentials |
| Secret Key | Used for secure request signing |
| HBL Public Key | RSA 4096 PEM (if required) |
| Merchant Private Key | RSA 4096 PEM (if required) |
| Sandbox / Production URLs | API and portal endpoints |
| Currencies | Default: PKR,USD,CAD,GBP,AED,EUR |
Features
- Pay invoice via HBL Pay from the customer invoice portal
- Sandbox and live modes
- Transaction list, detail view, and audit logs
- Reports and PDF export
- Dashboard widget for recent activity
- Email notifications for success, failure, and pending
- Staff capabilities for transactions, settings, and export
- Clean uninstall (tables + options + email templates)
Permissions
Assign under Setup → Staff → Roles:
- View HBL Transactions
- Manage HBL Settings
- Export HBL Reports
Uninstall
- Deactivate the module under Setup → Modules.
- Click Uninstall.
Removes:
- All
{prefix}hblpay_*database tables - HBL Pay email templates
- Module and gateway options (
paymentmethod_hblpay_*)
Core invoice payment records in Perfex are not deleted — only module-specific data.
After activation — configuration checklist
- Go to Setup → Modules and activate HBL Pay Payment Gateway.
- If prompted, click Upgrade Database or reload admin — migrations run automatically.
- Assign permissions under Setup → Staff → Roles.
- Configure under Setup → Settings → Payment Gateways → HBL Pay.
- Perfex CRM 2.3+ (3.x recommended)
- PHP 7.4+ (8.1+ recommended)
- MySQL 5.7+ / MariaDB 10.3+ (InnoDB)
- PHP extensions: mysqli, json, mbstring, curl, openssl
- HBL Pay merchant account (sandbox or live)
One-time setup (first time only)
- Setup → Modules → activate HBL Pay Payment Gateway.
- Setup → Staff → Roles → assign HBL Pay Payment Gateway permissions (view, create, edit, delete, approve, export, settings as needed).
- Open HBL Pay Payment Gateway → Settings and complete company defaults, prefixes, integrations, and notification options.
- Create master data (warehouses, products, templates, accounts, routes, etc.) before processing live transactions.
- Enable Perfex CRM cron (
php /path/to/perfex/index.php cron/index) for sync, retries, alerts, and scheduled jobs. - Optionally enable REST API / webhooks in module settings if you integrate external systems.
Tips for success
- Always configure Settings before creating live transactions.
- Create master data (items, warehouses, templates, channels, accounts) first — most modules block incomplete records.
- Use a test/sample record before going live with real customers or production stock.
- Separate roles: operators create/edit; managers approve; finance/reporting get view/export only.
- After any module upgrade, reopen Settings and confirm new options have sensible defaults.
- If overnight jobs fail, verify Perfex CRM cron and check the module log / failed queue screen.
Common questions (FAQ)
Where do I find the module after activation?
In the admin sidebar look for HBL Pay Payment Gateway. If missing, your role may lack view permission — fix under Setup → Staff → Roles.
Do I need to edit core Perfex CRM files?
No. Keep all custom code under modules/hblpay_gateway/. Activate/deactivate from Setup → Modules.
What happens if I uninstall?
Deactivate keeps data. Uninstall usually removes module tables/options (see the Install article). Core customers, invoices, and items are not deleted by well-built modules.
Why can't my staff see a screen?
Almost always a permissions issue. Give the role at least view on that feature, then ask the user to log out and back in.
Reports/export buttons do nothing
Confirm the role has export (or view reports) permission, and that filters return at least one row. Try PDF/CSV from a wider date range.
Perfex CRM Knowledge Base — detailed usage guide generated from module README, HOW_TO_USE, and documentation.