Case Study
Transactional Booking & Payment Platform
Payments • Webhooks • Concurrency
Tourism reservation platform in production. Multi-module, multi-tenant backoffice (partners and end customers). Payments via Mercado Pago, Stripe, Pix; webhooks as single source of truth for "reservation paid," with HMAC validation and idempotency by event_id. Idempotency keys on reservation creation; promotion engine with transactional claims; catalog normalization with external providers. Modular monolith, Docker, CI/CD, AWS. Transactional integrity and payment security by design.
Transactional Flow Overview
System Invariants
- ·A payment intent cannot transition from failed to succeeded.
- ·Reservation "paid" is set only after a verified webhook; frontend and redirect cannot set it.
- ·Webhook events are processed idempotently by provider event_id.
- ·Availability for a slot is updated under pessimistic lock (SELECT FOR UPDATE); no optimistic commit.
- ·Idempotency keys are scoped per client and stored; duplicate key returns original response.
- ·Payment and reservation state changes for a webhook occur in a single database transaction.
Architecture Decision Records
- ADR-01Use webhooks as single source of truth for payment status
- ADR-02Idempotency keys on reservation creation and event_id on webhooks
- ADR-03Pessimistic locking (SELECT FOR UPDATE) for availability
- ADR-04Modular monolith with explicit domain boundaries
- ADR-05HMAC validation for all incoming webhook payloads