Online Movie Ticket Booking Platform (Backend)

This post focuses on backend system design only (no UI). It covers architecture, service boundaries, booking correctness, scalability, observability, deployment, and API contracts for one read + one write scenario.

---

1. System Overview

1.1 Problem Statement

The objective is to design and implement a scalable, highly available Online Movie Ticket Booking Platform that enables seamless collaboration between theatre partners and end customers, while supporting:

• High-volume concurrent bookings
• Multiple cities and languages
• Secure payment processing

The platform must:

• Allow theatre partners to onboard, manage theatres, screens, seat layouts, and show schedules.
• Enable customers to browse movies, theatres, and show timings across cities and dates.
• Support real-time seat availability, ticket booking, payments, and notifications.
• Scale reliably during peak demand (e.g., movie releases, weekends).
• Ensure data consistency, prevent double booking, and meet stringent non-functional requirements such as 99.99% availability, security, and compliance.

The solution is expected to be service-oriented, cloud-native, and production-grade, focusing on backend services only.

---

1.2 Key Stakeholders

• Customers (B2C)
  Browse movies and showtimes, select seats, make payments, and receive booking confirmations.

• Theatre Partners (B2B)
  Onboard theatres, define screens and seat maps, create/update shows, and manage availability.

• Platform Operations Team
  Monitor system health, handle deployments, manage configurations, and ensure SLA compliance.

• External Systems
  Payment gateways, notification providers (SMS/Email/WhatsApp), and analytics platforms.

---

1.3 Core Functional Capabilities

Theatre & Partner Management

• Partner onboarding and authentication
• Theatre, screen, and seat-map configuration
• Show creation, updates, and cancellations

Movie Discovery & Browsing

• Browse movies by city, language, genre, and date
• View theatres currently running a selected movie
• Retrieve show timings and seat availability

Ticket Booking & Payments

• Seat selection with real-time availability
• Temporary seat locking to avoid double booking
• Secure payment initiation and confirmation
• Booking confirmation and ticket issuance

Offers & Pricing

• Rule-based promotional offers (e.g., third ticket at 50% discount)
• Flexible pricing strategies configurable per city or theatre

Notifications

• Booking confirmations, cancellations, and refunds
• Asynchronous notification delivery via messaging systems

---

1.4 Key Non-Functional Requirements

• High Availability:
  Achieve 99.99% uptime, especially during peak booking windows.

• Scalability:
  Horizontal scalability for spikes in read traffic (browsing) and write traffic (bookings).

• Consistency & Concurrency Control:
  Strong consistency for seat booking to prevent overselling and race conditions.

• Performance:
  Low-latency responses for browsing and booking flows.

• Security & Compliance:
  Protection against OWASP Top 10, secure handling of PII, and compliant payment processing.

• Extensibility:
  Easy onboarding of new cities, theatres, languages, and future features like recommendations or dynamic pricing.

---

1.5 In-Scope and Out-of-Scope

In Scope

• Backend service design and implementation
• API design for one read scenario (browse shows)
• API design for one write scenario (ticket booking)
• Database schema design
• Concurrency, transactions, and failure handling
• High-level architecture and deployment strategy

Out of Scope

• UI / frontend implementation
• Recommendation engines or advanced AI models
• Detailed financial settlement with theatre partners
• Manual customer support workflows

---

1.6 Solution Approach Summary

The proposed solution adopts a microservices-based architecture with clear separation of concerns across catalog, search, booking, payment, and notification domains.

It leverages event-driven communication, caching, and search indexing to achieve scalability and resilience, while ensuring strong transactional guarantees for seat booking and payments.

---

2. Architecture Diagram

2.1 High-Level Architecture

The platform is designed as a cloud-native microservices system optimized for:

• Read-heavy browsing (movie discovery, theatres, show timings) using Search + Cache
• Write-critical booking (seat selection → lock → payment → confirmation) using strong consistency + idempotency
• High availability (99.99%) via stateless services, horizontal scaling, and multi-AZ persistence
• Loose coupling via an event-driven backbone for non-blocking workflows like notifications, analytics, and booking transitions

If you want, you can embed a diagram here (Mermaid, Excalidraw export, or an image). In MDX, you can also import a React diagram component.

