Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
372 lines (287 loc) · 10.8 KB

ARCHITECTURE.md

File metadata and controls

372 lines (287 loc) · 10.8 KB
Raw

System Architecture

Overview

The TSP Payment Gateway uses a payment orchestration architecture that connects merchants with multiple payment providers through a unified platform.

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Merchants                              │
│                  (E-commerce, SaaS, etc.)                   │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              TSP Payment Gateway Platform                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              API Layer                               │  │
│  │  (OAuth, Checkout, Settlement, Webhooks)            │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │         Business Logic Layer                         │  │
│  │  (Routing, Fee Calculation, Reconciliation)          │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │         Data Layer                                   │  │
│  │  (Merchants, Transactions, Settlements)              │  │
│  └──────────────────────────────────────────────────────┘  │
└──────────────────────┬──────────────────────────────────────┘
                       │
         ┌─────────────┼─────────────┐
         │             │             │
         ▼             ▼             ▼
    ┌─────────┐  ┌─────────┐  ┌─────────┐
    │ Stripe  │  │ PayPal  │  │ Adyen   │
    │ Connect │  │Commerce │  │ (Future)│
    └─────────┘  └─────────┘  └─────────┘
         │             │             │
         └─────────────┼─────────────┘
                       │
                       ▼
            ┌──────────────────────┐
            │  Payment Networks    │
            │  (Visa, Mastercard)  │
            └──────────────────────┘

Component Architecture

1. API Layer

Responsibilities:

  • Handle merchant requests
  • Manage OAuth authentication
  • Process payment requests
  • Handle webhooks
  • Provide settlement data

Key Endpoints:

  • POST /merchants/connect - OAuth initiation
  • POST /payments - Create payment
  • GET /payments/{id} - Get payment status
  • POST /refunds - Create refund
  • GET /settlements - Get settlement data
  • POST /webhooks - Receive provider webhooks

2. Business Logic Layer

Responsibilities:

  • Route payments to appropriate provider
  • Calculate application fees
  • Handle payment reconciliation
  • Manage merchant onboarding
  • Process refunds and disputes

Key Components:

  • Router: Determines which provider to use
  • Fee Calculator: Calculates platform fees
  • Reconciliation Engine: Matches transactions
  • Settlement Manager: Manages payouts
  • Dispute Handler: Handles chargebacks

3. Data Layer

Responsibilities:

  • Store merchant data
  • Store transaction data
  • Store settlement data
  • Maintain audit logs
  • Provide data access

Key Tables:

  • merchants - Merchant information
  • transactions - Payment transactions
  • settlements - Settlement records
  • refunds - Refund records
  • webhooks - Webhook logs
  • audit_logs - Compliance audit trail

4. Integration Layer

Responsibilities:

  • Connect to payment providers
  • Handle provider-specific logic
  • Normalize provider responses
  • Implement provider webhooks

Supported Providers:

  • Stripe Connect
  • PayPal Commerce Platform
  • Adyen (future)

Data Flow

Payment Processing Flow

1. Merchant initiates payment
   └─> POST /payments
   
2. Platform validates request
   └─> Check merchant, amount, currency
   
3. Platform routes to provider
   └─> Determine best provider
   
4. Platform creates payment intent
   └─> Stripe/PayPal creates transaction
   
5. Customer completes payment
   └─> 3D Secure, card details, etc.
   
6. Provider confirms payment
   └─> Sends webhook to platform
   
7. Platform updates database
   └─> Stores transaction record
   
8. Platform notifies merchant
   └─> Webhook to merchant
   
9. Platform receives settlement
   └─> Funds arrive in merchant account
   
10. Platform receives application fee
    └─> Fee arrives in platform account

Settlement Flow

1. Provider settles transactions
   └─> Daily or weekly settlement
   
2. Funds arrive in merchant account
   └─> Provider transfers to merchant
   
3. Platform fees arrive
   └─> Provider transfers to platform
   
4. Platform reconciles
   └─> Matches transactions to settlements
   
5. Platform notifies merchant
   └─> Settlement report sent
   
6. Platform records settlement
   └─> Updates database

Technology Stack

Backend

  • Language: Python or Node.js
  • Framework: Flask/FastAPI or Express
  • Database: PostgreSQL
  • Cache: Redis
  • Message Queue: RabbitMQ or SQS

