Payment Collection

Current V2: other ways to pay on invoices

In V2, Settings > Payment collection (linked from the Settings hub) decides which ways your office can record an invoice payment collected outside Stripe. Cash, Check, ACH / bank transfer, and External card are always on. Under Other ways to pay, turn on any of Zelle, Venmo, Cash App, PayPal, or Financing, then click Save payment settings. A workspace that has never saved the page has Zelle and Financing on, the same as V1's default.

The list feeds the Collect payment panel on a sent invoice: the method dropdown shows the four built-ins plus whatever is turned on, and the panel has an optional reference and an optional note. The server checks the saved list again when the payment is recorded, so a panel opened before a method was turned off cannot record it. The method's name is kept with the payment and printed on the receipt as it read that day; turning a method off later never changes an old receipt.

Current V2: customer tip choices

The same page sets the three tip choices a customer sees when paying an invoice online, and the office sees when collecting a payment. Under Customer tip choices, each of the three is a Percentage of the taxable subtotal (the subtotal less any discount) or a Flat amount in dollars, then Save payment settings saves both sections together. No tip is always the fourth choice. The three must be different, a percentage runs from 1 to 100, and a flat amount from $0.01 to $10,000.00. A workspace that has never saved the page offers 10%, 15%, and 20%, the same as V1.

A tip is charged on top of the invoice amount and never counts toward the balance: the invoice shows paid the same whether or not the customer tipped, and the tip is kept with the payment, printed on the receipt as its own line, and shown in payment history. The server works the tip out from the saved choice on every new payment, so a page opened before the choices changed cannot charge a tip the workspace no longer offers; the payer is asked to pick again instead. Changing the choices does not touch tips already paid. Reports count tips as cash collected. The same saved choices are available when an office records a manual payment from an accepted lead; the office collect panel also has a Custom choice for an integer amount from $0.00 through $10,000.00, stored with the payment and checked on an exact replay. For a manual deposit, the configured percentage tip is calculated from the accepted option's frozen discounted pre-tax amount and is applied on top of the deposit principal without consuming the remaining balance. A manual refund amount means the total customer charge: it reduces remaining principal first, then remaining tip, and the payment is fully refunded only after both buckets are exhausted. Payment history net includes both buckets. A same-day void reverses the recorded tip with the principal.

Invoice refunds: Office refunds now reduce the remaining invoice principal first, then the payment's remaining tip. The invoice balance remains principal-only; see the invoice guide.

The office Deposit & Payments card uses the saved choices from the accepted proposal when recording an invoice or deposit payment. It also provides No tip and a Custom control for an office-entered amount from $0.00 through $10,000.00. The card shows the principal, tip, and total to record before the request is sent, and a retry keeps that exact choice and amount. When an older accepted proposal has no safe discounted pre-tax basis, percentage choices are omitted; saved flat choices, No tip, and Custom remain available.

Only members who can manage invoices can change the page. The sections below describe V1's mobile collection, which is unchanged.

V1 workflow: V1's mobile invoice collector and mobile saved-method selection and administration remain outside the current V2 mobile app; credits and write-offs also remain unbuilt. The web lead Deposit & Payments card now provides a true embedded Stripe card-entry form and supported web Stripe Terminal reader controls for an acceptance-bound deposit. Signed-in customers set up and manage hosted saved cards in the V2 portal, and an office teammate with Manage invoices can now view a client's saved cards (brand, last four digits, expiry, never a full card number) from the client profile's Payments tab; removing one needs Issue refunds as well. Current V2 supports Stripe-hosted payment of an immutable signed estimate's required deposit and a sent invoice's exact remaining balance, plus governed admin partial/split cash, check, ACH, external, and hosted-Stripe invoice collection with controlled refunds and same-day payment void. The office card choice opens Open secure card checkout or lets the admin copy that link; it is always a guest session for the invoice's exact balance, never bound to the client's saved cards, so holding the copied link never exposes or charges a saved card. Only the verified webhook records payment. The copied link returns to the public customer invoice/confirmation page rather than admin sign-in, and freeform staff references remain office-only. The broader V1 field/mobile workflow remains required parity.

If the office page is reloaded while an accepted card or reader attempt is reserved, pending, outcome-unknown, or failed but still payable at Stripe, the lead card offers Resume payment. It reuses the server-provided original request and idempotency key for the same PaymentIntent. When the original request cannot be recovered, the card holds the payment for reconciliation and does not start a new provider attempt. An unresolved provider result keeps the same action open until status is authoritative or the office cancels it.

Post-job customer-offer boundary: An eligible residential customer may open a server-priced Suds Club signup from the protected Work follow-up card when the organization enables that separate offer. It uses hosted Stripe Checkout and stays pending until verified settlement. Cancelling and retrying resumes the same plan. Exact-work rebooking has another independent, default-off control. A new request requires the customer to choose pay later or, when that control and the connected Stripe account are eligible, prepay the frozen issued-invoice total. Neither path schedules the work; the office still confirms it. These post-job flows are not mobile collection or the invoice Pay offer sequence. Commercial work still requests a custom maintenance proposal without accepting a plan or charging the customer.

In V1, use Settings > Payment Collection to control the choices your field team sees when collecting invoice payments in the mobile app. Settings are saved for the current workspace, so crews in another workspace keep their own choices.

Configure Tip Choices

