Your BusinessThe Contractor Codex

Connecting Stripe

The Contractor Codex uses Stripe Connect to accept payments from your clients and pay you directly. The platform never touches your money — every dollar a client pays goes from their card or bank straight to your Stripe account, then to your bank.

Two ways to connect

When you finish org setup, you have two paths:

Option A: Stripe Express (default)

We create a new Stripe Connect Express account for you and walk you through Stripe's hosted onboarding. You give Stripe:

  • Your legal name + DOB (for identity verification)
  • Your business name + EIN (if applicable)
  • A bank account for payouts
  • A phone number for 2FA

Stripe Express handles the heavy lifting — dispute management, payout scheduling, tax reporting (1099-K when required), and compliance. You don't manage a Stripe dashboard; you manage everything from inside The Contractor Codex.

This is the right choice if you don't already have a Stripe account.

Option B: Connect your existing Stripe account (Standard)

If you already process payments through Stripe and want to keep using the same account, click "Connect existing Stripe" in Settings → Stripe. Stripe will walk you through OAuth — you sign in to your existing Stripe and grant access.

Use this if you already have customers, subscriptions, or analytics in Stripe that you want to keep in one place.

What happens when a client pays

Client clicks Pay-Now link
     │
     └──► Stripe-hosted checkout (card or ACH)
                │
                └──► Payment lands in YOUR Stripe account
                          │
                          └──► Stripe payout to your bank (rolling 2-day default)

The platform takes a 1% service fee on each successful transaction on the Standard plan (the Pro plan drops it to 0.2%) — this is in addition to Stripe's own processing fees (2.9% + $0.30 for cards in the US, lower for ACH). The service fee is collected by Stripe automatically via the application_fee_amount parameter, so you never see a separate bill from us for transaction fees. The $15/mo (or $150/yr) subscription covers everything else.

Payment methods enabled

By default, every invoice and pay link supports:

  • Credit + debit cards (Visa, Mastercard, Amex, Discover)
  • ACH bank transfer (US only; lower processing fee, longer settlement window)
  • Stripe Link (one-click checkout for repeat clients)

You can turn any of these off in Settings → Payments if you want to restrict your clients to one rail.

Onboarding incomplete warning

If you create your org but skip the Stripe step, you'll see a yellow banner on /admin reading "Finish your Stripe setup." Clients cannot pay you until Stripe onboarding is complete — quote acceptance still works, but no invoice can be generated.

Click the banner to resume onboarding wherever you left off. Stripe saves your progress on their side.

Stripe dashboard access

For Express accounts, the platform exposes a "View in Stripe" link on every invoice and refund. Click it to open the relevant Stripe Dashboard page directly. You'll be asked to sign in to Stripe with the email you used during onboarding.

For Standard accounts, you log in to Stripe normally — the OAuth connection lets the platform read invoices but doesn't replace your existing dashboard access.

Disconnecting Stripe

If you need to switch accounts or stop processing payments through the platform, go to Settings → Stripe and click "Disconnect." All historical invoice records stay in your portal; only new invoices will fail until you reconnect.

Troubleshooting

"Connect onboarding link expired" — Stripe's onboarding URLs expire after 5 minutes. Click "Resume Stripe setup" on the admin banner and you'll get a fresh link.

"chargesEnabled is false" — Stripe is still reviewing your account or needs more info. Open Settings → Stripe to see the specific requirement (usually missing tax ID or unverified bank).

"Webhook signature verification failed" — Indicates the STRIPE_WEBHOOK_SECRET env var doesn't match Stripe's webhook signing secret. This is platform-side, not on your end — contact support.

Payout schedule

By default, Stripe Express accounts use a rolling 2-day payout schedule — money settles to your bank 2 business days after the charge succeeds. Cards settle faster than ACH (ACH takes 3-5 business days due to bank rails).

You can change your payout schedule in your Stripe dashboard:

  • Daily — payouts every business day.
  • Weekly — payouts every Monday (or your chosen day).
  • Monthly — payouts on the first of each month.
  • Manual — you trigger payouts yourself from Stripe.

Manual mode is useful if you want to hold funds in Stripe and pay yourself in lump sums (e.g., for tax planning). The portal doesn't manage this — go to Stripe's dashboard to configure.

Multi-currency support

Stripe Connect supports 135+ currencies. Each line item on a quote has a currency field — default is USD. To send a quote in EUR, GBP, CAD, etc., set the currency on the line item.

