0028 — Paid but out of stock: credit the captured amount to Shopping Credit¶
Status: accepted for implementation (2026-10-30). Owner decision. Applies only to a gateway payment that the provider has confirmed as captured and for which the order then cannot be created because the item has run out of stock.
Context¶
CommitOrderFromIntent (ADR 0005 payment-intent pipeline) turns a verified gateway payment into an order. Its stated invariant was that a paid customer always ends with an order and that the code never refunds behind their back. A stock failure at that moment (another customer took the last unit between payment and commit) left the intent in commit_retry_pending, retried until attempts ran out, then parked for a human — a customer with captured money, no order and no resolution.
The owner decided: no automatic gateway refund for this case; credit the captured amount to the customer's existing Shopping Credit, exactly once; never mark the order confirmed; keep the customer's statutory refund rights intact.
Decision¶
Eligibility (all required)¶
- the intent is
provider_confirmed/commit_retry_pending(the provider re-query already verified capture, provider, merchant reference, INR and the exact gateway amount); - it carries a provider payment reference,
confirmed == expected gateway amount, andcredits + gateway == quoted total; - no order exists for it, and the provider payment is not already attached to an order or credited to any wallet ledger row;
- the commit failed with
OUT_OF_STOCK,INSUFFICIENT_STOCK, or - added by the owner on 2026-10-30 (migration 118) -PRODUCT_UNAVAILABLEbecause the product itself was made inactive (shop_items.is_available = FALSE, recorded as reasonPRODUCT_INACTIVE). A disabled category is also covered since 2026-10-30 (migration 119, reasonCATEGORY_INACTIVE). A vanished product, a re-priced cart or any other error is not covered and stays in the existing retry queue for staff. An inactive product before capture never gets an intent: quote and intent creation refuse it.
Failed, pending, unverified, duplicate, cancelled and fulfilled cases never reach this path.
What is reused (nothing invented)¶
- the credit is an ordinary
wallets.shopping_creditsincrement plus an ordinarywallet_ledgerrow (txn_type = 'refund', which the app already renders as a credit and which classifies asrefund_restore), taggedreference_type = 'stock_recovery',reference_id = intent id, with the gateway references; - no new wallet, credit type or parallel ledger.
Protocol (two durable steps)¶
A. record a payment_stock_recoveries row (pending) — unique per intent and per (gateway, gateway_payment_id);
B. one transaction: lock intent → recovery → reservation → wallet; re-check eligibility and double-compensation; credit wallet + ledger; mixed payments: release the selected-credits hold (it was never debited) and credit only the gateway amount; recovery → completed; intent → stock_credited; audit; accounting journal when the engine is on.
A failure in B leaves the pending row and the intent in the paid region; the payment maintenance loop (stock_recovery pass, and the existing reconcile worker) retries. If stock has returned by then the customer gets their order and the recovery becomes superseded. A repeated webhook, retry, concurrent worker or restart replays the completed result and moves no money.
Duplicate-credit defences¶
UNIQUE(intent_id), UNIQUE(gateway, gateway_payment_id) on the recovery table; partial UNIQUE(reference_id) WHERE reference_type='stock_recovery' on wallet_ledger; the recovery row is locked FOR UPDATE; completed replays. A payment already attached to an order or credited elsewhere is parked as blocked and credits nothing.
Customer experience¶
Confirm/commit answers HTTP 422 STOCK_CREDITED (not 200, so no client can read it as an order; not 409/402, which the app treats as payment mismatch / "nothing charged"). Message: "Your payment was successful, but the item became unavailable. ₹X has been added to your Shopping Credit." A recovery still pending answers the existing truthful COMMIT_PENDING. The credit appears in the normal wallet balance and transaction history. The existing refund/help routes are untouched and Shopping Credit is not presented as a condition of any refund right. The app source understands the new outcome; an Android release is required for the native UI, and older builds already show the server's message.
Admin¶
Read-only Stock-failure credits page (GET /admin/stock-recoveries): payment captured → stock failed → pending / completed / blocked / superseded, amounts, provider payment reference, ledger reference, retries and errors. No contact or card data; no issue/edit/retry control.
Accounting and tax — NOT decided here¶
- No sale, revenue, COGS or GST is booked: no order exists, so the automatic sales-invoice hook never runs and no invoice is issued.
- With the journal engine off (production today) nothing is posted. When on, the cash leg is posted like a verified top-up: Dr Payment Gateway Clearing / Cr Wallet Liability (
wallet,stock-recovery:<intent>).
Open decisions (CA / counsel)¶
- Is "Dr Gateway Clearing / Cr Wallet Liability" the right treatment, and is it a supply of vouchers/advance with GST consequences (time of supply on an advance later applied to a different item)?
- Whether, and when, GST on the original payment must be reconsidered if the credit is never spent or is later refunded to the bank.
- Whether Shopping Credit may expire, and whether unspent recovery credit must be refundable to the original source on request (consumer-law position). The system does not waive any refund entitlement; the customer's existing refund request/help path is unchanged.
- (Resolved) a disabled category after capture is credited like an inactive product. A product that no longer exists, or a re-priced cart, is still retried and never auto-credited.
- A staff refund made directly in the gateway dashboard cannot be seen by this system before the credit posts; operational procedure should require checking the Stock-failure credits page first.
Rollback¶
scripts/postgres/rollback/rollback_117.sql (refuses while any intent is stock_credited; export payment_stock_recoveries first). Wallet credits already posted are real balances and are not reversed. Redeploy the previous backend image first.