Skip to main content
Chargeworx is an enterprise payment processing platform built on a multi-layered architecture with clear separation of concerns. The system handles payment transactions, chargebacks, account updates, and comprehensive reporting across multiple payment processors.

​
Architecture overview

The platform follows a layered architecture pattern with distinct responsibilities: 
┌─────────────────────────────────────────────────────────┐
│                    Presentation Layer                    │
│  ┌──────────────────┐         ┌──────────────────┐     │
│  │  Admin UI (MVC)  │         │   REST API       │     │
│  │  - Web Portal    │         │   - Swagger      │     │
│  │  - SignalR       │         │   - OAuth2       │     │
│  └──────────────────┘         └──────────────────┘     │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                     Domain Layer                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Business Logic & Orchestration                   │  │
│  │  - Transaction Management                         │  │
│  │  - Payment Processor Integration                  │  │
│  │  - Anti-Fraud Services                            │  │
│  │  - Import/Export Services                         │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                      Data Layer                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │   Main   │  │  Credit  │  │   Key    │  │ Report │ │
│  │    DB    │  │  Card DB │  │    DB    │  │   DB   │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                  External Integrations                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ CyberSource  │  │    PayPal    │  │     AWS      │ │
│  │   SOAP/REST  │  │  Payflow Pro │  │   Services   │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────┘

​
Core components

​
Presentation layer

Admin UI (Chargeworx.Admin)
  • ASP.NET Core MVC web application
  • Cookie-based authentication with optional MFA
  • Real-time notifications via SignalR
  • Company and project management
  • Transaction monitoring and reporting
  • User invitation system
  • Background process monitoring
REST API (Chargeworx.Api)
  • ASP.NET Core Web API
  • OAuth2 authentication via IdentityServer4
  • Swagger/OpenAPI documentation
  • Three controller domains:
    • Admin: Company, project, user, and transaction management
    • Payment: Transaction processing and payment info
    • Internal: Payflow callbacks and internal operations

​
Domain layer

Business logic (Chargeworx.Api.Domain)
  • Transaction orchestration and processing
  • Payment processor integration (CyberSource, PayPal)
  • Anti-fraud service integration
  • Account updater management
  • Chargeback and refund processing
  • Import/export services
  • Email notification services
  • Report generation
Core models (Chargeworx.Api.Core)
  • Domain models and DTOs
  • Validation attributes
  • Enums and constants
  • Request handlers

​
Data layer

Multi-database architecture (Chargeworx.Api.Data) The platform uses four separate databases for security and scalability:
  1. Main database (ChargeworxDb)
    • Companies, projects, users
    • Transactions and transaction events
    • Payment processors and configurations
    • Background processes
    • Import batches
  2. Credit card database (ChargeworxCreditCardDb)
    • Encrypted credit card information
    • Credit card batches for account updater
    • Credit card updater status tracking
  3. Key database (ChargeworxKeyDb)
    • RSA encryption keys
    • API keys and access tokens
    • IdentityServer client secrets
    • Settings metadata
  4. Report database (ChargeworxReportDb)
    • Denormalized transaction data for reporting
    • Transaction tags and custom fields
    • Account updater history
Data access patterns
  • Entity Framework Core with code-first migrations
  • Repository pattern via stores
  • Stored procedures for complex queries
  • Bulk operations for imports

​
Payment processing

Payment processor integration (Chargeworx.PaymentProcessor)
  • CyberSource SOAP and REST API integration
  • PayPal Payflow Pro integration
  • Account updater service
  • Chargeback report processing
  • Secure file transfer for batch operations

​
Cross-cutting concerns

Security
  • OAuth2 client credentials flow
  • IdentityServer4 for token management
  • RSA and AES encryption for sensitive data
  • IP whitelisting
  • MFA for admin users
Caching
  • Pluggable cache provider (in-memory or Redis)
  • Response caching for API endpoints
  • Distributed cache for session management
Logging
  • log4net for application logging
  • Request logging middleware
  • Structured logging with correlation IDs
  • Error tracking and monitoring
Background processing
  • Background process queue
  • Priority-based execution
  • Status tracking and monitoring
  • Automatic retry logic

​
Key features

​
Multi-tenancy

The platform supports multiple companies and projects:
  • Company: Top-level organization
  • Project: Payment configuration within a company
  • Users: Can belong to multiple companies and projects
  • Isolation: Data is isolated by company and project

​
Payment processing

  • Authorization: Reserve funds on a card
  • Capture: Settle authorized transactions
  • Refund: Return funds to customer
  • Void: Cancel an authorization
  • Recurring billing: Billing agreements for subscriptions

​
Account updater

Automatic credit card update service:
  • Batch creation and submission
  • Secure file transfer to CyberSource
  • Result processing and card updates
  • Status tracking per card

​
Chargeback management

Automated chargeback processing:
  • Daily report downloads
  • Transaction matching
  • Reversal transaction creation
  • Merchant notifications

​
Reporting

Comprehensive reporting capabilities:
  • Transaction reports with custom filters
  • Chargeback reports
  • Account updater reports
  • Export to CSV
  • Saved report configurations

​
Import/export

Bulk data operations:
  • Transaction import from CSV
  • Payment info import
  • Data transfer between projects
  • Validation and error reporting

​
Technology stack

Backend
  • .NET 6.0
  • ASP.NET Core MVC and Web API
  • Entity Framework Core
  • IdentityServer4
Frontend
  • Razor views with jQuery
  • Bootstrap 4
  • SignalR for real-time updates
  • Select2, DataTables, and other jQuery plugins
Data storage
  • SQL Server (4 separate databases)
  • Redis (optional, for distributed caching)
External services
  • CyberSource (SOAP and REST APIs)
  • PayPal Payflow Pro
  • AWS S3 (file storage)
  • SendGrid (email)
  • Firebase (push notifications)
DevOps
  • AWS CodeDeploy
  • GitHub Actions
  • Docker (optional)

​
Deployment architecture

The platform can be deployed in multiple configurations: Single-server deployment
  • API and Admin UI on same server
  • SQL Server on same or separate server
  • Suitable for development and small deployments
Multi-server deployment
  • API servers behind load balancer
  • Admin UI on separate servers
  • SQL Server cluster
  • Redis cluster for distributed caching
  • Suitable for production environments
AWS deployment
  • EC2 instances for API and Admin UI
  • RDS for SQL Server
  • ElastiCache for Redis
  • S3 for file storage
  • CodeDeploy for automated deployments

​
Security considerations

Data encryption
  • Credit card numbers encrypted with AES-256
  • RSA keys for secure key exchange
  • TLS 1.2+ for all communications
Access control
  • Role-based access control (RBAC)
  • Scope-based API authorization
  • IP whitelisting for API access
  • MFA for admin users
Compliance
  • PCI DSS considerations for card data
  • Audit logging for all operations
  • Data retention policies
  • Secure key rotation

​
Scalability

The architecture supports horizontal scaling:
  • API servers: Stateless, can scale horizontally
  • Admin UI: Session state in distributed cache
  • Database: Read replicas for reporting
  • Background processing: Multiple workers with queue

​
Monitoring and observability

Application monitoring
  • Health check endpoints
  • Request logging with correlation IDs
  • Error tracking and alerting
  • Performance metrics
Infrastructure monitoring
  • Server health checks
  • Database performance monitoring
  • Cache hit rates
  • External API response times

​
Next steps

Component interactions

Learn how services communicate

Data flow

Understand payment processing flow

Integration patterns

Common integration scenarios

System architecture

Detailed project structure