stripe-connect.js

Go to the documentation of this file.

/**
 * @file routes/stripe-connect.js
 * @module routes/stripe-connect
 * @description Stripe Connect onboarding and account management routes for tenant dashboard.
 * Handles OAuth onboarding flow, account status retrieval, and configuration updates.
 * 
 * **Dashboard Integration:**
 * - GET /config - Fetch tenant's Stripe account status
 * - POST /connect/start - Initiate Stripe Connect onboarding
 * - GET /connect/refresh - Regenerate onboarding link (if expired)
 * - GET /onboarding-complete - Return URL after successful onboarding
 * - GET /onboarding-refresh - Return URL when link expires
 * 
 * **Multi-Tenant Security:**
 * - All routes require authentication (authenticateToken)
 * - tenant_id extracted from JWT token
 * - Row-level security enforced on stripe_config table
 * 
 * **Onboarding Flow:**
 * 1. Tenant clicks "Connect with Stripe" in dashboard
 * 2. POST /connect/start creates Connected Account + account link
 * 3. Redirect tenant to Stripe-hosted onboarding
 * 4. Stripe redirects to /onboarding-complete or /onboarding-refresh
 * 5. Dashboard polls GET /config to check charges_enabled status
 * 
 * @requires express
 * @requires ../services/stripeService
 * @requires ../middleware/auth
 * @see {@link https://stripe.com/docs/connect/enable-payment-acceptance-guide|Stripe Connect Onboarding}
 */
 
const express = require('express');
const router = express.Router();
const pool = require('../services/db');
const StripeService = require('../services/stripeService');
const authenticateToken = require('../middleware/auth');
 
/**
 * GET /api/stripe/config
 * 
 * Retrieves tenant's Stripe Connect account configuration and status.
 * 
 * Returns account details if configured, or null if not yet onboarded.
 * Dashboard uses this to determine whether to show "Connect with Stripe" button
 * or display account status (verified, pending, disabled).
 * 
 * **Response Fields:**
 * - stripe_account_id - Connected Account ID (acct_...)
 * - account_status - pending, verified, disabled, suspended
 * - charges_enabled - Can accept payments (true/false)
 * - payouts_enabled - Can receive payouts (true/false)
 * - verification_status - unverified, pending, verified, failed
 * - requirements_currently_due - Array of missing required info
 * - onboarding_completed_at - Timestamp of onboarding completion
 * 
 * @route GET /api/stripe/config
 * @param {express.Request} req - Express request (authenticated)
 * @param {express.Response} res - Express response
 * @returns {Promise<Object>} Stripe config or null if not configured
 * 
 * @example
 * // Response when not onboarded:
 * {
 *   "configured": false
 * }
 * 
 * @example
 * // Response when onboarded and verified:
 * {
 *   "configured": true,
 *   "stripe_account_id": "acct_1234567890",
 *   "account_status": "verified",
 *   "charges_enabled": true,
 *   "payouts_enabled": true,
 *   "verification_status": "verified",
 *   "requirements_currently_due": [],
 *   "onboarding_completed_at": "2026-03-16T10:30:00.000Z",
 *   "country": "US",
 *   "default_currency": "usd"
 * }
 */
router.get('/config', authenticateToken, async (req, res) => {
  try {
    const tenantId = req.user.tenant_id;
 
    const result = await pool.query(
      `SELECT 
        config_id,
        stripe_account_id,
        account_status,
        charges_enabled,
        payouts_enabled,
        details_submitted,
        verification_status,
        requirements_currently_due,
        requirements_eventually_due,
        requirements_disabled_reason,
        account_type,
        country,
        default_currency,
        onboarding_completed_at,
        application_fee_percent,
        application_fee_fixed,
        created_at,
        updated_at
      FROM stripe_config
      WHERE tenant_id = $1`,
      [tenantId]
    );
 
    if (result.rows.length === 0) {
      return res.json({ configured: false });
    }
 
    res.json({
      configured: true,
      ...result.rows[0]
    });
  } catch (error) {
    console.error('❌ Error fetching Stripe config:', error);
    res.status(500).json({ error: 'Failed to fetch Stripe configuration' });
  }
});
 
