Connecting Stripe
Settings → Stripe Connect connects the account used to collect client payments. This is separate from Your Subscription, which pays for your Contractor Codex plan.
Two ways to connect
- New account: use the onboarding button to create a Stripe Connect Express account and complete Stripe's hosted business, identity, and payout setup.
- Existing account: choose Already have an account? Connect here to authorize an existing Stripe Standard account.
The account is not ready simply because an account ID exists. Check the Charges, Payouts, and Requirements Due indicators after onboarding. Use the verification/update controls if Stripe requests more information.
For an ordinary connected organization, client payments are processed using its configured Connect arrangement. A separate, restricted direct-platform-billing mode exists for eligible accounts; do not assume every organization uses the same payment route.
After a client accepts or pays
Quote acceptance follows that quote's billing mode: it may create an invoice to pay, a completion draft for you to finalize, or the first stage of a payment schedule. Acceptance is not proof of payment. Check the invoice's status and payment history before treating it as collected.
A Stripe payout to your bank is separate from the customer's payment. Timing, availability, reserves, settlement, and processing charges depend on your Stripe account and payment method. This app does not guarantee a two-day payout.
For Express accounts, Open Express Dashboard creates a hosted dashboard login link. Standard accounts keep their existing Stripe dashboard. Use Stripe's account controls for payout details.
Payment methods
Configure client payment options under Settings → Payments. Cards and Link are enabled by default; US bank-account payments are optional and must be enabled. Available methods still depend on your Stripe account, currency, and the invoice.
Do not use a real client payment as a test unless you intend to charge it. Test/sandbox credentials and live credentials are separate server configuration, not a toggle on the invoice form. Ask an administrator to confirm the environment before testing.
Fees are not taxes
The configured default application fee is 0.08% for Standard and 0.01% for Pro, separate from Stripe's own processing charges and the Contractor Codex subscription. On a $1,000 client payment, that is $0.80 on Standard or $0.10 on Pro. Check the current plan and account settings for the rate that applies to your business.
The application fee is part of the payment arrangement in Stripe, not a separate customer sales tax. Processing prices, refund treatment, and dispute fees depend on Stripe's current terms and account configuration; use your Stripe transaction details for actual amounts rather than a fixed example from this guide.
In Codex, categorize costs actually paid under Stripe Processing Fees or Platform Service Fees. These labels do not automatically create fee expenses for every payment. See Expense categories.
Codex income includes recorded platform payments. When the same money later arrives as a Stripe payout in your bank feed, categorize that movement as Transfer—not a second Income entry. The same caution applies to cash/check deposits already recorded through Record a payment.
Currency
Currency belongs to the quote/invoice as a whole, not to each individual quote line. The quote composer uses the organization's default currency and retains the currency of a loaded draft. All line items on that quote share it.
Changing a default is not a currency conversion. Confirm the currency before sending, especially when loading a saved quote or changing account settings. Stripe account/method support and conversion costs must be checked in Stripe.
Automatic tax
Automatic tax has three separate parts, shown in Invoice Defaults and Stripe Connect:
| Part | What it means |
|---|---|
| Saved invoice preference | Request automatic sales tax asks Stripe to calculate tax when supported new invoices are created. It does not register your business or change existing invoices/subscriptions. Save a preference change before it takes effect. |
| Stripe Tax setup | The app checks the liable billing account's Tax settings and active registrations. Configured for registered locations means setup is active and at least one active registration is present—not that every invoice must have tax. Setup incomplete, No active tax registrations, and Tax setup not verified tell you when more review is needed. |
| Tax actually collected | The dashboard and Codex report recorded invoice tax. This is not a percentage of all revenue, a forecast, or proof that money has been reserved or remitted. Demo payments may be seeded without tax. |
Checks are labeled Sandbox / test, Live, or Mode unverified. Sandbox setup does not establish production readiness. Provider checks are read-only; refresh the page after changing Stripe. If Stripe is unavailable or denies the check, the app does not assume tax is ready or disabled.
Manage tax setup for your business
The business owner can open Business Tax Setup from the Owner tax setup button in Stripe Connect or Invoice Defaults. It opens Stripe-hosted Tax settings and Tax registrations for that business's connected account—not an account chosen by a typed ID or whichever account happens to be open in another browser tab.
- Tax settings: review your head-office address and default product/service tax code. Mixed businesses should verify the appropriate item classifications; the default does not guarantee every item receives the right treatment.
- Tax registrations: record the locations where the business is registered to collect. Adding a registration in Stripe does not register your business with a government authority. Use your actual registration details; ask a qualified tax adviser if unsure.
- Saving: changes saved in these embedded forms update the connected account in Stripe. Completing setup does not enable Request automatic sales tax automatically; review and save that preference separately in Invoice Defaults. Refresh the setup page afterward to check readiness again.
The editor requires a direct sign-in as the business's active owner. Other administrators, customer preview, and impersonation sessions cannot open it. Stripe may require its own secure authentication popup. Use a regular supported browser and allow the popup; embedded desktop/mobile webviews are not supported by Stripe. Opening the page alone does not add a registration.
The embedded registration editor creates or ends registrations immediately. It cannot schedule future start/end dates or specify US state sales-tax elections. Those options require Stripe's dashboard or API; contact platform support when needed. See Stripe's component limitations.
For Express / Custom accounts, these embedded forms provide tax setup that the limited Express dashboard does not manage. A Standard owner can also use the connected account's full Stripe dashboard. For direct platform billing, no connected-account editor is opened: the platform owner reviews Tax settings and Registrations in the platform account's Stripe dashboard. If Stripe rejects access to the forms, contact platform support; do not configure a different account as a workaround.
When the portal setting is enabled, supported invoice creation paths request Stripe automatic tax. Review business/customer address and tax information, then check the resulting invoice. The app does not determine whether you are required to register, collect, or remit tax. Confirm those obligations with a qualified adviser.
Even with complete setup, tax may be zero for a customer's location outside your collecting regions, exempt customers/items, or another applicable tax treatment. The current invoice sender can also send without tax after Stripe rejects the customer's tax location; review the final invoice and any skipped-tax warning, and correct the customer's billing address before future invoices. Today's settings do not explain every historical invoice.
This preference does not file returns, remit tax or reserve cash. See Stripe Tax setup, zero-tax reasons, and Tax for platforms.
Customer sales tax, Stripe processing fees, platform service fees, and the Codex income-tax set-aside estimate are four different things.
Disconnecting or changing accounts
Read the confirmation on the Stripe settings page carefully:
- Standard: disconnect removes the portal's API connection; the Stripe account and its Stripe-side records remain.
- Express: Delete Express Account & Start Over attempts to delete the Express account. This is not merely unlinking OAuth, and is available only when the account can be safely removed. Accounts with processed client invoices require further handling.
Existing invoices remain associated with the account that created them. Connecting a different account does not migrate old invoices, payments, customers, or subscriptions automatically. Get support before changing an account with active billing.
Troubleshooting
- Onboarding expired: reopen the setup/update button for a fresh link.
- Charges disabled or requirements due: finish Stripe's requested verification; do not assume invoices can be collected yet.
- Payouts disabled: investigate the payout requirements even if charges are enabled.
- Webhook or connection failure: use the connection diagnostics and contact support. Invoice/payment status may need reconciliation.
- Refunds: review the original payment and the refund result. The app's refund path requests a proportional application-fee refund when applicable, but processing fees and settlement outcomes should be checked in Stripe.