fix: prevent quota exhaustion and improve payment/payout reliability

[maikNeta]

Summary

This PR addresses critical issues in payment retry logic, gateway integration reliability, payment correctness, and payout handling.

Changes

1. Issue Fix failed payout retry exhausting provider quota #1024: Fix failed payout retry exhausting provider quota

   • Added QuotaService to track provider request quotas (hourly and daily limits)
   • Implements quota enforcement in PaymentRetryService to prevent exhausting provider limits
   • Quota tracking prevents retry loops from overwhelming providers
   • Supports configurable burst limits and automatic reset

2. Issue Improve gateway integrations (iteration 6) #1162: Improve gateway integrations (iteration 6)

   • Created GatewayIntegrationService with enhanced error classification
   • Implements circuit breaker pattern for provider resilience
   • Adds request deduplication and caching for idempotent operations
   • Provides granular error handling (rate limit, timeout, auth, etc.)

3. Issue Fix payment correctness bugs (iteration 5) #1159: Fix payment correctness bugs (iteration 5)

   • Added PaymentCorrectnessService for payment state validation
   • Enforces valid state transitions (pending → processing/cancelled, etc.)
   • Validates payment records for data consistency
   • Provides consistency reporting and automatic cleanup of old records

4. Issue Improve payout reliability (iteration 6) #1160: Improve payout reliability (iteration 6)

   • Created PayoutReliabilityService with idempotency support
   • Detects and recovers stuck payouts
   • Tracks payout attempts and status transitions
   • Provides metrics on success rates and stuck payouts
   • Prevents duplicate payouts via idempotency keys

Technical Details

• QuotaService: Tracks per-provider request counts, resets hourly/daily
• GatewayIntegrationService: Circuit breaker (5 failures → open for 60s), error classification, request caching
• PaymentCorrectnessService: Enforces valid state machine transitions, validates payment data
• PayoutReliabilityService: Idempotent payout creation, stuck payout detection (1hr timeout), max 5 retry attempts

All services are designed to be thread-safe and work with async operations.

Testing

• Quota service tested with rate limit scenarios
• Payment state transitions validated against state machine
• Payout idempotency verified with duplicate requests
• Circuit breaker tested with failure scenarios

Closes #1024
Closes #1159
Closes #1160
Closes #1162

[vercel]

@maikNeta is attempting to deploy a commit to the smartdevs17's projects Team on Vercel.

A member of the Team first needs to authorize it.

[maikNeta]

Closed in favor of focused PR #1297 which properly integrates with upstream #1295