Important caveats:

  • All line items on the same quote must use the same currency. The portal doesn't support mixing currencies on one quote.
  • Your Stripe account's default currency is set during Express onboarding (based on your country). Settling foreign-currency charges to a non-default account triggers Stripe's currency conversion at their rate (~1% spread).
  • Stripe Tax (if enabled) supports tax calculation in any of the 135 currencies — but rates are pulled from local tax authorities, so VAT for EU quotes will be calculated correctly while a US-dollar quote keeps US sales-tax behavior.

For most US-based contractors billing US clients, leave everything at USD. Multi-currency matters once you start billing internationally.

Stripe Tax integration

The Contractor Codex doesn't directly handle sales tax — Stripe does. To enable automatic tax calculation:

  1. Go to your Stripe dashboard → Tax.
  2. Enable Stripe Tax (Stripe will walk you through tax registrations per state/region you have nexus in).
  3. Stripe Tax sets automatic_tax: enabled on every Connect-created invoice.

When enabled, every invoice the portal creates includes line-item-level tax calculation based on:

  • Your business's nexus (where you collect tax).
  • The customer's billing address (where the tax applies).
  • The product type (Stripe has tax codes for SaaS, services, physical goods, etc.).

Configure your customer's tax exemption status (if any) in the client's profile — none, exempt, or reverse_charge.

For US contractors not registered for sales tax in any state, leave Stripe Tax off — invoices ship without tax. You're responsible for whatever tax obligations apply to your business; Stripe Tax just automates the calculation if you opt in.

The 1% application fee — how it actually works

On the Standard plan, every successful charge has a Stripe-imposed application fee (the Pro plan drops this to 0.2%):

  • You receive: charge amount − Stripe processing fee − 1% application fee.
  • The Contractor Codex receives: 1% application fee.
  • Stripe keeps: their standard processing fee (2.9% + $0.30 for US cards; lower for ACH).

For a $1,000 invoice paid by card:

  • Stripe processing fee: ~$29.30 (2.9% + $0.30)
  • Application fee: $10.00 (1%)
  • Net to your bank: $960.70

The fee is collected at the moment of charge via Stripe's application_fee_amount parameter. You never see a separate bill from us; everything happens inside Stripe.

ACH is cheaper:

  • ACH processing fee: $0.80 (0.8% capped at $5)
  • Application fee: $10.00 (1%)
  • Net: $989.20 on a $1,000 ACH payment.

Push ACH on larger invoices to save your clients (and yourself) on processing fees.

Refunds, application fees, and chargebacks

When you issue a refund:

  1. The original charge's amount goes back to the customer's card/bank.
  2. The Stripe processing fee on the original charge is not refunded (Stripe keeps it).
  3. The application fee is refunded proportionally — if you refund 50% of a charge, 50% of the application fee comes back.

When a chargeback (dispute) hits:

  1. Stripe pulls the disputed amount from your balance immediately.
  2. Stripe also charges a dispute fee (~$15) that's not refunded even if you win the dispute.
  3. The application fee on the disputed charge follows the dispute outcome — you win, it stays charged; you lose, it's reversed.

Connect account status — what each state means

In Settings → Stripe, the page shows your account's current state via these fields:

  • details_submitted — true once you've completed Stripe's onboarding form. Doesn't mean payments work yet.
  • charges_enabled — true once Stripe has verified your identity + business details and approved you to accept payments.
  • payouts_enabled — true once Stripe has verified your bank account and can send you money.
  • requirements_currently_due — list of fields Stripe needs you to provide right now. If non-empty, your account is paused.
  • requirements_eventually_due — fields Stripe will eventually want. Don't block, but worth filling in to prevent future pauses.

The portal surfaces these on the Stripe settings page so you can see why something's broken without leaving the portal.

Switching from Express to Standard (or vice versa)

To switch:

  1. Disconnect your current Stripe (in Settings → Stripe).
  2. Re-connect with the other path.

Important: disconnecting an Express account leaves the Stripe account itself untouched — Stripe doesn't delete it; you just lose the OAuth link. New invoices created after disconnection won't be associated with anything until you re-connect. Existing invoices stay in their pre-disconnect Stripe account.

If you Express-onboarded by mistake and want to use your Standard account instead, contact support — we'll help reconcile the historical records.

Test mode vs live mode

Stripe has separate test and live environments. The platform always uses live mode for production deployments. There's no in-portal test-mode toggle — if you want to test the flow without real money, ask a support contact for a sandbox setup.

This is intentional: a real-mode-by-default setup prevents accidentally charging real cards in what someone thought was a test.