Payment Module Architecture

Audience: Backend developers, system architects Scope: Module organization, gateway abstraction, DB model, runtime decisions

Overview

The payment module (apps/api/src/modules/payment/) is a reusable gateway layer plus payment-record lifecycle service.

Current active consumer:

• Order checkout/buy-now flow (/api/orders/* and /api/mobile/orders/*)

Core responsibilities:

1. Gateway abstraction (PaymentGateway interface + runtime registry)
2. Payment record lifecycle (pending -> completed|failed|refunded)
3. Redirect callback verification and status finalization

High-Level Architecture

Payment Flow

Database Model

Primary table: payment

Key columns:

• reference_id + reference_type for polymorphic references
• user_id, amount_npr, gateway, status
• gateway_transaction_id, gateway_response, metadata

Current runtime usage:

• reference_type = order

reference_type remains polymorphic for future controlled expansion, but order is the active domain in current runtime.

Initiation Types

• form_post: frontend posts hidden form fields (esewa, connect_ips)
• redirect: frontend navigates to gateway URL (fonepay)
• sdk: reserved for future SDK-driven gateways

Design Notes

• Gateway registration is constructor-driven map lookup (Map<string, PaymentGateway>).
• Callback verification is backend-owned; frontend does not verify gateway signatures.
• Payment callbacks are idempotent and enqueue order-processing jobs.
• Manual refund business decision is handled in order runtime; no gateway refund API call is executed in this phase.

File Map

• apps/api/src/modules/payment/payment.service.ts
• apps/api/src/modules/payment/payment.interface.ts
• apps/api/src/modules/payment/controllers/payment-redirect.controller.ts
• apps/api/src/modules/payment/controllers/payment-result.controller.ts
• packages/db/src/schema/payment.ts