/**
 * POST /api/stripe/connect/start
 * 
 * Initiates Stripe Connect onboarding flow for tenant.
 * 
 * Creates Connected Account (if not exists) and generates onboarding link.
 * Returns redirect URL for tenant to complete onboarding on Stripe.
 * 
 * **Request Body:**
 * - email - Business email address (required)
 * - country - ISO 3166-1 alpha-2 country code (default: US)
 * - business_name - Business name (optional)
 * - business_url - Business website URL (optional)
 * 
 * **Response:**
 * - account_id - Stripe Connected Account ID
 * - onboarding_url - URL to redirect tenant to
 * - expires_at - Unix timestamp when link expires (5 minutes)
 * 
 * @route POST /api/stripe/connect/start
 * @param {express.Request} req - Express request with body
 * @param {express.Response} res - Express response with onboarding URL
 * @returns {Promise<Object>} Account ID and onboarding URL
 * 
 * @example
 * // Request:
 * POST /api/stripe/connect/start
 * {
 *   "email": "billing@acme.com",
 *   "country": "US",
 *   "business_name": "Acme Corp",
 *   "business_url": "https://acme.example.com"
 * }
 * 
 * @example
 * // Response:
 * {
 *   "account_id": "acct_1234567890",
 *   "onboarding_url": "https://connect.stripe.com/setup/e/acct_1234567890/...",
 *   "expires_at": 1710630000
 * }
 */
router.post('/connect/start', authenticateToken, async (req, res) => {
  try {
    const tenantId = req.user.tenant_id;
    const { email, country = 'US', business_name, business_url } = req.body;
 
    if (!email) {
      return res.status(400).json({ error: 'Email is required' });
    }
 
    // Check if tenant already has a Stripe account
    const existingConfig = await pool.query(
      'SELECT stripe_account_id FROM stripe_config WHERE tenant_id = $1',
      [tenantId]
    );
 
    let accountId;
 
    if (existingConfig.rows.length > 0) {
      // Use existing account
      accountId = existingConfig.rows[0].stripe_account_id;
      console.log(`🔄 Using existing Stripe account: ${accountId}`);
    } else {
      // Create new Connected Account
      const businessProfile = {};
      if (business_name) businessProfile.name = business_name;
      if (business_url) businessProfile.url = business_url;
 
      const account = await StripeService.createConnectAccount(
        email,
        country,
        'express', // Use Express accounts for faster onboarding
        businessProfile
      );
 
      accountId = account.id;
 
      // Store in database
      await pool.query(
        `INSERT INTO stripe_config 
         (tenant_id, stripe_account_id, account_status, account_type, country, created_by)
         VALUES ($1, $2, 'pending', 'express', $3, $4)`,
        [tenantId, accountId, country, req.user.user_id]
      );
 
      console.log(`✅ Created new Stripe account: ${accountId} for tenant ${tenantId}`);
    }
 
    // Generate onboarding link
    const frontendUrl = process.env.FRONTEND_URL || 'https://rmm-psa-dashboard-5jyun.ondigitalocean.app';
    const accountLink = await StripeService.createAccountLink(
      accountId,
      `${frontendUrl}/integrations?stripe_onboarding=success`,
      `${frontendUrl}/integrations?stripe_onboarding=refresh`
    );
 
    // Update account_link_created_at and expires_at
    await pool.query(
      `UPDATE stripe_config 
       SET account_link_created_at = NOW(),
           account_link_expires_at = to_timestamp($1),
           updated_at = NOW()
       WHERE stripe_account_id = $2`,
      [accountLink.expires_at, accountId]
    );
 
    res.json({
      account_id: accountId,
      onboarding_url: accountLink.url,
      expires_at: accountLink.expires_at
    });
  } catch (error) {
    console.error('❌ Error starting Stripe Connect onboarding:', error);
    
    // Check if this is the "Connect not enabled" error
    if (error.message && error.message.includes('signed up for Connect')) {
      return res.status(400).json({
        error: 'Stripe Connect not enabled',
        message: 'Stripe Connect must be enabled on your Stripe account before creating connected accounts.',
        instructions: [
          '1. Go to https://dashboard.stripe.com/connect',
          '2. Click "Get started" to enable Stripe Connect',
          '3. Complete the platform setup',
          '4. Return here and try connecting again'
        ],
        setupUrl: 'https://dashboard.stripe.com/connect'
      });
    }
    
    res.status(500).json({ 
      error: 'Failed to start Stripe onboarding', 
      message: error.message 
    });
  }
});
 
/**
 * POST /api/stripe/connect/refresh
 * 
 * Regenerates onboarding link if previous link expired.
 * 
 * Stripe account links expire after ~5 minutes. If tenant didn't complete
 * onboarding in time, dashboard calls this to generate a fresh link.
 * 
 * @route POST /api/stripe/connect/refresh
 * @param {express.Request} req - Express request
 * @param {express.Response} res - Express response with new onboarding URL
 * @returns {Promise<Object>} New onboarding URL and expiration
 * 
 * @example
 * // Response:
 * {
 *   "onboarding_url": "https://connect.stripe.com/setup/e/acct_1234567890/...",
 *   "expires_at": 1710630300
 * }
 */
