Handling Receive Payment Transactions

[PCIPal]

QuickBooks receive payment transactions can be added, queried, and deleted. This section describes the effects of sending a ReceivePaymentAdd request object to QuickBooks.

Applying a Payment:

In a ReceivePaymentAdd object, TotalAmount is optional. TotalAmount represents the total amount of money that is being received from the customer named in the CustomerRef. The reason TotalAmount is not required is that a ReceivePaymentAdd object can be used to set credits or discounts without receiving any payment.

You can use either AppliedToTxnAdd or IsAutoApply to distribute the received payment, as described in the following sections.

Distributing the Payment Explicitly:

You can include one or more instances of AppliedToTxnAdd, which allows you to specify exactly how to distribute TotalAmount for this customer job. Each instance of AppliedToTxnAdd refers to a different transaction, assigning a PaymentAmount to each one. (If you include AppliedToTxnAdd aggregates with duplicate TxnIDs, you will receive a status code error.)

You need to know the transaction ID of each transaction to which payment is applied. In QuickBooks, the main type of transactions that can receive payment are as follows:

•   Invoices
•   General journal debits
•   Checks (for example, a customer job might receive a payment reimbursing a check that was written for an expense for that customer job)
•   Statement charges

Table 18-1 attached 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).

Applying the Payment “Automatically”:

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:

•   If IsAutoApply is true, QuickBooks applies TotalAmount according to the following rules:
> If it finds an outstanding transaction for this customer job that exactly matches TotalAmount, it applies the payment to that transaction.
> If no exact match is found, the payment is applied to the outstanding transactions beginning with the oldest one. Within the QuickBooks user interface, you can set credits or discounts even when you auto-apply a payment, but you cannot do this through the SDK.
•   If IsAutoApply is false, QuickBooks receives the payment but does not apply it to any outstanding transaction. QuickBooks creates a credit that will appear on the customer job’s next transaction (not on the current transaction). For example, the ReceivePaymentAdd request shown in Listing 18-1 will result in a credit of $620.40 being available to the Smith:kitchen customer job account. On the next transaction involving the Smith:kitchen customer job, at least $620.40 of credit will be available. (More than $620.40 will be available if this customer job already had a credit.)

Listing 18-1 ReceivePaymentAdd request with IsAutoApply set to false; creating a credit:

PCQB_RqNew( “ReceivePaymentAdd” )
PCQB_RqAddFieldWithValue( “CustomerRef::FullName” ; “Smith:kitchen” )
PCQB_RqAddFieldWithValue( “ARAccountRef::FullName” ; “Accounts Receivable” )
PCQB_RqAddFieldWithValue( “TotalAmount” ; “620.40” )
PCQB_RqAddFieldWithValue( “IsAutoApply” ; “false” )

Setting Discounts:

Applying a discount reduces the amount that is to be received from the customer job. The discount is debited from the account referenced by DiscountAccountRef. In the QuickBooks user interface you can also apply discounts to statement charges, but you cannot do this through the SDK.

You can apply a discount to an invoice transaction by including a DiscountAmount in an AppliedToTxnAdd aggregate. You cannot set a discount if you auto-apply the payment.

Setting Credits:

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 ReceivePaymentAdd request 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.

For more information and an example of setting a credit, see “Example: Creating Links Only.”

Example: Creating Links Only

Listing 18-2 shows a ReceivePaymentAdd object 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 their account. A CreditMemoQueryRq query returned information about the amount and transaction ID of this credit memo (110.29 and 120-1012533559).

In Listing 18-2, 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.

Listing 18-2 ReceivePaymentAdd object that creates links but does not create a transaction:

PCQB_RqNew( “ReceivePaymentAdd” )
PCQB_RqAddFieldWithValue( “CustomerRef::FullName” ; “Smith:kitchen” )
PCQB_RqAddRelatedRecord( “AppliedToTxnAdd” )
PCQB_RqAddFieldWithValue( “TxnID” ; “24-974954” )
PCQB_RqAddRealtedRecord( “SetCredit” )
PCQB_RqAddFieldWithValue( “CreditTxnID” ; “120-1012533559” )
PCQB_RqAddFieldWithValue( “AppliedAmount” ; “110.29” )
PCQB_RqCloseRelatedRecord //closes the SetCredit record
PCQB_RqCloseRelatedRecord //closes the AppliedToTxnAdd record

A ReceivePaymentAdd object that does not create a transaction will return a lean AppliedToTxnRet aggregate this page. For example, Listing 18-3 shows a ReceivePaymentRet object that could be returned from the ReceivePaymentAdd request shown in Listing 18-2.

Listing 18-3 ReceivePaymentRet object returned by the ReceivePaymentAddRq shown in Listing 18-2:

<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>

How to parse the object...

PCQB_RsOpenFirstRecord
PCQB_RsOpenFirstRelatedRecord( “AppliedToTxnRet” )
PCQB_RsGerFirstFieldValue( “TxnID” ) //The transaction id for the related transaction
PCQB_RsGetFirstFieldValue( “TxnType” ) //The type for the related transaction
PCQB_RsGetFirstFieldValue( “TxnDate” ) //the date for the related transaction

Getting a small 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 in Listing 18-3, 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. For more information, see “Linked Transactions,”.

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.

Example: Applying Payment, Credit, and Discount in One Request

Listing 18-4 shows a request 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.

Listing 18-4 Applying Payment, Credit, and Discount in a ReceivePaymentAdd Request:

PCQB_RqNew( “ReceivePaymentAdd” )
...
PCQB_RqAddFieldWithValue( “TotalAmount” ; “100.00” )
PCQB_RqAddRelatedRecord( “AppliedToTxnAdd” )
PCQB_RqAddFieldWithValue( “TxnID” ; “43-222560” )
PCQB_RqAddFieldWithValue( “PaymentAmount” ; “100.00” )
PCQB_RqAddRelatedRecord( “SetCredit” )
PCQB_RqAddFieldWithValue( “CreditTxnID” ; “4552-22629” )
PCQB_RqAddFieldWithValue( “AppliedAmount” ; “5.00” )
PCQB_RqCloseRelatedRecord //closes the SetCredit record
PCQB_RqAddFieldWithValue( “DiscountAmount” ; “7.00” )
PCQB_RqAddFieldWithValue( “DiscountAccountRef::FullName” ; “discount” )
PCQB_RqCloseRelatedRecord //closes the AppliedToTxnAdd record

[Geoffrey Gerhard]

Nice write up.

A couple quick edits: this...

On February 22, 2018 at 6:57 PM, PCIPal said:

For example, after receiving the response shown in Listing 18-2

...should say "18-3" or "the response from the Query shown in Listing 18-2"

And in case anyone copy/pastes 18-2 or 18-4, there's a typo in the line...

PCQB_RqAddRealtedRecord( “SetCredit” )

...where "Realted" should read "Related" like this...

PCQB_RqAddRelatedRecord( “SetCredit” )

HTH!

Geoffrey Gerhard
Creative Solutions Incorporated
14000 Creekside Drive
Matthews, NC  28105
704) 814-6852

[PCIPal]

Thank you for catching those typos, Geoffrey! Post has been updated to reflect those changes.