5CRSE5CRSEDocumentation
← Back to site

#Payment System Architecture

#Component Diagram

+----------------------------------+     +----------------------------------+
|                                  |     |                                  |
|       Frontend Components        |     |        External Providers        |
|                                  |     |                                  |
+----------------------------------+     +----------------------------------+
|                                  |     |                                  |
| +------------------------------+ |     | +------------+  +------------+   |
| |                              | |     | |            |  |            |   |
| |      Payment Form            <--------> Stripe API  |  | Square API |   |
| |                              | |     | |            |  |            |   |
| +------------------------------+ |     | +------------+  +------------+   |
|                                  |     |                                  |
| +------------------------------+ |     +----------------------------------+
| |                              | |
| |      Receipt Viewer          | |
| |                              | |     +----------------------------------+
| +------------------------------+ |     |                                  |
|                                  |     |           API Endpoints          |
| +------------------------------+ |     |                                  |
| |                              | |     +----------------------------------+
| |    Payment Status Display    | |     |                                  |
| |                              <------->  /stripe/create-checkout-session |
| +------------------------------+ |     |  /stripe/webhook                 |
|                                  |     |  /square/create-payment-link     |
| +------------------------------+ |     |  /square/webhook                 |
| |                              | |     |  /payments/:id/status            |
| |    Analytics Dashboard       <------->  /payments/:id/generate-receipt  |
| |                              | |     |  /payments/:id/pdf-receipt       |
| +------------------------------+ |     |  /payments/stats                 |
|                                  |     |                                  |
+----------------------------------+     +----------------------------------+
                                               |
+----------------------------------+           |
|                                  |           |
|       Service Layer              <-----------+
|                                  |
+----------------------------------+
|                                  |
| +------------------------------+ |     +------------------------------+
| |                              | |     |                              |
| |      StripeService           <------->     PaymentTrackingService   |
| |                              | |     |                              |
| +------------------------------+ |     +------------------------------+
|                                  |                    ^
| +------------------------------+ |                    |
| |                              | |                    |
| |      SquareService           <--------------------+ |
| |                              | |                  | |
| +------------------------------+ |                  | |
|                                  |                  | |
| +------------------------------+ |     +------------+--------------+
| |                              | |     |                           |
| |    PaymentReceiptService     <------->    PdfReceiptService      |
| |                              | |     |                           |
| +------------------------------+ |     +---------------------------+
|                                  |
+----------------------------------+

                   ^
                   |
                   v

+----------------------------------+
|                                  |
|       Database                   |
|                                  |
+----------------------------------+
|                                  |
| +------------------------------+ |
| |                              | |
| |       Payments Collection    | |
| |                              | |
| +------------------------------+ |
|                                  |
| +------------------------------+ |
| |                              | |
| |       Bookings Collection    | |
| |                              | |
| +------------------------------+ |
|                                  |
| +------------------------------+ |
| |                              | |
| |       Media Collection       | |
| |                              | |
| +------------------------------+ |
|                                  |
+----------------------------------+

#Data Flow

#Payment Creation Flow

 User
   |
   v
[Payment Form]
   |
   v
[API Endpoint] -----> [Payment Service] -----> [Payment Provider API]
   |                       |                         |
   |                       v                         v
   |                  [Create Payment Record]   [Return Payment URL]
   |                       |                         |
   v                       |                         |
[Redirect to Payment URL] <-------------------------+
   |
   v
[Provider Payment Page]
   |
   v
[Complete Payment]
   |
   v
[Provider Webhook] -----> [Webhook Endpoint] -----> [Payment Service]
                                                        |
                                                        v
                                                  [Update Payment Status]
                                                        |
                                                        v
                                                  [Update Booking Status]
                                                        |
                                                        v
                                                  [Generate Receipt]

#Receipt Generation Flow

[Payment Service] -----> [PaymentReceiptService] -----> [Generate HTML Receipt]
                               |                               |
                               v                               v
                       [Store in Media Collection]      [Update Payment Record]
                               |
                               v
                       [PdfReceiptService]
                               |
                               v
                       [Generate PDF Receipt]
                               |
                               v
                       [Store in Media Collection]
                               |
                               v
                       [Update Payment Record]

#Payment API Structure

/api
  |
  +-- /stripe
  |     |
  |     +-- /create-checkout-session (POST)
  |     |
  |     +-- /webhook (POST)
  |     |
  |     +-- /session-details (GET)
  |
  +-- /square
  |     |
  |     +-- /create-payment-link (POST)
  |     |
  |     +-- /webhook (POST)
  |
  +-- /payments
  |     |
  |     +-- /:paymentId/status (GET)
  |     |
  |     +-- /:paymentId/generate-receipt (POST)
  |     |
  |     +-- /:paymentId/pdf-receipt (POST)
  |     |
  |     +-- /stats (GET)
  |
  +-- /receipts
        |
        +-- /:paymentId (GET)

#Service Interactions

The payment system follows a service-oriented architecture with clear separation of concerns:

  1. Provider-Specific Services

    • StripeService: Handles all Stripe-specific operations
    • SquareService: Handles all Square-specific operations

  2. Common Services

    • PaymentTrackingService: Centralizes payment status tracking across providers
    • PaymentReceiptService: Generates HTML receipts
    • PdfReceiptService: Converts HTML receipts to PDF format

  3. Data Flow

    • Frontend components interact with API endpoints
    • API endpoints delegate to appropriate services
    • Services interact with external providers and database
    • Webhooks update payment status asynchronously

This architecture provides:

  • Clean separation of payment provider logic
  • Centralized payment tracking
  • Consistent receipt generation
  • Extensibility for additional payment providers