Recharge / Top-up
How customers add money to their wallet. Built on a special WooCommerce product called Recharge Your Wallet.
Setting up?
Skip to Recharge Settings for the step-by-step admin tab walkthrough (preset chips, min/max, auto-complete, bonus %).
What It Does
| For | Means |
|---|---|
| Customer | Pick a preset amount or type a custom one → pay → wallet credited automatically when the order completes |
| Admin | Standard WC checkout flow. Any payment gateway works (Stripe / PayPal / COD / etc.). One product handles all top-ups |
How Customers See It
On /my-account/my_wallet/ (or /wallet-central/add-to-wallet/):
- Add money panel
- Pick a preset chip (
₹100 / ₹500 / ₹1000 / ...) or type a custom amount - See the live "You'll pay" total + bonus preview if active
- Click Add to Wallet → standard checkout
- Pay normally with any gateway
- Order completes → wallet credited (with bonus if enabled)
The Wallet Central version of the same form lives at /wallet-central/add-to-wallet/:
The Recharge Product
Auto-created when you activate the plugin: Recharge Your Wallet.
You can edit description, image, gallery, and SEO normally. Don't change the product type — it's what triggers the auto-credit.
If the product goes missing (rare): WooCommerce → Status → Tools → Wallet → Recreate recharge product.
Settings
Wallet → Settings → Recharge
| Setting | Default | What it does |
|---|---|---|
| Preset chips | 100, 500, 1000, 2500, 5000 | the 6-grid of one-tap amounts |
| Min top-up | 50 | smallest amount allowed |
| Max per order | 25000 | largest single top-up |
| Allow custom amount | ON | toggle off to lock customers to presets |
| Auto-complete recharge orders | ON | flips orders to completed automatically when only recharge items |
| Bonus enable | OFF | the optional +5% extra-credit promo |
| Bonus percent | 5 | the percentage when bonus is on |
Auto-Complete
By default, an order containing only the recharge product flips to completed automatically — saves admin from manually approving a top-up before the credit lands.
If the cart mixes recharge with normal goods, auto-complete is skipped (you wouldn't want store credit issued before the goods ship).
Bonus
Optional. Set a percentage on top of every top-up.
The Add money panel shows a live preview:
💚 Offer: Get 5% Extra Credit on every Top-up! Pay ₹1000 and get ₹1050 in your wallet.
See Deposit / Top-up Bonus for the full feature.
Common Scenarios
Run a flash promo with double bonus
Enable bonus, set to 10 for the campaign window, change back to 5 after. Or use a small filter to time-box (see dev section in Deposit / Top-up Bonus).
Disable preset chips, force custom only
Set "Preset chips" to empty. Customer types any value within min/max.
Lock customers to preset only
Set "Allow custom amount" → OFF. Customer can only pick a chip.
Embed top-up form on a landing page
Drop the shortcode anywhere:
[wkwp_wallet_recharge presets="100,500,1000" min="50" max="10000"]
See Shortcodes.
Refund / Cancel a Recharge
| Action | Effect on wallet |
|---|---|
completed → refunded | wallet debited the credited amount + bonus |
| Order cancelled | nothing — credit only applies on completed |
| Partial refund | wallet debited the partial amount only |
Reversal protection — never debits below zero. If BNPL is enabled and the customer's already spent the credit, the shortfall becomes a BNPL debt instead.
When Something Goes Wrong
| Problem | Fix |
|---|---|
| Recharge product missing | Status → Tools → Recreate recharge product |
| Order completed but balance not credited | Recharge product type was changed away from the wallet type — edit the product → set type back |
Customer charged but order stuck on processing | Auto-complete disabled, or cart had non-recharge items mixed in. Manually flip to completed |
| Custom amount input rejected | Min / max settings — check the Recharge tab |
For developers — top-up + bonus internals
Auto-credit flow
Hooked on woocommerce_order_status_completed priority 10:
- Iterate order line items
- Skip non-recharge products
- Read the customer-typed amount from cart meta
- Compute
total = amount × quantity(always 1 for top-ups) - Apply bonus:
credited = total × (1 + bonus_pct / 100)if bonus on and not already credited - Call
WKWP_Wallet_Core::credit() - Mark
_wkwp_topup_credited = yesorder meta to guard against double credit - Email customer (if Wallet credit notification on)
Hooks
| Hook | Type | When |
|---|---|---|
wkwp_wallet_topup_amount | filter | mutate amount before credit |
wkwp_wallet_topup_bonus | filter | mutate bonus % per order |
wkwp_wallet_topup_completed | action | after credit row written |
wkwp_wallet_topup_reversed | action | refund / cancel reversal |
Block editor
Each shortcode is also a Gutenberg block — no string typing needed.