Requests and responses for credit card refunds
Prior to QuickBooks 2006, QuickBooks provided no transaction specifically for refunds to customers, for example in the case of returned goods or overpayments. Beginning with QuickBooks 2006 credit card refund transactions are supported. Requests for credit card refunds must link the refund to an existing credit memo transaction.
Notice that via the SDK you can specify one or more of these transactions. In comparison, the UI limits you to linking one credit transaction per refund.
The refund can be a full refund of the entire amount of the specified credit memo or it can be a partial refund. (The response to the ARRefundCreditCard Add or Query returns the amount remaining on each credit for which you are issuing the refund.)
The ARRefundCreditCard* functionality provided by the SDK also supports the credit card transaction data provided by qbmsXML interaction with QuickBoooks Merchant Service (QBMS), so that the actual credit card transaction data can be stored in QuickBooks.
The following figure shows the beginning of the API Reference page for ARRefundCreditCardAdd.
The CustomerRef is required and must match the customer in the target transactions you want to link.
The RefundFromAccountRef is the source account from which the refund is made. Typically this is the default Undeposited Funds account, but you could specify any bank account or asset account here. This is optional: if you omit this, the Undeposited Funds default account is used.
The ARAcountRef is also optional. If you omit it, the default Accounts Receivable account is used. Make sure this account matches the ARAccountRef in the credit memo transactions you are linking to.
TxnDate and RefNumber are supplied for you automatically, but you can supply your own values if you want.
The address information is supplied for you via the CustomerRef so normally you need not add it in the request.
The PaymentMethodRef specifies the type of credit card used in the refund transaction. If there is credit card data included in the QuickBooks customer information, you can omit this tag and let QuickBooks supply the card type automatically. If you specify a non-credit card type here, you’ll get a runtime error.
Memo is available for any notes you want to save with the transaction.
The next figure shows the remainder of the API Reference page for ARRefundCreditCardAdd:
The credit card information contained in the CreditCardTxnInfo aggregate is optional, but if you supply that aggregate, you have to supply both the CreditCardTxnInputInfo and the CreditCardTxnResultInfo sub aggregates along with their required elements, as shown in the API Reference. Can you supply just any credit card data here? No, the data supplied here must be data from a qbmsXML refund transaction against the QuickBooks Merchant Service. Notice that the CreditCardTransType will always be Refund.
This means that you can supply this only if the company has a valid QBMS account and you use qbmsXML to interact with QBMS for credit card transactions. How can you determine this in the SDK? Simply do a company query and check the SubscribedServices aggregate for the QBMS service.
The InputInfo subaggregate is the data from the originating qbmsXML request that effected the credit card transaction. The ResultInfo subaggregate is the qbmsXML response to that request. You include all of this data in this request if you want to save that QBMS transaction data within QuickBooks. For more information, see the Developer’s Guide for QuickBooks Merchant Services.
If the original QBMS transaction was a qbmsXML 2.0 request or greater, and the qbXML spec level of your SalesReceiptAdd request is 6.0 or greater, the credit card number must be masked, that is, all X, except for the last 4 digits.
Notice that including the QBMS transaction data in the request does not result in any interactions with QBMS or in any attempts to connect to QBMS.
You link this refund to the target credit memo using the RefundAppliedToTxnAdd aggregate. You must link to at least one of these transactions; you can link to as many as you want. The TxnID is unique among these transactions, so you don’t (in fact you can’t) specify a transaction type.
The RefundAmount specifies how much of the linked credit transaction is to be refunded. If you specify an amount here that is greater than the credit, you’ll get a runtime error.
The following example shows how to build the credit card refund request in QBFC. This listing happens to include credit card transaction data from QBMS but this is not required. The code for building the refund is pretty straightforward. We don’t do any checks to make sure we don’t exceed any credit amounts, but you’ll need to do this.
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 54 55 56 57 58 59 60 61 62 63 64 | Public Sub QBFC_AddARRefundCreditCard()
Dim SessionManager As QBSessionManager
SetSessionManager = New QBSessionManager SessionManager.OpenConnection "",
"IDN Add ARRefundCreditCard Sample"
SessionManager.BeginSession "", omDontCare
Dim requestMsgSet As IMsgSetRequest
Set requestMsgSet = SessionManager.CreateMsgSetRequest("US", 5, 0) ' Initialize the
message set request's attributes
requestMsgSet.Attributes.OnError = roeStop
' Add the request to the message set request object Dim ARRefundCCAdd As IARRefundCreditCardAdd
Set ARRefundCCAdd = requestMsgSet.AppendARRefundCreditCardAddRq
'Set the properties in the Refund add object ARRefundCCAdd.CustomerRef.FullName.setValue
("Jack Williams")
ARRefundCCAdd.RefundFromAccountRef.FullName.setValue ("Undeposited Funds")
ARRefundCCAdd.ARAccountRef.FullName.setValue ("Accounts Receivable")
ARRefundCCAdd.PaymentMethodRef.FullName.setValue ("Visa") ARRefundCCAdd.Memo.setValue
("Partial refund sample")
'Add optional credit card info from a qbmsXML transaction with QBMS
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnInputInfo.CreditCardNumber.
setValue ("4111111111111111")
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnInputInfo.ExpirationYear.setValue (2008)
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnInputInfo.ExpirationMonth.setValue (11)
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnInputInfo.NameOnCard.setValue
("Jack Williams")
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnInputInfo.CreditCardTxnType.setValue
ccttRefund
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnResultInfo.ResultCode.setValue (0)
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnResultInfo.ResultMessage.setValue
("STATUS OK")
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnResultInfo.CreditCardTransID.setValue
("V54A60275101")
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnResultInfo.MerchantAccountNumber.setValue
("4269281420247209")
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnResultInfo.AuthorizationCode.setValue
("185PNI")
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnResultInfo.ReconBatchID.setValue
("420050223 MC 2005-02-23 QBMS 15.0 pre-beta")
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnResultInfo.PaymentGroupingCode.setValue (4)
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnResultInfo.PaymentStatus.setValue
(pssCompleted)
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnResultInfo.TxnAuthorizationTime.setValue
"2005-11-01", False
ARRefundCCAdd.CreditCardTxnInfo.CreditCardTxnResultInfo.TxnAuthorizationStamp.setValue
(1109192233)
'Now link two transactions whose TxnID we hardcoded here Dim RefundAppliedToTxn As
IRefundAppliedToTxnAdd
Set RefundAppliedToTxn = ARRefundCCAdd.RefundAppliedToTxnAddList.Append
RefundAppliedToTxn.RefundAmount.setValue (1)
RefundAppliedToTxn.TxnID.setValue ("B0-1131081904")
Set RefundAppliedToTxn = ARRefundCCAdd.RefundAppliedToTxnAddList.Append
RefundAppliedToTxn.RefundAmount.setValue (1)
RefundAppliedToTxn.TxnID.setValue ("9F-1131074959")
' Perform the request and obtain a response from QuickBooks Dim responseMsgSet
As IMsgSetResponse
Set responseMsgSet = SessionManager.DoRequests(requestMsgSet)
‘Save the results to a file for grins. requires Microsoft Scripting Runtime Dim fname As String
Dim xml As String
xml = responseMsgSet.ToXMLString
fname = "XML_request.doc"
Dim fso As New FileSystemObject Dim ts As TextStream
Set ts = fso.CreateTextFile(fname, True) ts.Write (xml)
Close the session and connection with QuickBooks. SessionManager.EndSession
SessionManager.CloseConnection
End Sub
|
The following example shows a simple Refund add request with linked credit memos.
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 | <?xml version="1.0" ?> <?qbxml version="5.0"?> <QBXML> <QBXMLMsgsRq onError = "stopOnError"> <ARRefundCreditCardAddRq requestID = "0"> <ARRefundCreditCardAdd> <CustomerRef> <FullName>Jack Williams</FullName> </CustomerRef> <RefundFromAccountRef> <FullName>Undeposited Funds</FullName> </RefundFromAccountRef> <ARAccountRef> <FullName>Accounts Receivable</FullName> </ARAccountRef> <PaymentMethodRef> <FullName>Visa</FullName> </PaymentMethodRef> <Memo>Partial refund sample</Memo> <RefundAppliedToTxnAdd> <TxnID>B0-1131081904</TxnID> <RefundAmount>1.00</RefundAmount> </RefundAppliedToTxnAdd> <RefundAppliedToTxnAdd> <TxnID>9F-1131074959</TxnID> <RefundAmount>1.00</RefundAmount> </RefundAppliedToTxnAdd> </ARRefundCreditCardAdd> </ARRefundCreditCardAddRq> </QBXMLMsgsRq> </QBXML> |
The next example shows a Refund add request with credit card transaction data from a preceding qbmsXML request/response interaction with QBMS.
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="5.0"?> <QBXML> <QBXMLMsgsRq onError = "stopOnError"> <ARRefundCreditCardAddRq requestID = "0"> <ARRefundCreditCardAdd> <CustomerRef> <FullName>Jack Williams</FullName> </CustomerRef> <RefundFromAccountRef> <FullName>Undeposited Funds</FullName> </RefundFromAccountRef> <ARAccountRef> <FullName>Accounts Receivable</FullName> </ARAccountRef> <PaymentMethodRef> <FullName>Visa</FullName> </PaymentMethodRef> <Memo>Partial refund sample</Memo> <CreditCardTxnInfo> <CreditCardTxnInputInfo> <CreditCardNumber>4111111111111111</CreditCardNumber> <ExpirationMonth>11</ExpirationMonth> <ExpirationYear>2008</ExpirationYear> <NameOnCard>Jack Williams</NameOnCard> <TransactionMode>CardNotPresent</TransactionMode> <CreditCardTxnType>Refund</CreditCardTxnType> </CreditCardTxnInputInfo> <CreditCardTxnResultInfo> <ResultCode>0</ResultCode> <ResultMessage>STATUS OK</ResultMessage> <CreditCardTransID>V54A60275101</CreditCardTransID> <MerchantAccountNumber>4269281420247209</MerchantAccountNumber> <AuthorizationCode>185PNI</AuthorizationCode> <ReconBatchID>420050223 MC 2005-02-23 QBMS 15.0 pre-beta</ReconBatchID> <PaymentGroupingCode>4</PaymentGroupingCode> <PaymentStatus>Completed</PaymentStatus> <TxnAuthorizationTime>2005-11-01T00:00:00</TxnAuthorizationTime> <TxnAuthorizationStamp>1109192233</TxnAuthorizationStamp> </CreditCardTxnResultInfo> </CreditCardTxnInfo> <RefundAppliedToTxnAdd> <TxnID>B0-1131081904</TxnID> <RefundAmount>1.00</RefundAmount> </RefundAppliedToTxnAdd> <RefundAppliedToTxnAdd> <TxnID>9F-1131074959</TxnID> <RefundAmount>1.00</RefundAmount> </RefundAppliedToTxnAdd> </ARRefundCreditCardAdd> </ARRefundCreditCardAddRq> </QBXMLMsgsRq> </QBXML> |
When you query for credit card refund transactions and use the entity filter, you must specify only customer or customer jobs. Other than this, this is a standard query, which is described in Query requests and responses.
To delete and void credit card refund transactions, you use TxnDelRq and TxnVoidRq, respectively, as described in Modify, delete, and void requests and responses.
Notice that this deletes any credit card information (CreditCardTxnInfo) in QuickBooks only. This does NOT delete any data at QBMS.