---

2.2 Component Responsibilities

API Gateway

• Central entry point for customers and partners
• Authentication/authorization, request validation, rate limiting, WAF rules, routing
• Supports versioned APIs and throttling during peak traffic

Browse Path (Read Optimized)

Search Service + Cache handle most browse traffic:

• Search service provides low-latency browse APIs (movie → city → theatres → shows)
• Uses OpenSearch/Elasticsearch index populated via events from Catalog/Show services
• Redis caches hot keys (popular movies, cities, show listings) to reduce DB load

Booking Path (Write / Consistency Critical)

Booking Service owns:

• Seat selection validation and seat lock with TTL
• Booking state machine: INITIATED → SEATS_LOCKED → PAYMENT_PENDING → CONFIRMED / FAILED / EXPIRED
• Double-booking prevention via:
  • Redis seat locks (fast TTL-based locking) and/or
  • DB-level constraints/transactions during confirmation (final authority)

Payment Processing

Payment Service integrates with external gateways:

• Creates payment intent for a booking (idempotent)
• Handles gateway webhooks (signature verification)
• Publishes payment events (payment.succeeded, payment.failed) to Kafka

Offers & Pricing

Offer/Pricing Service:

• Centralized discount rules (e.g., “3rd ticket 50%”)
• Pluggable rule execution (Strategy pattern)
• Ensures consistent pricing during booking creation/confirmation

Notifications

Notification Service:

• Asynchronous confirmation/cancellation messages triggered by booking/payment events
• Multi-channel (SMS/Email/WhatsApp) with retries and DLQ

---

2.3 Key Data and Event Flows

Read Scenario: Browse Shows (Fast, Scalable)

1. Client calls Search APIs via Gateway (e.g., movie + city + date)
2. Search service fetches from OpenSearch + Redis cache
3. If needed, resolves freshness via show updates consumed from Kafka
4. Returns theatre list + show timings + availability summary

Design goal: keep browsing highly available even under heavy load.

Write Scenario: Book Tickets (Correctness First)

1. Client requests booking with showId + seatIds
2. Booking service locks seats (Redis TTL), creates booking (PAYMENT_PENDING)
3. Pricing calculated via Offer/Pricing service
4. Client initiates payment → Payment service creates payment intent
5. Gateway webhook triggers payment status update
6. Payment service publishes payment event to Kafka
7. Booking service consumes event and finalizes booking (CONFIRMED) or releases locks (FAILED)

Design goal: no double-booking, idempotent retries, consistent final state.

---

2.4 Architecture Decisions (Why This Works)

• Read/Write separation: browsing uses Search + Cache; booking uses strong consistency
• Event-driven workflows: decouple booking, payment, notifications, indexing
• Idempotency everywhere: protects against retries/timeouts in booking/payment
• Horizontal scalability: stateless services scale behind load balancers
• High availability: multi-AZ, retries/backoff, circuit breakers, graceful degradation

---

3. Component Descriptions

This section describes major components, responsibilities, data ownership, key APIs, and interactions.

3.1 Core Application Services

3.1.1 API Gateway

3.1.2 Catalog Service

3.1.3 Theatre & Partner Service

3.1.4 Show Service

3.1.5 Search Service

3.1.6 Booking Service

3.1.7 Offer & Pricing Service

3.1.8 Payment Service

3.1.9 Notification Service

---

3.2 Infrastructure Components

3.2.1 Cache (Redis)

3.2.2 Message Broker (Kafka)

3.2.3 Databases

---

3.3 Component Interaction Summary

• Browse path: API Gateway → Search Service → Search Index / Cache
• Booking path: API Gateway → Booking Service → Offer Service → Payment Service
• Async path: Core services → Kafka → Search/Notification consumers
• Failure isolation: booking/payment issues don’t impact browse functionality

---

3.4 Design Rationale

• Clear service boundaries enable independent scaling and deployments.
• Event-driven design improves resilience and extensibility.
• Strong transactional guarantees are limited to booking + payment.
• Read-optimized components protect the system during traffic spikes.

---

4. Booking & Seat Locking Deep Dive

This section explains how correctness and consistency are ensured under high concurrency.

4.1 Core Challenges Addressed

