A checkout request crosses a boundary the application cannot control. If a provider times out after accepting it, blindly retrying through another provider can turn a network problem into a duplicate charge.
The approach
Give the payment intent one owner. Persist the merchant-scoped idempotency key and request fingerprint before starting a provider attempt. Treat an ambiguous response as awaiting confirmation, then use a verified webhook or reconciliation result to resolve it.
Architecture
One intent. Explicit uncertainty.
Proposed system boundariessync / durable / async
01
Merchant API
Authenticate merchant; validate amount and key.
02
Payment domain
Own intent, attempt history and legal transitions.
03
Provider adapter
Translate requests; classify definite vs ambiguous failures.
Durable boundary
PostgreSQL: payment intent + request fingerprint + attempt + outbox record. Unique merchant/key constraint. Never hold a database transaction open across a provider call.
Asynchronous work
Outbox relay → SQS → attempt worker. Verified webhooks enter an inbox; reconciliation resolves missing confirmations. Each consumer deduplicates independently.
Logical boundaries, not a deployed topology. The interactive model below covers state transitions only.
Exercise the failure path
The response was lost. Now what?
Submit a simulated CAD 75.00 payment, retry the request, then deliver its provider confirmation twice.
Ready. Submit the payment to simulate a provider timeout.
Model limits: Single payment, in-memory TypeScript model. The webhook is assumed verified. No provider calls, persistence, concurrency or signature verification.
A merchant payment can have several traceable attempts, but an unresolved attempt prevents blind rerouting.
Trade-off: Lower apparent availability during uncertainty; operational reconciliation is required.
02Provider-specific idempotency
Reuse a provider key for the same attempt, only where the provider guarantees that behaviour. Store the relationship locally.
Trade-off: Providers have different key retention and retry contracts. An abstraction cannot erase those differences.
03Start with a modular service
Keep domain, adapter and webhook modules explicit inside one Spring Boot service before introducing more deployable services.
Trade-off: Less independent scaling initially, but simpler transaction boundaries and incident investigation.
Operating the system
What needs attention in production.
Unknown outcomes
Alert on age of awaiting-confirmation payments, not just HTTP error rates. Route unresolved items to a reconciliation queue with evidence.
Safe recovery
Bound retries for definitively retryable failures. Dead-letter exhaustion for review. Never replay a financial operation without checking its current state.
Trust boundary
Verify provider signatures and replay windows before inbox insertion. Redact tokens and sensitive payloads; retain correlation IDs and audit metadata.
Outcome & limits
What this study establishes.
The model keeps the provider attempt count at one when the request is retried, applies a confirmation once, and rejects reuse of an intent with a different amount. Those are tested local invariants, not a production reliability claim.