Designing Robust Payment Systems: Idempotency Keys, State Machines & Webhook Guarantees

[ Client ] -- (Network Timeout) --> [ Payment API ] -- (Charged Successfully) --> [ Stripe / Provider ]
     |
  (User Clicks Pay Again!)
     v
💥 WITHOUT IDEMPOTENCY: User charged twice for a single order!

+--------+       1. POST /charge (Idempotency-Key: "uuid-123")      +------------+
| Client | -------------------------------------------------------> | Payment API|
+--------+                                                          +------------+
                                                                          |
                                      +-----------------------------------+-----------------------------------+
                                      | 2. Check Redis lock for key                                           |
                                      v                                                                       v
                            [ First Request ]                                                      [ Replay / Duplicate ]
                                      |                                                                       |
                          Process Charge with Gateway                                              Return Cached Response
                                      |                                                                  Immediately
                          Cache Final Response in DB                                                          |
                                      |                                                                       |
                                      +-----------------------------------> [ Return 200 OK ] <---------------+

  [ INITIATED ] ---> [ PROCESSING ] ---> [ SUCCEEDED ]
                            |
                            +-----------> [ FAILED ]

@Post('stripe-webhook')
async handleWebhook(@Req() req: RawBodyRequest<Request>, @Headers('stripe-signature') sig: string) {
  let event: Stripe.Event;

  try {
    // 1. Verify cryptographic signature
    event = this.stripe.webhooks.constructEvent(req.rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET);
  } catch (err) {
    throw new BadRequestException('Webhook signature verification failed');
  }

  // 2. Prevent duplicate event processing via idempotent DB record
  const existingEvent = await this.prisma.paymentEvent.findUnique({ where: { eventId: event.id } });
  if (existingEvent) return { received: true };

  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object as Stripe.PaymentIntent;
    await this.paymentService.markOrderPaid(paymentIntent.metadata.orderId, paymentIntent.id);
  }

  await this.prisma.paymentEvent.create({ data: { eventId: event.id, type: event.type } });
  return { received: true };
}