End-to-end payment flow for training enrollment requests with synchronous initiation and async payment finalization.

Training Enrollment Payment Flow

Overview

Training enrollment payment is a two-domain flow:

Training module validates enrollment context and creates/updates pending enrollment.
Order integration creates training order and initiates payment synchronously.
Redirect verification emits order jobs that finalize enrollment on payment success.

This flow is separate from cart checkout. For cart-based digital purchases, see payment/cart-checkout-flow.mdx.

Supported Purchase Method

Method	Endpoint
Training enrollment	`POST /api/mobile/training/enroll`

End-to-End Flow

API Contract Examples

All responses are wrapped in ResponseDto.

1. Enrollment request body

{
  "productId": 201,
  "cohortId": 10,
  "sessionId": 5,
  "promoCode": "TRAIN2026",
  "gateway": "esewa",
  "returnUrl": "https://example.com/payment/return",
  "formData": {
    "name": "Sita Shrestha",
    "email": "sita@example.com",
    "phone": "+9779800000000"
  }
}

2. Enrollment payment-init response (`200 OK`)

{
  "orderId": 123,
  "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": "2500.00",
    "tax_amount": "0.00",
    "total_amount": "2500.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 paid
- upserts training enrollment to enrolled
- increments cohort seat count once when a pending enrollment transitions to enrolled
- upserts matching product_access
- records promo usage when discount applied
order.payment_failed
- marks payment failure path and triggers retry when eligible
order.payment_retry
- verification-only retries with bounded attempts
order.auto_cancel
- auto-cancels unpaid training orders
orders_maintenance.cleanup_outbox
- scheduled maintenance job that removes old completed/failed rows from shared outbox_events based on retention config

Enrollment Access Behavior

Enrollment remains pending until payment success finalization.
On payment success, enrollment transitions to enrolled and binds to orderId.
Enrollment finalization is owned by the order processor path; the enroll endpoint itself only initiates payment.
accessType/accessValidUntil are derived from training validity settings.
Session content access remains blocked until enrollment is enrolled.

Edge Cases

Edge case	Behavior
Duplicate enrollment requests for same user/product	Idempotency + advisory lock prevent duplicate active enrollment creation.
Invalid promo or scope mismatch	Enrollment order creation rejects with promotion applicability error.
Cohort/session mismatch with selected product	Validation fails before order/payment initiation.
Payment timeout or user abandonment	`order.auto_cancel` runs; enrollment stays non-enrolled and content remains blocked.
Gateway callback arrives late after initial failure	Retry verification can reconcile to paid and complete enrollment transition.

apps/fumadocs/content/docs/developer/payment/cart-checkout-flow.mdx
apps/fumadocs/content/docs/developer/payment/course-booklet-flow.mdx
apps/fumadocs/content/docs/developer/training/api.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

Training Enrollment Payment Flow

On this page