¶ Introduction
Using the VeriFone Chip Readers offers a highly secure method of collecting cardholder data.
Cardholder data Is encrypted within the device itself, and remains encrypted as it travels across the internet to our PCI Level One Compliant processing platform. When a merchant supports this type of reader, they also help with eliminating charge backs for transactions which were run through the device.
¶ PCI SSC Software Security Framework (SSF)
Software Security Framework is a re-working of the existing PCI standard PA DSS. The PA DSS is going to be retired on June 30, 2021
Note: Easy Pay's "Aspen 3.1" is the first application to achieve the PCI Councils newest certification, SSF. The use of the "Aspen 3.1" software by an integrator or merchant provides an End-to-End Encrypted (E2EE) solution! LINK
¶ Architecture
The Verifone card readers are small hand-held devices, and they communicate with your computer on a USB port. A typical chip transaction is comprised of about a dozen transmissions back and forth between host (your computer) and device (VeriFone Device) and then finally off to the Easy Pay cloud platform.
¶ What We Offer
Currently we offer four different options for collecting payments with the Verifone card readers (Windows OS Only):
¶ 1) Standalone Desktop Application (Upon Request Only)
This application does the following:
- Collect Payments
- Create Card-on-File (Annual Consent)
- Create Card-on-File Payment Plans (Fixed Recurring Consent)
- Process Card-on-File
- Void / Credit (Refund)
- Settlements
- Reporting (with export to PDF)
¶ 2) Easy Pay Verifone SDK
This is simply a DLL written in C# MANAGED code and it provides a means of collecting payments and creating Card-on-File plans. Used in conjunction with our API, you can basically manage all aspects of your payment requirements, and all within the confines of your own custom application.
¶ 3) Browser based Interface
In order to interface with browser content Easy Pay has developed a windows service which uses Cross-Origin Resource Sharing (CORS) to communicate with the browser (EDGE, Mozilla, Chrome). This allows our Integrators to write simple client-side script within THEIR OWN web applications which will initiate transactions with the local Verifone. A very simple HTML site can be downloaded HERE which will show exactly how you can interact with our VeriFone from your own web applications. No cardholder data is transferred to the Integrator site as it is END to END encryption between the Verifone, Win Service, and EasyPay Cloud Servers. The Win service will return a simple XML response for each transaction directly to the HTML/PHP/ASP.NET page for consumption by the Host application.
¶ 4) Virtual Terminal
Our EasyPay Virtual Terminal has built in support for Verifone. One would need to install the middleware service and ask for this feature to be activated. You can download the Windows service HERE
There are 2 categories of integrations which require two different sets of files
- Browser Based Integrations (Install our Win Service which contains all your dependencies including the drivers and console installer)
- Desktop Based Integrations (Install Our SDK) (Here you will need a separate install for the Drivers and custom event Log installer)
Regardless of your integration it is recommended to adjust your Power plan settings to ensure your USB port does not suspend or sleep
¶ Easy Pay Verifone SDK
For you to DIRECTLY interface with the VeriFone using our SDK, you will need two components.
The following files are included in the SDK. You only need to interface directly to the file named EP.Enterprise.Vx820.dll. The other 3 files are dependencies.
The first component, when installed correctly will provide USB drivers and create a Virtual COM 9 port. In addition, it will add a unique EVENT LOG to the existing windows Event Log collection. To install THE FIRST COMPONENT please do the following:
- Connect your Verifone to the USB port which you plan to utilize.
- Wait until the device is fully initialized.
- Download and extract the ZIP file named Setup_USB_log.zip to the location of your choice.
- Right click the EXE named Setup_USB_log.exe and choose RUN AS ADMINISTRATOR
- Once the installation is complete you can verify the new windows event log named EPMIDDLEWARE
¶ Browser based Installation
To install our Win Service please download the ZIP file HERE.
- Connect your device to free USB port
- Allow device to initialize
- Extract the above archive to location of your choice
- Locate the EXE file (application)
- Right Click on EXE
- Run As Admin (important)
- Wait for application to finish then Reboot computer
The above install package does the following
- Installs USB drivers for the Verifone
- Creates a Custom Event Log with windows named EPmiddleware
- Installs a Certificate which encrypts data between the browser and the Windows service
- Install the windows service which listens on Port 8031
Your website can now issue commands to the Win Service as is demonstrated using the sample site:
You can download the entire site here
¶ Virtual Terminal
Our EasyPay Virtual Terminal has built in support for Verifone. One would need to install the service and ask for this feature to be activated.
¶ Custom Windows Event Log
Once the installation program has completed you will notice a new Windows Event Log has been registered named EPmiddleWare. This log is relevant for both SDK and Browser based Middleware.
The Custom Windows Event Log stores relevant information while it processes transactions as well as any errors encountered. This becomes a powerful troubleshooting component should the merchant have any problems. They would simply export the log and send it to Easy Pay if any unexpected behavior is encountered.
¶ Verifone Optimum Power Settings
It is important to note that the middleware service ( or SDK ) , once started, will attempt to maintain a continuous connection to the Verifone device. If your hardware goes into suspending or sleep mode, this can cause issues and prevent seamless operation. To avoid these issues please make sure to modify your USB Power settings as follows:
¶ Windows 10
¶ Windows 11
IMPORTANT: If you dont see USB power settings on your machine then you need to expose them as follows:
Run a Command Prompt (RUN AS ADMINISTRATOR)
Type the command below you into the elevated command prompt, and press Enter.
REG ADD HKLM\SYSTEM\CurrentControlSet\Control\Power\PowerSettings\2a737441-1930-4402-8d77-b2bebba308a3\48e6b7a6-50f5-4782-a5d4-53bb8f07e226 /v Attributes /t REG_DWORD /d 2 /f
After running command, reboot your computer and then reopen your advanced power settings following the steps listed above.
¶ End-To-End Encryption
¶ EasyPay Verifone Middleware Response Object
For browser type Verifone operations the middleware provides a Response object in XML format. This Object can be De-Serialized and cast into a Type Safe Object or can be consumed as XML. Currently there are two response object types:
- WidgetArgs- Sale Response when requesting authorization for a non-zero dollar amount ( Save Card Optional )
- WidgetArgs2- Consent Response when requesting to Save the Card ONLY
¶ SaleResponse ( WidgetArgs )
FIGURE 1. Sale Response Return Object ( Sale Only Response )
When requesting a Verifone Operation such as Purchase/Sale you have the option of also requesting that EasyPay Save the Card. In this case we will return a Token which you can use to charge the Card at a future time. We refer to any Saved Card as a Consent since you must get the cardholders permission to save their Cardholder information. Looking at the Object in Figure 1 you will see an Object named ConsentResult which contains relevant information concerning this optional Request to SAVE THE CARD. You will notice in FIGURE 2 that the response object indicates that a request was made to Save the card and the Unique ID for that Saved card info is 7849. The Card number ends in 2741 and the ExpDate of that Card is 05/28. You will save this data so that you can present this info to the cardholder should they decide to use this saved Card info in the future.
FIGURE 2. Sale Response Return Object ( Sale and Save Card Response )
Figure 3 shows an example on how to call the middleware to do the following:
- Chip Sale Only
- Chip Sale and Save Card
- Keyed Entry Sale Only
- Keyed Entry and Save Card
FIGURE 3. Requesting a Verifone transaction with options to Save Card
¶ Consuming the Response
It is important to consume the response in a Particular Order. The First item to examine should be the following:
TxEventType: This String Member will have one of the following Values:
{ TimeOut, Exception, PreSaleDeviceCode, PostSaleDeviceCode, AspenError, AuthFail, TxDecline, TxApproved, TxReversed, FunctionFail };
Here are the actions to take for each possible value returned:
TxApproved: The sale was approved by the issuer. You should examine and store the following values:
<TxID> This is the Unique ID of the transaction. This will be needed for refund or Void operations
<TxnCode> This is the Approval Code.
<ApprovedAmt> The amount charged to the Card.
TxDecline: The sale was declined by the issuer. You should examine and store the following values:
<TxID> This is the Unique ID of the declined transaction.
<TxnCode> This is the Decline Code. Browse the developer site to see a list of codes.
TxReversed: Occasionally the Issuer may approve a Transaction however during the final interaction with the CHIP, the device may require the transaction be declined. In this case the transaction will get Reversed. This will cause you to see a VOIDED transaction in your EasyPay Database.
PreSaleDeviceCode: An error occurred within the device prior to the transaction getting submitted to the Issuer. You can monitor the following for more info
<ErrCode> This is an Error Code
<ErrMsg> This is an Error Message
PostSaleDeviceCode: An error occurred within the device after the transaction was submitted to the Issuer. You can monitor the following for more info
<ErrCode> This is an Error Code
<ErrMsg> This is an Error Message
Timeout: The user waited too long to insert the card or interact with the device workflow. You can monitor the following for more info
<ErrCode> This is an Error Code
<ErrMsg> This is an Error Message
AspenError: An error occurred on the EasyPay Aspen Cloud Processing servers. You can monitor the following for more info
<ErrCode> This is an Error Code
<ErrMsg> This is an Error Message
AuthFail: This relates only when you are doping a SAVE CARD ONLY Operation. In this case we execute a CARD VERIFY (or Zero dollar Authorization) prior to saving the Card On File. If the Issuer declines to Verify the Card details, then you will see this Value returned and the Card will Not be saved. You may retrieve the TxID and decline code.
<TxID> This is the Unique ID of the declined transaction. This is needed for refund or Void operations
<TxnCode> This is the Decline Code.
FunctionFail: This can be returned when you supply improper or out of range values in your request. In addition , if you execute a Verifone command or Method while the previous action has not yet completed the device will return this Type. Please monitor the following.
<ErrCode> This is an Error Code
<ErrMsg> This is an Error Message
Exception: This indicates an error ( or exception ) was encountered in the local Windows Service. Please monitor the following.
<ErrCode> This is an Error Code
<ErrMsg> This is an Error Message
Below are the remainder of the member variables which are returned when Requesting a Sale from the middleware:
IsPartialApproval
True or False depending on whether the authorization was partially approved
ApprovedAmt
This is the amount of your authorization , This may be different if Surcharging is enabled or a partial Authorization was returned ( prepaid cards only )
RespMsg
This is a friendly message which reflects the status of a transaction
TxID
This is the Unique Transaction ID for either an approval or a decline
TxnCode
This is either an Approval Code or a Decline Code depending on the TxEventType
ErrCode
If TxEnentType is anything OTHER than TxApproved or TxDecline then your transaction was not processed due to some problem. You will log the ErrCode and ErrMsg in this case.
ErrMsg
If TxEnentType is anything OTHER than TxApproved or TxDecline then your transaction was not processed due to some problem. You will log the ErrCode and ErrMsg in this case.
In the case where you have requested to save the card at the time of the purchase you will want to monitor the inner object named ConsentResult
<ConsentResult>
<ConsentCreated>true</ConsentCreated> A Consent (Card on File) was successfully Created
<ConsentRequested>true</ConsentRequested> A Consent (Card on File) was Requested
<ErrMsg /> Error Message if relevant
<ErrCode>0</ErrCode> Error Code if relevant
<ConsentID>7849</ConsentID> This is the Unique ID of the Saved Card which is required when authorizing a Sale
<CardLast4>2741</CardLast4> Last 4 Digits of the Card (show this to the user when using the stored Card)
<ExpDate>0528</ExpDate> Expiration Date of the Card (show this to the user when using the stored Card)
</ConsentResult>
¶ ConsentResponse ( WidgetArgs2 ) ( For EMV Save Card Only )
FIGURE 4. Consent Response Return Object ( Save Card Response )
FIGURE 5 Requesting a Verifone transaction to Save Card Only
¶ Consuming the Response
It is important to consume the response in a Particular Order. The First item to examine should be the following ConsentEventType: This String Member will have one of the following Values
{ TimeOut, Exception, PreConDeviceCode, PostConDeviceCode, AspenError, AuthFail, ConsentFailed, ConsentSuccess, FunctionFail };
Here are the actions to take for each possible value returned:
ConsentSuccess: The Consent was created and Card was Saved Successfully. You should examine and store the following values:
This is the Unique ID of the Consent (Card On File). This is needed for charging the customer later.
ConsentFailed: The Consent was Not created for any particular reason. You should examine and store the following values:
This is an Error Code
This is an Error Message
PreConDeviceCode: An error occurred within the device prior to the Card being submitted. You can monitor the following for more info
This is an Error Code
This is an Error Message
PostConDeviceCode: An error occurred within the device after the Data was submitted. You can monitor the following for more info
This is an Error Code
This is an Error Message
Timeout: The user waited too long to insert the card or interact with the device workflow. You can monitor the following for more info
This is an Error Code
This is an Error Message
Exception: This indicates an error ( or exception ) was encountered in the local Windows Service. Please monitor the following.
This is an Error Code
This is an Error Message
AspenError: An error occurred on the EasyPay Aspen Cloud Processing servers. You can monitor the following for more info
This is an Error Code
This is an Error Message
AuthFail: In this case we execute a CARD VERIFY (or Zero dollar Authorization) prior to saving the Card On File. If the Issuer declines to Verify the Card details, then you will see this Value returned and the Card will Not be saved. You may retrieve the TxID and decline code.
This is the Unique ID of the declined transaction. This is needed for refund or Void operations
This is the Decline Code.
FunctionFail: This can be returned when you supply improper or out of range values in your request. In addition , if you execute a Verifone command or Method while the previous action has not yet completed the device will return this Type. Please monitor the following.
This is an Error Code
This is an Error Message
Below are the remainder of the member variables which are returned when Requesting to Save a Card Only without a purchase:
AuthSuccess
When we save a card, ( depending on account settings ) we first authorize the card for zero dollars to ensure it is in good standing. This flag denotes success in validating the card.
AuthMsg
Message returned after authorizing card for Zero dollars
RespMsg
Overall Operation response. If Card was successfully saved, the message will reflect this
ConsentID
This is the Unique ID needed to charge the saved card later using the API
AuthTxID
If the card was authorized for zero dollars this will be the ID of the authorization
ErrCode
If ConsentEventType is NOT ConsentSuccess you can log the ErrCode and ErrMsg
ErrMsg
If ConsentEventType is NOT ConsentSuccess you can log the ErrCode and ErrMsg
RecurSched
This is only for recurring payment schedules (Not used for this implementation )
¶ Resetting The Device
The red button on the Verifone can be used to cancel the current operation and set up for a READY state in most cases.
Two software commands of Interest are RESET and UNLOCK
FIGURE 6 Reset and Unlock
The ResetVerifone operation will send a RESET command to the Verifone Device. This can be used to put the device back into its Ready State. The UnlockVerifone command on the other hand releases the middleware from its current wait state or workflow position and also sends a RESET command to the device . If for any reason you continue to receive a Busy Response from the Middleware, but you don’t feel that waiting is productive then use the UnlockVerifone feature to return the software and Device to the READY State.