Author Topic: Receive Payments  (Read 10638 times)

snaf

  • Member
  • *
  • Posts: 4
Receive Payments
« on: October 17, 2009, 11:34:19 AM »
Someone has a simple SCRIPT to receive payments ?

I´m trying to use

PCQB_RqNew("ReceivePaymentAdd")  but I can get rigths results...

Set Error Capture [ On ]
Allow User Abort [ On ]
Freeze Window
Set Field [ Contact Management::gResult; PCQB_EndSession ]
Set Field [ Contact Management::gResult; PCQB_BeginSession("";"") ]
#Recebe valores
Set Field [ Contact Management::gResult; PCQB_RqNew( "ReceivePaymentAdd";"") ]
Set Field [ Contact Management::gResult; PCQB_RqAddFieldWithValue( "CustomerRef::ListID" ;"81A0002-1251482985" ) ]
Set Field [ Contact Management::gResult; PCQB_RqAddFieldWithValue( "CustomerRef:FullName" ;"1118, PATRICIA MOREIRA
GASPAR DE OLIVIERA" ) ]
Set Field [ Contact Management::gResult; PCQB_RqAddFieldWithValue( "RefNumber" ;"74") ]
Set Field [ Contact Management::gResult; PCQB_RqAddFieldWithValue( "TotalAmount" ;"55.00") ]
Set Field [ Contact Management::gResult; PCQB_RqExecute ]
#Check for Errors
Perform Script [ “Check for Errors” ]
Set Field [ Contact Management::gResult; PCQB_EndSession ]


CODE -1000
SEVERITY: failed validation
MESSAGE: Error at/ReceivePaymentAdd
Reason: Content for element "ReceivePaymentAdd" is incomplete according to the DTD/Schema
« Last Edit: October 17, 2009, 04:29:04 PM by snaf »

snaf

  • Member
  • *
  • Posts: 4
Re: Receive Payments
« Reply #1 on: October 18, 2009, 06:53:47 AM »
I made changes to SCRIPT.
Now I got the message: Object "1EE-1255869271" specifief in the request cannot be found.
This is the ListID of the Invoice, I check serveral times and it exists.


Set Error Capture [ On ]
Allow User Abort [ On ]
Freeze Window
Set Field [ Contact Management::gResult; PCQB_EndSession ]
Set Field [ Contact Management::gResult; PCQB_BeginSession("";"") ]
#Recebe valores
Set Field [ Contact Management::gResult; PCQB_RqNew( "ReceivePaymentAdd" ) ]
Set Field [ Contact Management::gResult; PCQB_RqAddFieldWithValue( "CustomerRef::FullName";"1006, Marcos de Lima
Pinto") ]
Set Field [ Contact Management::gResult; PCQB_RqAddRelatedRecord( "AppliedToTxnAdd" ) ]
Set Field [ Contact Management::gResult; PCQB_RqAddFieldWithValue( "TxnID";Contact Management::gResult InvoiceID) ]
Set Field [ Contact Management::gResult; PCQB_RqAddFieldWithValue( "PaymentAmount" ;"55.00") ]
Set Field [ Contact Management::gResult; PCQB_RqCloseRelatedRecord ]
Set Field [ Contact Management::gResult; PCQB_RqExecute ]
#Check for Errors
Perform Script [ “Check for Errors” ]
Set Field [ Contact Management::gResult; PCQB_EndSession ]

Melinda DePalma

  • Member
  • *
  • Posts: 179
    • Productive Computing
Re: Receive Payments
« Reply #2 on: October 20, 2009, 09:48:59 AM »
Here is a sample script that you may find useful.  ;)



snaf

  • Member
  • *
  • Posts: 4
Re: Receive Payments
« Reply #3 on: October 21, 2009, 07:04:04 AM »
Melinda,

Thanks for the script, it is very useful.

Do you have any suggestions if the payment ammount is different than the invoice value ?

Melinda DePalma

  • Member
  • *
  • Posts: 179
    • Productive Computing
Re: Receive Payments
« Reply #4 on: October 22, 2009, 04:51:55 PM »
Although this may not directly answer your question and may be more than you want, I find it extremely educational regarding Receive Payment Transactions as this comes directly from the SDK:

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-2, 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_RqAddRealtedRecord( “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

julioPlasencia

  • Member
  • *
  • Posts: 1
Re: Receive Payments
« Reply #5 on: November 20, 2009, 01:40:40 PM »
Hello,

Melinda, my script looks just like the one you attached originally, but I keep getting an error that the TxnID is invalid. Is this number NOT the invoice number I want to apply the payment to?

Julio

Melinda DePalma

  • Member
  • *
  • Posts: 179
    • Productive Computing
Re: Receive Payments
« Reply #6 on: November 24, 2009, 05:14:52 PM »
No, the TxnID is not the invoice number. QuickBooks generates a unique TxnID for each transaction that is added to QuickBooks. The TxnID is the transaction id for the related transaction. A TxnID returned from a request can be used to refer to the transaction in subsequent requests.

The most likely causes of the error are:
- The invoice is paid
- The invoice is recorded in an account that is different from that of the ReceivedPayment
- You include AppliedToTxnAdd aggregates with duplicate TxnIDs in the same Add request

To test compare the ARAccountRef::FullName of the invoice to the default in QB for receiving payments. The ARAccountRef::FullName in both the InvoiceAdd/Mod and ReceivePaymentAdd requests must be the same.


garry_n

  • Member
  • *
  • Posts: 3
Re: Receive Payments
« Reply #7 on: November 28, 2009, 09:53:41 AM »
Greetings,

I spent about month trying to figure this out. I was getting the same results. You need to specify the Accounts Receivable Account the payment will be applied to:

PCQB_RqAddFieldWithValue( "ARAccountRef::FullName" ;"ACCOUNTS RECIEVABLE")
(note: your ARAccountRef::FullName may be different than "ACCOUNTS RECIEVABLE")


Thanks to Chris Kuhn at Productive Computing for the solution.