Wallet System

How the bundled wallet ties auctions, fees, and payouts together — top-up, auction-win charge, peer-to-peer transfer, withdrawal.

What's bundled

The plugin ships a complete wallet system. Out of the box you get:

• A customer wallet endpoint at /my-account/my_wallet/
• A withdrawal request endpoint at /my-account/wkwc_withdrawal/
• A wallet payment gateway listed under WooCommerce → Settings → Payments
• Cart and checkout block compatibility (works in both classic and block-based checkout)
• OTP-protected peer-to-peer transfer
• Email and SMS templates for every wallet event
• Admin top-up / debit / refund operations

The wallet system is shared across Webkul plugins, so if you run more than one Webkul plugin that uses it, only one copy of the wallet is active at a time — automatically the most up-to-date one.

Top-up flow

1. The customer enters an amount on the My Wallet page.
2. The plugin adds a hidden "wallet top-up" WooCommerce product to the cart at the chosen amount.
3. The customer checks out via any WooCommerce payment gateway (Stripe, PayPal, bank, etc.).
4. When the order completes, the wallet credits the customer's balance.
5. The customer receives a "Wallet credited" email and the new balance shows immediately on the My Wallet page.

The top-up product is created automatically on plugin activation, hidden from the shop, search and catalog. You can swap it for a custom product under Settings → Payments → Top-up product ID.

Auction win flow

When an auction closes with a winner:

• If auto-charge winner is on and the winner's wallet balance covers the bid, the wallet is debited, an order is created and marked complete, the auction is marked paid, and the winner gets a "wallet-paid" email.
• Otherwise, the standard "Auction won" email goes out with a payment link, and the auction sits in awaiting payment until the customer checks out normally.

Auto-charge details →

Fee charge flow

Auction fees (listing, buyer's premium, late penalty, etc.) try the wallet first.

• If wallet pays fees is on and the wallet has enough, the wallet is debited and the fee is logged.
• Otherwise the fee is added to the next order and the customer pays it at checkout.

Monetization →

Withdrawal flow

Customer Withdrawal →

Refund flow

When an auction is cancelled or disputed and the win was paid from the wallet, the original debit is reversed: a fresh credit row goes into the ledger (the original debit is preserved for traceability), the auction is marked refunded, and the customer gets a "wallet refunded" email.

Concurrent debit safety

Like bidding, wallet debits are protected by per-customer row locks. Two simultaneous debits cannot drive a balance negative — the second attempt sees the updated balance and fails cleanly with "Insufficient balance".

HPOS support

The wallet gateway is fully compatible with WooCommerce's High-Performance Order Storage. Top-up and refund flows query the correct order tables automatically.

Settings

Under Auctions → Settings → Payments → Wallet plus the wallet gateway's own settings at WooCommerce → Settings → Payments → Wallet:

Common questions

"Where do top-up funds physically live?"

In your standard WooCommerce gateway account (Stripe, your bank, etc.). The customer's wallet balance is a liability in your books — money you owe them, recorded in the ledger.

"Is this an e-money / EMI license requirement?"

In some jurisdictions, yes. Holding customer money is a regulated activity. Consult legal counsel — the plugin provides the technical infrastructure (immutable ledger, audit log, KYC integration) but compliance is your responsibility as the operator.

"Can I disable the wallet entirely?"

Yes — turn off the master switch in Settings → Payments → Wallet. The wallet endpoints disappear from My Account and the wallet gateway is removed from checkout.

"How do I migrate an existing wallet system?"

Use Tools → Maintenance → Migrate from legacy wallet. It imports balances and transaction history from the old format with a dry-run preview.