Billing Module

🎯 Overview

The Billing module owns every Stripe-backed financial workflow exposed by the Internal API. It brokers customer and subscription lifecycle events, orchestrates one-off purchases for marketplace add-ons, hydrates analytics dashboards, and keeps local data stores in sync with Stripe through webhook ingestion. The module consolidates domain logic behind dedicated services and utilities while controllers remain thin HTTP adapters.

📁 Directory Structure

internal/api/v1/billing/
├── index.js                      # Router registration and shared middleware
├── controllers/                  # Express controllers (request/response glue)
│   ├── charge.controller.js      # Marketplace checkout orchestration
│   ├── customer.controller.js    # Customer, invoice, and payment method endpoints
│   ├── overview.controller.js    # Revenue analytics endpoints
│   ├── payment-intent.controller.js # Payment intent purchase flows
│   ├── payment-link.controller.js   # Ad-hoc invoice + hosted link creation
│   ├── payout.controller.js      # Payout summaries and drilldowns
│   ├── product.controller.js     # Product and price catalogue management
│   ├── webhook.controller.js     # Stripe webhook ingestion
│   └── index.js                  # Controller exports
├── routes/                       # Route definitions + middleware binding
│   ├── charge.route.js
│   ├── customer.route.js
│   ├── overview.route.js
│   ├── payment-intent.route.js
│   ├── payment-link.route.js
│   ├── payout.route.js
│   ├── product.route.js
│   ├── webhook.route.js
│   └── index.js
├── services/                     # Business logic (Stripe + Mongo orchestration)
│   ├── charge.service.js
│   ├── customer.service.js
│   ├── overview.service.js
│   ├── payment-intent.service.js
│   ├── payment-link.service.js
│   ├── payout.service.js
│   ├── product.service.js
│   ├── webhook.service.js
│   └── index.js
├── middlewares/
│   ├── stripe-check.js           # Ensures account has connected Stripe keys
│   └── validate.js               # Payload validation wrapper
├── validations/                  # Joi schema definitions per route surface
│   ├── charge.validation.js
│   ├── custom.validation.js      # Dynamic schema builder for linking configs
│   ├── customer.validation.js
│   ├── overview.validation.js
│   ├── payment-intent.validation.js
│   ├── payment-link.validation.js
│   ├── payout.validation.js
│   ├── product.validation.js
│   └── index.js
├── utils/                        # Stripe + CRM helpers shared by services
│   ├── add-mapping.js            # CRM contact mapping transforms
│   ├── ApiError.js               # Normalised API error factory
│   ├── index.js
│   ├── pick.js                   # Light projection helper used in queries
│   ├── stripe-account.js         # OAuth account lookup utilities
│   └── stripe-config.js          # Stripe SDK configuration (per connected account)
└── tests/
    ├── customer.test.js
    ├── overview.test.js
    ├── payout.test.js
    ├── product.test.js
    └── fixtures/
    ├── customer.js
    ├── overview.js
    ├── payout.js
    └── product.js

🗄️ MongoDB Collections

📚 Detailed Schema: See Database Collections Documentation

billing.charges

• Purpose: Stores enriched charge payloads emitted by Stripe webhooks for reporting.
• Model: shared/models/billing-charge.js
• Primary Use: Read-heavy analytics (gross/net volume, success counts).

billing.customers

• Purpose: Local snapshot of Stripe customers for linking and analytics.
• Model: shared/models/billing-customer.js
• Primary Use: Read/write during webhook sync, link to CRM contacts.

billing.subscriptions

• Purpose: Tracks subscription lifecycle metadata from Stripe.
• Model: shared/models/billing-subscription.js
• Primary Use: Aggregations powering overview metrics and CRM linking.

billing.disputes

• Purpose: Logs disputes and balance transaction deltas.
• Model: shared/models/billing-dispute.js
• Primary Use: Net volume adjustments, dispute count analytics.

billing.refunds

• Purpose: Tracks refunds for revenue reconciliation.
• Model: shared/models/billing-refund.js
• Primary Use: Deduct refunds from net volume analytics.

billing.products

• Purpose: Cache of Stripe products to avoid repeated API lookups.
• Model: shared/models/billing-product.js
• Primary Use: Hydrated by overview analytics when catalogue cache miss occurs.

billing.notes

• Purpose: Stores account-scoped customer notes within the billing workspace.
• Model: shared/models/billing-notes.js
• Primary Use: CRUD via customer service endpoints and CSV export.

Supporting Collections

