End-to-end flow for cart checkout payment initiation, gateway handoff, and async order finalization.

Cart Checkout Payment Flow

Overview

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

Cart-eligible product types: course, digital_book
Checkout initiation endpoint: POST /api/orders/checkout
Mobile-composed endpoint: POST /api/mobile/orders/checkout
Training products are not cart-eligible and use POST /api/mobile/training/enroll

Checkout initiation is synchronous. Payment finalization is asynchronous.

Request and Response Contract

All responses are wrapped in ResponseDto.

Checkout request body

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

Checkout initiation response (`200 OK`)

{
  "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",
    "tax_amount": "0.00",
    "total_amount": "1300.00",
    "transaction_uuid": "9001-1774884775940",
    "product_code": "EPAYTEST",
    "product_service_charge": "0.00",
    "product_delivery_charge": "0.00",
    "success_url": "https://api.example.com/api/payments/redirect/9001/success",
    "failure_url": "https://api.example.com/api/payments/redirect/9001/failure",
    "signed_field_names": "total_amount,transaction_uuid,product_code",
    "signature": "Tgk0luEqSxFj7qTrTs4w2zT61P1oM8oq+cm289bwgtU="
  }
}

End-to-End Flow

Checkout-Specific Edge Cases

Edge case	Behavior
Empty cart	Checkout request is rejected before payment initiation.
Cart contains non-digital item	Request fails because cart allows only `course` and `digital_book`.
Same idempotency key replayed	Returns same initiated result, prevents duplicate order creation.
Replayed payment success for the same order	Access grant logic skips extension when `product_access.orderId` already matches that order.
Gateway callback amount mismatch	Redirect verification rejects update with amount mismatch error.
Customer abandons gateway payment	Auto-cancel job closes unpaid order after timeout window.

apps/fumadocs/content/docs/developer/payment/course-booklet-flow.mdx
apps/fumadocs/content/docs/developer/payment/training-enrollment-flow.mdx
apps/fumadocs/content/docs/developer/order/api.mdx
apps/fumadocs/content/docs/developer/order/backend.mdx
apps/fumadocs/content/docs/developer/cart/feature.mdx
apps/fumadocs/content/docs/developer/cart/backend.mdx

Cart Checkout Payment Flow

On this page