Quick answer
WHMCS crypto gateway webhook troubleshooting starts with the gateway's current settlement record and the WHMCS transaction ledger. Wait for a non-final payment. For a settled, correctly mapped payment without credit, repair delivery or authentication and use supported redelivery; reconcile missed history. If the correct credit already exists, investigate service automation. Never request another payment while the original remains unresolved.
How WHMCS payment callbacks work
The customer has a transfer receipt; WHMCS still says Unpaid. Start with the gateway's settlement record, then the invoice ledger. Wait if settlement is pending. If settlement is established but credit is absent, trace delivery, authentication and invoice mapping before supported redelivery or reconciliation. If credit exists, repair the service action. Asking the customer to pay again can turn a missing notification into an extra payment.
In this illustrative incident, a USD 20 hosting invoice has no prior credit. The customer paid through BTCPay, yet hosting is suspended. Before selecting Paid manually, billing finds the gateway invoice settled, a firewall denial in delivery history and the server log, and no WHMCS transaction. Authentication and the original checkout mapping remain valid. The server administrator now has a specific fault to repair.
The module receives a server notification at its documented callback URL, validates authenticity and invoice association, checks for an existing transaction, logs the result and applies payment. Balance and service actions follow. A browser success page is separate: a visible transfer, gateway settlement and WHMCS credit are distinct findings.

WHMCS crypto gateway webhook troubleshooting: find the failed transition
Open Billing > Gateway Log and inspect Result and Debug Data around the payment time. Compare them with provider delivery history, server access/error logs, and Billing > Transactions. The useful finding is a matched sequence across systems, not an isolated error message or an empty log.
Link the WHMCS invoice and service to the gateway account/store, environment, invoice/payment reference, event/delivery references, blockchain hash/network, amounts/currencies and UTC timestamps. Keep identifiers distinct: a delivery identifies an attempt and an event identifies a notification. Neither automatically equals the module's recorded transaction ID. Search the ledger using that payment reference before recovery.
Confirm current gateway state, required confirmations, amount, currency, network and payment window. Check that the installed module is active and its documented callback destination includes the actual WHMCS subdirectory. Correlate an actual delivery with TLS/certificate, routing, firewall and application responses. A browser GET does not test an authenticated provider POST.
| Failure and symptom | Correlated evidence | What it establishes | Next action | Stop condition and owner | Recovery acceptance |
|---|---|---|---|---|---|
| Undelivered callback; Unpaid | Settled gateway payment and delivery attempt; server denial; no matching WHMCS transaction; service suspended | Transport failed before payment application | Repair the exact route, recheck ledger, then supported redelivery | Server administrator owns transport; billing stops if credit appears | Correct original credit and balance; intended service effect; no extra collection, credit or date advance |
| Rejected authentication; Unpaid | Delivery reaches handler; module rejects signature; matching store, endpoint, event and payment; no invoice credit | Reachability exists, authenticity has not passed | Inspect active secret/configuration; supported repair, then redelivery or current reconciliation | Maintainer owns unexplained rejection; pause credit if authenticity remains uncertain | Authenticated recovery credits the original invoice only; expected service effect without duplicate effects |
| Incorrect mapping; Unpaid or wrong invoice credited | Settled gateway invoice, saved checkout association, WHMCS invoice terms and transactions disagree | Payment destination in the ledger is uncertain | Billing reconstructs association; use supported reconciliation after review | Billing stops automatic credit if mapping or terms differ | Credit belongs to intended invoice/period, correct balance and service; no duplicate collection, credit or date advance |
| Non-final event; Unpaid | Current gateway state and confirmations do not establish settlement; WHMCS credit absent; service unchanged | Transfer exists but does not yet qualify | Wait and monitor existing payment; review exceptions | Billing owns monitoring; no full credit until settlement qualifies | Once qualified, original payment credited correctly with expected service action and no duplicate effects |
| Duplicate or out-of-order notice | Event/delivery times differ; current gateway settlement and mapped WHMCS transaction checked; service date recorded | Arrival order is not payment order; credit may already exist | Leave valid existing credit intact; reconcile current state if needed | Billing stops replay as repair when credit exists; maintainer owns duplicate effects | Same credit, balance and service date after repeat; no extra collection or date advancement |
| Credited invoice, service unavailable | Correct payment reference clears invoice; linked service reason, due date and Module Queue show remaining fault | Payment application succeeded; service action needs diagnosis | Follow the service procedure below | Server administrator owns failed service action; billing owns older arrears | Ledger intact; access restored when eligible, or remaining arrears explained; no repeated credit or date advancement |
A provider attempt plus server denial points to transport blocking; a handler rejection points to validation; a matching credit moves attention beyond delivery. These are illustrative observations, not universal log strings. Result labels are module-defined. No Gateway Log entry proves neither absence nor success: duplicate detection can halt processing before logging. Even an HTTP success response does not establish credit.
For WHMCS webhook signature verification, match the active webhook's account/store, environment and endpoint. BTCPay uses HMAC-SHA256, an authentication check derived from its secret and exact raw request body. Parsing and re-encoding can change signed bytes; ask the maintainer to check the unchanged body and active secret. Other modules have their own authentication and timestamp rules. Never bypass verification or invent a universal replay window.
For BTCPay WHMCS v4 Greenfield, use Set up / repair webhook. If setup reports a lost secret or stale record, preserve delivery evidence and inspect the matching webhook before confirmed Re-register webhook. Replacement invalidates old-secret deliveries without replaying all historical settlements: reconcile saved invoices through the current authenticated connection. For another module's unexplained replay rejection, pause accounting changes and send its maintainer the exact redacted error and correlated references.
Finality asks whether payment qualifies; mapping asks which obligation it pays. A valid invoice ID does not establish the billing period. In an illustrative variation, a customer has two USD 20 invoices: customer and amount cannot choose the month. Compare the original checkout association, amount, currency, payment method and connection. Missing mappings or changed terms stop automatic credit while billing reconstructs the association.
BTCPay's InvoiceProcessing precedes InvoiceSettled. For missed or out-of-order notices, reconcile current status with additionalStatus, which describes exceptions. An older Processing notice must not undo settlement. Partial, late, expired and overpaid payments require documented handling; partial receipt cannot justify full credit. Run a single recovery action per invoice at a time.