• _accounts (shared/models/account.js) – Validates ownership and parent account context.
• queues (shared/models/queues.js) – Enqueues follow-up jobs (contact linking, checkout side effects).
• _store.prices / _store.products (shared/models/store-price.js, shared/models/store-product.js) – Marketplace catalogue used by checkout logic.
• onebalance / onebalance-usage_logs – Balance ledger for sub-accounts.
• crm.contacts (shared/models/contact.js) – Synchronises Stripe customers to CRM.
• support.* collections – Open conversations when payments complete via webhook service.

🏗️ Architecture Overview

Key Responsibilities:

• Serve REST endpoints for customer, invoice, subscription, checkout, and payout operations.
• Bridge connected-account Stripe API calls with account-specific OAuth tokens.
• Generate finance dashboards via Mongo/Stripe aggregations (overview service).
• Keep Mongo caches consistent with Stripe through webhook upserts.
• Trigger downstream automations (Queue Manager, Support socket events) after key billing events.

Design Decisions:

• 🧩 Service Layer Isolation: All Stripe calls and Mongo pipelines live in services/ to keep controllers testable.
• 🔁 Connected Account Context: stripeConfig hydrates Stripe SDK with the requesting account’s OAuth token to avoid global state.
• 📊 Analytics via Aggregation: Overview metrics aggregate raw collections to avoid storing precomputed stats.
• 🔄 Webhook Idempotency: Webhook service uses findOneAndUpdate / upsert to guard against duplicate deliveries.
• 🧵 Queue Offloading: Expensive or asynchronous actions (store fulfilment, conversations) are pushed to queues to keep API latency low.

🔗 Submodules

Analytics & Reporting

• 📘 Overview Service – Sales KPIs, gross/net volume, dispute analytics, payout summaries.

Customer & Billing Records

• 📗 Customer Service – Stripe customer CRUD, invoices, payment methods, subscriptions, CRM linking.
• 📙 Webhook – Stripe event ingestion and Mongo sync.

Commerce & Checkout

• 📕 Charge – Marketplace checkout via direct charges for add-on products.
• 📒 Payment Intent Service – Payment Intent-based top-ups and purchases.
• 📔 Payment Link Service – Generates hosted invoices and short links.

Catalogue & Payouts

• 📓 Product Service – Stripe product/price management.
• 📔 Payout Service – Payout listing, detail drilldowns, and balance transaction summaries.

🔄 Data Flow

flowchart TB
 UI[DashClicks UI] -->|REST| Router
 Router --> Middleware
 Middleware --> Controllers
 Controllers --> Services
 Services -->|Connected account key| Stripe
 Services -->|Aggregations| Mongo[(MongoDB)]
 Services --> QueueManager
 Stripe --> Webhooks
 Webhooks --> WebhookService
 WebhookService --> Mongo
 WebhookService --> SupportSockets[(Support Sockets)]

 classDef ext fill:#f0f4ff,stroke:#3b6ae6;
 class Stripe,SupportSockets ext;

🔐 Configuration & Dependencies

Variable	Description	Required
STRIPE_SECRET_KEY	Platform secret key used when creating parent-account subscriptions	✅
APP_SECRET	JWT signing key for marketplace phone provisioning (charge.service)	✅
API_BASE_URL	Internal router base URL for customer creation proxy calls	✅
SETUP_PRODUCT	Stripe product ID for setup fees used in phone/listing bundles	✅
BASE_CURRENCY	ISO currency code used for OneBalance ledger conversions	✅

Key Libraries

• stripe – Official Stripe Node SDK (connected-account aware via stripeConfig).
• moment / moment-timezone – Date windowing for analytics queries.
• mongoose – Aggregations and CRUD across billing collections.
• json2csv – CSV export for billing notes (customer service).
• axios – Internal API proxying and phone number lookups.

🚀 Quick Start

1. Ensure the parent account has Stripe OAuth credentials (stripe-check middleware blocks otherwise).
2. Hit GET /v1/billing/overview with startDate/endDate to validate analytics connectivity.
3. Use POST /v1/billing/payment-links with a CRM contact to generate a hosted invoice.
4. Monitor tests/customer.test.js and tests/overview.test.js for regression coverage when extending services.

Requirements Coverage

• ✅ Customer & Checkout Flows – Documented under dedicated service pages linked above.
• ✅ Analytics – Overview service doc details aggregations and growth calculations.
• ✅ Webhooks & Sync – Webhook service doc explains idempotent upserts and downstream side effects.