This is an old revision of the document!


QuickBooks Merchant Service Integration

Getting Started

Getting started with the 'Desktop' communication model

  • You will be provided with an application login and connection ticket which you'll use in your QBMS XML posts.

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.

For production applications, visit this page in a web browser: https://merchantaccount.quickbooks.com/j/sdkconnection?appid=YOUR-APPLICATION-ID-HERE&appdata=mydata

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.

  • 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); ?>)
  • 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
  • Finish going through the application registration process, saving the stuff it spits back at you.
  • 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-----

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:

For production applications, visit this page in a web browser: https://merchantaccount.quickbooks.com/j/sdkconnection?appid=YOUR-APPLICATION-ID-HERE&appdata=mydata

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:

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

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

Example QBMS XML Requests and Responses

Sample Code

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

quickbooks_qbms_integration.1310477682.txt.gz · Last modified: 2013/01/21 12:44 (external edit)