How to Integrate Bolt.new with PayPal

PayPal uses a separate developer environment at developer.paypal.com that's completely isolated from your personal or business PayPal account. You need to create a developer app to get the sandbox credentials used for testing. Log in at developer.paypal.com using your PayPal credentials. Navigate to My Apps & Credentials. Click 'Create App' under the Sandbox section. Give it a descriptive name like 'MyBoltApp-Sandbox.' After creation, you'll see your Sandbox Client ID (a long string starting with 'A...') and a Secret (click to reveal). Copy both. Also on the developer dashboard, you'll see pre-created sandbox test accounts — you need a sandbox buyer account to test the payment flow. Find the sandbox personal account email and password under Sandbox → Accounts. When you're ready for production, create a separate Live app and use those credentials instead. Never mix sandbox and live credentials.

You'll need two PayPal packages: @paypal/paypal-js (or @paypal/react-paypal-js for React integration) for the client-side payment button UI, and no additional package for server-side API calls since you'll use the native fetch API for PayPal's REST API. The @paypal/react-paypal-js package provides the PayPalScriptProvider context and PayPalButtons component, which handle the complex PayPal SDK lifecycle management automatically. Store your credentials in .env — the client ID uses NEXT_PUBLIC_ prefix because it's needed by the client-side PayPal button script, but the secret uses no prefix because it's only read by your API routes. This is one of the rare cases where a 'public' variable is intentionally exposed — PayPal client IDs are designed to be visible in client code.

1# .env — sandbox for development
2NEXT_PUBLIC_PAYPAL_CLIENT_ID=your-sandbox-client-id-here
3PAYPAL_CLIENT_SECRET=your-sandbox-secret-here
4PAYPAL_API_URL=https://api-m.sandbox.paypal.com
5
6# For production, change to:
7# NEXT_PUBLIC_PAYPAL_CLIENT_ID=your-live-client-id
8# PAYPAL_CLIENT_SECRET=your-live-secret
9# PAYPAL_API_URL=https://api-m.paypal.com

PayPal's server-side flow has two distinct steps that each require a separate API route. The first route creates a PayPal order: it acquires an OAuth access token using your client ID and secret (a credentials-based POST request), then uses that token to create an order with the amount, currency, and intent. The route returns the PayPal order ID to the client. The second route captures the order after the customer approves it in the PayPal interface: the client sends the order ID back to this route, which makes a PayPal API call to capture the funds. The capture response contains the transaction details (amount, payer info, transaction ID) that you should save to your database. Both routes require the PAYPAL_CLIENT_SECRET which never leaves the server.

1// app/api/paypal/create-order/route.ts
2import { NextResponse } from 'next/server';
3
4async function getPayPalAccessToken(): Promise<string> {
5  const auth = Buffer.from(
6    `${process.env.NEXT_PUBLIC_PAYPAL_CLIENT_ID}:${process.env.PAYPAL_CLIENT_SECRET}`
7  ).toString('base64');
8
9  const response = await fetch(
10    `${process.env.PAYPAL_API_URL}/v1/oauth2/token`,
11    {
12      method: 'POST',
13      headers: {
14        'Authorization': `Basic ${auth}`,
15        'Content-Type': 'application/x-www-form-urlencoded',
16      },
17      body: 'grant_type=client_credentials',
18    }
19  );
20  const data = await response.json();
21  return data.access_token;
22}
23
24export async function POST(request: Request) {
25  try {
26    const { amount, currency = 'USD' } = await request.json();
27    const accessToken = await getPayPalAccessToken();
28
29    const response = await fetch(
30      `${process.env.PAYPAL_API_URL}/v2/checkout/orders`,
31      {
32        method: 'POST',
33        headers: {
34          'Authorization': `Bearer ${accessToken}`,
35          'Content-Type': 'application/json',
36        },
37        body: JSON.stringify({
38          intent: 'CAPTURE',
39          purchase_units: [{
40            amount: {
41              currency_code: currency,
42              value: amount.toFixed(2),
43            },
44          }],
45        }),
46      }
47    );
48
49    const order = await response.json();
50    return NextResponse.json({ id: order.id });
51  } catch (error) {
52    return NextResponse.json({ error: 'Failed to create order' }, { status: 500 });
53  }
54}

The @paypal/react-paypal-js library handles the complex PayPal JavaScript SDK lifecycle — loading the external PayPal script, initializing it with your client ID, and rendering the Smart Payment Button. You wrap your payment page with the PayPalScriptProvider context component (providing your client ID from the NEXT_PUBLIC_ environment variable), then use the PayPalButtons component where you want the button to appear. The PayPalButtons component takes two key callback props: createOrder (which calls your /api/paypal/create-order route and returns the order ID) and onApprove (which calls your /api/paypal/capture-order route after the customer approves payment in the PayPal popup). The PayPal button handles all the popup/modal logic internally — you just need to handle the success and error callbacks.

1'use client';
2import { PayPalScriptProvider, PayPalButtons } from '@paypal/react-paypal-js';
3import { useState } from 'react';
4
5interface PayPalCheckoutProps {
6  amount: number;
7  currency?: string;
8  onSuccess?: (details: Record<string, unknown>) => void;
9}
10
11export function PayPalCheckout({
12  amount,
13  currency = 'USD',
14  onSuccess,
15}: PayPalCheckoutProps) {
16  const [error, setError] = useState<string | null>(null);
17
18  return (
19    <PayPalScriptProvider
20      options={{
21        clientId: process.env.NEXT_PUBLIC_PAYPAL_CLIENT_ID!,
22        currency,
23      }}
24    >
25      <div className="max-w-sm">
26        <PayPalButtons
27          createOrder={async () => {
28            setError(null);
29            const response = await fetch('/api/paypal/create-order', {
30              method: 'POST',
31              headers: { 'Content-Type': 'application/json' },
32              body: JSON.stringify({ amount, currency }),
33            });
34            const order = await response.json();
35            if (!response.ok) throw new Error(order.error);
36            return order.id;
37          }}
38          onApprove={async (data) => {
39            const response = await fetch('/api/paypal/capture-order', {
40              method: 'POST',
41              headers: { 'Content-Type': 'application/json' },
42              body: JSON.stringify({ orderID: data.orderID }),
43            });
44            const details = await response.json();
45            if (!response.ok) throw new Error('Capture failed');
46            onSuccess?.(details);
47          }}
48          onError={(err) => {
49            setError('Payment failed. Please try again.');
50            console.error('PayPal error:', err);
51          }}
52        />
53        {error && (
54          <p className="text-red-600 text-sm mt-2">{error}</p>
55        )}
56      </div>
57    </PayPalScriptProvider>
58  );
59}

During development in Bolt's WebContainer, you can test the complete payment flow using the PayPal popup — the createOrder and captureOrder steps work in the preview since they make outbound HTTP calls to PayPal's sandbox. However, PayPal also sends webhook events (order.approved, payment.capture.completed) to confirm payments asynchronously on your server. These webhooks require a publicly accessible URL that PayPal can call. Bolt's WebContainer has no public URL, so webhook registration must wait until after deployment. Deploy to Netlify or Bolt Cloud first. After deployment, go to developer.paypal.com → your app → Webhooks → Add Webhook. Enter your deployed URL (e.g., https://your-app.netlify.app/api/paypal/webhook) and select the events you need. Create the webhook handler API route and verify signatures using PayPal's webhook verification API. Set your production PayPal credentials (live client ID and secret) in your hosting platform's environment variables.