Updates to the Payments APIs for QuickBooks Online may affect your application

What is happening?

On August 1, 2017, we announced changes to the QuickBooks Online Payments API and QuickBooks Merchant Services Payments API.

With these changes, beginning February 1, 2018, the QuickBooks Online Payments API and QuickBooks Merchant Services Payments API will require that the ecommerce and mobile indicators for all purchases made from a handheld device (smartphone or tablet) to be set within the application. This will affect any purchase whether the card number is keyed in, swiped, or fetched from a pass-through digital wallet like Apple Pay or a staged digital wallet like PayPal/Google Wallet.

Which entities are impacted?

• QuickBooks Online Payments API – Charge create and Charge Capture entities.
  The updated fields are described under the context field in the Payments API Reference.  

• QuickBooks Merchant Services – CreditCardCharge request.
  The updated fields are described here.

How does this affect you?

• QuickBooks Online Payments: In the charge create and capture API request, the isEcommerce and mobile indicators were previously optional. Beginning February 1, 2018, these indicators must be set within the API or your transaction will fail.
• QuickBooks Merchant Services: The IsECommerce and IsMobile indicators are new fields within the charge and payments APIs. Beginning February 1, 2018, these indicators must be set within the API or your transaction will fail.

What do you need to do?

For QuickBooks Online Payments API, start passing mobile and isEcommerce fields within the context field of the payload, refer to the sample below-

Sample Charge Request Before:

{

 “amount”: “10.55”,

 “card”: {

   “expYear”: “2020”,

   “expMonth”: “02”,

   “address”: {

     “region”: “CA”,

     “postalCode”: “94086”,

     “streetAddress”: “1130 Kifer Rd”,

     “country”: “US”,

     “city”: “Sunnyvale”

   },

   “name”: “emulate=0”,

   “cvc”: “123”,

   “number”: “4111111111111111”

 },

 “currency”: “USD”

}

Sample Charge Request After:

{

 “amount”: “10.55”,

 “card”: {

   “expYear”: “2020”,

   “expMonth”: “02”,

   “address”: {

     “region”: “CA”,

     “postalCode”: “94086”,

     “streetAddress”: “1130 Kifer Rd”,

     “country”: “US”,

     “city”: “Sunnyvale”

   },

   “name”: “emulate=0”,

   “cvc”: “123”,

   “number”: “4111111111111111”

 },

 “currency”: “USD”,

 “context”: {

“mobile”: “false”,

“isEcommerce”: “true”

}

}

For QBMS, start passing IsMobile and IsECommerce tags within the request xml, refer to the sample below-

Sample Charge Request Before:

<?xml version=”1.0″ encoding=”UTF-8″?>

<?qbmsxml version=”4.5″?>

<QBMSXML>

  <SignonMsgsRq>

     <SignonDesktopRq>

        <ClientDateTime>2017-12-17T14:57:00</ClientDateTime>

        <ApplicationLogin>XXXXXX</ApplicationLogin>

        <ConnectionTicket>XXXXXXXX</ConnectionTicket>

    </SignonDesktopRq>

  </SignonMsgsRq>

  <QBMSXMLMsgsRq>

     <CustomerCreditCardChargeRq>

        <TransRequestID>XXXXXXXXXX</TransRequestID>

        <CreditCardNumber>4111111111111111</CreditCardNumber>

        <ExpirationMonth>1</ExpirationMonth>

        <ExpirationYear>2018</ExpirationYear>

        <Amount>21.21</Amount>

     </CustomerCreditCardChargeRq>

  </QBMSXMLMsgsRq>

</QBMSXML>

Sample Charge Request After:

<?xml version=”1.0″ encoding=”UTF-8″?>

<?qbmsxml version=”4.5″?>

<QBMSXML>

  <SignonMsgsRq>

     <SignonDesktopRq>

        <ClientDateTime>2017-12-17T14:57:00</ClientDateTime>

        <ApplicationLogin>XXXXXX</ApplicationLogin>

        <ConnectionTicket>XXXXXXXX</ConnectionTicket>

    </SignonDesktopRq>

  </SignonMsgsRq>

  <QBMSXMLMsgsRq>

     <CustomerCreditCardChargeRq>

        <TransRequestID>XXXXXXXXXX</TransRequestID>

        <CreditCardNumber>4111111111111111</CreditCardNumber>

        <ExpirationMonth>1</ExpirationMonth>

        <ExpirationYear>2018</ExpirationYear>

        <IsECommerce>true</IsECommerce>

        <IsMobile>false</IsMobile>

        <Amount>21.21</Amount>

     </CustomerCreditCardChargeRq>

  </QBMSXMLMsgsRq>

</QBMSXML>

Addition Samples available in our github:

• .Net
• Java
• Python

How can I test this?

We have enabled these changes in the sandbox environment for you to test. Please go to the Intuit Developer sandbox and be sure the ecommerce and mobile indicator flag is set if transactions come in from handheld devices. You will need to activate this in your production application prior to February 1, 2018. For a full explanation of the changes, please review the documentation.

Any other questions?

Please contact us with any questions or concerns.

Thanks!
Intuit Developer