Deposit / Top-up Bonus

A percentage bonus credited automatically on every successful top-up. Pure marketing lever — "Pay ₹1000, get ₹1100 in your wallet."

Setting up?

Bonus toggle + percent live under Recharge Settings → Bonus section.

What It Does

For	Means
Customer	Top up `₹1000` → wallet shows `₹1050` (with 5% bonus). Live preview banner on the Add money panel shows the bonus before paying
Admin	One toggle + percent value. Idempotent — bonus credited once per order even if order status flips

How Customers See It

On the Add money panel:

┌─────────────────────────────────────────────┐
│  💚 Offer: Get 5% Extra Credit on every     │
│     Top-up!                                 │
├─────────────────────────────────────────────┤
│  Custom amount  [   ₹1000   ]              │
│  You'll pay     ₹1000.00                   │
│  Bonus preview  Pay ₹1000 and get ₹1050    │
│                  in your wallet.            │
├─────────────────────────────────────────────┤
│  [ Add to Wallet ]                          │
└─────────────────────────────────────────────┘

The bonus preview updates live as the customer types.

Add money panel with the live bonus banner — preset chips, custom amount, You'll-pay row

Setup

Wallet → Settings → Recharge → Bonus

Deposit Bonus admin section — enable, percent, min top-up, max bonus

Setting	Default	What it does
Enable	OFF	global toggle
Bonus percent	`5`	the % credited on top of every top-up
Min top-up to qualify	empty	only top-ups above this amount earn bonus
Max bonus per order	empty	optional cap on bonus value

When OFF, the banner disappears and no bonus is credited — base top-up amount only.

Behaviour

When a recharge order completes:

Plugin reads each recharge line item
Computes topup × bonus_pct / 100, applies caps
Credits topup + bonus to the wallet
Marks the order so bonus can't credit twice

The bonus is embedded in the top-up audit row — single row, note explains the breakdown. Switch to a separate row via filter if your accounting prefers split rows.

Refund Reversal

When a top-up order is refunded:

Refund	Bonus effect
Full refund	total credited (base + bonus) debited
Partial refund	proportional debit
Order cancelled	nothing — bonus only fires on `completed`

Common Scenarios

Run a flash 25% bonus weekend

Bump percent to 25, run the campaign, drop back to 5. Customers see the new banner immediately.

Bonus only on top-ups above ₹500

Set "Min top-up to qualify" → 500. Smaller top-ups don't earn bonus and the banner hides for them.

Different bonus for VIP customers

Use a one-line filter (see dev section).

Auto time-boxed bonus

Build a small filter that returns a higher % during a specific date window (see dev section).

Reporting

Filter Wallet → Transactions for note containing bonus:

SELECT SUM(amount) FROM wp_wkwc_wallet_transactions
WHERE type = 'credit' AND note LIKE '%bonus%'
  AND created_at >= '2026-04-01';

Total bonus issued in any window.

When Something Goes Wrong

Problem	Fix
Bonus not credited	Feature enabled? Order has recharge line item? Order in `completed`?
Bonus credited twice	Should not happen — guard meta on order. File a bug ticket if reproducible
Live preview not updating	Browser console error; jQuery dependency missing in theme
Wrong bonus %	Filter chain — print the value from a debug shortcode

For developers — hooks + per-user override + time-boxed promo

Hooks

Hook	Type	When
`wkwp_wallet_bonus_amount`	filter	mutate % per user / order
`wkwp_wallet_bonus_credited`	action	after credit row written
`wkwp_wallet_bonus_split_row`	filter	render bonus as separate ledger row
`wkwp_wallet_bonus_min_topup`	filter	min top-up to qualify

Per-user override

add_filter( 'wkwp_wallet_bonus_amount', function( $pct, $user_id, $topup ) {
    if ( in_array( 'vip', wp_get_user_role_slugs( $user_id ), true ) ) {
        return 10; // 10% for VIPs
    }
    return $pct;
}, 10, 3 );

Time-boxed campaign

add_filter( 'wkwp_wallet_bonus_amount', function( $pct ) {
    $now = current_time( 'timestamp' );
    if ( $now >= strtotime( '2026-04-01' ) && $now < strtotime( '2026-04-15' ) ) {
        return 15; // double bonus during launch fortnight
    }
    return $pct;
} );

Idempotency

_wkwp_bonus_credited flag on order — prevents double-credit even when admin flips status.