# Stripe Payout Diagnostic Guide

## Issue: Payment showing in UI but not in bank account

This is **usually normal** - Stripe holds funds before transferring to your bank. Let's diagnose:

---

## Step 1: Verify You're in Live Mode (Not Test Mode)

**CRITICAL**: Test mode payments are fake - no real money moves.

1. Go to https://dashboard.stripe.com
2. Look at the top-right corner
3. Check the toggle switch:
   - **If it says "Test mode ON"**: You're in test mode - no real money
   - **If it says "Viewing test data"**: Switch to Live mode
   - **If it says "Live mode" or toggle is OFF/gray**: You're in live mode ✅

**If you were in test mode:**
- The $5 payment was a test transaction
- No real money was charged
- You need to redo the donation in Live mode

---

## Step 2: Check Your Stripe Balance

Your Stripe balance shows funds that are available or pending payout.

1. Go to https://dashboard.stripe.com/balance/overview
2. Look for two numbers:

### Available for Payout
- **If $0.00**: Funds are still pending
- **If $5.00 NZD (or converted amount)**: Funds are ready but not sent yet

### Pending
- **Shows funds waiting to become available**
- New accounts: 7-14 day hold
- Established accounts: 2 day rolling reserve

**Normal behavior**: Your $5 should appear in "Pending" first, then move to "Available" after the hold period.

---

## Step 3: Check Payout Schedule

1. Go to https://dashboard.stripe.com/settings/payouts
2. Look for **"Payout schedule"** section
3. Check settings:

### Standard Payout Schedule (Most Common):
- **Frequency**: Daily, Weekly, or Monthly
- **Timing**: "2 business days after charge" (standard)
- **Status**: Should say "Automatic payouts enabled"

### What to look for:
- ✅ **"Automatic"**: Payouts happen automatically
- ❌ **"Manual"**: You must request payouts manually
- ⚠️ **"Payouts paused"**: Issue with account - see Step 6

**If set to Manual:**
1. Click "Switch to automatic payouts"
2. Or manually request payout: Balance → "Pay out funds"

---

## Step 4: Verify Bank Account is Connected

1. Go to https://dashboard.stripe.com/settings/payouts
2. Scroll to **"Bank accounts and debit cards"** section
3. Check:

### You should see:
- ✅ A bank account listed (with last 4 digits)
- ✅ Status: "Verified" or "Default"
- ✅ Currency: NZD

### If NO bank account listed:
1. Click **"Add bank account"**
2. Enter your NZ bank details:
   - Account number (format: XX-XXXX-XXXXXXX-XX)
   - Account holder name
   - Bank name
3. Verify via micro-deposits (Stripe sends 2 small deposits, you confirm amounts)

### If bank account shows "Verification required":
- Check your email for verification instructions from Stripe
- You may need to confirm micro-deposit amounts
- Or upload bank statement for verification

---

## Step 5: Check Payment Status

Let's verify the $5 payment actually succeeded:

1. Go to https://dashboard.stripe.com/payments
2. Look for your $5 NZD payment
3. Click on it to see details

### Check the Status:
- ✅ **"Succeeded"**: Payment captured successfully
- ⏳ **"Processing"**: Still being processed (rare for card payments)
- ❌ **"Failed"** or **"Requires payment method"**: Payment didn't work

### Check the Fee:
- Stripe charges fees on each transaction
- For NZD: 2.9% + $0.30 per transaction
- $5.00 NZD → ~$4.55 NZD net after fees

### Check Available On:
- This shows when funds become available for payout
- Usually: Payment date + 2 business days
- Example: Oct 18 payment → Available Oct 20 (if no weekends)

---

## Step 6: Check Account Status

Your account might be restricted or need verification:

1. Go to https://dashboard.stripe.com/settings/account
2. Look for banners or alerts at the top
3. Check **"Account status"** section

### Common issues:
- ⚠️ **"Verification required"**: Need to provide business documents
- ⚠️ **"Payouts paused"**: Account under review
- ⚠️ **"Risk review"**: Flagged for unusual activity

### Required information:
- Business type (Individual / Company)
- Business details (name, address, URL)
- Personal information (ID verification)
- Bank account verification

**If verification required:**
- Click the banner or alert
- Follow the steps to submit required documents
- Verification usually takes 1-2 business days

---

## Step 7: Timeline - When to Expect Payout

Here's the typical timeline for a new Stripe account:

