02 · Webhooks → PaymentEventProcessor: accepted events, writes, emails, rejections (14 Oct 2026) Diagram

Wallet top-ups (D74, D75, D76, D79)

Top-up keys come only from server-created metadata: Stripe Checkout Session and its PaymentIntent (payment_intent_data.metadata), Razorpay order notes. Browser payment.notes are not read. Sources: RazorpayWebhookAdapter.ts L106-110, L155-158; StripeWebhookAdapter.ts L155; StripeProvider.ts L220.
Events: Stripe checkout.session.completed and payment_intent.payment_failed; Razorpay payment.captured and payment.failed. Each carries walletPurchaseId and cycle 0.
process() routes walletPurchaseId events to handleWalletTopup before the subscription gate. The customer chooses the top-up gateway, so the check is against WalletPurchase.provider and currency, not the subscription's country rule. Source: PaymentEventProcessor.ts L40-41, L78.
Succeeded: completes a pending, expired or failed purchase once, adds credits, redeems the coupon, sets invoiceNumber (WLT...) and paidAt. Failed: marks the purchase failed unless it is already completed. Source: wallet-payment-event.service.ts L34, L57, L146, L235.
Razorpay verify counts only captured; authorized returns 202 pending and the payment.captured webhook completes the purchase. Source: RazorpayProvider.ts L369; wallet.controller.ts L204.

Events that reach the processor

Stripe: setup_intent.succeeded (only with metadata.internalSubscriptionId) → TOKEN_SAVED, carrying the plan change if the setup was for one; payment_intent.succeeded / payment_failed with metadata.billingCycleNumber
Razorpay: payment.captured binds a new token to the subscription owner and fetches confirmed status; token.confirmed completes pending registration → TOKEN_SAVED. payment.captured / payment.failed also settle the durable debit attempt. token.cancelled / token.rejected → TOKEN_REVOKED.
A card added to a paid subscription (reason method_registration) stays an extra card and starts no charge, unless the subscription has no card at all (for example a migrated customer): then it becomes the default.
Failures also carry failureReason (Stripe decline_code, else code; Razorpay error_reason) and retryAttempt from the charge metadata
Dedupe: an event whose log row is processed is skipped; a failed row is processed again when the gateway redelivers it
India-issued Stripe card: detached, Payment Failed - Action Required sent, no event (StripeWebhookAdapter.normalize, setup_intent.succeeded branch)

What each handler writes and sends

Adapters and processor validate the subscription's country/gateway pair before token writes or auto-capture; successful payments must match currency. Mismatches fail explicitly. Sources: RazorpayWebhookAdapter.ts L32-43; StripeWebhookAdapter.ts L73-76; PaymentEventProcessor.ts L39-53.
Current-cycle outcomes release the charge lock after persisted settlement/failure; stale deliveries cannot release a newer charge. Uncertain signup debits retain persistent protection.
TOKEN_SAVED accepts only the stored gateway. Stripe queues a billing job: the current cycle's charge, or, for a setup that carries a plan change, that change's own charge (planChangeCharge) under a separate job ID. A Razorpay mandate cannot switch to Stripe. Stripe customers from before the migration are moved by the cutover script (D33, resolved in source, not yet run).
Trial conversion paid (reason trial_upgrade, sub a TRIALING or ENDED free-plan trial): one locked transaction records invoice + payment (cycle 1), applies the chosen plan, clears the trial flags, sets ACTIVE with the paid period starting now and the next renewal as cycle 2. Follow-up: renewal job scheduled, trial and grace jobs cancelled, payment-success email with the invoice PDF; admins get Payment Received; agents not kept are removed.
Reactivation paid (reason reactivation, sub CANCELLED): plan applied, ACTIVE, new period from the payment, cycle +1, grace cleared. A late renewal paid while PAST_DUE or PENDING_REAUTH also starts its period at the payment date.
Upgrade paid (reason upgrade): the plan, assets, price and discount (recomputed for the new price) are applied in one locked transaction; the recorded agents for removal are applied; a changed interval restarts the period and the renewal job; reminders are re-scheduled
Plan-change charge declined (reason upgrade, trial_upgrade or reactivation): no status change, no grace, no retry; email that the change did not happen (not for a Razorpay trial conversion or reactivation, which the customer watched in the popup)
Cycle 0 paid: lock coupon then subscription; record invoice/payment, redeem booking and count the actual discount once; PENDING_SETUP and active user commit together. Durable follow-up provisions org/IAM and sends the existing 3 onboarding emails.
Cycle 0 failed: PAYMENT_FAILED; Payment Failed - Action Required only when it first enters PAYMENT_FAILED; no automatic retry
Renewal paid: ACTIVE, period from the old end + intervalDays (from the payment date if it was paid late), cycle +1, pending price and its discount promoted, next job, lifecycle and retry jobs cancelled, reminders re-scheduled, Payment Successful with the invoice PDF attached
Same external payment: one invoice/payment only. Different payment for a settled cycle: record money without applying the cycle or discount allowance again. Refunds are not allowed.
Cycle ≥ 1 failed: PAST_DUE; on the failure that enters PAST_DUE: email, grace deadline (expiryDate) + warnings + final job, mandate reminders on a breach; retry n+1 (max 3, 3 days apart) only for a temporary reason; a manual-retry failure schedules nothing
Normal settlement invoice: subtotal = paid amount + actual charged discount, discountAmount = snapshot, total = paid amount; no tax split.

Fixed on this path

D44 resolved 8 Oct 2026: the payment.authorized capture call (400 on every logged event, Razorpay already captures automatically) is removed; payment.captured records the payment.
D21 resolved: the legacy StripeEventLog table and its cleanup schedule are removed; WebhookEventLog is kept and not pruned.
D57 resolved: POST /verify-payment binds the order and the Razorpay customer to the posted subscription, as the webhook path does.
D76 and D77 resolved: a decline can no longer overwrite a completed top-up, and a coupon slot is released exactly once (success decides from the status its own update completes; a checkout-creation failure ends the purchase and releases the slot in one transaction).