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.
Payment Status
- requires_capture
- succeeded
- canceled
- refunded
- partially_refunded
- disputed
- disputed_lost
Authorization Lifecycle
- authorized
- captured
- canceled
Refund Lifecycle
- none
- partial
- full
Dispute Lifecycle
- open
- in_review
- won
- lost
Stripe Webhook Processing
Stripe events are processed through a centralized endpoint.
POST
/webhook
Supported events include:
checkout.session.completedpayment_intent.succeededpayment_intent.amount_capturable_updatedcharge.refundedcharge.dispute.createdcharge.dispute.closed
The system ensures idempotent processing so events are never applied twice.
Firestore Ledger Model
The platform maintains a financial ledger in Google Cloud Firestore.
Core collections:
paymentspayment_transactionsevent_logswebhook_events
These collections provide a complete financial audit trail.
Authentication & Access
The platform controls access via authentication and authorization boundaries.
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