ETIM 2 00i User's Manual
ETIM 2 00i User's Manual
ETIM 2 00i User's Manual
MANAGER (ETIM)
USERS MANUAL
V E R S I O N 2 . 0 0 . 0 0 . 4 6 A N D H I G HE R
OCTOBER 18, 2013
Notice
VeriFone, the VeriFone logo, PAYware PC, PAYware SIM, PAYware Transact, PAYware Mobile, PAYware
Connect, and PCCharge and are registered trademarks of VeriFone. Other brand names or trademarks
associated with VeriFone products and services are trademarks of VeriFone, Inc. All other brand names
and trademarks appearing in this manual are the property of their respective holders.
NO WARRANTY
VeriFone has attempted to ensure the accuracy of the contents of this Program Guide. However, this
Program Guide may contain errors or omissions. This Program Guide is supplied as-is, without any
warranty of any kind, either expressed or implied, including the implied warranties of merchantability
and fitness for a particular purpose.
LIMITED LIABILITY
In no event shall VeriFone be liable for any indirect, special, incidental, or consequential damages,
including without limitation damages for loss of business, profits, or the like, even if VeriFone or its
representatives have been advised of the possibility of such damages.
Mailing Address
VeriFone, Inc.
8001 Chatham Center Drive
Suite 500
Savannah, GA 31405
Telephone
Savannah Sales Office: (800) 725-9264
Savannah Office Fax: (912) 527-4533
Web Site
www.verifone.com
Advanced Product Support
Advanced Product Support is available to those developers who will integrate their application with
Enterprise Terminal Interface Manager and implement that stand-alone product as an in-house
transaction processing solution.
(888) 764-1764
APSupport@verifone.com
VeriFone Integration Support
VeriFone Integration Support is available to those developers who will integrate their application with
PAYware Connect and implement that stand-alone product as an in-house transaction processing
solution.
DevSupport@verifone.com
(877) 659-8983
Revision History
Revision
Date
Author
Revision Description
1.00a
08-19-2011
Shawn_P2
New document
1.00b
03-23-2012
Shawn_P2
2.00a
06-27-2012
Shawn_P2
2.00b
08-02-2012
Shawn_P2
2.00c
09-27-2012
Shawn_P2
2.00d
10-05-2012
Shawn_P2
2.00e
03-25-2013
Shawn_P2
2.00f
04-15-2013
Shawn_P2
2.00g
07-26-2013
Shawn_P2
2.00h
08-09-2013
Shawn_P2
Revision
Date
Author
Revision Description
2.00i
10-18-2013
Shawn_p2
Table of Contents
Notice ................................................................................................. 2
Revision History ..................................................................................... 3
Welcome .............................................................................................. 7
eTIM Overview ........................................................................................................ 7
Reference Documents .......................................................................................... 8
23
23
23
30
31
31
32
39
40
40
43
49
52
54
56
73
74
78
80
82
Welcome
Congratulations on your selection of VeriFones Enterprise Terminal Interface Manager (eTIM)!
VeriFone is one of the industrys leading suppliers of payment processing products designed for small,
medium, and large sized businesses.
eTIM is designed to support the connection of selected VeriFone terminals to PAYware Connect.
PAYware Connect is a fast, reliable, and cost effective product that can easily be integrated into any
brick and mortar, MOTO (Mail Order/Telephone Order), e-Commerce, or restaurant application-regardless of the operating system or development platform used. PAYware Connect enables merchants
to process secure payment transactions in a real time environment over the Internet and supports all
major credit and debit card payment types, EBT, and gift.
eTIM Overview
eTIM is a server designed and developed by VeriFone, Inc. to work between PAYware Connect and
selected VeriFone Point of Sale devices such as the VeriFone MX Series. It is written in Java, so it can
run on multiple platforms, including Windows, Linux, and OS/400 (or i5/OS) for the IBM System i.
eTIM works in conjunction with PAYware Connects API so merchants with existing PAYware Connect
interfaces will not have to change their API to take advantage of eTIM. Highly configurable and easy to
use, eTIM provides a utility to configure all of the global and device settings for the supported
terminals on a Local Area Network (LAN) and is capable of managing a large number of terminals per
store. An optional BIN Management feature supports debit encouragement.
eTIM supports Credit Card, Debit Card, EBT, and Gift Card transactions. The commands supported
include:
Credit Cards: SALE, PRE_AUTH, POST_AUTH, CREDIT, RETURN (processor dependent). Other
transactions are available using passthrough to PAYware Connect.
Debit Cards: SALE, RETURN, BALANCE, VOID, CREDIT, REVERSAL, PRE_AUTH. The use of SALE with
CASHBACK_AMNT is supported (processor dependent)
EBT Cards: SALE,RETURN,POST_AUTH (voucher), VOID, BALANCE. The use of SALE with
CASHBACK_AMNT is supported (CASH_BENEFITS only)
Gift Cards (processor dependent): SALE, PRE_AUTH, CREDIT, RETURN, BALANCE, ADD_VALUE,
REMOVE_VALUE, ACTIVATE, DEACTIVATE, REACTIVATE, REGISTER, GIFT_CLOSE
Sample XML Request set:
<TRANSACTION>
<FUNCTION_TYPE>PAYMENT</FUNCTION_TYPE>
<PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
<COMMAND>SALE</COMMAND>
<TRANS_AMOUNT>5.00</TRANS_AMOUNT>
<INVOICE>123456</INVOICE>
<CLIENT_ID>1100010001</CLIENT_ID>
<DEVICEIP>192.168.0.20</DEVICEIP>
<DEVICEPORT>9001</DEVICEPORT>
</TRANSACTION>
Note that card data is not included in the transaction. This will prompt the terminal to request a card
swipe. If card data is provided, the terminal will be bypassed, and eTIM will send the transaction
directly to PAYware Connect.
If the DEVICEIP and DEVICEPORT are not present in the transaction, eTIM will authenticate to
PAYware Connect and attempt to process the transaction on behalf of the POS. In this manner, eTIM
supports all transactions available in the PAYware Connect Integration Guide.
This manual is your guide to the installation, configuration, integration, and usage of eTIM for PAYware
Connect. Additionally, VeriFones Integration Support team is available to answer your questions about
all aspects of the PAYware Transact, PAYware Connect, and eTIM products. If you cannot find the
answers to your questions within the pages of this manual, please contact our team at (877) 659-8983.
We want to know your thoughts about eTIM. If you have any comments or suggestions about the eTIM
product or this manual, please e-mail us at feedback@verifone.com.
Reference Documents
Applicability
The PCI PA-DSS applies to any payment application which stores, processes, or transmits cardholder
data as part of authorization or settlement, unless the application would fall under the merchants PCI
DSS validation. PAYware PC, PAYware Transact, PAYware SIM, and PCCharge (collectively the
PAYware NA Payment Applications) were developed by VeriFone for use by third parties, and
therefore are subject to PA-DSS validation. PAYware Connect (also included under PAYware NA
Payment Applications) falls under PCI DSS. See the PCI PA-DSS Program Guide to determine if PCI PADSS validation is required for any other payment applications used at the merchant location.It is
important to note that PA-DSS or PCI DSS validated payment applications alone do not guarantee PCI
DSS compliance for the merchant. The validated payment application must be implemented in a PCI
DSS compliant environment. If your application is ran on Windows XP, you are required to turn off
Windows XP System Restore Points.
Cardholder Data
Data Element
Storage
Permitted
Protection
Required
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
No
Yes
Yes
No
No
N/A
N/A
CAV2/CID/CVC2/CVV2
No
N/A
N/A
PIN/PIN Block
No
N/A
N/A
Cardholder Name
Service Code 1
Expiration Date
Sensitive
Authentication
Data 2
2
3
These data elements must be protected if stored in conjunction with the PAN. This protection should be per
PCI DSS requirements for general protection of the cardholder environment. Additionally, other legislation
(for example, related to consumer personal data protection, privacy, identity theft, or data security) may
require specific protection of this data, or proper disclosure of a company's practices if consumer-related
personal data is being collected during the course of business. PCI DSS, however, does not apply if PANs are
not stored, processed, or transmitted.
Do not store sensitive authentication data after authorization (even if encrypted).
Full track data from the magnetic stripe, magnetic-stripe image on the chip, or elsewhere.
PA-DSS Guidelines
The following PA-DSS Guidelines are being provided by VeriFone as a convenience to its customers.
Customers should not rely on these PA-DSS Guidelines, but should instead always refer to the most
recent PCI DSS Program Guide published by PCI SSC.
1.1.2 After authorization, do not store the card-validation value or code (three-digit or fourdigit number printed on the front or back of a payment card) used to verify card-not-present
transactions.
Note: See PCI DSS and PA-DSS Glossary of Terms, Abbreviations, and Acronyms for additional
information.
PCI Data Security Standard Requirement 3.2.2
1.1.3 After authorization, do not store the personal identification number (PIN) or the
encrypted PIN block.
Note: See PCI DSS and PA-DSS Glossary of Terms, Abbreviations, and Acronyms for additional
information.
PCI Data Security Standard Requirement 3.2.3
1.1.4 Securely delete any magnetic stripe data, card validation values or codes, and PINs or
PIN block data stored by previous versions of the payment application, in accordance with
industry-accepted standards for secure deletion, as defined, for example by the list of
approved products maintained by the National Security Agency, or by other State or National
standards or regulations.
PCI Data Security Standard Requirement 3.2
Note: This requirement only applies if previous versions of the payment application stored
sensitive authentication data.
1.1.5 Securely delete any sensitive authentication data (pre-authorization data) used for
debugging or troubleshooting purposes from log files, debugging files, and other data sources
received from customers, to ensure that magnetic stripe data, card validation codes or values,
and PINs or PIN block data are not stored on software vendor systems. These data sources must
be collected in limited amounts and only when necessary to resolve a problem, encrypted
while stored, and deleted immediately after use. PCI Data Security Standard Requirement 3.2
The PAN must be rendered unreadable anywhere it is stored, even outside the payment
application.
Note: Strong cryptography is defined in the PCI DSS and PA-DSS Glossary of Terms,
Abbreviations, and Acronyms.
2.4
If disk encryption is used (rather than file- or column-level database encryption),
logical access must be managed independently of native operating system access control
mechanisms (for example, by not using local user account databases). Decryption keys must not
be tied to user accounts. PCI Data Security Standard Requirement 3.4.2
2.5
Payment application must protect cryptographic keys used for encryption of cardholder
data against disclosure and misuse. PCI Data Security Standard Requirement 3.5
2.6
Payment application must implement key management processes and procedures for
cryptographic keys used for encryption of cardholder data. PCI Data Security Standard
Requirement 3.6
2.7
Securely delete any cryptographic key material or cryptogram stored by previous
versions of the payment application, in accordance with industry-accepted standards for secure
deletion, as defined, for example the list of approved products maintained by the National
Security Agency, or by other State or National standards or regulations. These are
cryptographic keys used to encrypt or verify cardholder data. PCI Data Security Standard
Requirement 3.6
Note: This requirement only applies if previous versions of the payment application used
cryptographic key materials or cryptograms to encrypt cardholder data.
Note: Strong cryptography is defined in PCI DSS and PA-DSS Glossary of Terms, Abbreviations,
and Acronyms. PCI Data Security Standard Requirement 8.4
Note: This requirement for code reviews applies to all payment application components (both
internal and public-facing web applications), as part of the system development life cycle
required by PA-DSS Requirement 5.1 and PCI DSS Requirement 6.3. Code reviews can be
conducted by knowledgeable internal personnel or third parties.
5.2
Develop all web payment applications (internal and external, and including web
administrative access to product) based on secure coding guidelines such as the Open Web
Application Security Project Guide. Cover prevention of common coding vulnerabilities in
software development processes, to include:
Documentation of impact.
Management sign-off by appropriate parties
Testing functionality to verify the new change(s) does not adversely
impact the security of the system. Remove all testing configurations, samples,
and data before finalizing the product for production.
Back-out or product de-installation procedures.
5.4
The payment application must not use or require use of unnecessary and insecure
services and protocols (for example, NetBIOS, file-sharing, Telnet, unencrypted FTP, must be
secured via SSH, S-FTP, SSL, IPSec and other technology to implement end to end security.).
PCI Data Security Standard Requirement 2.2.2
provided with or required by the payment application (for example, web servers, third-party
libraries and programs) must be included in this process. PCI Data Security Standard
Requirement 6.2
7.2
Software vendors must establish a process for timely development and deployment of
security patches and upgrades, which includes delivery of updates and patches in a secure
manner with a known chain-of-trust, and maintenance of the integrity of patch and update
code during delivery and deployment.
More Information
VeriFone, Inc. highly recommends that merchants contact the card association(s) or their processing
company and find out exactly what they mandate and/or recommend. Doing so may help merchants
protect themselves from fines and fraud.
For more information related to security, visit:
http://www.pcisecuritystandards.org
http://www.visa.com/cisp
http://www.sans.org/resources
http://www.microsoft.com/security/default.asp
https://sdp.mastercardintl.com/
http://www.americanexpress.com/merchantspecs
Documentation Notes
This manual provides documentation on the installation and usage of eTIM on three major operating
system families: Microsoft Windows, various Linux/Unix flavors, and IBMs i5/OS (which runs
exclusively on the System i). If you are using an operating system that is not covered in this manual,
you should consult your operating systems user guide for specifics on the installation and usage of
Java-based products.
WARNING
Warnings contain information vital to the subject being discussed. Failure to address the
concepts described in these warnings may result in downgraded per-transaction rates,
serious program errors, unsuccessful transactions, etc.
Note
Notes contain important information separated from the normal flow of information in
order to draw your attention to a concept and/or further clarify an idea.
eTIM Directory
The eTIM default installation directory will be referred to as \<eTIM>\ in this documentation, with
<eTIM> referring to the installation directory that you specify during installation. Unless you provide
an alternate directory path and name, eTIM will be installed in C:\VeriFone\etim on Windows and
in /root/verifone/etim on Linux. You should change the base install directory to /opt so that
eTIM is not installed in the /root directory. On i5/OS, eTIM will be installed on the mapped drive in
/verifone/etim. There is no option to change the install directory for i5/OS.
Chapter 1 -- Installation
Installation Recommendations
We recommend that a System Administrator assists with or performs the eTIM installation. Although
this manual goes into detail about all of aspects of the eTIM installation, it is assumed that the person
performing the installation has a certain amount of knowledge (see the list below) and administrative
rights on the server.
The person installing eTIM will need to perform the following task prior to and during the installation:
Download and install the Java Virtual Machine on the server that will run eTIM. The Java
Virtual Machine is included with the Java 2 Platform, Standard Edition.
Basic Prerequisites
eTIM has the following prerequisites. Detailed information is provided in the installation section for
each operating system.
1. Java 2 Platform, Standard Edition (J2SE) SDK version 1.6 or later
2. TCP/IP support
Initial Teleconference
Prior to performing the installation, it is recommended that you contact VeriFone, Inc. to set up an
initial installation and integration teleconference. This teleconference is designed to familiarize you
with the installation procedure and the integration aspects of eTIM. For VeriFone, Inc. contact
information, refer to the Notice section (see page 2).
Installation Prerequisites
Perform the following prerequisite steps to prepare your Windows server for eTIM. Once the
prerequisites have been met, the eTIM installation, configuration, and integration can begin.
1) Log on to the server as Administrator or equivalent.
The user performing the installation must have permissions to create directory structures on the
server.
2) Install the Java 2 Platform, Standard Edition (J2SE) SDK version 1.6 or later.
The Java Virtual Machine (JVM) version 1.6 or later is required to run eTIM. The JVM is included in
the J2SE SDK.
To find out if you already have the correct JVM installed, go to a command prompt (click Start /
Run and type cmd) and then type:
java version
If the JVM is installed and the executable is in your path, the version of the JVM will be returned. If
you do not have the JVM installed or have an older version, you should download and install the
latest stable J2SE SDK (version 1.6 or later).
The J2SE SDK is available for download from Oracle's web site:
http://www.oracle.com/technetwork/java/javase/downloads/index.html.
After downloading the file, install the J2SE SDK by executing the installation program and following
the default installation prompts. If necessary, refer to the online Java documentation and your
operating systems documentation for help with the installation.
Installation
A GUI-based program called the eTIM Setup is provided to install eTIM. The eTIM Setup is a Java-based
program and requires that Java is installed and is in the servers path.
5. After selecting the Type of Installation, you will be prompted to Select an Operating System. Click
to select Windows and click Next to continue.
b) If you have selected the installation type as Upgrade Installation, the Upgrade Location
screen appears. The Destination Directory should be the location where you had installed eTIM
previously. Use the Browse button to locate, and Click Next to continue.
Note
The upgrade installation will copy the entire \<etim>\ folder to \<etim_backup>\ and
zip it with the current date as the file name. Your configuration information will be
retrieved for the new installation.
7. After a few moments, the Java Runtime Environment screen will appear with the default JRE path
in the text field. In the event that you want to use a different JRE, use the Browse button to
locate it. Once you have selected the JRE, Click Next to continue.
Note
Sometimes the JRE installs to a directory where the name includes spaces. Long filenames
with spaces do not work properly in scripts. If this is the case, use the DOS 8.3 name of the
directory.
Example: C:\Program Files\ should be referenced as C:\progra~1\.
8. The Confirm Installation screen allows you to review the details of your installation. To change any
of the options, use the Back button. Once you are ready to initiate the installation, click Install.
Once you have initiated the installation, the Setup program will start copying the necessary files to
the selected installation directory. A progress bar will appear, indicating the status of the
installation process, and a text area will display the details of the current process. Note that the
Finish button is disabled during installation.
9. When the installation is complete, a status message will display stating Installation Successful.
Click Finish.
Whats Next?
Now that eTIM is installed on your Windows computer, you are ready to configure eTIM. Skip to
Chapter 2 -- Configuration for information on configuring eTIM.
Installation Prerequisites
Perform the following prerequisite steps to prepare your Linux/Unix server for eTIM. Once the
prerequisites have been met, the eTIM installation, configuration, and integration can begin.
1. Log on to the server as root or equivalent.
The user performing the installation must have permissions to create directory structures on the
server.
2. Install the Java 2 Platform, Standard Edition (J2SE) SDK version 1.6 or later.
The Java Virtual Machine (JVM) version 1.6 or later is required to run eTIM. The JVM is included in
the J2SE SDK.
To find out if you already have the correct JVM installed, go to a terminal window and then type:
java version
If the JVM is installed and the executable is in your path, the version of the JVM will be returned. If
you do not have the JVM installed or have an older version, you should download and install the
latest stable J2SE SDK (version 1.6 or later).
The J2SE SDK is available for download from Oracle's web site:
http://www.oracle.com/technetwork/java/javase/downloads/index.html.
After downloading the file, install the J2SE SDK by executing the installation program and following
the default installation prompts. If necessary, refer to the online Java documentation and your
operating systems documentation for help with the installation.
Once the J2SE SDK is installed, add the Java bin directory to your path. By default, the J2SE
SDK is installed in the /usr/java/j2sdk1.6.x_xx directory. If necessary, consult your operating
systems documentation for information on adding directories to your path.
Installation
A GUI-based program called the eTIM Setup is provided to install eTIM. The eTIM Setup is a Java-based
program and requires that Java is installed and is in the servers path.
Note
All commands are case-sensitive.
1. To start the eTIM Installer, change your path to the eTIM Setups root directory.
Next, start the eTIM Setup Wizard by executing the following script file:
./installer.sh
2. Once the eTIM Setup Wizard has been launched, it prompts to select the Type of Installation: New
Installation or Upgrade Installation
3. Click to select the appropriate Type of Installation.
4. Click Next to continue.
5. After selecting the Type of Installation, you will be prompted to Select an Operating System, Click
to select Linux and click Next to continue.
b) If you have selected the installation type as Upgrade Installation, the Upgrade Location
screen appears. The Destination Directory should be the location where you had installed eTIM
previously. Use the Browse button to locate.
7. After a few moments, the Java Runtime Environment screen will appear with the default JRE path
in the text field. In the event that you want to use a different JRE, use the Browse button to
locate it. Once you have selected the JRE, Click Next to continue.
8. The Confirm Installation screen allows you to review the details of your installation. To change any
of the options, use the Back button. If you are ready to initiate the installation, click Install.
9. Once you have initiated the installation, the Setup program will start copying the necessary files to
the select installation directory. A progress bar will appear, indicating the status of the
installation process, and a text area will display the details of the current process. Note that the
Finish button is disabled during installation.
10. When the installation is complete, a status message will be displayed stating Installation
Successful and the progress bar will be at 100%. At that point, the Finish button will be enabled.
11. Setup has now finished installing eTIM to your computer. Click on Finish.
Whats Next?
Now that eTIM is installed on your Linux/Unix computer, you are ready to configure eTIM. Skip to
Chapter 2 -- Configuration for information on configuring eTIM.
Note
The eTIM Setup program must be executed from a Windows workstation. The installation
program will install eTIM Server to the System i Integrated File System (IFS) via the
network. To perform the installation, the Windows workstation must have read/write
access to the System i IFS. Make sure a Windows workstation is available and is set up to
access the System i IFS prior to beginning the steps outlined in this section.
Installation Prerequisites
Perform the following prerequisite steps to prepare your System i server for eTIM. Once the
prerequisites have been met, the installation, configuration, and integration can begin.
1. Log on to the System i as QSECOFR or equivalent.
Although the majority of the installation occurs from a Windows workstation, several commands
must be executed on the System i. The person installing eTIM must have access to the System i
(either via a terminal session or direct access to the System i). This user must be logged in as
QSECOFR or equivalent.
2. Map a drive from Windows to the System i.
You must map a drive from Windows to the System i in order to use the eTIM Setup
programs GUI application (See Step 6).
3. Verify and configure the TCP/IP settings on the System i. TCP/IP must be configured properly if
payment processing will be conducted via the Internet. To verify that TCP/IP is configured
properly, type CFGTCP from the i5/OS command line. Choose option 12, Change TCP/IP
domain information and verify the following:
The Host name and Domain name settings must be properly set.
The Domain name server (DNS) settings must be set properly. Contact your ISP to obtain the
IP address(es) of your DNS Server(s) and enter them on this screen. Alternatively, if a Windows
workstation on the same network as the System i is configured for Internet connectivity, go to
a command prompt on the Windows workstation and enter the following command:
ipconfig /all
The output from this command will indicate which DNS Server(s) are currently being used on
your network.
4. Verify that Java 1.6 is installed and configured properly on the System i. The Java runtime
environment is installed as part of the licensed programs. To check if the Java runtime
environment is installed properly and to make sure you are running at least version 1.6, type the
following from the command line:
java *version
If the Java runtime environment is installed properly, a message indicating the version should
appear at the bottom of the screen.
If a message does not appear, or the message indicates a version prior to 1.6, make sure that Java
1.6 is installed. If Java 1.6 is installed, and the java *version command returns an earlier
version, use a text editor to update the SystemDefault.properties file that appears in the
/home/<username>/ directory to indicate the following:
java.version=1.6
After updating this file, execute the java *version command again to verify that the proper
version of Java is configured and running properly on the System i.
5. Install the J2SE SDK version 1.6 on a Windows workstation. To run the eTIM Setup program, you
must install the J2SE SDK (which includes the JVM) on the Windows workstation. The eTIM Setup
program is a Java program and requires the JVM to run.
To find out if you already have the JVM installed, go to a command prompt (click Start / Run and
type cmd) and then type:
java version
If the JVM is installed and the executable is in your path, the version of the JVM will be returned. If
you do not have the JVM installed or have an older version, you should download and install the
latest stable J2SE SDK (version 1.6 or later).
The J2SE SDK is available for download from Oracle's web site:
http://www.oracle.com/technetwork/java/javase/downloads/index.html.
After downloading the file, install the J2SE SDK by executing the installation program and following
the default installation prompts. If necessary, refer to the online Java documentation and your
operating systems documentation for help with the installation.
6. On the Windows workstation, map a drive to the System i IFS root directory. Use Windows
Explorer to map the network drive.
a. From Windows Explorer, click Tools | Map Network Drive...
b. Choose a drive letter from the Drive: drop down box (Example: X:).
c. Type in the System is IFS root directorys network address in the Folder: box.
Installation
A GUI-based program called eTIM Setup is provided to install eTIM. The eTIM Setup is a Java-based
program and requires that Java is installed and is in the servers path.
5. After selecting the Type of Installation, you will be prompted to Select the Operating System.
Click to select OS/400 and click Next to continue.
6. The Java Version and Mapped Drive screen will appear. Select the Java Version of your System i
and select the Mapped Drive that is used to connect the System i to Windows. Click Next to
continue.
7. The Confirm Installation screen allows you to review the details of your installation. To change any
of the options, use the Back button. Once you are ready to initiate the installation, Click Install.
8. Once you have initiated the installation, the Setup program will start copying the necessary files to
the selected installation directory. A progress bar will appear, indicating the status of the
installation process, and a text area will display the details of the current process. Note that the
Finish button is disabled during installation.
9. When the installation is complete, a status message will be displayed stating Installation
Successful and the progress bar will be at 100%. At that point, the Finish button will be enabled.
10. Setup has now finished installing eTIM to your System i computer. Click on Finish.
Note
Setting up a Separate Subsystem from QBATCH
We strongly recommend that you run eTIM and any Device servers in a separate
subsystem from QBATCH:
From the i5/OS command line, type the following to set up the #VFeTIM subsystem
environment:
qsh
<Enter>
cd /VeriFone/etim/utils
iSbuildTIAS400Environment.sh
This will create the following:
VFETIM library
#VFETIM subsystem
VFETIM job queue
Whats Next?
Now that eTIM is installed on your System i computer, you are ready to configure your eTIM. Proceed to
Chapter 2 -- Configuration for information on configuring eTIM.
Chapter 2 Configuration
Welcome
The Welcome screen provides basic instruction on how to use the configuration utility. Click on Help to
display the current version of eTIM.
Click Next to continue.
Server Configuration
Description
Listening Port
Type the TCP port where eTIM server will wait for connections from the POS.
Default = 5015
Monitor Port
Type the TCP port that the GUI launcher utility can use to monitor eTIM servers status.
Default = 5016
Use SSL
Enter or browse to select the relative path to the .cer or .jks used to enable SSL
connectivity.
Default = blank or ./certs/etimcert.cer
Type the password used to open the Key Store containing the certificates.
Note
Consult your PAYware Connect validation letter to obtain the URL Settings required.
Primary URL Settings - Enter the PAYware Connect URL that will be used to process regular
transactions.
Secondary URL Settings Enter the PAYware Connect Secondary URL. The Secondary URL is
used when Primary URL is not able to connect to the host.
Admin URL Settings Enter the Admin URL. The Admin URL is used to load SERIAL_NUM and
DEVICEKEY of the Client ID.
Connection Timeout: Enter Connection Timeout for each URL. The Connection Timeout is the
time interval within which the connection with the host should be established.
Response Timeout: Enter Response Timeout for each URL. The Response Timeout is the time
interval in which the response from the host should happen before the Response Timeout.
Note
Most of the Global settings will default and do not need to be entered.
Property Name
Description
Payment Settings
Select TRUE if you wish to allow manual entry of the account number. You will also be
prompted for expiration date and zip code. Refer to BadMagReadMsgBox=<value>
setting in config.usr1 on MX Series device.
Select TRUE if Credit/Refund amount should display as a negative value on the MX Series
device.
Select to re-order payment steps. See section Payment Transaction Flow (page 88).
Select FALSE to prompt cardholder to select payment type. Select TRUE to prompt
cardholder to confirm amount.
Select track order preference to send to PAYware Connect. If using VeriShield Protect,
TRACK2-TRACK1 (2-1) is recommended for VeriShield Protect activation.
Select TRUE to enable eTIM to prompt for signature on all approved / captured credit
card transactions.
Select TRUE to enable eTIM to send a void request when customer cancels at the signature
prompt.
NOTE: Credit card VOIDs must be enabled in the API application validation configuration; if
not, it will result in error.
NOTE: The following apply to Payment Transaction Flow steps.
If Submit Payment is before Prompt for Signature and Void on Signature Cancel is TRUE:
When customer cancels, eTIM sends void request (the transaction already submitted).
If Submit Payment is after Prompt for Signature and Void on Signature Cancel is TRUE:
When customer cancels, it is just a cancellation. No VOID is sent (or required).
Select FALSE to turn off storing signatures. Default is TRUE. If TRUE, signature files will be
stored as .bmp files in \html\signatures.
Property Name
Description
Select TRUE to require entry of cardholder billing postal code for all keyed payment card
transactions.
Select TRUE to bypass expiration date prompt when doing Private Label manual sale
transactions.
Debit Settings
Allow Cashback
Select TRUE if you wish to allow Debit cardholders to request Cashback amount from the
Device. See example on next page.
Enter if CARDHOLDER is selected as Cash Back Entry Mode and you wish to configure a
maximum cash back amount.
Cashback Amount 1
Enter if PRE_CONFIGURED is selected as Cash Back Entry Mode. Five values must be
configured and will be presented as selectable options (buttons) from which the cardholder
can select the desired cash back amount.
Cashback Amount 2
Cashback Amount 3
Cashback Amount 4
Cashback Amount 5
Enter the minimum transaction amount required for a BIN lookup to change the transaction
type from CREDIT to DEBIT.
Select TRUE to prompt the user to swipe card and enter PIN for debit REVERSAL transactions
that include the TROUTD or CTROUTD tag.
EBT Settings
Allow Cashback
Select TRUE if you wish to allow Debit cardholders to request Cashback amount from the
Device. See example on next page.
Enter if CARDHOLDER is selected as Cash Back Entry Mode and you wish to configure a
maximum cash back amount.
Cashback Amount 1
Enter if PRE_CONFIGURED is selected as Cash Back Entry Mode. Five values must be
configured and will be presented as selectable options (buttons) from which the cardholder
can select the desired cash back amount.
Cashback Amount 2
Cashback Amount 3
Cashback Amount 4
Cashback Amount 5
Select TRUE to prompt the user to swipe card on an EBT VOID transaction.
Gift Settings
Once you have configured the Global Settings for all of your Client IDs, click Next to add all of the
Client IDs.
Client ID Configuration
To Configure a Client ID, click Add.
To Edit a Client ID configuration, select the complete row of the device that you want to edit and click
Edit to start editing.
To Delete a Client ID, select the complete row and click Delete to delete the device configuration.
The Client ID Settings screen will allow you to configure your PAYware Connect Client IDs.
Click Next to continue.
Note
This local settings configuration should only be used when your Client ID needs a
configuration that is different from the global (or default) configuration.
Now you can configure your local settings for that particular Client ID (see table next page). The fields
that are marked as (use global) will use the configured values within the global settings.
Example:
If Allow Cashback is set to true in the global settings and if the value here is (use global) then
the Client ID will use the global setting and allow Cashback.
At this point, the configurator will require a Device key load.
Note
This local settings configuration should only be used when your Client ID needs a
configuration that is different from the global (or default) configuration. The fields that
are marked as (use global) will use the configured values within the global settings
Property Name
Description
Payment Settings
Select TRUE if you wish to allow manual entry of the account number. You will also be
prompted for expiration date and zip code. Refer to BadMagReadMsgBox=<value>
setting in config.usr1 on MX Series device.
Select TRUE if Credit/Refund amount should display as a negative value on the MX Series
device.
Select to re-order payment steps. See section Payment Transaction Flow (page 88).
Select FALSE to prompt cardholder to select payment type. Select TRUE to prompt
cardholder to confirm amount.
Select track order preference to send to PAYware Connect. If using VeriShield Protect,
TRACK2-TRACK1 is required for VeriShield Protect activation.
Select TRUE to enable eTIM to prompt for signature on all approved / captured credit
card transactions.
Select TRUE to enable eTIM to send a void request when customer cancels at the signature
prompt.
NOTE: Credit card VOIDs must be enabled in the API application validation configuration; if
not, it will result in error.
NOTE: The following apply to Payment Transaction Flow steps.
If Submit Payment is before Prompt for Signature and Void on Signature Cancel is TRUE:
When customer cancels, eTIM sends void request (the transaction already submitted).
If Submit Payment is after Prompt for Signature and Void on Signature Cancel is TRUE:
When customer cancels, it is just a cancellation. No VOID is sent (or required).
Select FALSE to turn off storing signatures. Default is TRUE. If TRUE, signature files will be
stored as .bmp files in \html\signatures.
Property Name
Description
Select TRUE to require entry of cardholder billing postal code for all keyed payment card
transactions.
Select TRUE to bypass expiration date prompt when doing Private Label manual sale
transactions.
Debit Settings
Allow Cashback
Select TRUE if you wish to allow Debit cardholders to request Cashback amount from the
Device. See example on next page.
Enter if CARDHOLDER is selected as Cash Back Entry Mode and you wish to configure a
maximum cash back amount.
Cashback Amount 1
Enter if PRE_CONFIGURED is selected as Cash Back Entry Mode. Five values must be
configured and will be presented as selectable options (buttons) from which the cardholder
can select the desired cash back amount.
Cashback Amount 2
Cashback Amount 3
Cashback Amount 4
Cashback Amount 5
Enter the minimum transaction amount required for a BIN lookup to change the transaction
type from CREDIT to DEBIT.
Select TRUE to prompt the user to swipe card and enter PIN for debit REVERSAL transactions
that include the TROUTD or CTROUTD tag.
EBT Settings
Allow Cashback
Select TRUE if you wish to allow Debit cardholders to request Cashback amount from the
Device. See example on next page.
Enter if CARDHOLDER is selected as Cash Back Entry Mode and you wish to configure a
maximum cash back amount.
Cashback Amount 1
Enter if PRE_CONFIGURED is selected as Cash Back Entry Mode. Five values must be
configured and will be presented as selectable options (buttons) from which the cardholder
can select the desired cash back amount.
Cashback Amount 2
Cashback Amount 3
Cashback Amount 4
Cashback Amount 5
Select TRUE to prompt the user to swipe card on an EBT VOID transaction.
Gift Settings
Click to select device type for which you wish to change configuration settings.
Click Next to continue to Device Result Settings.
Note
Note
The term MX Series device, as it is used in this documentation, applies to the MX 880, MX
870, MX 860, MX 850, MX 830, MX 760, MX 915, and MX 925. Examples shown for the MX 880
device are for illustration purposes and would apply to all MX Series devices.
The MX Series device must be configured as a TCP/IP Client using an editor like Unix VI.
Two files in the MX 870/MX 850/MX 830 must be edited.
To enable the TCP/IP setting, ensure the config.usr1 file in /mnt/sram has the
following five parameter settings:
1.
2.
3.
4.
5.
commtype=TCPIP
formnameinevent=1
server=1
termprt=9001
ifconfig=eth0 <ip-address> netmask <net-mask>
Example:
Note
Follow the steps below to enable TCP/IP on MX 915 and MX 925 devices.
Tap the Administration tab on the System Mode screen. Tap the Communication tab. Tap
Network and then Ethernet. Choose DHCP or StaticIP.
If you choose DHCP, then the device will automatically go and get an IP address.
commtype=TCPIP should be selected by default in the FORMAgent/ETIM Forms load.
Note
Newly configured Global Settings are not loaded by the Direct Device Test (see page 124).
They only apply when running transactions through the eTIM server.
Note
Most of the Global settings will default and do not need to be entered.
Property Name
Description
Card Swipe Settings
VSP Enabled
The separator that indicates the start of the account number in Track1 Data
The separator that indicates the start of the card holder name in Track1 Data
The separator that indicates the start of the account number in Track2 Data
Device Application Settings
The maximum time (in seconds) to display the result on the device
The time (in seconds) eTIM will wait for an event from the MX Series device. Min 30 and
Max 180 (default). BLOCK_TIMEOUT in the request will override this setting.
Start X Co-ordinates
Change default signature box area for display. Here you can set merchants preferred
settings that will apply to all devices of this type. These settings take priority over
default/general settings that are contained in the devicetype.properties file. The
new settings would be contained in the device.properties file.
NOTE: Start X Co-ordinates = top left position of signature area
Start Y Co-ordinates
Change default signature box area for display. Here you can set merchants preferred
settings that will apply to all devices of this type. These settings take priority over
default/general settings that are contained in the devicetype.properties file. The
new settings would be contained in the device.properties file.
NOTE: Start Y Co-ordinates = top left position of signature area
End X Co-ordinates
Change default signature box area for display. Here you can set merchants preferred
settings that will apply to all devices of this type. These settings take priority over
default/general settings that are contained in the devicetype.properties file. The
new settings would be contained in the device.properties file.
NOTE: End X Co-ordinates = top right position of signature area
End Y Co-ordinates
Change default signature box area for display. Here you can set merchants preferred
settings that will apply to all devices of this type. These settings take priority over
default/general settings that are contained in the devicetype.properties file. The
new settings would be contained in the device.properties file.
NOTE: End Y Co-ordinates = lower left position of signature area
Once you have configured the Global Settings for all of your MX Series devices, click Close to return to
the Device Global Settings screen.
Here you can configure Actual Result Text with user-friendly custom Device Displayed Text responses.
The custom responses will be shown on the device Result Form.
Example: If the merchant wishes to display TRANSACTION APPROVED instead of the RESULT response
CAPTURED, that translation would be configured here.
Click Next.
Device Inventory
Add Device
If you choose to Add a device, you will be presented with the following:
Using the drop-down arrow, choose the device type. Next, type your device IP Address and its TCP
Port number.
Click Create to continue.
Edit Device
To edit device settings, click to highlight the row of the device you wish to edit in the Device
Inventory. Click Edit.
If you choose to Edit a device, you will be presented with the following:
Note
This device configuration should only be used when your device needs settings that differ
from the global (or default) configuration.
Convert Device
To Convert from one device type to another, click on the Convert button. A dialog box appears. Select
the target device type from the drop-down box.
WARNING
Configure the target device type to avoid undesired behavior. Settings do not carry over
automatically from Global Device Type settings. For example, if VSP is enabled on the
current device type, users need to configure Global settings for the new device type to
enable VSP.
Click Convert.
A Confirmation dialogue box will appear if the target device types global configuration is at Default
settings.
Click Yes to continue conversion and configure later, or click No to return to Device Inventory.
BIN Range configuration encourages Debit transactions. Once a debit range is configured, eTIM will no
longer prompt the user to select the Payment Type (e.g., CREDIT or DEBIT). Instead, it prompts for
the PIN directly, hence benefiting the merchant by Debit Encouragement.
To Add a debit range, click Add.
To Edit a range, select the complete row of the debit range that you want to edit and click Edit.
To Delete a range, select the complete row and click Delete to delete the debit range.
Click Next to continue.
If you choose to Add a BIN Range Configuration, you will be presented with the following:
Card Type Label Select Card Type Label from drop-down list. Example: Visa Purchasing
Receipt Settings
The following Receipt Settings screen appears:
To configure the receipt format, select one of the options provided on this panel.
Note
The receipt template selected will be used for all accounts.
If the template you have selected can be customized, a Receipt Template Configuration screen
similar to one of the following is displayed:
Note
You are required to enter all three of the receipt template settings.
Configuration Saved
The following Confirmation panel displays to overwrite configuration data:
The text area will serve as console windows to eTIM server. The user may use the Launch eTIMServer
button to start eTIM .The respective Stop button can be used to terminate the server.
Borrow Device
Payment Media
Payment Type
Payment Details
Confirm Amount
Submit Payment
Capture Signature
Upload Signature
Return Device
Note
The current rules for payment flow are as follows:
Payment Details must be before Confirm Amount
Payment Media must be before Payment Details
Payment Type, Payment Media, Confirm Amount, and Payment Details must be
before Submit Payment
Payment Type must be before Capture Signature
Capture Signature and Submit Payment must be before Upload Signature
Transaction Stages
Borrow Device
eTIM will borrow the requested device from its internal device pool. If the device configuration has
changed since the last transaction, eTIM will reload this information before proceeding.
If the DEVICEIP and DEVICEPORT are not present, eTIM will short-circuit the payment transaction
flow by immediately submitting the transaction to PAYware Connect and returning the response.
Payment Media
eTIM collects the Payment Media if it is not present. During this stage, eTIM will determine if the
command requires a Card Swipe/Tap and collects it if not present. If BIN management is set up, eTIM
will attempt to determine the Payment Type based on the card BIN range.
If ETIM_MODIFIER MANUAL_ENTER has been included in the transaction, eTIM will attempt to collect
the account number and expiration date on the device.
The following Payment Type/Command combinations will prompt for a Card Swipe on the device:
Credit / Unknown
SALE
CREDIT
PRE_AUTH
POST_AUTH
VOICE_AUTH
Debit
SALE
CREDIT
BALANCE
PRE_AUTH
VOID (if set in configuration)
SALE
CREDIT
RETURN
VOID (if set in configuration)
POST_AUTH
BALANCE
SALE
CREDIT
RETURN
PRE_AUTH
BALANCE
ADD_VALUE
REMOVE_VALUE
ACTIVATE
DEACTIVATE
REACTIVATE
REGISTER
GIFT_CLOSE
EBT
Gift
Payment Type
eTIM prompts the customer for the Payment Type if it is not known or if eTIM has been configured not
to Accept POS Payment Type of Credit.
Payment Details
eTIM will attempt to collect additional details about the payment method such as the EBT Type, PIN,
and Cashback Amount. The actions taken here differ by Payment Type.
Credit
eTIM will prompt for the Customer Zip code.
Debit
eTIM will prompt for the PIN on the device. If the Payment Type was determined through a card BIN
range lookup, the customer can press the Cancel key on the device to select Credit.
If Cashback is configured, eTIM will prompt for the Cashback Amount on the device.
EBT
If the transaction is not a POST_AUTH, eTIM will prompt for the EBT Type. If Cash Benefits is selected,
eTIM will prompt for the Cashback Amount.
Gift
eTIM takes no additional actions.
Confirm Amount
eTIM prompts the customer to confirm the amount.
The following commands will never prompt to Confirm Amount:
BALANCE
ACTIVATE
DEACTIVATE
COMPLETION
GIFT_CLOSE
REACTIVATE
REGISTER
REVERSAL
VOID
Submit Payment
eTIM adds authentication information to the transaction and submits the transaction to PAYware
Connect.
Capture Signature
eTIM prompts the customer for signature on the device if the follow conditions are true:
Note
eTIM can be configured to automatically attempt a VOID transaction when the customer
presses Cancel on the device.
Upload Signature
eTIM will send the captured signature data and the TROUTD of the transaction to PAYware Connect. If
no signature data was captured, eTIM will skip this step.
Return Device
eTIM will return the requested device to its internal device pool. If the device configuration has
changed since the beginning of the transaction, eTIM will reload this information. eTIM will also
initialize the device to its idle screen, at this time, prior to making it available for subsequent
transactions.
If the BIN manager feature is not enabled, displays Select Payment Type form
The above form appears when the account number is manually keyed:
If the CANCEL button is clicked:
Cancels the transaction that has been initiated by the cashier/POS.
Type the expiration date in MMYY format on the key pad and click ENTER:
Displays the Enter Zip Code form.
The above form appears when the account number is manually keyed:
If the CANCEL button is clicked:
Cancels the transaction that has been initiated by the cashier/POS.
Type the zip code in MMYY format on the key pad:
Displays the Is Amount Correct? form.
The above form appears when the cardholder swipes the card on the Please Swipe Card form:
If Gift card option is not enabled.
If the Cancel button is clicked:
Cancels the transaction that has been initiated by the cashier/POS.
If the Debit button is clicked:
Displays the Enter PIN form.
If the EBT button is clicked:
Displays the Enter PIN form.
If the Credit button is clicked:
Displays the Is Amount Correct? form.
The above form appears when the cardholder swipes the card in Please Swipe Card form:
If Gift card option is enabled.
If the Cancel button is clicked:
Cancels the transaction that has been initiated by the cashier/POS.
If the Debit button is clicked:
Displays the Enter PIN form.
If the EBT button is clicked:
Displays the Enter PIN form.
If the Credit button is clicked:
Displays the Is Amount Correct? form.
Enter PIN
Note
If the cardholder hits the red CANCEL button before entering a PIN:
If the transaction sent from the POS was Credit and BIN manager prompted for a PIN, the
device prompts for CREDIT or DEBIT. The buyer has the option of choosing a payment type of
CREDIT rather than DEBIT for the purchase, or the buyer can re-select DEBIT and continue with
the purchase. The buyer also has the option to press the red CANCEL button again to cancel the
transaction.
If the transaction sent from the POS was Debit or EBT, it cancels the transaction initiated by
the cashier/POS.
Once the cardholder begins entering the PIN number, the CLEAR button will appear, which allows
the cardholder to clear and re-enter the PIN if needed.
Note
Is Amount Correct?
Result
After the transaction is processed, the result is displayed in the following form.
Chapter 5 Integration
<PAYMENT_MEDIA>MC</PAYMENT_MEDIA>
<PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
<PRESENT_FLAG>3</PRESENT_FLAG>
<REFERENCE>219117502542</REFERENCE>
<RESPONSE_TEXT>APPROVAL TAS036 </RESPONSE_TEXT>
<RESULT>CAPTURED</RESULT>
<RESULT_CODE>4</RESULT_CODE>
<SIGNATUREDATA>Qk1eBQAAAAAAAD4AAAAoAAAA6AAAACkAAAABAAEAAAAAACAFAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAP///wD///////////////////////////////////////////8
AH/////////////wH////////////////////////+P/h////////////g/gf//////////
/////////////n//4f//////////x//+H//////////////////////9///+P/////////+
////h//////////////////////v////H/////////3////4f//////AD////////////+/
////P////////+/////+P/////j/wP///////////7/////x////////7//////H////9//
/A///////////v/////5////////v//////n////v///8P/////////+//////z///////9
///////j///+/////H/////////7//////8f//////3///////z///9/////j/////////v
//////+f//////f///////x///3/////z/////////f//////+f/////9////////5///f/
////x////////9///////+f/////3////////5//+//////5////////7///////+f/////
v////////5//7//////5////////v///////+P////+/////////5//3//////z////////
f////////P////7/////////5//f//////8f//////+/////////P////v/////////5/+/
//////+P//////7/////////P////f/////////5/7////////P//////3/////////P///
9//////////5/3////////P//////v/////////P///7//////////5/f////////P/////
+//////////P///v//////////5+/////////P/////9//////////P///f//////////59
/////////f/////3//////////P//+///////////57////////+//////v//////////P/
/7///////////5v////////9//////f//////////P//3///////////7f/////////////
/+///////////P//f///////////y///////////////9///////////P/+////////////
w///////////////7///////////P/7////////////x///////////////3///////////
P/3////////////z///////////////v///////////P/f////////////n////////////
///f///////////P+/////////////H//////////////+////////////P9///////////
/+v//////////////9////////////P3////////////9f//////////////7//////////
//fv////////////4///////////////z///////////+ff////////////5///////////
////z///////////8//////////////z///////////////z///////////+b//////////
///////////////////////////////+X//////////////////////////////////////
///+P//////////////////////////////////////////////////////////////////
/</SIGNATUREDATA>
<SIGNATURE_FILE>signatures/2996700.bmp</SIGNATURE_FILE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<TRANS_AMOUNT>1.00</TRANS_AMOUNT>
<TRANS_DATE>2012.07.09</TRANS_DATE>
<TRANS_SEQ_NUM>4</TRANS_SEQ_NUM>
<TRANS_TIME>13:30:56</TRANS_TIME>
<TROUTD>2996700</TROUTD>
<VSP_CODE>100</VSP_CODE>
<VSP_RESULTDESC>Success</VSP_RESULTDESC>
<VSP_TRXID>634774521473099794</VSP_TRXID>
</RESPONSE>
<INTRN_SEQ_NUM>2996796</INTRN_SEQ_NUM>
<MIMETYPE>image/tiff</MIMETYPE>
<PAYMENT_MEDIA>VISA</PAYMENT_MEDIA>
<PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
<RESULT>CAPTURED</RESULT>
<RESULT_CODE>4</RESULT_CODE>
<SIGNATUREDATA><<See Example Above>></SIGNATUREDATA>
<SIGNATURE_FILE>signatures/2996796.bmp</SIGNATURE_FILE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<TRANS_AMOUNT>1.00</TRANS_AMOUNT>
<TRANS_DATE>2012.07.09</TRANS_DATE>
<TRANS_SEQ_NUM>11</TRANS_SEQ_NUM>
<TRANS_TIME>13:41:47</TRANS_TIME>
<TROUTD>2996796</TROUTD>
<VSP_CODE>910</VSP_CODE>
<VSP_RESULTDESC>VSP NOT APPLICABLE</VSP_RESULTDESC>
<VSP_TRXID>0</VSP_TRXID>
</RESPONSE>
Note
eTIM includes commands to perform direct device operations.
Do not perform direct device operations during PAYMENT requests to eTIM.
Signature Capture
The SIGNATURE command performs a signature capture and returns the data back to the POS. No data
is submitted to PAYware Connect. If Store Signature Files is set to TRUE in the Global or Local
Settings configuration, the signatures will be stored as .bmp files in \html\signatures.
Value
Comments
ETIM_SYSTEM can also be used (with no
change in functionality)
FUNCTION_TYPE
DEVICE
COMMAND
SIGNATURE
DEVICEIP
Ex: 192.168.2.110
Device IP address
DEVICEPORT
Ex: 9001
Value
Comments
MIMETYPE
Ex: image/tiff
RESPONSE_TEXT
Error condition/description
RESULT
Ex: OK
Valid values:
OK
ERROR
RESULT_CODE
Ex: -1
Valid values:
-1 (successful execution)
990099
SIGNATUREDATA
TERMINATION_STATUS
Ex: SUCCESS
Example Request:
<TRANSACTION>
<FUNCTION_TYPE>DEVICE</FUNCTION_TYPE>
<COMMAND>SIGNATURE</COMMAND>
<DEVICEIP>192.168.2.110</DEVICEIP>
<DEVICEPORT>9001</DEVICEPORT>
</TRANSACTION>
Example Response:
<RESPONSE>
<MIMETYPE>image/tiff</MIMETYPE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<RESULT_CODE>-1</RESULT_CODE>
<SIGNATUREDATA> base 64 encoded data </SIGNATUREDATA>
<RESULT>SUCCESS</RESULT>
</RESPONSE>
Device Information
The DEVICE_INFO command allows the POS to retrieve device version levels and serial number. The
actual data is device-specific.
Value
Comments
ETIM_SYSTEM can also be used (with no
change in functionality)
FUNCTION_TYPE
DEVICE
COMMAND
DEVICE_INFO
DEVICEIP
Ex: 192.168.2.110
Device IP address
DEVICEPORT
Ex: 9001
Value
Comments
RESULT
Ex: OK
Valid values:
OK
ERROR
RESULT_CODE
Ex: -1
Valid values:
-1 (successful execution)
990099
TERMINATION_STATUS
Ex: SUCCESS
(Device-specific fields)
Example Request:
<TRANSACTION>
<FUNCTION_TYPE>DEVICE</FUNCTION_TYPE>
<COMMAND>DEVICE_INFO</COMMAND>
<DEVICEIP>192.168.2.110</DEVICEIP>
<DEVICEPORT>9001</DEVICEPORT>
</TRANSACTION>
Example Response:
<RESPONSE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<RESULT_CODE>-1</RESULT_CODE>
<RESULT>SUCCESS</RESULT>
additional key-value pairs are device specific
</RESPONSE>
Passthru
The PASSTHRU command allows the POS to perform device level commands by brokering the
connection and passing the data back and forth between the POS and the device.
Note
This feature is available only for Legacy Support with other VeriFone systems. It is
recommended that POS systems make a direct connection to the device whenever
possible.
Passthru Request
Field
Value
Comments
FUNCTION_TYPE
DEVICE
COMMAND
PASSTHRU
DEVICEIP
Ex: 192.168.2.110
Device IP address
DEVICEPORT
Ex: 9001
Ex: TRUE
Ex: FALSE
Ex: FALSE
Ex: 180
Ex: 9001
HAS_RESPONSE
RESET
BLOCK
BLOCK_TIMEOUT
DEVICE_REQUEST_HEX
Passthru Response
Field
Value
Comments
DEVICE_RESPONSE_HEX
Ex: image/tiff
If HAS_RESPONSE = TRUE
A hex-encoded comma delimited string
containing the device request
If HAS_RESPONSE = FALSE
COMMAND executed successfully
RESULT
Ex: OK
Valid values:
OK
ERROR
RESULT_CODE
Ex: -1
Valid values:
-1 (successful execution)
990099
TERMINATION_STATUS
Ex: SUCCESS
Chapter 6 Troubleshooting
Note
Before running the Diagnostic utility, please ensure that PAYware Connect Server (if
testing the connection to PAYware Connect) is running and that eTIM is not.
The eTIM Diagnostic Tool will help you carry out the following diagnostic tests:
Enter the eTIM IP, eTIM Port, Device IP, Device Port and the Client ID in their respective text boxes.
You can change the Connection Timeout (secs) if you wish. Click on the desired transaction type to
generate a request transaction for eTIM.
Sample request:
<TRANSACTION>
<FUNCTION_TYPE>PAYMENT</FUNCTION_TYPE>
<PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
<CLIENT_ID>1000010001</CLIENT_ID>
<COMMAND>SALE</COMMAND>
<DEVICEIP>192.168.000.020</DEVICEIP>
<DEVICEPORT>9001</DEVICEPORT>
</TRANSACTION>
Click Process, found at the bottom of the screen, to send the request to eTIM Server and check the
connection. (Note that setting a Connection Timeout of 0 will maintain connection indefinitely.)
If a connection is successfully established with eTIM Server, the response message from eTIM Server
will populate the Response Message text area of the eTIM Connection Utility. If there is a problem
with the connection, or anything else, the error will be reported by the Utility.
Click Reset to clear the last request transaction.
Enter the PAYware Connect URLS, Merchant Key, User ID, User Pwd and the Client ID in their
respective text boxes. You may increase the Connection Timeout (secs) to a value greater than the
default of 60. Click on the desired transaction type to generate a request transaction for PAYware
Connect.
Click Test Connection, found at the bottom of the screen, to send the request to PAYware Connect
Server and check the connection.
If a connection is successfully established with PAYware Connect Server, the response message from
PAYware Connect Server will populate the Response Message text area of the PAYware Connect
Connection Utility. If there is a problem with the connection, or anything else, the error will be
reported by the Utility.
Direct device tests allow a merchant to perform quick tests on each of the capabilities of a device.
Most of device behavior for eTIM is available for testing in this standalone way.
Note
Direct Device Test uses default and hardcoded settings. The utility does not recognize
eTIM configuration values.
Card Swipe Attempts to capture track data from the device. Depending on device capability, this may
originate from the magnetic stripe reader, the RFID, or be manually entered.
Cashback Yes/No Prompts Yes/No/Cancel for cashback
Cashback Cardholder Prompts to enter cashback amount
Cashback Preconfig Prompts to select from (4 or 6) pre-configured cash amount options
Confirm Amount Prompts Yes/No/Cancel for $1.00 amount
Device Information Returns system information. Depending on the device, system information may
also display on the device screen.
Device Variables Returns variables of special interest (when supported). These are hardcoded and
typically considered important configuration variables.
EBT Type Prompts for Food Stamp or Cash Benefits
Enter PIN Prompts for PIN on the device
Copyright 2013. VeriFone Systems, Inc. All Rights Reserved.
124
eTIM requires that the integrator build the MX command, including STX, ETX, and LRC, and then encode
the string in a hex comma delimited string. The eTIM Testing Suite will build the full string, given just
the MX command.
For instance, if you fill in the input fields and enter the desired MX command in the MX PassThru
Command field then click the Generate Request button, the Diagnostic Tool will build the full request
in the Request Message area. The actual DEVICE_REQUEST_HEX value will include the required STX,
ETX, and LRC.
Example:
Modify and paste this string in the MX PassThru Command field:
XBATCH<FS>72<RS>XIFM<FS>ET_INIT<RS>XSFM
Click Generate Request. The Request should appear as follows.
Example Request:
<TRANSACTION>
<FUNCTION_TYPE>ETIM_SYSTEM</FUNCTION_TYPE>
<COMMAND>MX_PASSTHRU</COMMAND>
Copyright 2013. VeriFone Systems, Inc. All Rights Reserved.
126
<DEVICEIP>192.168.2.110</DEVICEIP>
<DEVICEPORT>9001</DEVICEPORT>
<DEVICE_REQUEST_HEX>02,58,42,41,54,43,48,1C,37,32,1E,58,49,46,4D,1C,45,
54,5F,49,4E,49,54,1E,58,53,46,4D,03,4C</DEVICE_REQUEST_HEX>
<RESET>FALSE</RESET>
<BLOCK>FALSE</BLOCK>
<BLOCK_TIMEOUT>180</BLOCK_TIMEOUT>
<HAS_RESPONSE>TRUE</HAS_RESPONSE>
</TRANSACTION>
Example Response:
<RESPONSE>
<BLOCK_TIMEOUT>180</BLOCK_TIMEOUT>
<DEVICE_RESPONSE_HEX>02,58,42,41,54,43,48,1C,1E,58,49,46,4D,1C,31,1E,58
,53,46,4D,1C,31,03,01</DEVICE_RESPONSE_HEX>
<DEVICEPORT>9001</DEVICEPORT>
<DEVICEIP>192.168.2.110</DEVICEIP>
<FUNCTION_TYPE>ETIM_SYSTEM</FUNCTION_TYPE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<RESULT_CODE>-1</RESULT_CODE>
<COMMAND>MX_PASSTHRU</COMMAND>
<BLOCK>FALSE</BLOCK>
<RESULT>SUCCESS</RESULT>
</RESPONSE>
The decoded DEVICE_RESPONSE_HEX is
<STX>XBATCH<FS><RS>XIFM<FS>1<RS>XSFM<FS>1<ETX><SOH>
Select Provider
1. Once the BIN Conversion Utility has been launched, it prompts to select the Type of Provider:
Bank Of America or Paymentech or Fifth Third Debit Card or First Data.
2. Click to select the appropriate Type of Provider.
3. Click Next to continue.
If you chose First Data as your provider in the previous step, you will be prompted to select the source
of your BIN file: FTP or Local System.
If you select Local System you will see the screen above.
FTP Settings
If you did not choose First Data as your provider, or if you chose First Data as your provider and
selected the Local System option, skip to the next page.
If you chose First Data as your provider and selected the FTP option for the source of your BIN file, you
will be prompted to enter the following FTP settings:
FTP Server FTP Server name or IP
FTP User Name Valid FTP user name
FTP Password Valid FTP password
Port The FTP Port. The conventional FTP port is 21. Please check with the BIN data provider before
changing the default value
File Name The BIN Data file name to be downloaded from the FTP Server
FTP Connect Timeout The timeout value. (IMPORTANT NOTE: The default value is 60 seconds. For
larger files, or on slower data connections, please increase the timeout value.)
Click Next to continue.
After the file is downloaded from First Data, you can go back and use the Local System option to run
the conversion.
If an error is displayed, there may be HTML or other unnecessary data that was not stripped from the
file. Verify this, and select Ignore to continue.
Some files may have three or more of these types of records at the beginning and at the end of the
file. It is best to edit the file before passing it to the BIN Conversion Utility in order to avoid these
errors.
A Saved screen will appear, listing the Number of Records Added, Number of Duplicate Records Found,
and Number of Invalid Records Found. Click Finish to exit.
Note
Note
Note
There may be cases when you do not want signature capture prompted on the terminal
for example, a COMPLETION done in shipping when customer is not present or a
REF_TROUTD transaction. In these cases, simply do not include device IP address or Port
with the transaction.
If you wish to prompt for signature capture outside of a payment transaction (e.g., to
waive a warranty), you can send the prompt as a standalone device command. See Chapter
5 Integration, Direct Device Transactions for more information.
Note
Generally, the errors originating from eTIM develop from configuration, environment, or
integration issues requiring operator intervention (see section eTIM Error Handling).
eTIM allows PAYware Connect to handle most errors (see section PAYware Connect Result
Codes).
Note
You must review error results in conjunction with RESPONSE_TEXT (see below).
Result Code
eTIM generates one of two RESULT_CODEs:
-1 (Success - commands that do not require a message to PWC return a RESULT_CODE = -1,
RESULT = SUCCESS upon successful execution)
990099 (Error originating from eTIM see RESPONSE_TEXT for specifics)
Result
eTIM generates the following RESULTs:
SUCCESS = Success
ERROR = General error (may be from PAYware Connect or from eTIM)
CANCELED = Cancelation
DEVICE_ERROR = Error passed from the device
INTERNAL_ERROR = Unexpected execution route in eTIM (things that should not happen)
UNKNOWN = Unknown (last ditch effort to return a response to the POS)
PARAM_ERROR = Parameter error or unsupported command
Response Text
The RESPONSE_TEXT should give a clear indication of the problem (also recorded in the logs).
The most common RESPONSE_TEXT responses include:
SUCCESS
SUCCESS (operation-specific text)
CANCELED
- CANCELED BY %1 (Example: customer canceled at signature screen)
DEVICE_ERROR
- DEVICE IS BUSY (Example: device had two requeststhis is second)
- Device configuration error: %1
- Device connection failed/lost
- Device is required
- Device operation failed while %1
- Configuration error: %1
- UNABLE to connect to %1
ERROR
- {environmental}
- Client ID Exception: %1
INTERNAL_ERROR
- Missing data while %1
- Received no data while %1
- Received too much data while %1
- Unexpected data while %1
PARAM_ERROR
- %1 not allowed for %2
- %1 is not a valid value (Example: DEVICEIP is not a valid value)
- %1 is required
- Expected %1 parameters received %2 while %3
- UNSUPPORTED COMMAND
- Received insufficient data while %1
Note
The result codes listed below are the most common. For a full list of result/status codes,
refer to the PAYware Connect Integration Guide.
RESULT_CODE
RESULT
Comments
-2
-1
SUCCESS
UNKNOWN
Unknown result
SETTLED
CAPTURED
APPROVED
DECLINED
VOIDED
10
COMPLETED
16
PARTCOMP
Partial completion
17
TIP_MODIFIED
Tip modification
21
Settlement Scheduled
93
97
1010
Invalid Amount
2029999
Authentication Error
Kernel
MX 760
MX0004US.c
RFS00020 (100616)
MX 830
MX0003US
MX 850
MX0004US
MX 860
MX0007US
RFS00016*
SP 016.05.01
RFS00017*
SP 017.01.01
RFS00018
MX 870
MX0007US
RFS00018
MX 880
MX0007US
RFS00018
MX 915
MX200001
MX 925
MX200001
RFS1.09
Build 2012065
RFS1.0.9.0104
Build 20120625-SC
3.0.1
2013 VeriFone, Inc. All rights reserved. VeriFone and the VeriFone logo are either trademarks or registered trademarks of VeriFone in the United States and/or other countries. All other trademarks or brand
names are the properties of their respective holders. All features and specifications are subject to change without notice. Reproduction or posting of this document without prior VeriFone approval is
prohibited.
5/11 00000 Rev A FS
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies: