Refund to Wallet

Two flows. Both end in money landing back in the customer's wallet.

Setting up?

The customer-side request queue settings live on Wallet → Settings → Refund Requests — see the Admin Settings index. Wallet gateway "Refund back to wallet" toggle lives under Checkout Settings.

What It Does

For	Means
Customer	Refunds arrive instantly as wallet credit instead of waiting on bank reversal. Or proactively request a refund-to-credit
Admin	Keep the cash in-store. Customers spend the credit on the next order

Refund Settings admin section — global toggle, default reason list, auto-credit

Two Modes

A. Admin-direct refund

Admin issues a WC refund on a wallet-paid order → wallet credited automatically.

Behaviour controlled by the wallet gateway's "Refund back to wallet" toggle:

ON (default) → wallet credited the refund amount when method was wallet
OFF → refund goes back to the original method (card, PayPal, etc.)

Override per-order on the order edit screen → side meta-box → "Force refund to wallet".

B. Customer-requested refund

Works on any order (wallet-paid or otherwise). Customer asks; admin approves or rejects.

How Customers See It (mode B)

My Account → Orders → click an eligible order
Request refund to wallet button
Type amount + reason + optional note
Submit → status pending

Admins review pending requests in Wallet → Refund Requests:

Refund Requests queue — pending customer-submitted refund requests with Approve / Reject

Refund credits show up in the customer's activity feed alongside everything else:

Recent activity card — refund rows iconised, dated, balance-after recorded

Eligible only when:

Order is in completed status
Within your refund window (default 14 days)
Not already refunded
Customer's KYC is approved (if you've gated it)

Admin Review (mode B)

Wallet → Refund Requests lists all rows.

Each pending row has a side drawer with:

Order details (line items, total, payment method)
Requested amount + reason + note
Customer wallet balance preview after credit

Approve flow:

Admin confirms the amount (can edit downward — partial refund)
Optional: tick "also create WC refund (origin payment method)" — splits the refund: half to original card, half to wallet
Click Approve
Wallet credited
Customer email fires

Reject flow:

Admin enters required note (shown to customer)
Status flips to rejected
Customer email fires

Setup

Wallet → Settings → Refund Requests

Setting	Default	What it does
Enable	OFF	global toggle
Refund window (days)	`14`	how long after order completion request is allowed
Max requests per order	`1`	usually one is enough
Reason required	OFF	force customer to pick from `damaged` / `wrong_item` / `not_as_described` / `other`
Eligible statuses	`completed`	only completed orders allow a request

Status Pills

Status	Meaning
`pending`	submitted, awaiting admin
`approved`	wallet credited
`rejected`	admin declined; admin note shown to customer

Common Scenarios

Customer's order arrived damaged

Customer submits a refund request from My Account with reason damaged. Admin approves; wallet credited; customer spends on a replacement.

Refund original card AND give credit (partial)

When approving the request, tick "also create WC refund". Plugin issues a partial WC refund + a partial wallet credit. Use for goodwill compensation.

Block customers from requesting refunds

Toggle "Enable" → OFF. Existing flow (admin-direct refund-to-wallet on wallet-paid orders) still works.

RMA Pro / Smart Refunder integration

When WooCommerce RMA Pro is detected, the bridge auto-routes RMA-approved refunds through wallet credit when the original payment was wallet. Toggle the bridge under Integrations Settings.

Cashback / Bonus Reversal

Approving a refund request does not automatically reverse cashback or top-up bonus from the original order. To do that, also issue a "Refund order" in WC admin — that's the trigger for cashback reversal logic.

If you want refund-request approval to also reverse cashback, see the dev section below for a 4-line hook.

When Something Goes Wrong

Problem	Fix
Request button not visible	Order status not eligible; outside refund window; KYC gate active
Wallet not credited on approve	Amount was zero or negative — should not happen via UI; check for custom filters
Customer sees no email	WC mailer down; check `WC → Status → Logs → emails`
Cashback not reversed on approve	Expected — see note above; hook into the action to bridge

For developers — hooks + cashback bridge

Hooks

Hook	Type	When
`wkwp_refund_request_eligible`	filter	gate visibility of the customer-side button
`wkwp_refund_request_submitted`	action	new request row written
`wkwp_refund_request_approved`	action	wallet credited
`wkwp_refund_request_rejected`	action	rejection email about to fire
`wkwp_refund_to_wallet_amount`	filter	mutate amount on admin direct refund

Bridge approval into cashback reversal

add_action( 'wkwp_refund_request_approved', function( $request_id, $order_id ) {
    do_action( 'woocommerce_order_partially_refunded', $order_id, 0 );
} );

Triggers the standard WC refund hook — cashback engine reverses proportional credit.

Audit

Approved request writes one ledger row tagged refund_request:#<id>.