QuickBooks Desktop and QuickBooks Payments integration

Saving Payments data into QuickBooks Desktop enables the merchant to use the QuickBooks Reconcile feature to account for credit card transaction fees and to get funding status. You can use the QuickBooks Payments API only to do payments transactions. But that would not take full advantage of its benefits, namely, the ability to save the Payments transaction request data into QuickBooks Desktop.

If you intend to reconcile Payments transaction data into QuickBooks Desktop, then you will be sending certain parts of the Payments transaction request and response for inclusion in certain QBXML SDK SalesReceiptAddRq, ReceivePaymentAddRq, and ARRefundCreditCardAddRq requests all accept Payments transaction data.

You will need to request that your Payments App be whitelisted for recon(reconciliation) data, by submitting a support ticket asking for your app to be whitelisted for recon data and include your Payments AppID in the request.

Whitelisting your Payments application will add the following fields to the Payments response:

• “paymentGroupingCode”: “5”,
• “paymentStatus”: “Completed”,
• “reconBatchID”: “420200428 1Q09435247719956394663AUTO04”,
• “recurring”: false,
• “txnAuthorizationStamp”: “1588092181”,
• “merchantAccountNumber”: “1234719921256732”,
• “clientTransID”: “arkazk62”,
• Note: You will need to convert the txnAuthorizationStamp from a Unix timestamp to a String and place it in the TxnAuthorizationTime field.

The QuickBooks Desktop with Payment Reconcile feature is designed to solve the problem of keeping the merchant’s QuickBooks company data in sync with the merchant’s actual bank account data. There are two areas where these can get out of sync and where reconciliation can help:

• Credit card funding of transactions occurring in the real bank account are not reflected in QuickBooks Desktop until the merchant performs a Deposit to record the deposit of the transaction funds in the QuickBooks Desktop’s bank account.
  • To help sync up Get Funding Status, QuickBooks Desktop with Payments provides Funding Status information for each batch of deposits inside the QuickBooks Undeposited Funds account. The Get Funding Status button gets the current status of the selected transactions from Payments. If the transactions are funded at the merchant’s bank, the merchant knows that the transactions need to be moved from QuickBooks Undeposited Funds into the appropriate bank account set up to receive those funds.
• Credit card transaction fees taken out of the merchant’s real bank account are not reflected in the QuickBooks company until the merchant updates QuickBooks Desktop with those assessed fees. These fees are charged on a daily as well as monthly basis and consist of fees such as transaction fees, discount fees, downgrades, monthly fees, and chargebacks.
  • To help sync up the QuickBooks company in the transaction fees area, QuickBooks Desktop with Payments enables the merchant to download the fees for VISA, Discover, and Mastercard that were posted to the bank account. This permits accurate matching of the fees with the actual bank debits. For American Express, since the funds are deposited net of fees, QB lets the merchant compute the fees through a fees calculator while depositing the funded batch of transactions in QuickBooks Desktop.

In the scenarios described above, if the credit card transactions are carried out within QuickBooks Desktop enabled with Payments, the transaction data is already in QuickBooks Desktop and only the synching-up for Funding status and Fees is required in QuickBooks Desktop using the Reconcile feature.

However, if you have a third party application integrated with the QuickBooks Payments API, then that transaction data must be saved by the third party application into QuickBooks Desktop via the QBXML SDK requests: ReceivePaymentAdd, SalesReceiptAdd, or ARRefundCreditCardAdd. (The response data from the Payments transaction requests contain data that must be included in those requests.)

Important:

1. The aggregate containing the supplied Payments transaction data must mask the credit card number with lower case x and no dashes. For example, xxxxxxxxxxxx1234.

   Notice that once the transaction data is automatically saved into QuickBooks Desktop, the merchant must still manually perform the sync operations (making QB deposits when the real Bank account is funded, loading any transaction fees into QuickBooks Desktop). Those activities are NOT automated by the QuickBooks Payments API or by the QBXML SDK.

2. You must be careful when bringing data from Payments credit card transactions into a QuickBooks company via the SalesReceiptAdd, ReceivePaymentAdd, or ARRefunCreditCardAdd. The QBXML SDK has no way of knowing which company file should get that information, so if you are logged into the wrong company file, the wrong company file will get that data. One way to implement a check on whether the company is the expected one is to use a data extension on the QuickBooks company.

The ReceivePaymentAdd, SalesReceiptAdd, and ARRefundCreditCardAdd requests (part of the QuickBooks SDK) accept credit card data originating from Payments transactions, if the current QuickBooks company is set up to use Payments and has a valid Payments account.

If you build a ReceivePaymentAdd, SalesReceiptAdd, or ARRefundCreditCardAdd request that contains Payments transaction data, you are responsible for making sure the credit card transaction is mapped to the proper CustomerRef. Also, you must make sure you specify the proper credit card type in the PaymentMethod Ref. This information is NOT included in the credit card aggregate data.

If you don’t specify the credit card type in the PaymentMethodRef, the ReceivePaymentAdd, SalesReceiptAdd, or ARRefundCreditCardAdd request will fail.

If you are including Payments credit card data, both the ReceivePaymentAdd and SalesReceiptAdd requests require the same parent aggregate CreditCardTxnInfo and the same child aggregates CreditCardTxnInputInfo and CreditCardTxnResultInfo, as shown in the OSR. All of the data in these aggregates must be obtained from the Payments credit card requests for CreditCardTxnInputInfo and responses for CreditCardTxnResultInfo.

However, there are two items in the CreditCardTxnResultInfo that might be slightly tricky. The ResultCode and the ResultMessage are the StatusCode and StatusMessage returned as attributes in the Payments responses.

