How prateesh-sulikeri/distributed-payment-gateway works
This repo is a multi-service distributed payment gateway, not a single application. Each service is a standalone Spring Boot 4 app with its own Gradle build, database schema migrations, and runtime port. The architecture is centered on one synchronous control plane for merchant and payment APIs, and one asynchronous event pipeline over Kafka for payment processing, notifications, and settlement.
The main runtime services are:
• merchant-service on 8082 for merchant registration and API-key issuance.
• payment-service on 8080 as the core payment orchestrator.
• mock-bank-service on 8081 as a bank simulator / payment processor.
• webhook-service on 8083 for merchant-facing webhook delivery.
• settlement-service on 8084 for end-of-day aggregation and settlement.
An auth-service and api-gateway are planned but not implemented yet.
merchant-service is the source of truth for merchant identity, status, and API key generation. Its package layout is simple: controller, service, repository, entity, DTO, mapper, and a security helper for API-key generation. Other services call it via client classes rather than sharing a database, so merchant validation remains a service boundary.
payment-service is the central transaction coordinator. It exposes payment endpoints, validates requests with an ApiKeyValidationFilter, looks up merchant data through MerchantServiceClient, persists payments in PostgreSQL, and uses a PaymentCacheService plus distributed locking (DistributedLock, LockService, LockRepository) to guard against duplicate or concurrent processing. This service also contains the transactional outbox pieces, which is a key architectural boundary: business writes happen in the database first, and Kafka publication is handled separately and reliably by OutboxPublisherJob.
The payment event flow starts in payment-service with a PaymentInitiatedEvent. That event is published to Kafka, then consumed by mock-bank-service. The bank simulator processes the request, routes it to a payment-method-specific processor, and emits a PaymentProcessedEvent back to Kafka. payment-service has a consumer for that processed event and then emits a PaymentSucceededEvent for downstream consumers once the bank result is accepted.
mock-bank-service is the simulated external payment rail. It includes a router and multiple processors (CardProcessor, UpiProcessor, NetBankingProcessor) built on a shared abstract processor. This makes the bank layer pluggable by payment method and keeps the simulated authorization/processing logic isolated from the main payment domain. It has both REST and Kafka entry points, so it can behave like a mock remote bank as well as an event-driven processor.
webhook-service handles merchant notifications after payment processing. It consumes PaymentProcessedEvent, looks up merchant metadata through MerchantServiceClient, and persists delivery attempts in WebhookDelivery. A retry job (WebhookRetryJob) indicates that failed deliveries are retried asynchronously rather than blocking the payment path. This service is the outbound integration boundary toward merchant systems.
settlement-service is the end-of-day financial aggregation layer. It consumes PaymentSucceededEvent, groups and stores settlement data, and uses Spring Batch components (SettlementBatchConfig, SettlementScheduler, SettlementTasklet, SettlementProcessor) to run batch settlement jobs. Its repository/model split suggests it writes both settlement headers and per-payment settlement records, making it the reporting/clearing boundary of the system.
The shared infrastructure is important to the architecture: Kafka carries inter-service events, PostgreSQL stores service-owned state, Redis is used only in payment-service for locking/caching, and Flyway manages schema evolution per service. Docker Compose is the local environment glue for standing up those dependencies.
Cross-cutting concerns are implemented per service instead of in a shared platform layer. Examples include API-key validation in payment-service, global exception handling there, REST client configs in services that need merchant lookups, and Kafka producer/consumer configs in all event-driven services. This keeps each service independently deployable, but also means the diagram should show repeated infrastructure dependencies rather than a single shared runtime.
The most important architectural arrows to capture are:
1. Merchant onboarding in merchant-service.
2. Payment request enters payment-service.
3. payment-service validates merchant/API key and writes payment state.
4. payment-service publishes PaymentInitiatedEvent to Kafka.
5. mock-bank-service consumes it, processes it, and emits PaymentProcessedEvent.
6. payment-service and webhook-service react to the processed event.
7. payment-service emits PaymentSucceededEvent.
8. settlement-service consumes success events and builds batch settlements.
The planned api-gateway and auth-service are not part of the implemented topology yet, so the current architecture is still service-by-service rather than gateway-first or centralized-auth-first.
Main entry points: docker-compose.yml Docker Compose · PaymentServiceImpl.java Payment Core · SettlementServiceApplication.java Settlement App · MerchantServiceImpl.java Merchant Core
Components 28
Merchant Service
Merchant onboarding and API-key issuance
- Merchant App · Merchant registration and API-key issuance runtime
merchant-service/src/main/java/com/payments/merchant_service/MerchantServiceApplication.java - Merchant API · Merchant registration and lookup endpoints
merchant-service/src/main/java/com/payments/merchant_service/controller/MerchantController.java - Merchant Core · Owns merchant identity, status, and API-key generation
merchant-service/src/main/java/com/payments/merchant_service/service/impl/MerchantServiceImpl.java - Merchant Store · Merchant persistence and domain model
merchant-service/src/main/java/com/payments/merchant_service/repository/MerchantRepository.java
Payment Service
Core payment orchestration and transactional outbox
- Payment App · Central payment orchestration runtime
payment-service/src/main/java/com/payments/payment_service/PaymentServiceApplication.java - Payment API · Payment endpoints and API-key validation boundary
payment-service/src/main/java/com/payments/payment_service/payment/controller/PaymentController.java - Payment Core · Validates, coordinates, and persists payments
payment-service/src/main/java/com/payments/payment_service/payment/service/impl/PaymentServiceImpl.java - Merchant Client · Merchant lookup client used for validation and enrichment
payment-service/src/main/java/com/payments/payment_service/payment/client/MerchantServiceClient.java - Payment Store · Payment persistence and domain state
payment-service/src/main/java/com/payments/payment_service/payment/repository/PaymentRepository.java - Outbox Job · Publishes database-backed events to Kafka reliably
payment-service/src/main/java/com/payments/payment_service/payment/event/outbox/OutboxPublisherJob.java - Locking Cache · Duplicate protection and concurrent processing guard
payment-service/src/main/java/com/payments/payment_service/common/lock/LockService.java - Payment Events · Initiated, processed, and succeeded payment events
payment-service/src/main/java/com/payments/payment_service/payment/event/PaymentEventProducer.java
Mock Bank
Simulated external payment rail and processor
- Bank App · Mock bank simulator runtime
mock-bank-service/src/main/java/com/payments/mock_bank_service/MockBankServiceApplication.java - Payment Router · Dispatches by payment method to processors
mock-bank-service/src/main/java/com/payments/mock_bank_service/processor/PaymentRouter.java - Processors · Card, UPI, and netbanking processing implementations
mock-bank-service/src/main/java/com/payments/mock_bank_service/processor/AbstractPaymentProcessor.java - Bank Events · Consumes initiated events and emits processed events
mock-bank-service/src/main/java/com/payments/mock_bank_service/event/PaymentInitiatedConsumer.java
Webhook Service
Merchant notification delivery and retries
- Webhook App · Merchant notification delivery runtime
webhook-service/src/main/java/com/payments/webhook_service/WebhookServiceApplication.java - Webhook Delivery · Persists delivery attempts and status
webhook-service/src/main/java/com/payments/webhook_service/service/impl/WebhookDeliveryServiceImpl.java - Retry Job · Asynchronous retry path for failed webhook deliveries
webhook-service/src/main/java/com/payments/webhook_service/job/WebhookRetryJob.java - Webhook Events · Consumes payment processed events for merchant notifications
webhook-service/src/main/java/com/payments/webhook_service/event/PaymentProcessedConsumer.java
Settlement Service
End-of-day aggregation and batch settlement
- Settlement App · Batch settlement and aggregation runtime
settlement-service/src/main/java/com/payments/settlement_service/SettlementServiceApplication.java - Batch Pipeline · Scheduler, tasklet, and processor for settlement runs
settlement-service/src/main/java/com/payments/settlement_service/config/SettlementBatchConfig.java - Settlement Core · Groups successful payments into settlement records
settlement-service/src/main/java/com/payments/settlement_service/service/impl/SettlementAggregationServiceImpl.java - Settlement Store · Settlement headers and per-payment records
settlement-service/src/main/java/com/payments/settlement_service/repository/SettlementRepository.java
Shared Infra
Cross-service messaging, storage, and local environment
- Kafka · Inter-service event transport
- PostgreSQL · Service-owned persistent state
- Redis · Distributed locks and payment cache
- Docker Compose · Local environment orchestration for dependencies and services
docker-compose.yml
Connections 36
- Merchant API → Merchant Core: delegates · Controller routes onboarding and lookup requests to domain logic
- Merchant Core → Merchant Store: persists · Merchant records are stored in the service-owned database
- Merchant Core → Merchant App: runs in · Core merchant logic is part of the Spring Boot runtime
- Payment API → Payment Core: delegates · Payment endpoints hand off to orchestration logic
- Payment API → Merchant Client: validates merchant · API-key and merchant checks use the merchant service boundary
- Payment Core → Merchant Client: looks up · Payment processing enriches and validates merchant data remotely
- Payment Core → Payment Store: persists · Payment state is written to PostgreSQL first
- Payment Core → Locking Cache: locks/cache · Duplicate prevention and fast reads use Redis-backed helpers
- Payment Core → Payment Events: creates events · Payment orchestration emits initiated and success events
- Outbox Job → Kafka: publishes · Outbox entries are published asynchronously to Kafka
- Payment Events → Kafka: publishes/consumes · Payment-service produces initiated and succeeded events and consumes processed events
- Bank Events → Kafka: consumes/publishes · Mock bank consumes initiated events and emits processed results
- Bank Events → Payment Router: routes · Incoming payment requests are dispatched by method
- Payment Router → Processors: selects · Card, UPI, and netbanking processors implement method-specific behavior
- Webhook Events → Kafka: consumes · Webhook delivery starts from processed payment events
- Webhook Events → Webhook Delivery: creates deliveries · Processed payments are turned into delivery attempts
- Webhook Delivery → Retry Job: retries via · Failed deliveries are retried asynchronously
- Webhook Delivery → Merchant Client: enriches merchant · Merchant metadata is fetched before notification delivery
- Batch Pipeline → Settlement Core: orchestrates · Batch configuration drives settlement aggregation steps
- Settlement Core → Settlement Store: persists · Settlement headers and payment records are stored locally
- Settlement App → Kafka: consumes · Settlement is triggered by success events from the payment flow
- Settlement App → Batch Pipeline: runs · Batch runtime hosts scheduled settlement jobs
- Merchant App → PostgreSQL: uses · Merchant service owns its PostgreSQL schema
- Payment App → PostgreSQL: uses · Payment service persists business and outbox state
- Payment App → Redis: uses · Payment service is the only Redis consumer
- Bank App → Kafka: uses · Bank service participates in the event pipeline
- Webhook App → Kafka: uses · Webhook service reacts to payment events
- Settlement App → PostgreSQL: uses · Settlement service stores settlement aggregates in its own database
- Docker Compose → Merchant App: starts · Local compose brings up each standalone service
- Docker Compose → Payment App: starts · Local compose brings up each standalone service
- Docker Compose → Bank App: starts · Local compose brings up each standalone service
- Docker Compose → Webhook App: starts · Local compose brings up each standalone service
- Docker Compose → Settlement App: starts · Local compose brings up each standalone service
- Docker Compose → Kafka: provides · Compose coordinates shared event infrastructure
- Docker Compose → PostgreSQL: provides · Compose coordinates shared database infrastructure
- Docker Compose → Redis: provides · Compose coordinates shared cache infrastructure