On this page, we will address common issues with the WHMCS payment gateway module. Our WHMCS payment gateway module has been thoroughly tested and is designed to automatically process all paid invoices once configured. However, certain poorly coded modules or incorrect settings on your site may cause issues. This guide will help you troubleshoot and resolve these problems. If you need further assistance, our support team is available for free help.
Paid Invoices are Not Marked as Paid (IPN Failure)
The payment gateway module is designed to automatically mark WHMCS invoices as paid after a customer completes the payment. This process, called Instant Payment Notification (IPN), may fail due to improperly configured modules or settings. As a result, some invoices may remain in a pending status even after payment.
To address this issue, you must first identify the cause and understand how the process works. Each invoice has a unique callback URL that is visited by our payment bot after a payment is completed. The bot ensures the invoice is marked as paid. If this visit is successful, the invoice status is updated accordingly.
Investigating the Callback URL
The callback URL for each module follows this format:
https://www.example.com/modules/gateways/callback/provider.php?invoice_id={invoice-number}
The PHP file name will vary depending on the activated module. For example, for the Wert module, it will be wert.php. Paste the callback URL into your browser and carefully examine the response. One common issue is CAPTCHA (I’m not a robot) appearing on the page, which blocks our bot from completing the notification.
Fix CAPTCHA Blocking IPN
If a CAPTCHA appears, you need to allow our bot’s IP address or remove the CAPTCHA from the callback pages. CAPTCHA issues are often caused by firewall plugins or Cloudflare protection. To resolve this with Cloudflare, allow the callback page paths through the Cloudflare dashboard under Security > WAF.
Invoice Failed Error
If you encounter an error message such as “Invoice failed. Please select another payment provider or contact support“, it is typically due to one of the following:
- The order amount is less than the minimum allowed by the payment provider.
- The store currency is unsupported by the payment provider.
Other Common Errors
Some errors are caused by entering an invalid wallet address or failing to configure a wallet address in the WHMCS gateway admin settings. To receive payments, you must provide a valid USDC (Polygon) wallet address. Errors related to invalid or missing wallet addresses include:
- “Payment could not be processed due to incorrect payout wallet settings. Please contact the website admin.”
- “Payment could not be processed. Please try again (wallet address error).”
If you encounter an error not mentioned here or need further assistance, please contact our support team.