Troubleshooting

The most common problems and the exact fix.

Quick Index

Symptom	Jump to
Wallet gateway missing at checkout	→ Gateway visibility
Recharge order completed but balance not credited	→ Top-up not credited
Withdrawal stuck on pending	→ Withdrawal stuck
Cashback not firing	→ Cashback not firing
KYC modal won't open	→ KYC modal broken
Transfer OTP not received	→ OTP not received
BNPL eligible user not getting offer	→ BNPL eligibility
REST API returning 401 / 403	→ REST auth
Stale balance shown to customer	→ Cache stale
Bulk batch stuck on pending	→ Bulk stuck

Installation Checks

After activation, confirm:

Check	Where	Expected
Tables created	`SHOW TABLES LIKE 'wp_wkw%'`	At least 11 tables
Recharge product exists	Products → All Products	`Recharge Your Wallet`
Gateway registered	WC → Settings → Payments	`Wallet` row visible
My Wallet endpoint	`/my-account/my_wallet/`	renders
Admin menu	sidebar	Webkul Addons → Wallet

If any missing → run WC → Status → Tools → Wallet → Re-run installer.

Wallet Gateway Not Visible at Checkout

Run through this list:

Gateway enabled? WC → Settings → Payments → Wallet toggle ON
Customer logged in? Gateway never shows to guests
Customer balance > 0? Or "Show on zero balance" ON
Excluded product in cart? Per-product _wkwp_exclude_wallet = yes blocks
Sale item + global "disable on sale" ON? Hides gateway
KYC required and not approved? wallet_usage is gated; customer must approve KYC
Theme caches checkout? Test with default theme + cache plugin off
Custom filter returning false? Search code for wkwc_wallet_show_method_on_checkout

See Wallet Payment Gateway.

Top-up Completed But Balance Not Credited

Step	Check
1	Order has at least one `wkwc_wallet`-type line item — open the order, view product types
2	Order in `completed` status (not `processing`) — only `completed` triggers credit unless auto-complete is on for mixed carts
3	`_wkwp_topup_credited = yes` order meta? If yes, credit already happened — check ledger for the row
4	Recharge product type was changed away from `wkwc_wallet`? Re-set it
5	Custom filter on `wkwp_wallet_topup_amount` returning 0 / negative? Search code

If still no credit → manually re-trigger by setting order to processing then back to completed (re-fires woocommerce_order_status_completed).

See Recharge / Top-up.

Withdrawal Stuck on Pending

Step	Check
1	Admin must approve manually — pending sits until acted on
2	KYC required + not approved? Customer can't even submit; if a row exists from before KYC was required, manual action needed
3	Hold period set + not yet matured? Row sits as `approved` until cron `wkwp_wallet_withdrawal_payout_cron` runs
4	Cron not firing? `wp cron event list` to verify; alarm if `wp-cron.php` is disabled (`DISABLE_WP_CRON`)
5	Payout API failed? Status would be `failed`, not `pending` — check the row's error column

For PayPal / Stripe specifics see PayPal Payout and Stripe Payout.

Cashback Not Firing

Step	Check
1	Rule active? Toggled ON in Wallet → Cashback Rules
2	Order in `completed` status (not just `processing`)
3	Min order value met by the order subtotal
4	Cart matched the rule's scope (product / category / global)
5	Per-customer cap hit?
6	`_wkwp_cashback_processed = yes` order meta already set — credit already given
7	Higher-priority rule shadowing this one — engine picks first match by priority

Test with a single global rule and zero min — if cashback fires there, narrow down.

See Cashback Engine.

Step	Check
1	Browser console error? Likely a theme JS conflict
2	Native `<dialog>` polyfill missing on old Safari (< 15.4) — plugin ships its own; verify it's loaded on the page
3	KYC pill visible but click does nothing — JS bound after page-load? Check `DOMContentLoaded` order
4	KYC feature toggle off — pill renders but modal hidden
5	Theme overriding `dialog` CSS to `display: none !important`?

Quick test: open browser console and run document.querySelector('dialog#wkwp-kyc-modal').showModal() — if that opens it, the click handler is the issue.

See KYC.

Transfer OTP Not Received

