How to Integrate Bolt.new with Stripe Connect

Open your Bolt.new project and use the chat to generate the full Stripe Connect integration. Be specific about the account type (Express is simplest for most use cases), the payment flow (Direct charges vs Destination charges), and which webhooks you need. Bolt's AI understands Stripe Connect architecture and will generate the API routes, the onboarding redirect flow, and the React components for your dashboard. For an Express account integration with Direct charges, your prompt should specify: the onboarding flow, the charge creation with application fees, and the webhook handler. Bolt will generate an API route for creating the Connect account, an API route for creating the account link (Stripe's hosted onboarding page URL), and a route for creating payment intents or checkout sessions with the connected account as a parameter. After generating, review the files Bolt created. You should see at minimum: app/api/connect/account/route.ts (creates accounts), app/api/connect/onboard/route.ts (generates onboarding links), and app/api/webhooks/stripe/route.ts (handles events). If Bolt missed any of these, ask it to add the specific missing piece.

Before adding your API keys, review the generated code to understand what each route does and verify the payment logic is correct. The three core routes in a Stripe Connect integration each serve a distinct purpose in the payment lifecycle. The account creation route calls stripe.accounts.create() with type: 'express' and saves the returned account ID to your database, associated with your user's record. This account ID is the key that links your user to their Stripe Connect account for all future operations. The onboarding route calls stripe.accountLinks.create() with the account ID, a refresh URL (where to send the user if the link expires), and a return URL (where to send the user after they finish onboarding). This generates a one-time Stripe-hosted URL where the seller completes identity verification and bank account setup. You redirect the user to this URL from your frontend. The checkout or payment route creates a payment intent or checkout session with two additional parameters: the connected account ID (stripe_account) and an application_fee_amount. This tells Stripe to charge the customer, send most of the money to the seller's account, and keep the application_fee_amount on your platform account. Verify the webhook handler calls stripe.webhooks.constructEvent() with the raw request body (not the parsed JSON) and your webhook secret. This signature verification step is critical for security and is a common point of failure if Bolt generates it incorrectly.

1// app/api/connect/account/route.ts
2import { NextResponse } from 'next/server';
3import Stripe from 'stripe';
4
5const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
6  apiVersion: '2024-11-20.acacia',
7});
8
9export async function POST(request: Request) {
10  try {
11    const { email, userId } = await request.json();
12
13    // Create a Stripe Connect Express account
14    const account = await stripe.accounts.create({
15      type: 'express',
16      email,
17      capabilities: {
18        card_payments: { requested: true },
19        transfers: { requested: true },
20      },
21    });
22
23    // Save account.id to your database associated with userId
24    // await db.users.update({ where: { id: userId }, data: { stripeAccountId: account.id } });
25
26    return NextResponse.json({ accountId: account.id });
27  } catch (error) {
28    const message = error instanceof Error ? error.message : 'Unknown error';
29    return NextResponse.json({ error: message }, { status: 500 });
30  }
31}
32
33// app/api/connect/onboard/route.ts
34export async function POST(request: Request) {
35  const { accountId } = await request.json();
36  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || 'http://localhost:3000';
37
38  const accountLink = await stripe.accountLinks.create({
39    account: accountId,
40    refresh_url: `${baseUrl}/connect/refresh`,
41    return_url: `${baseUrl}/connect/return`,
42    type: 'account_onboarding',
43  });
44
45  return NextResponse.json({ url: accountLink.url });
46}
47
48// app/api/connect/checkout/route.ts
49export async function POST(request: Request) {
50  const { amount, currency, connectedAccountId, platformFeeAmount } =
51    await request.json();
52
53  const paymentIntent = await stripe.paymentIntents.create({
54    amount, // in cents
55    currency: currency || 'usd',
56    application_fee_amount: platformFeeAmount,
57    transfer_data: {
58      destination: connectedAccountId,
59    },
60  });
61
62  return NextResponse.json({ clientSecret: paymentIntent.client_secret });
63}

Stripe Connect requires two credentials during development: your test secret key and, once you have a deployed webhook URL, your webhook signing secret. In Bolt.new, environment variables for server-side code go into the .env file in your project root. Click the file explorer in Bolt and open or create the .env file. Add your Stripe test secret key — it starts with sk_test_. Never use your live key (sk_live_) during development. If Bolt has not already created a .env file, ask it to create one with placeholder values: 'Create a .env file in the project root with STRIPE_SECRET_KEY=your_key_here and STRIPE_WEBHOOK_SECRET=your_webhook_secret_here'. For the NEXT_PUBLIC_BASE_URL variable, set this to http://localhost:3000 during development. When you deploy, you will update this to your Netlify or Bolt Cloud URL. This variable controls where Stripe redirects sellers after the onboarding flow completes. Important: add .env to your .gitignore file if you are pushing to GitHub. Stripe secret keys committed to public repositories get automatically revoked by Stripe's secret scanning system, and you will need to rotate your keys. Bolt's AI typically adds .env to .gitignore automatically, but verify this is the case before any GitHub push.

