Introduction
Semi-integrated techniques have provided many opportunities for software developers to directly, and without using any third-party middleware or gateway, integrate their software to credit card processing terminals and pinpads. This article is an introduction to piconnect.dll, a library for semi-integration to PAX terminals such as the PAX S300, D210, etc.
Background
Since October 2015, what is known as the liability shift, forced all merchants who accept and process credit cards to accept chip cards or be responsible for chargebacks and fraudulent charges. This naturally puts a lot of stress on point of sale software developers to add chip card processing capabilities to their software
Several device manufacturers, including PAX, introduced semi-integration. In a semi-integrated solution, you integrate to a device, which in turn is fully integrated and certified with one or more major credit card processors, such as First Data, Global, Heartland, Vantiv, TSYS, etc.
PIConnect DLL by PI Technologies is a DLL for semi-integration into PAX. This is a small and very fast dll written in C#, which supports every major transaction type, such as Credit Sale, Credit Auth, Credit Adjust, Credit Return, Debit Sale, Debit Return and EBT transactions.
Using the PIConnect DLL reduces your development time from weeks to minutes.
Using the code
This DLL is now available on NuGet.
You can use 1502122693 as your temporary developer account to start the development immediately.
You can start by using a free developer account number from PI Technologies.
Reference to piconnect.dll in your software
In Visual Studio, expand your project and right click on the References, then select "Manage NuGet Packages". On Nuget, go to the Browse tab and search for piconnect.
Create instances of PiPay() and DeviceSettings() classes.
- PiPay myClass = new PiPay();
- DeviceSettings myDevice = new DeviceSettings();
- DeviceSettings() class prepares your PAX teminal: myDevice.DeviceIp = ip;
- myDevice.PortNo = paxPort;
- myDevice.Timeout = paxTimeout;
- myDevice.DeviceSn = sn;
- myDevice.AccNumber = Account;
You could use a .ini file to store the device info, or if you are going to have a database, simply store this information in a table.
Perform a CreditSale() transaction
Most common transaction type is CreditSale().
- PiPay myClass = new PiPay();
- PaymentResponse myResp = new PaymentResponse();
- DeviceSettings myDevice = new DeviceSettings();
- myResp = myClass.CreditSale(amount, ticket);
- jsonData = JsonConvert.SerializeObject(myResp);
CreditSale() method, requires an amount and a ticket number only.
As you can see we have introduced an instance of PaymentResponse() . This class has all the returned fields,
- TransactionID
- TicketID
- TransType
- Timestamp
- ResponseMsg
- ResponseCode
- RefNum
- CardHolder
- HostResponse
- HostCode
- CardType
- AccountNum
- ApprovedAmount
- AmountDue
- TipAmount
- AuthCod
- CVM
- SerialNo
- EntryMode
- TransactionResult
- UniqueId
- Toke
- ExpirationDate
In addition to these fields, you will also receive several fields related to EMV.
If you use JSON.NET you can easily serialize the myResp object into a JSON object.
Acceptable transaction types are listed below,
- creditsale,
- creditvoid,
- creditreturn,
- creditauth,
- creditcapture,
- creditadjust,
- debitsale,
- debitvoid,
- debitreturn,
- closebatch,
- closeallbatches,
- clearbatch,
- initialize,
- quickread,
- transactiondetails,
- failedtransactions,
- totaltransactions,
- lastbatch,
- forcebatchclose,
- ebtsale,
- ebtreturn
Other Object Classes
PIConnect contains the following object classes,
- BatchManage()
- BatchResponse()
- DetailReportResponse()
- DeviceInit()
- DeviceSettings()
- PaymentResponse()
- FailedReportResponse()
- LastBatchReport()
- ReadResponse()
- ReportResponse()
- SaResponse()
- ShowMessageResponse()
- CloseBatch()
At the end of each business day, merchants close their credit card transactions batch. Batch closing process could be automated or manual. The following example shows how to close a batch,
- PiPay myClass = new PiPay();
- BatchResponse myResp = new BatchResponse();
- DeviceSettings myDevice = new DeviceSettings();
- myDevice.DeviceIp = ip;
- myDevice.PortNo = paxPort;
- myDevice.Timeout = paxTimeout;
- myDevice.DeviceSn = sn;
- myDevice.AccNumber = piAccount;
- myClass.DeviceSetting = myDevice;
- myResp = myClass.CloseBatch();
- jsonData = JsonConvert.SerializeObject(myResp);
Tokenization
I did not want to close this article without talking about tokenization. Tokenization is a method in which your credit card processor converts sensititive credit card information into an encrypted token and you can use this token to perform a CreditSale() or CreditReturn(). Since piconnect.dll always returns a token (when your device has tokenization enabled) after CreditSale() transactions, you can perform subsequent tokenized CreditSale() transactions without access to the actual card number.
Look at the following CreditSale() with a token,
- PiPay myClass = new PiPay();
- PaymentResponse myResp = new PaymentResponse();
- DeviceSettings myDevice = new DeviceSettings();
- myResp = myClass.CreditSale(amount, ticket, token, expdate, cardtype);
- jsonData = JsonConvert.SerializeObject(myResp);
Additional fields to be sent are the Token, Expiration date and Card type. All these fields are available to you after you perfom a CreditSale(). Future CreditSale() calls could just use the token and card is not required.
After experiencing integration with the DLL provided by the manufacturer, it became clear that there must be a better and faster way. The PIConnect DLL is built from the ground up and has no dependencies on the manufacturers' libraries.