Home / Blog / Solutions

WHMCS Crypto Gateway Webhook Troubleshooting Guide

Fix WHMCS crypto payment callbacks and unpaid invoices. Diagnose webhook delivery, signatures, gateway logs, cron jobs and duplicate transactions.

Anna Alenteva Anna Alenteva Nov 13, 2026 11 min read
Technician’s hand connects a worn diagnostic cable to an unbranded rack-mounted network appliance in a daylight-lit hosting facility.

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.

A billing operator and server administrator review a redacted payment-incident printout during a handoff at a daylight hosting support counter.

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 symptomCorrelated evidenceWhat it establishesNext actionStop condition and ownerRecovery acceptance
Undelivered callback; UnpaidSettled gateway payment and delivery attempt; server denial; no matching WHMCS transaction; service suspendedTransport failed before payment applicationRepair the exact route, recheck ledger, then supported redeliveryServer administrator owns transport; billing stops if credit appearsCorrect original credit and balance; intended service effect; no extra collection, credit or date advance
Rejected authentication; UnpaidDelivery reaches handler; module rejects signature; matching store, endpoint, event and payment; no invoice creditReachability exists, authenticity has not passedInspect active secret/configuration; supported repair, then redelivery or current reconciliationMaintainer owns unexplained rejection; pause credit if authenticity remains uncertainAuthenticated recovery credits the original invoice only; expected service effect without duplicate effects
Incorrect mapping; Unpaid or wrong invoice creditedSettled gateway invoice, saved checkout association, WHMCS invoice terms and transactions disagreePayment destination in the ledger is uncertainBilling reconstructs association; use supported reconciliation after reviewBilling stops automatic credit if mapping or terms differCredit belongs to intended invoice/period, correct balance and service; no duplicate collection, credit or date advance
Non-final event; UnpaidCurrent gateway state and confirmations do not establish settlement; WHMCS credit absent; service unchangedTransfer exists but does not yet qualifyWait and monitor existing payment; review exceptionsBilling owns monitoring; no full credit until settlement qualifiesOnce qualified, original payment credited correctly with expected service action and no duplicate effects
Duplicate or out-of-order noticeEvent/delivery times differ; current gateway settlement and mapped WHMCS transaction checked; service date recordedArrival order is not payment order; credit may already existLeave valid existing credit intact; reconcile current state if neededBilling stops replay as repair when credit exists; maintainer owns duplicate effectsSame credit, balance and service date after repeat; no extra collection or date advancement
Credited invoice, service unavailableCorrect payment reference clears invoice; linked service reason, due date and Module Queue show remaining faultPayment application succeeded; service action needs diagnosisFollow the service procedure belowServer administrator owns failed service action; billing owns older arrearsLedger intact; access restored when eligible, or remaining arrears explained; no repeated credit or date advancement
Choose recovery from correlated evidence. In every row, preserve the original payment association and check the final ledger and service effect.

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.

Wide view of a hosting facility network room where a technician uses a service light to inspect an open equipment cabinet beneath overhead cable trays.

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.

  1. Follow gateway settlement into its matching delivery, Gateway Log entry and WHMCS transaction. Confirm the original payment reference is attached to the intended invoice.
  2. 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.
  3. 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.

Standing operator authorizes a payment by phone beside a defocused test terminal and small equipment rack in a naturally lit hosting laboratory.

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.

Server administrator stands in profile operating a pull-out rack console while holding an access key in a daylight-lit equipment aisle.

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.

Billing operator files a redacted incident packet in a records cabinet while holding the matching service checklist in a daylight office.

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
Written by

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.

Accept crypto without giving up control

Subscriptions and one-time payments, settled to your own wallet. No custody, no frozen funds, no chargebacks.