Appearance
Errors
PhonePe for WHMCS logs failure details to the WHMCS Gateway Log (Utilities → Logs → Gateway Log) rather than showing customer-facing error strings. This page covers two primary failure conditions:
- Webhook authentication failures: Mismatched credentials or failed API status confirmations.
- License-inactive states: Suspended payment processing due to an expired or missing key.
Webhook authentication failures
Every webhook from PhonePe is SHA256 hash-authenticated using the username and password you configured on both sides. When that check fails, the gateway rejects the request:
| You see | What it means | What to do |
|---|---|---|
| 401 (unauthorized) on the webhook | The incoming request failed the SHA256 authentication check — the webhook username/password don't match between PhonePe and WHMCS. | Re-enter matching Webhook Username / Webhook Password in both the PhonePe dashboard and Setup → Payment Gateways → PhonePe. |
| 500 (processing error) on the webhook | The request authenticated but the handler couldn't finish — often the secondary status confirmation to PhonePe failed, or credentials were wrong during that check. | Check the Gateway Log entry, verify Client ID/Secret, and confirm outbound HTTPS to PhonePe is allowed. |
| Invoice stays unpaid after a paid attempt | The webhook didn't arrive or was rejected, so the payment was never recorded. | Confirm the Webhook URL over HTTPS and the username/password match; see Troubleshooting. |
Dual verification
Authenticated webhooks undergo secondary validation:
- API confirmation: The gateway queries PhonePe's API to verify payment success before marking invoices Paid.
- Fail-safe: If the API check cannot verify status, the invoice remains unpaid to prevent recording unconfirmed payments.
License-inactive behaviour
The license directly controls payment processing:
- Processing disabled: The gateway halts PhonePe charges while the license is inactive.
- Outage tolerance: Local background caching tolerates brief licensing-server outages without interrupting checkout.
- Recovery: Renew your license or enter a valid License Key in Setup → Payment Gateways → PhonePe, then click Save Changes.
Other gateways and the rest of your WHMCS install are unaffected — only PhonePe payment processing is gated.
Related pages
- Troubleshooting — step-by-step fixes for these situations
- Licensing — the two license types and the license-gated feature
- Configuration — the webhook and license fields