Immediate decision
Keep the synchronous path small: validate what is necessary to continue the customer journey, bound provider waits and return an explicit state.
Data flow
Trace the journey
across clear boundaries.
A useful architecture describes where data crosses boundaries and who owns the truth at each step. The exact persistence and provider implementation remains project-specific.
01Customer surface
02Commerce domain
03Adapter contract
04External provider
05Verified event
Conceptual flow only · implementation configuration and source-of-truth rules remain authoritative.
Recovery and side effects
Move non-critical work to controlled asynchronous paths when safe, with idempotency, retry limits and observability.
Never trust a callback blindly
Verify authenticity, normalize provider state, deduplicate and reconcile when order/payment truth is uncertain.
Leave useful evidence
Correlation identifiers and safe event history make failures diagnosable without logging credentials or sensitive payloads unnecessarily.