• Prevent double booking under concurrent requests
• Handle partial failures (payment outcomes, timeouts)
• Ensure idempotent behavior for retries
• Support high throughput while maintaining correctness
• Auto-recover abandoned bookings

The solution prioritizes data integrity for booking and availability for browsing.

---

4.2 Booking Lifecycle (State Machine)

Each booking follows a deterministic state machine owned by the Booking Service:

• INITIATED → SEATS_LOCKED → PAYMENT_PENDING → CONFIRMED → COMPLETED

Failure / Exit states:

• FAILED – payment failure or validation error
• EXPIRED – seat lock TTL expired before payment completion
• CANCELLED – user-initiated cancellation

Rules:

• Monotonic + idempotent transitions
• Only valid transitions allowed (e.g., EXPIRED → CONFIRMED rejected)
• Transitions persisted atomically in the booking DB

---

4.3 Seat Locking Strategy

Design goal: prevent two users from booking the same seat, while allowing temporary reservation during payment.

Chosen Approach: Redis Seat Lock with TTL

Each seat lock key:

• seatlock:{showId}:{seatId}

Lock acquisition:

• Booking Service uses atomic SETNX
• Lock TTL (example: 5 minutes)
• All seats must lock successfully, or booking fails

Properties:

• Atomic (exclusive ownership)
• Time-bound (TTL prevents deadlocks)
• Fast (high concurrency without DB hotspot)

Failure handling:

• If any seat lock fails:
  • Release all acquired locks
  • Reject with conflict

---

4.4 Booking Creation Flow

1. Client selects show and seats
2. Booking Service validates show status + seatIds
3. Acquire Redis seat locks
4. Create booking record in SEATS_LOCKED
5. Store booking expiry timestamp (lock TTL)
6. Calculate pricing via Offer & Pricing
7. Transition to PAYMENT_PENDING

Idempotent via client-provided Idempotency-Key.

---

4.5 Payment Orchestration

Payment initiation

• Payment Service creates payment intent with gateway
• bookingId used as idempotency key
• Payment state tracked independently

Webhook processing

• Gateway sends signed webhook callbacks
• Payment Service verifies signature and publishes:
  • payment.succeeded
  • payment.failed

Booking finalization

• Booking Service consumes payment events
• On success:
  • booking → CONFIRMED
  • seat inventory marked sold
  • seat locks released
• On failure:
  • booking → FAILED
  • locks released

---

4.6 Database Consistency Guarantees

Final authority: relational database.

Constraints:

• Unique constraint on (show_id, seat_id) for sold seats
• Transactional updates during confirmation
• Defensive checks during finalization

Dual-layer approach (Redis + DB) gives strong consistency + throughput.

---

4.7 Handling Expired Bookings

Scheduled job:

• Detect expired bookings
• Transition to EXPIRED
• Release remaining locks
• Publish booking.expired

Covers abandoned payments, client crashes, timeouts.

---

4.8 Idempotency & Retry Handling

Retries happen due to timeouts, duplicates, webhook replays.

Implementation:

• All write APIs accept Idempotency-Key
• Booking/payment deduped
• Webhooks: exactly-once logically, at-least-once physically

---

4.9 Failure Scenarios & Recovery

---

4.10 Why This Design Works

• Strong correctness guarantees
• High concurrency without DB hot-spotting
• Self-healing via TTL + background jobs
• Clear ownership of state transitions
• Scales linearly with traffic

---

5. Technology Stack

5.1 Application & Service Layer

---

5.2 API & Integration Layer

---

5.3 Data Storage Layer

Rationale

• Relational DB for ACID booking/payment
• Search index for low-latency browsing
• Redis for fast TTL locks and reduced contention

---

5.4 Messaging & Event Streaming

Events for:

• Booking state changes
• Payment outcomes
• Show/catalog updates
• Notification triggers
• Search indexing updates

---

5.5 Security & Compliance

---

5.6 Observability & Monitoring

Key metrics:

• API latency/error rates
• Seat lock contention
• Booking success/failure
• Payment success rate
• Booking expiry %

---

5.7 Deployment & Platform

---

5.8 Cloud Infrastructure

---

5.9 AI & Intelligent Capabilities (Suggested)

