---
url: /phonepe-whmcs/troubleshooting.md
description: >-
  Fix the common PhonePe for WHMCS problems — payments failing, the webhook not
  delivering, and a license that won't activate — starting from the Gateway Log.
---

# Troubleshooting

Most PhonePe problems come down to a credential, a webhook setting, or the license. This page walks
through the three you're most likely to hit. **Start with the Gateway Log** — it almost always
names the cause.

::: tip Always check the Gateway Log first
Go to **Utilities → Logs → Gateway Log** and look for the most recent PhonePe entries around the
time of the failed payment. The log records what PhonePe returned and why the gateway stopped.
:::

## Payments are failing

When a customer can't complete a PhonePe payment:

1. **Check the Gateway Log** (above) for the specific failure on that attempt.
2. **Verify your credentials.** In **Setup → Payment Gateways → PhonePe**, confirm the
   **Client ID** and **Client Secret** exactly match those in your PhonePe Merchant (Business)
   dashboard — no trailing spaces, correct account.
3. **Confirm the account is live.** Your PhonePe Business account must be **active and
   KYC-verified**; a pending or restricted account can't take live payments.
4. **Check Sandbox Mode.** If **Sandbox Mode** is **Yes**, you're testing against PhonePe's
   sandbox, not taking real payments — set it to **No** for live.
5. **Confirm the webhook is configured** so results can come back (see below); without it, an
   otherwise-successful payment may not be recorded as Paid.

## The webhook isn't working

The webhook is how PhonePe tells your site a payment succeeded. If invoices stay unpaid even though
customers paid, work through these:

1. **The URL must be reachable over HTTPS.** In the PhonePe dashboard, the Webhook URL must be
   exactly:
   `https://yourdomain.com/modules/gateways/phonepe/webhook.php`
   Open it in a browser — it should be served over a valid SSL certificate, not blocked by a
   firewall or WAF.
2. **The username and password must match.** The **Webhook Username** and **Webhook Password** in
   **Setup → Payment Gateways → PhonePe** must be identical to the ones you set in the PhonePe
   dashboard's webhook settings. A mismatch is the most common cause of a rejected webhook.
3. **A 401 means authentication failed** — the incoming request didn't pass the SHA256 hash check,
   almost always because the username/password don't match on both sides. Re-enter them in both
   places and save.
4. **A 500 means processing failed** — the webhook arrived but the handler hit an error. Check the
   Gateway Log for that entry; a stale license or bad credentials during the secondary status
   check are typical causes.

::: info Why results are double-checked
When the webhook arrives, the gateway also makes a secondary call to PhonePe to confirm the
payment status before marking an invoice Paid. If that confirmation can't be made — for example,
outbound HTTPS is blocked or credentials are wrong — the invoice won't flip to Paid even though
the webhook was received.
:::

## The license won't activate

If PhonePe payments are disabled because the license won't activate:

1. **Re-check the key.** In **Setup → Payment Gateways → PhonePe**, confirm the **License Key**
   matches the one in your relyweb.co client area exactly, with no extra spaces, then
   **Save Changes**.
2. **Allow outbound HTTPS.** Your server must be able to reach **relyweb.co** over HTTPS to
   validate the key. If outbound requests are firewalled, activation will fail.
3. **Confirm the license is current.** A Leased license must still be active; a lapsed one disables
   payments until renewed. See [Licensing](/phonepe-whmcs/licensing).

## Related pages

* [Errors](/phonepe-whmcs/errors) — webhook auth failures and license-inactive behaviour
* [Configuration](/phonepe-whmcs/configuration) — the fields referenced above
* [Licensing](/phonepe-whmcs/licensing) — how the license gates payments
* [FAQ](/phonepe-whmcs/faq) — quick answers to common questions