Frontend

  • Framework: React or Vue.js
  • UI Library: Material-UI or Tailwind CSS
  • State Management: Redux or Vuex

Infrastructure

  • Cloud: AWS or GCP
  • Container: Docker
  • Orchestration: Kubernetes
  • CI/CD: GitHub Actions or GitLab CI

Monitoring

  • Metrics: Prometheus
  • Logging: ELK Stack or CloudWatch
  • Tracing: Jaeger or DataDog
  • Alerting: PagerDuty

Security Architecture

Data Protection

  • Encryption at Rest: AES-256
  • Encryption in Transit: TLS 1.3
  • Key Management: AWS KMS or HashiCorp Vault

Authentication & Authorization

  • Merchant Auth: OAuth 2.0
  • API Auth: API Keys + HMAC
  • Internal Auth: JWT tokens

PCI DSS Compliance

  • Level: SAQ A (Hosted Fields only)
  • Scope: Minimal card data handling
  • Certification: Annual audit

Fraud Prevention

  • Transaction Monitoring: Real-time rules engine
  • Velocity Checks: Limit transaction frequency
  • Geolocation Checks: Detect suspicious locations
  • Device Fingerprinting: Track devices

Scalability Architecture

Horizontal Scaling

  • Stateless API servers: Multiple instances behind load balancer
  • Database replication: Read replicas for scaling reads
  • Caching layer: Redis for frequently accessed data
  • Message queue: Async processing of webhooks

Performance Optimization

  • Database indexing: Optimize query performance
  • Query optimization: Reduce N+1 queries
  • Connection pooling: Reuse database connections
  • API caching: Cache provider responses

Monitoring & Observability

  • Metrics: Track system performance
  • Logs: Centralized logging
  • Traces: Distributed tracing
  • Alerts: Proactive alerting

Deployment Architecture

Development Environment

  • Local development with Docker
  • Local database
  • Mock payment providers

Staging Environment

  • Staging server (AWS/GCP)
  • Staging database
  • Stripe/PayPal test accounts

Production Environment

  • Production servers (AWS/GCP)
  • Production database with backups
  • Stripe/PayPal live accounts
  • CDN for static assets

Integration Points

Stripe Connect

  • OAuth for merchant onboarding
  • Payment Intent API for payments
  • Webhooks for payment updates
  • Payout API for settlements

PayPal Commerce Platform

  • Partner Referrals API for onboarding
  • Orders API for payments
  • Webhooks for updates
  • Reporting API for settlements

Regulatory Systems

  • AML/KYC providers
  • Compliance monitoring
  • Audit logging
  • Regulatory reporting

Key Design Patterns

1. Payment Orchestration

Route payments to multiple providers based on:

  • Merchant preference
  • Provider availability
  • Cost optimization
  • Geographic coverage

2. Idempotency

Prevent duplicate charges by:

  • Using idempotency keys
  • Caching request results
  • Checking for duplicates
  • Retrying safely

3. Event-Driven Architecture

Use events for:

  • Webhook processing
  • Async notifications
  • Audit logging
  • Analytics

4. Circuit Breaker

Handle provider failures by:

  • Monitoring provider health
  • Failing fast
  • Falling back to alternative provider
  • Alerting on failures

Disaster Recovery

Backup Strategy

  • Database: Daily backups, 30-day retention
  • Code: Version control with GitHub
  • Secrets: Encrypted in vault
  • Logs: Archived for 1 year

Recovery Procedures

  • RTO (Recovery Time Objective): 1 hour
  • RPO (Recovery Point Objective): 15 minutes
  • Failover: Automatic to standby system
  • Testing: Monthly disaster recovery drills

Future Architecture Considerations

Planned Enhancements

  • Additional payment providers (Adyen, Square)
  • Real-time settlement
  • Advanced routing algorithms
  • Machine learning for fraud detection
  • Blockchain integration (future)

Scalability Roadmap

  • Microservices architecture (Year 2)
  • Event streaming (Kafka)
  • GraphQL API
  • Mobile app

References

  • See docs/TECHNICAL.md for detailed technical specification
  • See knowledge-base/ARCHITECTURE_PATTERNS.md for design patterns
  • See examples/ for code examples

Document Version: 1.0
Last Updated: June 2026
Prepared For: Technical Teams