• Search relevance: typo tolerance, fuzzy matching
• Customer support: FAQ / booking-status bot
• Risk signals: fraud/anomaly detection
• Ops insights: demand forecasting, capacity planning

AI is pluggable and does not impact booking consistency.

---

5.10 Key Technology Drivers Summary

• Correctness first: ACID DB + controlled concurrency
• Scale on demand: stateless + cache + search
• Resilience: event-driven + graceful degradation
• Security by design: OWASP-compliant, encrypted, auditable
• Future-ready: modular services, extensible pricing + AI

---

6. Scalability & 99.99% Availability

6.1 Availability Target & Design Philosophy

99.99% uptime → less than 4.4 minutes downtime/month.

Principles:

• Stateless services
• Failure isolation (browse vs booking)
• Graceful degradation
• Automated recovery

Correctness is prioritized for booking; availability for browsing.

---

6.2 Horizontal Scalability Strategy

• Stateless microservices behind load balancers
• Kubernetes HPA based on CPU, latency, and custom metrics

---

6.3 Read-Heavy Workload Optimization

Techniques:

• Search index for denormalized reads
• Redis hot caching
• Event-driven index updates
• TTL eviction to balance freshness

Result:

• Browse APIs stay up even if transactional services degrade
• Sub-second latency during spikes

---

6.4 Write Path Scalability (Booking)

Challenges:

• Contention on popular shows
• Strict correctness

Solutions:

• Redis locks to minimize DB contention
• Shard booking data by city or showId
• Short-lived TTL locks
• Backoff retries to avoid thundering herd

Trade-off: write throughput is intentionally constrained to preserve correctness.

---

6.5 Database High Availability

Relational DB:

• Multi-AZ failover
• Read replicas for reporting
• Partitioning by city/time

Cache:

• Redis cluster with replicas + failover
• TTL recovery

Search:

• Multi-node cluster
• Shard replication and rebalancing

---

6.6 Event-Driven Resilience

Kafka provides:

• At-least-once delivery
• Idempotent consumers
• DLQs for poison messages

Ensures:

• Booking confirmation doesn’t block notifications
• Payment processing survives transient failures

---

6.7 Fault Tolerance & Graceful Degradation

---

6.8 Disaster Recovery & Multi-AZ Strategy

• Services across multiple AZs
• Load balancers spread traffic
• Automated pod restarts/rescheduling
• DB failover in minutes

Targets:

• RTO: < 5 minutes
• RPO: near-zero for bookings/payments

---

6.9 Observability-Driven Reliability

Focus:

• Golden signals: latency, traffic, errors, saturation
• Booking metrics: lock success/failure, payment rate, expiry rate

Alerts:

• SLA breach risk
• Error spikes
• Capacity thresholds

---

6.10 Why This Meets 99.99%

• No single point of failure
• Read/write isolation prevents cascading outages
• Stateless compute + auto-scaling
• Strong transactional boundaries only where needed
• Event-driven retries/recovery

---

7. Monitoring & Observability

7.1 Monitoring Objectives

• Ensure 99.99% SLA compliance
• Detect issues before customer impact
• Deep visibility into booking + payment correctness
• Faster RCA
• Capacity planning and forecasting

Monitoring is a first-class production feature.

---

7.2 Observability Pillars

1. Metrics (numbers)
2. Logs (structured debugging + audit)
3. Traces (end-to-end flow visibility)

---

7.3 Metrics Monitoring

Infrastructure:

• CPU/memory/disk/network
• Pod restarts, node health
• HPA activity

Golden signals:

Booking metrics:

• Seat lock success vs failure
• Booking creation and confirmation rate
• Booking expiry %
• Double-booking prevention triggers

Payment metrics:

• Payment initiation success
• Gateway latency
• Webhook success/failure
• Payment-to-booking conversion

---

7.4 Logging Strategy

• Structured JSON logs
• Centralized aggregation

Types:

• Application logs
• Audit logs (state transitions, payment events)
• Security logs (auth failures)

Principles:

• Correlation IDs everywhere
• Mask PII/payment data
• Retention aligned with compliance

---

7.5 Distributed Tracing

Coverage:

• Browse → search → cache → response
• Booking → lock → pricing → payment
• Webhook → confirmation → notification

