PayPal Integration Guide

FastSaaS includes built-in PayPal integration for one-time payments. This guide walks you through the complete setup.

Prerequisites

PayPal Business account
PayPal Developer account

Step 1: Create PayPal App

Go to developer.paypal.com
Navigate to Apps & Credentials
Click Create App
Choose Merchant as the app type
Copy your Client ID and Secret

Step 2: Configure Environment

Add your PayPal credentials to .env:

PAYPAL_CLIENT_ID="your-client-id"
PAYPAL_CLIENT_SECRET="your-client-secret"
PAYPAL_MODE="sandbox"  # or "live" for production

Step 3: Understanding the Payment Flow

FastSaaS uses PayPal's Server-Side integration:

sequenceDiagram
    Customer->>Frontend: Click "Buy Now"
    Frontend->>API: POST /api/checkout/create-order
    API->>PayPal: Create Order
    PayPal->>API: Order ID
    API->>Frontend: Redirect to PayPal
    Customer->>PayPal: Approve Payment
    PayPal->>Frontend: Return with token
    Frontend->>API: POST /api/checkout/capture-order
    API->>PayPal: Capture Payment
    PayPal->>API: Payment Complete
    API->>Frontend: Success + GitHub Access

Step 4: Create Order Endpoint

The /api/checkout/create-order endpoint creates a PayPal order:

// Already included in FastSaaS
export async function POST(request: NextRequest) {
  const { productId } = await request.json();

  const order = await paypal.createOrder({
    intent: "CAPTURE",
    purchase_units: [
      {
        amount: {
          currency_code: "USD",
          value: product.price,
        },
      },
    ],
  });

  return NextResponse.json({ orderId: order.id });
}

Step 5: Capture Payment

After the customer approves, capture the payment:

// /api/checkout/capture-order
const capture = await paypal.captureOrder(orderId);

if (capture.status === "COMPLETED") {
  // Grant access to the product
  await grantGitHubAccess(email, productId);
  await sendConfirmationEmail(email, productId);
}

Step 6: Post-Purchase Actions

FastSaaS automatically:

✅ Sends confirmation email
✅ Creates GitHub invitation
✅ Records purchase in database
✅ Sends webhook notifications

Testing in Sandbox

Use PayPal sandbox credentials for testing:

Sandbox Buyer Account:

Email: sb-buyer@personal.example.com
Password: See PayPal Developer Dashboard

Test Credit Card:

Number: 4111111111111111
Expiry: Any future date
CVV: Any 3 digits

Going Live

Create a Live app in PayPal Developer
Update .env with live credentials
Set PAYPAL_MODE="live"
Test with a small real transaction

Troubleshooting

"INVALID_CLIENT" Error

Verify Client ID and Secret are correct
Check that you're using the right mode (sandbox/live)

"INSTRUMENT_DECLINED"

The payment method was declined
Try a different card or PayPal account

Payment Not Captured

Check server logs for errors
Verify the order wasn't already captured

PayPal Integration Guide for FastSaaS