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.

Key Concepts

Payment Application

Payments can be applied in several ways:

Payment Methods

Related Entities

Field Reference

Payment Core Fields

Payment Line Fields (Invoice Application)

Credit Memo Core Fields

Metadata Fields

API Patterns

Query Payments

GET /v3/company/{realmId}/query?query=SELECT * FROM Payment WHERE CustomerRef = '123'&minorversion=73
Authorization: Bearer {access_token}
Accept: application/json

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'

Record Payment (Applied to Invoice)

POST /v3/company/{realmId}/payment?minorversion=73
Content-Type: application/json
Authorization: Bearer {access_token}

Single invoice payment:

{
  "CustomerRef": {
    "value": "123"
  },
  "TotalAmt": 2850.00,
  "TxnDate": "2026-02-15",
  "PaymentMethodRef": {
    "value": "2"
  },
  "PaymentRefNum": "CHK-10542",
  "DepositToAccountRef": {
    "value": "35"
  },
  "Line": [
    {
      "Amount": 2850.00,
      "LinkedTxn": [
        {
          "TxnId": "456",
          "TxnType": "Invoice"
        }
      ]
    }
  ],
  "PrivateNote": "February managed services payment - Acme Corp"
}

curl -s -X POST \
  -H "Authorization: Bearer $QBO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  "https://quickbooks.api.intuit.com/v3/company/$QBO_REALM_ID/payment?minorversion=73" \
  -d '{
    "CustomerRef": { "value": "123" },
    "TotalAmt": 2850.00,
    "PaymentRefNum": "CHK-10542",
    "Line": [{
      "Amount": 2850.00,
      "LinkedTxn": [{ "TxnId": "456", "TxnType": "Invoice" }]
    }]
  }'

Multi-invoice payment:

{
  "CustomerRef": {
    "value": "123"
  },
  "TotalAmt": 7500.00,
  "TxnDate": "2026-02-20",
  "PaymentMethodRef": {
    "value": "5"
  },
  "PaymentRefNum": "ACH-20260220",
  "Line": [
    {
      "Amount": 2500.00,
      "LinkedTxn": [{ "TxnId": "450", "TxnType": "Invoice" }]
    },
    {
      "Amount": 2500.00,
      "LinkedTxn": [{ "TxnId": "460", "TxnType": "Invoice" }]
    },
    {
      "Amount": 2500.00,
      "LinkedTxn": [{ "TxnId": "470", "TxnType": "Invoice" }]
    }
  ],
  "PrivateNote": "Bulk payment covering Dec, Jan, Feb invoices"
}

Unapplied payment (retainer/advance):

{
  "CustomerRef": {
    "value": "123"
  },
  "TotalAmt": 5000.00,
  "TxnDate": "2026-02-01",
  "PaymentMethodRef": {
    "value": "5"
  },
  "PaymentRefNum": "WIRE-20260201",
  "PrivateNote": "Advance retainer payment - project deposit"
}

Create Credit Memo

{
  "CustomerRef": {
    "value": "123"
  },
  "TxnDate": "2026-02-15",
  "Line": [
    {
      "Amount": 500.00,
      "Description": "Service credit - downtime incident on 2026-02-10",
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
        "ItemRef": { "value": "1" },
        "Qty": 1,
        "UnitPrice": 500.00
      }
    }
  ],
  "CustomerMemo": {
    "value": "Credit for service disruption on February 10, 2026."
  }
}

Void Payment

POST /v3/company/{realmId}/payment?operation=void&minorversion=73
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "Id": "789",
  "SyncToken": "1"
}

Get Payment Details

curl -s -H "Authorization: Bearer $QBO_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://quickbooks.api.intuit.com/v3/company/$QBO_REALM_ID/payment/789?minorversion=73"

Common Workflows

Record Client Payment

async function recordClientPayment(customerId, amount, invoiceIds, metadata) {
  const lines = invoiceIds.map(invoiceId => {
    // Fetch invoice to determine amount to apply
    return {
      Amount: 0, // Will be calculated
      LinkedTxn: [{ TxnId: invoiceId, TxnType: 'Invoice' }]
    };
  });

  // Distribute payment across invoices (oldest first)
  let remaining = amount;
  for (const line of lines) {
    const invoice = await getInvoice(line.LinkedTxn[0].TxnId);
    const applyAmount = Math.min(remaining, invoice.Balance);
    line.Amount = applyAmount;
    remaining -= applyAmount;
    if (remaining <= 0) break;
  }

  return await createPayment({
    CustomerRef: { va