Step	Check
1	Sender's phone meta set? `get_user_meta($id, '_wkwp_user_phone', true)` — empty means no SMS, only email OTP
2	Twilio creds correct? Test from Wallet → Settings → Notifications → SMS → Test send
3	Twilio from-number verified? Test number can only message verified destinations on trial accounts
4	Twilio geo permission for the destination country enabled?
5	Email OTP arriving? If yes → Twilio side issue; if no → SMTP issue
6	OTP expired? 10-min window; re-request

See Wallet Transfer, SMS Notifications.

BNPL Eligible User Not Offered Checkout

Step	Check
1	BNPL globally enabled? `_wkwp_bnpl_enable = yes`
2	Customer in eligibility set per `_wkwp_bnpl_eligibility_mode`? Whitelist / role / kyc-approved
3	Cart total >= `_wkwp_bnpl_min_order_for_bnpl`?
4	Existing debt + new shortfall <= `_wkwp_bnpl_max_debt_per_user`?
5	`wkwp_bnpl_eligible` filter returning false?

See Buy Now Pay Later.

REST API 401 or 403

Status	Cause
401 `invalid_credentials`	Key revoked, or wrong secret, or owner user lacks underlying capability
403 `forbidden_caller_ip`	Caller IP not in the key's whitelist
403 `kyc_required`	The endpoint enforces KYC and the owner user lacks approved KYC
429 `too_many_requests`	Rate-limit hit — wait `Retry-After` seconds

Mint a new API key with the right scope. See REST API.

Stale Balance Shown to Customer

Cache invalidation missed. Fixes:

WC → Status → Tools → Wallet → Clear wk_caching cache — one-click flush
WP-CLI: wp cache flush
Programmatic: WK_Caching::flush_namespace( 'wkwp_wallet' );
If recurring, check that wkwp_wallet_balance_changed action is firing — search code for do_action( 'wkwp_wallet_balance_changed'

Bulk Batch Stuck on Pending

Step	Check
1	Cron firing? `wp cron event list` — look for `wkwp_wallet_bulk_queue_process`
2	`DISABLE_WP_CRON` set? Switch to a system cron + manually trigger from the Bulk page's "Process now"
3	Worker errored on a row? Check the `error` column of the queue table
4	Lock not released? Find `wkwp_bulk_lock` transient and delete it

See Bulk Credit / Debit.

Decorator Breaks Customer Wallet Page

The modern fintech My Wallet layout is a decorator on the legacy template. If your theme breaks it:

Toggle the layout to layout-classic (decorator bypassed) via the wkwp_my_wallet_layout filter (see Filters & Hooks)
Open a support ticket with theme name + screenshots — we'll patch the decorator selectors

See My Wallet Page.

"Insufficient balance" When Balance Should Be Enough

Step	Check
1	Multi-currency mode on? Customer's active currency might have a different balance
2	Outstanding BNPL debt counts against balance — auto-deduct grabs new credits
3	Hold period on the recharge order? Topups on `processing` aren't credited until `completed`
4	Float rounding — check the ledger for the actual decimal value, not the display

Withdrawal Says "KYC Required" But KYC Is Approved

Cache miss on KYC gate. Force flush:

WK_Caching::delete( 'wkwp:kyc:gates:' . $user_id, 'wkwp_wallet' );

Or just toggle the customer's KYC status to pending then back to approved from the admin to fire wkwp_kyc_status_changed (the cache-buster).

See KYC.

Wallet Used But Order Total Wrong

Likely: cashback / discount applied AFTER wallet calc, or rounding.

Order edit screen → side meta-box Wallet shows _wkwp_wallet_paid_amount — must equal the wallet line in the ledger
WC's order total accounts for fees + cashback + discount + tax — wallet pays the post-everything cart total
Compare with WC()->cart->get_total() at checkout time (use a debug shortcode)

Logs

Enable per-event debug logs:

define( 'WKWP_DEBUG', true );

Logs land in wp-content/uploads/wc-logs/wkwp-wallet-*.log. Tail with:

tail -f wp-content/uploads/wc-logs/wkwp-wallet-*.log

When to Open a Support Ticket

Open a ticket with the following info:

WordPress version + WC version + PHP version
Wallet plugin version
Site URL (or a screenshot if confidential)
The exact error message + steps to reproduce
Output of WC → Status → System Status (copy-paste the report)
Output of Tools → Site Health → Status (the wallet section)
Browser console output if the issue is UI-side
Server-side logs if available

Submit at https://webkul.uvdesk.com.