Learn how to integrate PayPal payments for both one-time and recurring subscriptions in your Indie Kit project

Setting Up PayPal Payments 💰

Indie Kit supports PayPal for both one-time purchases and recurring subscriptions. Follow this guide to get started! 🚀

Initial PayPal Setup 🛠️

Before configuring payment types, you'll need to set up your PayPal developer environment:

1. Create a PayPal Developer Account 👤

Go to developer.paypal.com
Click "Log in to Dashboard" and create your account
Complete the developer verification process

2. Create Test Accounts 🧪

In your PayPal Developer Dashboard, go to "Sandbox" > "Accounts"
Create one Test Business Account (this will be your merchant account)
Create one Test Personal Account (for testing purchases)
Note down the credentials for both accounts

3. Get API Credentials 🔑

Go to "My Apps & Credentials" in your developer dashboard
Click "Create App" under the "Sandbox" section
Choose your business account and give your app a name
Copy your Client ID and Secret Key

4. Set Up Environment Variables 📝

Add these to your .env.local file:

# PayPal Sandbox Configuration
NEXT_PUBLIC_PAYPAL_CLIENT_ID='AQLowgpUG45c3c6WpgPvkaCAqYh36dvtwjzeuMoJZnQydqnXgRHgF8HE3-jD26aCW8-9_2lmsWm5Dfzo'
PAYPAL_SECRET_KEY='EP01knzIEI8C8jGGOvRsVj41uX_AYouvCgnrB1JpFhSiUk6szFDYSrUXKkT4xdzSxKs33qg-00q1NqJw'
NEXT_PUBLIC_PAYPAL_IS_SANDBOX=true # This is for test payments, set to false for production

5. Configure Webhooks 🪝

For local development, you'll need ngrok:

# Install ngrok (if not already installed)
npm install -g ngrok

# Start your Next.js app
npm run dev

# In another terminal, expose your local server
ngrok http 3000

Then in PayPal Developer Dashboard:

Go to "Webhooks" section
Click "Create Webhook"
Use your ngrok URL: https://your-ngrok-url.ngrok.io/api/webhooks/paypal
Select relevant events (payments, subscriptions)
Copy the Webhook ID and add to your environment:

PAYPAL_WEBHOOK_ID=1VC691815S403080G

💡 Pro Tip

Testing locally with ngrok is highly recommended before deploying to production. This ensures your webhook handling works correctly!

Setting up One-time Payments 💸

Perfect for products, courses, or any single purchase!

6. Create Plan in Database 📊

Go to /super-admin/plans/ in your app
Create a new plan and add setup the onetime price.

Your existing getSubscribeUrl function already supports PayPal:

// Usage for one-time payment
const subscribeUrl = getSubscribeUrl({
  codename: "pro", // From database
  type: PlanType.ONETIME,
  provider: PlanProvider.PAYPAL,
});

// Use in components/pages

<Link href={subscribeUrl}>
    Checkout with PayPal
</Link>

8. Test Your Setup ✅

Use your test personal account to make a purchase
Verify the webhook receives payment confirmations
Check that the payment status updates correctly

💡 Perfect For

Digital products

Course purchases

One-time software licenses

Ebooks and resources

Setting up Recurring Payments 🔄

Great for SaaS subscriptions and membership sites!

6. Create Subscription Plan in PayPal 📋

Log into your Sandbox Business Account
Go to "Business Tools" > "Subscriptions" > "Get Started"
Click "Create Plan"
You might need to create a Product first, then the plan
Configure your plan:
- Billing cycle: Monthly or Yearly
- Setup fee: Optional initial charge
- Trial period: If desired
Copy the Plan ID after creation

7. Add Plan ID to Database 🗄️

Go to /super-admin/plans/ in your app
Create or edit your plan and add the paypal plan id in monthly or yearly price section. No need to specify the price in cents here as it's managed by paypal.

// Usage for monthly subscription
const monthlyUrl = getSubscribeUrl({
  codename: "pro", // From database
  type: PlanType.MONTHLY,
  provider: PlanProvider.PAYPAL,
});

// Usage for yearly subscription  
const yearlyUrl = getSubscribeUrl({
  codename: "pro", // From database
  type: PlanType.YEARLY,
  provider: PlanProvider.PAYPAL,
});

// Use in components/pages

<Link href={monthlyUrl}>
    Subscribe monthly with PayPal
</Link>

<Link href={yearlyUrl}>
    Subscribe yearly with PayPal
</Link>

9. Test Subscription Flow 🧪

Subscribe using your test personal account
Verify subscription creation and billing
Test subscription cancellation
Check webhook notifications for all events

💡 Perfect For

SaaS applications

Membership sites

Monthly/yearly services

Content subscriptions

Production Configuration 🌟

When you're ready to go live:

Update Environment Variables 🔄

Replace your sandbox credentials with production ones:

# Production PayPal Configuration
NEXT_PUBLIC_PAYPAL_CLIENT_ID='your-production-client-id'
PAYPAL_SECRET_KEY='your-production-secret-key'
NEXT_PUBLIC_PAYPAL_IS_SANDBOX=false
PAYPAL_WEBHOOK_ID='your-production-webhook-id'

Production Webhook Setup 🌐

Create a new webhook in PayPal's production dashboard
Use your actual domain: https://yourdomain.com/api/webhooks/paypal
Update the webhook ID in your environment variables

Troubleshooting 🔍

Common issues and solutions:

1. Webhook Not Receiving Events 📡

Verify your ngrok tunnel is running for local development
Check that webhook URL is correctly set in PayPal dashboard
Ensure your webhook endpoint is properly implemented
Look at PayPal webhook logs for delivery attempts

2. Payment Authentication Errors 🔐

Double-check your Client ID and Secret Key
Verify you're using the correct sandbox/production environment
Ensure your PayPal app has the necessary permissions

3. Subscription Creation Fails 📋

Verify the PayPal Plan ID is correct
Check that the plan is active in your PayPal dashboard
Ensure your business account has subscription features enabled

4. Environment Variable Issues ⚙️

Restart your development server after changing .env.local
Verify variable names match exactly (case-sensitive)
Check for typos in your PayPal credentials

Next Steps 🎯

Now that PayPal is configured:

Test thoroughly with sandbox accounts before going live
Set up proper error handling for failed payments
Implement subscription management features
Configure email notifications for payment events
Set up analytics to track payment conversions

Your PayPal integration is ready! Start accepting payments with confidence! 💪

🚨 Important Note

Always test your payment flows thoroughly in sandbox mode before switching to production. PayPal's sandbox environment closely mimics production behavior.

PayPal Integration