Knowledgebase

MPGS for WHMCS — Troubleshooting & Error Codes (Customer Guide)

This guide is for customers who have purchased the Snowtech MPGS Gateway for WHMCS and are installing it on their own WHMCS instance.

Before You Start

• WHMCS version: Ensure you are running a supported WHMCS + PHP version for your build.
• Correct environment: Make sure you have the correct host and credentials for Sandbox vs Live.
• Know the payment type:
  • Customer-initiated payment (client pays invoice manually) — CVV is entered on-screen.
  • Merchant-initiated / recurring payment (WHMCS auto-charge / admin captures using stored card) — no CVV is stored (PCI requirement).

Where to Check Logs in WHMCS

• Gateway Log: Utilities → Logs → Gateway Log
• Activity Log: Utilities → Logs → Activity Log

Enable Debug Logging (Temporary)

If you need deeper detail:

1. Go to Configuration → System Settings → Payment Gateways
2. Select MPGS
3. Enable Debug Logging
4. Reproduce the issue once
5. Disable Debug Logging again

Important: Debug logs are sanitized (masked) but should still be treated as sensitive.

Most Common Issues & Fixes

1) “Card security code (CVV) is required.”

What it means: MPGS is requiring a CVV for the transaction.

When this usually happens:

• You attempt to pay an invoice using a stored card (client profile card on file), or
• WHMCS automation (cron) attempts an auto-charge

Why: WHMCS (and all compliant systems) does not store CVV. If your MPGS merchant configuration requires CVV for card-not-present transactions, stored-card/recurring payments will fail.

Fix (what you need to ask your bank / MPGS provider for):

• Enable recurring / card-on-file payments
• Enable Merchant Initiated Transactions (MIT) (sometimes called “Card on File - Merchant Initiated”)
• Enable tokenisation for recurring billing (recommended)

Best practice: If you need reliable auto-charging, use MPGS features designed for recurring billing (tokenisation / card-on-file). If your provider cannot enable this, you may be limited to manual client payments (where CVV is entered each time).

2) HTTP 401 Unauthorized

What it means: Invalid API authentication.

Common causes:

• Wrong Merchant ID or API Password
• Using sandbox credentials against a live host (or vice versa)
• Username format mismatch (some MPGS setups require merchant.<MERCHANTID>)

Fix:

• Re-check the MPGS host and confirm it matches your credentials environment.
• Re-enter the API password carefully (watch for leading/trailing spaces).
• Confirm your provider’s required API username format.

3) HTTP 403 Forbidden

What it means: Auth worked, but your API user is not permitted to perform that operation.

Common causes:

• API user role not allowed to run PAY or REFUND
• Merchant has IP restrictions / allow-listing enabled
• Operation not enabled on the merchant profile

Fix:

• Ask your bank/provider to confirm your API account has permissions for required operations.
• If IP restriction is enabled, allow-list your WHMCS server IP.

4) HTTP 404 Not Found

What it means: Wrong endpoint URL.

Common causes:

• Incorrect Gateway Hostname
• Incorrect API version or base path
• Host includes extra path segments (should be hostname only, no https://, no /...)

Fix:

• Set the hostname to the value your provider supplied (hostname only).
• Use the API version recommended by your provider (commonly 100).

5) HTTP 400 Bad Request

What it means: MPGS rejected the request payload (data format/values).

Common causes:

• Invalid currency or amount formatting
• Required fields missing for the chosen operation
• Unsupported field for your API version

Fix:

• Enable Debug Logging and review the sanitized request/response.
• Confirm you are using a supported currency code (e.g. AUD).
• Confirm amount is formatted correctly (two decimals).

6) “Invalid JSON response from gateway”

What it means: WHMCS did not receive valid JSON (could be HTML, empty, or truncated).

Common causes:

• Firewall/WAF/proxy returning an HTML error page
• Network instability
• SSL interception on the server network

Fix:

• Confirm your server can reach the gateway host on port 443.
• Check if outbound HTTPS is being filtered or intercepted.
• Diagnostics only: temporarily enable “Disable SSL Verification” to confirm it is SSL-chain related, then switch it OFF once fixed.

7) SSL / cURL certificate errors

Symptoms: cURL errors about certificate verification or issuer chain.

Fix:

• Update your server CA certificates / trust store
• Ensure ca-certificates is installed and current
• Only for diagnostics: toggle “Disable SSL Verification” temporarily

Refund Errors

If refunds are declining:

• Confirm the original payment is in a refundable state (check MPGS portal).
• Confirm the API user has refund permission enabled.
• Confirm the transaction reference stored in WHMCS matches the expected format used by the module.

Stored Cards & Auto-Charge (Important)

WHMCS never stores CVV (PCI compliance). That means:

• Manual client payments can use CVV (entered at time of payment).
• Auto-charge / admin capture using a stored card requires your MPGS profile to allow merchant-initiated / recurring charges without CVV (usually tokenised).

If your bank requires CVV for every transaction, you will not be able to use stored-card automation, and clients must pay invoices manually.

What to Send Support (So We Can Help Fast)

Please include:

• WHMCS version + PHP version
• Is it Sandbox or Live?
• The exact error message shown in WHMCS
• A screenshot or copy from Utilities → Logs → Gateway Log (sanitized)
• Whether it was:
  • Client manual payment
  • Admin attempted capture using stored card
  • Cron/automation capture attempt

Quick Reference Table