MhPay Documentation

Overview

MhPay lets you create payment requests, accept payments through active gateways, monitor transactions and verify supported MFS payment SMS with the MH Pay Verifier Android app.

Install & license Panel sections Create a bank gateway Domains & brands Android verifier Modules API integration Troubleshooting

Use HTTPS for the panel and integrations. Keep admin credentials, API keys and Android device tokens private.

Installation and Modern License

Upload the MhPay files to the intended domain and create an empty MySQL database.
Open https://your-domain/install/ and confirm PHP 7.4–8.3, cURL, MySQLi, GD, Fileinfo, Imagick and ZipArchive are available.
Enter database host, port, name, table prefix, username and password; then create the administrator account.
Enter the Modern License key issued for MhPay. The panel verifies the key against the license server and binds it to the installation identity.
Log in at https://your-domain/admin/, configure the panel, then remove or protect the install directory.

Upgrade note: version 2.0.7 uses Modern Licensing Manager. A legacy WHMCS license record is not accepted after this upgrade. The administrator will be asked to enter a newly issued Modern License key.

License verification behaviour

Only an Active signed response is accepted.
The response signature, current date and domain are validated locally.
A valid response is cached briefly to reduce license-server requests.
If the license is invalid, the admin panel shows a key-entry screen. Do not edit the local license file manually.

Using the panel

Dashboard

Shows payment totals, status breakdown and latest transactions. Use it to quickly identify pending or failed payments.

Transaction

Lists all payment attempts. Filter by status and brand, open a transaction to inspect its customer, gateway, sender, verification ID and timeline.

Customers

Stores payment customers and their payment history.

Invoices

Create invoices, choose a due amount and share the invoice checkout URL.

Payment Links

Create shareable fixed-amount payment links. Each link creates a checkout request when the customer selects Pay.

SMS Data

Displays recognised MFS messages, their account type, SIM slot, transaction ID, amount and verification state.

Transaction states

State	Meaning
Pending	The customer submitted payment details, but MhPay has not yet verified the matching payment.
Completed	The payment is verified and can trigger redirect/webhook actions.
Failed / Refunded	The payment was unsuccessful or was refunded.

Gateways

The left menu Gateways opens installed payment gateways. A gateway can be activated or deactivated from its card. Only active gateways are available at checkout and for brand assignment.

Create Bank Gateway

Select Gateways → Add New, then choose Create Bank Gateway for a bank not included in the installed list. The new gateway is managed alongside the other gateways.

Section	Required data
Information	Gateway Name, Display Name, min/max amount, fixed and percentage charge/discount, currency and Active/Inactive status.
Assets	Optional PNG, JPG, GIF or WEBP logo (maximum 2 MB).
Colors	Primary, text, button and button-text colors.
Configuration	Bank name, account holder, account number, branch, routing number and SWIFT/BIC code.

Set the correct min/max amount and charge fields before activating a bank gateway. Update the account details if the receiving account changes.

Domain and Brand

One MhPay installation can serve multiple approved domains. A Domain represents the allowed integration domain; a Brand controls the customer-facing identity for that domain.

Open Domain and add the exact domain used by your website or integration.
Open Brand, select the domain, then enter brand name, logo and colors.
Select the active gateways that this brand may use, then save. MhPay generates a separate Brand API key.
Use that Brand API key in the corresponding WHMCS, WordPress, custom PHP or other server-side integration.

Brand appearance

Brand logo, primary color, text color, button color and button text color apply to branded checkout.

Brand reporting

Transactions retain brand and source-domain data. The Transaction page can filter records by brand.

Brand API key

Open System Settings → API Settings to copy a key. Regenerating it immediately stops integrations using the old key.

A Brand API key must be sent from its allowed domain. Provide domain in the request body or send X-Brand-Domain; a mismatched domain is rejected.

MH Pay Verifier Android app and SMS Data

The Android verifier reads only recognised incoming payment transaction messages for supported bKash, Nagad and Rocket Personal, Merchant and Agent accounts. It sends recognised transaction data to the connected MhPay panel over HTTPS.

Connect a device

In the panel, open SMS Data → Connected Devices and create or copy the device connection details.
Install the current MH Pay Verifier app and open it.
Enter the panel URL and the one-time/device credential supplied by the panel.
Read the in-app disclosure, accept the privacy policy, then grant SMS permission when Android displays its system dialog.
Enable Automatic verification and keep the device connected to the correct SIM/account.

Automatic verification

Situation	Result
Recognised SMS reaches the panel and the Auto Verify Pending Payment module is active	MhPay matches transaction ID, amount, gateway, account type and sender number. The payment becomes Completed immediately.
Mobile/app has no internet	The payment remains Pending; the app queues the recognised message for delivery.
Internet returns	The queued SMS is uploaded and the pending-payment module retries the match. A matched SMS is marked `Used`.
SMS is unrelated or an OTP	It is not used for payment verification.

