End-to-end order checkout payment initiation, gateway handoff, and async order + inventory finalization.

Cart Checkout Payment Flow

Overview

Cart checkout is the payment path for a user's active cart.

Checkout endpoint: POST /api/orders/checkout
Mobile-composed endpoint: POST /api/mobile/orders/checkout

Checkout initiation is synchronous; payment finalization is asynchronous via queue workers.

Checkout Request

{
  "gateway": "esewa",
  "returnUrl": "https://example.com/payment/return"
}

Payment-Init Response (`200`)

{
  "orderId": 101,
  "status": "payment_pending",
  "paymentId": 9001,
  "gatewayTransactionId": "9001-1774884775940",
  "initiationType": "form_post",
  "redirectUrl": "https://rc-epay.esewa.com.np/api/epay/main/v2/form",
  "gatewayPayload": {
    "amount": "1300.00",
    "total_amount": "1300.00",
    "transaction_uuid": "9001-1774884775940"
  }
}

Sequence

Inventory Coupling

Checkout/buy-now creates reservation outbox events (stock.reserve).
Payment success emits finalize outbox events (stock.finalize).
Payment failure/cancel/expiry emits release outbox events (stock.release).

Edge Cases

Edge Case	Behavior
Empty cart	Request rejected before initiation
Idempotency replay	Existing initiation result returned; duplicate order prevented
Callback amount mismatch	Verification fails; status not marked completed
Gateway abandonment	Auto-cancel closes unpaid order after timeout

apps/fumadocs/content/docs/developer/order/api.mdx
apps/fumadocs/content/docs/developer/order/backend.mdx
apps/fumadocs/content/docs/developer/cart/feature.mdx

Cart Checkout Payment Flow

On this page