Benefits:

• Find latency bottlenecks
• Detect dependency failures
• Speed up RCA

---

7.6 Alerting & Incident Response

Alerts are actionable:

• SLA near-breach
• Error spikes
• Payment gateway down
• Seat lock contention anomalies
• Resource saturation

Response:

• On-call routing
• Runbooks
• Automated recovery (restart/scale)

---

7.7 SLA & SLO Tracking

SLIs:

• API availability
• Booking success rate
• Payment completion rate

SLOs:

• ≥ 99.99% availability
• p99 latency thresholds
• acceptable booking failure %

Error budgets:

• guide release velocity vs stability
• freeze/rollback on exhaustion

---

7.8 Capacity Planning & Trend Analysis

Use monitoring data for:

• peak forecasting (releases/weekends)
• scaling validation
• performance regression detection
• cost optimization

---

7.9 Why This Works

• Combines technical + business metrics
• Proactive detection
• Fast troubleshooting
• SLA visibility always
• Scales with platform growth

---

8. Deployment & Release Strategy

8.1 Deployment Environments

Each environment is isolated (infra/config/data boundaries).

---

8.2 CI/CD Pipeline

CI:

• Build + unit tests
• Static analysis + security scans
• Container image build
• Versioned artifacts stored in registry

CD:

• Auto deploy to lower envs
• Manual approval to prod
• Config injection per env
• Immutable image promotion

---

8.3 Containerization & Orchestration

Docker:

• Each microservice packaged as image

Kubernetes (EKS):

• Rolling updates
• Liveness/readiness probes
• Auto-scaling

---

8.4 Release Strategies

• Blue-Green

  • Two identical environments
  • Switch traffic after validation
  • Instant rollback

• Canary

  • Small % traffic first
  • Gradual ramp using health metrics
  • Auto rollback on error thresholds

• Feature Flags

  • Toggle offers/pricing without redeploy
  • City/theatre rollouts

---

8.5 Zero-Downtime Guarantee

Achieved via:

• Stateless services behind LBs
• Rolling/canary
• Backward-compatible API/schema changes
• Safe DB migrations with versioning tools

---

8.6 Database Migration Strategy

• Managed via migration tools
• Prefer backward-compatible migrations
• Multi-step for breaking changes:
  1. Expand schema
  2. Deploy app changes
  3. Contract old fields
• Maintain rollback scripts

---

8.7 Multi-Region & Multi-AZ

AZ strategy:

• Services spread across AZs
• LBs distribute traffic

DR:

• DB failover
• Backup/restore drills
• RTO < 5 minutes, RPO near zero

---

8.8 Configuration & Secrets

• Centralized config
• Env-specific externalized settings
• Secrets in vault/secrets manager
• No secrets in code or images

---

8.9 Rollback & Recovery

Triggers:

• SLA breach
• Error spikes
• Payment/booking failures

Methods:

• Traffic switch (blue-green)
• Abort canary
• Disable feature flags

Fast + reversible + automated.

---

8.10 Why This Works

• Frequent safe releases
• Minimal customer impact
• Controlled experimentation
• Operational stability
• Scales with growth

---

## 9. API Contracts (Read & Write)

This section defines the backend API contracts for **one Read scenario** (browse theatres & show timings for a selected movie in a city on a given date) and **one Write scenario** (book tickets by selecting theatre/timing/seats). APIs are **RESTful**, **versioned**, and designed for **idempotency**, **concurrency safety**, and clear **error handling**.

---

### 9.1 API Standards (Common)

#### Base
- **Base URL:** `/api/v1`  
- **Content-Type:** `application/json`  
- **Auth:** `Authorization: Bearer <JWT>`

#### Idempotency (Write APIs)
- **Header:** `Idempotency-Key: <uuid>`
- Re-sending the same request with the same key returns the same logical outcome (same booking/payment intent).

#### Correlation
- **Header:** `X-Correlation-Id: <uuid>` (optional; server generates if absent)
- Returned in response headers for traceability.

