Audience: Mobile/web frontend developers Scope: Checkout, payment, order endpoints

Order Module - API & Integration Guide

1. How to Read / Quick Metadata

• Module: Order
• Auth models:
  • Customer/mobile routes: JwtAuthGuard
  • Admin routes: JwtAuthGuard + RoleGuard + @Permissions(...)
• Primary base URLs:
  • Customer: /api/orders
  • Mobile-composed customer: /api/mobile/orders
  • Admin: /api/admin/orders
  • Payment redirect callbacks: /api/payments/redirect/:paymentId/success|failure
• Response envelope: successful endpoints return ResponseDto<T>
• Swagger tags used by controllers:
  • Orders (Mobile)
  • Orders (Admin)

2. High-Level Overview

Order API is split into:

• synchronous payment-initiation endpoints (checkout, buy-now) returning gateway payload immediately
• synchronous read endpoints (list/detail/request-status)
• async command endpoints for cancellation and admin refund processing

Payment verification is completed through redirect callbacks, then finalized by queue workers.

Buy-now product behavior:

• Physical product types (thangka, singing_bowl, statue, jewellery) are supported and create orderType: "physical".

3. Core Concepts and Terminology

• order: primary transaction entity (order table)
• order item: line-level monetary snapshot (order_item table)
• status history: append-only transition log with actor provenance (order_status_history)
• async request: command-tracking record for async mutations (async_request)
• outbox event: durable dispatch record for background jobs (outbox_event)
• payment-init response: payload containing initiationType, redirectUrl, and gatewayPayload

Current async order jobs:

• order.payment_success
• order.payment_failed
• order.payment_retry
• order.cancel
• order.process_refund
• order.auto_cancel

Current queue payload contracts:

Transactional notification routing events used by order flow:

• ORDER_PLACED_CHECKOUT, ORDER_PLACED_BUYNOW
• ORDER_PAYMENT_RECEIVED_CHECKOUT, ORDER_PAYMENT_RECEIVED_BUYNOW
• ORDER_PAYMENT_FAILED, ORDER_CANCELLED
• ORDER_REFUND_REQUESTED, ORDER_REFUND_APPROVED, ORDER_REFUND_REJECTED

Order-to-inventory outbox events emitted by lifecycle stage:

• stock.reserve after checkout/buy-now order creation
• stock.finalize after verified payment success
• stock.release after payment failure, cancellation, or expiry

Outbox/queue lifecycle for inventory coupling:

1. Order service writes outbox_events with targetQueue for inventory processing.
2. Outbox dispatcher claims pending inventory-target rows only from its owned queue set.
3. Dispatcher enqueues reserve/finalize/release inventory jobs.
4. Inventory processors mutate stock state and acknowledge job completion.

Delivery channels for transactional events:

• push (mobile_push, in-app targets)
• email (template-based renderer output)

4. Route Summary

4.1 Customer / Mobile

Mobile-composed equivalents are available under /api/mobile/orders/.... GET /api/orders/requests/:requestId is for async operations (for example cancel/refund processing), not for checkout/buy-now initiation.

4.2 Admin

4.3 Payment Redirect and Result

Route Details

Checkout

Get Orders

5. Query Parameters

5.1 Customer list (GET /api/orders)

5.2 Admin list (GET /api/admin/orders)

6. Response Shape Examples

6.1 Checkout request

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

6.2 Buy-now request

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

6.3 Payment-init 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="
  ""
"

6.4 Async request status response

"
  "requestId": "cancel_9f67c1bc67694347b6509e1ee1277f49",
  "status": "completed",
  "result": "
    "orderId": 101,
    "orderStatus": "cancelled",
    "paymentStatus": "failed",
    "correlationId": "order_cancel_user_abc_79f9c2fa11a7"
  "",
  "createdAt": "2026-03-10T10:00:00.000Z",
  "completedAt": "2026-03-10T10:00:05.000Z"
"

6.5 Admin status history item (actor provenance)

