Connecting Stripe

Stripe powers current V2 signed-estimate deposits, sent-invoice balance Checkout, optional exact-work prepayment from protected paid-invoice or Work offers, and eligible residential Suds Club signup. Once onboarding is complete, an accepted proposal with a required upfront payment, a sent invoice with a remaining ledger balance, an eligible exact-work rebooking whose organization has enabled the default-off offer, or a server-priced membership signup can open Stripe-hosted Checkout. Clean Estimate marks the payment settled, makes the repeat order fulfillment-ready, or activates the membership and releases its visits only after a verified Stripe event confirms settlement. Awaiting-payment, processing, resumable Checkout, and signup-pending states can exist earlier; the browser's return to CE Pro is navigation, not payment proof.

Current V2 includes secure invoice links, customer/PDF views, safe unpaid voiding, Stripe collection for the exact remaining invoice balance, governed admin office collection, and controlled refunds. Embedded keyed-card entry, tips, credits/write-offs, office-side saved-method selection/administration, and mobile invoice collection remain required parity in the V1 Payment Collection reference.

What Current V2 Supports

• Hosted checkout for the immutable option the customer accepted and signed
• A server-calculated 25% or 50% deposit based on the accepted option total
• Ledger-aware collection of only the remaining required deposit after any

settled deposit records, while refund evidence returns the customer to the office instead of automatically charging again

• Safe reuse of one compatible open checkout; any extra, wrong-amount, or

wrong-return sessions are expired before replacement

• Frozen connected-account ownership for the initial Checkout and every

monthly Suds Club schedule, invoice, refund, and cancellation, including after the provider reconnects a different Stripe account

• A scheduling payment gate that stays pending until Stripe confirms payment or,

for a non-membership deposit handled outside the portal, an active office user with both Manage invoices and Issue refunds marks it paid or waived

• Recorded proposal-payment totals on the signed proposal and payment history in the authenticated customer account
• Hosted Checkout for the exact remaining balance of a sent standalone invoice,

bound to the invoice, provider workspace, and connected Stripe account that created the registered payment session

• Hosted Checkout for the exact server-priced Suds Club signup amount shown on

an eligible residential completed-job Work card, with the membership pending until verified settlement and its invoice kept as a separate accounting target

• Separate proposal-deposit and invoice-payment accounting targets. An eligible

settled deposit is never relabeled as an invoice payment; it can reduce a source-linked invoice only as a separately labeled, auditable carried-forward credit.

• Admin collection of partial or split invoice payments across cash, check,

ACH/bank transfer, external processor, and card through hosted Stripe with registered provider payment state

• Controlled partial refunds bound to the original settled tender, with

durable pending, succeeded, or failed evidence and one coherent invoice, portal, client-history, totals, and earnings projection

The payment methods shown in hosted checkout depend on the connected Stripe account and transaction eligibility. Clean Estimate does not force every checkout to a fixed card-only or card-plus-ACH list.

Connect Stripe

1. Open Settings in the Business section of the V2 sidebar.
2. Find Payments (Stripe) near the top of the page.
3. Select Set up payments.
4. Complete Stripe's hosted onboarding and return to Clean Estimate.
5. Confirm the card says charges are enabled; it also reports whether payouts are enabled or pending.

If onboarding was started but not completed, select Resume Stripe onboarding. If the card says payments are not configured on this deployment, the deployment owner must finish the Stripe environment setup before an organization can connect.

Current V2 does not use a separate Integrations tab, Settings > Billing page, raw account-ID field, or secret-key form for this connection.

Upcoming: Stripe account readiness and hosted card settlement

The following connection changes are not active. Do not use this section as confirmation that a business can take live payments through the new account path.

When enabled, new business connections will require a full Stripe Dashboard account configured for Stripe to collect processing fees and handle negative-balance losses. Clean Estimate will collect its separately configured application fee; the amount is not set by this guide. The Payments (Stripe) card will show whether charges and payouts are enabled. Returning from Stripe's hosted onboarding will refresh the account status automatically.

Before a payment starts, the new account path will confirm that the connected account has the expected full-Dashboard responsibilities, merchant configuration, and active card payments. An older or incompatible connection will show a support message instead of silently charging through the wrong account. The new account-readiness path remains off; existing Stripe connections are unchanged. No live merchant readiness or hosted card settlement has been verified, and this documentation does not activate onboarding or payment collection.

Require a Deposit on an Estimate

1. Open the estimate in Estimates.
2. In the single-screen editor, choose 25% deposit or 50% deposit under the payment terms.
3. Save and send the estimate.
4. The customer chooses an option and signs the secure proposal before checkout becomes available.

