1. Connect Stripe

What Happens When You Connect

When you connect a Stripe account to your BillStack team:

1. Your Stripe secret key, publishable key, and webhook secret are encrypted with AES-256-GCM and stored in the database
2. BillStack creates an isolated PostgreSQL schema for your team (stripe_team_{teamId})
3. The stripe-sync-engine runs migrations inside that schema to hold synced Stripe data
4. BillStack verifies the keys are valid by calling stripe.accounts.retrieve()

Option A: Dashboard UI

1. Log in to your BillStack dashboard
2. Navigate to Team Settings > Stripe Connection
3. Paste your Secret Key (sk_live_... or sk_test_...)
4. Paste your Publishable Key (pk_live_... or pk_test_...)
5. Paste your Webhook Secret (whsec_...) — you'll update this in Step 5
6. Click Connect

Option B: API

curl -X POST https://your-billstack.com/api/billstack/teams/{teamId}/stripe/connect \
  -H "Content-Type: application/json" \
  -H "Cookie: <session-cookie>" \
  -d '{
    "secretKey": "sk_test_...",
    "publishableKey": "pk_test_...",
    "webhookSecret": "whsec_..."
  }'

Response:

{
  "success": true,
  "webhookUrl": "https://your-billstack.com/api/webhooks/stripe/{teamId}",
  "syncStatus": "pending"
}

Verify the Connection

After connecting, check the status:

curl https://your-billstack.com/api/billstack/teams/{teamId}/stripe/status \
  -H "Cookie: <session-cookie>"

Response:

{
  "connected": true,
  "isActive": true,
  "syncStatus": "ready",
  "schemaExists": true,
  "accountName": "My SaaS Inc.",
  "keyValid": true
}

Getting Your Stripe Keys

If you don't have your keys handy:

For initial setup, you can use a placeholder webhook secret and update it later when you configure the webhook endpoint in Stripe.

Test vs Live Mode

Use test mode keys (sk_test_...) during migration to avoid affecting real customers. Switch to live keys once you've verified everything works:

1. Connect with test keys first
2. Complete all migration steps
3. Disconnect: DELETE /api/billstack/teams/{teamId}/stripe/disconnect
4. Reconnect with live keys

Warning: Disconnecting drops the team's synced data schema. This is safe because BillStack will re-sync everything from Stripe when you reconnect and backfill.

Next Step

Once connected, create API keys so your SaaS applications can authenticate with BillStack.