Stripe Connect Troubleshooting
Every contractor on ContractShield gets paid through Stripe Connect. When something goes wrong with verification, payouts, or disputes, this is your first stop.
Onboarding failures
The four issues that block 90% of new contractors from completing Stripe verification.
KYC verification rejected
Cause
Stripe couldn't verify your business name, EIN, or beneficial owner identity against the documents you uploaded.
Fix
Open Account → Payouts in your dashboard, click Resume verification, and re-submit the exact legal name on your IRS EIN letter (or SSN for a sole prop). Make sure the address matches your business license.
Bank account couldn't be linked
Cause
Routing or account number mismatch, account is on hold at the bank, or the account name doesn't match the business name on your Stripe account.
Fix
Re-enter your routing/account number directly (not pasted). If the account is in your personal name but Stripe expects a business name, link a business checking account instead — most personal-name mismatches cause silent rejects.
Identity document upload failed
Cause
The image was too small (<200×200), too dark, or showed a non-government ID like a fishing license.
Fix
Use a flat, well-lit photo of your driver's license or passport, both sides if requested. JPG or PNG, at least 1024×768. Re-upload via Account → Payouts → Identity.
EIN verification stuck on pending
Cause
Stripe's IRS lookup can take 24–72 hours during peak filing periods. Common around April 15 and October 15.
Fix
Wait 3 business days. If still pending after that, email support@contractshield.io and we'll escalate with Stripe directly.
Verification needed
Stripe needs additional documentation to release this payout. Open Account → Payouts and complete the open requirements to resume.
Connect account
acct_••••••••
Pending balance
$2,500.00
Next payout
On hold
Held payouts
Why money you earned isn't in your bank account yet — and what to do about each case.
Pending — first $100 holdback
Why: Stripe holds the first $100 of every new account for 7 days as a fraud control. This is automatic and applies to every Connect account.
How to spot it: Your first invoice gets paid. Money sits in pending status for 7 days, then releases on the next normal payout schedule.
Action: Nothing to do — this is by design and resolves on its own.
Held pending verification
Why: Your KYC isn't complete OR Stripe needs additional documentation. Common after large transactions or if your address changed.
How to spot it: Status shows 'requirements.disabled_reason: requirements.past_due' in your Stripe dashboard.
Action: Open Account → Payouts and complete every checklist item. Payouts auto-resume within 24 hours of full verification.
Held during dispute review
Why: A client filed a chargeback or refund request. We hold the disputed amount in reserve until the dispute resolves.
How to spot it: You'll see a notification in /contractor/payments and an email from Stripe.
Action: Submit dispute evidence within 7 days via the link in the notification. If the dispute is won, the hold releases. If lost, the amount + a $15 chargeback fee are clawed back.
Auto-paused at 0.75% dispute rate
Why: ContractShield auto-pauses any contractor whose 30-day dispute rate exceeds 0.75% (3 disputes per 400 transactions). This protects the marketplace from systemic chargeback fraud.
How to spot it: You'll receive an email from us, and your /contractor/dashboard shows a 'Payouts paused — review required' banner.
Action: Reply to the email with context for each dispute. Once resolved with a clean 30-day rolling window, payouts resume automatically.
Refunds and disputes
ContractShield uses 100% contractor liability for refunds and chargebacks. Here's how the money moves.
Client requests refund
Client opens the project, clicks 'Request refund' on the relevant invoice, and submits a reason. You and they both get notified.
You have 7 days to respond
Approve, partially approve, or dispute the request from /contractor/payments. No response within 7 days = auto-approval.
Money flow on approval
Refund is debited from your next payout. If your next payout doesn't cover it, the balance is clawed back from your bank account on file. The 1% client platform fee is also refunded; the 1% contractor fee is NOT.
Money flow on dispute (chargeback)
If the client escalates to their bank, Stripe creates a formal dispute. You have 7 days to submit evidence (photos, time logs, signed work order). If you win, money returns. If you lose, you owe the disputed amount plus a $15 chargeback fee.
Win the dispute — submit this evidence
- Photos of work in progress and completion
- Signed work order or accepted quote
- Time tracking entries with dates and durations
- Receipts for materials charged through
- Chat logs with the client (auto-attached from /messages)
- Change-order approvals if scope changed
Still stuck?
Email support@contractshield.io with your Stripe account ID and a screenshot of the error. We can pull the full event log from Stripe and usually identify the exact blocker within an hour.
Last updated