If Stripe charges are not enabled, V2 drops a standard one-time deposit requirement when the proposal is sent and explains that Stripe must be connected. It does not send a customer into a checkout that cannot collect the deposit. An explicitly added monthly membership cannot use that fallback: sending remains blocked until Stripe is charge-ready because its signup payment must establish the recurring billing schedule.

Customer Payment Experience

1. The customer opens the secure proposal link delivered by email or text.
2. The customer compares the options, selects one, and signs the proposal.
3. If the accepted option requires an unpaid deposit, the same signed proposal offers Pay deposit securely or Pay securely for a full-payment requirement.
4. Stripe opens hosted checkout and returns the customer to the same signed proposal after success or cancellation.
5. Clean Estimate changes the payment state after the verified Stripe webhook arrives; delayed payment methods can remain pending until Stripe sends their final result.

The authenticated customer account can compare the current estimate options, review their included scope, choose one, sign, and start the required deposit Checkout without finding the original message. The original secure proposal link remains valid and uses the same one-acceptance and payment-ledger boundaries, so either surface converges on the same signed estimate and payment state. Before opening checkout, Clean Estimate revalidates the active customer session under the acceptance/estimate lock and derives the collectible amount from settled deposit records. A completed deposit cannot reopen merely because a workflow flag is late, and later maintenance installments are not mistaken for the original signup deposit.

Clean Estimate treats a provider-confirmed expired Checkout session as safe to replace. If Stripe still reports the session as open, complete, unknown, or cannot confirm its state, the original payment remains pending and the office must retry instead of creating another payable session.

The post-job Suds Club return follows the same provider-confirmed rule. A successful browser return can show Suds Club signup received while payment is pending; it does not activate the plan. Cancelling returns to the same protected Work offer. A retry targets the same accepted plan and reuses a compatible live session or replaces a provider-confirmed expired session, so closing Checkout or rotating the customer login session cannot create a second membership. Exact-work rebooking uses a separate, default-off customer-offer switch. When enabled, an eligible customer can explicitly choose pay later or prepay the frozen issued-invoice total. CE Pro shows prepay only while Stripe is configured, the connected account can accept charges, and that total is inside provider bounds. This post-job choice is independent from the invoice Pay offer sequence, and neither rebooking choice schedules an appointment. If Checkout is definitively unavailable before the first prepay acceptance, CE Pro discards the uncommitted browser command, refreshes server truth, and reopens the payment choices. No accepted server order or payment is changed; an accepted, open, or processing prepayment stays locked to its prepay continuation.

An applied exact-work prepayment can be refunded through the governed queue only while its linked job is Unscheduled, Scheduled, or In progress. CE Pro asks Stripe first. If the provider does not confirm the refund, the job remains active but blocked and the same durable command remains available for retry. An ambiguous or pending outcome reuses the same provider attempt and idempotency key. After an exact Stripe failed or canceled result, the next authorized retry advances that same command to a fresh durable provider-attempt key. After Stripe succeeds, CE Pro finalizes the local payment and cancels that exact job in the same transaction with its normal status audit. If a full refund completes outside CE Pro while its matching refund command is unresolved, retrying that command reconciles registered provider truth and cancels an eligible linked job in the same local transaction without another Stripe request. Without a matching unresolved command, Refund attention remains until the office reviews and cancels the linked job. A duplicate-payment refund never cancels the valid job, and Complete or Cancelled work cannot initiate the governed applied-payment refund. A provider-reported partial refund on the applied payment also returns active or not-yet-created repeat work to Refund attention with the remaining balance. CE Pro blocks materialization, scheduling, rescheduling, start, and completion until the refund is resolved, while still allowing scheduled work to be pulled back to Unscheduled for review.

A sent invoice can open its exact remaining ledger balance from the secure invoice link or the signed-in customer's Invoices page. Clean Estimate reuses or replaces only a session registered for that invoice and return surface, keeps the connected-account snapshot that created it, and shows paid only after the verified webhook settles the invoice ledger. An eligible estimate deposit appears separately as Deposit carried forward rather than being duplicated as an invoice payment.

Authorized admins can also collect a partial or split invoice balance from the office. Cash, check, ACH/bank transfer, and external-processor tenders are recorded against the exact invoice; card collection opens hosted Stripe on the connected account and settles only from its registered provider payment rather than exposing raw card details to Clean Estimate. Customer Checkout and office collection share the same invoice lock and ledger balance, preventing overcollection when two surfaces act at once.

