[Backend] Build Enterprise-Grade Cashfree Payment Infrastructure & Financial Processing System

Implement a fully production-ready payment infrastructure using Cashfree Payments for CommDesk.

This issue covers the complete backend financial architecture required for a modern SaaS platform, including:

* Payment lifecycle management
* Queue-driven event processing
* Webhook ingestion & retries
* Financial audit logging
* Reconciliation systems
* Refund engine
* Async email processing
* Distributed reliability patterns
* Monitoring & observability
* Fraud-prevention foundations
* Enterprise-grade security
* Production DevOps readiness

This implementation must follow large-scale architecture standards used by enterprise products and fintech systems.

---

# Objectives

## Primary Goals

* Create highly reliable payment infrastructure
* Prevent duplicate charges & duplicate webhooks
* Handle async financial workflows safely
* Ensure fault tolerance
* Support high-volume concurrent traffic
* Build production observability
* Enable future subscription billing
* Enable future multi-gateway support
* Maintain financial consistency
* Ensure auditability of all operations

---

# Tech Stack Requirements

## Backend Stack

Use:

* Node.js
* TypeScript
* Express or NestJS
* MongoDB or PostgreSQL
* Redis
* RabbitMQ
* Docker
* Prometheus
* Grafana
* Winston or Pino

---

# Architecture Requirements

## Required Architecture Style

Use:

* Modular architecture
* Service-layer abstraction
* Repository pattern
* Queue-driven async architecture
* Event-driven communication
* Domain-based module separation
* Centralized configuration system
* Shared error handling layer
* Shared response formatter
* Shared logger system
* Shared retry utilities
* Shared validation system

---

# Required Backend Modules

---

# 1. Payment Module

## Responsibilities

* Create orders
* Verify payments
* Manage payment lifecycle
* Track statuses
* Handle payment metadata
* Manage settlement references
* Generate invoices
* Emit payment events

---

## Payment Lifecycle

```txt id="0kk97v"
CREATED
PENDING
AUTHORIZING
PROCESSING
SUCCESS
FAILED
EXPIRED
CANCELLED
REFUNDED
PARTIALLY_REFUNDED
SETTLED
```

---

## Required Features

### Payment Creation

* Generate internal payment ID
* Generate order ID
* Store request metadata
* Validate amount
* Validate currency
* Validate user ownership
* Generate idempotency key

### Payment Verification

* Verify Cashfree signature
* Verify amount integrity
* Verify payment status
* Verify transaction consistency
* Prevent replay attacks

### State Management

Use state machine pattern.

Prevent:

* Invalid transitions
* Duplicate transitions
* Race conditions

---

# 2. Webhook Module

## Responsibilities

* Receive Cashfree events
* Validate signatures
* Store raw payloads
* Push events into queues
* Retry failures
* Track processing history
* Prevent duplicates

---

## Webhook Reliability Features

### Mandatory

* Signature verification
* Timestamp validation
* Replay attack prevention
* Request hashing
* Idempotent consumers
* Event versioning
* Dead-letter queues
* Retry queues
* Exponential backoff

---

## Webhook Processing Flow

```txt id="xg3fq7"
Cashfree
   ↓
Webhook Controller
   ↓
Signature Validation
   ↓
Webhook Log Storage
   ↓
Queue Publisher
   ↓
Queue Consumer
   ↓
Payment Service
   ↓
Database Update
   ↓
Analytics Event
   ↓
Email Event
```

---

# 3. Queue Infrastructure Module

Use RabbitMQ for all async operations.

---

# Exchange Design

## payment.exchange

Routing Keys:

```txt id="qtr2xf"
payment.created
payment.processing
payment.success
payment.failed
payment.cancelled
payment.refunded
payment.settled
```

---

## webhook.exchange

Routing Keys:

```txt id="k3wfrv"
webhook.cashfree.received
webhook.cashfree.processing
webhook.cashfree.retry
webhook.cashfree.failed
webhook.cashfree.deadletter
```

---

## email.exchange

Routing Keys:

