# RateRight Stripe Payment Testing Guide
**Version:** 1.0  
**Date:** 2026-02-15  
**Environment:** Test Mode Only  
**Critical:** Never test with real payment details  

## 🔒 Safety First - Pre-Testing Checklist

### ⚠️ MANDATORY VERIFICATION
**Before ANY payment testing:**

1. **Console Check:**
   ```
   Open browser console (F12)
   Look for: "Stripe test mode active" 
   If you see "live mode" → STOP IMMEDIATELY
   ```

2. **Dashboard Verification:**
   - Stripe dashboard shows "Test mode" badge
   - All amounts show in test currency
   - No real bank connections visible

3. **Environment Variables:**
   ```bash
   # Check these are test keys (start with pk_test_ or sk_test_)
   grep -r "STRIPE" .env*
   ```

**🚨 If ANY doubt about test mode → Contact Builder immediately**

---

## 1. Stripe Test Cards Reference

### Successful Payment Cards
```
💳 Visa: 4242 4242 4242 4242
💳 Visa (Debit): 4000 0566 5566 5556
💳 Mastercard: 5555 5555 5555 4444
💳 American Express: 3782 822463 10005
💳 Discover: 6011 1111 1111 1117

For all cards:
- Expiry: Any future date (e.g., 12/25)
- CVC: Any 3-4 digit number (e.g., 123)
- ZIP: Any 5 digits (e.g., 12345)
```

### Failed Payment Cards
```
❌ Generic Decline: 4000 0000 0000 0002
❌ Insufficient Funds: 4000 0000 0000 9995
❌ Lost Card: 4000 0000 0000 9987
❌ Stolen Card: 4000 0000 0000 9979
❌ Expired Card: 4000 0000 0000 0069
❌ Incorrect CVC: 4000 0000 0000 0127
```

### Special Test Scenarios
```
🔐 3D Secure Required: 4000 0025 0000 3155
⏱️ Processing Delay: 4000 0000 0000 0259
🌍 International: 4000 0000 0000 0044 (UK)
```

---

## 2. Payment Flow Testing Scripts

### 2.1 Standard Success Flow
**Time:** 3 minutes | **Priority:** Critical

#### Prerequisites
- Contractor account logged in
- Worker applied to job
- Ready to hire worker

#### Test Steps
1. **Initiate Hire:**
   - Navigate to job applications
   - Click "Hire" for selected worker
   - Verify amount shows: $50.00

2. **Enter Payment Details:**
   - Card: `4242 4242 4242 4242`
   - Expiry: `12/25`
   - CVC: `123`
   - Name: `Test User`

3. **Submit Payment:**
   - Click "Pay Now"
   - **Expected:** Processing indicator appears

4. **Verify Success:**
   - Success message within 5 seconds
   - Redirect to confirmation page
   - Email confirmation sent
   - Messaging unlocked between users

#### Success Criteria
- ✅ Payment processes in < 5 seconds
- ✅ No error messages in console
- ✅ Worker contact details now visible
- ✅ Job status updated to "Hired"
- ✅ Email confirmation received

---

### 2.2 Payment Decline Testing
**Time:** 5 minutes | **Priority:** High

#### Test Multiple Decline Scenarios

1. **Generic Decline:**
   - Card: `4000 0000 0000 0002`
   - **Expected:** "Your card was declined"
   - **Verify:** User can retry with different card

2. **Insufficient Funds:**
   - Card: `4000 0000 0000 9995`
   - **Expected:** "Insufficient funds"
   - **Verify:** Helpful error message suggests checking balance

3. **Expired Card:**
   - Card: `4000 0000 0000 0069`
   - **Expected:** "Your card has expired"
   - **Verify:** Suggests checking expiry date

#### Critical Checks After Decline
- [ ] No payment recorded in Stripe dashboard
- [ ] User remains on payment page
- [ ] Form allows retry without reload
- [ ] Worker NOT marked as hired
- [ ] No email confirmation sent
- [ ] Error message helpful and clear