#### Standard Error Format
```json
{
  "error": {
    "code": "SEAT_LOCK_FAILED",
    "message": "One or more seats are no longer available.",
    "details": {
      "showId": "sh_123",
      "unavailableSeatIds": ["A10", "A11"]
    },
    "correlationId": "c0b7f2d0-6c8d-4e6f-9c5f-3ff2f2f0f9b1"
  }
}

Common Error Codes

• VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND
• SEAT_LOCK_FAILED, BOOKING_EXPIRED, PAYMENT_PENDING, PAYMENT_FAILED
• RATE_LIMITED, INTERNAL_ERROR

---

9.2 Read Scenario APIs (Browse)

9.2.1 Browse theatres running a movie in a city (with show timings for a date)

Endpoint

• GET /api/v1/cities/{cityId}/movies/{movieId}/shows?date=YYYY-MM-DD&language=<optional>&format=<optional>

Description Returns theatres currently running the selected movie in the given city on the specified date, along with show timings and a lightweight availability summary.

Path Params

• cityId (required): City identifier (e.g., blr)
• movieId (required): Movie identifier (e.g., mv_901)

Query Params

• date (required): YYYY-MM-DD
• language (optional): e.g., en, hi, te
• format (optional): e.g., 2D, 3D, IMAX

Response 200 (Example)

{
  "cityId": "blr",
  "movie": {
    "movieId": "mv_901",
    "title": "Example Movie",
    "language": "en",
    "genres": ["Thriller", "Drama"],
    "durationMins": 128
  },
  "date": "2026-02-01",
  "theatres": [
    {
      "theatreId": "th_101",
      "name": "PVR Orion",
      "area": "Malleshwaram",
      "shows": [
        {
          "showId": "sh_5001",
          "screenName": "Screen 3",
          "startTime": "2026-02-01T18:30:00+05:30",
          "format": "2D",
          "priceFrom": 180,
          "availability": {
            "availableSeats": 72,
            "status": "AVAILABLE"
          }
        },
        {
          "showId": "sh_5002",
          "screenName": "Screen 3",
          "startTime": "2026-02-01T21:45:00+05:30",
          "format": "2D",
          "priceFrom": 220,
          "availability": {
            "availableSeats": 12,
            "status": "FAST_FILLING"
          }
        }
      ]
    }
  ]
}

Errors

• 400 VALIDATION_ERROR (invalid date format)
• 404 NOT_FOUND (city/movie not found)
• 429 RATE_LIMITED

---

9.2.2 Get seat map + real-time availability for a show

Endpoint

• GET /api/v1/shows/{showId}/seats

Description Returns seat layout and availability at the time of request. Availability is derived from:

• sold seats (DB truth)
• locked seats (Redis locks, TTL)

Path Params

• showId (required): Show identifier (e.g., sh_5001)

Response 200 (Example)

{
  "showId": "sh_5001",
  "theatreId": "th_101",
  "screenName": "Screen 3",
  "startTime": "2026-02-01T18:30:00+05:30",
  "seatMap": {
    "rows": [
      {
        "rowLabel": "A",
        "seats": [
          { "seatId": "A1", "type": "REGULAR", "price": 180, "status": "AVAILABLE" },
          { "seatId": "A2", "type": "REGULAR", "price": 180, "status": "LOCKED", "lockExpiresAt": "2026-02-01T18:05:00+05:30" },
          { "seatId": "A3", "type": "REGULAR", "price": 180, "status": "SOLD" }
        ]
      }
    ]
  }
}

Errors

• 404 NOT_FOUND (show not found)
• 429 RATE_LIMITED

Notes on seat status

AVAILABLE: Not sold and not locked LOCKED: Temporarily reserved by another booking; includes lockExpiresAt when available * SOLD: Finalized purchase (DB truth)

---

9.3 Write Scenario APIs (Booking)

9.3.1 Create booking + lock seats (Seat Reservation)

Endpoint

• POST /api/v1/bookings

Headers

• Authorization: Bearer <JWT>
• Idempotency-Key: <uuid>
• X-Correlation-Id: <uuid> (optional)

Request Body

{
  "userId": "u_2001",
  "showId": "sh_5001",
  "seatIds": ["A10", "A11"],
  "couponCode": "THIRD50",
  "client": {
    "platform": "WEB",
    "appVersion": "1.0.0"
  }
}

Behavior

• Validates showId is active and seatIds are valid
• Attempts to lock all requested seats with TTL (e.g., 5 minutes)
• Calculates price via Offer & Pricing Service
• Creates booking in PAYMENT_PENDING (or SEATS_LOCKED then transitions internally)

Response 201 (Example)

{
  "bookingId": "bk_90001",
  "status": "PAYMENT_PENDING",
  "expiresAt": "2026-02-01T18:10:00+05:30",
  "show": {
    "showId": "sh_5001",
    "theatreId": "th_101",
    "startTime": "2026-02-01T18:30:00+05:30"
  },
  "seats": ["A10", "A11"],
  "pricing": {
    "currency": "INR",
    "subtotal": 360,
    "discount": 90,
    "fees": 20,
    "tax": 12,
    "total": 302,
    "appliedOffers": [
      { "code": "THIRD50", "description": "50% off on eligible ticket" }
    ]
  }
}

Errors

• 400 VALIDATION_ERROR (invalid seatIds, show not bookable)
• 404 NOT_FOUND (show not found)
• 409 SEAT_LOCK_FAILED (one/more seats unavailable/locked)
• 410 BOOKING_EXPIRED (idempotency replay edge-case referencing expired booking)
• 429 RATE_LIMITED

---

9.3.2 Initiate payment for a booking (Create Payment Intent)

Endpoint

• POST /api/v1/bookings/{bookingId}/payments

Headers

• Authorization: Bearer <JWT>
• Idempotency-Key: <uuid>
• X-Correlation-Id: <uuid> (optional)

Request Body

{
  "provider": "RAZORPAY",
  "returnUrl": "https://app.example.com/payment/return"
}

Response 201 (Example)

{
  "paymentId": "pay_771",
  "bookingId": "bk_90001",
  "status": "INITIATED",
  "amount": 302,
  "currency": "INR",
  "provider": "RAZORPAY",
  "providerPayload": {
    "paymentIntentId": "pi_abc123",
    "redirectUrl": "https://gateway.example.com/pay/pi_abc123"
  }
}

Errors

• 404 NOT_FOUND (booking not found)
• 409 PAYMENT_PENDING (payment already initiated)
• 410 BOOKING_EXPIRED (seat lock expired)
• 422 (booking not in payable state)

State validation rules (payable)

A booking is payable only if: status is PAYMENT_PENDING and current time is before expiresAt

---

9.3.3 Payment webhook (Provider → Platform)

This endpoint is called by the payment gateway and not by the client.

Endpoint

• POST /api/v1/payments/webhooks/{provider}

Security

• Signature validation (provider-specific headers)
• Optional IP allowlist
• Idempotent handling based on eventId / provider event identifier

Webhook Payload (Example)

{
  "eventId": "evt_99001",
  "paymentIntentId": "pi_abc123",
  "status": "SUCCEEDED",
  "amount": 302,
  "currency": "INR",
  "bookingReference": "bk_90001",
  "timestamp": "2026-02-01T18:06:30+05:30"
}

Webhook Response

• 200 OK if processed (or already processed)
• 400 if signature invalid

Downstream Effect

• Payment Service publishes payment.succeeded / payment.failed event
• Booking Service consumes event and finalizes booking

---

9.3.4 Get booking status (Client polling fallback)

Endpoint

• GET /api/v1/bookings/{bookingId}

Response 200 (Example)

{
  "bookingId": "bk_90001",
  "status": "CONFIRMED",
  "confirmedAt": "2026-02-01T18:06:45+05:30",
  "ticket": {
    "ticketId": "tkt_50001",
    "qrCodeData": "BASE64_OR_TOKEN",
    "seatIds": ["A10", "A11"]
  }
}

Errors

• 404 NOT_FOUND
• 403 FORBIDDEN (booking does not belong to user)

---

9.3.5 Cancel booking (Optional but production-realistic)

Endpoint

• POST /api/v1/bookings/{bookingId}/cancel

Behavior

• If PAYMENT_PENDING and lock valid → cancel + release locks
• If already CONFIRMED → initiate refund workflow (if supported)

Response 200 (Example)

{
  "bookingId": "bk_90001",
  "status": "CANCELLED",
  "refund": {
    "status": "INITIATED",
    "amount": 302
  }
}

---

9.4 Status Codes Summary