Next.js and Stripe Connect: refunds across server actions and routes

Route handlers vs server actions for money

Server actions re-authenticate from scratch on every invocation — treat arguments as hostile, verify session and ownership before any Stripe call. Route handlers suit webhook receivers (signature verification lives naturally there). Mixing concerns across both is fine; trusting either implicitly is not.

The Edge/Node split

Signature verification runs happily on Edge; anything requiring node:crypto-backed secret material does not. Production architecture mirrors this: Edge receiver verifies and enqueues, Node workers do detection and recovery work. Local dev hides the boundary until deploy surprises you.

The silent env-var trap

Flags sourced from configuration (process.env.REVERSE_TRANSFERS === "true") fail closed when staging variables misspell names — refunds succeed, transfers strand, nothing logs. Hard-code true flags; reserve configuration for genuinely variable policy like floors.

// Fragile: config-gated correctness
const flags = process.env.CONNECT_REVERSALS ? {...} : {};

// Robust: correctness isn't configurable
await stripe.refunds.create({ charge, reverse_transfer: true, refund_application_fee: true });

RSC caching showing stale amounts

Cached components rendering amount_refunded predate reversals landing elsewhere. Route from cached views; decide from fresh fetches at action time — the payload-staleness lesson wearing frontend clothing.