WYRE-AI QuickBooks Online Payment Management
Overview
Payments in QuickBooks Online record money received from customers. For MSPs, payments are typically applied against outstanding invoices for managed services, project work, or hardware. QBO supports multiple payment methods (check, credit card, ACH, cash), allows partial payments, handles overpayments as credits, and tracks deposits. Proper payment recording is essential for accurate accounts receivable and cash flow management.
Anti-triggers
- Actually taking the money — nothing here charges a card or moves
funds. These tools record that money arrived. Capture, ACH debit,
retries, and dunning belong to the payments platform; use
alternative-payments-paymentsor the Stripe plugin. - The books are in Xero, not QuickBooks — use
xero-payments. The concepts are near-identical, so only the vendor name disambiguates. - Money going out — vendor payments are accounts payable, a different
entity; use
qbo-expenses. - What is still outstanding — an aged-receivables view is a report,
not a payment query; use
qbo-reports. - The invoice being paid against — use
qbo-invoices.
Key Concepts
Payment Application
Payments can be applied in several ways:
| Application | Description | MSP Example |
|---|---|---|
| Full payment | Covers one invoice completely | Client pays monthly invoice |
| Partial payment | Covers part of an invoice | Client makes installment payment |
| Multi-invoice | Applied across multiple invoices | Client pays several open invoices at once |
| Unapplied | Payment recorded without linking to invoice | Advance payment or retainer |
| Overpayment | Excess amount after invoice(s) paid | Credit applied to future invoices |
Payment Methods
| Method | Description | Common MSP Usage |
|---|---|---|
| Check | Paper check | Traditional clients |
| Credit Card | Card payment | Online payment via QBO |
| ACH/EFT | Bank transfer | Recurring autopay clients |
| Cash | Cash payment | Rare for MSPs |
| Other | Catch-all category | Wire transfers |
Related Entities
| Entity | Description |
|---|---|
| Payment | Money received from a customer |
| CreditMemo | Credit issued to a customer (reduces balance) |
| RefundReceipt | Refund issued to a customer |
| Deposit | Bank deposit grouping multiple payments |
Core Fields
A Payment requires CustomerRef.value and TotalAmt. Invoice application happens through the Line array, where each line carries an Amount and a LinkedTxn entry of { TxnId: <invoice id>, TxnType: "Invoice" }. UnappliedAmt (Payment) and RemainingCredit (CreditMemo) are read-only and reflect what is still available to apply.
See references/fields.md for the complete Payment, Payment Line, CreditMemo, and metadata field reference.
API Patterns
Common Queries
-- All payments for a customer
SELECT * FROM Payment WHERE CustomerRef = '123' ORDERBY TxnDate DESC
-- Payments in a date range
SELECT * FROM Payment WHERE TxnDate >= '2026-01-01' AND TxnDate <= '2026-01-31'
-- Payments with unapplied amount
SELECT * FROM Payment WHERE UnappliedAmt > '0'
-- Recent payments
SELECT * FROM Payment ORDERBY TxnDate DESC MAXRESULTS 25
-- Credit memos with remaining credit
SELECT * FROM CreditMemo WHERE RemainingCredit > '0'
Write Operations
| Operation | Request |
|---|---|
| Record payment | POST /v3/company/{realmId}/payment with CustomerRef, TotalAmt, and a Line per invoice |
| Unapplied payment | Same POST, omit Line entirely — QBO holds the full amount as UnappliedAmt |
| Issue credit | POST /v3/company/{realmId}/creditmemo with SalesItemLineDetail lines |
| Void payment | POST /v3/company/{realmId}/payment?operation=void with Id + SyncToken |
See references/api.md for full request bodies (single-invoice, multi-invoice, unapplied, credit memo, void) and the endpoint catalog.
Common Workflows
Record Client Payment
Distribute a single received amount across the customer's open invoices oldest-first: fetch each invoice's Balance, apply min(remaining, balance) to that line, and drop any line that ends up at zero before posting.
Collections Review
Query Invoice WHERE DueDate < today AND Balance > '0' ORDERBY DueDate ASC, group by CustomerRef.value, and rank clients by total overdue balance.
Apply Unapplied Payments
Query payments with UnappliedAmt > '0' and open invoices for the same customer, then sparse-update each payment to append LinkedTxn lines against the oldest invoices.
Issue Service Credit
Create a CreditMemo with a service-credit item line for SLA breaches or downtime; the credit reduces the customer's balance and can be applied to future invoices.
See references/examples.md for working implementations of each workflow.
Error Handling
Common API Errors
| Code | Message | Resolution |
|---|---|---|
| 6000 | Business Validation | Check amounts, references, and required fields |
| 610 | Object Not Found | Verify CustomerRef, Invoice ID, or Payment ID |
| 5010 | Stale Object | Re-fetch SyncToken and retry |
| 6140 | Duplicate | Payment may already be recorded |
| 2050 | Invalid Reference | Check CustomerRef, PaymentMethodRef, or AccountRef |
Validation Errors
| Error | Cause | Fix |
|---|---|---|
| CustomerRef required | Missing customer | Add CustomerRef.value |
| TotalAmt required | Missing amount | Add TotalAmt |
| Amount exceeds balance | Payment > invoice balance | Reduce applied amount |
| Invalid LinkedTxn | Bad invoice ID | Verify invoice exists and has balance |
See references/examples.md for an error recovery wrapper that re-fetches an invoice balance when a payment amount exceeds it.
Best Practices
- Always link to invoices - Apply payments to specific invoices for accurate A/R; unlinked payments sit as
UnappliedAmtand quietly overstate open balances - Record reference numbers - Include check numbers, ACH refs, and transaction IDs
- Set deposit account - Specify
DepositToAccountRefto track cash in the correct bank account - Use payment methods - Create PaymentMethod records for consistent categorization
- Handle overpayments - QBO automatically creates unapplied amounts; apply to future invoices
- Void instead of delete - Voiding preserves the audit trail
- Apply oldest first - When paying multiple invoices, apply to oldest first
- Use credit memos for SLA credits - Issue credits for service disruptions rather than editing the original invoice
- Reconcile regularly - Match QBO payments to bank statements
- Track unapplied amounts - Regularly review and apply unapplied payments
Related Skills
- QBO Invoices - Invoice management
- QBO Customers - Customer balance tracking
- QBO Reports - A/R Aging and cash flow reports
- QBO API Patterns - API reference