Payment integration architecture in HLD - System Design Guide

Problem Statement

When a system processes payments directly without a clear integration architecture, it risks exposing sensitive data, facing compliance issues, and experiencing failures that disrupt user transactions. Without a robust payment integration design, the system can become unreliable, insecure, and difficult to maintain or scale as transaction volume grows.

Solution

Payment integration architecture separates the payment processing logic from the core application by using dedicated payment gateways and services. It securely routes payment requests through APIs, handles retries and failures gracefully, and ensures compliance by isolating sensitive data. This design also supports multiple payment methods and scales by decoupling payment workflows from business logic.

Architecture

User App

(Frontend)

→Payment API

↓

Payment

Service Layer

↓

Database /

Transaction

This diagram shows how user payment requests flow from the frontend app through a payment API gateway to external payment gateways. The payment service layer handles business logic, fraud detection, and transaction logging.

Trade-offs

✓ Pros

→

Improves security by isolating payment data and using secure gateways.

→

Enhances reliability with retry mechanisms and failure handling.

→

Supports multiple payment methods and providers easily.

→

Simplifies compliance with PCI DSS by limiting sensitive data exposure.

✗ Cons

→

Adds architectural complexity and requires careful API design.

→

Increases latency due to multiple network calls and external dependencies.

→

Requires ongoing maintenance of integration with third-party payment providers.

Use when your system handles real money transactions, requires PCI compliance, or expects to scale beyond a few hundred transactions per minute.

Avoid if your application only simulates payments or handles very low transaction volumes (under 100 per day) where direct integration overhead is unnecessary.

Real World Examples

Uber

Uber uses payment integration architecture to securely process millions of ride payments daily, supporting multiple payment methods and handling retries for failed transactions.

Shopify

Shopify integrates with multiple payment gateways to allow merchants worldwide to accept payments securely and comply with regional regulations.

Stripe

Stripe provides a payment gateway service that abstracts payment processing complexities for developers, enabling easy integration and compliance.

Alternatives

Direct Payment Processing

The application handles payment logic and communication with payment providers directly without an intermediary layer.

Use when: Choose when transaction volume is very low and simplicity is more important than scalability or compliance.

Hosted Payment Page

Redirects users to a third-party hosted payment page instead of processing payments within the app.

Use when: Choose when you want to minimize PCI compliance scope and reduce development effort.

Summary

Payment integration architecture separates payment processing from core business logic to improve security and reliability.

It uses API gateways and dedicated services to handle multiple payment methods and compliance requirements.

This design supports scaling transaction volume and managing failures without disrupting user experience.

Practice

1. Which component in a payment integration architecture is primarily responsible for securely transmitting payment data between your system and the bank?

easy

A. Payment Gateway

B. Merchant Database

C. User Interface

D. Inventory Management System

Solution

1. Step 1: Understand the role of each component

   The Payment Gateway acts as the secure bridge that transmits payment data from your system to the bank or processor.

2. Step 2: Identify the secure transmission responsibility

   Other components like Merchant Database or User Interface do not handle secure transmission of payment data.

3. Final Answer:

   Payment Gateway -> Option A

4. Quick Check:

   Secure transmission = Payment Gateway [OK]

Hint: Payment Gateway always handles secure payment data transfer [OK]

Common Mistakes:

• Confusing Payment Gateway with Merchant Database
• Thinking User Interface handles security
• Assuming Inventory Management is involved in payments

2. Which of the following is the correct sequence of steps in a typical payment integration flow?

easy

A. Bank -> Payment Processor -> Payment Gateway -> User initiates payment

B. User initiates payment -> Payment Gateway -> Payment Processor -> Bank

C. Payment Processor -> User initiates payment -> Bank -> Payment Gateway

D. Payment Gateway -> Bank -> User initiates payment -> Payment Processor

Solution

1. Step 1: Identify the logical payment flow

   The user starts the payment, which goes to the Payment Gateway, then to the Payment Processor, and finally to the Bank for authorization.

2. Step 2: Verify the order of components

   Options B, C, and D have incorrect sequences that do not match the real-world payment flow.

3. Final Answer:

   User initiates payment -> Payment Gateway -> Payment Processor -> Bank -> Option B

4. Quick Check:

   Payment flow order = A [OK]

Hint: Payment always starts with user and ends at bank authorization [OK]

Common Mistakes:

• Reversing the order of components
• Placing Bank before Payment Gateway
• Confusing Payment Processor and Gateway roles

3. Consider this simplified payment request flow in pseudocode:

sendPaymentRequest(userData) {
  gatewayResponse = callPaymentGateway(userData)
  if (gatewayResponse.status == 'success') {
    processorResponse = callPaymentProcessor(gatewayResponse.data)
    return processorResponse.status
  } else {
    return 'failed'
  }
}

What will be the output if callPaymentGateway returns {status: 'success', data: 'txn123'} and callPaymentProcessor returns {status: 'approved'}?

medium

A. 'txn123'

B. 'success'

C. 'failed'

D. 'approved'

Solution

1. Step 1: Analyze the gateway response

   The gateway returns status 'success' and data 'txn123', so the if condition is true and the processor is called.

2. Step 2: Analyze the processor response

   The processor returns status 'approved', which is returned by the function.

3. Final Answer:

   'approved' -> Option D

4. Quick Check:

   Processor status returned = 'approved' [OK]

Hint: If gateway success, processor status is final output [OK]

Common Mistakes:

• Returning gateway status instead of processor status
• Returning transaction data instead of status
• Ignoring the else branch

4. In a payment integration system, a developer notices that payment requests sometimes fail silently without error logs. Which is the most likely cause?

medium

A. Missing error handling after calling the payment gateway

B. Using HTTPS for communication

C. Encrypting payment data before sending

D. Validating user input before payment

Solution

1. Step 1: Identify silent failure cause

   Silent failures usually happen when errors are not caught or logged properly, indicating missing error handling.

2. Step 2: Evaluate other options

   Using HTTPS, encrypting data, and validating input improve security and correctness but do not cause silent failures.

3. Final Answer:

   Missing error handling after calling the payment gateway -> Option A

4. Quick Check:

   Silent failure = Missing error handling [OK]

Hint: Silent failures mean errors are not caught or logged [OK]

Common Mistakes:

• Blaming HTTPS or encryption for failures
• Ignoring the need for error handling
• Assuming validation causes silent failures

5. You are designing a payment integration system expected to handle 10,000 transactions per second. Which architectural choice best supports scalability and reliability?

hard

A. Store all payment data in a single database table without sharding

B. Process all payments synchronously in a single server to ensure order

C. Use asynchronous message queues between components and horizontally scale payment processors

D. Skip retries on failed payments to reduce load

Solution

1. Step 1: Identify scalability needs

   Handling 10,000 TPS requires distributing load and decoupling components to avoid bottlenecks.

2. Step 2: Evaluate architectural choices

   Asynchronous queues and horizontal scaling allow parallel processing and fault tolerance. Single server or unsharded DB cause bottlenecks. Skipping retries reduces reliability.

3. Final Answer:

   Use asynchronous message queues between components and horizontally scale payment processors -> Option C

4. Quick Check:

   High TPS needs async queues + horizontal scaling [OK]

Hint: Scale horizontally and use async queues for high throughput [OK]

Common Mistakes:

• Choosing synchronous single server processing
• Ignoring database sharding or partitioning
• Skipping retries reduces payment reliability