Designing a payment system

Designing a backend for a payment system is a task where correctness is the absolute priority. Unlike other systems where a minor bug might only degrade user experience, a failure in a payment flow can lead to financial loss for users or the platform. The following blueprint outlines the essential steps and architectural decisions required to build a reliable system that integrates with Payment Service Providers (PSPs) like Stripe or PayPal.

Core Integration Approaches

When building for payments, there are three primary paths to consider, each with its own trade-offs between speed-to-market and control:

No-Code Solutions: Utilizing hosted checkout pages or payment links provided by PSPs. This is the fastest way to go live and requires minimal development effort, but offers the least customization and brand control.
Building a Payment Processor: Directly connecting to card networks (Visa/Mastercard). This path requires massive upfront costs, years of licensing, stringent PCI compliance, and extensive legal work. It's typically only feasible for companies at an Amazon-scale due to the extremely low transaction fees it can achieve.
Integrating a PSP: The most popular choice for the vast majority of companies. Payment Service Providers (PSPs) like Stripe, PayPal, or Adyen handle the complexities of card network integrations, fraud detection, and banking relationships. This approach allows your business to maintain significant control over your backend logic and user experience without the immense overhead of becoming a processor yourself.

Key Requirements for Payment Systems

check_circle Exactly-Once Processing: You must ensure that a user is never charged twice for the same purchase, nor is a payment ever lost. This is paramount for trust and financial integrity.
verified_user Consistency over Availability: In accordance with the CAP theorem, payment systems must prioritize data consistency over availability. An incorrect balance or transaction status is far worse than a brief period of downtime. Your system must always reflect the true financial state.
lock_open Idempotency: The system must be idempotent at every layer—from the client request to the backend and the communication with the PSP. Retrying an operation multiple times should produce the same result as performing it once.

The 3-Phase Payment Life Cycle

Money movement typically follows three distinct phases, each critical to a successful transaction:

Authorization: The cardholder submits their payment details. Your system creates a "Payment Intent" (a stateful object tracking the transaction), and the issuing bank validates the funds and places a hold on the specified amount. No money moves yet, but the funds are reserved.
Capture: The merchant finalizes the authorized amount. This can be immediate for digital goods or services (e.g., streaming subscriptions) or delayed until fulfillment for physical products (e.g., shipping a tangible item). Upon capture, the actual transfer of funds is initiated.
Settlement: At the end of the business day (or a defined cycle), captured transactions are batched by the PSP, and the aggregated funds (minus processing fees) are transferred to the merchant's bank account. This is when the money truly lands in your business account.

Technical Architecture: Synchronous vs. Asynchronous Paths

A robust, senior-level architecture for payments separates work into synchronous (user-facing, immediate feedback) and asynchronous (background processing, data integrity) paths to maximize responsiveness and reliability.

Synchronous Path (User Experience)

This path focuses on the immediate interaction with the user, ensuring a smooth and secure checkout experience.

Front-end: Implements secure IFrames (like Stripe Elements, PayPal Smart Buttons, etc.) to ensure sensitive card data never hits your servers directly. This significantly reduces your PCI compliance scope. The front-end receives a client secret from your backend to confirm the payment intent with the PSP.
Payment API: Your backend API (e.g., a REST endpoint) validates the incoming request, checks for idempotency keys against your database to prevent duplicate submissions, creates a payment record in your system, and then communicates with the PSP to create a "Payment Intent" (or equivalent). It returns a `client_secret` to the front-end, allowing it to securely complete the transaction directly with the PSP.

terminal api/createPaymentIntent.js Node.js (Express/Stripe)


const stripe = require('''stripe''')(process.env.STRIPE_SECRET_KEY);

exports.createPaymentIntent = async (req, res) => {
  const { amount, currency, idempotencyKey } = req.body;

  // 1. Check idempotency key to prevent duplicate processing
  const existingPayment = await getPaymentRecord(idempotencyKey);
  if (existingPayment) {
    return res.status(200).json({ clientSecret: existingPayment.clientSecret });
  }

  try {
    const paymentIntent = await stripe.paymentIntents.create({
      amount: amount,
      currency: currency,
      // You might pass idempotencyKey to Stripe too, if supported
    });

    // 2. Store internal payment record with idempotency key and client secret
    await savePaymentRecord({
      idempotencyKey,
      paymentIntentId: paymentIntent.id,
      clientSecret: paymentIntent.client_secret,
      status: '''created''',
      amount,
      currency
    });

    res.status(200).json({ clientSecret: paymentIntent.client_secret });
  } catch (error) {
    console.error('''Error creating payment intent:''', error);
    res.status(500).json({ error: error.message });
  }
};