### Day 0 (Today - Oct 18):
- ✅ Customer pays $5 NZD
- ✅ Payment appears in Stripe Dashboard
- ✅ Payment appears in your Tractatus UI
- ❌ **No payout yet** - this is normal

### Day 0-7:
- Funds in "Pending" balance
- **New accounts**: 7-14 day initial hold period
- **This is Stripe's risk mitigation for new accounts**

### Day 7-14:
- Funds move from "Pending" to "Available"
- Automatic payout scheduled

### Day 9-16:
- **Payout sent to your bank account**
- Bank processing: 1-3 business days
- **Money appears in your bank account**

### Timeline Summary:
- **New Stripe account**: 7-14 days until first payout
- **Established account (after 90 days)**: 2 days
- **Weekends/holidays add extra days**

---

## Step 8: How to Check Scheduled Payouts

1. Go to https://dashboard.stripe.com/payouts
2. You should see a list of payouts

### What you might see:
- **"In transit"**: Payout sent to bank, waiting for bank processing
- **"Paid"**: Successfully received by bank
- **"Scheduled"**: Future payout queued
- **Empty list**: No payouts scheduled yet (if balance still pending)

---

## Quick Diagnostic Checklist

Run through this checklist:

- [ ] I'm in **Live mode** (not test mode)
- [ ] Payment shows **"Succeeded"** in Stripe Dashboard
- [ ] Payment amount is correct: $5 NZD
- [ ] Balance shows funds in **"Pending"** or **"Available"**
- [ ] Bank account is **connected and verified**
- [ ] Payout schedule is set to **"Automatic"**
- [ ] Account status is **"Active"** (no verification required)
- [ ] I understand the **7-14 day hold** for new accounts

---

## Expected Outcome for New Account

**This is completely normal:**
1. ✅ Oct 18: Payment succeeded ($5 NZD)
2. ✅ Oct 18: Shows in Tractatus transparency dashboard
3. ✅ Oct 18-25: Funds held in "Pending" balance
4. ⏳ Oct 25-28: Funds become "Available"
5. ⏳ Oct 26-29: Automatic payout sent to bank
6. ⏳ Oct 27-30: **Money appears in your bank account**

**Stripe's reasoning:**
- New accounts have longer holds to prevent fraud
- After 90 days of good history, holds reduce to 2 days
- This protects both you and customers from chargebacks

---

## If Money Still Missing After 14 Days

1. **Check Stripe Balance**: https://dashboard.stripe.com/balance
   - Should be $0 if payout completed
   - Should show amount if still pending

2. **Check Payouts**: https://dashboard.stripe.com/payouts
   - Should show "Paid" status
   - Should show payout date

3. **Check Bank Statement**:
   - Look for "STRIPE" or "Stripe Payments"
   - Amount might be slightly less due to fees
   - Can take 1-3 business days after "Paid" status

4. **Contact Stripe Support**:
   - https://dashboard.stripe.com/support
   - Provide payment ID and payout ID
   - They can trace the exact status

---

## Testing Without Waiting

If you want to verify the system works without waiting 14 days:

### Option 1: Request Manual Payout (if available)
1. Go to Balance → "Pay out funds"
2. Only works if funds are "Available" (not "Pending")

### Option 2: Check Test Mode First
1. Switch to Test mode
2. Make a test donation
3. Verify it appears in database and UI
4. This confirms the integration works
5. Live mode will work the same way (just with real money)

---

## Common Misconceptions

❌ **"Payment succeeded = money in bank immediately"**
- Payments go to Stripe balance first
- Then Stripe pays out on schedule
- Total time: 2-14 days depending on account age

❌ **"Test mode payments are real"**
- Test mode uses fake card numbers
- No real money moves
- Use live mode for real payments

❌ **"Stripe balance = bank balance"**
- These are separate
- Stripe holds funds temporarily
- Bank receives scheduled payouts

---

## Next Steps

1. **Check if you're in Live mode** (Step 1)
2. **Verify bank account is connected** (Step 4)
3. **Check payment succeeded** (Step 5)
4. **Check account status** (Step 6)
5. **Wait 7-14 days for first payout** (Step 7)

**If everything looks correct**: Just wait. This is normal for new Stripe accounts.

**If something is wrong**: Follow the specific step where you found an issue.

---

**Document Created**: 2025-10-18
**Your Payment Date**: 2025-10-18
**Expected Payout**: 2025-10-25 to 2025-11-01 (first time)
**Future Payouts**: 2 days after payment (after account is established)