Stripe Connect — onboarding, capabilities, and what to do when payments fail

Stripe Connect lets you accept card payments directly into your own Stripe account — Trimsy never touches the money. Connect once, and online deposits, in-person Terminal payments, and customer card-on-file all flow through.

Connecting

1. Settings → Payments → Stripe Connect → Connect Stripe Account.
2. Pop-up routes you to Stripe's onboarding flow.
3. Fill in:
   • Business type (sole trader, company, partnership)
   • Business address + ABN/ACN (Australia) or equivalent
   • Bank account for payouts (BSB + account number)
   • ID verification (driver's licence + selfie for sole traders; director ID for companies)
   • Tax residency confirmation
4. Submit. Stripe reviews — usually instant; sometimes a few hours for manual review.
5. Once approved, the panel shows Connected with your business name + payout-enabled status.

Capabilities

A connected account has individual capabilities you can see in the panel:

• card_payments — accept online card charges. Almost always approved.
• transfers — receive payouts to your bank. Approved together with card_payments in most regions.
• terminal — accept in-person card payments via a Stripe Terminal reader (BBPOS WisePOS, etc.). May require an extra application.

The Trimsy Settings → Payments panel shows two booleans:

• Charges enabled — can accept payments. If false, the customer's payment will fail.
• Payouts enabled — Stripe will release money to your bank. If false, money is collected but held by Stripe until the issue is resolved.

Why payouts get held

Stripe holds payouts when:

• Identity verification incomplete. Log into Stripe, fix the missing fields, and the hold lifts within a day.
• Risk review. A pattern of charges looked unusual to Stripe's automated system. Stripe will email you with what they need (typically a couple of customer invoices and an explanation of your business).
• Negative balance from a recent dispute. New incoming payments cover it before payouts resume.
• Bank account validation failed — they'll request a different bank account.

The panel shows the specific reason in red when there's a hold. Click through to Stripe's dashboard to resolve.

Disconnecting

Settings → Payments → Stripe Connect → Disconnect. Tokens are revoked. Existing pending charges still settle into your account; future charges fail until you reconnect or set up an alternative.

Don't disconnect if you have pending refunds or recurring subscription customers — disconnect after those are processed.

Troubleshooting common errors

"Charges enabled is false"

Stripe hasn't fully verified your account. Open Stripe Dashboard, find the red banner, complete the missing details. Usually it's a missing identity document or a tax residency confirmation.

"Card declined" on every payment

Test mode vs live mode mismatch. Make sure your .env has live keys (STRIPE_* keys starting with sk_live_ and pk_live_) and the Stripe Connect environment matches what's in Settings → Payments. Restart workers after env changes.

"Authentication required" → 3DS challenge fails

Customer's bank requires a 3D Secure challenge and it timed out. The booking creation flow holds the order in pending state for up to 30 minutes — ask the customer to retry through the same checkout link.

"Application requires a domain to be added"

Apple Pay / Google Pay need your domain registered with Stripe. Go to Stripe Dashboard → Apple Pay → Domain Verification, add your domain, upload the verification file. (Trimsy serves the file at .well-known/apple-developer-merchantid-domain-association automatically once configured.)

Test mode for QA

Use STRIPE_TEST_MODE=true in env to flip the SPA to test keys. Use Stripe's test cards (4242 4242 4242 4242 etc.) for end-to-end testing without real money. Set back to false before going live.

Disputes

When a customer disputes a charge, Stripe debits the disputed amount + a fee from your balance until resolved. The Trimsy bell shows the dispute. Open the linked invoice → Disputes tab → respond with evidence (signed receipt, intake form, email correspondence). Stripe reviews and either returns the money or sides with the customer.

Disputes count against your account health — keep them under 1% of charges. Three patterns predict trouble: vague service descriptions on receipts, no-show charges without consent, and aggressive refund policies. Document every transaction clearly.