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

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