Stripe Integration

🎯 Overview

The Stripe integration enables DashClicks to process payments, manage subscriptions, handle billing, and collect customer charges through the Stripe payment platform. This integration supports multiple connected apps including billing management, funnel payments, and review request automation.

Provider: Stripe (https://stripe.com)
API Version: Latest (using Stripe Node.js SDK)
Integration Type: OAuth 2.0 + REST API + Webhooks
Authentication: OAuth Connect for account linking

📁 Directory Structure

Documentation Structure:

stripe/
├── 📄 index.md - Integration overview and setup
├── 📄 authentication.md - OAuth flow and credential management
└── 📄 webhooks.md - Webhook handling for billing and reviews

Source Code Location:

• Base Path: external/Integrations/Stripe/
• Controllers: Controllers/auth.js
• Models: Models/keys.js
• Routes: Routes/auth.js

🗄️ MongoDB Collections

📚 Detailed Schema: See Database Collections Documentation

stripe-key

• Purpose: Store Stripe OAuth tokens and connected app configurations
• Model: external/models/stripe-key.js
• Primary Use: Store Stripe Connect access tokens, refresh tokens, and app connections

queues

• Purpose: Background job processing for Stripe data sync
• Model: external/models/queues.js
• Primary Use: Queue billing data imports and contact synchronization

Billing Collections

• Collections: billing-charge, billing-dispute, billing-refund, billing-customer, billing-subscription, billing-notes, billing-product
• Purpose: Store synced Stripe billing data
• Models: external/models/billing-*.js

🔐 Authentication & Configuration

Authentication Method: OAuth 2.0 Connect

Required Environment Variables:

Variable	Description	Required
STRIPE_SECRET_KEY	Platform Stripe secret key	✅
STRIPE_CLIENT_ID	OAuth Connect client ID	✅
STRIPE_REDIRECT_URL	OAuth callback URL	✅
API_BASE_URL	Base URL for webhook endpoints	✅
APP_SECRET	JWT signing secret for state parameter	✅

Credential Storage: OAuth tokens stored in stripe-key collection with account linking

Token Structure:

{
  account_id: ObjectId,
  token: {
    access_token: String,
    refresh_token: String,
    stripe_user_id: String,
    stripe_publishable_key: String,
    scope: String,
    livemode: Boolean,
    token_type: "bearer"
  },
  connected_apps: ["billing", "review", "funnel"],
  type: "person" | "business", // For billing contact mapping
  new_contact: Boolean,
  mappings: Object, // Field mappings for contact import
  token_invalidated: Boolean
}

🏗️ Architecture Overview

Key Responsibilities:

• OAuth 2.0 authentication flow for Stripe Connect
• Multi-app connection management (billing, review, funnel)
• Token lifecycle management and invalidation handling
• Webhook registration and management
• Billing data synchronization via queue jobs

API Communication Pattern:

• OAuth 2.0 for initial authentication
• Stripe Node.js SDK for API interactions
• Webhooks for real-time event processing

Connected Apps:

1. billing - Import charges, customers, subscriptions, disputes, refunds
2. review - Trigger auto-review requests on successful charges
3. funnel - Payment processing for funnel products

Rate Limiting:

• Stripe enforces rate limits per API key (varies by endpoint)
• SDK handles automatic retry with exponential backoff

🔗 Features & Capabilities

Core Features

• 📘 Authentication - OAuth Connect flow, token management, multi-app connections
• 📗 Webhooks - Webhook registration for billing and review events

🔄 Integration Data Flow

Initial Connection Flow

sequenceDiagram
    participant User
    participant DashClicks
    participant StripeOAuth
    participant StripeAPI
    participant DB

    User->>DashClicks: Connect Stripe (with app type)
    DashClicks->>DashClicks: Generate JWT state token
    DashClicks->>StripeOAuth: Redirect to OAuth
    User->>StripeOAuth: Authorize account
    StripeOAuth->>DashClicks: Callback with code
    DashClicks->>DashClicks: Verify JWT state
    DashClicks->>StripeAPI: Exchange code for token
    StripeAPI-->>DashClicks: Return access token
    DashClicks->>DB: Save token with connected_apps
    alt Billing App
        DashClicks->>StripeAPI: Register billing webhook
        DashClicks->>DB: Queue billing data sync
    end
    alt Review App
        DashClicks->>StripeAPI: Register review webhook
    end
    DashClicks-->>User: Redirect to success URL

Re-connection Flow (Existing Token)

sequenceDiagram
    participant User
    participant DashClicks
    participant DB

    User->>DashClicks: Connect Stripe (with app type)
    DashClicks->>DB: Check existing token
    alt Token Exists & Valid
        alt App Not Connected
            DashClicks->>DB: Add app to connected_apps
            alt Billing App
                DashClicks->>DB: Queue billing sync
            end
        end
        DashClicks-->>User: Redirect to success
    else Token Invalidated
        DashClicks->>DB: Delete old token
        DashClicks-->>User: Restart OAuth flow
    end

🔗 Submodules

• Authentication Flow - OAuth Connect, token management, disconnection
• Webhooks - Webhook setup for billing and review automation

🚨 Error Handling

Common Error Scenarios:

Token Invalidation

• Error: invalid_grant, 401, 403 responses
• Handling: Set token_invalidated: true flag, force re-authentication
• User Impact: Requires reconnection

Account Already Connected

• Error: stripe_user_id already exists in another account
• Handling: Reject connection with error message
• User Impact: Cannot connect same Stripe account to multiple DashClicks accounts

OAuth State Mismatch

• Error: Invalid JWT state parameter
• Handling: Return 401 Unauthorized
• User Impact: Must restart OAuth flow

Webhook Registration Failures

• Error: Webhook endpoint creation fails
• Handling: Log error but allow connection (non-blocking)
• User Impact: Manual webhook setup may be required

📊 Monitoring & Logging

Logged Events:

• OAuth authentication attempts
• Token invalidation events
• Webhook registration success/failure
• Billing data sync queue creation
• Account disconnection events

Logger Initiator: external/Integrations/Stripe/

Key Metrics:

• Active Stripe connections by account
• Connected apps distribution
• Token invalidation rate
• Webhook delivery success rate

⚠️ Multi-App Connection System

Allowed Connected Apps:

• billing - Full billing data sync
• review - Auto-review request triggers
• funnel - Payment processing

Connection Logic:

1. First connection establishes token
2. Additional apps add to connected_apps array
3. Each app triggers specific setup:
   • billing: Registers webhook, queues data sync, sets up contact mapping
   • review: Registers charge.succeeded webhook
   • funnel: Uses existing token for payments

Disconnection Logic:

• Disconnect single app: Removes from connected_apps array
• Disconnect 'all': Removes all apps and deletes token
• Billing disconnect: Deletes all billing data, removes webhook
• Review disconnect: Removes webhook only if no other accounts use it

🔗 Related Documentation

• Provider API Docs: Stripe API Documentation
• Stripe Connect: OAuth Documentation
• Authentication Details: Authentication Flow
• Webhook Documentation: Webhooks
• Billing Collections: Database Collections

🎯 Integration Checklist

Before Using:

• Set STRIPE_SECRET_KEY environment variable
• Configure STRIPE_CLIENT_ID for OAuth
• Set STRIPE_REDIRECT_URL to callback endpoint
• Verify webhook endpoint accessibility
• Test OAuth flow with test mode account

When Connecting:

• Specify connected_app parameter (billing/review/funnel)
• Provide forward_url for post-auth redirect
• For billing: Optionally provide contact_mapping configuration

After Connection:

• Verify webhook registration in Stripe dashboard
• Check queue jobs created for billing sync
• Monitor token invalidation events