Repair, reconcile and test the callback end to end
Use redelivery when a settled, correctly mapped payment remains uncredited after its demonstrated fault is repaired and the provider supports repeating that event. Use reconciliation for missed history or uncertain event order. Neither action should initiate another collection. When authenticity, mapping or prior credit remains uncertain, stop accounting changes and escalate.
In the illustrative firewall incident, the server administrator repairs only the documented callback route and required traffic, retaining signature validation. Billing rechecks the ledger, then chooses Redeliver on the existing settlement webhook in BTCPay invoice details. The assumed USD 20 obligation receives one USD 20 credit, leaving USD 0, with no fee or exchange adjustment. No second transfer is requested.
Here, the service was suspended for Overdue on Payment, Enable Unsuspension is enabled and no older arrears prevent restoration. Payment advances Next Due Date by its billing cycle and access resumes. Billing verifies both. These are the illustration's acceptance results; redelivery does not override service settings. An already credited invoice instead follows the service procedure below.
If verified delivery leaves payment uncredited, or settlement predates repair, use current authenticated reconciliation. In BTCPay v4's recovery page, choose Reconcile saved invoices, then Continue reconciliation through all batches. Each submission checks up to five unprocessed mappings. Resolve errors and rescan, including payments received during repair. Automatic recovery requires a persisted matching association; older unmapped invoices need manual review, not an order-number guess.
Use staging with separate provider configuration where available. WHMCS gateway test mode is module-specific; a sandbox is not universal. Otherwise isolate a low-value live product with understood service actions. Record balance, service state and Next Due Date, generate an invoice through normal checkout and pay once using the intended wallet/network. In BTCPay v4, confirm Webhook ready. Check connection tests access and permissions, not inbound delivery.
- Follow gateway settlement into its matching delivery, Gateway Log entry and WHMCS transaction. Confirm the original payment reference is attached to the intended invoice.
- Check that the fully paid invoice has zero balance and the expected hosting action occurred. Compare the service state and Next Due Date with the baseline, including actual hosting access.
- During this controlled test, redeliver that same settlement once through the supported control. Compare the ledger, balance, service state and Next Due Date again: no additional credit, collection or date advancement is acceptable.
In the illustration, the repeat leaves credit and service date unchanged. If it adds credit or advances the date, stop replay and give before-and-after evidence to the maintainer. A fabricated unsigned POST proves neither normal processing nor duplicate safety. The original credit and intended service effect must survive the repeat without another collection.
Escalate with a UTC timeline, gateway invoice/payment and event/delivery references, current settlement, expected/received amounts and currency, original association, WHMCS transactions, redacted responses/logs and service outcome. Remove keys, secrets and unnecessary customer data. Name billing, server and maintainer owners. For modules without documented recovery controls, request supported reconciliation of the existing payment with accounting changes paused.
After verification, tell the customer: Your original payment has been applied and hosting access is restored. You do not need to pay this invoice again. Monitor the next actual payment through the same transitions. For unresolved custom behavior, the WHMCS custom payment gateway guide frames a maintainer discussion; crypto billing webhook integration reading explains repeated and missed notifications.

