# 📋 Stripe Payment System - Implementation Checklist

## Phase 1: Setup (15 minutes)

### Get Stripe API Keys
- [ ] Go to https://dashboard.stripe.com/apikeys
- [ ] Copy **Publishable key** (pk_test_...)
- [ ] Copy **Secret key** (sk_test_...)
- [ ] Navigate to https://dashboard.stripe.com/webhooks
- [ ] Create endpoint for: `https://yourdomain.com/payments/webhook/stripe`
- [ ] Select events: `invoice.payment_succeeded`, `invoice.payment_failed`
- [ ] Copy **Signing secret** (whsec_...)

### Configure Environment
- [ ] Open `.env` file
- [ ] Add `STRIPE_PUBLIC_KEY=pk_test_...`
- [ ] Add `STRIPE_SECRET_KEY=sk_test_...`
- [ ] Add `STRIPE_WEBHOOK_SECRET=whsec_...`
- [ ] Save file

### Verify Database
- [ ] Run: `php artisan migrate:status`
- [ ] Confirm migration `2026_04_02_100000_add_stripe_billing_fields` exists
- [ ] If not applied, run: `php artisan migrate --force`
- [ ] Tables updated: packages, subscriptions, payments

---

## Phase 2: Admin Configuration (10 minutes)

### Setup Stripe Payment Method
- [ ] Login to app as admin
- [ ] Navigate to `/admin/payment-methods`
- [ ] Click "Create Payment Method"
- [ ] Fill form:
  - **Name:** "Stripe"
  - **Provider:** "stripe"
  - **Is Active:** ✓ (checked)
  - **Description:** "Stripe recurring billing" (optional)
- [ ] Add Credential:
  - **Key:** "api_key"
  - **Value:** `sk_test_...` (your secret key)
- [ ] Click "Test" button
- [ ] Verify: See "Stripe credentials are valid" message
- [ ] Click "Save"

### Create Test Driver Packages
- [ ] Navigate to `/admin/packages`
- [ ] Click "Create Package"
- [ ] **Package 1 - Startup:**
  ```
  Name: Startup
  Description: For small operations
  Driver Limit: 5
  Truck Limit: 2
  Base Price: 30.00
  Price Per Driver: 10.00
  Billing Cycle: monthly
  Is Active: ✓
  Features: Select 2-3 features
  ```
- [ ] Click "Save"
- [ ] Create **Package 2 - Professional:**
  ```
  Name: Professional
  Description: For growing companies
  Driver Limit: 10
  Truck Limit: 5
  Base Price: 50.00
  Price Per Driver: 15.00
  Billing Cycle: monthly
  Is Active: ✓
  Features: Select 3-4 features
  ```
- [ ] Click "Save"

---

## Phase 3: User Testing (20 minutes)

### Create Test Company
- [ ] Logout (if needed)
- [ ] Create new account (company owner)
- [ ] Complete onboarding:
  - [ ] Fill company details
  - [ ] Add business information
  - [ ] Complete registration
- [ ] Login to dashboard

### Subscribe to Package
- [ ] Click on "Billing" or "Subscriptions" menu
- [ ] Navigate to `/subscriptions/select-package`
- [ ] Select "Startup" package
- [ ] Review terms and click "Subscribe"
- [ ] You'll be redirected to payment setup

### Complete First Payment
- [ ] System shows subscription pending
- [ ] Click "Create Stripe Subscription" or similar button
- [ ] Payment method already set to "Stripe"
- [ ] Click "Pay Now" or "Proceed to Payment"
- [ ] **Use Test Card:**
  - **Card Number:** 4242 4242 4242 4242
  - **Expiry:** 12/26 (any future date)
  - **CVC:** 123 (any 3 digits)
  - **Name:** Test User
- [ ] Click "Pay"
- [ ] Wait for processing...
- [ ] **Expected:** Redirect to success page with message
- [ ] Verify:
  - [ ] Subscription status changed to "active"
  - [ ] Page shows "Payment successful"
  - [ ] Next billing date is visible

### Verify Payment in Admin
- [ ] Navigate to `/admin/payments`
- [ ] Find your payment in the list
- [ ] Click to view details:
  - [ ] Status: "completed"
  - [ ] Amount: $30 + (driver_count × $10)
  - [ ] Transaction ID: starts with "in_"
  - [ ] Processing timestamp visible

---

## Phase 4: Feature Testing (15 minutes)