1# .env
2# Stripe Connect credentials
3# Get these from https://dashboard.stripe.com/test/apikeys
4STRIPE_SECRET_KEY=sk_test_your_key_here
5
6# Get this after creating a webhook endpoint in Stripe Dashboard
7# Developers → Webhooks → Add endpoint → copy Signing secret
8STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
9
10# Your app's public URL (update after deploying)
11NEXT_PUBLIC_BASE_URL=http://localhost:3000
12
13# For Stripe Connect, also needed:
14# STRIPE_PUBLISHABLE_KEY for client-side Stripe.js initialization
15NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key_here

With your API key in place, you can test the account creation and onboarding redirect in Bolt's WebContainer preview. The outbound calls from your app to Stripe's API work fine during development — you can create Connect accounts, generate onboarding links, and receive redirect URLs from Stripe. What you cannot test in the preview is webhook delivery, which requires a publicly reachable URL. To test the onboarding flow: navigate to your seller dashboard or onboarding page in Bolt's preview, trigger the 'Connect your Stripe account' action, and verify that Bolt's API route successfully calls stripe.accounts.create() and returns an account ID. Then trigger the onboarding link generation and verify you receive a URL that starts with https://connect.stripe.com/setup/e/. You can click this link and it will take you to Stripe's real onboarding form (in test mode, you can use fake data). For the complete account activation and webhook testing, you need to deploy. Stripe's account.updated webhook fires when a seller completes onboarding, and without receiving this event, your app will not know the account is ready to accept payments. The WebContainer cannot receive this incoming event because browser tabs do not have publicly accessible URLs that Stripe can POST to. If you see CORS errors when making requests to Stripe from client-side code, this means some Stripe calls are being made from the browser instead of the API route. All Stripe API calls using the secret key must go through your server-side routes.

Stripe Connect depends heavily on webhooks for critical events: when a seller completes onboarding (account.updated), when a payment succeeds (payment_intent.succeeded), when a payout is sent (payout.created), and when a charge dispute opens (charge.dispute.created). None of these can be tested locally in Bolt's preview because incoming webhook events require a publicly accessible HTTPS URL. Deploy your app to Netlify first. In Bolt, go to Settings → Applications → Connect Netlify (OAuth authorization), then click Publish. Bolt will build and deploy your app, giving you a URL like your-app.netlify.app. This takes about 60-90 seconds for most Next.js projects. Once deployed, set your environment variables in the Netlify dashboard: Site settings → Environment variables → Add variable. Add STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET (you will fill this in next), and NEXT_PUBLIC_BASE_URL set to your Netlify URL. Now register your webhook endpoint in Stripe. Go to Stripe Dashboard → Developers → Webhooks → Add endpoint. Enter your webhook URL: https://your-app.netlify.app/api/webhooks/stripe. Select the events you need: account.updated, payment_intent.succeeded, and checkout.session.completed at minimum. After creating the endpoint, Stripe shows you a Signing secret starting with whsec_. Copy this and add it as STRIPE_WEBHOOK_SECRET in your Netlify environment variables. Trigger a redeploy on Netlify after adding the secret so your app picks it up. Update NEXT_PUBLIC_BASE_URL in your Netlify environment variables to your actual Netlify URL so that Stripe's onboarding redirect URLs point to the correct place after sellers complete their Connect account setup.

1// app/api/webhooks/stripe/route.ts
2// IMPORTANT: This route must read the RAW body for signature verification
3import { NextResponse } from 'next/server';
4import Stripe from 'stripe';
5
6const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
7  apiVersion: '2024-11-20.acacia',
8});
9
10export async function POST(request: Request) {
11  const body = await request.text(); // RAW text, not request.json()
12  const signature = request.headers.get('stripe-signature')!;
13
14  let event: Stripe.Event;
15
16  try {
17    event = stripe.webhooks.constructEvent(
18      body,
19      signature,
20      process.env.STRIPE_WEBHOOK_SECRET!
21    );
22  } catch (err) {
23    const message = err instanceof Error ? err.message : 'Unknown error';
24    console.error('Webhook signature verification failed:', message);
25    return NextResponse.json(
26      { error: 'Webhook signature verification failed' },
27      { status: 400 }
28    );
29  }
30
31  switch (event.type) {
32    case 'account.updated': {
33      const account = event.data.object as Stripe.Account;
34      // Update your database: mark seller account as active if charges_enabled
35      if (account.charges_enabled) {
36        console.log(`Account ${account.id} is now active and can accept payments`);
37        // await db.users.update({ where: { stripeAccountId: account.id }, data: { isActive: true } });
38      }
39      break;
40    }
41    case 'payment_intent.succeeded': {
42      const paymentIntent = event.data.object as Stripe.PaymentIntent;
43      console.log(`Payment ${paymentIntent.id} succeeded for $${paymentIntent.amount / 100}`);
44      // Update order status in your database
45      break;
46    }
47    default:
48      console.log(`Unhandled event type: ${event.type}`);
49  }
50
51  return NextResponse.json({ received: true });
52}