tractatus/docs/STRIPE_PAYOUT_DIAGNOSTIC.md

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)