A safer checkout flow

Checkout touches money, inventory, and order state, so the client keeps the flow simple and the backend keeps the final say.

1. Create or load cart
2. Review server checkout readiness
3. Submit one idempotent checkout
4. Backend verifies actor and ownership
5. Backend prices and validates cart
6. Backend debits wallet and finalizes order
7. Listen for checkout completion

Before placing the order#

Use checkoutReadiness(input) to show whether the server sees any blocking reasons. This is a helpful preview, not a reservation: stock and wallet balances can change before checkout reaches the backend.

Submit once#

Call checkout with a stable cart, user, shipping address, and wallet payment method. The SDK prevents a second simultaneous checkout for the same cart in one instance and sends x-idempotency-key on every attempt.

If the response is lost, retry the unchanged payload. The client reuses its generated key while it remains alive. For retries after a page reload or process restart, create and persist an idempotency key in your application and pass it explicitly.

What the backend locks#

The backend verifies the JWT actor matches the requested user, validates cart ownership, claims the idempotency key in MongoDB, and rejects a duplicate while the original is processing. The database's unique (key, userId) index is the cross-instance lock. A duplicate request must not release another request's active claim.

The backend calculates totals and performs payment/order transitions. Never use client-supplied prices or readiness results as proof that a payment is valid.