### Test Driver Limit Enforcement
- [ ] Navigate to `/owner/drivers` (as company owner)
- [ ] See current driver count in header badge
- [ ] Startup package limit: 5 drivers
- [ ] Try to add drivers:
  - [ ] Add 1st driver - Success ✓
  - [ ] Add 2nd driver - Success ✓
  - [ ] Add 3rd driver - Success ✓
  - [ ] Add 4th driver - Success ✓
  - [ ] Add 5th driver - Success ✓
  - [ ] Badge shows "5 of 5 drivers used"
  - [ ] "Add Driver" button disabled
- [ ] Try to add 6th driver:
  - [ ] Button or form prevented
  - [ ] See message: "Driver limit reached"

### Test Driver Count Affecting Billing
- [ ] Subscribe with 3 drivers current
- [ ] Run command: `php artisan billing:process-recurring-payments`
- [ ] Check payment amounts:
  - [ ] With 3 drivers: $30 + (3×$10) = $60
  - [ ] Payment record shows amount: 60.00
  - [ ] Payment shows driver_count: 3

### Test Webhook Simulation (Advanced)
- [ ] Open Laravel Tinker: `php artisan tinker`
- [ ] Get a payment:
  ```php
  $payment = \App\Models\Payment::first();
  $payment->status; // Should be 'pending'
  ```
- [ ] Manually trigger webhook:
  ```php
  $controller = app(\App\Http\Controllers\PaymentController::class);
  // Or check logs for webhook receipt
  ```

---

## Phase 5: Daily Automation Testing (10 minutes)

### Test Scheduled Commands Manually

#### Test 1: Update Driver Charges
- [ ] Open terminal
- [ ] Run: `php artisan billing:update-driver-charges`
- [ ] **Expected Output:**
  ```
  Checking X subscriptions...
  (shows if any driver count changes detected)
  Updated X subscription(s).
  ```
- [ ] Verify: No errors in output

#### Test 2: Process Recurring Payments
- [ ] Run: `php artisan billing:process-recurring-payments`
- [ ] **Expected Output:**
  ```
  Processing X subscriptions...
  Processing subscription Y...
  ✓ Subscription Y processed successfully
  Done.
  ```
- [ ] Verify: New Payment records created
- [ ] Verify: `next_billing_date` updated
- [ ] Check admin `/admin/payments` for new payments

### View Scheduled Tasks
- [ ] Run: `php artisan schedule:list`
- [ ] Should see:
  ```
  billing:update-driver-charges ..................... 01:00
  billing:process-recurring-payments ............... 02:00
  ```

---

## Phase 6: Advanced Testing (15 minutes)

### Test Failed Payment Retry
- [ ] Create subscription with declined card
- [ ] Use test card: `4000 0000 0000 0002` (DECLINE)
- [ ] Payment should fail
- [ ] Navigate to `/admin/payments`
- [ ] Find failed payment
- [ ] Click "Retry"
- [ ] Update with valid card: `4242 4242 4242 4242`
- [ ] Confirm retry successfully charges

### Test Pro-rated Charges
- [ ] Subscribe with 2 drivers on billing date
- [ ] Add 3 more drivers mid-cycle (day 15 of 30)
- [ ] Run: `php artisan billing:update-driver-charges`
- [ ] Verify Stripe subscription metadata updated
- [ ] Next billing will charge for all 5 drivers

### Test Invoice Summary
- [ ] As company owner, go to subscription detail page
- [ ] View invoice summary showing:
  - [ ] Base price
  - [ ] Driver count
  - [ ] Price per driver
  - [ ] Total amount
  - [ ] Next billing date

---

## Phase 7: Production Checklist (Before Deploying)

### Security Verification
- [ ] ✓ All Stripe keys are test keys (pk_test_, sk_test_)
- [ ] ✓ No live keys in repository
- [ ] ✓ Webhook secret properly configured
- [ ] ✓ Webhook endpoint uses HTTPS (required by Stripe)
- [ ] ✓ No sensitive data in logs

### Functionality Verification
- [ ] ✓ Payment method works without errors
- [ ] ✓ Subscriptions create successfully
- [ ] ✓ Webhooks are received and processed
- [ ] ✓ Payments update status correctly
- [ ] ✓ Driver limit enforcement working
- [ ] ✓ Scheduled commands run successfully
- [ ] ✓ Failed payments can be retried
- [ ] ✓ Pro-rated charges calculated correctly

### Code Quality
- [ ] ✓ No compilation errors
- [ ] ✓ Services properly handle exceptions
- [ ] ✓ Controllers have authorization checks
- [ ] ✓ Migrations applied cleanly
- [ ] ✓ Models have proper relationships

### Documentation
- [ ] ✓ README files clear and accurate
- [ ] ✓ API endpoints documented
- [ ] ✓ Testing guide covers main scenarios
- [ ] ✓ Troubleshooting section helpful
- [ ] ✓ Setup steps verified to work

---

