API-first.
Boring by design.
Create an order, redirect to checkout, receive authoritative confirmation. Keep your systems in sync without guessing what happened.
Single source of truth
Orders drive the system. UIs don’t confirm payments — events do.
Webhook authoritative
Payment status comes from verified events, not front-end redirects.
Minimal surface
Small API surface. Clear behaviour. Fewer edge cases.
The shape of the integration
1) Create order
POST /api/checkout/session
{ merchantId, product, quantity }2) Redirect
→ checkoutUrl /checkout/:orderId
3) Confirm via events
POST /api/webhooks/stripe (payment_intent.succeeded)
4) Update your system
Order: PENDING → PAID Notify / Fulfil / Ship
You can start with a redirect checkout and grow into deeper integration later — without changing the mental model.
Build fast. Stay correct.
Keep the checkout experience clean. Let events confirm the truth.