Why Stripe Connect
When we decided to add card payments to NextFlow, the question was not whether to use Stripe — it was which Stripe product. Connect is the platform model: your customers (our users) receive the money into their own Stripe accounts. We are just the software layer.
The alternative was a payfac model where we hold the money and pay out. Faster to build, but we would need to obtain money-transmitter licences in every territory we operate in. For a small team, Stripe Connect was the obvious call.
Connect gives you legal simplicity. In return, Stripe takes a platform fee on every transaction and the onboarding UX is more complex than a simple checkout.
What broke at 2am
Three months after launch, we had a webhook processing bug. Stripe sends payment events to our endpoint; we update the lead record. A deploy introduced a silent failure in our idempotency key generation — the same payment event was being processed twice, creating duplicate payment records in the UI.
Nobody noticed for 6 hours because the actual money movement was correct. Only the display was wrong. But that is enough to shake user trust. We now run a nightly reconciliation job that compares our database against the Stripe API.
// Idempotency key: stripe event id + internal user id
// Never use timestamp — not unique enough
const key = `${event.id}::${userId}`;What we would do differently
- Build the reconciliation job on day one, not after the incident
- Use Stripe's test clock feature for end-to-end payout testing before launch
- Webhook retries need their own dead-letter queue — do not rely on Stripe resending
- Surface the Stripe Dashboard link directly in the NextFlow UI so users can self-serve
Overall, Stripe Connect was the right call and remains so. The developer experience is excellent, the documentation is thorough, and the fraud tooling we get for free is worth the platform fee many times over.