Card payments and surcharges

concorbit can collect card payments for invoices it owns and, when enabled, for invoices whose paid state lives in Autotask or QuickBooks. It can also add an optional card processing fee that the customer sees before they pay and that appears on the invoice they download.

This page covers paying an externally-governed invoice by card (reconciled through QuickBooks), and the card surcharge: how it is charged, where the customer sees it, and how it is booked back to QuickBooks as income.

Paying an externally-governed invoice by card

Most card payments are simple: a concorbit-governed invoice is paid through the portal pay-now button, the ledger records the settlement, and the invoice flips to paid. An externally-governed invoice is different. Autotask-governed and QuickBooks-governed invoices have their paid state owned upstream (see Governance), so concorbit must never mutate it directly. Collecting a card payment for one of these and then writing amount_paid would be overwritten by the next sync and could double-count.

When card pay is enabled for these invoices, the money still moves at Stripe, but the reconciliation runs through QuickBooks:

1. Stripe collects the payment from the customer.

2. concorbit records a non-mutating ledger row (status external_recorded, excluded from the settled total) and sets a lock on the invoice so a second charge cannot be taken while the round trip completes.

3. concorbit pushes the payment to QuickBooks against the linked QB invoice.

4. The native QuickBooks and Autotask integration marks the upstream invoice paid.

5. concorbit's sync reads the upstream paid state on the next pass, reconciles amount_paid, and clears the lock.

This keeps the upstream system as the single source of truth for paid state while still letting the customer pay by card.

When the pay-now button appears

For an externally-governed invoice the button is shown only when all of the following hold:

While a payment is mid-reconciliation the portal shows "Payment received, reconciling" rather than offering a second charge.

Refunds and disputes

Refunds and disputes on an externally-governed card payment are not actioned inside concorbit. The upstream system owns the money state, so:

• The in-app refund button is blocked for these invoices. Refund in QuickBooks or Autotask instead.

• A Stripe-side refund or dispute raises an operator repair notification rather than adjusting amount_paid.

For concorbit-governed invoices, refunds work as normal from the invoice screen. See Disputes.

Operator recovery

If a payment is collected but the QuickBooks push fails (no connection, an unresolved or mismatched QB invoice, or a QuickBooks error), the money has already moved, so the failure is surfaced as an operator notification and the invoice stays locked for manual reconciliation. The concorbit:billing-at-payment-repair command retries the push or clears a stuck lock with a full audit trail. See Operator runbook.

Card surcharge

A card surcharge is an optional processing fee added to a card payment so you can recover your card costs. It is configured per tenant and is off by default.

The surcharge is added to the Stripe charge only. It is never written into the invoice total. This matters for two reasons:

• An externally-governed invoice's total is owned upstream, so concorbit must not change it.

• A customer who pays the same invoice another way (bank transfer, cheque) is never charged the fee.

How it is calculated

The fee is a percentage of the invoice balance, rounded up to the nearest penny. You set the percentage and the line label on the Billing settings page. A £100 invoice with a 2% surcharge is charged as £102: £100 of base plus £2 of fee.

What the customer sees

• Before paying: the portal pay window shows a breakdown of the invoice amount, the fee, and the total to pay, so the charge is never a surprise.

• On the invoice they download: the printable and emailed PDF shows a card processing fee line and a "Total paid (incl. card fee)" figure. The invoice Total row stays at the base amount (the canonical accounting figure is unchanged); the fee is shown as an addition, so the document matches what the card was actually charged.

How it is recorded

The payment row stores the full amount Stripe collected (so it reconciles against Stripe) and the fee portion separately. The invoice settles on the base only, so amount_paid equals the invoice total rather than overshooting by the fee. A refund of a surcharged charge returns the gross cash and reconciles cleanly.

Booking the fee in QuickBooks

For an externally-governed invoice, the payment pushed to QuickBooks applies only the base against the QB invoice, so the invoice closes for the right amount. The surcharge is booked separately as a one-line QuickBooks sales receipt to a card-fee income item, so the fee lands as revenue in your accounts. Because concorbit only ever tells QuickBooks about the base on the payment and the fee on the sales receipt, the two documents partition the single Stripe charge with no double count, and both sit in Undeposited Funds for your normal bank-deposit reconciliation.

This requires you to map a QuickBooks card-fee item once. Until you do, the fee is still collected and recorded in concorbit and shown on the invoice, but it is not booked in QuickBooks, and an operator is nudged to set it. Map the item on the QuickBooks connection page; see QuickBooks sync. Choose a service or non-inventory item whose income account is where you track card fees.

For concorbit-governed invoices the surcharge is collected and shown the same way; there is no separate QuickBooks document because concorbit owns the invoice.

What is and is not surcharged

• Portal card payments are surcharged when the feature is on.

• Autopay and recurring card subscriptions are not surcharged. These are automatic off-session charges, not portal pay-now, and are deliberately left out.

• Payments by any other method (bank transfer, manual, cheque) are never surcharged, because the fee is added at the card charge, not to the invoice.