router.post('/connect/refresh', authenticateToken, async (req, res) => {
  try {
    const tenantId = req.user.tenant_id;
 
    // Get tenant's Stripe account ID
    const configResult = await pool.query(
      'SELECT stripe_account_id FROM stripe_config WHERE tenant_id = $1',
      [tenantId]
    );
 
    if (configResult.rows.length === 0) {
      return res.status(404).json({ error: 'Stripe account not found. Please start onboarding first.' });
    }
 
    const accountId = configResult.rows[0].stripe_account_id;
 
    // Generate new onboarding link
    const frontendUrl = process.env.FRONTEND_URL || 'https://rmm-psa-dashboard-5jyun.ondigitalocean.app';
    const accountLink = await StripeService.createAccountLink(
      accountId,
      `${frontendUrl}/integrations?stripe_onboarding=success`,
      `${frontendUrl}/integrations?stripe_onboarding=refresh`
    );
 
    // Update timestamps
    await pool.query(
      `UPDATE stripe_config 
       SET account_link_created_at = NOW(),
           account_link_expires_at = to_timestamp($1),
           updated_at = NOW()
       WHERE stripe_account_id = $2`,
      [accountLink.expires_at, accountId]
    );
 
    res.json({
      onboarding_url: accountLink.url,
      expires_at: accountLink.expires_at
    });
  } catch (error) {
    console.error('❌ Error refreshing Stripe Connect link:', error);
    res.status(500).json({ 
      error: 'Failed to refresh onboarding link', 
      message: error.message 
    });
  }
});
 
/**
 * POST /api/stripe/connect/sync
 * 
 * Syncs tenant's Stripe account status from Stripe API to database.
 * 
 * Dashboard calls this after onboarding redirect to fetch latest account status.
 * Also useful for manually refreshing verification status if requirements change.
 * 
 * @route POST /api/stripe/connect/sync
 * @param {express.Request} req - Express request
 * @param {express.Response} res - Express response with updated account status
 * @returns {Promise<Object>} Updated account configuration
 * 
 * @example
 * // Response:
 * {
 *   "synced": true,
 *   "account_status": "verified",
 *   "charges_enabled": true,
 *   "payouts_enabled": true,
 *   "verification_status": "verified"
 * }
 */
router.post('/connect/sync', authenticateToken, async (req, res) => {
  try {
    const tenantId = req.user.tenant_id;
 
    // Get tenant's Stripe account ID
    const configResult = await pool.query(
      'SELECT stripe_account_id FROM stripe_config WHERE tenant_id = $1',
      [tenantId]
    );
 
    if (configResult.rows.length === 0) {
      return res.status(404).json({ error: 'Stripe account not found' });
    }
 
    const accountId = configResult.rows[0].stripe_account_id;
 
    // Fetch latest account details from Stripe
    const account = await StripeService.retrieveAccount(accountId);
 
    // Update database with latest status
    await StripeService.updateAccountConfig(tenantId, account);
 
    // Check if onboarding was just completed
    if (account.charges_enabled && !configResult.rows[0].onboarding_completed_at) {
      await pool.query(
        `UPDATE stripe_config 
         SET onboarding_completed_at = NOW()
         WHERE tenant_id = $1`,
        [tenantId]
      );
    }
 
    // Fetch updated config from database
    const updatedConfig = await pool.query(
      `SELECT 
        account_status,
        charges_enabled,
        payouts_enabled,
        verification_status,
        requirements_currently_due,
        onboarding_completed_at
      FROM stripe_config
      WHERE tenant_id = $1`,
      [tenantId]
    );
 
    res.json({
      synced: true,
      ...updatedConfig.rows[0]
    });
  } catch (error) {
    console.error('❌ Error syncing Stripe account status:', error);
    res.status(500).json({ 
      error: 'Failed to sync account status', 
      message: error.message 
    });
  }
});
 
/**
 * DELETE /api/stripe/connect
 * 
 * Disconnects tenant from Stripe (removes Connected Account configuration).
 * 
 * **Warning:** This does NOT delete the Stripe account itself (must be done in Stripe Dashboard).
 * Only removes the connection from this platform.
 * 
 * @route DELETE /api/stripe/connect
 * @param {express.Request} req - Express request
 * @param {express.Response} res - Express response
 * @returns {Promise<Object>} Deletion confirmation
 */
router.delete('/connect', authenticateToken, async (req, res) => {
  try {
    const tenantId = req.user.tenant_id;
 
    const result = await pool.query(
      'DELETE FROM stripe_config WHERE tenant_id = $1 RETURNING stripe_account_id',
      [tenantId]
    );
 
    if (result.rows.length === 0) {
      return res.status(404).json({ error: 'Stripe account not found' });
    }
 
    console.log(`🗑️ Disconnected Stripe account ${result.rows[0].stripe_account_id} for tenant ${tenantId}`);
 
    res.json({ 
      disconnected: true,
      message: 'Stripe account disconnected successfully'
    });
  } catch (error) {
    console.error('❌ Error disconnecting Stripe account:', error);
    res.status(500).json({ error: 'Failed to disconnect Stripe account' });
  }
});
 
module.exports = router;