Architecture

System Architecture

The platform is built using an event-driven payment architecture.

Core Components

• Stripe Connect — Each merchant operates through their own Stripe account. Sensitive financial and compliance data remains inside Stripe.
• Webhook Processing Engine — Stripe events are received through a centralized webhook endpoint and translated into ledger updates.
• Payment Ledger — A structured ledger stored in Google Cloud Firestore maintains a complete audit trail of all payment activity.
• Risk Engine — The system calculates merchant exposure and payment health metrics.

Payment Lifecycle Tracking

The platform tracks every stage of a payment.

Stripe Webhook Processing

Stripe events are processed through a centralized endpoint.

Supported events include:

• checkout.session.completed
• payment_intent.succeeded
• payment_intent.amount_capturable_updated
• charge.refunded
• charge.dispute.created
• charge.dispute.closed

The system ensures idempotent processing so events are never applied twice.

Stripe → Ledger event flow

Events from Stripe are received at the webhook endpoint and translated into ledger updates in Firestore.

Firestore Ledger Model

The platform maintains a financial ledger in Google Cloud Firestore.

Core collections:

• payments
• payment_transactions
• event_logs
• webhook_events

These collections provide a complete financial audit trail.

Authentication & Access

The platform uses authentication plus Role-Based Access Control (RBAC) to enforce tenant isolation and least-privilege access across the payment lifecycle.

RBAC Model

• Tenant roles limit access to a single merchant tenant (e.g. merchant admin vs. merchant user).
• Platform roles allow cross-tenant visibility for administrators and operational teams.
• Permissions map to capabilities such as viewing payments, managing refunds/disputes, and accessing developer APIs/merchant dashboards.

Enforcement

• API authorization: each request is authorized using the caller identity (JWT/session) combined with role + tenant context.
• Data isolation: Firestore access checks tenant ownership so ledger collections (for example payments, payment_transactions, event_logs) cannot be read or modified outside the caller’s tenant scope.
• Least privilege: roles only receive permissions needed for their UI and workflows (dashboard reads, orchestration actions, etc.).

In practice, a merchant’s Stripe account remains isolated within Stripe Connect, while your platform provides a consistent multi-tenant view through controlled access to the ledger and APIs.

Risk & Exposure Engine

The platform includes a merchant exposure analysis engine.

Metrics include:

• Net merchant exposure
• Refund impact
• Dispute impact
• Stripe Radar risk signals

Example health score:

health_score = net_exposure / original_amount