---

### 2.3 3D Secure Authentication
**Time:** 3 minutes | **Priority:** Medium

#### Test Steps
1. **Use 3D Secure Card:** `4000 0025 0000 3155`
2. **Initiate Payment:** Follow normal payment flow
3. **3D Secure Popup:**
   - Popup should appear from Stripe
   - Click "Complete Authentication"
4. **Verify Success:** Payment completes normally

#### Expected Behavior
- 3D Secure modal opens
- Clear instructions for user
- Payment completes after authentication
- No timeout issues

---

## 3. Webhook Verification

### 3.1 Webhook Events to Monitor
**Time:** 5 minutes | **Priority:** High

#### Key Events
```
payment_intent.succeeded
payment_intent.payment_failed
payment_intent.requires_action
```

#### Verification Steps
1. **Stripe Dashboard:**
   - Go to Webhooks section
   - Find RateRight webhook endpoint
   - Check recent events

2. **Application Logs:**
   ```bash
   # Check webhook processing
   tail -f /var/log/rateright/webhooks.log
   ```

3. **Database Verification:**
   ```sql
   -- Check payment records match webhook events
   SELECT * FROM payments 
   WHERE created_at > NOW() - INTERVAL '1 hour'
   ORDER BY created_at DESC;
   ```

---

## 4. Database Payment Verification

### 4.1 Payment Record Validation
**Time:** 3 minutes per payment

#### Required Checks
1. **Access Supabase Dashboard:**
   - Go to https://supabase.com/dashboard
   - Select RateRight project
   - Navigate to Table Editor

2. **Verify Payment Tables:**
   ```sql
   -- Check payment was recorded
   SELECT 
     id, 
     amount, 
     status, 
     stripe_payment_intent_id,
     contractor_id,
     worker_id,
     created_at
   FROM payments 
   WHERE amount = 5000  -- $50.00 in cents
   ORDER BY created_at DESC
   LIMIT 5;
   ```

3. **Check Job Status Update:**
   ```sql
   -- Verify job status changed to 'hired'
   SELECT id, title, status, updated_at
   FROM jobs 
   WHERE status = 'hired'
   ORDER BY updated_at DESC;
   ```

#### Expected Database State
- Payment record exists with correct amount
- Status = 'succeeded'
- Stripe payment intent ID populated
- Job status updated to 'hired'
- User relationship records created

---

## 5. Error Handling Scenarios

### 5.1 Network Interruption During Payment
**Time:** 5 minutes | **Priority:** Critical

#### Test Scenario
1. **Start Payment Process:** Use valid test card
2. **Interrupt Network:**
   - Chrome DevTools → Network → Offline
   - Or disconnect WiFi
3. **Wait 30 seconds:** Leave offline
4. **Reconnect Network:** Turn back on
5. **Check Payment Status:** Verify no duplicate charges

#### Expected Behavior
- Clear error message about connectivity
- Payment either succeeds or fails cleanly
- No partial/stuck payment states
- User can retry payment

### 5.2 Browser Refresh During Payment
**Time:** 2 minutes

1. **Start Payment:** Click "Pay Now"
2. **Immediately Refresh:** Press F5 or Cmd+R
3. **Check Results:**
   - No duplicate payment processing
   - Clear payment status
   - User can retry if needed

---

## 6. Stripe Dashboard Monitoring

### 6.1 Real-Time Payment Tracking
**Time:** Ongoing during all tests

#### Dashboard Sections to Monitor
1. **Payments Tab:**
   - All test payments appear
   - Amounts match ($50.00)
   - Status shows correctly

2. **Events Tab:**
   - Payment events logged
   - Webhook deliveries successful
   - No failed webhook attempts

3. **Logs Tab:**
   - API requests/responses
   - Any error messages
   - Performance metrics

#### Screenshots to Take
- Payment success confirmations
- Any error messages
- Webhook delivery confirmations
- Event timeline for complex flows

---

