feat: Add payment reconciliation scheduled job

src/app.module.ts

@@ -24,6 +24,7 @@ import { GlobalExceptionFilter } from './common/interceptors/global-exception.fi
 import { DeepLinkModule } from './deep-link/deep-link.module';
 import { InvoicesModule } from './payments/invoices/invoices.module';
 import { ReportingModule } from './payments/reporting/reporting.module';
+import { PaymentsModule } from './payments/payments.module';
 import { HealthModule } from './health/health.module';
 
 // ✅ keep BOTH modules
@@ -53,6 +54,7 @@ const featureFlags = loadFeatureFlags();
     DeepLinkModule,
     InvoicesModule,
     ReportingModule,
+    PaymentsModule,
     HealthModule,
 
     // ✅ always include read replicas (or wrap if needed)

src/audit-log/enums/audit-action.enum.ts

@@ -48,6 +48,8 @@ export enum AuditAction {
   DATA_RETENTION_APPLIED = 'DATA_RETENTION_APPLIED',
   AUDIT_LOG_EXPORTED = 'AUDIT_LOG_EXPORTED',
   REPORT_GENERATED = 'REPORT_GENERATED',
+  // Payment reconciliation
+  PAYMENT_RECONCILIATION_MISMATCH = 'PAYMENT_RECONCILIATION_MISMATCH',
 }
 export enum AuditSeverity {
   INFO = 'INFO',

src/payments/payments.module.ts

@@ -1,17 +1,25 @@
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { CurrencyModule } from '../currency/currency.module';
+import { AuditLogModule } from '../audit-log/audit-log.module';
 import { Payment } from './entities/payment.entity';
 import { Subscription } from './entities/subscription.entity';
 import { Invoice } from './entities/invoice.entity';
 import { Refund } from './entities/refund.entity';
 import { PricingService } from './services/pricing.service';
 import { PricingController } from './controllers/pricing.controller';
+import { ReconciliationService } from './reconciliation/reconciliation.service';
+import { ReconciliationTask } from './reconciliation/reconciliation.task';
+import { ReconciliationController } from './reconciliation/reconciliation.controller';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([Payment, Subscription, Invoice, Refund]), CurrencyModule],
-  providers: [PricingService],
-  controllers: [PricingController],
-  exports: [PricingService, CurrencyModule],
+  imports: [
+    TypeOrmModule.forFeature([Payment, Subscription, Invoice, Refund]),
+    CurrencyModule,
+    AuditLogModule,
+  ],
+  providers: [PricingService, ReconciliationService, ReconciliationTask],
+  controllers: [PricingController, ReconciliationController],
+  exports: [PricingService, CurrencyModule, ReconciliationService],
 })
 export class PaymentsModule {}

src/payments/reconciliation/reconciliation.controller.ts

@@ -0,0 +1,61 @@
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiResponse, ApiBearerAuth } from '@nestjs/swagger';
+import { ReconciliationService, ReconciliationReport } from './reconciliation.service';
+import { RolesGuard } from '../../auth/guards/roles.guard';
+import { Roles } from '../../auth/decorators/roles.decorator';
+
+/**
+ * Controller for payment reconciliation endpoints.
+ * Provides admin-only access to reconciliation reports.
+ */
+@ApiTags('Payments - Reconciliation')
+@ApiBearerAuth()
+@Controller('payments/reconciliation')
+@UseGuards(RolesGuard)
+export class ReconciliationController {
+  constructor(private readonly reconciliationService: ReconciliationService) {}
+
+  /**
+   * Get the last reconciliation report
+   * GET /payments/reconciliation/report
+   */
+  @Get('report')
+  @Roles('admin')
+  @ApiOperation({
+    summary: 'Get last reconciliation report',
+    description: 'Returns the results of the most recent payment reconciliation run. Admin-only endpoint.',
+  })
+  @ApiResponse({
+    status: 200,
+    description: 'Reconciliation report retrieved successfully',
+    schema: {
+      type: 'object',
+      properties: {
+        runAt: { type: 'string', format: 'date-time' },
+        startDate: { type: 'string', format: 'date-time' },
+        endDate: { type: 'string', format: 'date-time' },
+        totalProviderTransactions: { type: 'number' },
+        totalLocalPayments: { type: 'number' },
+        matchedTransactions: { type: 'number' },
+        unmatchedProviderTransactions: { type: 'array', items: { type: 'object' } },
+        unmatchedLocalPayments: { type: 'array', items: { type: 'object' } },
+        mismatches: { type: 'array', items: { type: 'object' } },
+      },
+    },
+  })
+  @ApiResponse({
+    status: 401,
+    description: 'Unauthorized - authentication required',
+  })
+  @ApiResponse({
+    status: 403,
+    description: 'Forbidden - admin role required',
+  })
+  @ApiResponse({
+    status: 404,
+    description: 'No reconciliation report available',
+  })
+  getLastReport(): ReconciliationReport | null {
+    return this.reconciliationService.getLastReport();
+  }
+}