## Phase 8: Production Deployment

### Before Going Live

#### Get Live Stripe Keys
- [ ] Go to https://dashboard.stripe.com/apikeys
- [ ] Toggle "Viewing test data" to OFF
- [ ] Copy live **Publishable key** (pk_live_...)
- [ ] Copy live **Secret key** (sk_live_...)
- [ ] Create live webhook endpoint
- [ ] Copy live **Signing secret** (whsec_...)

#### Update Production Environment
- [ ] SSH into production server
- [ ] Edit `.env` file:
  ```env
  STRIPE_PUBLIC_KEY=pk_live_...
  STRIPE_SECRET_KEY=sk_live_...
  STRIPE_WEBHOOK_SECRET=whsec_...
  ```
- [ ] Save and verify

#### Setup Cron Job
- [ ] Edit crontab: `crontab -e`
- [ ] Add entry:
  ```
  * * * * * cd /path/to/true-trucker/web && php artisan schedule:run >> /dev/null 2>&1
  ```
- [ ] Save (Ctrl+X, Y, Enter for nano)
- [ ] Verify: `crontab -l`

#### Test Production Connection
- [ ] Run: `php artisan tinker`
- [ ] Test Stripe connection:
  ```php
  \Stripe\Stripe::setApiKey(config('services.stripe.secret'));
  \Stripe\Customer::create(['name' => 'Test']);
  // Should succeed without error
  exit
  ```

#### Monitor First 24 Hours
- [ ] Check payment logs: `tail -f storage/logs/laravel.log | grep -i stripe`
- [ ] Verify webhook deliveries in Stripe dashboard
- [ ] Monitor failed payments
- [ ] Check scheduled task execution

---

## Phase 9: Ongoing Maintenance

### Daily Checks (Pick 1 time)
- [ ] Monitor error logs for payment issues
- [ ] Check failed payment counts
- [ ] Verify webhook delivery success rate

### Weekly Checks
- [ ] Review payment metrics
- [ ] Check for any retry failures
- [ ] Monitor customer complaints
- [ ] Verify cron job still running

### Monthly Checks
- [ ] Analyze billing patterns
- [ ] Review package usage
- [ ] Check for broken webhooks
- [ ] Update documentation if needed

### Quarterly Checks
- [ ] Review Stripe dashboard for suspicious activity
- [ ] Audit payment security
- [ ] Analyze failure rates and adjust
- [ ] Plan for enhancements/upgrades

---

## Troubleshooting Quick Reference

| Issue | Solution |
|-------|----------|
| "API key not configured" | Check STRIPE_SECRET_KEY in .env |
| "Invalid signature" | Verify STRIPE_WEBHOOK_SECRET matches Stripe |
| "Driver limit reached" | This is expected! Feature working correctly |
| "Webhook not received" | Check endpoint URL in Stripe, verify HTTPS |
| "Payment stuck pending" | Webhook may not have processed, manually trigger |
| "Scheduled task not running" | Verify cron job installed correctly |
| "Migration failed" | Ensure database is accessible, retry migrate |

---

## Final Verification

- [ ] **Setup:** All Stripe keys configured
- [ ] **Database:** Migrations applied, new fields visible
- [ ] **Admin:** Payment method created and tested
- [ ] **Packages:** Driver packages with pricing created
- [ ] **User:** Can subscribe to package
- [ ] **Payment:** Test payment processes successfully
- [ ] **Billing:** Scheduled commands run without errors
- [ ] **Webhook:** Webhook signature verification working
- [ ] **Limits:** Driver limits enforced correctly
- [ ] **Admin Panel:** Can view and manage payments

---

## ✅ Success Criteria

System is working correctly when:
1. ✅ Users can subscribe to packages
2. ✅ Payments process without errors
3. ✅ Payment status updates via webhooks
4. ✅ Driver limit prevents over-adding
5. ✅ Billing calculates correctly
6. ✅ Scheduled tasks run daily
7. ✅ Failed payments can be retried
8. ✅ Admin can view all payments
9. ✅ No errors in application logs
10. ✅ Stripe dashboard shows transactions

---

## 📞 Support Resources

- **Stripe Docs:** https://stripe.com/docs
- **Test Cards:** https://stripe.com/docs/testing
- **Laravel Docs:** https://laravel.com/docs
- **Implementation:** `README_STRIPE_PAYMENT_SYSTEM.md`
- **Setup Guide:** `STRIPE_QUICKSTART.md`
- **Testing:** `STRIPE_TESTING_GUIDE.md`

---

**Checkoff this list as you complete each step. Once all items are checked, your Stripe payment system is ready for production!**

**Estimated Total Time: 90 minutes**

Good luck! 🚀
