biblical-guide.com/STRIPE_SETUP_GUIDE.md

Stripe Integration Setup Guide

This guide will help you complete the Stripe integration for Biblical Guide donations.

What Has Been Implemented

1. Database Schema

• Added Donation model to Prisma schema with the following fields:
  • Stripe session and payment IDs
  • Donor information (email, name, message)
  • Amount and currency
  • Status tracking (PENDING, COMPLETED, FAILED, REFUNDED, CANCELLED)
  • Anonymous and recurring donation support
• Database has been synced with prisma db push

2. Backend API Routes

• /api/stripe/checkout - Creates Stripe checkout sessions
• /api/stripe/webhook - Handles Stripe webhook events for payment status updates

3. Frontend Pages

• /[locale]/donate - Main donation page with form
• /[locale]/donate/success - Success confirmation page after donation

4. Utility Functions

• lib/stripe.ts - Stripe initialization and helper functions

Setup Instructions

Step 1: Get Stripe API Keys

1. Go to Stripe Dashboard
2. Sign up or log in to your account
3. Navigate to Developers > API keys
4. Copy your keys:
   • Publishable key (starts with pk_)
   • Secret key (starts with sk_)

Step 2: Configure Environment Variables

Update your .env.local file with your actual Stripe keys:

# Stripe
STRIPE_SECRET_KEY=sk_test_your_actual_secret_key_here
STRIPE_PUBLISHABLE_KEY=pk_test_your_actual_publishable_key_here
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_actual_publishable_key_here

Important Notes:

• Use test keys (starting with sk_test_ and pk_test_) for development
• Use live keys (starting with sk_live_ and pk_live_) for production
• The NEXT_PUBLIC_ prefix makes the key available in the browser

Step 3: Set Up Stripe Webhook

Webhooks are crucial for updating donation status when payments complete.

For Development (Local Testing)

1. Install Stripe CLI:

   # On Linux
   wget https://github.com/stripe/stripe-cli/releases/download/v1.19.5/stripe_1.19.5_linux_x86_64.tar.gz
   tar -xvf stripe_1.19.5_linux_x86_64.tar.gz
   sudo mv stripe /usr/local/bin/
   

2. Login to Stripe CLI:

   stripe login
   

3. Forward webhook events to your local server:

   stripe listen --forward-to localhost:3010/api/stripe/webhook
   

4. Copy the webhook signing secret (starts with whsec_) and add it to your .env.local file

For Production

1. Go to Stripe Dashboard > Webhooks
2. Click Add endpoint
3. Enter your webhook URL: https://biblical-guide.com/api/stripe/webhook
4. Select events to listen to:
   • checkout.session.completed
   • checkout.session.expired
   • payment_intent.payment_failed
   • charge.refunded
5. Copy the webhook signing secret and add it to your production .env.local (or use environment variables in your hosting platform)

Step 4: Test the Integration

1. Start your development server:

   npm run dev
   

2. Start the Stripe CLI webhook forwarding (in another terminal):

   stripe listen --forward-to localhost:3010/api/stripe/webhook
   

3. Visit http://localhost:3010/en/donate (or your locale)

4. Test a donation using Stripe test cards:

   • Success: 4242 4242 4242 4242
   • Decline: 4000 0000 0000 0002
   • Requires Auth: 4000 0025 0000 3155
   • Use any future expiry date, any 3-digit CVC, and any ZIP code

5. Check the Stripe CLI output to see webhook events

6. Verify the donation status in your database:

   npx prisma studio
   

Step 5: Enable Recurring Donations (Optional)

Recurring donations are already implemented in the code. To enable them in Stripe:

1. Go to Stripe Dashboard > Products
2. The system will automatically create products when users make recurring donations
3. Subscriptions will appear in Stripe Dashboard > Subscriptions

Features Included

Donation Form Features

• ✅ Preset donation amounts ($5, $10, $25, $50, $100, $250)
• ✅ Custom donation amount input
• ✅ One-time and recurring donations (monthly/yearly)
• ✅ Donor information (email, name, message)
• ✅ Anonymous donation option
• ✅ Secure Stripe Checkout redirect
• ✅ Success confirmation page
• ✅ Email receipt from Stripe

Backend Features

• ✅ Stripe checkout session creation
• ✅ Webhook handling for payment events
• ✅ Database tracking of all donations
• ✅ Status updates (pending → completed/failed/cancelled)
• ✅ Support for refunds
• ✅ Metadata storage for additional info

Security Features

• ✅ Webhook signature verification
• ✅ Server-side payment processing
• ✅ No card details stored on your server
• ✅ PCI compliance through Stripe

File Structure

/root/biblical-guide/
├── app/
│   ├── api/
│   │   └── stripe/
│   │       ├── checkout/
│   │       │   └── route.ts          # Create checkout session
│   │       └── webhook/
│   │           └── route.ts          # Handle webhook events
│   └── [locale]/
│       └── donate/
│           ├── page.tsx              # Donation form
│           └── success/
│               └── page.tsx          # Success page
├── lib/
│   └── stripe.ts                     # Stripe utilities
├── prisma/
│   └── schema.prisma                 # Database schema (Donation model)
└── .env                              # Environment variables

Troubleshooting

Issue: "No signature" error in webhook

Solution: Make sure Stripe CLI is running with the correct forward URL

Issue: Webhook events not received

Solution: Check that your webhook secret is correct in .env.local

Issue: "Invalid API key" error

Solution: Verify your Stripe keys are correct and match the environment (test/live)

Issue: Donation status stays PENDING

Solution: Check webhook events are being received and processed correctly

Going Live Checklist

Before launching in production:

• Switch to live Stripe API keys (not test keys)
• Set up production webhook endpoint in Stripe Dashboard
• Update NEXTAUTH_URL in .env.local to production URL (or use environment variables in hosting platform)
• Test a real payment with a real card
• Set up Stripe email receipts (in Stripe Dashboard > Settings > Emails)
• Configure Stripe tax settings if needed
• Review Stripe security settings
• Set up monitoring for failed payments
• Create a plan for handling refunds

Admin Dashboard (Future Enhancement)

You may want to add an admin page to view donations:

• View all donations
• Filter by status, date, amount
• View donor messages
• Export donation data
• Issue refunds

Support

For Stripe-specific questions:

• Stripe Documentation
• Stripe Support

For implementation questions, refer to:

• Next.js Documentation
• Prisma Documentation