Appearance
Errors
This page describes the behaviour you'll see in two situations: when a webhook fails authentication, and when the license is inactive. PhonePe records the detail of each in the Gateway Log (Utilities → Logs → Gateway Log) rather than showing a customer-facing error string, so the log is where you confirm the cause.
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
Even a correctly authenticated webhook is double-checked: the gateway calls PhonePe to confirm the payment status before an invoice is marked Paid. If that confirmation can't be made, the invoice won't flip to Paid — this is deliberate, to prevent recording an unconfirmed payment.
License-inactive behaviour
The license gates payment processing. When the license is active, PhonePe takes payments normally. When it is inactive:
- PhonePe payment processing is disabled — the gateway stops completing charges through PhonePe until a valid, active license key is saved.
- The check runs locally in the background, so a brief licensing-server outage does not disable payments; short interruptions are tolerated.
- Restore it by renewing your license or re-entering a valid License Key in Setup → Payment Gateways → PhonePe, then Save Changes. Payments resume once the license is active again.
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