Asynchronous Path (Data Integrity & Reconciliation)

This critical path handles post-transaction processing, status updates, and ensures your system'''s ledger remains consistent with the PSP'''s records.

Web-hook Receiver: This dedicated endpoint listens for status updates from the PSP (e.g., `payment_intent.succeeded`, `charge.refunded`). It must immediately verify the signature of the incoming webhook (to ensure authenticity), store the raw event payload in your database, and respond with a `200 OK` to the PSP to avoid timeouts and prevent the PSP from retrying the webhook unnecessarily.
Message Queue: A robust message queue (e.g., Kafka, RabbitMQ, SQS) decouples the receipt of web-hooks from their processing. This ensures that even if background workers fail or are temporarily unavailable, the events are not lost and can be processed later.
Background Workers: These workers consume messages from the queue. They handle state transitions (e.g., updating a `PaymentIntent` from `authorized` to `captured`), apply business logic, perform retries with exponential backoff for failed operations, and are crucial for daily reconciliation between your internal ledger and the PSP'''s records.

Database and Ledger Design

To track payments accurately and maintain financial integrity, your database design must be more than just a list of transactions:

Idempotency Keys Table: Stores unique keys submitted by clients or generated internally. It should include a "Recovery Point" or status to track the progress through multi-step operations. This allows a retry of an operation to resume from the last successful step rather than restarting the whole payment flow, significantly improving resilience.
Immutable Audit Log: Every significant state transition or event related to a payment should generate a new, immutable entry in a dedicated events table. No rows are ever updated; the history remains append-only. This provides a transparent, unalterable record of all changes, crucial for debugging, auditing, and compliance.
Double-Entry Ledger: The gold standard for financial systems. Every money movement is recorded as a balanced pair of debit and credit entries across different accounts (e.g., "Customer A" account debits, "Platform Revenue" account credits). It is strictly append-only; mistakes are corrected with new, reversing entries, never by deleting or modifying existing ones. This ensures that the sum of all debits always equals the sum of all credits, guaranteeing financial balance.

Reliability Patterns for Payment Systems

Building a truly robust payment system requires implementing several critical reliability patterns:

Optimistic Locking: Use a version column (or `updated_at` timestamp) and "compare-and-swap" logic on status transitions to prevent concurrent updates from corrupting data. If two processes try to update the same payment record simultaneously, only one succeeds, and the other is instructed to retry or handle the conflict.
Finite State Machine (FSM): Enforce strict valid transitions for your payment objects. For example, a `PaymentIntent` cannot jump directly from `created` to `captured` without first being `authorized`. This prevents invalid states and ensures the payment lifecycle is followed correctly.
Circuit Breakers: Implement circuit breakers for all external PSP API calls. If the external service (e.g., Stripe'''s API) is slow or experiencing downtime, the circuit breaker "trips," preventing further calls and ensuring your internal threads remain free to handle other requests. This protects your system from cascading failures due to external dependencies.
Dead-Letter Queues (DLQs): For your message queues, configure DLQs. If a message fails to be processed by background workers after a certain number of retries, it'''s moved to a DLQ for manual inspection and reprocessing. This ensures no event is permanently lost, even in the face of persistent processing errors.
Comprehensive Monitoring & Alerting: Implement detailed monitoring for all payment-related metrics: success rates, error rates, latency of PSP calls, webhook processing times, and ledger balances. Set up immediate alerts for any anomalies, failed transactions, or discrepancies.

Designing a payment system is not merely a coding exercise; it'''s an exercise in defensive architecture and financial accountability. By meticulously implementing these patterns and adhering to a "correctness above all" mindset, you can build a payment backbone that is not only functional but truly robust and trustworthy.