Cron, delayed service updates and troubleshooting FAQ
Core WHMCS cron is not a universal crypto webhook replay mechanism. Separate missing payment credit from delayed invoice generation or service automation. Once the correct transaction clears the invoice, further payment replay is the wrong way to repair suspended hosting.
Open Utilities > Automation Status, inspect the cron badge and daily-task failures, and assign cron repair to the server administrator. After repair, wait at least five minutes and refresh. A healthy run establishes that scheduled work resumed, not that the missing payment arrived. Retry behavior is module-specific; investigate absent credit separately.
Verify a real transaction cleared the balance: manually selecting Paid does not trigger payment automation. Check the service's suspension reason, Next Due Date and older invoices. Under Configuration > System Settings > Automation Settings, inspect Enable Unsuspension. Automatic restoration requires eligible Overdue on Payment suspension; paying a newer invoice can leave the due date inside the suspension range because older arrears remain.
Inspect Utilities > Module Queue. Have the server administrator repair the failed hosting/provisioning action and resolve the queue through supported controls. Verify WHMCS state, the hosting account and customer access while preserving the payment record. If older arrears justify suspension, billing explains that remaining obligation instead of collecting the cleared invoice again.
Record invoice generation, payment application and service restoration separately, with an owner for each unresolved outcome. Healthy cron can coexist with a blocked callback; correct credit can coexist with a failed hosting command. The FAQ addresses residual questions without promising that a cron restart restores payment status synchronization.

Close the incident before evaluating the next gateway
Close against evidence: the original payment credits the intended invoice, its balance is correct, the expected service outcome is verified, and the controlled repeat adds no collection, credit or service-date advancement. A green connection indicator is a useful observation, not an accounting receipt.
Carry the demonstrated gap into later evaluation: missing history demands durable invoice associations; duplicate effects demand a repeat-event test; failed access demands a separate service check. The incident now supplies a concrete requirement for a controlled evaluation.

Turn the incident into a gateway requirement
Use the WHMCS Crypto Gateway Guide to compare your installed setup's demonstrated invoice and confirmation behavior with its invoice-handling, settlement, custody and renewal requirements. Carry the unresolved requirement into a controlled evaluation. The guide supports that next decision; opening it does not repair the incident.
Frequently asked questions
Why does WHMCS show Unpaid after payment?
A visible transfer may still be non-final, or the settled payment's callback may have failed delivery, validation or mapping. Confirm current gateway settlement and search the WHMCS transaction ledger before selecting recovery.
Where is WHMCS Gateway Log?
Open Billing > Gateway Log and inspect Result and Debug Data around the payment time. Compare those entries with provider delivery history and server logs; an empty log alone does not identify the failed layer.
How do I test a gateway callback?
Generate an invoice through normal checkout in an isolated test setup, pay once, and trace settlement through credit and service action. Repeat the same settlement through supported redelivery and verify that the ledger and service date remain unchanged.
Should I disable signature checks to resolve a rejected webhook?
Keep verification enabled. Check the active endpoint, environment, account/store and secret. BTCPay checks the exact raw body; other modules require their own documented authentication and replay rules.
Can I match a settled payment by customer and amount?
That can select the wrong billing period. Use the original checkout association and matching invoice terms. Missing or changed associations need billing review before automatic credit resumes.
Does a duplicate notification mean the customer paid twice?
No. Compare the actual payment reference and ledger, not the number of deliveries. An authentic repeated notification must preserve the existing credit and service date.
When is reconciliation preferable to redelivery?
Use current authenticated reconciliation for missed settlement history, obsolete-secret deliveries after webhook replacement, or uncertain event order. Automatic recovery requires a valid saved association; ambiguous payments need manual review.
Can cron fix a Paid invoice whose hosting remains suspended?
Inspect the service's suspension reason, due date, older arrears, Enable Unsuspension and Module Queue. Repair the failed service action or cron task as appropriate; replaying the successful payment is not a service repair.
Anna Alenteva
Head of HR at Scrile. Sets up the working relationship between company and employees so both sides come out ahead. Writes about team building, hiring patterns in SaaS, and the operating model behind sustainable engineering teams.
Reviewed under our Editorial standards.