The customer-facing tip screen (the V2 pay pages and V1's mobile collector) always contains exactly three configured choices plus No tip. The office collect panel has those same choices and Custom, which is an office-only override and does not change workspace settings. For each configured choice:

1. Select Percentage or Flat amount.
2. Enter the value.
3. Repeat for all three choices.
4. Click Save payment settings.

Percentage tips are calculated from the invoice's taxable amount. Flat tips add the exact configured dollar amount. No tip is always available and cannot be removed. The three paid choices must be unique and greater than zero.

Example configurations include 10% / 15% / 20%, or $10 / $20 / $30. Percentage and flat choices can also be mixed.

Configure Other Ways to Pay

The standard mobile payment choices remain Card, Cash, and Check. The separate Other choice opens only the alternate methods enabled here, such as Zelle, financing, ACH, bank transfer, Venmo, Cash App, or PayPal.

Select at least one alternate method before saving. A mobile collection records the selected method's name in payment history and on the receipt when one is sent.

How Changes Reach Mobile

Mobile users receive the saved workspace settings when they open an invoice or job payment screen. If a manager changes a choice while a crew member already has that screen open, the server refuses an outdated or altered selection. The crew member should reopen the payment screen and use the current choices.

Estimate payment behavior is global application behavior rather than a per-user display setting. Every estimate family uses the same Request, Card, Check, and Other workflow. Workspace configuration still controls permissions, enabled alternate methods, deposit rules, Stripe connection, and tenant-priced programs such as Suds Club.

Current V2 Deposit After Quote Approval

On the current V2 estimate approval flow, the customer signs the immutable selected option before Clean Estimate asks for a required deposit. A missing or pending deposit does not undo approval, but it keeps scheduling gated until Stripe confirms the payment or, for a non-membership deposit handled outside the portal, an active office user with both Manage invoices and Issue refunds resolves it as paid or waived. The service locks and rechecks that identity, both grants, and current all-office or same-office access during the update; a deactivation, permission removal, or office reassignment that commits first rejects the stale action without changing the deposit gate. A monthly Suds Club signup cannot use the office paid-or-waived override, even before plan reconciliation creates its database row, because its verified Stripe payment must create the recurring billing schedule.

The quote's validity deadline controls whether an unanswered quote can still be accepted. It does not cancel an approval already on file. An accepted quote continues to show its payment status and available deposit actions after that deadline.

When the signed quote contains a supported payment requirement, the customer can start Stripe-hosted checkout or leave the deposit pending and return later. Eligible payment methods come from Stripe and the connected account.

For a non-membership deposit, the Deposit & Payments card on the accepted lead lets an active office user with both money permissions record cash, check, ACH / bank transfer, or another enabled offline method. Each entry is bound to the exact accepted estimate, revision, option, and acceptance. The server locks the current principal balance and rejects stale amounts, changed lineage, disabled methods, or a changed tip choice before writing. A repeated request key returns the original payment without expiring a newer Checkout session or creating another ledger row. An online deposit session is expired only after a new manual intent passes these checks; if that provider expiry fails, the transaction rolls back rather than committing a manual payment alongside a live session. Monthly membership signup payments do not offer that override.

The same transition guard covers the newer direct Stripe PaymentIntent path. While a keyed-card or reader reservation is still reserved, provider-created, or outcome-unknown, manual payment, waiver, and replacement Checkout remain blocked even when the payment mirror row has not been written yet. A registered direct intent is cancelled only while Stripe reports a cancellable state, using the connected account saved with that payment. A settled, unknown, or provider-refused intent stays pending and the office must retry after the provider state is reconciled; a failed local row can still represent a confirmable PaymentIntent and is guarded the same way. Replacement Checkout admission performs that guard even when the failed direct row is the only payment projection or the reservation has no payment row yet. A still-valid pending Checkout is the one reusable exception and is returned without expiring it when the return boundary is unchanged.

The lead payment summary gives the selected accepted option's tipBaseCents and its tipOptions. tipBaseCents is the canonical discounted pre-tax amount from the frozen accepted option pricing snapshot, even when the option total includes tax. Each option has one of the fixed ids tip_1, tip_2, tip_3, or none, the saved-choice label, and the resulting tipCents. Invoice rows in the same summary expose the same fields from invoice subtotal minus discount. The selected option also exposes its canonical paymentStatus (pending, paid, or waived). If an older frozen snapshot cannot establish a truthful pre-tax basis, tipBaseCents is null, tipUnavailableReason explains why, and tipOptions keeps only configured flat choices plus none; percentage choices are rejected for that option rather than inferred from a tax-inclusive total. When the office records a payment, it sends the selected tipChoice and the displayed expectedTipCents. A Custom selection also sends customTipCents between 0 and 1,000,000 cents. An exact request-key replay checks the selected choice, custom amount when present, and displayed tip against the original persisted payment and returns the original row without recalculating it from later settings.

Commercial accepted options keep their frozen V2 gross pricing provenance when the lead summary derives a percentage-tip basis. The calculation removes the frozen tax components, applies the recorded portfolio discount ratio to the untaxed first-year amount, and adds the untaxed first-clean premium. It never re-prices an accepted option from current V1 settings. If an older snapshot is missing that provenance, percentage choices stay unavailable rather than using the tax-inclusive total as a pretax guess.

Deposit amounts come from the accepted quote snapshot. A residential estimate uses the standard 25% residential deposit, while Holiday Lights and selected proposal options use their saved percentage or fixed amount. If a commercial, fleet, generic, or Holiday Lights quote has no structured payment schedule, CE Pro approves the quote without inventing a deposit and leaves collection to the office.

During a rolling deployment, a workspace without a saved configuration safely uses 10% / 15% / 20% and Zelle, financing, ACH, and bank transfer until an owner or manager saves its preferred settings.

Who Can Manage These Settings

Owners and managers with Settings access can view and update payment collection settings. Sales representatives, crew leads, and technicians can read the non-sensitive choices in the mobile app, but cannot change the workspace configuration.

Next Steps

• Review Invoices and Payments for the current V2 standalone invoice workflow and its explicit V1 parity backlog.
• Connect Stripe before collecting card payments.