End-to-end deposit walkthrough — ProMount by Vancomm entity. Follow phases 1–8 in order, check each box as you go.
Before you start — confirm all of these are live. The automated steps in Phases 4–6 will not fire unless every prerequisite is wired. None of these need re-checking between test runs; they are one-time setup items. The deployed bridge Worker is scoro-qbo-bridge.vancomm.workers.dev.
⚡ Run this first — green means ready. The prerequisites below can be auto-checked in one command:
doppler run -p vancomm -c dev_vancomm -- node scripts/qbo-launch-preflight.mjs
It reports PASS / FAIL / MANUAL for each prerequisite. It is read-only — it checks state and creates nothing. The list below is the reference for what each item checks and how to fix it if the preflight flags something.
cd workers/scoro-qbo-bridge
echo -n '<verifier-token>' | doppler run -p vancomm -c dev_vancomm -- npx wrangler secret put QBO_WEBHOOK_VERIFIER_TOKEN
P-5 QBO refresh token valid in Worker KV (scoro-qbo-kv). If auth errors, mint a fresh refresh token and push it to the Worker. Recommended path — Intuit's OAuth 2.0 Playground (browser, no local setup):
Select the com.intuit.quickbooks.accounting scope.
Authorize the Mhondoro Capital Partners, LLC company.
Copy the resulting Refresh Token, then set it on the Worker:
cd workers/scoro-qbo-bridge
echo -n '<refresh-token>' | doppler run -p vancomm -c dev_vancomm -- npx wrangler secret put QBO_REFRESH_TOKEN
Note: Tailscale is not needed for the Worker — it only ever mattered for the old local-callback OAuth script.
Alternative (local script): if you prefer running the local OAuth flow on your own machine, tailscale funnel 8742 then doppler run -p vancomm -c dev_vancomm -- node scripts/qbo-oauth.mjs, and push the resulting token with the same wrangler secret put QBO_REFRESH_TOKEN command above.
P-7 QBO Connector: Receipts = To Scoro direction is ON — same Integrations page.
P-8 Custom field c_qbo_invoice_link (field_id 27) — "Can add text in HTML format" MUST be ON. Check at Scoro → Settings → Custom fields.
P-9 PDF templates carry the pay-link — Quote 48, Invoice 49, Prepayment 51 each contain [a]c_qbo_invoice_link[/a] in the Payment Instructions block. Check at Scoro → Settings → PDF templates.
P-10 QBO "Customer Deposit" service item = Id 4 maps to the "Customer Deposits" liability account = Id 15 in QuickBooks Online.
Pay-online link in customer e-mails — the e-mail body that carries the link is configured at Scoro → Settings → Email. Copy-paste templates live in the e-mail kit.
Test amounts: keep totals small ($5–$10). Real money flows through QBO Payments. Small amounts limit exposure during validation. Deposit formula: deposit = quote sum × prepayment_percent (e.g. $1.00 × 50% = $0.50).
DoIn Scoro (ProMount by Vancomm), create a new Project at vancomm.scoro.com/projects/ with a clearly test-flagged name — e.g., WALKTHROUGH TEST [date]. Leave status at default; assign yourself as manager if required.
ExpectProject is saved, appears in the Projects list with a numeric project ID. Note the ID — you will link the quote here.
Verify
Project record exists with a numeric ID
URL contains promount (not julieh)
Example: the test project created in the promount entity. The project ID appears in the URL and in the record header. Live fixture: Project 3031.
DoCreate a new Company and a linked Person at vancomm.scoro.com/companies/ with a clearly test-flagged name — e.g., WALKTEST CUSTOMER LLC [date]. Use a real email address you can receive at — QBO will email the deposit invoice to this address when payment is enabled.
ExpectBoth contacts are saved. The company gets a numeric contact ID. Note it — the Worker needs it for the QBO customer mapping (Prerequisite P-11).
Verify
Company record exists with a contact ID
Person record is linked to the company
Email address on the company or person is reachable
Example: the test customer company in Scoro. The contact ID appears in the URL bar. Live fixture: Company 565.
DoFrom inside the Project, create a new Quote (Quotes) linked to the Customer from Phase 2. Add at least one line item (use any V2_Raw Materials product or a test product). Keep the total small ($5–$10). Optionally set a quote-level discount — open the Discount field, type a value (e.g., 5 for 5%), Tab out — the discount line appears on the PDF automatically. Quote PDFs use template 48 (carries the pay-link token).
ExpectQuote is saved with a quote number and a total. Note the total — it is the reference for the deposit calculation.
Verify
Quote exists with a quote number and total
Quote is linked to the correct Project and Customer
Quote PDF renders correctly (check via the PDF preview action)
Example: quote PDF with a 5% discount applied. Total $0.95 — the deposit will be 50% of this amount. Live fixture: Quote 3290.
4
Create Prepayment (Deposit Invoice)
manual create it in Scoro UI · auto Worker mints QBO invoice + writes pay-link back
4a. Create the prepayment in Scoro UI
DoFrom the Quote (or linked Order), navigate to Invoices and select New prepayment invoice. Set the advance percentage to 50%. Save.
Note: Prepayment invoices cannot be created via the API — this UI step is the only way to mint one. The Worker reads and modifies existing prepayments via REST (invoices/prepayments/view / invoices/prepayments/modify) but does not create them.
ExpectA prepayment record is created: its own invoice number, sum = full order amount, prepayment_percent = 50, status: unpaid. The c_qbo_invoice_link field is empty at this point.
Creates a QBO invoice for the deposit amount — Customer Deposit item (Id 4) → Customer Deposits liability account (Id 15), with online payment enabled
Fetches the Intuit InvoiceLink (hosted pay page URL)
Writes <a href="[pay URL]">Pay online</a> into c_qbo_invoice_link (field_id 27) on the Scoro prepayment
Caveat A — wait before sending the PDF. The pay-link is populated by the Worker after the QBO sync. If you open or send the prepayment PDF immediately, c_qbo_invoice_link may still be empty. Refresh the Scoro prepayment record after ~60 seconds before sending.
Caveat B — confirm the link renders as clickable, not as literal HTML. The custom field c_qbo_invoice_link (field_id 27) must have "Can add text in HTML format" = ON — check at Settings → Custom fields (Prerequisite P-8). If that flag is off, the PDF shows <a href=...> as text instead of a link. Prepayment PDFs use template 51.
Verify
Scoro prepayment: note its numeric ID
Scoro prepayment record: c_qbo_invoice_link field shows a value (not empty)
Prepayment PDF: Payment Instructions block shows Pay online as a live hyperlink — not raw markup
QBO: a new invoice under the test customer, amount = 50% of order total, online payment enabled
Prepayment record after Worker runs — the "Pay online" pay-link is populated in the custom field.The deposit-invoice PDF — "Pay online" renders as a clickable hyperlink in the Payment Instructions block. Live fixture: Prepayment 128.
5
Customer Pays the Deposit
manual pay via link or direct in QBO · auto Worker marks Scoro prepayment paid
5a. Pay the deposit
DoClick the Pay online link from the prepayment PDF and complete payment. Alternatively for testing without a real card: open the deposit invoice in QuickBooks Online → Receive payment → enter the deposit amount → save.
ExpectQBO records the payment; deposit invoice shows Paid / $0.00 balance.
Verify (QBO)
Deposit invoice for the test customer: status Paid, $0.00 balance
A QBO payment record exists for the deposit amount
The Intuit-hosted invoice page after payment — balance $0.00, status Paid. Payee: Mhondoro Capital Partners, LLC.
5b. Worker reconciles back to Scoro (~30–60 seconds)
Worker verifies Intuit HMAC signature using QBO_WEBHOOK_VERIFIER_TOKEN
Worker fetches the QBO payment record, resolves the linked QBO invoice ID
Worker looks up qbomap:qbo_invoice:{id} in KV → resolves to Scoro prepayment ID
Worker posts a receipt to Scoro (receipts/modify with prepayment_id set) → Scoro prepayment flips to paid/reconciled
Verify (Scoro)
Prepayment record: status paid / reconciled (no longer shown as outstanding)
A receipt for the deposit amount is linked to the prepayment
6
Complete the Order — Final Invoice
manual advance order status · auto Worker creates balance invoice + pay-link
6a. Advance the order to "Ready to Invoice"
DoIn Scoro, find the Order linked to your Quote. Advance its status to the stage that triggers billing — the label may be "Ready to Invoice," "Completed," or a configured pipeline stage. Use whichever stage is wired to the trigger from Prerequisite P-3.
ExpectOrder status updates. Worker Path C begins.
Verify
Order shows the correct "Ready to Invoice" (or equivalent) status
6b. Worker creates the final invoice + applies deposit credit (~30–60 seconds)
Applies the deposit credit — balance = order total − depositPaid
Creates a QBO balance invoice for the remaining balance (online payment enabled)
Fetches the QBO InvoiceLink and writes it to c_qbo_invoice_link on the Scoro final invoice
Verify (Scoro)
Final invoice exists — note its ID
Invoice total = order total; deposit amount already credited; balance due = order total − deposit
c_qbo_invoice_link is populated; final invoice PDF (template 49) shows a clickable Pay online link (same Caveats A & B as Phase 4)
Final invoice after Worker Path C — the deposit paid in Phase 4–5 is credited, and only the balance remains due. Live fixture: Final invoice 2348.
Verify (QBO)
A second QBO invoice exists for the test customer — amount = balance due
This balance invoice shows online payment enabled
7
Pay the Balance Invoice
manual pay via link or QBO direct · auto Worker or native connector marks Scoro invoice paid
DoClick the Pay online link from the final invoice PDF (or from the c_qbo_invoice_link field) and pay the remaining balance. Alternatively, record the payment directly in QBO against the balance invoice.
ExpectQBO records the balance payment. The Worker (Path B, same as Phase 5b) receives the QBO payment webhook and posts a receipt back to Scoro against the final invoice, marking it paid in full. The native connector's Receipts = To Scoro (P-7) may also close it — either mechanism works; idempotency keys prevent double-credits.
Verify (QBO)
QBO balance invoice: status Paid, $0.00 balance
A QBO payment record exists for the balance amount
Verify (Scoro)
Final invoice status: Paid in full (paid_sum = invoice total; unpaid balance = $0)
A receipt for the balance amount is linked to the final invoice
8
Final Reconciliation Checks
manualRun after both payments are recorded
Scoro (ProMount by Vancomm entity)
Prepayment invoice — status: paid / reconciled; receipt amount = deposit (50% of order total)
Final invoice — status: paid in full; paid_sum = order total; unpaid balance = $0
No outstanding AR on the test customer — both documents cleared
Both invoice PDFs show the Pay online link as a rendered hyperlink (not raw HTML)
c_qbo_invoice_link is populated on both the prepayment and the final invoice
prepayment_percent incorrect on the Scoro prepayment
Open the prepayment — confirm advance percentage is 50 (not 100). If reset, the invoices/prepayments/modify call may have omitted prepayment_percent — check Worker Path A code
Final invoice pay-link blank (Phase 6)
Worker Path C failed to get the QBO InvoiceLink
Check Worker logs for pathC; confirm QBO Payments is enabled; re-trigger via /process/order-complete/{orderId}
QBO balance invoice exists but Scoro invoice not marked paid (Phase 7)
qbomap KV entry for the balance invoice was not written by Path C
Check that Path C completed fully; confirm KV key qbomap:qbo_invoice:{balanceInvoiceId} exists
Duplicate receipts in Scoro
Both the native connector (P-7) and Worker Path B fired for the same payment
Not harmful — Scoro deduplicates by amount/date. If a double-credit occurs, void the duplicate receipt manually in Scoro UI
QBO refresh tokens expire after 100 days.
If the Worker returns token-related errors, re-run the OAuth flow: tailscale funnel 8742 && doppler run -- node scripts/qbo-oauth.mjs — the rotated token is persisted automatically in Worker KV on every successful API call.
Rollback
See deliverables/runbooks/qbo-e2e-quote-to-cash/README.md — the rollback section lists --delete script commands for all QBO artifacts. Scoro receipts have no API delete endpoint; void them manually in Scoro UI.
