Stripe expects merchants to handle disputes, refunds, and chargebacks responsibly. Dispute rates above their threshold get accounts restricted or closed. Ahead of commercial launch, that's not something to punt on.
The initial Stripe integration only handled one webhook event -- the successful checkout. This work extended it to six, covering the full dispute arc: early fraud warnings, disputes created, disputes updated, disputes closed, and charges refunded. Along with the handlers came a dispute events table, an admin Lambda with credit lookup and action endpoints, a Billing section in the dashboard with dispute evidence panels, and a 350-line operating procedure.
Early fraud warnings
The most valuable of the new handlers is the one for Radar Early Fraud Warnings. Stripe's fraud scoring sometimes flags a charge after it's been authorized but before any dispute has been filed. Merchants get an event. If you proactively refund at that point, the charge never becomes a dispute, you avoid the fifteen-dollar dispute fee, and it doesn't count against your dispute rate. The handler fires an automatic refund, deducts the credits, logs the event, and moves on. Stripe's own docs recommend this pattern.
Two admin actions
Not every fraud flag is actionable without a human, and not every dispute is fraud. Two admin actions sit on top of the automatic flow:
- Refund as Fraud: reverses the charge with Stripe, deducts credits, logs the event.
- Refund and Disable: same, plus suspends the user record, disables the Cognito account, and optionally sends a notification email.
The email wording is deliberately vague. Stripe's best-practices docs are clear that you should never tell a user how fraud was detected (you give the next fraudster a playbook) and should avoid accusatory language (false positives create defamation risk). The notification is opt-outable per action for cases where tipping off the user is worse than silence.
Testing the close paths
The lost-dispute path was straightforward to test with a Stripe test card. The won-dispute path was harder: Stripe's test mode doesn't reliably auto-resolve disputes, so waiting for a real close could mean hours. I built a small helper that signs synthetic webhook events with the real webhook secret and POSTs them to the live endpoint. The handler can't tell synthetic events from real ones because the signature is valid, which lets the entire close-handler code path get exercised in seconds.
The operating procedure
A written procedure for fraud response, rendered inline in the dashboard via the existing markdown pipeline. It covers when to act and when not to, a decision tree between the admin actions, customer communication templates, evidence collection checklists, and edge cases. Admin-authenticated, so the playbook isn't discoverable by reading page source.