QuickBooks Merchant Services

From ConsoliBYTE Wiki
Jump to: navigation, search

Contents

QuickBooks Merchant Services

You can talk to QuickBooks Merchant Services like any other payment gateway by HTTP POSTing data (via CURL, HttpLib, or a socket, or whatever your programming language supports). You'll send a qbXML request, and get back a qbXML response.

This documentation is for a standard qbXML gateway connection. If you're looking to do a "Hosted PayPage" thing (where you send the user to Intuit's website to pay, and then they get bounced back) then this is NOT the documentation for you. This documentation is if you want to collect the card data on your own website (e.g. in your shopping cart) and then pass the card information in the background to Intuit for auth/charge.

Getting Started

  1. Start by getting a test account here: https://merchantaccount.ptc.quickbooks.com/j/mas/signup?nonQBmerchant=true
  1. And registering for a developer account here: http://developer.intuit.com
  1. Then, go to the application registration page here: https://developer.intuit.com/Application/Create/QBMS


Getting started with the 'Desktop' communication model

  1. Follow the steps on the application registration page here: https://developer.intuit.com/Application/Create/QBMS
  2. You will be provided with an application login and connection ticket which you'll use in your QBMS XML posts.
  3. After you have developed your QBMS application, you need to attach your QBMS account to your application registration. You can do that by visiting the links below in a web browser.
  1. For production applications, visit this page in a web browser: https://merchantaccount.quickbooks.com/j/sdkconnection?appid=YOUR-APPLICATION-ID-HERE&appdata=mydata
  1. For development applications, visit this page in a web browser: https://merchantaccount.ptc.quickbooks.com/j/sdkconnection?appid=YOUR-APPLICATION-ID-HERE&appdata=mydata

Notes

Even if your application is actually a hosted application, you can still use the desktop communication model, it's just a bit less secure.

Getting started with the 'Hosted' communication model

You need to follow these steps to set up the 'Hosted' communication model with QuickBooks Merchant Service.

  1. Register your application here: https://appreg.intuit.com/AppReg.aspx (you'll only be able to get part-way through the process before you need to generate a CSR).
  2. Your callback URLs should point to a PHP script which saves HTTP POST data somewhere (i.e. <?php $fp = fopen('out.txt', 'a+'); fwrite($fp, print_r($_REQUEST, true)); fclose($fp); ?>)
  3. Generate a CSR on your server. You can do this with the following two commands from a *nix shell prompt, or using Cygwin on Windows. The [Common Name] for the CSR should be in the form of: your-https-hostname.com:your-application-login. You should not enter an e-mail address when prompted. You should not enter a password.
 
openssl genrsa -out host.key 1024
openssl req -new -nodes -key host.key -out host.csr
 
  1. Finish going through the application registration process, saving the stuff it spits back at you.
  2. Append the key to the certificate generated by Intuit for your CSR (key first, certificate second). This is the .pem file that you will send with your outgoing request to the QBMS servers. So the contents of the .pem file should look something like this:
 
-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQCsUdEx9P9Cn1ghpPf5HSLKlw2I7MGAmUEKp2wuqeEURsAEm/WT
XNhrbywv5SqeYJqbiZnjjjek01a+gWoCyN/7hIB1/XELIYffGiJv7pvFLzY6yfv8
... more stuff here...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIEEzCCA3ygAwIBAgICB1MwDQYJKoZIhvcNAQEEBQAwgcExCzAJBgNVBAYTAlVT
MRYwFAYDVQQIEw1NYXNzYWNodXNldHRzMRAwDgYDVQQHEwdXYWx0aGFtMTswOQYD
... more stuff here...
-----END CERTIFICATE-----
 
  1. After you have developed your QBMS application, you need to attach your QBMS account to your application registration. You can do that by visiting one of the two links below in a web browser:
  1. For production applications, visit this page in a web browser: https://merchantaccount.quickbooks.com/j/sdkconnection?appid=YOUR-APPLICATION-ID-HERE&appdata=mydata
  1. For development applications, visit this page in a web browser: https://merchantaccount.ptc.quickbooks.com/j/sdkconnection?appid=YOUR-APPLICATION-ID-HERE&appdata=mydata

Notes

You can inspect an existing CSR with this command:

openssl req -in server.csr -noout -text

