feat(payments): add idempotency keys to payment create

Allow clients to safely retry POST /payments by supplying an
idempotencyKey; replaying the same key returns the original payment
instead of creating a duplicate (mirrors the existing Transaction
idempotency pattern).

What changed:
- Prisma: add nullable, unique Payment.idempotencyKey + index, migration
- CreatePaymentDto: optional idempotencyKey field
- PaymentsService.create(): short-circuits to the existing payment when
  the key was already used, before any wallet/limit checks run; stores
  the key on new payments
- MetricsService: new payment_idempotency_hits_total counter
- Fixed pre-existing wiring bugs that left PaymentsModule unable to
  actually instantiate: PAYMENT_LIMITS_PORT was never bound to a
  provider in payments.module.ts, payments.service.ts called a
  non-existent this.limitsService instead of the injected
  this.paymentLimitsPort, and RequestContextService was provided by
  payments.module.ts/limits.module.ts but never injected into
  PaymentsService/LimitsService's constructors. These bugs made
  src/payments/payments.service.ts and src/limits/limits.service.ts
  fail to compile/run, which is on the direct path of this feature, so
  they're fixed here rather than worked around. Narrowed
  PaymentLimitsPort.checkLimits to Promise<void> (was Promise<void> |
  void) to match retryWithBackoff's generic constraint.
- Updated payments.service.spec.ts / payments-limits.integration.spec.ts
  / limits.service.spec.ts, which referenced the same undeclared
  identifiers, to compile and pass
- New tests: idempotent replay returns existing payment without a
  duplicate create, fresh key creates and stores it, no key skips the
  lookup entirely

Closes #477

Author: Meshmulla

prisma/migrations/20260724010000_add_payment_idempotency_key/migration.sql

@@ -0,0 +1,8 @@
+-- AlterTable
+ALTER TABLE "Payment" ADD COLUMN "idempotencyKey" TEXT;
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Payment_idempotencyKey_key" ON "Payment"("idempotencyKey");
+
+-- CreateIndex
+CREATE INDEX "Payment_idempotencyKey_idx" ON "Payment"("idempotencyKey");

prisma/schema.prisma

