Amr Samir | Payment System Architecture & Idempotency Keys

1. The Core Golden Rules of Financial Engineering

In payment architectures, failure is inevitable: network drops, third-party timeouts, duplicate requests, and async race conditions. A production payment gateway must guarantee:

Never Double Charge a Customer.

Never Deliver Goods Without Verified Payment.

Always Reconcile Asynchronous State Inconsistencies.

code

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

2. Idempotency Keys Architecture

code

+--------+       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 ] <---------------+

4. Verifying Webhooks Asynchronously

typescript

@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 };
}

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

Recommended Posts

Docker & Kubernetes — From Containerization to Cluster Orchestration

Reliable User Registration: Solving the Dual-Write Problem with Transactional Outbox

Building Resilience Against Third-Party Outages: Circuit Breakers & Exponential Backoff

Related Projects

Related Certificates

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

1. The Core Golden Rules of Financial Engineering

2. Idempotency Keys Architecture

3. Strict State Machine Design

4. Verifying Webhooks Asynchronously

5. Summary Checklist