The following sample XML shows a SalesReceiptAdd request containing Payments credit card data. The transaction is for a customer named John Hamilton. Notice the payment ref is set to Credit Card: if you don’t have this, the request will fail. Notice that the aggregate CreditCardTxnResultInfo contains a ResultCode of 0, which means the original Payments transaction request was successful.

 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
44
45
46
47
48
49
50
51
52
53

  <?xml version="1.0"?>
  <?qbxml version="13.0"?>
  <QBXML>
    <QBXMLMsgsRq onError="stopOnError">
          <SalesReceiptAddRq requestID="101">
            <SalesReceiptAdd>
                  <CustomerRef>
                    <FullName>John Hamilton</FullName>
                  </CustomerRef>
                  <TxnDate>2009-02-23</TxnDate>
                  <RefNumber>2345</RefNumber>
                  <PaymentMethodRef>
                    <FullName>Visa</FullName>
                  </PaymentMethodRef>
                  <Memo>QBMS SDK Test 2345</Memo>
                  <CreditCardTxnInfo>
                    <CreditCardTxnInputInfo>
                          <CreditCardNumber>xxxxxxxxxxxx4444</CreditCardNumber>
                          <ExpirationMonth>12</ExpirationMonth>
                          <ExpirationYear>2012</ExpirationYear>
                          <NameOnCard>John Hamilton</NameOnCard>
                          <CreditCardAddress>2750 Coast Avenue</CreditCardAddress>
                          <CreditCardPostalCode>94043</CreditCardPostalCode>
                          <CommercialCardCode>123</CommercialCardCode>
                          <TransactionMode>CardNotPresent</TransactionMode>
                    </CreditCardTxnInputInfo>
                    <CreditCardTxnResultInfo>
                          <ResultCode>0</ResultCode>
                          <ResultMessage>STATUS OK</ResultMessage>
                          <CreditCardTransID>V64A76208243</CreditCardTransID>
                          <MerchantAccountNumber>4269281420247209</MerchantAccountNumber>
                          <AuthorizationCode>185PNI</AuthorizationCode>
                          <AVSStreet>Pass</AVSStreet>
                          <AVSZip>Fail</AVSZip>
                          <CardSecurityCodeMatch>Pass</CardSecurityCodeMatch>
                          <ReconBatchID>420050223 MC 2005-02-23 QBMS 15.0 pre-beta</ReconBatchID>
                          <PaymentGroupingCode>4</PaymentGroupingCode>
                          <PaymentStatus>Completed</PaymentStatus>
                          <TxnAuthorizationTime>2005-02-23T20:57:13</TxnAuthorizationTime>
                          <TxnAuthorizationStamp>1109192233</TxnAuthorizationStamp>
                          <ClientTransID>q0002ee5</ClientTransID>
                    </CreditCardTxnResultInfo>
                  </CreditCardTxnInfo>
                  <SalesReceiptLineAdd>
                    <ItemRef>
                          <FullName>Fee</FullName>
                    </ItemRef>
                    <Rate>100.00</Rate>
                  </SalesReceiptLineAdd>
            </SalesReceiptAdd>
          </SalesReceiptAddRq>
    </QBXMLMsgsRq>
  </QBXML>

If your application integrates Payments transaction data with QuickBooks Desktop, the merchant must also have a version of QuickBooks Desktop that supports the Payments recon data. We strongly recommend the use of QBXML specification 6.0 and greater and QuickBooks Desktop 2008 and Enterprise version 8 or greater, because these support the latest PCI/PADSS standards required by card payment processors.

If you want your web application to access a QuickBooks company at a remote location, say at a customer/merchant’s system, you can do so using the QuickBooks Web Connector. To see how to do this, please refer to the QuickBooks Web Connector Programmer’s Guide included with the QBXML SDK.

It is possible integrate an application both with QB POS and with Payments. One typical way that this is used is that in QBPOS, merchants use two key transactions for sales - Sales Orders (most commonly used for online transactions) that are fulfilled later in the store by the retailer, and Sales Receipts (immediate fulfillment). In either case, we recommend use of the QuickBooks Payments API for authorizing & capturing the credit card funds after fulfillment.

Notice that currently Auth transaction data cannot be stored in QuickBooks Desktop.

The elements in the response are supplied in the CreditCardTxnResultInfo aggregate when you save the transaction to QuickBooks Desktop: most of these are used by QuickBooks Desktop internally for the Reconcile feature and the Get Funding Status feature. See the OSR for field descriptions.

The elements in the response are supplied in the CreditCardTxnResultInfo aggregate when you save the transaction to QuickBooks Desktop: most of these are used by QuickBooks Desktop internally for the Reconcile feature and the Get Funding Status feature. See the OSR for field descriptions.

Important: The Payments transaction data brought into QuickBooks Desktop must mask the credit card number. It should be all lowercase x except for the last four digits, with no dashes.

If the response to a Refund or Void request contains the Type “Refund”, then you can save the transaction in QuickBooks Desktop using the QBXML SDK request ARRefundCreditCardAdd. To save the transaction you need to supply the last 4 digits of the credit card number, and expiration month and year of the card used in the original sales or delayed capture transaction. If the response to a Refund or Void request contains the Type “Void”, then you do not save any data into QuickBooks Desktop.

Using the response data obtained from the CustomerCreditCardRefund request, you can optionally save the refund transaction data into QuickBooks Desktop via the request ARRefundCreditCardAddRq.

Data from this transaction is not saved into QuickBooks Desktop.