Receiving payments and making bill payments can be more complex than other transactions, since it may be necessary to apply a payment to more than one transaction, to mix payments with credits or discounts, etc.The following table summarizes the functionality provided by the Desktop SDK:
| Request message type | Can apply payments? | Can apply credits? | Can apply discounts? |
|---|---|---|---|
| ReceivePayment (ReceivePaymentAddRq) | Y - can be applied to multiple transactions | Y – can be applied to multiple transactions ? in credit-only messages, the outcome may be linked transactions, and the response message may be “thin” | Y - can be applied to multiple transactions? |
BillPayment (BillPaymentCheckAdd, BillPaymentCreditCardAdd) |
Y - can be applied to multiple transactions | Y - can be applied to multiple transactions ? | Y - can be applied to multiple transactions? |
Notice than a singe message can combine payments, credits, and discounts.
For both payments received and bill payments, the SDK provides the option of distributing the payment among multiple transactions:
With payments received and bill payments, it is important to note the difference between creating a credit and setting a credit. For receive payments, credits are created when a customer returns some merchandise or overpays an invoice. For bill payments credits, are created when the business returns some merchandise to one of its vendors or overpays a bill.
Note that once a credit is applied, via a payment received or bill payment request, it cannot be modified, even though the Desktop SDK provides ReceivePaymentModRq and BillPaymentCheckModRq messages. This is because QuickBooks does not track which transactions consumed which credits. Therefore, once the credits are applied, there is no way of unapplying them other than deleting the transaction (if that is possible) and redoing the transaction with the desired credits. You can, however, apply additional credits.
Although the receive payment and bill payment messages are referred to as transactions, adding these objects to QuickBooks does not always result in a transaction. For example, when a credit is applied in a receive payment or bill payment object and no payment is involved, links are created between the credit memo and the invoice (or other receivable/payable transaction) but no new transactions are created. This case is covered in some of the examples further down this page
The query requests for invoice, credit memo, bill, and bill credit objects contain an IncludeLinkedTxns flag, which specifies whether to include information about these links in the response. If this flag is true, a LinkedTxn aggregate is returned for each linked transaction.
For example, if this flag is set to true in an InvoiceQueryRq, the response will include a list of all transactions linked to the invoice specified in the query. This list is similar to the History view of a transaction in the user interface, but not identical, as the SDK list contains only linked transactions, not items. By default, the IncludeLinkedTxns flag is false.
The response returned for a receive payment or bill payment object can include either a full version or a thin version of the AppliedToTxnRet response object. When a receive payment or bill payment is credit only it does not create a new transaction, but simply links a credit memo the existing bill transaction, a full AppliedToTxnRet object is not required, since no transaction was created. The thin version returned in these cases includes only:
To find out exactly what happened, you need to perform the appropriate query on the returned TxnID.
In QuickBooks, the main type of transactions that can receive payment are:
ReceivePaymentAdd objects can be added, queried, and deleted through the SDK.
When a ReceivePaymentAdd request includes an actual payment (as distinguished from a credit or a discount, the TotalAmount element should pass the total payment amount, and not include any credit or discount amounts that will be included in the request. (In requests that include only credits or discounts, there is no TotalAmount.) The TotalAmount can be applied to a single transaction or distributed as described below.
A receive payment request message can include one or more occurrences of the AppliedToTxnAdd aggregate, which allows you to specify how to distribute the TotalAmount for a customer job. Each occurrence will reference a different transaction, by transaction ID, and apply the specified PaymentAmount to that transaction.
The following table shows how the sum of the payment amounts relates to the TotalAmount specified. The sum of the PaymentAmount elements in all the AppliedToTxnAdd aggregates should be less than or equal to the TotalAmount (in the ReceivePaymentAdd object).
Relationship of Payment Amounts to TotalAmount
Result
payment amounts = TotalAmount
Entire received amount is distributed
payment amounts < TotalAmount
UnusedPayment amount is returned in the ReceiveAmountRet object and is available for a future payment transaction
payment amounts > TotalAmount
Error!
The IsAutoApply flag is used instead of AppliedToTxnAdd. This flag allows QuickBooks to apply the payment according to its set of rules, or simply to receive the payment without applying it to a specific transaction, as follows:
The following example shows a ReceivePaymentAddRq message that has noAppliedToTxnAdd and IsAutoApply is false. This request will result in a credit of $620.40 being available to the Smith:kitchen customer job account.
1 2 3 4 5 6 7 8 9 10 11 12 | <receivepaymentaddrq requestid="356088"> <receivepaymentadd> <customerref> <fullname>Smith:kitchen</fullname> </customerref> <araccountref> <fullname>Accounts Receivable</fullname> </araccountref> <totalamount>620.40</totalamount> <isautoapply>false</isautoapply> </receivepaymentadd> </receivepaymentaddrq> |
The ReceivePaymentAddRq provides several ways to set discounts:
You cannot set a discount if you auto-apply a payment to the same AppliedToTxnAdd aggregate.
You can set a credit (add credit to a customer job account) by including the SetCredit aggregate in an AppliedToTxnAdd aggregate. You cannot set a credit if you auto-apply the payment.
If you set one or more credits in a ReceivePaymentAddRq but do not distribute a payment or set a discount, then no transaction will be created. Setting a credit merely creates links between existing transactions (for example, between a credit memo transaction and an invoice transaction), and no information about these links will be returned to you in the ReceivePaymentRet response.
The AppliedToTxnRet aggregate included in the returned ReceivePaymentRet object will not refer directly to any credit that was set. If you want information about credits, you must do a query on the TxnID returned by AppliedToTxnRet. For example, if AppliedToTxnRet refers to an invoice with a particular TxnID, if you query that TxnID you can get information about credit memos that are linked to that transaction.
The following example is aa ReceivePaymentAddRq that sets a credit but does not include a PaymentAmount or DiscountAmount element. This ReceivePaymentAdd object will create a link between a credit memo and an invoice transaction, but will not create a new transaction.
The customer named Smith previously returned merchandise, and a credit memo was created for this account. A CreditMemoQueryRq query returned information about the amount and transaction ID of this credit memo (110.29 and 120-1012533559). In the following example the full amount from the credit memo is applied to the customer job Smith:kitchen, and a link is created to the invoice with the TxnID of 24-974954. The balance of that invoice will be reduced by $110.29, and closed altogether if the previous balance was $110.29.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | <receivepaymentaddrq requestid="356089"> <receivepaymentadd> <customerref> <fullname>Smith:kitchen</fullname> </customerref> <appliedtotxnadd> <txnid>24-974954<txnid> <setcredit> <credittxnid>120-1012533559</credittxnid> <appliedamount>110.29</appliedamount> </setcredit> </appliedtotxnadd> </receivepaymentadd> </receivepaymentaddrq> |
The next example is a ReceivePaymentAddRs object that could be returned from the preceding ReceivePaymentAddRq.The request object did not create a transaction, and the response is a thin AppliedToTxnRet aggregate:
1 2 3 4 5 6 7 8 9 10 | <receivepaymentaddrs> requestID="356089" statusCode="0" statusSeverity="Info" statusMessage="Status OK"> <receivepaymentret> <appliedtotxnret> <txnid>24-974954</txnid> <txntype>Invoice</txntype> <txndate>2002-02-10</txndate> </appliedtotxnret> </receivepaymentret> </receivepaymentaddrs> |
Getting a thin response such as this might prompt you to query the specified invoice further to learn about any linked transactions. For example, after receiving the response shown above, you might send an InvoiceQueryRq with TxnID of 24-974954 and IncludeLinkedTxns set to true. The query would return a LinkedTxn aggregate representing a credit memo with TxnID of 120-1012533559.
Note
Note
You can perform additional queries for links only if the affected transaction (the transaction returned in the AppliedToTxnRet) is an invoice. For example, if the TxnID 24-974954 had a TxnType of JournalEntry, it would not be possible to query the journal entry to find out about linked transactions because a JournalEntryQueryRq does not include an IncludeLinkedTxns flag.
The next example shows a ReceivePaymentAddRq that applies a payment, credit, and discount. The invoice with TxnID 43-222560 has a balance of $100.00, and a payment is received for $100.00. The invoice will be closed, but there will also be an unused payment, because both a credit (for $5.00) and a discount (for $7.00) are set. QuickBooks will reduce the internal payment amount to $88.00 [$100.00 - ($5.00 + $7.00)]. This example will produce an overpayment of $12.00, so UnusedPayment will be 12.00 in the returned ReceivePaymentRet object.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | <receivepaymentaddrq> <receivepaymentadd> . . . <totalamount>100.00</totalamount> <appliedtotxnadd> <txnid>43-222560</txnid> <paymentamount>100.00</paymentamount> <setcredit> <credittxnid>4552-22629</credittxnid> <appliedamount>5.00</appliedamount> </setcredit> <discountamount>7.00</discountamount> <discountaccountref> <fullname>discount</fullname> </discountaccountref> </appliedtotxnadd> </receivepaymentadd> </receivepaymentaddrq> |
If the company is subscribed to QBMS, you can record a ReceivePaymentAdd that is basically a pending transaction. That is, in this usage, you want to save a QBMS authorization transaction into QuickBooks. Thus, the ReceivePaymentAdd contains a CreditCardTxnInfo aggregate with a CreditCardTxnType of Authorization. QuickBooks saves this as a pending transaction.
Later, when the authorized charge is captured to become a real charge in QBMS, you can record that charge into QuickBooks by modifying that ReceivePayment (ReceivePaymentMod). The ReceivePaymentMod will have a CreditCardTxnInfoMod containing data from the QBMS capture transaction, with a CreditCardTxnType of Capture. QuickBooks automatically removes the pending status and records the transaction.
Beginning with qbXML specification 6.0 and QuickBooks 2007, you can modify a ReceivePayment transaction via the SDK. However, notice that you cannot modify applied credits, as explained above.
Beginning with qbXML spec 7.0 and QuickBooks 2008, you can modify a ReceivePayment transaction to add a CreditCardTxnInfo aggregate or modify an existing one if you want. The most common use of this feature is described under the topic “Using ReceivePayment for Credit Card Authorization and Capture.” However, you can make other modifications if you wish because the feature is not limited to an authorization/capture usage.
The Desktop SDK, supports bill payments by check or by credit card and the SDK provides different request message types for them: (The SDK does not currently support online banking.)
In addition, a bill payment request, like a receive payment request, can be used to set credits and discounts. The request type used should reflect the payment types used.
In the QuickBooks UI, the pay bills window shows all open bills from all vendors. The user can select multiple bills from multiple vendors and pay them, all at one time. In the SDK, applications can pay multiple bills in one bill payment request, but the bills must all be from the same vendor. In the SDK, the BillToPayQueryRq performs the same function.
A bill payment is always applied to a particular transaction. The payment amount can be less than, equal to, or greater than the amount due. In the case of an overpayment, a credit in the amount of the overpayment is created. This credit appears in the QuickBooks UI in the Credits window list.
To pay a bill using BillPaymentCheckAddRq or BillPaymentCreditCardAddRq, you must specify the transaction ID and a payment amount. If necessary, use the BillToPayQueryRq to obtain the transaction ID. This query returns a list of all open bills and all credits available. The following BillToPayQuery request for all bills and credits for Allison BMW as of August 16, 2002: (The corresponding response, with information on two bills and one credit is shown after the request,)
1 2 3 4 5 6 7 8 9 | <billtopayqueryrq requestid="123456"> <payeeentityref> <fullname>Allison BMW</fullname> </payeeentityref> <apaccountref> <fullname>Accounts Payable</fullname> </apaccountref> <duedate>2002-08-16</duedate> </billtopayqueryrq> |
The corresponding BillToPayQueryRs, with information on two bills and one credit:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | <billtopayqueryrs requestid="123456" statuscode="0" statusmessage="Status OK" statusseverity="Info"> <billtopayret> <billtopay> <txnid>101-1029260941</txnid> <txntype>Bill</txntype> <apaccountref> <listid>280000-1026788471</listid> <fullname>Accounts Payable</fullname> </apaccountref> <txndate>2002-07-26</txndate> <refnumber>0126</refnumber> <duedate>2002-08-16</duedate> <amountdue>152.00</amountdue> </billtopay> </billtopayret> <billtopayret> <billtopay> <txnid>FE-1029260914</txnid> <txntype>Bill</txntype> <apaccountref> <listid>280000-1026788471</listid> <fullname>Accounts Payable</fullname> </apaccountref> <txndate>2002-08-13</txndate> <refnumber>0125</refnumber> <duedate>2002-07-17</duedate> <amountdue>1250.00</amountdue> </billtopay> </billtopayret> <billtopayret> <credittoapply> <txnid>104-1029260962</txnid> <txntype>VendorCredit</txntype> <apaccountref> <listid>280000-1026788471</listid> <fullname>Accounts Payable</fullname> </apaccountref> <txndate>2002-08-13</txndate> <refnumber>0300</refnumber> <creditremaining>125.00</creditremaining> </credittoapply> </billtopayret> </billtopayqueryrs>undefinedundefined |
If the BillPayment*AddRq applies only a credit amount (and no payment), QuickBooks creates a link between the bill and the credit transaction, but does not create a transaction. The return object in this case will contain the thin version of the AppliedToTxnRet.
You can discount only bills in the BillTxnList. (An attempt to set a discount on other types of objects results in an error.) If you discount a bill without paying it, only a general journal entry is created (but no BillPaymentCreditCardRet or BillPaymentCheckRet transaction). The return object in this case is a thin AppliedToTxnRet object.
If you apply both a credit and a discount amount (but no payment), the combined total cannot exceed the total amount due of the bill.
The following example shows the AppliedToTxnAdd aggregate from a payment add request that combines a payment, a credit, and a discount to close a bill. The amount due on Bill 1 (B1) is $100. The request applies an $80 payment, a $10 credit, and a $10 discount to the bill.
1 2 3 4 5 6 7 8 9 10 11 12 | <appliedtotxnadd> <txnid>B1</txnid> <paymentamount>80.00</paymentamount> <setcredit> <credittxnid>C1</credittxnid> <appliedamount>10.00</appliedamount> </setcredit> <discountamount>10.00</discountamount> <discountaccountref> <fullname>D1</fullname> </discountaccountref> </appliedtotxnadd> |
The result is that QuickBooks pays the bill and closes it, because the sum of payments, credits, and discounts is exactly equal to the amount of the bill.
In the next example, the amount due on Bill 1 (B1) is still $100. The payment request includes a payment of $80, a credit of $20 from C1, and a discount of $10. The total payment for Bill 1 is $110, so QuickBooks creates a $10 credit as a result of this overpayment.
1 2 3 4 5 6 7 8 9 10 11 12 | <appliedtotxnadd> <txnid>B1</txnid> <paymentamount>80.00</paymentamount> <setcredit> <credittxnid>C1</credittxnid> <appliedamount>20.00</appliedamount> </setcredit> <discountamount>10.00</discountamount> <discountaccountref> <fullname>D1</fullname> </discountaccountref> </appliedtotxnadd> |
In the next example, the amount due on Bill 1 (B1) is still $100. The payment request includes a payment of $50, a credit of $60, and a discount of $45. The total payment is $110, but it results in an error, because the combined credits and discounts applied to a bill cannot exceed the amount due of the bill:
1 2 3 4 5 6 7 8 9 10 11 12 | <appliedtotxnadd> <txnid>B1</txnid> <paymentamount>50.00</paymentamount> <setcredit> <credittxnid>C1</credittxnid> <appliedamount>60.00</appliedamount> </setcredit> <discountamount>45.00</discountamount> <discountaccountref> <fullname>”GoodCustomerDiscount”</fullname> </discountaccountref> </appliedtotxnadd> |
In the next example the request pays two bills. To Bill 1, which has an amount due of $100, it applies the following:
To Bill 2, which has an amount due of $50 it applies the following
No payment is applied to Bill 2. Note that one credit, C1, is applied to multiple bills.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | <billpaymentcheckaddrq> <appliedtotxnadd> <txnid>B1</txnid> <paymentamount>80.00</paymentamount> <setcredit> <credittxnid>C1</credittxnid> <appliedamount>10.00</appliedamount> </setcredit> <discountamount>10.00</discountamount> <discountaccountref> <fullname>D1</fullname> </discountaccountref> </appliedtotxnadd> <appliedtotxnadd> <txnid>B2</txnid> <setcredit> <credittxnid>JulyRebate</credittxnid> </setcredit> </appliedtotxnadd> </billpaymentcheckaddrq> |
The response message will include two AppliedToTxnRet objects—one for Bill 1 and one for Bill 2. The AppliedToTxnRet for Bill 1 will be the full AppliedToTxnRet. The AppliedToTxnRet for Bill 2 will be the thin version since no payment was made for Bill 2. To find out more about Bill 2, you could perform additional queries for links using the IncludeLinkedTxns flag.
Beginning with qbXML specification 6.0 and QuickBooks 2007, you can modify BillPaymentCheck transactions via the SDK. However, you cannot modify any credit that was applied to a bill, either via the QuickBooks UI or a BillPaymentCheckMod request.
A deposit is used to move funds from the Undeposited Funds account to an asset account or from one asset account to another A deposit contains the following information:
You can specify the transfer of deposited funds explicitly to a given account, or you can specify it using the PaymentTxnID and PaymentTxnLineID elements contained in the DepositAdd request, as shown by the following examples.
The first example shows a straightforward DepositAdd request. A total deposit, in the amount of $50, is taken from customer1’s savings account. A cash back payment ($12)
Adding a deposit to the specified account
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | <depositaddrq requestid="SDK deposit 3"> <depositadd> <deposittoaccountref> <fullname>checking</fullname> </deposittoaccountref> <memo>SDK deposit 3</memo> <cashbackinfo> <accountref> <fullname>cash</fullname> </accountref> <memo>SDK cash back</memo> <amount>12.00</amount> </cashbackinfo> <depositlineadd> <entityref> <fullname>customer1</fullname> </entityref> <accountref> <fullname>savings</fullname> </accountref> <paymentmethodref> <fullname>cash</fullname> </paymentmethodref> <amount>50.00</amount> </depositlineadd> </depositadd> </depositaddrq> |
The next example shows a simple request that issues the helper query ReceivePaymentToDeposit.
1 2 3 4 | <qbxmlmsgsrq onerror="continueOnError"> <receivepaymenttodepositqueryrq> </receivepaymenttodepositqueryrq> </qbxmlmsgsrq> |
The next example shows response to the preceding ReceivePaymentToDeposit query. This response shows that Kristy Abercrombie has paid $200.00 against an invoice, and lists the TxnID and TxnLineID that the funds are being applied to. The payment received from Kristy Abercrombie was already included on the original invoice in the form of a payment line item.
1 2 3 4 5 6 7 8 9 10 11 12 13 | <receivepaymenttodepositqueryrs statuscode="0" statusmessage="Status OK" statusseverity="Info"> <receivepaymenttodepositret> <txnid>48ED-1071532336</txnid> <txnlineid>48F1-1071532336</txnlineid> <txntype>Invoice</txntype> <customerref> <listid>170000-933272658</listid> <fullname>Abercrombie, Kristy:Kitchen</fullname> </customerref> <txndate>2003-12-15</txndate> <amount>200.00</amount> </receivepaymenttodepositret> </receivepaymenttodepositqueryrs> |
The next example shows a DepositAdd request, which feeds the TxnID and TxnLineID obtained in Listing 16-13 into a deposit. The funds are desposited to the account referred to by the DepositToAccountRef element in the DepositAdd request—namely, the checking account.
1 2 3 4 5 6 7 8 9 10 11 12 | <depositaddrq requestid="101"> <depositadd> <deposittoaccountref> <fullname>checking</fullname> </deposittoaccountref> <memo>SDK deposit 3</memo> <depositlineadd> <paymenttxnid>48ED-1071532336</paymenttxnid> <paymenttxnlineid>48F1-1071532336</paymenttxnlineid> </depositlineadd> </depositadd> </depositaddrq> |
Note
Note
If you use the ReceivePaymentToDeposit query to obtain a TxnID and TxnLineID, be sure to supply both of these values to the DepositAdd request (in the PaymentTxnID and PaymentTxnLineID elements).