"
  "status": "cancelled",
  "notes": "Cancelled by support",
  "actorType": "admin",
  "createdByCustomerId": null,
  "createdByAdminId": "019d2c3e-3ca0-76ae-83ba-53e81e74eed1",
  "createdBy": "019d2c3e-3ca0-76ae-83ba-53e81e74eed1",
  "createdAt": "2026-03-30T12:00:00.000Z"
"

7. Enums

7.1 order_type

• digital
• physical

7.2 order_payment_method

• online

7.3 order_status

• created
• payment_pending
• paid
• payment_failed
• cancelled
• refund_requested
• refund_pending
• refund_approved
• refund_rejected

Current manual refund flow does not transition through refund_pending; approvals/rejections are applied directly by admin action.

7.4 order_status_actor_type

• customer
• admin
• system

7.5 order_source

• checkout
• buy_now
• admin_manual

7.6 refund_status

• requested
• pending
• approved
• rejected

Current manual refund flow uses requested -> approved|rejected; pending remains a legacy enum value.

8. Integration Diagram

9. Caching

Cache keyspaces:

• order:customer:list:
• order:detail:
• order:admin:list:
• order:admin:detail:
• order: (detail-specific state key)

TTL envs:

• ORDER_HISTORY_CACHE_TTL_SECONDS (default 120)
• ORDER_ADMIN_CACHE_TTL_SECONDS (default 60)

Invalidation triggers:

• customer/admin mutation services invalidate related prefixes after accepted commands

10. Endpoint Reference + Payload Cheatsheet

10.1 Payload Cheatsheet Table (Every Endpoint)

10.1.1 Customer List Endpoint Query Variations

10.1.2 Admin List Endpoint Query Variations

10.1.3 Checkout/Buy-now Request Variations

10.1.4 Payment Init Response Variations

10.1.5 Async Request Status Response Variations

10.1.6 Order Status Flow States

10.1.7 Admin Action Variations

10.1.8 Error Response Variations

10.1.9 Cache Key Patterns

10.1.10 Rate Limit Patterns

10.1.11 Job/Queue Payloads

10.1.12 Transactional Notification Events

10.1.13 Inventory Outbox Events (Post-Payment Lifecycle)

10.1.14 DTO Field Reference

CheckoutDto

BuyNowCheckoutDto

CancelOrderDto / CancelOrderAdminDto

RequestRefundDto

ProcessRefundDto

AddNoteDto

11. Testing Scenarios

11.1 Customer Checkout Flow

Test Case: Successful checkout via esewa

1. User has items in active cart
2. POST /api/orders/checkout with "" "gateway": "esewa", "returnUrl": "https://app.com/payment/return" ""
3. Expect 200 with PaymentInitResponseDto containing redirectUrl and gatewayPayload
4. Submit form to esewa redirect URL
5. Verify user redirected back to /api/payments/redirect/:paymentId/success
6. Verify order status becomes paid after queue processing

11.2 Customer Buy-now Flow

Test Case: Buy-now with promo code

1. User selects single product
2. POST /api/orders/buy-now with "" "productId": 101, "gateway": "khalti", "returnUrl": "https://app.com/payment/return", "promoCode": "SUMMER2026" ""
3. Expect 200 with payment initiation payload
4. Complete payment via Khalti
5. Verify promo discount applied to finalPayable

11.3 Customer Order List with Filters

Test Case: Filter orders by status

1. Authenticated user with multiple orders
2. GET /api/orders?status=paid&page=1&size=10
3. Expect 200 with paginated list of paid orders only
4. Verify pagination metadata accurate

11.4 Customer Cancel Order

Test Case: Cancel order in valid status

1. User has order with status payment_pending
2. POST /api/orders/101/cancel with "" "reason": "Changed my mind" ""
3. Expect 202 with AsyncRequestResponseDto containing requestId
4. Poll GET /api/orders/requests/:requestId until status: "completed"
5. Verify order status changed to cancelled

11.5 Customer Request Refund

Test Case: Request refund on paid order

1. User has order with status paid
2. POST /api/orders/101/request-refund with "" "reason": "Product not as described", "remarks": "Please check with seller" ""
3. Expect 200 with order detail showing refundStatus: "requested"
4. Verify refund reason stored in order

