# 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](https://dashboard.stripe.com/)
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:

```bash
# 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:
   ```bash
   # 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:
   ```bash
   stripe login
   ```

3. Forward webhook events to your local server:
   ```bash
   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](https://dashboard.stripe.com/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:
   ```bash
   npm run dev
   ```

2. Start the Stripe CLI webhook forwarding (in another terminal):
   ```bash
   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:
   ```bash
   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](https://dashboard.stripe.com/products)
2. The system will automatically create products when users make recurring donations
3. Subscriptions will appear in [Stripe Dashboard > Subscriptions](https://dashboard.stripe.com/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](https://stripe.com/docs)
- [Stripe Support](https://support.stripe.com/)

For implementation questions, refer to:
- [Next.js Documentation](https://nextjs.org/docs)
- [Prisma Documentation](https://www.prisma.io/docs)