@@ -44,8 +44,13 @@ model Payment {
   userId Int // Legacy field
   user   LegacyUser @relation("UserPayments", fields: [userId], references: [id])
 
+  /// Client-supplied idempotency key to prevent duplicate submissions
+  idempotencyKey String? @unique
+
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
+
+  @@index([idempotencyKey])
 }
 
 model UserLimit {

src/limits/limits.service.spec.ts

@@ -4,6 +4,7 @@ import { EventEmitter2 } from '@nestjs/event-emitter';
 import { LimitsService, LimitExceededException } from './limits.service';
 import { PrismaService } from '../prisma/prisma.service';
 import { MetricsService } from '../metrics/metrics.service';
+import { RequestContextService } from '../common/request-context/request-context.service';
 import { LimitUpdatedEvent } from './events/limit-updated.event';
 import { LimitExceededEvent } from './events/limit-exceeded.event';
 
@@ -12,6 +13,7 @@ describe('LimitsService', () => {
   let prisma: any;
   let eventEmitter: any;
   let metrics: any;
+  let requestContext: any;
 
   const walletId = 'wallet-uuid-1';
 
@@ -31,15 +33,15 @@ describe('LimitsService', () => {
       incrementLimitExceeded: jest.fn(),
       incrementLimitChecks: jest.fn(),
     };
-
-    cacheService = { get: jest.fn(), set: jest.fn(), delete: jest.fn() };
+    requestContext = { getRequestId: jest.fn().mockReturnValue('req-1') };
 
     const module: TestingModule = await Test.createTestingModule({
       providers: [
         LimitsService,
         { provide: PrismaService, useValue: prisma },
         { provide: EventEmitter2, useValue: eventEmitter },
         { provide: MetricsService, useValue: metrics },
+        { provide: RequestContextService, useValue: requestContext },
       ],
     }).compile();
 

src/limits/limits.service.ts

@@ -14,6 +14,7 @@ import { LimitUpdatedEvent } from './events/limit-updated.event';
 import { LimitExceededEvent } from './events/limit-exceeded.event';
 import { retryWithBackoff } from '../common/utils/retry';
 import { MetricsService } from '../metrics/metrics.service';
+import { RequestContextService } from '../common/request-context/request-context.service';
 
 export const LIMIT_ERROR_CODES = {
   PER_TX_LIMIT_EXCEEDED: 'LIMIT_PER_TX_EXCEEDED',
@@ -40,6 +41,7 @@ export class LimitsService {
     private readonly prisma: PrismaService,
     private readonly eventEmitter: EventEmitter2,
     private readonly metrics: MetricsService,
+    private readonly requestContext: RequestContextService,
   ) {}
 
   async setLimits(walletId: string, daily: number, perTx: number) {

src/metrics/metrics.module.ts

@@ -32,6 +32,10 @@ import { MetricsController } from './metrics.controller';
       help: 'Total number of limit checks performed',
       labelNames: ['result'],
     }),
+    makeCounterProvider({
+      name: 'payment_idempotency_hits_total',
+      help: 'Total number of payment create requests deduplicated via idempotency key',
+    }),
   ],
   exports: [MetricsService],
 })

src/metrics/metrics.service.spec.ts

@@ -7,6 +7,7 @@ describe('MetricsService', () => {
   let paymentProcessingHistogram: any;
   let limitExceededCounter: any;
   let limitChecksCounter: any;
+  let paymentIdempotencyHitsCounter: any;
 
   beforeEach(() => {
     const labeledCounter = { inc: jest.fn() };
@@ -15,13 +16,15 @@ describe('MetricsService', () => {
     paymentProcessingHistogram = { observe: jest.fn() };
     limitExceededCounter = { labels: jest.fn().mockReturnValue(labeledCounter) };
     limitChecksCounter = { labels: jest.fn().mockReturnValue(labeledCounter) };
+    paymentIdempotencyHitsCounter = { inc: jest.fn() };
 
     service = new MetricsService(
       paymentsCreatedCounter,
       paymentsFailedCounter,
       paymentProcessingHistogram,
       limitExceededCounter,
       limitChecksCounter,
+      paymentIdempotencyHitsCounter,
     );
   });
 
@@ -61,4 +64,12 @@ describe('MetricsService', () => {
       expect(limitChecksCounter.labels).toHaveBeenCalledWith('allowed');
     });
   });
+
+  describe('payment idempotency metrics', () => {
+    it('should increment payment_idempotency_hits_total counter', () => {
+      service.incrementPaymentIdempotencyHit();
+
+      expect(paymentIdempotencyHitsCounter.inc).toHaveBeenCalled();
+    });
+  });
 });

src/metrics/metrics.service.ts

@@ -15,6 +15,8 @@ export class MetricsService {
     private readonly limitExceededCounter: Counter,
     @InjectMetric('limit_checks_total')
     private readonly limitChecksCounter: Counter,
+    @InjectMetric('payment_idempotency_hits_total')
+    private readonly paymentIdempotencyHitsCounter: Counter,
   ) {}
 
   incrementPaymentsCreated(): void {
@@ -36,4 +38,8 @@ export class MetricsService {
   incrementLimitChecks(result: 'allowed' | 'denied'): void {
     this.limitChecksCounter.labels(result).inc();
   }
+
+  incrementPaymentIdempotencyHit(): void {
+    this.paymentIdempotencyHitsCounter.inc();
+  }
 }

src/payments/dto/create-payment.dto.ts

@@ -72,4 +72,15 @@ export class CreatePaymentDto {
   @IsNotEmpty({ message: 'toId is required' })
   @Min(1, { message: 'toId must be greater than 0' })
   toId: number;
+
+  /** Client-supplied idempotency key. Replaying the same key returns the original payment instead of creating a duplicate. */
+  @ApiProperty({
+    example: 'a1b2c3d4-e5f6-4789-a012-3456789abcde',
+    description:
+      'Optional client-supplied idempotency key. Reusing the same key returns the original payment instead of creating a duplicate.',
+    required: false,
+  })
+  @IsString({ message: 'idempotencyKey must be a string' })
+  @IsOptional()
+  idempotencyKey?: string;
 }

src/payments/payments-limits.integration.spec.ts

@@ -7,6 +7,9 @@ import { PrismaService } from '../prisma/prisma.service';
 import { PaymentStatus } from './entities/payment.entity';
 import { WalletStatus } from '../wallets/domain/wallet.model';
 import { RequestContextService } from '../common/request-context/request-context.service';
+import { PAYMENT_LIMITS_PORT } from './ports/payment-limits.port';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { MetricsService } from '../metrics/metrics.service';
 
 describe('Payments and Limits Integration', () => {
   let paymentsService: PaymentsService;
@@ -46,6 +49,18 @@ describe('Payments and Limits Integration', () => {
         { provide: PAYMENT_LIMITS_PORT, useExisting: LimitsService },
         { provide: WalletsService, useValue: mockWalletsService },
         { provide: RequestContextService, useValue: mockRequestContext },
+        { provide: EventEmitter2, useValue: { emit: jest.fn() } },
+        {
+          provide: MetricsService,
+          useValue: {
+            incrementPaymentsCreated: jest.fn(),
+            incrementPaymentsFailed: jest.fn(),
+            recordPaymentProcessingDuration: jest.fn(),
+            incrementPaymentIdempotencyHit: jest.fn(),
+            incrementLimitExceeded: jest.fn(),
+            incrementLimitChecks: jest.fn(),
+          },
+        },
       ],
     }).compile();
 

src/payments/payments.controller.ts

@@ -41,7 +41,7 @@ export class PaymentsController {
 
   @ApiOperation({
     summary: 'Create a new payment',
-    description: 'Create a new payment between wallets. Requires API key authentication. Rate limited to prevent abuse. Emits payment.created event on success.',
+    description: 'Create a new payment between wallets. Requires API key authentication. Rate limited to prevent abuse. Emits payment.created event on success. Pass an idempotencyKey to safely retry without creating a duplicate payment — replaying the same key returns the original payment.',
   })
   @ApiBody({
     type: CreatePaymentDto,
@@ -55,6 +55,7 @@ export class PaymentsController {
           description: 'Payment for services',
           fromId: 1,
           toId: 2,
+          idempotencyKey: 'a1b2c3d4-e5f6-4789-a012-3456789abcde',
         },
       },
     },