Module: Alfa Payment Gateway v1.0.0
What is Alfa Payment Gateway?
Enterprise Bank Alfalah Alfa Payment Gateway integration for Perfex CRM
This module installs into modules/alfapay_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 Alfa Payment Gateway:
- Activate — Setup → Modules → activate Alfa Payment Gateway (run Upgrade if prompted).
- Permissions — Setup → Staff → Roles → enable view/create/edit (and approve/settings if needed) for this module.
- Settings — Open Alfa 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.
Module documentation index
Start here — full guides for Alfa 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 Alfa Payment Gateway permissions.
- Open Alfapay Gateway (sidebar) or search for Alfa 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 Alfa Payment Gateway section in the admin sidebar. Screens your staff may use (depending on role):
- Alfa Payment Gateway
- Alfa Payment History
- Alfa Transactions
- Audit Logs
Detailed guide — features, workflows, API & FAQ
Configuration
- Open Setup → Settings → Payment Gateways → Alfa Payment Gateway.
- Enter Merchant ID, Store ID, Merchant Hash, Username, Password, Hash Key 1, Hash Key 2.
- Enable Testing Mode for sandbox, or Production Mode for live.
- Set currencies (example:
PKR,USD) — invoice currency must match. - Copy the displayed Callback / Return / Success / Failed / IPN URLs into your Bank Alfalah merchant portal.
- Optionally click Test Connection.
- Set the gateway to Active.
Note: The gateway cannot be activated until all required credential fields are filled.
How to Use
Client payment flow
- Create an unpaid invoice in a supported currency.
- Client opens the invoice (public link or client area).
- Clicks Pay via Alfa.
- Confirms amount and continues to the Alfa hosted payment page.
- After payment, customer returns to success / failed / pending page.
- Callback / IPN updates the transaction and records the invoice payment.
Admin workflow
- Dashboard — revenue, success rate, charts
- Transactions — list and open payment records
- Refunds — refund paid transactions (permission required)
- Audit Logs — track gateway actions
- Reports — filter and export
Features
- Bank Alfalah Alfa hosted checkout
- Invoice payments from client portal / invoice HTML
- Test & live modes
- Transactions, refunds, audit logs
- Admin dashboard + Perfex dashboard widget
- Client payment history menu
- PDF receipts
- Reports & export
- Email templates (success / failed / pending / refund / admin)
- Granular staff permissions
- Clean uninstall (tables + options removed)
Permissions
Assign under Setup → Staff → Roles:
| Capability group | Actions |
|---|---|
| Alfa Transactions | View, Manage |
| Alfa Refunds | Manage |
| Alfa Reports | View, Export |
| Alfa Settings | Manage |
Uninstall
- Setup → Modules → Deactivate
- Click Uninstall
Removes all alfapay_* tables, module email templates, and gateway options (alfapay_* / paymentmethod_alfapay_*). Core Perfex CRM files are not changed. Existing core invoice payment history is not bulk-deleted by the module.
After activation — configuration checklist
- Go to Setup → Modules and activate Alfa Payment Gateway.
- If prompted, click Upgrade Database or reload admin — migrations run automatically.
- Assign permissions under Setup → Staff → Roles.
- Open Setup → Settings → Payment Gateways → Alfa Payment Gateway and configure credentials.
- 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
- Bank Alfalah Alfa merchant account (test or live)
One-time setup (first time only)
- Setup → Modules → activate Alfa Payment Gateway.
- Setup → Staff → Roles → assign Alfa Payment Gateway permissions (view, create, edit, delete, approve, export, settings as needed).
- Open Alfa 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 Alfa 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/alfapay_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.