Intuit Merchant Services has made changes to their API that will most likely impact thousands if not tens of thousands of customers starting February 1st. Where most companies such as PayPal allow deprecated APIs to continue to work to maximize translation sales, Intuit no longer takes a backward compatibility approach to their API which could lead to the loss of millions of dollars for Intuit customers that rely on the stability of their API.
Starting February 1st, the API now requires 2 additional fields that indicate a true/false that the application making the charge is doing so for “eCommerce” as well as for “Mobile Devices”. Searching online showed no evidence that the new fields are required, and no other competitors require such fields. We can only assume the new fields are now required for someone mid-level at Intuit, perhaps to have questions answered. Currently APIs such as BrainTree’s (PayPal’s latest) does not have requirements to specify if the transaction is eCommerce or comes from a mobile device. We can assume the decision for this information to be mandatory was an internal one. Apparently the information is extremely important and is worth the loss in transactions by customers who do not implement the new fields.
Applications that do not specify a true/false value for the eCommerce or isMobile tags in the API calls will not be able to charge or refund customers. Intuit’s API is NOT backwards compatible,which means you must update your API in your application or after February 1st you will no longer be able to process credit cards.
Failure to effectively notify users of the severity of the problem
Intuit has not communicated the changes in a meaningful way. All notifications up to this point have been poorly titled or were secondary to the original messages being sent. Furthermore, all communication up to this point poorly highlighted the importance of the changes.
Intuit sent the first 3 email notifications of the API change via their “Intuit Developer News” newsletter. The first was sent on September 28, 2017. In the newsletter burred in the bottom in a section titled “timeline reminders”, developers could find the last time in the newsletter “February 1, 2018: Updates to the Payments API for QuickBooks Online are live.” which links to the following announcement made August 1, 2017: https://developer.intuit.com/hub/blog/2017/08/01/updates-payment-apis-quickbooks-online Additional notices were sent in the same way as the first, in the Intuit Developer News newsletters on October 27th and November 30th.
On January 10th, a new email was sent via mass-mailing titled “Updates to the Payments APIs for QuickBooks Online may affect your application”. The first real email to emphasize the problem to its clients, the title can still be easily ignored as many customers will assume that it does not apply to them. The email links to the following page which tries to explain the severity of the changes: It contains some links, the first to the announcement page posted on August 1, 2017, the second to Payments API Reference (https://developer.intuit.com/docs/api/payments/charges) and a third to QBMS (https://developer.intuit.com/docs/0100_quickbooks_payments/z_qbms_payments/0060_documentation/transaction_types#/Credit_Card_Charge). The Payments API Reference page, and navigating to immediate pages sadly shows no explanation for the new eCommerce or Mobile fields that are now required. The 3rd to the QBMS documentation shows an example XML with the 2 new tags but no where on the page does it explain the 2 new fields or that the order in which they are placed in the XML is important.
On January 12, 2018 they put a news announcement on the subject on their blog. For those customers of Intuit who just happen to visit the QuickBooks API news blog between now and February 1st will see the announcement “Updates to the Payments APIs for QuickBooks Online may affect your application”.
Poorly written documentation
There are two places where the changes are made, with the Payments API and with the QBMS (QuickBooks Merchant Services) API. Both are hard to navigate and do not have a way to find out information about fields in various requests. I could not find any details about “ecommerce and “mobile” under Payments API, and I could not find anything for IsMobile and IsECommerce within the QBMS API.
Backwards compatible claim
If you are not aware, XML has the ability to allow for backward compatibility. What this means is that a tag in XML can set a version number that you are following of an API, that way the service you are communicating with knows how to treat your parameters. If you build for version 1.0 and your API calls always reference that you are using 1.0, then the server will treat them as 1.0.
Intuit years ago recognized this and documented as such in their documentation, found on this page: https://developer.intuit.com/docs/0100_quickbooks_payments/z_qbms_payments/0060_documentation/sending_requests
Quickbooks XML API version 4.1 was set many years ago. It appears in this case, these 2 fields that are now required would trigger a new version number of 4.2, but upon scanning the API documentation I see no mention of the version number changing. This change goes against their documentation which stats taht changes would have a new version. This also means the claim in their documentation that the API is backwards compatible is not true.
This latest API change suggest the QuickBooks XML API is not backwards compatible and the version numbering in the XML most likely means nothing on the Intuit server side of the request.
Documentation is poor
It is not clear in the documentation which requests now need these 2 new fields or that the location of the fields in the QBMS XML is critical. Upon our initial testing, we simply added the XML at the end of the API calls and did them for all API calls. Doing so quickly made some calls fail. After experimenting we discovered they are only needed for API calls that also include an <Amount> tag. Also just as if not more importantly, they need to be before the <Amount> tag to work. No where can you find this information in the documentation. In one announcement blog post they had the capitalization (camel case for those developers who know what that is) wrong in their example (source), which means they more than likely did not test the changes themselves.
The documentation is sloppy, does not explain at all the fields that are required and what they mean let alone note which are optional and which are required.
They should know which customers are affected and contact them ASAP
The beautiful thing about client-server communication is that such communication can be monitored. It would be easy, if not already being done, to monitor and log every request to see which do not have the fields in question. It would then be easy for Intuit to send a report to each customer that says “X percent of your applications are not including the IsMobile tag, Y percent of your applications are not including the IsECommerce tag”. followed by an explanation why the fields are now required and the date the changes must be in place so that you do not loose sales. Intuit has this data, and they could take things a step further and have staff call their customers who are going to be affected to let them know about the API change. Unfortunately, they should be doing this 6 months ahead of the change, to give development environments enough time to make and test such changes without disrupting other development tasks already underway. That is not the case, instead they poorly announced the changes and only January 10th, 2018 have they sent an email specific to the issue to its customers, and even then it is apparent Intuit is not looking at the API calls to see how many of their customers will be affected by the change.
Intuit is making a grave mistake by disregarding their own promise to provide a backwards compatible API. This will cost them in transactions and more importantly, cost their customers sales as they scramble to deal with the change. I guarantee that within a few days Intuit will feel the impact with a lower than usual number of transactions since the 1st of February. The lower transactions will have to be justified by the required changes and we may find out within a few weeks that the changes did not justify the loss of transactions / sales.
I personally will not recommend using Intuit for credit card processing in the future, simple as that. This is incompetence.