Every office Collect or hosted-Checkout request locks and revalidates that the actor is still active with both manage_invoices and issue_refunds and still has all-office or same-office access to the invoice. A stale page cannot collect after either grant is removed or the actor is reassigned first. Raw payment, refund-command, and delivery-outcome writes are blocked; the controlled services own those state transitions.

Choosing card in Collect payment creates or reuses only the exact registered Checkout for that workspace, connected account, invoice balance, and return surface. The panel shows Open secure card checkout plus a copy link. The staff-device action may return to the authenticated office invoice; the copied link uses a customer-safe public invoice/confirmation return and never sends a customer to admin sign-in. Neither action marks the invoice paid; only the verified connected-account webhook settles the ledger. A different account, amount, invoice, or return surface cannot reuse that session.

Refunds begin from the exact settled tender. Stripe-backed refunds retain the connected-account snapshot and provider payment that collected the money; offline/external refunds remain attached to their original collection. Pending, succeeded, and failed attempts remain auditable, and every invoice/payment surface derives its net amount from those same immutable ledger rows. The first zero-balance transition emits one invoice.paid event; retries, refunds, and a later recollection do not emit that first-paid event again.

Provider refund recovery is service-only. It resumes a pending command only after matching the exact organization, invoice, payment, command, actor, amount/reason/idempotency identity, connected account, and provider payment. It also revalidates the stored actor's current active permissions and office entitlement. An ordinary staff request cannot mark a pending command succeeded or attach the provider result to another invoice.

For an exact-work prepayment, if exact registered provider truth shows that the exact scoped payment is fully refunded while the matching command remains unresolved, recovery supersedes that command locally without making a second Stripe refund request; the original command remains auditable.

Freeform office payment references and notes remain private audit fields. The public bearer invoice, signed-in customer account, customer payment history, and PDF receive only the allowlisted payment method and customer-safe ledger facts, never that staff-entered text or a raw Stripe payload.

Customers cannot self-report cash, check, Venmo, or another offline method. Those invoice tenders require the governed admin office workflow. For a non-membership estimate deposit handled outside the portal, an authorized office user with current all-office or same-office access can resolve the scheduling gate as paid or waived from Calendar. A monthly Suds Club signup cannot be marked received or waived—even before its plan row has been reconciled—because verified Stripe payment is what saves the payment method and creates its recurring billing schedule.

Current V2 Troubleshooting

Stripe onboarding is incomplete

• Open Settings and check Payments (Stripe).
• Select Resume Stripe onboarding when the account exists but charges are not enabled.
• Complete Stripe's requested identity and business details on the hosted page, then return to Clean Estimate.
• Wait for Stripe to enable charges before sending a proposal that must collect a deposit.

A confirmed payment does not appear right away

• Reopen or refresh the signed proposal payment section or the authenticated customer Payments history.
• Check whether Clean Estimate still shows the payment as Pending.
• Confirm the checkout succeeded in the connected Stripe Dashboard.
• For a delayed payment method, wait for Stripe's final event before expecting a paid state.

Clean Estimate trusts the verified provider result rather than the browser redirect, so returning from checkout alone does not mark a deposit paid.

The customer cannot start deposit checkout

• Confirm the proposal was accepted and signed and still has an unpaid payment requirement.
• Confirm Payments (Stripe) reports that charges are enabled.
• In the signed-in account, confirm the customer opened the current estimate

under Estimates, then refresh that estimate.

• On the public proposal, confirm the customer opened the current secure link

rather than an expired or withdrawn revision.

• Resend the current estimate from its office detail page only when the

customer is using the public-link flow and that link is no longer valid.

V1 Manual-Collection Reference

The following capabilities describe Clean Estimate V1 and are not yet available from the current V2 web or mobile UI:

• Embedded keyed-card entry and Refresh Card Entry after changing the amount or tip
• Hosted tip collection, credits/write-offs, and same-day provider void attempts
• Office-side saved-method selection/administration and expanded custom/manual tender administration; hosted customer saved-card setup and management are available in the signed-in portal
• Mobile job or invoice collection
• Multi-brand collection and brand-specific Stripe account routing

Current V2 invoice pages support governed admin partial/split cash, check, ACH, external, and hosted-Stripe collection plus controlled refunds. Customer invoice links support Stripe Checkout for the exact outstanding balance. Keep using the versioned V1 Payment Collection reference when supporting the V1 application's embedded card, tip, credit/write-off, same-day void, saved-method, brand-routing, and mobile workflows. Restoring those remaining controls on V2's safer payment services remains required parity.