How abhishek1913/upi-checkout-reconciliation works
This is a Spring Boot UPI checkout service. Customers create idempotent orders, start a collect or intent payment, and query order status and the payment timeline. Gateway outcomes arrive through authenticated, duplicate-prone webhooks; scheduled reconciliation checks unresolved attempts and expires overdue orders. The README also documents a deliberately unreliable simulator and a Cashfree sandbox integration. Sampled services show key orchestration, but several domain modules were not inspected, so links between those modules are limited to documented behavior.
Main entry points: PaymentInitiationService.java Payment initiation · WebhookIngestionService.java Webhook ingestion · PaymentGateway.java Gateway interface · ReconciliationService.java Reconciliation
Components 27
Orders and payments
- Order API
src/main/java/com/abhishekshukla/checkout/order/OrderController.java - Order service
src/main/java/com/abhishekshukla/checkout/order/OrderService.java - Payment API
src/main/java/com/abhishekshukla/checkout/payment/PaymentController.java - Payment initiation
src/main/java/com/abhishekshukla/checkout/payment/PaymentInitiationService.java - Session provisioner
src/main/java/com/abhishekshukla/checkout/payment/GatewaySessionProvisioner.java - Attempt ledger
src/main/java/com/abhishekshukla/checkout/payment/PaymentAttemptLedger.java - Payment applier
src/main/java/com/abhishekshukla/checkout/payment/GatewayPaymentApplier.java - Payment queries
src/main/java/com/abhishekshukla/checkout/payment/PaymentQueryService.java
Gateway integrations
- Gateway interface
src/main/java/com/abhishekshukla/checkout/gateway/PaymentGateway.java - Cashfree adapter
src/main/java/com/abhishekshukla/checkout/gateway/cashfree/CashfreeGateway.java - Gateway simulator
src/main/java/com/abhishekshukla/checkout/gateway/simulator/SimulatedGateway.java - Webhook verifier
src/main/java/com/abhishekshukla/checkout/gateway/cashfree/CashfreeWebhooks.java
Event reliability
- Idempotency
src/main/java/com/abhishekshukla/checkout/idempotency/IdempotencyService.java - Webhook API
src/main/java/com/abhishekshukla/checkout/webhook/WebhookController.java - Webhook ingestion
src/main/java/com/abhishekshukla/checkout/webhook/WebhookIngestionService.java - Webhook inbox
src/main/java/com/abhishekshukla/checkout/webhook/WebhookInbox.java - Reconciliation
src/main/java/com/abhishekshukla/checkout/reconciliation/ReconciliationService.java - Attempt reconciler
src/main/java/com/abhishekshukla/checkout/reconciliation/AttemptReconciler.java - Discrepancy API
src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyController.java - Discrepancy service
src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyService.java
Persistence and audit
- Key store
src/main/java/com/abhishekshukla/checkout/idempotency/IdempotencyStore.java - Order repository
src/main/java/com/abhishekshukla/checkout/order/OrderRepository.java - PostgreSQL
- Reconciliation queue
src/main/java/com/abhishekshukla/checkout/reconciliation/ReconciliationQueue.java - Discrepancy repository
src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyRepository.java
Other components
- Customer
- Cashfree PG
Connections 34
- Customer → Order API: creates order
- Order API → Order service: calls
- Order service → Idempotency: executes safely
- Idempotency → Key store: claims and replays
- Key store → PostgreSQL: reads and writes
- Order service → Order repository: saves and reads
- Order repository → PostgreSQL: reads and writes
- Customer → Payment API: starts payment
- Payment API → Payment initiation: calls
- Payment initiation → Session provisioner: provisions session
- Payment initiation → Attempt ledger: opens attempt
- Payment initiation → Gateway interface: initiates payment
- Cashfree adapter → Gateway interface: implements
- Gateway simulator → Gateway interface: implements
- Cashfree adapter → Cashfree PG: calls
- Customer → Webhook API: gateway delivers
- Cashfree PG → Webhook API: sends webhook
- Webhook API → Webhook ingestion: passes delivery
- Webhook ingestion → Webhook verifier: authenticates
- Webhook ingestion → Webhook inbox: records delivery
- Webhook ingestion → Payment applier: applies payment update
- Webhook inbox → PostgreSQL: records events
- Payment applier → Attempt ledger: updates attempt
- Customer → Payment queries: checks status
- Payment queries → Order repository: checks order
- Payment queries → PostgreSQL: reads attempts and timeline
- Reconciliation → Reconciliation queue: claims due attempts
- Reconciliation → Attempt reconciler: reconciles attempts
- Reconciliation → PostgreSQL: expires overdue orders
- Attempt reconciler → Gateway interface: checks gateway
- Customer → Discrepancy API: views discrepancies
- Discrepancy API → Discrepancy service: calls
- Discrepancy service → Discrepancy repository: reads open records
- Discrepancy repository → PostgreSQL: reads and writes