```txt id="0z6y7q"
email.payment.success
email.payment.failed
email.payment.refund
email.invoice.generated
email.admin.alert
```

---

## analytics.exchange

Routing Keys:

```txt id="54f39q"
analytics.payment.created
analytics.payment.success
analytics.payment.failed
analytics.refund.created
analytics.webhook.failure
```

---

# Queue Reliability Features

## Must Implement

* Durable queues
* Persistent messages
* Retry queues
* Dead-letter queues
* Queue TTL
* Delayed retries
* Consumer acknowledgements
* Consumer retry protection
* Queue monitoring
* Queue metrics

---

# Retry Strategy

## Retry Attempts

```txt id="09sxy4"
1st Retry → 30 seconds
2nd Retry → 2 minutes
3rd Retry → 10 minutes
4th Retry → 30 minutes
5th Retry → Dead-letter queue
```

---

# 4. Email Processing Module

All emails must be async via queues.

---

# Email Types

## Payment Success Email

Include:

* payment ID
* transaction ID
* invoice
* support contact
* amount details

---

## Payment Failure Email

Include:

* failure reason
* retry CTA
* support information

---

## Refund Email

Include:

* refund amount
* refund status
* refund ETA

---

## Admin Alert Emails

Trigger alerts for:

* webhook failures
* queue overload
* high payment failures
* fraud anomalies
* reconciliation mismatches

---

# 5. Financial Audit Module

## Responsibilities

Track every financial action.

---

# Audit Events

Store:

* actor
* action
* resource type
* resource ID
* before state
* after state
* IP address
* user agent
* trace ID
* request ID
* timestamps

---

# 6. Refund Module

## Required Features

* Partial refunds
* Full refunds
* Retry-safe refunds
* Refund audit logs
* Refund reconciliation
* Refund state machine

---

## Refund States

```txt id="jlwmc8"
INITIATED
PROCESSING
SUCCESS
FAILED
REVERSED
```

---

# 7. Reconciliation Engine

Create scheduled reconciliation jobs.

---

# Responsibilities

Compare:

* internal payments
* Cashfree reports
* settlements
* refunds
* webhook logs

---

# Detect

* missing settlements
* duplicate transactions
* inconsistent refunds
* delayed settlements
* orphaned records

---

# Reconciliation Features

* automatic mismatch detection
* reconciliation reports
* reconciliation history
* admin alerts
* retry reconciliation

---

# 8. Fraud Detection Foundation

## Add foundational support for:

* suspicious payment detection
* rapid transaction spikes
* repeated failures
* IP anomaly tracking
* device fingerprint support
* velocity checks

---

# 9. Monitoring & Observability Module

---

# Logging Requirements

Use:

* Winston or Pino

---

# Structured Logging Fields

Every log must contain:

```ts id="29jq8h"
{
  requestId: string;
  correlationId: string;
  traceId: string;
  userId?: string;
  paymentId?: string;
  orderId?: string;
  service: string;
  module: string;
  environment: string;
  timestamp: string;
}
```

---

# Metrics

Track:

* payment success rate
* payment failure rate
* webhook processing latency
* refund latency
* queue depth
* retry counts
* DLQ counts
* API latency
* email delivery failures

---

# Monitoring Stack

Use:

* Prometheus
* Grafana

---

# Alerts

Create alerts for:

* webhook downtime
* queue failures
* payment spikes
* refund spikes
* DLQ growth
* high failure rates
* reconciliation mismatches

---

# 10. Security Requirements

---

# API Security

Must use:

* Helmet
* Rate limiting
* Request validation
* Zod or Joi validation
* Input sanitization
* CORS protection
* CSP headers

---

# Payment Security

Must implement:

* signature verification
* request hashing
* amount validation
* currency validation
* replay attack prevention
* timestamp validation

---

# Infrastructure Security

Use:

* encrypted environment variables
* secure secret storage
* queue authentication
* database encryption
* TLS everywhere
* masked sensitive logs

---

# 11. Redis Infrastructure

Use Redis for:

* distributed locks
* idempotency keys
* retry tracking
* rate limiting
* temporary session storage
* webhook replay prevention

