Payment Processing Architecture - SOLID Principles & Scalable PSP Integration

Overview

This application is designed to manage payment processing for merchants using various Payment Service Providers (PSPs), such as Stripe and PinPayments. The system follows a modular, scalable, and testable architecture that adheres to SOLID principles, making it easy to add new PSPs in the future.

Key Architectural Principles

1. PSP-Agnostic Payment Processing (Dependency Inversion - "D" in SOLID)

The application employs a PaymentServiceInterface to standardize the interactions between the system and multiple PSPs.
The payment processing logic for each PSP (e.g., StripePaymentService and PinPaymentService) is encapsulated in separate classes, which decouple the payment logic from the rest of the system.
This approach allows us to easily add more PSPs by implementing the interface and updating the service factory.

2. Using Singletons for PSP Services (Singleton Pattern)

Instead of creating new instances of PSP services (such as new StripePaymentService()), the system utilizes singletons to manage PSP services. This ensures that each PSP service is instantiated only once and reused across the application.

The MerchantsPaymentsService class serves as the service factory to retrieve the correct PSP service instance:

class MerchantsPaymentsService
{
    public function getService(string $psp): PaymentServiceInterface
  {
      if ($psp === 'stripe') {
          return StripePaymentService::getInstance('pk_test_default', 'sk_test_default');
      }

      if ($psp === 'pin') {
          return PinPaymentService::getInstance('pk_test_default', 'sk_test_default');
      }

      // Throw an exception if the PSP is not supported
      throw new \Exception("Payment service provider {$psp} is not supported.");
  }
}

This approach makes the system more efficient and ensures that the payment service is only instantiated once per request cycle.

3. IoC Container & Dependency Injection

Laravel's Service Container is used to manage and inject dependencies. The singleton pattern is applied here as well, where the PSP services are bound in the container so that they are shared throughout the application's lifecycle:

$this->app->singleton(StripePaymentService::class, function ($app) {
    return new StripePaymentService('sk_test_default', 'pk_test_default');
});

$this->app->singleton(PinPaymentService::class, function ($app) {
    return new PinPaymentService('pin_test_default', 'pin_test_default');
});

This allows the PaymentController to inject the PSP service dynamically using Laravel’s dependency injection system, ensuring that dependencies are resolved automatically.

4. Unit Testing with Mocking (Mockery & PestPHP)

To ensure that the tests are fast and isolated from external services, Mockery is used to mock external dependencies like the payment services. This eliminates the need for real API calls during testing.

For instance, the StripePaymentService can be mocked as follows:
```
$mockService = \Mockery::mock(StripePaymentService::class);
$mockService->shouldReceive('charge')->andReturn(['success' => true]);
app()->instance(StripePaymentService::class, $mockService);
```
This guarantees that the tests remain independent of external APIs and are efficient.

5. Error Handling & Logging

A robust error-handling mechanism is in place to ensure that the system gracefully handles failures. Errors are logged using Laravel’s built-in logging features, providing insight into issues without interrupting the flow of the application:
```
catch (\Exception $e) {
    Log::error('Stripe Payment Error', ['error' => $e->getMessage()]);
}
```

Payment Flow Execution (High-Level Process)

Merchant Configuration
Merchants specify their active_psp (e.g., stripe or pinpayments) and configure their API keys in the database.
User Payment Request
Users initiate a payment by sending a request to charge a card (POST /api/merchants/{merchantId}/charge). The request is validated using Laravel's built-in validation tools.
PSP Selection & Processing
The PaymentController utilizes the MerchantsPaymentsService to dynamically select the correct PSP based on the merchant’s configuration and processes the payment.
Response Handling
If the payment is successful, the payment intent ID is returned. In case of failure (e.g., invalid API key), the error is logged and an appropriate message is returned to the user.

Key Technologies & Frameworks

Laravel 10 - Backend framework
Stripe API / PinPayments API - Payment processing
SOLID Principles - Clean architecture, Dependency Inversion Principle (DIP), Single Responsibility Principle (SRP)
Singleton Pattern - Efficient service resolution
Dependency Injection & IoC - Laravel's service container
Mockery & PestPHP - Unit testing and mocking
Logging & Exception Handling - Error resilience

Conclusion

This architecture provides modularity, extensibility, and maintainability while ensuring that the payment logic remains agnostic to any specific PSP. New PSPs can be integrated seamlessly by implementing the PaymentServiceInterface and updating the service factory. By leveraging Dependency Injection, Singletons, and Mocking, the system is robust, scalable, and easy to maintain. This approach also ensures that the application can evolve to support additional PSPs with minimal changes to existing code. 🚀