## 7. Performance Testing

### 7.1 Payment Processing Speed
**Time:** 5 minutes

#### Speed Benchmarks
- Payment initiation: < 1 second
- Stripe processing: < 3 seconds
- Success confirmation: < 5 seconds total
- Database updates: < 2 seconds

#### Test Method
```javascript
// Browser console timing
console.time('payment-flow');
// Click "Pay Now"
// Wait for success confirmation
console.timeEnd('payment-flow');
```

---

## 8. Mobile Payment Testing

### 8.1 Mobile-Specific Scenarios
**Time:** 10 minutes

#### iOS Safari Testing
1. **Touch ID/Face ID:** If available, test biometric authentication
2. **Keyboard Issues:** Ensure number pad appears for card entry
3. **Viewport Changes:** Test portrait/landscape orientation

#### Android Chrome Testing
1. **Autofill:** Test Google Pay integration if enabled
2. **Back Button:** Ensure payment state preserved
3. **App Switching:** Background/foreground during payment

---

## 9. Comprehensive Test Checklist

### Pre-Testing Setup
- [ ] Confirmed test mode active
- [ ] Browser console open
- [ ] Stripe dashboard accessible
- [ ] Database access ready
- [ ] Test cards list handy

### Payment Success Tests
- [ ] Standard Visa payment
- [ ] Mastercard payment
- [ ] American Express payment
- [ ] 3D Secure flow
- [ ] International card

### Payment Failure Tests
- [ ] Generic decline
- [ ] Insufficient funds
- [ ] Expired card
- [ ] Invalid CVC
- [ ] Lost/stolen card

### Edge Case Tests
- [ ] Network interruption
- [ ] Browser refresh
- [ ] Multiple payment attempts
- [ ] Concurrent payments
- [ ] Mobile device testing

### Verification Steps
- [ ] Database records created
- [ ] Webhook events processed
- [ ] Email confirmations sent
- [ ] User access updated
- [ ] No duplicate charges

---

## 10. Issue Reporting Template

### Payment Bug Report Format
```
**Test Type:** [Success/Decline/3D Secure/Edge Case]
**Card Used:** [4242 4242 4242 4242]
**Browser:** [Chrome 120.0.0.0]
**Device:** [MacBook Pro / iPhone 14]
**Amount:** [$50.00]

**Steps to Reproduce:**
1. [Detailed steps]
2. [What happened]

**Expected Result:**
[What should have happened]

**Actual Result:**
[What actually happened]

**Console Errors:**
[Any JavaScript errors]

**Stripe Event ID:**
[From Stripe dashboard if available]

**Database Impact:**
[Check payment/job tables]

**Screenshots:**
[Attach payment screens]
```

---

## 🚨 Critical Failure Indicators

**Stop testing immediately if you see:**

1. **Real Money Processing:**
   - Live mode indicators
   - Real bank account connections
   - Actual charges on real cards

2. **Data Corruption:**
   - Payment records without corresponding jobs
   - User access granted without payment
   - Duplicate payment processing

3. **Security Issues:**
   - Payment details visible in logs
   - Unauthorized access granted
   - User data exposure

**Emergency Contact:** Builder via Rivet bridge immediately

---

## 📊 Test Results Summary Template

```
**Payment Testing Summary**
Date: [Date]
Duration: [Minutes]
Tests Completed: [X/Y]

**Successful Flows:**
- [ ] Standard payments (5/5)
- [ ] Decline handling (4/4) 
- [ ] 3D Secure (1/1)
- [ ] Mobile payments (3/3)

**Critical Issues Found:**
[List any critical issues]

**Minor Issues:**
[List minor issues]

**Performance:**
- Average payment time: [X.X seconds]
- Success rate: [XX%]
- Webhook delivery: [XX%]

**Database Integrity:**
- Payment records: ✅/❌
- Job status updates: ✅/❌
- User access updates: ✅/❌

**Recommendation:**
[Ready for production / Needs fixes / Major issues]
```