Buy Now Pay Later (BNPL)
Let approved customers check out using the wallet gateway even when their balance can't cover the order. The shortfall becomes debt; auto-deducted from any future wallet credit.
Setting up?
Skip to BNPL Settings for the step-by-step admin tab walkthrough (eligibility mode, debt cap, repayment days, interest).
Pilot feature
BNPL is the highest-risk feature in the plugin. Roll it out to a small whitelist first. Pair with KYC + transaction limits.
What It Does
| For | Means |
|---|---|
| Customer | Checkout normally even at zero balance. Repay later from any wallet credit (cashback, refund, top-up) |
| Admin | Optional revenue stream from interest. Hard caps per customer. Whitelist or KYC-gated. Full audit trail |
How Customers See It
When the customer picks Pay with Wallet at checkout and balance is short:
- Eligible customer → checkout proceeds. Wallet drops to 0; shortfall recorded as debt
- Not eligible → standard "insufficient balance" error → prompted to top up or split-pay
A later visit to My Wallet shows an Outstanding card with debt rows + a Repay button per row.
The hero card and recent activity reflect the running balance + every BNPL repayment as a row:
Setup
Wallet → Settings → BNPL
| Setting | Default | What it does |
|---|---|---|
| Enable | OFF | global toggle |
| Eligibility mode | whitelist | how customers get into the BNPL pool |
| Eligible users | empty | the whitelist (used in whitelist mode) |
| Eligible roles | empty | role list (used in role mode) |
| Max debt per user | 1000 | hard cap so you don't over-extend |
| Min order to qualify | 100 | small carts skip BNPL |
| Repayment days | 30 | window before "overdue" |
| Interest type | none | none / fixed / percent |
| Interest amount | 0 | value when interest is on |
| Grace days before interest | 7 | days past due before interest accrues |
Eligibility Modes
| Mode | Logic |
|---|---|
whitelist | only listed users can use BNPL |
role | any user with a listed role |
all_kyc_approved | any KYC-approved customer |
Plus all modes also require:
- Cart total ≥ "min order to qualify"
- Existing debt + new shortfall ≤ "max debt per user"
Repayment
Two ways debt gets paid down:
Auto-deduct (default)
Any wallet credit (cashback, top-up, refund, transfer received) automatically applies to the oldest debt first. No customer action needed.
If the customer wants to opt out, toggle _wkwp_bnpl_auto_deduct per-user — the plugin then waits for manual repayment.
Manual repayment
Customer's My Wallet → BNPL panel → per-row Repay button → typed amount → submits → wallet debited, debt reduced.
Interest
Optional. Computed only on view (not pre-calculated):
days_late = today - (due_date + grace_days_before_interest)
interest =
none → 0
fixed → flat amount per overdue row
percent → principal × pct/100 × (days_late / 30)
Overdue Handling
Daily cron marks rows where today > due_date as overdue. Customer gets a reminder email per debt (rate-limited to one per week).
Admin can write off a debt manually from the row drawer (one-click → outstanding → 0).
Risk Controls (recommended)
| Control | Where |
|---|---|
| Require KYC | add wallet_usage to KYC required features |
| Hard cap per customer | "Max debt per user" |
| Whitelist only | eligibility mode = whitelist + manual additions |
| Block withdrawal during outstanding | filter the withdrawal-eligible flag |
Common Scenarios
Pilot with 5 trusted customers
Whitelist mode + manually add 5 user IDs + low max-debt cap (500). Watch for a month, expand if healthy.
Convert all KYC-approved customers
Eligibility mode = all_kyc_approved. New approvals automatically join the BNPL pool.
Charge late-payment fee only
Interest type = fixed, amount = 50, grace days = 7. Customer hit with flat ₹50 each week past due.
Write off a debt for goodwill
Open the row in admin → "Write off" button → outstanding → 0, status → repaid, audit row written with admin name.
When Something Goes Wrong
| Problem | Fix |
|---|---|
| Eligible customer not offered BNPL | Cart below min; existing debt + new amount > cap; KYC gate active |
| Auto-deduct not firing | Customer opted out of auto-deduct; or hook order conflict |
| Interest looks wrong | Grace days config; interest type config |
| Overdue email sent more than once a week | Built-in rate-limit is once per debt per week — third-party hook may be duplicating |
For developers — hooks + reporting
Hooks
| Hook | Type | When |
|---|---|---|
wkwp_bnpl_eligible | filter | gate eligibility per cart |
wkwp_bnpl_debt_created | action | new debt row written |
wkwp_bnpl_repaid | action | a debt hits zero |
wkwp_bnpl_overdue | action | row marked overdue |
wkwp_bnpl_interest_calculated | filter | mutate interest amount per row |
wkwp_bnpl_max_debt_per_user | filter | per-user override |
Reporting
| KPI | Source |
|---|---|
| Total outstanding | sum across non-repaid debt rows |
| Overdue total | same with status = overdue |
| Customers in debt | distinct user count |
| Avg. days to repay | mean of repaid_at - created_at |
Surface on the Wallet Dashboard once BNPL is enabled.
Compatibility
- Subscriptions — renewal orders can use BNPL
- Refund-to-wallet — refunds first repay outstanding BNPL, surplus credits balance
- Withdrawal — KYC gate stops customers cashing out fresh credit while debt outstanding (configurable)