---

# 12. Idempotency System

## Mandatory Protection

Protect:

* payment creation
* payment verification
* refunds
* webhook processing
* queue consumers

---

# Requirements

Implement:

* idempotency middleware
* Redis locks
* atomic updates
* duplicate prevention
* request fingerprinting

---

# Suggested Redis Keys

```txt id="w9k4dl"
idempotency:payment:{key}
lock:payment:{paymentId}
webhook:event:{eventId}
refund:request:{refundId}
```

---

# 13. API Design

---

# Payment APIs

```http id="z8xj83"
POST   /api/v1/payments/create
POST   /api/v1/payments/verify
GET    /api/v1/payments/:paymentId
GET    /api/v1/payments/history
GET    /api/v1/payments/status/:orderId
```

---

# Refund APIs

```http id="0ksm74"
POST   /api/v1/refunds/initiate
GET    /api/v1/refunds/:refundId
GET    /api/v1/refunds/payment/:paymentId
```

---

# Webhook APIs

```http id="h5l2lg"
POST   /api/v1/webhooks/cashfree
```

---

# Health APIs

```http id="n48z0o"
GET /health
GET /health/queues
GET /health/database
GET /health/redis
```

---

# 14. Production Database Schema

---

# payments Schema

```ts id="jlwm9q"
{
  _id: ObjectId;

  paymentId: string;
  orderId: string;

  userId: ObjectId;

  gateway: "cashfree";

  gatewayOrderId: string;
  gatewayPaymentId?: string;

  amount: number;
  currency: string;

  status:
    | "CREATED"
    | "PENDING"
    | "PROCESSING"
    | "SUCCESS"
    | "FAILED"
    | "REFUNDED";

  paymentMethod?: string;

  customerEmail?: string;
  customerPhone?: string;

  metadata: Record<string, any>;

  failureReason?: string;

  settlementStatus?: string;
  settlementAmount?: number;

  isReconciled: boolean;

  retryCount: number;

  createdAt: Date;
  updatedAt: Date;
}
```

---

# transactions Schema

```ts id="h73pn7"
{
  _id: ObjectId;

  transactionId: string;

  paymentId: string;

  providerTransactionId: string;

  bankReference?: string;

  gatewayResponse: object;

  settlementAmount?: number;

  settlementDate?: Date;

  status: string;

  createdAt: Date;
}
```

---

# webhook_logs Schema

```ts id="a1jlwm"
{
  _id: ObjectId;

  eventId: string;

  eventType: string;

  payload: object;

  headers: object;

  signature: string;

  hash: string;

  retryCount: number;

  processingStatus:
    | "RECEIVED"
    | "PROCESSING"
    | "SUCCESS"
    | "FAILED";

  failureReason?: string;

  receivedAt: Date;

  processedAt?: Date;
}
```

---

# refunds Schema

```ts id="o5c7jv"
{
  _id: ObjectId;

  refundId: string;

  paymentId: string;

  amount: number;

  reason: string;

  status:
    | "INITIATED"
    | "PROCESSING"
    | "SUCCESS"
    | "FAILED";

  providerRefundId?: string;

  retryCount: number;

  createdAt: Date;
  updatedAt: Date;
}
```

---

# audit_logs Schema

```ts id="j4px7r"
{
  _id: ObjectId;

  actorId?: string;

  action: string;

  resourceType: string;

  resourceId: string;

  beforeState?: object;

  afterState?: object;

  ipAddress?: string;

  userAgent?: string;

  traceId: string;

  requestId: string;

  createdAt: Date;
}
```

---

# 15. Docker & DevOps Requirements

---

# Docker

Use:

* multi-stage builds
* minimal production images
* health checks
* non-root containers

---

# CI/CD

Implement:

* automated testing
* security scanning
* dependency scanning
* secret scanning
* Docker image scanning

---

# Deployment

Support:

* zero-downtime deployment
* queue-safe deployment
* rollback strategy
* blue-green deployment readiness

---

# 16. Required Environment Variables

