One of the common tasks when delivering POS solutions to customers is to prepare POS application for card payments. Although there is some support for payment cards in Dynamics AX 2012, it does not fit well with the requirements that most European retailers would put on it. Thus, custom development is inevitable. In this post, I give some guidelines on how to integrate the payment terminals with Dynamics AX 2012 Retail POS. Namely, we successfully integrated Global Payment Europe (GPE) payment terminals with Enterprise POS (Windows Forms version of POS) for Microsoft Dynamics AX 2012 R3 (CU10). However, I believe that the text contains valuable information for other versions of Dynamics AX POS as well, be it Modern POS or Cloud POS in Dynamics AX 2012, Dynamics AX (7) or Dynamics 365 for Operations.
This blog post is for reader who has already some experience with Dynamics AX 2012 enterprise POS development more information is below.
I suppose that the reader has already some experience with Dynamics AX 2012 enterprise POS development. For introductory information, see Extend Point of Sale section at technet. There are also good posts by Erstad Shane or you can have a look at my previous post for a complete POS development scenario.
As already mentioned, standard AX has a support for payment cards. This includes not only AX backend but also POS clients. So, what’s the trouble? The answer lies in the payment process. From the POS point of view, it consists of the following steps:
Payment process in standard AX
However, for security reasons, payment terminal providers implement another approach, which is not supported in AX:
Required payment process
From the above we can see that a development is needed in two areas:
Development of payment terminal communication library is far beyond the scope of this post. For your imagination – the whole Visual Studio solution contains over 30 files putting it together to more than 3500 source code lines in C#. Therefore, I will give only some basic ideas how to proceed.
First, it is important to find out what does the communication protocol between POS and payment terminal look like. To this end you must contact your payment terminal vendor and get a technical documentation. The communication protocol will most probably consist of two layers – application protocol and transport technology. In my case (GPE), the technology has two variants – you can either communicate over TCP/IP network or by USB serial port. Our customer opted for TCP/IP transfer but the use of USB would not be much different – mainly since the application protocol defined by GPE is the same in both cases.
At high level, the GPE application protocol defines several operations. Here I will concentrate on the bare minimum – the operation “Make payment” that takes in amount, currency code and optionally invoice (receipt) identification as input parameters and then performs the card payment itself. GPE defines few more operations – return, cancel the last operation, perform payment terminal closing etc. – but it would only distract us from the main ideas that are the same regardless of the operation.
Now invoking the make payment operation consists of assembling data payloads correctly and sending them to the payment terminal over TCP/IP or USB. As for the transport part, .NET framework does the most of the job by offering TcpClient and SerialPort classes, respectively. Thus, our main concern is the assembly of the data payloads according to the rules defined in the payment terminal’s documentation. However, there is much more to that – exception handling, asynchronous programming, recovery after operation cancellation and others. This is quite a lot of work to do. Fortunately, in Dynamics AX Retail SDK there are samples where to learn from.
HardwareStation Visual Studio solution contains sample implementation for the Verifone Mx925 payment terminal
Namely, there is a HardwareStation Visual Studio solution that contains sample implementation for the Verifone Mx925 payment terminal. Having had a look at it it turned out that there are many analogies between GPE and Mx925 payment terminals and that a lot of source code for GPE solution can be easily adopted from existing classes. Therefore, let’s delve into the internal structure of the HardwareStation solution a little bit.
The whole solution consists of three projects:
The Application project is an ASP.NET web application. Of main interest for us is the PaymentTerminalController class (in Controllers/PaymentTerminalController.cs). It is an entry point for any operations provided by payment terminals. For our needs, I refactored this class so that it is not bound to ASP.NET. In other words – my PaymentTerminalController class does not extend the ApiController class and its public methods are not decorated by HttpPost attributes.
Next object to look at is the PaymentTerminalManager class in PaymentTerminal / PaymentTerminalManager.cs of the Peripherals project. It just represents an additional level of indirection between PaymentTerminalController and IPaymentDevice interface implementation.
The IPaymentDevice interface defines payment terminal device’s capabilities. Different payment terminals differ by implementing classes – VerifonePaymentDevice in HardwareStation solution or GPEPaymentDevice in my case. Inside VerifonePaymentDevice class you will note the extensive use of the protocol member variable of type IDeviceProtocol, the implementation of which is in the VerifoneDeviceProtocol class. It is exactly the place where the application protocol is defined (in fact it uses several other helper classes to this aim – ProtocolCommands, ProtocolConstants and ProtocolUtilities) and thus where my largest effort was given during GPE payment terminals implementation.
Finally, classes in the PaymentTerminal / Mx925Device / Transport folder contain transport protocol specific logic (e.g. IP address and port number value substitution). This can be seen in TcpTransport class.
Sticking to the HardwareStation internal architecture has one potential advantage – porting to the Modern POS or Cloud POS should be much easier – it suffices to change the PaymentTerminalController class.
Now it is time to connect POS to the .NET assembly and change payment process at POS side. This consists of several steps:
Card payments are a must for each POS implementation. I hope that after reading this post a reader will have an idea of what the payment terminal integration into Dynamics AX Retail POS involves and what skills are needed for its successful implementation.