For successful auto verification, activate the matching payment gateway, connect the correct mobile number, and keep the Auto Verify Pending Payment module active.

Modules

Open Modules from the left menu to review installed modules and activate or deactivate each one. The current module set is:

Admin App Push Notification

Sends panel events to the MhPay payment panel app.

Auto Update

Checks and applies supported panel updates.

Auto Verify Pending Payment

Matches approved, delayed MFS SMS data to pending payments.

SMS Notification

Sends SMS alerts for invoice and payment events.

SMTP Mailer Pro

Delivers email through an authenticated SMTP server.

Telegram Bot Notification

Delivers transaction alerts through a Telegram bot.

Two-factor authentication

Adds a second sign-in verification step for account security.

Webhook Manager

Posts transaction and event data to configured HTTP/HTTPS endpoints.

API integration

Open System Settings → API Settings to copy the global API key or a Brand API key. Make requests from your server only; do not expose a key in browser JavaScript, a mobile app or a public repository.

Endpoints and authentication

Endpoint	Method	Purpose
`https://your-panel-domain/api/create-charge`	POST	Create a hosted payment request.
`https://your-panel-domain/api/verify-payments`	POST	Retrieve the current state of a payment by `pp_id`.
`https://your-panel-domain/api/brand-config`	GET	With a Brand API key, returns brand appearance and active gateway information.

Content-Type: application/json mh-mhpay-api-key: YOUR_API_KEY X-Brand-Domain: shop.example.com # required for a Brand API key unless domain is in JSON

Create a payment

All of the following are required: full_name, email_mobile, amount, metadata, redirect_url, cancel_url, webhook_url, return_type and currency. Redirect and cancel URLs must be valid HTTP or HTTPS URLs. Set webhook_url to -- only when webhook delivery is intentionally disabled.

curl -X POST "https://your-panel-domain/api/create-charge" \\ -H "Content-Type: application/json" \\ -H "mh-mhpay-api-key: YOUR_API_KEY" \\ -d '{ "full_name":"Customer Name", "email_mobile":"customer@example.com", "amount":100, "currency":"BDT", "metadata":{"order_id":"ORDER-1001"}, "redirect_url":"https://merchant.example/payment/success", "cancel_url":"https://merchant.example/payment/cancel", "webhook_url":"https://merchant.example/webhooks/mhpay", "return_type":"json", "product_name":"Example order" }'

A successful response returns status, pp_id and pp_url. Redirect the customer to pp_url. For a brand request, include domain in the JSON body or use X-Brand-Domain.

Verify a payment

curl -X POST "https://your-panel-domain/api/verify-payments" \\ -H "Content-Type: application/json" \\ -H "mh-mhpay-api-key: YOUR_API_KEY" \\ -d '{"pp_id":"PAYMENT_ID_FROM_CREATE_CHARGE"}'

The response includes customer data, payment method, amount, sender number, transaction ID, status, metadata, source domain and brand information when applicable.

HTTP responses

Code	Meaning
200	Request completed.
401	API key is missing or invalid.
403	Brand key does not match the requested domain or transaction.
404	Unknown endpoint or payment.
409	The payment has not yet been submitted by the customer.
422	Required field, amount, currency or URL validation failed.

Troubleshooting and security

“redirect_url must be a valid HTTP or HTTPS URL”

Use a complete URL including https://, for example https://merchant.example/complete. Do not send an empty value, a relative path or a non-web scheme.

SMS Data is Approved but Transaction is Pending

Confirm the transaction ID, amount, mobile sender, gateway and Personal/Merchant/Agent type match. Ensure the payment is still pending, the device has uploaded the SMS, and the Auto Verify Pending Payment module is active. A successfully matched row changes from Approved to Used.

Brand API request is rejected

Use the API key from the same Brand, activate both the domain and brand, and send the exact approved domain in domain or X-Brand-Domain.

Recommended operations

Back up the database and uploaded media before applying an update.
Use a valid SSL certificate and restrict admin access.
Keep API keys, license keys and device credentials private.
Test a payment link and a low-value transaction after gateway or brand changes.
Configure the Cron Job shown in System Settings so delayed jobs and modules can run.

Modules and Plugins Download

Download the official MhPay integration package for your platform. Configure the panel URL and API key after installation.

WHMCS Module

Accept MhPay payments from WHMCS invoices and receive payment status through the included callback module.

↓ Download WHMCS Module

WordPress Plugin

Add MhPay as a WooCommerce payment method, including classic checkout and WooCommerce Blocks support.

↓ Download WordPress Plugin

SMM Panel Module

Connect MhPay with a supported Smart/SMM panel using the included controller, admin integration and installation guide.

↓ Download SMM Module

Need a Custom Module?

Contact MH IT for a custom MhPay integration for your website, billing panel, mobile app or other platform.

Contact for Custom Module

For security, download modules only from these official buttons. Keep your API key out of client-side code and public repositories.