End-to-end payment flow for course and booklet purchases via synchronous checkout/buy-now initiation.

Course & Booklet Payment Flow

Overview

This document covers the payment lifecycle for digital product purchases (course, digital_book) routed through the order module.

Checkout and buy-now now use synchronous initiation:

create order + payment record
return payment-init payload immediately (200 OK)
frontend initiates gateway
payment redirect emits order success/failure jobs
processor finalizes artifacts

Supported Purchase Methods

Method	Endpoint	Product types
Cart checkout	`POST /api/orders/checkout`	`course`, `digital_book`
Buy-now	`POST /api/orders/buy-now`	`course`, `digital_book`

Mobile-composed equivalents are available under /api/mobile/orders/....

End-to-End Flow

API Contract Examples

All responses are wrapped in ResponseDto.

1. Checkout request body

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

2. Buy-now request body

{
  "productId": 101,
  "gateway": "esewa",
  "returnUrl": "https://example.com/payment/return",
  "promoCode": "SUMMER2026"
}

3. Payment-init response payload (`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="
  }
}

Job Queue Flow

order.payment_success
- marks order as paid
- creates/upserts product_access for course and digital_book
- records promotion_usages when discount applied
order.payment_failed
- marks failed state and schedules retry pipeline when eligible
order.payment_retry
- verification-only retry (does not create a new order)
order.auto_cancel
- cancels unpaid orders after timeout window
orders_maintenance.cleanup_outbox
- scheduled maintenance job that removes old completed/failed rows from shared outbox_events based on retention config

Payment Retry Behavior

Automatic verification retries only (no manual customer retry endpoint).
Payload shape: { orderId, paymentId, attempt, maxAttempts }.
Delay schedule: attempt 1 = 1 min, attempt 2 = 5 min, attempt 3 = 15 min.

Access Grant Behavior

On successful payment:

course purchase -> upsert product_access for that course product.
digital_book purchase -> upsert product_access for that booklet product.
Replay handling is order-aware. If the same order's payment-success event is replayed, access validity is not extended again.

Edge Cases

Edge case	Behavior
Gateway payment fails/transient verification issue	`order.payment_retry` verification runs with bounded retries.
Repeated checkout/buy-now submission	Idempotency keys replay same response and prevent duplicate order creation.
Replayed `order.payment_success` for the same order	Access grant logic detects existing `orderId` and skips extension for that replay.
Buy-now request retried with changed request context	Returns idempotency mismatch conflict.
User never completes payment	`order.auto_cancel` closes unpaid order after configured timeout (`ORDER_AUTO_CANCEL_MINUTES`).
Callback reports amount mismatch	Redirect verification rejects update with `ORDER_PAYMENT_AMOUNT_MISMATCH`.

apps/fumadocs/content/docs/developer/payment/cart-checkout-flow.mdx
apps/fumadocs/content/docs/developer/order/api.mdx
apps/fumadocs/content/docs/developer/order/backend.mdx
apps/fumadocs/content/docs/developer/payment/architecture.mdx
apps/fumadocs/content/docs/developer/payment/browser-return-flow.mdx

Course & Booklet Payment Flow

On this page