You can inspect an existing certificate with this command:

openssl x509 -text -in /Users/kpalmer/cert.pem

If you get an error that says “ARSC260: Login name not found. Check your CN= entries applogin value”, try generating your CSR again without entering an e-mail address. For some reason entering an e-mail address borks the CSR sometimes.

If you get an error that says “2000: Host in certificate does not match connected host”, check that your reverse DNS entries point to the correct server. You can check your reverse DNS with this command: host xxx.xxx.xxx.xxx (where xxx.xxx.xxx.xxx is your IP server's address)

Sending Transactions to the QuickBooks Merchant Service Gateway

Once you have attached your application to your QBMS account, you HTTP POST XML requests to a URL to run transactions, and read the HTTP response for XML that tells you the result of the transactions. You send your POST requests to:

  1. For production applications: https://webmerchantaccount.quickbooks.com/j/AppGateway
  1. For development applications: https://webmerchantaccount.ptc.quickbooks.com/j/AppGateway

Example QBMS XML Requests and Responses

Sample Code

  1. QuickBooks PHP DevKit
  2. QuickBooks Merchant Services with Visual Basic .NET

Signing On with the HOSTED Security Model

The HOSTED security model is designed for web applications that need to issue QBMS requests. It provides additional security over the DESKTOP security model in the form of SSL certificate verifications. Note that either security model can be used by a website, but the HOSTED security model is the recommended security model for web applications.

Example SignOn Request

 
<?xml version="1.0" ?>
<?qbmsxml version="3.0"?>
<QBMSXML>
  <SignonMsgsRq>
    <SignonAppCertRq>
      <ClientDateTime>2009-05-17T13:04:00</ClientDateTime>
      <ApplicationLogin>applogin.www.your-domain.com</ApplicationLogin>
      <ConnectionTicket>TGT-152-LWGg2YQRgfTAlSW8DK1c6A</ConnectionTicket>
    </SignonAppCertRq>
  </SignonMsgsRq>
</QBMSXML>
 

Example SignOn Response

 
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE QBMSXML PUBLIC "-//INTUIT//DTD QBMSXML QBMS 3.0//EN" "http://webmerchantaccount.ptc.quickbooks.com/dtds/qbmsxml30.dtd">
<QBMSXML>
 <SignonMsgsRs>
  <SignonAppCertRs statusCode="0" statusSeverity="INFO">
   <ServerDateTime>2009-05-17T17:04:04</ServerDateTime>
   <SessionTicket>V1-148-Q1z7fSxjT0hGKxChABsISw:106892184</SessionTicket>
  </SignonAppCertRs>
 </SignonMsgsRs>
</QBMSXML>
 

Example SignOn Request for DESKTOP Security Model

The DESKTOP security model is designed for applications running on someone's desktop computer (i.e. not a website). Websites can use the DESKTOP security model, but it's slightly less security as anyone with your connection ticket can make QBMS requests.

Example XML Request

 
<?xml version="1.0" ?>
<?qbmsxml version="3.0"?>
<QBMSXML>
  <SignonMsgsRq>
    <SignonDesktopRq>
      <ClientDateTime>2009-05-17T13:13:35</ClientDateTime>
      <ApplicationLogin>applogin.www.your-domain.com</ApplicationLogin>
      <ConnectionTicket>TGT-152-LWGj1YQUugGAlSW8DK1c6A</ConnectionTicket>
    </SignonDesktopRq>
  </SignonMsgsRq>
</QBMSXML>
 

Example XML Response

Example XML Response (failure code, using the wrong security model)

If you try to connect to an application registered with a HOSTED security model using a DESKTOP security model request, you'll receive an error message like this:

 
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE QBMSXML PUBLIC "-//INTUIT//DTD QBMSXML QBMS 3.0//EN" "http://webmerchantaccount.ptc.quickbooks.com/dtds/qbmsxml30.dtd">
<QBMSXML>
 <SignonMsgsRs>
  <SignonDesktopRs statusCode="2000" statusMessage="Application is not a desktop applcation" statusSeverity="ERROR">
   <ServerDateTime>2009-05-17T17:13:37</ServerDateTime>
  </SignonDesktopRs>
 </SignonMsgsRs>
</QBMSXML>
 

AUTHORIZE Credit Card Funds

Example AUTHORIZE Request

 
<?xml version="1.0" ?>
<?qbmsxml version="3.0"?>
<QBMSXML>
  <SignonMsgsRq>
    <SignonTicketRq>
      <ClientDateTime>2009-05-17T13:04:05</ClientDateTime>
      <SessionTicket>V1-148-Q1z7fSxjT0gJKxCvEBsISw:106892184</SessionTicket>
    </SignonTicketRq>
  </SignonMsgsRq>
  <QBMSXMLMsgsRq>
    <CustomerCreditCardAuthRq>
      <TransRequestID>1ddffe13d5394151142b74dd2215515e</TransRequestID>
      <CreditCardNumber>5105105105105100</CreditCardNumber>
      <ExpirationMonth>5</ExpirationMonth>
      <ExpirationYear>2009</ExpirationYear>
      <Amount>295.00</Amount>
      <NameOnCard>Keith Palmer</NameOnCard>
      <CreditCardAddress>56 Cowles Road</CreditCardAddress>
      <CreditCardPostalCode>06279</CreditCardPostalCode>
    </CustomerCreditCardAuthRq>
  </QBMSXMLMsgsRq>
</QBMSXML>
 

Example AUTHORIZE Response

 
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE QBMSXML PUBLIC "-//INTUIT//DTD QBMSXML QBMS 3.0//EN" "http://webmerchantaccount.ptc.quickbooks.com/dtds/qbmsxml30.dtd">
<QBMSXML>
 <SignonMsgsRs>
  <SignonTicketRs statusCode="0" statusSeverity="INFO">
   <ServerDateTime>2009-05-17T17:04:09</ServerDateTime>
   <SessionTicket>V1-148-Q1z7fSxjT0jIKxCvGBsISw:106892184</SessionTicket>
  </SignonTicketRs>
 </SignonMsgsRs>
 <QBMSXMLMsgsRs>
  <CustomerCreditCardAuthRs statusCode="0" statusMessage="Status OK" statusSeverity="INFO">
   <CreditCardTransID>ZZ9630895963</CreditCardTransID>
   <AuthorizationCode>604297</AuthorizationCode>
   <AVSStreet>Pass</AVSStreet>
   <AVSZip>Pass</AVSZip>
   <CardSecurityCodeMatch>NotAvailable</CardSecurityCodeMatch>
   <ClientTransID>q0034942</ClientTransID>
  </CustomerCreditCardAuthRs>
 </QBMSXMLMsgsRs>
</QBMSXML>
 

CAPTURE Credit Card Funds (from a previous AUTHORIZATION)

Example XML Request

 
<?xml version="1.0" encoding="utf-8"?>
<?qbmsxml version="3.0"?>
<QBMSXML>
  <SignonMsgsRq>
    <SignonTicketRq>
      <ClientDateTime>2009-05-17T13:04:10</ClientDateTime>
      <SessionTicket>V1-148-Q1z7fSxjT0jGKxCvEBsISw:106892184</SessionTicket>
    </SignonTicketRq>
  </SignonMsgsRq>
  <QBMSXMLMsgsRq>
    <CustomerCreditCardCaptureRq>
      <TransRequestID>9ba28244e07de1df13ccc06ab0f2c77d</TransRequestID>
      <CreditCardTransID>ZZ9630895963</CreditCardTransID>
      <Amount>295.00</Amount>
    </CustomerCreditCardCaptureRq>
  </QBMSXMLMsgsRq>
</QBMSXML>
 

Example XML Response

 
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE QBMSXML PUBLIC "-//INTUIT//DTD QBMSXML QBMS 3.0//EN" "http://webmerchantaccount.ptc.quickbooks.com/dtds/qbmsxml30.dtd">
<QBMSXML>
 <SignonMsgsRs>
  <SignonTicketRs statusCode="0" statusSeverity="INFO">
   <ServerDateTime>2009-05-17T17:04:17</ServerDateTime>
   <SessionTicket>V1-148-Q1z7fSxjT0gJKxCvEBsISw:106892184</SessionTicket>
  </SignonTicketRs>
 </SignonMsgsRs>
 <QBMSXMLMsgsRs>
  <CustomerCreditCardCaptureRs statusCode="0" statusMessage="Status OK" statusSeverity="INFO">
   <CreditCardTransID>ZZ3107419310</CreditCardTransID>
   <AuthorizationCode>313392</AuthorizationCode>
   <MerchantAccountNumber>4269283011409218</MerchantAccountNumber>
   <ReconBatchID>420090517 1Q10044269283011409218AUTO04</ReconBatchID>
   <PaymentGroupingCode>4</PaymentGroupingCode>
   <PaymentStatus>Completed</PaymentStatus>
   <TxnAuthorizationTime>2009-05-17T17:04:17</TxnAuthorizationTime>
   <TxnAuthorizationStamp>1242579857</TxnAuthorizationStamp>
   <ClientTransID>q0034943</ClientTransID>
  </CustomerCreditCardCaptureRs>
 </QBMSXMLMsgsRs>
</QBMSXML>
 

CHARGE Credit Card Funds (basically an AUTHORIZE and a CAPTURE together in one request)

Example XML Request

 
<?xml version="1.0" encoding="utf-8"?>
<?qbmsxml version="3.0"?>
<QBMSXML>
  <SignonMsgsRq>
    <SignonTicketRq>
      <ClientDateTime>2009-10-09T13:14:16</ClientDateTime>
      <SessionTicket>xxxxxxxxxxxxky4yL6eBtCULX1zgQ:106892184</SessionTicket>
    </SignonTicketRq>
  </SignonMsgsRq>
  <QBMSXMLMsgsRq>
    <CustomerCreditCardChargeRq>
      <TransRequestID>35f9cf7cb20994e8a32e6b3e91e8e602</TransRequestID>
      <CreditCardNumber>xxxxxxxxxxxx5100</CreditCardNumber>
      <ExpirationMonth>10</ExpirationMonth>
      <ExpirationYear>2009</ExpirationYear>
      <Amount>295.00</Amount>
      <NameOnCard>Keith Palmer</NameOnCard>
      <CreditCardAddress>56 Cowles Road</CreditCardAddress>
      <CreditCardPostalCode>06279</CreditCardPostalCode>
    </CustomerCreditCardChargeRq>
  </QBMSXMLMsgsRq>
</QBMSXML>
 

Example XML Response

 
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE QBMSXML PUBLIC "-//INTUIT//DTD QBMSXML QBMS 3.0//EN" "http://webmerchantaccount.ptc.quickbooks.com/dtds/qbmsxml30.dtd">
<QBMSXML>
 <SignonMsgsRs>
  <SignonTicketRs statusCode="0" statusSeverity="INFO">
   <ServerDateTime>2009-10-09T17:14:19</ServerDateTime>
   <SessionTicket>xxxxxxxxxxxxky4yL6eBtCULX1zgQ:106892184</SessionTicket>
  </SignonTicketRs>
 </SignonMsgsRs>
 <QBMSXMLMsgsRs>
  <CustomerCreditCardChargeRs statusCode="0" statusMessage="Status OK" statusSeverity="INFO">
   <CreditCardTransID>ZZ3760989376</CreditCardTransID>
   <AuthorizationCode>9546</AuthorizationCode>
   <AVSStreet>Pass</AVSStreet>
   <AVSZip>Pass</AVSZip>
   <CardSecurityCodeMatch>NotAvailable</CardSecurityCodeMatch>
   <MerchantAccountNumber>4269283011409218</MerchantAccountNumber>
   <ReconBatchID>420091009 1Q10144269283011409218AUTO04</ReconBatchID>
   <PaymentGroupingCode>4</PaymentGroupingCode>
   <PaymentStatus>Completed</PaymentStatus>
   <TxnAuthorizationTime>2009-10-09T17:14:19</TxnAuthorizationTime>
   <TxnAuthorizationStamp>1255108459</TxnAuthorizationStamp>
   <ClientTransID>q003ebd2</ClientTransID>
  </CustomerCreditCardChargeRs>
 </QBMSXMLMsgsRs>
</QBMSXML>
 

Additional QuickBooks QBMS Integration Information

PHP Hints: http://idnforums.intuit.com/messageview.aspx?catid=50&threadid=9487&highlight_key=y

More PHP Hints: http://idnforums.intuit.com/messageview.aspx?catid=3&threadid=7743&highlight_key=y&keyword1=php

General Setup Information: http://developer.intuit.com/qbms/support/?id=992