Stripe Setup

Stripe is the default payment provider. This page covers the Codapult-specific setup steps.

API Keys

Get your keys from the Stripe Dashboard:

STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

Use test keys (sk_test_*) during development. Switch to live keys (sk_live_*) when going to production.

Test Mode

In test mode, use Stripe test card numbers:

Webhook Setup

Codapult's Stripe webhook endpoint is POST /api/webhooks/stripe.

Local Development

Use the Stripe CLI to forward events to your local server:

stripe listen --forward-to http://localhost:3000/api/webhooks/stripe

The CLI prints a webhook signing secret (whsec_...) — copy it to STRIPE_WEBHOOK_SECRET in .env.local.

Production

1. Go to Stripe Dashboard → Webhooks
2. Add endpoint: https://your-app.com/api/webhooks/stripe
3. Select the events listed below
4. Copy the signing secret to STRIPE_WEBHOOK_SECRET

Handled Events

Webhook payloads include metadata (userId, planId) set during checkout. All deliveries are logged in the webhook_delivery table.

Stripe Connect

For marketplace features, Codapult supports Stripe Connect. Your platform can collect an application fee on transactions:

NEXT_PUBLIC_STRIPE_CONNECT_FEE_PERCENT=10  # 10% platform fee (overrides appConfig.payments.stripeConnectFeePercent)

The server-side fee is read via env.stripeConnectFeePercent from @/lib/config. The Connect dashboard UI reads the display value from appConfig.payments.stripeConnectFeePercent in src/config/app.ts. Keep both values in sync.

The Connect integration handles onboarding, account creation, and fee collection. Manage connected accounts from the admin panel.

Going Live Checklist

• Switch from sk_test_* to sk_live_* keys
• Create a production webhook pointing to your live URL
• Update STRIPE_WEBHOOK_SECRET with the production signing secret
• Verify webhook events are being received (check webhook_delivery table)
• Configure the Stripe Customer Portal in Stripe Settings → Customer Portal

For the full Stripe documentation, see docs.stripe.com.