# 01. Architecture & Design Overview ## Executive Summary The **ERP Payment Gateway** is a robust, multi-tenant middleware designed to facilitate secure payments between various ERP modules and third-party payment providers (Razorpay, CCAvenue). It acts as a single source of truth for payment statuses, ensuring data consistency across disparate systems. --- ## 1. High-Level System Architecture The application follows a modern **Service-Oriented Architecture (SOA)** built on the Laravel framework. It serves as a bridge between three main entities: 1. **ERP Systems**: Initiate payment requests and receive status updates. 2. **Payment Gateway (PG)**: Processes the actual monetary transactions. 3. **End Users**: Interact with the hosted payment pages to complete transactions. ### Multi-Tenancy Model The system uses a **Database-level multi-tenancy** approach where: - **Customers**: Represent different ERP instances or clients. - **Events**: Represent specific payment contexts (e.g., Admission Fees, Exam Fees). - **Credentials**: Each Customer/Event can have its own sets of PG credentials (API keys, secrets). --- ## 2. Core Development Workflow ### Phase A: Intent Creation (Server-to-Server) 1. ERP system sends a POST request to `/api/v1/create-payment-intent`. 2. The `PaymentIntentController` validates the `customer` and `event`. 3. A `PaymentIntent` record is created with a unique UUID (`token`). 4. The API returns a `redirect_url` (e.g., `/pay/{token}`). ### Phase B: Payment Initiation (Client Interaction) 1. User visits the `redirect_url`. 2. `PaymentPageController` displays available gateways for that specific event. 3. User selects a gateway; a `PaymentTransaction` is logged as `INITIATED`. 4. System redirects the user to the Payment Gateway's checkout page. ### Phase C: Resolution (Callbacks & Webhooks) 1. **Callback**: After payment, the PG redirects the user back to `/payment/callback/{gateway}`. 2. **Webhook**: The PG sends an asynchronous notification to `/api/v1/webhooks/{gateway}` to ensure reliability. 3. `CallbackController` or `WebhookController` updates the `PaymentTransaction` and `PaymentIntent` status. 4. `WebhookService` notifies the original ERP system via the `notify_url`. --- ## 3. Technology Stack - **Backend Framework**: Laravel 12.0 (PHP 8.2+) - **Database**: SQL-based (MySQL) - **API Authentication**: Laravel Sanctum & Custom Header validation. - **Frontend**: Blade Templates + Vanilla CSS. - **External Dependencies**: - `razorpay/razorpay`: Official SDK for Razorpay integration. - `ccavenue`: Custom-built driver for CCAvenue. --- ## 4. Key Design Decisions - **Uuids for External Tracking**: Uses UUIDs for public-facing tokens (`payment_intent_id`) to prevent ID enumeration attacks. - **Polymorphic-like Credentials**: Gateways and Credentials are decoupled, allowing a single gateway type to have multiple configurations based on the customer or event. - **Webhook Resilience**: Implements an ERP-side signature verification (`X-PB-Signature`) to ensure ERP systems can trust the incoming status updates.