ReceivePayment · Add
simulated in sandboxReceivePaymentAdd
Received payments close out invoices. Each one is applied to one or more open invoices through AppliedToTxnAdd, or auto-applied oldest-first with IsAutoApply.
qbXML request
<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="13.0"?>
<QBXML>
<QBXMLMsgsRq onError="stopOnError">
<ReceivePaymentAddRq requestID="1">
<ReceivePaymentAdd>
<CustomerRef>
<FullName>Bayside Builders LLC</FullName>
</CustomerRef>
<TxnDate>2026-11-09</TxnDate>
<RefNumber>5521</RefNumber>
<TotalAmount>828.00</TotalAmount>
<PaymentMethodRef>
<FullName>Check</FullName>
</PaymentMethodRef>
<IsAutoApply>true</IsAutoApply>
</ReceivePaymentAdd>
</ReceivePaymentAddRq>
</QBXMLMsgsRq>
</QBXML>JSON equivalent
{
"txnDate": "2026-11-09",
"refNumber": "5521",
"customerRef": {
"fullName": "Bayside Builders LLC"
},
"isAutoApply": true,
"totalAmount": 828,
"paymentMethodRef": {
"fullName": "Check"
}
}curl -X POST https://ledgerwire.vibiz.app/v1/receive-payments \
-H "Authorization: Bearer $LEDGERWIRE_KEY" \
-H "Content-Type: application/json" \
-d '{"txnDate":"2026-11-09","refNumber":"5521","customerRef":{"fullName":"Bayside Builders LLC"},"isAutoApply":true,"totalAmount":828,"paymentMethodRef":{"fullName":"Check"}}'Run this request against your own sandbox
Add and Mod requests change data, so they run in a private sandbox, not the shared demo. Get a free key (10 seconds), then POST the request above to /v1/qbxml.
qbXML response (from the sandbox seed data)
<?xml version="1.0" ?>
<QBXML>
<QBXMLMsgsRs>
<ReceivePaymentAddRs requestID="1" statusCode="0" statusSeverity="Info" statusMessage="Status OK">
<ReceivePaymentRet>
<TxnID>2A3-1784071862</TxnID>
<TimeCreated>2026-07-14T23:31:02+00:00</TimeCreated>
<TimeModified>2026-07-14T23:31:02+00:00</TimeModified>
<EditSequence>1784071862</EditSequence>
<TxnNumber>3001</TxnNumber>
<CustomerRef>
<FullName>Bayside Builders LLC</FullName>
</CustomerRef>
<ARAccountRef>
<ListID>80000003-1760311862</ListID>
<FullName>Accounts Receivable</FullName>
</ARAccountRef>
<TxnDate>2026-11-09</TxnDate>
<RefNumber>5521</RefNumber>
<TotalAmount>828.00</TotalAmount>
<PaymentMethodRef>
<FullName>Check</FullName>
</PaymentMethodRef>
<DepositToAccountRef>
<ListID>80000004-1760311862</ListID>
<FullName>Undeposited Funds</FullName>
</DepositToAccountRef>
<IsAutoApply>true</IsAutoApply>
<UnusedPayment>0</UnusedPayment>
<UnusedCredits>0</UnusedCredits>
<AppliedToTxnRet>
<TxnID>101-1780875062</TxnID>
<TxnType>Invoice</TxnType>
<TxnDate>2026-06-07</TxnDate>
<RefNumber>1001</RefNumber>
<BalanceRemaining>0.00</BalanceRemaining>
<Amount>24.75</Amount>
</AppliedToTxnRet>
</ReceivePaymentRet>
</ReceivePaymentAddRs>
</QBXMLMsgsRs>
</QBXML>FAQ
What is required in ReceivePaymentAdd?
`customerRef`, `totalAmount` at minimum. Elements must appear in the order the qbXML schema lists them; LedgerWire orders them for you when you send JSON.
Why does ReceivePaymentAdd fail with status 3140?
3140 means a reference (for example CustomerRef or an ItemRef) points at something that does not exist in the company file. Look the record up first, or create it, and pass its ListID.
Can I set my own RefNumber on a received payment?
Yes. RefNumber is free text (up to 11 characters for most transactions). If you leave it out, QuickBooks auto-numbers when the preference is on.
Sandbox fidelity
The LedgerWire sandbox simulates ReceivePaymentAdd with QuickBooks rules: required fields, element names, refs that must exist (3140), unique names (3100), field lengths (3070) and EditSequence locking (3200). Tax calculation, custom fields and preferences are not simulated.
More ReceivePayment messages
Skip the XML: call POST /v1/receive-payments with JSON.
Get a free sandbox key