11.6 Admin Process Refund

Test Case: Admin approves refund request

1. Admin retrieves order with refundStatus: "requested"
2. POST /api/admin/orders/101/process-refund with "" "action": "approve", "remarks": "Approved after verification" ""
3. Expect 202 with async request response
4. Poll until completion
5. Verify order refundStatus becomes approved

11.7 Admin Order Search

Test Case: Search orders by order number

1. Admin wants to find specific order
2. GET /api/admin/orders?search=ORD12345678
3. Expect 200 with matching orders
4. Verify search matches order number, customer name, email, or phone

11.8 Payment Failure Handling

Test Case: Payment gateway returns failure

1. User initiates checkout
2. User cancels/aborts at gateway
3. Gateway redirects to /api/payments/redirect/:paymentId/failure
4. Backend processes failure callback
5. Order status changes to payment_failed or cancelled
6. User sees payment failure page with retry option

12. Integration Flow Recipes

12.1 Mobile App: Complete Purchase Flow

1. Initialize cart: Ensure user has items in cart via Cart module
2. Initiate checkout:
   • POST /api/mobile/orders/checkout with "" "gateway": "esewa", "returnUrl": "https://yourapp.com/payment-result" ""
   • Capture returned paymentId, redirectUrl, gatewayPayload
3. Redirect to gateway:
   • If initiationType === "form_post", auto-submit form with gatewayPayload to redirectUrl
   • If initiationType === "redirect", navigate browser to redirectUrl with query params
4. Handle callback:
   • Gateway redirects to /api/payments/redirect/:paymentId/success (or failure)
   • Backend processes and redirects to payment result page with next param
5. Poll for status:
   • After redirect, call GET /api/orders/:orderId to verify status
   • Or GET /api/orders/requests/:requestId if used async flow
6. Show result:
   • If orderStatus === "paid", show success, unlock access
   • If orderStatus === "payment_failed", show failure, offer retry

12.2 Admin: Handle Customer Refund Request

1. Receive refund request: Customer submits via app
2. Review order:
   • GET /api/admin/orders/:orderId to view full order details
   • Check payment reference, transaction history
   • Verify product not already consumed (for digital: check access grants)
3. Make decision:
   • Approve: POST /api/admin/orders/:orderId/process-refund with "" "action": "approve", "remarks": "Refund approved" ""
   • Reject: POST /api/admin/orders/:orderId/process-refund with "" "action": "reject", "remarks": "Reason for rejection" ""
4. Track async operation:
   • Poll GET /api/admin/orders/requests/:requestId until completed
   • Verify final order state reflects decision
5. Add admin note:
   • POST /api/admin/orders/:orderId/notes with note for audit trail

12.3 Webhook: Payment Gateway Callback Processing

1. Receive callback:
   • Payment gateway POSTs to /api/payments/redirect/:paymentId/success (or /failure)
   • Request contains gateway-specific fields (transaction_uuid, total_amount, etc.)
2. Validate payload:
   • Backend verifies signature if provided
   • Matches paymentId with internal records
3. Queue processing job:
   • order.payment_success or order.payment_failed job added to queue
4. Async processing:
   • Worker updates order status
   • Worker creates/entitles product access (on success)
   • Worker emits transactional notifications
5. Redirect to frontend:
   • Backend redirects to /api/payments/result with status params
   • Frontend shows result page and redirects to app deep link

13. Error Handling

All order API errors return the standard error envelope:

"
  "statusCode": 404,
  "errorCode": "ORDER_NOT_FOUND",
  "message": "Order not found.",
  "timestamp": "2026-03-20T10:00:00.000Z",
  "path": "/api/orders/123"
"

Representative error map:

Time fields in this module are stored as timezone-aware values and should be handled as ISO-8601 instants by API consumers.

See Also

• Feature Guide: See Order - Feature List Section 6 (State Models) for order lifecycle diagram.
• Backend Reference: See Order - Backend Documentation Section 9 for system architecture diagram.