Thursday, June 5, 2014

Developing a RESTful JSON web service integration for Dynamics GP - Part 1

By Steve Endow

I just finished a very interesting Dynamics GP integration.  It is a RESTful JSON web service that allows a web site to integrate with Dynamics GP,, and k-eCommerce / Azox Credit Card Extension.  Because it is a web service that will receive credit card data, it also includes HMAC authentication and AES encryption and runs over HTTPS.

As Fancy Nancy would say:  Très geek!

The customer uses an internal web site to record customer orders.  The web site collects the customer information, credit card information, and the products that the customer is purchasing.  In the past, the customer information was saved and then separately entered or imported into Dynamics GP.  Credit card transactions were processed through a payment gateway, and setup with recurring billing through the gateway.  All transactions were entered in GP after the fact.  The client wanted a real time integration between the web site and Dynamics GP so that the customer information is immediately saved to GP.

However, the customer did not want to store the credit card information in Dynamics GP or the Credit Card Extension module--even if it is encrypted.  They wanted to use "tokenization".  This involves sending the credit card information to the payment gateway (in this case, and receiving a unique ID, or "token" that can later be used to process credit card transactions.  Once the token was received, it would be stored in the Credit Card Extension module so that future credit card transactions could be performed from within Dynamics GP.

So why RESTful?  Well, the customer's web site was developed using PHP on Linux.  That pretty much ruled out direct APIs such as COM and .NET libraries.  SOAP would have required the client's developers do more work, so we went with REST, which they were familiar with, and REST is pretty simple and would work well for this relatively straightforward integration.

Why JSON?  The customer's web developers were used to JSON-based web services, so that was much easier than trying to implement a SOAP based web service or anything that involved XML.  Neither the client's web developer nor I like XML, so I was open to trying JSON.

So with those architectural choices made, we had a few implementation details to work out.  How would we authenticate calls to the web service?  The client's developer recommended HMAC--something that I had, sadly, never heard of before.  HMAC is a very clever and simple authentication method where you hash the contents of a request combined with a secret shared key.  The resulting hash produces a unique "password" of sorts that is effectively impossible for someone else to forge.  When the web service receives the request and the HMAC value, it performs the same hash on the request data, with the same secret key.  If the resulting value matches the HMAC value submitted by the caller, the request is considered valid.  We chose to use SHA-256 for our hashing algorithm.

Next was the credit card data.  Even though the web service would use SSL and only accept HTTPS requests, we still did not want to transmit the credit card data as plain text.  We decided to encrypt the credit card info using AES-128.  We thought that would be pretty straightforward, but it ended up being more difficult than we expected.  One challenge was figuring out how to choose an "initialization vector" (IV), and a second challenge was learning how AES is implemented in PHP vs. .NET--it took us a while to figure out that there are different default settings for PHP encryption, so we had to dig pretty deep and spend several hours researching every one of the encryption settings.  We finally figured out that PHP uses NULL padding by default, where as my encryption library uses PKCS7 padding by default.  Got that?  Easy peasy lemon squeezee!  (okay, so it is not obvious at all)

In the next several posts on this topic, I'll explore each of the elements of the project in more detail.

Steve Endow is a Microsoft MVP for Dynamics GP and a Dynamics GP Certified IT Professional in Los Angeles.  He is the owner of Precipio Services, which provides Dynamics GP integrations, customizations, and automation solutions.

You can also find him on Google+ and Twitter


Unknown said...

I'm going right now through the same project using mean full stack application (pure javascript) and I would like to develop restful json web services to push data and pull data to the GP. If you could please please explain me what is the best approach to follow or if you have any samples of the restful json web services will be really helpful and great.


Steve Endow said...

Hi Mahmoud,

I used a .NET MVC template to develop the web app, so I don't have any pointers for JavaScript.

Using .NET, I was able to utilize GP eConnect through the eConnect .NET assemblies, and then call SQL directly for queries and custom data access operations that aren't supported by eConnect. If there is a good way for JavaScript to call .NET assemblies, I would recommend using the eConnect assemblies, as they make things very easy.

Alternately, if you are using GP 2010 or higher, you could try using GP Web Services, but it is SOAP based, so I am not a fan and don't recommend it.

If you are using GP 2015 or 2016 and are using the GP web client, you could theoretically use the new Service Based Architecture, but it has some drawbacks, like the large amount of server infrastructure it requires.

Regardless of the integration method you choose, you will need to have (or develop) a pretty good understanding of GP in order to develop an integration.


Unknown said...

Hi steve,
Thank you for your quick answer and your explanation, I have a good understanding of GP and I do a lot with back end to troubleshoot all issues related to the integration. In case please you have some samples how to use GP eConnect through the eConnect .NET assemblies, it will be really great and helpful to a newbie like me. My email address is

Thanks a lot

Unknown said...

Hi Steve,
Thanks for the quick response and the good explanation. Do you have any samples please for how to use GP eConnect through the eConnect .NET assemblies? I'm struggling a little bit because I'm a newbie. my e-mail address is