Main Services Implementation

The Main Services form the customer-facing runtime of the payment gateway. They render checkout and portal pages, read checkout sessions, create transactions, receive provider webhooks, and expose customer document downloads.

Main Backend

The Main Backend is a Go service using Gin, MongoDB, Garnet-compatible cache access, OpenTelemetry middleware, structured logging, rate limiting, and the shared encryption libraries.

Runtime Responsibilities

1. Checkout session retrieval: The customer checkout app calls GET /api/v1/checkouts/:id and POST /api/v1/checkouts/:id/tax-preview. Checkout creation itself is owned by the Admin Backend at POST /api/v1/checkouts/{siteId}/create.
2. Transaction creation and status: The checkout app calls POST /api/v1/transactions/create, GET /api/v1/transactions/:id/status, POST /api/v1/transactions/:id/cancel, and POST /api/v1/transactions/:id/mark-pending. Provider-specific implementations update payment intents or create billing requests from these handlers.
3. Billing requests: Non-card and redirect-style providers use POST /api/v1/billing-requests/create to initialize provider-side payment flows.
4. Provider webhooks: Upstream provider callbacks arrive at /hooks/{type}/{providerId} on the Main Backend host. These routes are intentionally registered outside /api/v1 so provider dashboards can use short webhook URLs.
5. Customer portal API: Routes under /api/v1/portal support status checks, OTP/magic-link authentication, document listing, PDF/e-invoice downloads, subscription views, upcoming proforma PDFs, and cancellation requests.
6. VAT validation API: Checkout pages can validate EU VAT IDs through /api/v1/vat/validate and check EU membership through /api/v1/vat/eu-country/:code.
7. License enforcement: All /api/v1 routes run through the Main Backend license middleware. Provider webhooks are registered at the root route group and are handled by provider-specific verification.
8. Document delivery: The Main Backend proxies customer-facing PDF and e-invoice requests to payment-gateway-main-worker; it does not require a shared volume with the worker.

Transaction Flow

The current implementation does not publish payment.initiated events to Garnet. Garnet is used as a Redis-compatible cache. Transaction creation and provider calls happen in the request path or provider-specific webhook path, with side effects dispatched asynchronously where appropriate.

For background work, the service uses a MongoDB-backed jobs collection. Invoices enqueue pdf:generate; notification scheduling enqueues email:send, slack:send, or sms:send; the Worker claims those jobs and performs the slow work outside the API request.

Observability

The Main Backend installs request IDs, structured request logs, OpenTelemetry Gin middleware, rate limiting, global request timeouts, and health checks for MongoDB, cache, and provider availability.

Main Frontend

The Main Frontend is the customer-facing React application served by a Node/Express server. It is accessed when customers open a checkout paymentUrl or customer portal route.

Operational Features

• Checkout and portal UI: React 19 and React Router render checkout pages, invoice/credit-note pages, portal login, document lists, subscription views, and provider-specific payment forms.
• API proxying: The Express server proxies /api/* to the configured Main Backend target using REACT_APP_MAIN_BACKEND_SERVICE, REACT_APP_MAIN_BACKEND_PORT, and REACT_APP_MAIN_BACKEND_HTTPS.
• Provider browser SDKs: The content security policy allows the configured payment SDK domains used by Stripe, Mollie, PayPal, and other provider forms.
• Runtime configuration endpoint: The server exposes frontend environment values needed by the UI without baking deployment domains into the built assets.
• Graceful shutdown: The server handles SIGTERM and SIGINT, closes the HTTP server, and exits cleanly for container restarts.