System Design Interview: Design a Payment Service

Before drawing anything, ask these:

• "What countries and payment methods are we supporting?"
• "What is the expected transaction volume — transactions per second?"
• "Are we building for a marketplace (split payments) or a direct merchant?"
• "Do we need recurring/subscription payments or one-time only?"
• "What are the consistency requirements — can we tolerate eventual consistency or do we need strong consistency for order status?"

Taking 2-3 minutes to ask these before touching the whiteboard signals seniority. Junior candidates jump to drawing. Senior candidates clarify.

Client Browser
     |
     | POST /checkout/start
     v
Checkout Service ──── POST /transaction/initialize ──→ Paystack API
     |                                                      |
     | returns authorization_url                            | webhook
     |                                                      v
Customer Browser ←── redirect to Paystack checkout    Webhook Receiver
     |                                                      |
     | (after payment) redirect to callback URL             | validate HMAC
     |                                                      | deduplicate on reference
     v                                                      v
Callback Handler                                      Order Service
     |                                                      |
     | GET /transaction/verify/:ref                         | update orders SET status='paid'
     v                                                      | trigger fulfillment
  Paystack API                                              v
                                                      Fulfillment Service
                                                      (email, access grant, etc.)

Key database tables: orders (reference, amount, status, customer_id, created_at, paid_at), webhook_events (event_id, reference, event_type, processed_at) — the second table is your idempotency store.

Your interviewer wants to hear you think about failure:

• Webhook never arrives — the callback redirect triggers verification. Both paths call the same fulfillment logic through the same idempotency check. Neither path double-fulfills.
• DB write fails after Paystack confirms — use a database transaction: update order status and insert webhook event in one atomic operation. If the transaction fails, the webhook will be retried by Paystack and succeed on the next attempt (idempotency store is checked first).
• Duplicate webhooks — insert into webhook_events with a UNIQUE constraint on (reference, event_type). Duplicate insert → constraint violation → return 200 → skip fulfillment.
• Paystack API is down — checkout initialization fails gracefully with a user-friendly error. No partial orders. Retry from client.

See system design: payout system for the payout-specific version.

Sign up for the McTaba newsletter