Design Razorpay's Payment Gateway with Retry and Idempotency

Problem

Design the core payment gateway that processes card and UPI transactions for Razorpay merchants.

Requirements

Functional:

• Merchant initiates payment → user pays → confirmation webhook sent to merchant
• Support retries without double-charging
• Support payment status polling
• Refund initiation

Non-functional:

• 100K transactions/minute at peak
• Exactly-once processing (idempotency)
• < 2s end-to-end p99
• 99.99% uptime

Critical discussion topics

1. Idempotency key design and storage
2. State machine for payment lifecycle (created → processing → success/failed/refunded)
3. Outbox pattern for reliable webhook delivery
4. Handling bank timeout vs bank failure (different retry strategies)
5. PCI-DSS compliance implications on your architecture