Slot Booking & Paytm Payment LLD

The user is not buying a generic product. The user is trying to own one exact time window on one exact ground. Two users can see the same Available slot, two payment sessions can be opened, and Paytm can report the result later through either client verification or webhook.

The design therefore separates a temporary claim from a confirmed booking. A claim blocks other users for a short payment window, but the slot is not marked Booked until payment success is reconciled and the claim is still valid.

BookingSlot is the slot source of truth. It belongs to one ground, has startAt/endAt, and has status Available, Booked, or Blocked. The unique pair groundId plus startAt prevents duplicate generated slots for the same ground time.

GroundBooking is the payment-aware claim record. It stores userId, groundDetailsId, bookingSlotId, sportId, totalPrice, paymentStatus, bookingStatus, Paytm order fields, attempt number, and holdExpiresAt.

The create flow first rejects impossible requests: unverified mobile, slot not found, slot/ground mismatch, unsupported sport, inactive or maintenance ground, inactive or maintenance venue, tournament-only venue, past or too-near slots, and already Booked or Blocked slots.

Pricing is resolved before the hold is created. That matters because a same-user active hold can only be reused when sport, pricing rule, side count, turf mode, and base amount still match.

The critical section is the BookingSlot row. The code runs SELECT FOR UPDATE with a lock timeout, then checks active claims for the slot inside the transaction. That makes two concurrent create requests serialize instead of both creating valid holds.

The database hold is the durable rule. Redis is a mirror with the same expiry so other reads can cheaply understand that a slot is temporarily held. Releasing the Redis hold uses a compare-and-delete script so one booking cannot delete another booking's hold.

Paytm initiation returns a txnToken and retry hints. The booking stores the latest Paytm order fields, while GroundBookingPaymentAttempt stores the attempt snapshot and provider payload.

Payment success is never trusted blindly. Client verify and Paytm payment webhook both enter the same shape of reconciliation: find the booking by order id, lock the slot, validate that the current booking owns the order and current attempt, confirm hold expiry has not passed, and then update the slot from Available to Booked.

Refund is the escape hatch for real-world payment races. If Paytm captures money after the hold expired, after a newer attempt superseded the order, or after the slot is no longer Available, the booking moves to a cancelled refund state instead of stealing the slot.

Refund status can be driven by explicit refund status checks or Paytm refund webhooks. The system records Paytm refund reference, refund id, provider status, message, result code, and the latest provider payload for audit and support.

A normal refund for an already Booked slot is stricter: the booking must be Paid/Booked, the slot must not have started, Paytm transaction id must be known or resolvable, and the slot is blocked after refund initiation so the cancelled time is not resold accidentally.