```env id="sjgtku"
NODE_ENV=

PORT=

MONGO_URI=
REDIS_URL=
RABBITMQ_URL=

CASHFREE_APP_ID=
CASHFREE_SECRET_KEY=
CASHFREE_WEBHOOK_SECRET=

JWT_SECRET=

PROMETHEUS_ENABLED=
GRAFANA_ENABLED=

PAYMENT_ENCRYPTION_KEY=

LOG_LEVEL=
```

---

# 17. Required Folder Structure

```txt id="vbltq5"
src/
 ├── modules/
 │    ├── payment/
 │    ├── refund/
 │    ├── webhook/
 │    ├── reconciliation/
 │    ├── audit/
 │    ├── analytics/
 │    ├── email/
 │    └── monitoring/
 │
 ├── infrastructure/
 │    ├── rabbitmq/
 │    ├── redis/
 │    ├── logger/
 │    ├── database/
 │    └── metrics/
 │
 ├── shared/
 │    ├── middleware/
 │    ├── errors/
 │    ├── utils/
 │    ├── validators/
 │    └── constants/
 │
 ├── config/
 ├── jobs/
 └── app.ts
```

---

# 18. Testing Requirements

---

# Unit Tests

Test:

* services
* repositories
* validators
* retry logic
* signature verification
* queue publishers
* queue consumers

---

# Integration Tests

Test:

* payment lifecycle
* webhook lifecycle
* refund lifecycle
* retry flows
* reconciliation flows

---

# Stress Testing

Test:

* concurrent payments
* webhook floods
* queue overload
* Redis lock contention

---

# Acceptance Criteria

* Full payment lifecycle operational
* Queue-driven architecture implemented
* Webhook retries operational
* DLQ handling implemented
* Duplicate webhook prevention working
* Distributed idempotency implemented
* Refund engine operational
* Reconciliation engine operational
* Monitoring dashboards configured
* Alerting configured
* Audit logging functional
* Production-grade logging implemented
* Redis locking functional
* Security hardening completed
* High automated test coverage
* Docker production setup completed

---

# Deliverables

* Production-ready payment backend
* Queue infrastructure
* Retry engine
* Refund engine
* Webhook engine
* Reconciliation system
* Monitoring stack
* Metrics dashboard
* Audit infrastructure
* API documentation
* Deployment guide
* Security documentation
* Failure recovery system



[Backend] Build Enterprise-Grade Cashfree Payment Infrastructure & Financial Processing System #23

Description

Objectives

Primary Goals

Tech Stack Requirements

Backend Stack

Architecture Requirements

Required Architecture Style

Required Backend Modules

1. Payment Module

Responsibilities

Payment Lifecycle

Required Features

Payment Creation

Payment Verification

State Management

2. Webhook Module

Responsibilities

Webhook Reliability Features

Mandatory

Webhook Processing Flow

3. Queue Infrastructure Module

Exchange Design

payment.exchange

webhook.exchange

email.exchange

analytics.exchange

Queue Reliability Features

Must Implement

Retry Strategy

Retry Attempts

4. Email Processing Module

Email Types

Payment Success Email

Payment Failure Email

Refund Email

Admin Alert Emails

5. Financial Audit Module

Responsibilities

Audit Events

6. Refund Module

Required Features

Refund States

7. Reconciliation Engine

Responsibilities

Detect

Reconciliation Features

8. Fraud Detection Foundation

Add foundational support for:

9. Monitoring & Observability Module

Logging Requirements

Structured Logging Fields

Metrics

Monitoring Stack

Alerts

10. Security Requirements

API Security

Payment Security

Infrastructure Security

11. Redis Infrastructure

12. Idempotency System

Mandatory Protection

Requirements

Suggested Redis Keys

13. API Design

Payment APIs

Refund APIs

Webhook APIs

Health APIs

14. Production Database Schema

payments Schema

transactions Schema

webhook_logs Schema

refunds Schema

audit_logs Schema

15. Docker & DevOps Requirements

Docker

CI/CD

Deployment

16. Required Environment Variables