Integrations

Stripe Connect Setup

Set up Stripe Connect for payment processing

Overview

Stripe Connect enables multi-tenant payment processing. Each organization can connect their own Stripe account to accept payments.

Prerequisites

  • Stripe account (sign up here)
  • Stripe API keys
  • Stripe Connect enabled

Platform Account Setup

1. Get Stripe API Keys

  1. Go to Stripe Dashboard
  2. Navigate to DevelopersAPI Keys
  3. Copy:
    • Secret Key (starts with sk_)
    • Publishable Key (starts with pk_)

2. Configure Environment Variables

STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
NEXT_PUBLIC_APP_URL=http://localhost:3000
STRIPE_DEFAULT_COUNTRY=US

3. Enable Stripe Connect

  1. Go to Stripe Dashboard
  2. Navigate to ConnectSettings
  3. Enable Stripe Connect
  4. Choose account type: Express Accounts

Webhook Setup

1. Create Webhook Endpoint

  1. Go to DevelopersWebhooks
  2. Click Add Endpoint
  3. Enter URL:
    • Development: http://localhost:3000/api/webhooks/stripe (use ngrok)
    • Production: https://yourdomain.com/api/webhooks/stripe

2. Subscribe to Events

Select these events:

  • payment_intent.succeeded
  • payment_intent.payment_failed
  • account.updated
  • account.application.deauthorized

3. Get Webhook Secret

  1. Copy the Signing Secret (starts with whsec_)
  2. Add to environment:
STRIPE_WEBHOOK_SECRET=whsec_...

Stripe Connect Onboarding

Express Account Creation

The onboarding flow is handled in OpenInvoice:

  1. User goes to SettingsPayments
  2. Clicks Connect Stripe Account
  3. Redirected to Stripe onboarding
  4. Completes:
    • Business information
    • Bank account details
    • Identity verification
  5. Returns to OpenInvoice
  6. Account is connected

Account Status

Track account status:

  • Connected - Ready to accept payments
  • Pending - Onboarding in progress
  • Disconnected - Not connected

Payment Processing

Creating Payment Intents

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

const paymentIntent = await stripe.paymentIntents.create({
  amount: invoiceAmount,
  currency: 'usd',
  customer: customerId,
  payment_method: paymentMethodId,
  application_fee_amount: platformFee, // Optional
}, {
  stripeAccount: connectedAccountId, // Organization's Stripe account
});

Handling Webhooks

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

const event = stripe.webhooks.constructEvent(
  req.body,
  signature,
  process.env.STRIPE_WEBHOOK_SECRET!
);

if (event.type === 'payment_intent.succeeded') {
  // Update invoice status
  // Record payment
  // Send confirmation email
}

Platform Fees

Configuring Platform Fees

Set platform fee percentage:

STRIPE_PLATFORM_FEE_PERCENTAGE=2.9

Fees are calculated and applied automatically.

Testing

Test Mode

  1. Use Stripe test keys
  2. Use test card numbers:
    • Success: 4242 4242 4242 4242
    • Decline: 4000 0000 0000 0002
  3. Test Connect onboarding
  4. Verify webhooks

Production

  1. Use live Stripe keys
  2. Complete Stripe verification
  3. Set up production webhook
  4. Test with real accounts

Troubleshooting

Payments Not Processing

  • Verify Stripe account is connected
  • Check account status
  • Verify API keys
  • Review Stripe Dashboard logs

Webhook Issues

  • Verify webhook secret
  • Check webhook endpoint is accessible
  • Review webhook events in Stripe Dashboard
  • Test with Stripe CLI

Best Practices

  1. Use Test Mode - Test thoroughly before production
  2. Handle Errors - Implement proper error handling
  3. Monitor Webhooks - Track webhook delivery
  4. Secure Keys - Never expose secret keys
  5. Test Connect Flow - Verify onboarding works

Next Steps