SIM Integration Guide - Verifone Support Portal

Transcription

PAYware SIM
Secure Integration
Method Device Control
Version 2.0.2.4
© Copyright 2009. VeriFone, Inc. All rights reserved.
Notice
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.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the
information herein; these changes will be incorporated in new editions of the publication. VeriFone may make
improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without
notice.
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.
Printed in the United States of America.
Copyright  2010 VeriFone, Inc. All rights reserved. VeriFone, the VeriFone logo, PAYware, 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 part of this publication may be copied, distributed, stored in a retrieval system, translated into any human or computer
language, transmitted in any form or by any means without prior written consent of VeriFone, Inc.
 VeriFone, Inc.
8001 Chatham Center Drive, Suite 500
Savannah, Georgia 31405
Development Support: (877) 659-8983
[email protected]
2
Table of Contents
VeriFone PA-DSS Guide: PAYware PC, PAYware Transact, and PCCharge........................... 5
Introduction and Scope ............................................................................... 5
Applicability ............................................................................................ 5
Distribution and Updates ............................................................................. 5
What does PA-DSS mean to you? .................................................................... 6
Third Party Applications .............................................................................. 6
PA-DSS Guidelines ..................................................................................... 7
More Information .................................................................................... 13
PA-DSS Requirements Reference .................................................................. 13
Overview...................................................................................................... 15
PAYware Secure Integration Method (PAYware SIM) Control ........................................ 15
Supported Operating Systems ..................................................................... 15
Features ...................................................................................................... 16
Supported Hardware ........................................................................................ 17
PIN pads ............................................................................................... 17
MX Passthrough....................................................................................... 17
USB HID Format Card Readers ..................................................................... 19
VeriFone SIM.DLL ............................................................................................ 21
System Requirements ............................................................................... 21
Install / Uninstall Documentation ................................................................ 21
Referencing the Control ............................................................................ 21
Instantiating the Control ........................................................................... 22
PAYware SIM Dependencies ........................................................................ 23
PAYware SIM Namespace ........................................................................... 23
Pseudo-Code ................................................................................................. 24
Credit Card Sale/Pre-Auth/Debit Sale – Retail/Card Present................................ 25
―Follow-On‖ Transactions .......................................................................... 27
SIM.DLL Integration Method ............................................................................... 29
Device Properties .................................................................................... 29
Device Methods ...................................................................................... 33
Communication Properties ......................................................................... 34
Communication Methods ........................................................................... 35
Merchant Configuration Properties ............................................................... 36
Logging Properties ................................................................................... 37
SIM.DLL General Methods .......................................................................... 38
SIM.DLL Events ....................................................................................... 40
SIM.DLL Error Properties ........................................................................... 40
Integrating to PCCharge ................................................................................... 41
PCCharge Properties ................................................................................ 41
PCCharge Methods ................................................................................... 49
PCCharge Gift Card Integration Properties ..................................................... 52
PCCharge Gift Card Integration Methods ........................................................ 54
Integrating to PAYware PC, PAYware Transact or PAYware Connect .............................. 58
PAYware PC, PAYware Transact/PAYware Connect Properties ............................. 58
PAYware PC, PAYware Transact/PAYware Connect Methods ................................ 69
Appendix A – SIM.DLL Constants .......................................................................... 74
3
Action Codes .......................................................................................... 74
Error Codes ........................................................................................... 78
Appendix B – PCCharge Constants ........................................................................ 79
Address Verification Response Codes ............................................................ 79
CVV2/CVC2/CID Response Codes ................................................................. 79
Processing Company Codes ........................................................................ 80
PCCharge Transaction Result Constants ......................................................... 81
Appendix C – PAYware PC, PAYware Transact and PAYware Connect Constants ................ 83
Address Verification Response Codes ............................................................ 83
CVV2/CVC2/CID Response Codes ................................................................. 83
Payment Media ....................................................................................... 84
PAYware Transact and PAYware Connect Transaction Result Constants .................. 85
Termination Status .................................................................................. 86
Appendix D - Unmanaged Code ........................................................................... 87
Appendix E – TIM: Store and Forward Module .......................................................... 88
Appendix F – VeriShield Protect© ......................................................................... 89
Appendix G - MX Passthrough FormAgent Commands ................................................ 90
Appendix H - Editing/Creating the SIM Form Deck ................................................... 113
4
VeriFone PA-DSS Guide: PAYware PC, PAYware Transact, and
PCCharge
Introduction and Scope
The Payment Card Industry Payment Application Data Security Standard (PCI PA-DSS) is comprised of fourteen
requirements that support the Payment Card Industry Data Security Standard (PCI DSS). The PCI Security Standards
Council (PCI SSC), which was founded by the major card brands in June 2005, set these requirements in order to protect
cardholder payment information. The standards set by the council are enforced by the payment card companies who
established the Council: American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and
Visa, Inc.
PCI PA-DSS is an evolution of Visa‘s Payment Application Best Practices (PABP), which was based on the Visa Cardholder
Information Security Program (CISP). In addition to Visa CISP, PCI DSS combines American Express‘ Data Security Operating
Policy (DSOP), Discover Network‘s Information Security and Compliance (DISC), and MasterCard‘s Site Data Protection
(SDP) into a single comprehensive set of security standards. The transition to PCI PA-DSS was announced in April 2008. In
early October 2008, PCI PA-DSS Version 1.2 was released to align with the PCI DSS Version 1.2, which was released on
October 1, 2008.
Applicability
The PCI PA-DSS applies to any payment application that stores, processes, or transmits cardholder data as part of
authorization or settlement, unless the application would fall under the merchant‘s PCI DSS validation. If your application
runs on Windows XP, you are required to turn off Windows XP System Restore Points. 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 PA-DSS validation is
required for any other payment applications used at the merchant location. It is important to note that PA-DSS validated
payment applications alone do not guarantee PCI DSS compliance. The validated payment application must be
implemented in a PCI DSS compliant environment.
Distribution and Updates
This guide will be provided to VeriFone‘s customers including processors, resellers, ISOs, and integrators along with the
PAYware NA payment applications. It is the responsibility of these parties to ensure the information contained in this
guide is passed on to their customers (the merchant), in order to illustrate the requirements for complying with PCI DSS.
Additional information about PA-DSS and VeriFone‘s PA-DSS Training can be found on our website at
www.verifone.com/padss.
5
What does PA-DSS mean to you?
VeriFone submits its PAYware NA payment applications to an annual PA-DSS audit in order to maintain PA-DSS validation.
In addition, if any major version change is made in any PAYware NA payment applications, VeriFone submits that
application for a full PA-DSS audit again. An example of a major version change would be PCCharge 5.8 moving to
PCCharge 5.9. For minor changes, such as PCCharge 5.8.1 to 5.8.2, an attestation form for minor change revisions is
required. These minor change revisions are submitted to VeriFone‘s Qualified Security Assessor (QSA), which creates a
report to submit to PCI SSC. All validated applications are listed on the PCI SSC web site at
https://www.pcisecuritystandards.org/security_standards/vpa/.
The following table provides opening points to cover in any discussion with merchants on data storage and why a merchant
should use PAYware PC, PAYware Transact, PAYware SIM, PAYware Connect, or PCCharge to assist in maintaining PCI-DSS
compliance.
Cardholder Data
Sensitive
Authentication
Data 2
Data Element
Primary Account Number
Cardholder Name 1
Service Code 1
Expiration Date 1
Full Magnetic Stripe Data3
CAV2/CID/CVC2/CVV2
PIN/PIN Block
Storage
Permitted
Yes
Yes
Yes
Yes
No
No
No
Protection
Required
Yes
Yes 1
Yes 1
Yes 1
N/A
N/A
N/A
PCI DSS Req. 3, 4
Yes
No
No
No
N/A
N/A
N/A
Third Party Applications
A PAYware NA payment application validation does not extend to any external third party application that has integrated
such PAYware NA payment application as the payment engine. The end-to-end transaction process, beginning with entry
into the third party application until the response from the payment engine is returned, must meet the same level of
compliance. In order to claim the third party application is end-to-end compliant, the application would need to be
submitted to a QSA for a full PA-DSS audit.
The use of a PAYware NA payment application also does not exempt a third party integrator‘s application from a PA-DSS
audit. The end user and/or P.O.S. developer can integrate and be compliant in the processing portion of a payment
transaction. A brief review (given below) of the PA-DSS environmental variables that impact the end user merchant can
1
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.
6
help the end user merchant obtain and/or maintain PA-DSS compliance. Environmental variables that could prevent
passing an audit include without limitation issues involving a secure network connection(s), end user setup location
security, users, logging and assigned rights.
PA-DSS Guidelines
The following PA-DSS Guidelines are being provided by VeriFone as a convenience to its customers. These PA-DSS
Guidelines were copied from PCI DSS Program Guide as of March 31, 2009. 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. Sensitive Data Storage Guidelines
1.1
Do not store sensitive authentication data after authorization (even if encrypted):
Sensitive authentication data includes the data as cited in the following Requirements 1.1.1 through 1.1.3.
PCI Data Security Standard Requirement 3.2
Note: By prohibiting storage of sensitive authentication data after authorization, the assumption is that the
transaction has completed the authorization process and the customer has received the final transaction approval.
After authorization has completed, this sensitive authentication data cannot be stored.
1.1.1 After authorization, do not store the full contents of any track from the magnetic stripe (located on the
back of a card, contained in a chip, or elsewhere). This data is alternatively called full track, track, track 1, track
2, and magnetic-stripe data.
In the normal course of business, the following data elements from the magnetic stripe may need to be retained:
 The accountholder‘s name,
 Primary account number (PAN),
 Expiration date, and
 Service code
 To minimize risk, store only those data elements needed for business.
Note: See PCI DSS and PA-DSS Glossary of Terms, Abbreviations, and Acronyms for additional information. PCI Data
Security Standard Requirement 3.2.1
1.1.2 After authorization, do not store the card-validation value or code (three-digit or four-digit 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.
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.
7
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
2. Protect stored cardholder data
2.1
Software vendor must provide guidance to customers regarding purging of cardholder data after expiration
of customer-defined retention period. PCI Data Security Standard Requirement 3.1
2.2
Mask PAN when displayed (the first six and last four digits are the maximum number of digits to be
displayed).
Notes:
 This requirement does not apply to those employees and other parties with a legitimate business need to
see full PAN;
 This requirement does not supersede stricter requirements in place for displays of cardholder data—for
example, for point-of-sale (POS) receipts. PCI Data Security Standard Requirement 3.3
2.3
Render PAN, at a minimum, unreadable anywhere it is stored, (including data on portable digital media,
backup media, and in logs) by using any of the following approaches:
 One-way hashes based on strong cryptography
 Truncation
 Index tokens and pads (pads must be securely stored)
 Strong cryptography with associated key management processes and procedures.
The MINIMUM account information that must be rendered unreadable is the PAN. PCI Data Security Standard
Requirement 3.4
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.1
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
8
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.
3. Provide secure authentication features
3.1
The ―out of the box‖ installation of the payment application in place at the completion of the installation
process, must facilitate use of unique user IDs and secure authentication (defined at PCI DSS Requirements 8.1,
8.2, and 8.5.8–8.5.15) for all administrative access and for all access to cardholder data. PCI Data Security
Standard Requirements 8.1, 8.2, and 8.5.8–8.5.15
Note: These password controls are not intended to apply to employees who only have access to one card number
at a time to facilitate a single transaction. These controls are applicable for access by employees with
administrative capabilities, for access to servers with cardholder data, and for access controlled by the payment
application. This requirement applies to the payment application and all associated tools used to view or access
cardholder data.
3.2
Access to PCs, servers, and databases with payment applications must require a unique user ID and secure
authentication. PCI Data Security Standard Requirements 8.1 and 8.2
3.3
Render payment application passwords unreadable during transmission and storage, using strong
cryptography based on approved standards
Note: ―Strong cryptography‖ is defined in PCI DSS and PA-DSS Glossary of Terms, Abbreviations, and Acronyms.
4. Log payment application activity
4.1
At the completion of the installation process, the ―out of the box‖ default installation of the payment
application must log all user access (especially users with administrative privileges), and be able to link all
activities to individual users. PCI Data Security Standard Requirement 10.1
4.2
Payment application must implement an automated audit trail to track and monitor access.
PCI Data Security Standard Requirements 10.2 and 10.3
5. Develop secure payment applications
5.1
Develop all payment applications in accordance with PCI DSS (for example, secure authentication and
logging) and based on industry best practices and incorporate information security throughout the software
development life cycle. These processes must include the following: PCI Data Security Standard Requirement 6.3
5.1.1 Testing of all security patches and system and software configuration changes before
deployment, including but not limited to testing for the following.
5.1.1.1 Validation of all input (to prevent cross-site scripting, injection flaws, malicious file
execution, etc.)
9
5.1.1.2
5.1.1.3
5.1.1.4
5.1.1.5
Validation of
Validation of
Validation of
Validation of
proper error handling
secure cryptographic storage
secure communications
proper role-based access control (RBAC)
5.1.2 Separate development/test, and production environments
5.1.3 Separation of duties between development/test, and production environments
5.1.4 Live PANs are not used for testing or development.
5.1.5 Removal of test data and accounts before production systems become active
5.1.6 Removal of custom payment application accounts, user IDs, and passwords before payment
applications are released to customers
5.1.7 Review of payment application code prior to release to customers after any significant change, to
identify any potential coding vulnerability.
Note: This requirement for code reviews applies to all payment application components (both internal and publicfacing 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:
5.2.1 Cross-site scripting (XSS).
5.2.2 Injection flaws, particularly SQL injection. Also consider LDAP and Xpath injection flaws, as well as
other injection flaws.
5.2.3 Malicious file execution
5.2.4 Insecure direct object references.
5.2.5 Cross-site request forgery (CSRF).
5.2.6 Information leakage and improper error handling
5.2.7 Broken authentication and session management
5.2.8 Insecure cryptographic storage
5.2.9 Insecure communications
5.2.10 Failure to restrict URL access.
Note: The vulnerabilities listed in PA-DSS Requirements 5.2.1 through 5.2.10 and in PCI DSS at 6.5.1 through 6.5.10
were current in the OWASP guide when PCI DSS v1.2 was published. However, if and when the OWASP guide is
updated, the current version must be used for these requirements. PCI Data Security Standard Requirement 6.5
5.3
Software vendor must follow change control procedures for all product software configuration changes. PCI
Data Security Standard Requirement 6.4. The procedures must include the following:
5.3.1
5.3.2
5.3.3
5.3.4
Documentation of impact
Management sign-off by appropriate parties
Testing of operational functionality
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, etc.). PCI Data Security Standard Requirement 2.2.2
10
6. Protect wireless transmissions
6.1
For payment applications using wireless technology, the wireless technology must be implemented
securely.
PCI Data Security Standard Requirements 1.2.3 & 2.1.1
6.2
For payment applications using wireless technology, payment application must facilitate use of industry
best practices (for example, IEEE 802.11i) to implement strong encryption for authentication and transmission.
Payment applications using wireless technology must facilitate the following regarding use of WEP:
 For new wireless implementations, it is prohibited to implement WEP after March 31, 2009.
 For current wireless implementations, it is prohibited to use WEP after June 30, 2010.
7. Test payment applications to address vulnerabilities
7.1
Software vendors must establish a process to identify newly discovered security vulnerabilities (for
example, subscribe to alert services freely available on the Internet) and to test their payment applications for
vulnerabilities. Any underlying software or systems that are provided with or required by the payment application
(for example, web servers, 3rd-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.
8. Facilitate secure network implementation
8.1
The payment application must be able to be implemented into a secure network environment. Application
must not interfere with use of devices, applications, or configurations required for PCI DSS compliance (for
example, payment application cannot interfere with anti-virus protection, firewall configurations, or any other
device, application, or configuration required for PCI DSS compliance). PCI Data Security Standard Requirements 1,
3, 4, 5, and 6.6
9. Cardholder data must never be stored on a server connected to the Internet
9.1
The payment application must be developed such that the database server and web server are not
required to be on the same server, nor is the database server required to be in the DMZ with the web server.
10. Facilitate secure remote software updates
10.1
If payment application updates are delivered via remote access into customers‘ systems, software vendors
must tell customers to turn on remote-access technologies only when needed for downloads from vendor, and to
turn off immediately after download completes. Alternatively, if delivered via VPN or other high-speed
connection, software vendors must advise customers to properly configure a firewall or a personal firewall product
to secure ―always-on‖ connections. PCI Data Security Standard Requirements 1 and 12.3.9
11
11. Facilitate secure remote access to payment application
11.1
The payment application must not interfere with use of a two-factor authentication mechanism. The
payment application must allow for technologies such as RADIUS or TACACS with tokens, or VPN with individual
certificates. PCI Data Security Standard Requirement 8.3
11.2
If the payment application may be accessed remotely, remote access to the payment application must be
authenticated using a two-factor authentication mechanism. PCI Data Security Standard Requirement 8.3
11.3
If vendors, resellers/integrators, or customers can access customers‘ payment applications remotely, the
remote access must be implemented securely. PCI Data Security Standard Requirement 8.3
12. Encrypt sensitive traffic over public networks
12.1
If the payment application sends, or facilitates sending, cardholder data over public networks, the
payment application must support use of strong cryptography and security protocols such as SSL/TLS and Internet
protocol security (IPSEC) to safeguard sensitive cardholder data during transmission over open, public networks.
Examples of open, public networks that are in scope of the PCI DSS are:
 The Internet
 Wireless technologies
 Global System for Mobile Communications (GSM)
 General Packet Radio Service (GPRS)
12.2
The payment application must never send unencrypted PANs by end-user messaging technologies (for
example, e-mail, instant messaging, chat). PCI Data Security Standard Requirement 4.2
13. Encrypt all non-console administrative access
13.1
Instruct customers to encrypt all non-console administrative access using technologies such as SSH, VPN, or
SSL/TLS for web-based management and other non-console administrative access. Telnet or rlogin must never be
used for administrative access. PCI Data Security Standard Requirement 2.3
14. Maintain instructional documentation and training programs for customers, resellers, and
integrators
14.1
Develop, maintain, and disseminate a PA-DSS Implementation Guide(s) for customers, resellers, and
integrators that accomplishes the following:
14.1.1 Addresses all requirements in this document wherever the PA-DSS Implementation Guide is
referenced.
14.1.2 Includes a review at least annually and updates to keep the documentation current with all major
and minor software changes as well as with changes to the requirements in this document.
14.2
Develop and implement training and communication programs to ensure payment application resellers and
integrators know how to implement the payment application and related systems and networks according to the
PA-DSS Implementation Guide and in a PCI DSS-compliant manner.
14.2.1 Update the training materials on an annual basis and whenever new payment
application versions are released.
12
More Information

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

WARNING: Although VeriFone, Inc. has designed SIM.DLL to properly secure credit card cardholder
information according to PCI guidelines, it is ultimately the merchant’s responsibility to secure the
system on which SIM.DLL resides and the environment in which it is used.
PA-DSS Requirements Reference
The following DSS Requirements were referenced in this document:
DSS Requirement
1
2
3
4
6
9
10
11
12
13
14
DSS Sub-requirement(s)
1.1.4, 1.1.5, 1.1.6
2.1
3.1, 3.2, 3.3
4.1 4.2
6.1
9.1
10.1
11.2, 11.3
12.1, 12.2
13.1
14.2
13
Document History: 1.0.0.27
Revision Author Date
Description
1.0.0.20 CC.
04/20/2008 Consolidate documents.
1.0.0.21 TH.
04/28/2008 Format revisions.
1.0.0.22 AW.
05/20/2008 PABP Updates
1.0.0.23 MN.
06/21/2008 Document Updates.
1.0.0.24 PG.
1.0.0.25 KM.
1.0.0.26 TH.
01/08/2009 PA-DSS Update, Document Updates.
1.0.0.27 MM.
02/10/2009 Document formatting updates.
2.0.0.0
TH.
4/03/2009
2.0.0.1
SP.
2.0.0.1
TH.
11/11/2009 Updated Action Codes in the Appendices.
PA-DSS Update
2.0.0.1a TH.
11/16/2009 Updated CommMethod, Added Note to Libusb-win32, added Vx810 Canadian to device lists.
2.0.0.1b TH.
01/07/2010
2.0.2.4
03/01/2010
TH.
Updated Amount, CashBack, and GratuityAmount properties to reflect correct totals for PCCharge vs.
PAYware product lines.
14
Overview
PAYware Secure Integration Method (PAYware SIM) Control
PAYware SIM is a comprehensive ActiveX control that provides a single interface to simply and securely integrate Windowsbased POS systems with VeriFone‘s complete portfolio of payment engines and PIN pads. PAYware SIM is designed to allow
developers to enable processing of Credit, Debit, EBT, Gift and Settlement transactions to VeriFone‘s four payment engine
services: PAYware PC, PCCharge, PAYware Transact, and PAYware Connect. Signature capture is also available via
VeriFone MX series terminals.
PAYware SIM is similar to the Device.ocx and the PSCharge.dll included in the PCCharge DevKit. PAYware SIM combines
the functionality of both controls, while also giving access to VeriFone‘s other payment engines: PAYware PC, PAYware
Transact and PAYware Connect.
Supported Operating Systems





Vista Business Edition (32-bit)
Vista Home Premium (32-bit)
Vista Home Basic Edition (32-bit)
Windows XP Professional Edition (32-bit)
Windows 2003 Server Edition (32-bit)
Note: Please contact Developer Support for information regarding 64-bit Operating Systems.
15
Features
PAYware SIM extends many of the features previously offered by the device.ocx and the PSCharge.dll. It also adds value
through the following features:
Simplified



PAYware SIM is designed to take much of the integration to the devices and payment engines out of the
developer‘s hands.
PAYware SIM handles all PIN pad communication, payment engine message building, and socket or HTTP
communications to the payment engine. The developer is only responsible for setting the transaction, merchant,
device, and communication properties.
An extensive sample is provided to aid integrators with coding their application.
Flexible






PAYware SIM supports the PAYware PC, PCCharge, PAYware Transact, and PAYware Connect APIs. It allows for
simple transitioning to each payment engine.
PAYware SIM supports several popular VeriFone PIN pads and allows for card swipe and PIN entry extraction for
processing.
Supports all processors that are supported by the four payment engines.
Supports Retail, Mail Order, Restaurant, and Ecommerce business types.
Supports Credit, Debit, Gift, EBT, and Settlement transaction types.
Signature capture is available when using PAYware SIM with VeriFone MX series terminals.
Other Features




Utilizes the features of Microsoft‘s .NET 3.0 framework. This provides less dependency on third party controls.
Supports SSL (Secure Socket Layer) connectivity to the payment engines for added security.
Vast error handling.
Contains optional, configurable logging as an additional troubleshooting tool.
16
Supported Hardware
PIN pads
PAYware SIM allows integration to PIN pads connected to the serial port. Currently, PAYware SIM supports the following
devices:













VeriFone 101/1000 (PIN entry only)
VeriFone 2000 (Card Swipe and PIN entry only)
VeriFone SC 5000 (Card Swipe and Pin Entry only, SC 5000 with VeriFone 2000 emulation only)
VeriFone MX830*
VeriFone MX850*
VeriFone MX860*
VeriFone MX870*
VeriFone MX860 (MX Download 1.4 required)
x
VeriFone V 810 with Duet baset
x
VeriFone V 810 (XPI interface, US Debit only) t
VeriFone SC 5000 (Interac Canadian Debit)
x
VeriFone V 810 with Duet base (Interac Canadian Debit)t
x
VeriFone V 810 (XPI interface, Interac Canadian Debit) t
*MX Series terminals will need to be configured with the proper forms. To obtain forms and upload instructions, please
contact Development Support at 1-877-659-8983.
x
t
Minimum requirements for using a V 810 and/or Duet:
 OS:
QG0011A0
 App:
XPI 3.10a
MX Passthrough
PAYware SIM provides an interface to send FormAgent/PAYware Vision commands to the MX devices. For a list of
commands, please consult the FormAgent and PAYware Vision API documentation or see Appendix D on page 90.
New Methods and Properties for MX Passthrough (See Device Properties and Methods beginning on page 32):
 Method
 SendMXCommand
 RetrieveMultiMXResponse
 Properties
 Command
 ResponseExpected
 WaitForFormEvent
 FormEventTimeout
17
Example scenario using detailing response handling:
POS sends a command to show form with buttons on it and request PAYware SIM to wait for a response.
SIM.SendMxCommand(<stx>XSFM RETR_YN<etx>, True, True, 60)
One of three actions could occur:
1. The MX returns a response. PAYware SIM stores that response and the subsequent event occurs. Returned response
to the method would be something like this:
<stx>XSFM<fs>1<etx><gs><stx>XEVT<fs>2<fs>2<fs>0<fs>RETR_YN<etx>
u
2. The MX returns a response. PAYware SIM stores that response but the MX fail to response on the subsequent form
event. Returned response to the method would be something like this:
<stx>XSFM<fs>1<etx><gs>-1
3. The MX fails to return a response to the initial command. Returned response to the method would be this:
-1
***<stx>,<etx>,<fs>, and <gs> are ASCII representations
18
USB HID Format Card Readers
PAYware SIM now provides integration with independent card swipe devices. Integrators will be able to use USB HID format
devices. The benefit to using an HID device is that it will send the encrypted card swipe data directly to PAYware SIM. This
isolates the card data from the POS. This was previously only possible through a PIN pad with an integrated card swipe.
This empowers integrators to develop their applications using a wider range of hardware integration.
Prerequisites required in conjunction with SIM.DLL in order to use USB HID devices:
Libusb-win32 driver from Sourceforge.net:
http://sourceforge.net/project/showfiles.php?group_id=78138&package_id=79216
Note: Users with Windows XP and earlier should download Libusb-win32 driver version 0.1.12.1. Users with
Windows Vista or higher should download Libusb-win32 driver version 0.1.10.1.
Dependencies required in conjunction with SIM.DLL in order to use USB HID devices:



nunit.framework.dll
USB_LIB.dll
USBHIDDRIVER.dll
Steps to Integrate a USB HID device with PAYware SIM:
1.
2.
3.
4.
5.
Set UseUSBCardReader = true
Call GetUSBDeviceList, which will return a list of all USB/HID devices that are attached to the PC.
Set the USBDeviceIndex to the index number of the desired device from the list returned in step two.
Set all non-card related transaction properties in PAYware SIM then call the Process function.
PAYware SIM will now wait for a card swipe from the configured USB/HID device for the allotted amount of time
set in the SwipeTimeout property.
6. Swipe a card through the USB/HID device. The CardSwipe event will fire, at which time the integrated application
is able to gather the masked card, expiration date, and cardholder name by calling the various ―Get‖ methods.
7. PAYware SIM will continue to process the transaction.
The card information may be also gathered prior to calling the process routine by following steps 1-3 and then calling the
RequestCardSwipe method of PAYware SIM. Then continue with step 4-7.
Note
PAYware SIM will only support USB HID format devices. It does not support USB HID
Keyboard wedges. Some USB HID Keyboard wedges can be reconfigured to be true USB HID
formatted devices. Please consult the USB HID manufacturer‘s documentation on
instructions for doing this.

PAYware SIM supports POS Keyboards with built-in card swipe devices; however, that card
swipe device must also be reconfigured to USB HID format.
19
Code Example – Using a combo box to gather and set USB HID device:
SIM.UseUSBCardReader = True
Dim DeviceList As New Array()
DeviceList = SIM.GetUSBDeviceList
For i As Integer = 0 To DeviceList.Count - 1
cboUSBDevices.Items.Add(DeviceList(i))
Next
.USBDeviceIndex = cboUSBDevices.SelectedIndex
20
VeriFone SIM.DLL
SIM.DLL is provided with PAYware SIM. The control allows developers to access the various properties and methods
necessary to integrate with the payment engines and the PIN pad devices.
A comprehensive code sample and source code can be found in the SIM Sample Source Code folder. A sample executable
can be found in the SIM Sample Application folder. The files that need to be deployed with SIM.DLL can be found in the
SIM Deployment Modules folder. For any questions on the source code, sample executable, or deployment modules, please
contact Development Support at 1-877-659-8983.
System Requirements
When integrating or deploying this control it is required that the machine has the following:
 .NET Framework 3.0 or higher installed on the machine
 Microsoft.ApplicationBlocks.ConfigurationManagement.DLL
 Microsoft.ApplicationBlocks.ConfigurationManagement.Interfaces.dll
Install / Uninstall Documentation
IMPORTANT: It is important to note SIM.DLL is deployed as part of an integrated solution. This solution is designed and
created by a developer in order to integrate their product with PCCharge, PAYware PC, PAYware Connect, or PAYware
Transact. As such, the SIM.DLL has no devoted installer. It is the sole discretion and responsibility of the integrator to
meet necessary compliance to create and maintain proper install / uninstall documentation for the product that includes
SIM.DLL.
Referencing the Control
Each development language has a different way of referencing ActiveX control. For example,
In Microsoft‘s Visual Studio 2005, follow the procedure below:
1. Choose Project | My Project Properties from the menu bar, where My Project is the name of your project.
2. On the left side, click on the References tab.
3. Click on the Add button. This will display a dialog box that has several options for finding the SIM.DLL. Clicking on
the Browse option is probably easiest. This will allow you to browse to the location of the SIM.DLL control. Once
you add the reference, you will see ―VeriFone Secure Integration Method Device‖ in the References list. The
control is now available for use.
If Microsoft Visual Studio 2005 is not being used, please refer to the language documentation for referencing ActiveX
controls or libraries.
21
Instantiating the Control
SIM.DLL has two instantiation options from which to choose. If you would like to initialize the PIN pad, you may do so by
instantiating the control as follows:
For PINpad 1000, PINpad 2000, Omni 3730 or SC 5000:
 Private WithEvents Charge As New SIM.Charge(―Com Port‖, ―Baud‖, ―Parity‖, ―DataBits‖, ―Device Name‖,
―Logging Level‖)
For MX Devices using IP:

Private WithEvents Charge As New SIM.Charge(ByVal IPAddress As String, ByVal Port As String, ByVal SSL As
Boolean, ByVal SSLCertificate As String, ByVal Timeout As String, ByVal Device As DeviceType, ByVal LoggingLevel
As Integer)
Initializing the PIN pad on instantiation allows the customer to swipe and initiate a transaction prior to the POS passing the
transaction to the PIN pad. If you wish to not initialize the PIN pad on instantiation, use the following:

Private WithEvents Charge As New SIM.Charge ()
The PIN pad will be initialized on the first transaction.
22
PAYware SIM Dependencies
The following files must be registered and are required by PAYware SIM to perform various functions.
Dependency
Description
SaxComm8.ocx
Required for components that use the COM ports in Windows
Interop.SaxComm8.dll
Required for components that use the COM ports in Windows
USB_LIB.dll
Required for USB HID Devices
USBHIDDRIVER.dll
Nunit.framework.dll
PAYware SIM Namespace
A a new NameSpace and Class to centralize common Constants and Methods, and make them available to integrators.
Namespace/Class
Description
SIM.VFI.Utils.StringUtils.CharConstants
Constants for common control characters.
SIM.VFI.Utils.StringUtils.AddLRC
Calculates and appends the LRC value to a string.
SIM.VFI.Utils.StringUtils.GetLRC
Calculates the LRC value for a string.
SIM.VFI.Utils.StringUtils.RegexConstants
Constants doe commonly used regular expressions.
23
Pseudo-Code
This section includes several programming algorithms that may be followed when using SIM.DLL. These examples are
intended to be general pseudo-code type of examples and are not intended to reflect any one particular programming
environment.
The examples in this section represent the most common transactions that integrators may want to support when enabling
payment processing in their application. Integrators can refer to the API, code samples, or contact Development support
for questions about any of the transactions that are not covered in this section.
24
Credit Card Sale/Pre-Auth/Debit Sale – Retail/Card Present
This algorithm demonstrates the coding required to perform a swiped credit card transaction in a retail environment. This
example uses an SC 5000 device. See Instantiating the control for use with other devices.
‗Create the object
Private WithEvents Charge As New SIM.Charge (―COM1‖, ―1200‖ , ―E‖, ―7‖, SIM.Charge.DeviceType.ppdSC5000, ―3‖)
At this point, you want to gather card swipe information. When a customer swipes his or her card through the device, the
―CardSwipe‖ event is fired.

Note
The gather card swipe routine is completely optional. SIM.DLL will actually store that data
through the duration of the transaction and send that data when Process is called. This
step is only necessary for data gathering purposes. The card number will be returned in
masked form, only displaying the first 6 and last 4 digits of the card number.
‘Gather Card Swipe
Private Sub Charge_CardSwipe() Handles Charge.CardSwipe
Card = Charge.GetCard
ExpDate = Charge.GetExpDate
Member = Charge.GetMember
End Sub
This data can be saved for when the ―Process‖ function is called.
Private Sub Process()
With Charge
‘Set the Payment Engine/Merchant Configuration properties
‗For PCCharge
.PaymentEngine = SIM.Charge.PaymentSoftware.PCCharge
.MerchantNumber = ―999999999911‖
.Processor = ―NPC‖
.UserID = ―User1‖
‗For PAYware Transact/Payware PC
.PaymentEngine = SIM.Charge.PaymentSoftware.RiTA_PAYware
.ClientID = ―100040001‖
.UserID = ―MANAGER‖
.UserPW = ―Test123%‖
25
‗For PAYware Connect
.PaymentEngine = SIM.Charge.PaymentSoftware.IPCharge
.ClientID = ―100040001‖
.UserPW = ―rita‖
.MerchantKey = ―123457890‖
‘Set the required Communication Properties”
‗For PAYware Transact/PAYware PC/PCCharge
.IPAddress = ―127.0.0.1‖
.Port = ―31419‖
.CommMethod = SIM.Charge.CommMethod.IP
‘Set the required Device properties. Note: that if you already instantiated the device with the properties included as this
example does above, then this portion of code is not necessary.
.Baud = ―1200‖
.Parity = ―E‖
.Databits = ―7‖
.Device = SIM.Charge.DeviceType.ppdVerifone_SC5000
‘Set the transaction properties. This is the basic, minimum data for a transaction. There are many other properties
available. Please refer to the properties section for a list of those properties
.Amount = ―25.00‖
.Cashback = ―10.00‖
‗For Debit
.Ticket = ―123456‖
.Action = SIM.Charge.Command.Credit_Sale
‗Miscellaneous properties
.Timeout = ―60‖
.SwipeTimeout = ―120‖
.LoggingLevel = ―3‖
‗ 3 = highest, 0 = Off
.MaxLogsize = ―3‖
‗in MB
‘Process the transaction
If .Process Then
Print .GetResult
Print .GetAuthCode
Print .GetReference
Print .GetResultCode
Print .GetTroutD
Print .GetResponseText
Else
MsgBox("" & .ErrorCode & ": " & .ErrorDescription)
End If
‘Clear the properties
.ClearProps()
26
“Follow-On” Transactions
This algorithm demonstrates how to perform ―follow-on‖ transactions. ―Follow-on‖ transactions are transactions that
update, modify, or void a previous transaction. For instance, a post-auth is a ―follow-on‖ of a pre-auth. A void is a
―follow-on‖ of a sale or any other completed transaction. A gratuity is a ―follow-on‖ of a sale, etc.
For ‖follow-on‖ transactions, all that is necessary for submission to the payment engine is the TroutD, which was returned
on the original transaction, and the amount, if the amount needs to be updated. (Voids do not require an amount.) The
TroutD is a unique identifier that allows the payment engine to reference the original transaction. The amount is only
necessary on post-auths that are changing the original pre-auth amount, and gratuity transactions.
‗Create the object
Private WithEvents Charge As New SIM.Charge ()
Private Sub Process()
With Charge
‘Set the Payment Engine/Merchant Configuration properties
‗For PCCharge
.PaymentEngine = SIM.Charge.Payment.PaymentSoftware.PCCharge
.MerchantNumber = ―999999999911‖
.Processor = ―NPC‖
.UserID = ―User1‖
‗For PAYware Transact/Payware PC
.PaymentEngine = SIM.Charge.PaymentSoftware.RiTA_PAYware
.ClientID = ―100040001‖
‗For PAYware Connect
.PaymentEngine = SIM.Charge.Payment.PaymentSoftware.IPCharge
.ClientID = ―100040001‖
.MerchantKey = ―123457890‖
‘Set the required Communication Properties”
‗For PAYware Transact/PAYware PC/PCCharge
.IPAddress = ―127.0.0.1‖
.Port = ―31419‖
.SSL = True
.CommMethod = SIM.Charge.CommMethod.IP
27
‘Set the transaction properties.
.Amount = ―25.00‖
‗For post-auths only
.GratuityAmount = ―5.00‖
‗For gratuity/add-tip trans
.TroutD = ―1492‖
‗for PCCharge follow-on trans
.RefTroutD = ―35‖
‗For PAYware Connect, PAYware Transact, and PAYware PC follow-on trans
.Action = SIM.Charge.Command.Credit_Post_Auth
‗Miscelaneous properties
.Timeout = ―60‖
.LoggingLevel = ―3‖
‗ 3 = highest, 0 = Off
.MaxLogsize = ―3‖
‗in MB
‘Process the transaction
If .Process Then
Print .GetResult
Print .GetAuthCode
Print .GetReference
Print .GetResultCode
Print .GetTroutD
Print .GetResponseText
Else
MsgBox("" & .ErrorCode & ": " & .ErrorDescription)
End If
‘Clear the properties
.ClearProps()
28
SIM.DLL Integration Method
The previous section demonstrates how to code using the SIM.DLL. This section will explain in further detail the properties
of PAYware SIM.
Device Properties
This portion describes the properties used in combination with the device. These properties are necessary only when the
device has not been instantiated to initialize. Initializing the PIN pad on instantiation allows the customer to swipe the
card at any time to initiate a transaction.

Note: We have identified IP connectivity (MxCommSetting = 1) to be the optimal way of
communicating with an Mx Device. If the integrator chooses to use Serial (MxCommSetting = 0)
there are other settings that must be taken into consideration prior to initializing the Mx Device.
Please see note and screenshot below the Device Properties table for more information.
Property Name
Data Type
Description
Baud
String
Baud rate (Example: ―1200‖)
Databits
String
Databits (Example: ―7‖ or ―8‖)
Device
Enum
The PIN pad that will be used. Specify this parameter by using a
numerical value (or an enumerated value if the programming language
being used supports enumerated values).
Valid values:
0 (ppdVerifone_1000) – Verifone 101 or 1000
1 (ppdVerifone_2000) – Verifone 2000
2 (ppdVerifone_3730) – Verifone Omni 3730
3 (ppdVerifone_Mx830) –Verifone MX830
6 (ppdVerifone_Mx870) – Verifone MX870
7 (ppdVerifone_SC5000) – Verifone SC5000 (w/ 2000 emulation)
8 (ppdVerifone_SC5000_Interac) – VeriFone SC5000 Canadian Debit
9 (ppdVerifone_Vx810) – Verifone Vx810
10 (ppdVerifone_Vx810_Duet) – Verifone Vx810 Duet
11 (ppdVerifone_Vx810_Interac) – Verifone Vx810 Canadian Debit
12 (ppdVerifone_Vx810_Duet_Interac) – Verifone Vx810 Duet Canadian
Debit.
Example: Device = 0
DisplayString
String
For VeriFone MX Devices only. Sets message that will display on PIN
pad.
Parity
String
Parity (―E‖ for even, ―O‖ for odd, ―N‖ for none)
ComPort
String
Number of the COM port to be used (Example: ―COM1‖)
MxCommSetting
Enum
Sets the connection type of the MX Device (Defaults to Serial).
Valid Values:
0 Serial
1 IP
Example: MxCommSetting = 0
MxIPAddress
String
IP Address of the MX Device.
29
Property Name
Data Type
Description
MxPort
String
Port of the MX Device
The name of the SSL certificate used to authenticate with the MX
Device. This value should be the ―Issued To‖ name in the MMC console.
This value is optional. If no value is passed, the SIM will use the first
certificate available in the Personal Certificate Store.
MxSSLCertificate
String
MxSSL
Boolean
Set to TRUE to communicate with the MX Device via SSL (Defaults to
False).
The name of the SSL certificate used to authenticate with the BIN
Manager. This value should be the ―Issued To‖ name in the MMC
console. This value is optional. If no value is passed, the SIM will use
the first certificate available in the Personal Certificate Store.
BinManagerSSLCertificate
String
SwipeTimeOut
String
The amount of time, in seconds, to wait for a customer to swipe the
card through the device. This timer starts when the Process method is
called.
PrintReceipts
String
The text to be printed on the receipt. This method is for the Omni
3730 only.
Boolean
Set to false by default. This will prompt the cardholder to enter a tip
amount on the PIN pad for Sale transactions when set to true. Set to
false if you wish to not have the cardholder be prompted. (Interac
Only)
Boolean
Set to false by default. This will prompt the cardholder to confirm the
surcharge amount, which is indicated by the Surcharge property of the
SIM.DLL. Set to false if you wish to not have the cardholder be
prompted. The ―Process‖ function will return false and the error code
and error description will contain a message stating that the Surcharge
amount was rejected by the cardholder. (Interac Only)
Boolean
Set to true by default. This will prompt the cardholder to enter a
signature on the device if the transaction captured. The signature will
be returned in the GetSignatureData property. Set to false if you wish
to not have the cardholder be prompted. Note: SIM.DLL uses the
SwipeTimeout setting as a value for the signature timeout. If the
cardholder fails to enter their signature in that set amount of time, or
they hit the cancel or clear button, SIM.DLL will issue a void for that
transaction. The error code and error description will be shown and
state whether the void was successful or not. (MX Devices only)
Boolean
Set to false by default. This will prompt the cardholder verify that the
amount of the transaction is correct when set to true. Set to false if
you wish to not have the cardholder be prompted. (MX Only)
PromptForTip
*
PromptForSurcharge
PromptForSigCap
*
*
PromptForAmountConfimation
*
30
Property Name
PromptForCashback
*
Data Type
Description
Boolean
Set to false by default. This will prompt the cardholder to enter a
cashback amount on the PIN pad for Sale transactions when set to true.
Set to false if you wish to not have the cardholder be prompted.
(Interac & MX Only). NOTE: On the MX the cardholder will only be
prompted on Debit and EBT transactions. Also, the CashBackLimit
property should be set when using the property.
Set to false by default. This will prompt the cardholder select a
payment type when set to true. Set to false if you wish to not have the
cardholder be prompted. (MX Only)
NOTE: If only 1 or no payment types are selected, it will NOT prompt
the customer for a payment type selection.
PromptForPaymentType
*
Boolean
NOTE: The selectable payment types will be determined by the
―Enable‖ properties of each payment type. The integrator should send
a credit transaction as the initial payment type. For instance, if the
transaction is a sale, send a credit sale. If the cardholder select debit,
the transaction type will be changed. Payment type selection only
refers to the following transactions:
Debit_Sale, Debit_Return, EBT_Purchase, EBT_Food_Stamp_Purchase,
EBT_Cash_Withdrawal, EBT_Food_Stamp_Return, EBT_Inquiry,
Credit_Pre_Auth, Credit_Voice_Auth, Credit_Sale,
Credit_Sale_with_Gratuity, Credit_Commercial_Card_Return,
Credit_Return, Gift_PreAuth, Gift_Redemption, Gift_Refund
Boolean
Set to false by default. This will reverse (void) the transaction if the
cardholder cancels the signature by hitting the ―clear‖ button on the
screen or if the cardholder does not sign the device in the allotted
timeout period, determined by the SwipeTimeout property. Set to
true to reverse the transaction. (MX Devices only)
Boolean
Set to true by default. This will add credit card as a selectable type
when prompting the cardholder for a payment type when
PromptForPaymentType is set to true.
Boolean
Set to true by default. This will add debit card as a selectable type
Boolean
Set to true by default. This will add EBT as a selectable type when
prompting the cardholder for a payment type when
Boolean
Set to true by default. This will add gift card as a selectable type
String
Sets the maximum cashback amount that cardholder can enter when
PromptForCashback is set to true. DD.CC format. For example,
100.00.
Boolean
Set to true to enable the manual entry of card number and expiration
date on the 3 unsuccessful swipe attempts. Note: For MX use only.
UseUSBCardReader
Boolean
Set to True if the integrated application would prefer that SIM.DLL
gather the card swipe data from the USB/HID device during processing
of a transaction. Defaults to False.
USBDeviceIndex
Integer
The index of the USB/HID device in the Device List, returned by calling
GetUSBDeviceList, which the integrated application would prefer to
use to gather card swipes.
ReverseFailedSignatures
EnableCredit
EnableDebit
EnableEBT
EnableGift
*
*
*
*
*
CashBackLimit
EnableManualCardEntry
*
31
Property Name
Data Type
Description
Command
String
This string will be passed to the MX. It should be in format that the MX
application understands (e.g., Form Agent or PAYware Vision). Please
consult the API documentation of the appropriate application for the
commands available and formats. The command should be wrapped
with an STX and ETX character. An LRC is not necessary as SIM.DLL will
add that itself.
ResponseExpected
Boolean
Set to true if the command being passed to the MX will have a response
as not all commands have a response. This informs SIM.DLL whether or
not to wait for a response.
WaitForFormEvent
Boolean
Set to true if there is an expected form event. In this scenario,
typically a form is displayed with some object that is capable of firing a
form event, such as a button press. In this case, a command of ―Show
Form x‖ would be sent to the MX device. The MX device would
respond with the appropriate response. SIM.DLL will wait for the
subsequent form event response. SIM.DLL will then return the first
response, followed by a group separator (<GS>, Character 29),
followed by the form event response.
FormEventTimeout
String
The number of seconds SIM.DLL should wait for a response from the MX
for form events.
Note: Please adjust the following Windows Com properties prior to initializing an Mx Device using Serial as the
MxCommSetting.
32
Device Methods
Property Name
Data Type
ChangeForm(FormName as
*
String)
String
GetUSBDeviceList
ArrayList
SendMXCommand
String
RetrieveMultiMXResponse
Byte Array
Description
Changes the form to display on the MX device. The FormName is the
name of the form in the form deck loaded on the MX Device.
Note: The value is case sensitive. This method should not be called
while the customer is interacting with the device or a transaction is
processing. This could interfere with the payment process.
Example:
Name of the form to be changed: Welcome
Method called: ChangeForm(Welcome)
Returns an indexed list of product names for all USB/HID devices
attached to the PC.
This method will pass the Command parameter to the MX Device that
is configured in SIM.DLL. The return value is the response from the
MX.
Format: SendMXCommand(Command as string, ResponseExpected
as Boolean, WaitForFormEvent as Boolean, FormEventTimeout
as string)
Some Form Agent Commands will have multiple responses. This
function will return outstanding responses from the MX Device. This
command should be called until the ―more indicator‖ in the MX
response is a value of ―N‖. Example Form Agent commands where
this is applicable are ―S00‖ and ―XPNG‖.
Note: These properties need to be set BEFORE the Process method each time Process is called. InitializePinPad
must return True prior to calling these properties and the Process method.
33
Communication Properties
These communication properties must be set in order for SIM.DLL to know how and where to communicate the transaction
data.
Property Name
CommMethod
Data Type
Description
Enum
The type of communication that will be used.
Valid values:
0 – IP = SIM.Charge.CommType.IP
1 – URL = SIM.Charge.CommType.URL
2 – DIAL = SIM.Charge.CommType.DIAL
Note: Only IP is supported for PCCharge and PAYware Transact. Only
URL and DIAL is supported for PAYware Connect
IPAddress
String
IP Address of the Payment Engine
Port
String
Open port on the server that the payment engine is listening for
transactions on. Refer to the payment engine documentation for
instructions on opening the port.
SSL
Boolean
For use with IP CommMethod only. Enables SSL communication with
the server. SSL must be enabled on the server side as well. Currently
supported by PAYware PC, PAYware Transact and PCCharge.
The name of the SSL certificate used to authenticate with the MX
Device. This value should be the ―Issued To‖ name in the MMC console.
This value is optional. If no value is passed, the SIM will use the first
certificate available in the Personal Certificate Store.
SSLCertificate
String
TimeOut
Long
The number of seconds after which a timeout error will be returned
from the control. The count will start when the Process method is
called. It is highly recommended that integrators review the Payment
Engine documentation about timeouts. Setting the TimeOut value
improperly could cause reconciliation issues and problems such as
double-charging a customer‘s account.
TimeOutInt32
Integer
Allows the integrator to set the transaction timeout in seconds. This is
compatible with using Unmanaged code such as VB6, Delphi, etc.
URL
String
For use with PAYware Connect only: The URL of the PAYware Connect
gateway.
This is used to set the UNC path to the PCCharge directory.
Note: The IP Address and COM port communication settings must still
be used to transmit transactions to PCCharge.
Path
String
Note: This is only needed for PCCharge Integration with Paymentech
Canadian Debit.
Note: SIM.DLL needs to access file on the PCCharge directory during
the processing of a Canadian debit transaction. Please make sure the
PCCharge directory is accessible by the client with appropriate
permissions set.
34
Property Name
Data Type
Description
Modem
String
For use with PAYware Connect only: The TAPI name of the modem to
be used for the transaction.
Note: The URL property must be set for IPC dial transactions. It is used
to build the message header.
DialupPhoneNumber
String
For use with PAYware Connect only: The Number to dial for the
transaction.
UseDialBackup
Boolean
For use with PAYware Connect only: Dial Backup Indicator.
Property Name
Data Type
Description
GetTAPIDeviceList
Array
For use with PAYware Connect only: Returns an array of strings of
TAPI devices found on the machine.
GetTAPIDeviceListAsString
String
For use with PAYware Connect only: Returns a pipe separated string
of TAPI devices found on the machine.
Communication Methods
35
Merchant Configuration Properties
The payment engine must be set in order to build the correct message from the correct API. These properties must be set
in order to inform the payment engine of which merchant the transaction processed against.
Property Name
Data Type
Description
ClientID
String
Required for PAYware PC, PAYware Transact and PAYware Connect:
The ClientID used by the integrator or merchant determines which
merchant account / terminal will be used to process the transaction.
This value is automatically assigned by PAYware Connect, PAYware PC,
and PAYware Transact.
The ClientID value is actually made up of three different pieces of
information: An ACCOUNT number, a SITE number, and a TERMINAL
number.
Note: for PAYware PC users: This value corresponds to the account
setup in the management client or the configuration wizard, the first
account has a client ID of 100010001, if a second client is setup under
that same account the client ID will be 100010002.
Note: for PAYware Connect users: This value can be retrieved on the
completion for the merchant setup by a reseller in the reseller console.
MerchantKey
String
Required For PAYware Connect only: PAYware Connect uses this
field to validate the merchant. The value is provided by VeriFone and
must be submitted with each transaction request.
String
Required For PCCharge only: the Processor or the Merchant Services
Provider issues this number to the merchant. The value set in this
property must match what is set up in the Merchant Setup window of
PCCharge.
String
Required For PCCharge only: The code for the processing company
that will be used to process the transaction. This value can be no more
than four characters and must be capitalized. The processor specified
in this property must be set up with a valid merchant number in
PCCharge. A list of valid processor codes are listed in Appendix A.
Enum
The payment engine that the transaction is to be submitted to.
Valid Values:
0 – PCCharge
1 – RiTA_PAYware
2 – IPCharge (PAYware Connect)
UserID
String
Required for all 4 Engines:
For PCCharge:
Sets the PCCharge user name associated with the transaction. The user
name must be in DOS file format, no spaces. Max Length: 8 characters*
For PAYware PC, PAYware Transact/PAYware Connect:
The User‘s login as assigned by PAYware PC, PAYware Connect or
PAYware Transact. The UserID must have proper permissions to
perform the Command being requested.
UserPW
String
For PAYware PC, PAYware Transact/PAYware Connect only: The
password assigned to the UserID.
EnableBinManager
Boolean
Set to TRUE to use the VeriFone BIN Manager to check the BIN range of
the swiped card. When the card is swiped SIM.DLL will connect with
the VeriFone BIN Manager to check the BIN Manager to determine the
card type.
Note: If this is not enabled SIM.DLL will continue with the transaction
as usually. This is also the case if it is enabled, but unable to connect
to the VeriFone BIN Manager.
BinManagerIPAddress
String
IP Address of the machine where the VeriFone BIN Manager is located.
BinManagerPort
String
Open the port to connect to the VeriFone BIN Manager.
MerchantNumber**
Processor**
PaymentEngine
36
Property Name
Data Type
Description
BinManagerSSL
Boolean
Set to TRUE to connect to the VeriFone BIN Manager via SSL.
CheckCard
Boolean
Defaults to FALSE. Set to TRUE to have SIM.DLL check the validity of
the card number that was either swiped or passed by the Point of Sale
before submitting the card for authorization to the payment engine.
** The user name is used to keep the transaction associated with the correct terminal. It is highly recommended that integrators review the Multi-User
Support section of the PCCharge manual. This section contains detailed information about user names and how they should be implemented.
*** If the ―Use Default Processor‖ option is enabled in the PCCharge preferences, and the Processor and MerchantNumber properties are omitted from the
transaction request, PCCharge will process all transactions using the ―Default Processor‖. The ―Default Processor‖ is defined as the first merchant
number that is set up PCCharge. In addition, Processor and MerchantNumber should not be set when doing follow-on transactions. Refer to the section
Follow On Transactions.
Logging Properties
SIM.DLL contains logging that can be used to help troubleshoot issues. The following properties are related to SIM.DLL
logging. The SIMEvent.log is located in the same directory as the SIM.DLL and viewable through any text editor.
Property Name
LoggingLevel
Data Type
Description
String
This value determines the amount of logging desired.
Valid Values:
0 – Off/No Logging
1 – Errors Only
2 – Information
3 – Detailed Debug
Maximum size of the log. In MB. Example: 3
MaxLogSize
String
Note: Beginning with SIM version 2.0.2.4, once the MaxLogSize is set
the log will not be purged, but backed up to a new file with the
date/time attached to the name.
Example: SIMEvent.log.20100217.114022
37
SIM.DLL General Methods
Method Name
Return Type
Description
CancelTransaction
Boolean
The CancelTransaction method attempts to cancel the transaction in
progress. Calling the CancelTransaction method does not guarantee
that the transaction will be canceled; it simply attempts to cancel
the transaction. It will return false if the transaction has already
been submitted to the server for authorization.
ClearProps
None
Clears all of the transaction properties and resets them to an empty
string. This should be called at the conclusion of each transaction.
This method will also reset the PIN pad to an idle state.
GetCard
String
This method returns the account number when the card is swiped
through the device. This method should be called upon the firing of
the CardSwipe Event. The card number will be returned in masked
form, only displaying the first 6 and last 4 digits of the card number.
GetExpDate
String
This method returns the expiration date when the card is swiped
the CardSwipe Event.
GetEnteredCashBack
String
Returns cashback entered by the cardholder if the
PromptForCashback setting was set to true. This is returned at the
end of the transaction. (Interac & MX only)
GetEnteredTipAmount
String
Returns tip amount entered by the cardholder if the PromptForTip
setting was set to true. This is returned at the end of the
transaction. (Interac only)
GetNewTotal
String
When cashback, tip, and/or surcharge amounts are confirmed by the
cardholder, these amounts are totaled and then passed to the
payment engine. This total amount will be returned in this method
at the end of the transaction. (Interac & MX only)
GetMember
String
This method returns the cardholder name when the card is swiped
the CardSwipe Event.
IsInitialized
Boolean
This method can be called at anytime to determine if the PIN pad is
initialized. Returns True if it is.
InitializePinPad
Boolean
Initializes the PIN pad. Returns TRUE if the initialization was
successful, FALSE if not. Initialize has an optional parameter than
can be passed in that will allow checking of the com port.
KeyLoadRequest
Boolean
This will perform a key synchronization with the host for the SC 5000
Interac PIN pad. This method should only be necessary when first
setting up the PIN pad. (Interac only)
Boolean
This method initiates the transaction. All necessary transaction,
merchant, communication, and device properties should be set prior
to calling this method. This method will return true if the
transaction was successfully submitted to the payment engine and
received a response from the payment engine. Otherwise, it will
return false, at which time the integrator should call .ErrorCode and
.ErrorDesc to determine the reason for the failure.
Process
Returns true if the customer signature was successful. At that time
GetSignatureData should be called to retrieve the signature data
string. Returns false if the customer cancels or the call times-out.
PromptForCustomerSignature
Boolean
Note: It is important that integrators only call this function if they
need to gather signature data outside the transaction. For example
this will allow the MX device to become a general signature device. A
merchant can use this to capture signatures when a customer picks
up an item but they are paying cash. Otherwise allow the SIM.DLL
gather the signature by itself as a normal transaction process.
38
Method Name
Return Type
Description
RequestCardSwipe
None
Prompts the customer to swipe their card. Only to be used with the
MX830, MX850, MX860 and MX870 terminals.
String
This method creates an XML element to be added to the XML
transaction request. This allows a missing Name Value Pair to be
sent.
Example: SetOtherNVP(XMLTAG as String, Value as String)
<XMLTAG>Value</XMLTAG>
None
This method should be called when exiting the integrated application
or prior to destroying SIM.DLL object. This method is responsible for
cleaning up all ports and destroying all internal references of the
SIM.DLL.
SetOtherNVP
Shutdown
Returns signature data in Base64 format. The MX870, MX850 and the
MX830 devices can also be used to capture Cardholder Signature in
Base 64 encoded BMP format data. To enable this feature, the
―Allow Signature Capture‖ option for the MX8xx device must be set
to true. To view the Signature captured, the Base64 encoded data
has to be decoded using the Base64 decode algorithm. The decoded
data can be saved to a BMP file and can be viewed using any image
viewer that supports the BMP format, such as the Paint application
of Windows.
It is the responsibility of the merchant to save the signature image as
desired. The signature is not stored within TIM.
GetSignatureData
String
Note: The MX devices will prompt the customer for their signature
upon a successful (APPROVED or CAPTURED) response for the
following transactions: Credit_Commercial_Card_Sale,
Credit_Pre_Auth, Credit_Voice_Auth, Credit_Sale,
Credit_Sale_with_Gratuity, Credit_Commercial_Card_Return,
Command.Credit_Return. After the customer has signed and presses
the "OK" button on the device, the Process() function will return true
with the normal response properties. At that time, the integrator
can call this method to retrieve the swipe data. If the customer hits
the "Clear" or "Cancel" button when prompted for the signature, or
the signature is not entered in the allotted time (SIM.DLL uses the
SwipeTimeout setting as the signature timeout) SIM.DLL will process
a void for that transaction and return the void results along with an
error code 34 and related error description and raises the error
event. If the void was able to process, the error description will say
as such.
Prompts the customer to manually enter their card number and
expiration date into the device. This should only be done in the
event of a bad card read. This is only for use with the MX series and
the SC 5000(US only). This method will return true if the manual
entry was successful.
RequestManualCardEntry
Boolean
GetCreditCardType
String
Returns Card Issuer.
VerifyCreditCard
String
Returns TRUE if the card passes validity checks.
GetReceipt
String
Note: This method is not required to be called with the MX series of
devices, as those devices will automatically prompt the customer for
manual entry upon 3 unsuccessful card swipes. However, the SC
5000 does not return a failed card swipe response to SIM.DLL.
Therefore this method is required to be called when a manual card
entry is desired for the SC 5000.
Returns receipt data.
Note: Only available for Paymentech Canadian Debit.
39
SIM.DLL Events
Property Name
Description
CardSwipe
This event is fired when a card is swiped through the PIN pad device.
Cancel
This event fires when the customer at the PIN pad device presses the ―Clear‖ or
―Cancel‖ button. This event internal halts the processing of the transaction. The
integrator should restart the transaction if this event fires.
Err
This event is fired when an internal error occurs within SIM.DLL, primarily for PIN
pad problems. When this event fires, the integrator to reset the transaction and
call .ErrorCode and .ErrorDesc to determine the cause of the problem
SIM.DLL Error Properties
Property Name
Return Type Description
ErrorCode
Integer
This property returns an error code if an error was encountered
during the processing, initialization, or use of the PIN pad. Consult
Appendix A for a description of values that may be returned.
ErrorDesc
String
This property returns a string representation of an error if an error
was encountered during the processing, initialization, or use of the
PIN pad. Consult Appendix A for a description of values that may be
returned.
40
Integrating to PCCharge
When integrating to the PCCharge Payment Engine, only these transaction properties should be used.
PCCharge Properties
Property
Data Type
Description
Action
Enum
The action code that identifies what type of transaction will be
performed. Consult the Appendix A for a list of valid values.
Amount
String
The amount of the transaction. Format: DDDDDD.CC. Max Length: 9
characters, including the decimal. The value may not be negative. Do
not use commas. Note: The amount MUST include the decimal point
and the cents even if the amount is a whole dollar amount. Example:
―3.00‖, not ―3‖ or ―3.‖ If sending less than one dollar, the zero
placeholder must be sent as well. Example: ―0.50‖. If the amount is
set to an incorrect format, the Error event will fire after calling the
Send method.
AmxChargeDescription
String
The American Express Charge Description.
This is a general
description describing merchandise: the AMEX representative and the
merchant will decide on an appropriate description. Note: Only
Required for Retail, MOTO and Restaurant transactions when using
AMEX direct settlement or TSYS. Max Length: 23 bytes
AmxDescription_1
String
American Express Description data.
Additional description or
information about merchandise—if populated, should be printed on the
receipt. Note: Only used for Retail transactions when using AMEX
direct settlement. Max Length: 40 bytes
This field is optional and should only be provided if the transaction
will be settled directly with Amex or TSYS.
AmxDescription_2
String
AmxDescription_3
String
AmxDescription_4
String
AuthCode
String
The Authorization code. This value is returned by the issuing bank and
should only be set in a transaction request when processing a PostAuthorization and if the Post-Authorization is being used to add a
Voice-Authorization to the batch or to ―store‖ a Voice-Authorization.
The AuthCode property does not need to be set if the PostAuthorization completes a standard Pre-Authorization using the TroutD
value of the Pre-Authorization.
41
Property
Data Type
Description
Billpay
String
Only valid for Visa debit and credit transactions. It is used to indicate
the transaction is being processed for payment of a bill (utility,
monthly gym dues, etc.) Valid values:
0 – Non-Bill payment transaction
1 – Bill payment transaction
Card
String
The credit card number that will be used when processing the
transaction. Card number must not contain spaces. Please trim field
prior to calling Process. Max Length: 20 characters. Example:
5424180279791765
CashBack
String
The amount of cash back that the customer will receive. This amount
is in addition to value entered in Amount property. For example, if
the total amount of the sale is $10 and the customer has requested $5
cash back, Amount should be set to $10 and CashBack should be set to
$5. The CashBack property should be formatted the same the Amount
property. Max Length: 9 characters. Note: Some processors do not
support the cash back feature.
CardPresent
String
For Retail or Restaurant transactions: Flag that indicates whether
the card was present.
For eCommerce transactions: Flag that indicates what type of
transaction occurred. Valid values:
0 = Card not present, 1 = Card present (for Retail, MOTO, or
Restaurant);
D = Digital goods, P = Physical goods (for eCommerce)
CommercialCardFlag
String
The type of commercial card being submitted. The commercial card
type can be retrieved from the Bin.mdb in the PCCharge directory.
Valid values:
B – Business
P,L,G -- Purchase
C – Corporate
F – Fleet
CustCode
String
Customer code for purchasing/commercial cards. This property must
be set for commercial card transactions in order to get the best
discount rate. Additionally, the transaction‘s action code must
indicate that the transaction is a commercial card transaction. Note:
Global East (NDC), terminal based, requires the customer code be all
upper case. Max Length: 25 characters, alphanumeric only.
CVV2
String
The CVV2 value for the transaction. The card verification value (CVV2
for Visa, CVC2 for MasterCard, and CID for AMEX and Discover) is a 3 or
4 digit number that is embossed in the signature panel for Visa,
MasterCard, and Discover and on the front of the card for AMEX. All
AMEX cards utilize a 4 digit CID. Max Length: 4 characters. CVV2
should only be passed on non-swiped transactions.
DestZipCode
String
Destination Zip Code for American Express purchasing/commercial
cards. This property must be set for American Express commercial
card transactions when using American Express as the processor (or via
split dial) in order to get the best discount rate. Additionally, the
transaction‘s action code must indicate that the transaction is a
commercial card transaction.
DriverID
String
Driver identification field. Only required for Wright Express, Voyager
and Fleet One cards.
DriverPIN
String
Driver personal identification number.
cards.
EBTVoucherNum
String
The EBT Voucher Number.
Valid Values: 0 – Food Stamp, 1 – Cash Benefits
42
Only required for Fuelman
Property
Data Type
Description
EstGratuityAmount
String
For use with Restaurant transactions only. The estimated gratuity
amount for a Sale (action code 1) or Pre-Authorization (action code 4)
transaction.
If the EstGratuityAmount is populated, PCCharge will
submit the sum of the values in the Amount and EstGratuityAmount
fields for authorization. If the transaction is authorized, only the
value in the Amount field will be placed in the PCCharge settlement
file (if running a Sale). By using the EstGratuityAmount, the merchant
can help ensure that the customer has enough available credit on their
card to leave a tip. Once the customer indicates the amount of the
tip that will be left, a gratuity transaction (action code 13) must be
performed on the sale prior to settlement in order to add the actual
gratuity to the transaction. Format: DDDDDD.CC. Max Length: 9
characters, including the decimal. The value may not be negative.
Note: The amount MUST include the decimal point and the cents even
if the amount is a whole dollar amount. Example: ―3.00‖, not ―3‖ or
―3.‖ If sending less than one dollar, the zero placeholder must be
sent as well. Note: It is recommended to check with the processor or
merchant service provider for guidance on what amount to set this
value to. Incorrectly setting this value can result in downgrades.
ExpDate
String
The expiration date associated with the credit card number that will
be processed. Must be exactly four characters long. Format: MMYY
Example: 1209
GratuityAmount
String
For use with Restaurant transactions only. The actual gratuity
amount for a Sale with Gratuity (action code 14), Gratuity (action
code 13), or Post-Authorization (action code 5) transaction.
IDNumber
String
Only required for Voyager cards, dependant on Restriction Code. Four
to six digits. Note: Only used for Pre-Authorization transactions
ItemID
String
The Item ID for the transaction. This field is only used for Chase
Paymentech (GSAR) and can store five (5) four-digit codes that are
defined by Chase Paymentech. Example: If the ItemID is set to
00010002000300040005, it stores 5 item IDs (0001, 0002, 0003, 0004,
and 0005). These numbers must be obtained from Chase Paymentech.
Language
Enum
Language setting for the prompts on the SC 5000 Interac PIN pad.
Values: 0 – English, 1 – French. English is the default.
MCSC
String
The Multiple Count Sequence Count. This is the total number of
installments that will be charged in a non-restaurant recurring billing
scenario. Max Length: 2 characters. Example: If there are 5 payments
to be made, set this property to ―5‖.
MCSN
String
In a restaurant environment: The server or cashier id. Max Length: 2.
This field should be passed for reporting and reconciliation purposes.
In a non-restaurant environment, this field is the Multiple Count
Sequence Number. This is the transaction number within the total
number of payment installments in a recurring billing scenario. Max
Length: 2 characters. Example: If there are 5 payments to be made
and this transaction is the first transaction, set this property to ―1‖.
The first transaction should also include the CVV property, but this
value should not be stored or sent for subsequent transactions.
Member
String
The cardholder‘s name. Max Length: 20 characters.
Multi
String
Flag that indicates whether PCCharge should leave the modem
connection open in anticipation of other transactions that will follow
shortly. If set, this value will override the corresponding value in the
PCCharge GUI. Note that PCCharge can only keep the connection
open as long as is allowed by the processing company. Valid values: 1
= TRUE, 0 = FALSE Default value: 0. This Flag has no effect if
processing will occur over IP or leased line.
43
Property
Data Type
Description
Odometer
String
The odometer reading. Only required for Fleet One (7 digits), Voyager
(7 digits), and Fuelman (6 digits) cards.
Offline
String
Flag that indicates whether PCCharge should process the transaction
offline. If the offline flag is set, PCCharge will put the transaction into
a .BCH file that resides in the PCCharge directory for importing at a
later time. The file can only be imported from the PCCharge GUI.
Valid values: 1 = TRUE, 0 = FALSE
OrigPurchData
String
The Original Purchase Data. Used when performing a Debit Return
with the processors TSYS, Heartland, RBS WorldPay, and NPC. This is
the original transaction date. Format: DDMMhhmm
PeriodicPayment
String
Flag that indicates whether the transaction is a recurring transaction.
Valid values: 1 = TRUE, 0 = FALSE Note: If periodic payment is set to
true, the recurring billing properties must also be set to achieve the
best processing rates.
PrintReceipts
String
The number of receipts that PCCharge should print for the
transaction. This value will override the corresponding value in the
PCCharge GUI.
PCCharge will retain this value for subsequent
transactions. Valid values: 0-9. Setting the property to 0 will disable
receipt printing.
ProductDetailAmount_X
String
Note: Only required for the processor NBS. This is the total dollar
amount for PRODUCT_DETAIL_PRODUCT_CODE_X being authorized.
For example, PRODUCT_DETAIL_PRODUCT_CODE_1 has a
PRODUCT_DETAIL_QUANTITY_1 = 2 and a
PRODUCT_DETAIL_UNIT_PRICE_1 = $2.00, therefore the
PRODUCT_DETAIL_AMOUNT_1 = $4.00
ProductDetailCount
String
Note: Only required for the processor NBS. All card types are
configurable except for Fleet One, which is limited to 7 records. Only
01 – 10 records are currently supported through PCCharge for all card
types.
ProductDetailCode
String
Note: Only required for the processor NBS. This is the number of
items for PRODUCT_DETAIL_PRODUCT_CODE_X. Currently, PCCharge
will support 1 – 10.
ProductDetailQuantity_X
String
Note: Only used for the processor NBS. This is the unit price for
PRODUCT_DETAIL_PRODUCT_CODE_X. This is only used for Fleet One
and Fuelman. Currently, PCCharge will support 1 – 10.
Reference
String
The reference number from the original transaction (returned by the
processor). Set this property only if processing a Post-Authorization
and the Post-Authorization is being used to add a Voice-Authorization
to the batch or to ―store‖ a Voice-Authorization. (For information on
stored Voice-Authorizations, The Reference property does not need to
be set if the Post-Authorization completes a standard PreAuthorization using the TroutD value of the Pre-Authorization. Max
Length: 8 characters. Note:
NBS/ Fleet One cards require a
Reference Number to be sent with each transaction. This is a
minimum of 2 digits and a max of 15. This must be all numeric.
44
Property
Data Type
Description
RestrictionCode
String
Only required for Voyager cards. This is used to determine the level
of identification and which fields are required. Two digits.
Valid Values:
00 - No ID Number or Odometer required. Fuel and Other allowed.
01 - No ID Number or Odometer required. Fuel only allowed.
10 - ID Number only required. Fuel and Other allowed.
11 - ID Number only required. Fuel only allowed.
20 - Odometer only required. Fuel and Other allowed.
21 - Odometer only required. Fuel only allowed.
30 - ID Number and Odometer required. Fuel and Other allowed.
31 - ID Number and Odometer required. Fuel only allowed.
Note: Required for both manual and swiped transactions.
RFID
String
Set to 1 if card information was read from RFID (Radio Frequency
Identification) device. Set to 0 otherwise.
Store
String
Flag indicating whether a Voice Authorization transaction should be
stored. This flag should only be submitted when performing a PostAuthorization transaction (action code 5) that includes an
authorization code from the voice operator. Valid Value: 1 - Store the
Voice Authorization transaction.
Street
String
The cardholder's billing street address. The Street property is used for
address verification. Address verification can only be performed on
non-swiped transactions. For FDC: Use first 5 digits only. Note: For
manually keyed transactions, Street is required to qualify for the
lowest transaction rates. Max Length: 20 characters
Surcharge
String
Optional surcharge amount for Canadian Debit transactions.
TaxAmt
String
The tax amount. This is the portion of the amount that is tax.
Providing the tax amount is required to obtain the best rate on
commercial card transactions. Max Length: 9 characters (including
the decimal). Format: DDDDDD.CC. The transaction's action code must
indicate that it is a commercial transaction. Tax amount should be
included in the amount field.
TaxExempt
String
Tax Exempt Flag. This flag is used to indicate if the purchase is tax
exempt. Used only for Commercial Card Transactions. Valid Values: 1
– Purchase is tax exempt; 0 – Purchase is not tax exempt.
Ticket
String
The ticket or invoice number for internal referencing by merchant.
This value is stored by PCCharge and passed to the processor for
referencing purposes. Max Length: 9 characters. The value can be
alphanumeric. Note: Not all processors support alphanumeric
characters. Note: For manually keyed transactions, Ticket is required
to qualify for the lowest transaction rates. Note: When using Elavon
(NOVA), ticket numbers can only be alphanumeric, no hyphens.
Track
String
Card swipe data. This is populated when card swipe is sent from a
Keyboard Wedge swipe device.
TroutD
String
The TroutD (Transaction Routing ID) is used when performing ―Follow
On‖ transactions. The TroutD is a PCCharge-assigned unique identifier
that will be associated with a transaction and any subsequent
transactions related to it. This property must be set when performing
Follow-on Transactions.
VehicleID
String
Only required for Wright Express cards (5 digits) and Voyager cards (8
digits).
Note: Required for both manual and swiped transactions.
45
Property
Data Type
Description
Zip
String
The cardholder's zip code. The Zip property is used for address
verification. Max Length: 9 digits. Address verification can only be
performed on non-swiped transactions. Note: For manually keyed
transactions, the Zip is required to qualify for the lowest transaction
rates. Note: For manually keyed transactions, the Zip is required to
qualify for the lowest transaction rates. Note: If submitting the 9digit zip, do not include the dash.
FSA t
String
Indicates if the transaction qualifies to be authorized as a Flexible
Spending Account (FSA). Values: 1 = True, 0 = False
Note: If this value is not present it is defaulted to false.
String
Total amount of qualified healthcare products (includes prescription,
vision, clinic, and dental).
Format: dddd.cc (a whole number sent without the decimal will be
assumed as such. Ex. 1095 will be interpreted as $1,095.00)
Note: This value will not be added to the Amount (TRANS_AMOUNT)
sent, but serves to note how much of the Amount (TRANS_AMOUNT)
is qualified healthcare products.
String
Indicates how much of the HealthcareAmount is being authorized for
prescription products.
Format: dddd.cc
String
vision products.
Format: dddd.cc
String
transit.
Format: dddd.cc
Note: This property is currently not supported by any processors.
String
the Co-pay.
Format: dddd.cc
Note: This property is currently not supported by any processors.
HealthcareAmount
t
PrescriptionAmount
VisionAmount
t
TransitAmount
CoPayAmount
t
t
t
Check Properties
CheckType
Enum
Valid Values: 0 = Personal, 1 = Business
CustomerName
String
The name on the customer‘s ID.
CustomerCity
String
The Customer‘s City
CheckReaderCode
String
Passes the type of Check Reader that is being used.
Valid Values:
001 - Magtek mini micr
002 - EnCheck 3000
003 - IVI 2500
004 - IVI 430
005 - IVI 431
006 - ICE 5700
007 - MagtekImager
008 - VeriFone CR1000i
009 - Epson - TMH6000
010 - Epson - TMH6000Imager
011 - WelchAllyn ScanTeam 8300
012 - VeriFone CR600
46
Property
Data Type
Description
013
014
015
016
017
018
019
020
021
022
- Magtek Imager with Modem
- IBM 4610 reader/printer
- Ingenico EC2600
- RDM EC5000
- RDM EC6000
- NCR 7158 and 7167
- LS 100
- MagTek Excella
- MagTek Excella (DL Capture & F&B check images)
- VeriFone Model Quartet
MICR
String
The full swipe from Check Read
Note: MICR is required if check is swiped. The MICR contains the 9digit ABA Number immediately followed by the checking account
number (up to 14 digits) and then optional check number.
Note: MICR stands for Magnetic Ink Character Recognition
MICRReaderStatus
String
Valid Values:
15 = Valid read by MICR reader
15I = Valid read by MICR reader with imaging capability
9 = Manual only
State
String
The Customer‘s State.
CHECK: State from which the ID was issued
Required when CUSTOMER_ID_TYPE used.
License
String
Driver‘s License Number
DLTrack2
String
The parsed TrackII data from the driver‘s license.
ABANumber
String
The Transit Routing number / Bank Number
This value should not be passed if the MICR is sent. This value is
required if check is manually keyed.
Note: ABA stands for American Bankers Association
Note: Must be exactly 9 characters when using Fifth-Third.
PhoneNumber
String
Customer‘s Phone Number.
Maximum Length: 10 characters
Example: 9125551234
DOB
String
Customer Date of Birth. Format: MMDDYYYY
Example: 01012001 for someone born January 1st, 2001.
CheckNumber
String
The Check Number
This value should be passed if MICR not sent.
ManagerNumber
String
Optional Manager Number for manager override.
CashierNumber
String
The Cashier Number
FirstName
String
The Customer‘s First Name
CHECK: Required by some networks
Note: This value may contain the entire name - first and last
LastName
String
The Customer‘s Last Name.
Payee
String
The Payee.
The name of the check's recipient
CustomerAddress
String
The cardholder‘s street address.
CustomerAddress2
String
Continuation of the street address.
CustomerAcctType
String
The Customer Account Type
Specifies whether transaction involves a business account check or a
personal check. If the checking account is designated as a business,
personal identification parameters are not applicable. Valid for Echo
Valid Values: (Echo)
47
Property
Data Type
Description
Personal Accounts:
PC - Personal Checking
PS - Personal Savings
PL - Personal Loan
Personal Accounts:
BC - Business Checking
BS - Business Savings
BL - Business Loan
ACHType
String
The ACH Payment Type as defined by the National Automated Clearing
House Association
Populate only if CUSTOMER_ACCT_TYPE=PC
Note: Echo only
Note: NACHA regulations require that either the session in which the
order was taken be recorded, or the consumer be notified in writing
prior to initiation of the transaction.
Valid Values:
PPD - (Prearranged Payment and Deposit Entry) Used to submit
prearranged credit and debit transactions such as payroll deposits and
periodic bill payments against a consumer's account.
WEB - (Internet-Initiated Entry). Used to submit debit entries pursuant
to an authorization that has been obtained from the consumer via the
Internet. DEFAULT for personal checks
TEL - (Telephone-Initiated Entry). Used to submit transactions
pursuant to an oral authorization obtained from the consumer via the
telephone.
CCD = Cash Concentration or Disbursement (default for business
checks)
CTX = Corporate Trade Exchange (business checks)
CustomerStreet
String
Max Length: 50 characters
Note: In some cases, this value may be truncated to meet the
processor‘s field length specifications.
CustomerStreet2
String
Suffix
String
The customer suffix (Ex: Jr, Sr)
PhoneNumberType
String
Phone Number Type. Valid Values:
H = Home
W = Work
D = Day
N = Night
CustomerIDType
String
The Customer‘s ID Type. The type of Identification being used to
identify the owner of the checking account. Valid Values:
DL - Drivers License
MI - Military ID
GN - Generic ID
SS - Social Security or Government ID
Note: Required if CustomerIDNum is used
Note: Required for Echo unless this is a business check transaction.
CustomerIDNum
String
The driver‘s license (ID) number of the individual writing the check.
CustomerIDDay
String
Expiration Day – Format: DD
CustomerIDMonth
String
Expiration Month – Format: MM
CustomerIDYear
String
Expiration Year – Format: YY
 These properties are the minimum required to process a Sale or Pre-Authorization transaction.
*Interac Canadian Debit available only for PAYware Connect and PAYware Transact
t
These properties are to be used to process transactions with Healthcare Flexible Spending Accounts. Please see the PCCharge Dev Kit Manual for further
details.
48
PCCharge Methods
Method
Returned
Value
Description
GetAcctDataSrc
String
Returns the entry method of the transaction.
GetACI
String
Returns the VPS indicator to indicate wherever the card is a
VISA, MC or AMEX card PS2000 data. This value is not returned
by all processing companies.
GetAddText1
String
Only supported on Fleet One, this field contains miscellaneous
additional text returned from host. Currently PCCharge will
support GetAddText1- GetAddText4.
GetAuthCode
String
For approved transactions, returns the authorization code from
the issuing bank. For declined transactions, returns the reason
why the transaction was declined (if the issuing bank provides
one) or why the transaction was rejected.
GetAuthDataSrc
String
Returns the Authorization Source Code. The authorization
source code indicates to the processor who authorized the
transaction.
This value is not returned by all processing
companies.
GetAVS
String
Returns the AVS response code from the issuing bank. If
performing
Address
Verification
on
card-not-present
transactions, this code indicates how well the AVS information
passed in matches what the issuing bank has on file for the
cardholder. Consult Appendix B for a description of values that
may be returned.
GetBatchResult
String
Returns the result of a settlement attempt
GetBatchBalance
String
Returns the total balance of the current batch file.
GetBatchNumber
String
Returns the batch number for the current batch
GetBatchCount
String
Returns the batch item count for the current batch.
GetBatchError
String
Returns the error code from the processor if one is provided for
a declined transaction. All processors do not support this field.
GetBatchReference
String
The reference field returns the response from the processor if
the response is a declined. This field is not returned for all
processors.
GetBatchStatus
String
Returns the status of the batch. If the batch was successfully
closed this status will indicate that, if the batch was not closed
and there was a problem, it will return the response from the
processor. For example, if TSYS sends back a rejected batch
response this method will return the RB# number that TSYS
returns.
GetBatchInternalSettlementNumber
String
Returns the Settlement number that is stored in association with
the transaction in PCCharge‘s database. This number is not
returned from the processor but is PCCharge‘s internal
sequencing number scheme.
GetCashBenefitsAvailBalance
String
Returns the available cash benefits balance.
GetCCAvailBalance
String
Returns the Prepaid card balance. Only for prepaid credit cards
with Elavon (NOVA).
GetCardIDCode
Boolean
Returns a code that is used to verify the identity of the
cardholder.
49
Method
Returned
Value
Description
GetCVV2
String
Returns the CVV2/CVC2/CID response code from the issuing
bank. If performing CVV2/CVC2/CID validation on card-notpresent transactions, this code indicates if the CVV2/CVC2/CID
code passed in matches what the issuing bank has on file for the
cardholder. Consult Appendix B for a description of values that
may be returned.
GetDCAvailBalance
String
Returns the available balance on prepaid debit cards. Only for
prepaid debit cards with Elavon (NOVA).
GetECommGoodsInd
String
Returns a value indicating whether the goods sold were digital
or physical in an e-commerce environment.
GetEstGratuityAmount
String
The GetEstGratuityAmount echoes the estimated gratuity from
the original transaction.
GetFoodStampAvailBalance
String
Returns the available food stamp balance
GetGratuityAmount
String
The GetGratuityAmount echoes the gratuity amount from the
original transaction.
GetIND
String
Returns the IND code. The IND code is a transaction description
code and an Interchange compliance field. This value is not
returned by all processing companies.
GetInternalSeqNum
String
Returns the Internal Sequence Number, which is a PCChargeassigned unique number for each transaction. This number is
stored in the Number field in the PCCharge database
(PCCW.MDB) for each transaction.
GetMerchantNumber
String
Returns the merchant number that was specified in the
MerchantNumber property.
GetMSI
String
Returns the Market Specific Indicator. This value indicates the
transaction‘s market segment. This value is assigned by the
card associations and is not returned with all transactions.
GetPCard
String
The GetPCard method returns the PurchaseCard field from the
.oux file. Not all processing companies support this field. Valid
values: 1 = Purchasing card, 0 = Otherwise
GetPEM
String
Returns the Point of Entry Mode that is associated with the
transaction. This value is not returned by all processing
companies.
GetReference
String
Returns the reference number associated with the transaction.
The reference number is assigned by the card associations. The
reference number is used to help identify the transaction and is
useful for the cardholder and merchant when doing research.
This value is not returned with all transactions.
GetRespCode
String
Returns the response code that is provided by the processor.
This value is not returned by all processing companies.
GetResponseCommercialType
String
Returns the type of commercial card that was used for the
transaction. This value is not returned by all processing
companies.
GetRestrictCode
String
Note: Only supported on Fleet One. The product restriction
code.
GetResult
String
Returns the result, which indicates the transaction‘s status upon
completion. Consult Appendix B for a description of values that
may be returned.
GetResultCode
String
Returns the response code that is provided by the processor.
50
Method
Returned
Value
Description
GetREC
String
Returns the record number of the transaction in the reversal
file. Will return -1 if the processor doesn't support reversals.
GetRET
String
Returns the Retrieval reference number. This value is not
returned by all processing companies
GetTraceNumber
String
Returns the trace number from the processor. Only for prepaid
credit cards with Elavon (NOVA).
GetTBatch
String
Returns the active batch number for the transaction. This value
is not returned by all processing companies.
GetTDate
String
Returns the date that the transaction was processed. This value
GetTicket
String
Returns the ticket number or invoice of the transaction. This
value is echoed back from the original transaction or is
generated by PCCharge if one is required to complete the
transaction.
GetTICode
String
Returns the validation code for VISA or the Bank Net Date if the
card is a MasterCard. This value is not returned by all processing
companies.
GetTIM
String
Returns the Time of the transaction. This value is not returned
by all processing companies.
GetTitem
String
Returns the Transaction Item number or the number that is
associated with the transaction in the settlement file. This value
GetTransNum
String
Returns the Internal Sequence Number, which is a PCChargeassigned unique number for each transaction. This number is
stored in the Number field in the PCCharge database
GetTransactionReferenceNumber
String
Returns the transaction reference number from the processor.
Only for prepaid credit cards with Elavon (NOVA).
GetTroutD
String
Returns the TroutD (Transaction Routing ID) for the transaction.
The TroutD is a PCCharge-assigned unique identifier that is
associated with the transaction throughout its ―lifespan‖. This
number is stored in the TroutD field in the PCCharge database
(PCCW.MDB) for each transaction).
GetUser
String
Returns the user name that was specified in the User property.
GetXMLResponse
String
The GetXMLResponse method is used to echo the text that is
returned in the response file associated with the transaction.
GetXMLRequest
String
This method is used to echo the text that is sent in the request
file associated with the transaction.
GetReturnCheckFee
String
Returns the response from the processor, which indicates the
fee for returned checks.
GetReturnCheckNote
String
Returns the response from the processor, which displays a note
for returned checks.
Check Methods
51
PCCharge Gift Card Integration Properties
Property
Data Type
Description
Action
Enum
performed. Consult the Appendix A for a list of valid values.
Amount
String
Send method. Consult the section System Error Codes and
Descriptions for a list of valid errors that will be returned.
Card
String
transaction. Max Length: 20 characters. Example: 5424180279791765
ExpDate
String
Example: 1208
GiftPin
String
Only used for the processor SVS. To retrieve pin, call GetGfitPin upon
activation. Used for only for virtual gift card transactions.
GiftUnits
String
The Units for points transactions. Note: Only Givex supports Points
transactions.
GiftSeqNum
String
Stores the card sequence number for GSAR transactions.
IndType
String
The industry type for the transaction. Valid Values: 1 = retail, 2 =
restaurant. For VLNK: 0 = retail, 1 = restaurant, 2 = e-Commerce.
LoyaltyFlag
String
The Loyalty flag indicates whether the transaction is a loyalty
transaction. Currently, only VTEC supports the Loyalty flag. The
default value of the Loyalty flag is false.
Member
String
Multi
String
PCCharge GUI. Note that PCCharge can only keep the connection open
as long as is allowed by the processing company. Valid values: 1 =
TRUE, 0 = FALSE Default value: 0. This Flag has no effect if
Offline
String
Flag that indicates whether PCCharge should process the transaction
offline. If the offline flag is set, PCCharge will put the transaction into
a .BCH file that resides in the PCCharge directory for importing at a
later time. The file can only be imported from the PCCharge GUI.
Valid values: 1 = TRUE, 0 = FALSE
PartialRedemptionFlag
String
For GSAR: Flag indicating whether the transaction is a partial
redemption transaction.
PrintReceipts
String
The number of receipts that PCCharge should print for the transaction.
This value will override the corresponding value in the PCCharge GUI.
PCCharge will retain this value for subsequent transactions. Valid
values: 0-9. Setting the property to 0 will disable receipt printing.
PromoCode
String
Used for GVEX: A code defined by the merchant that affects the
calculation from amount and units to points.
RefundFlag
String
Flag that indicates whether to provide the customer a refund when
performing a VTEC Deactivate transaction. Valid Values:
1 – Provide refund
0 – Do not provide refund
52
Property
Data Type
Description
SourceAcctNum
String
For VTEC replace transaction, VLNK Balance Merge and Balance
Transfer, the field should be set to the account number of the old
card.
Ticket
String
characters.
TotalNumCards
String
The total number of cards for multiple issuances for Chase
Paymentech. The refund amount for VTEC‘s deactivate transaction.
TroutD
String
VirtualGiftCardFlag
String
Only used for the processor SVS. 0 - False, 1 - True – Only sent on an
activation to determine if a pin should be returned.
53
PCCharge Gift Card Integration Methods
Method Name
Returned
Value
Description – Gift Card Integration Methods
GetActivationCount
String
Returns the number of activations in the current batch
GetActivationTotalAmount
String
Returns the total dollar amount of activations in the current batch
GetAddPointsCount
String
Returns the number of AddPoints Transactions in the current batch
GetAddPointsTotalAmount
String
Returns the total dollar amount of AddPoints transactions in the current
batch
GetAddValueCount
String
Returns the number of AddValue transactions in the current batch
GetAddValueTotalAmount
String
Returns the total dollar amount of AddValue transactions in the current
batch
GetAmountDue
String
Used in partial redemption transactions where only part of the amount was
authorized. Returns the remainder amount that is owed to the merchant.
GetAuth
String
The GetAuth method returns the authorization number for approved
transactions or the reason the transaction was declined (if the processor
provides one). For GVEX Balance transaction: GetAuth will return the
balance remaining on an account. For all other GVEX transactions: GetAuth
will return the transaction‘s reference/error message. For VTEC, returns the
Auth Code. For a VTEC Batch function: use this method to retrieve the
number of sales done that day and the total amounts of sales in the following
format <# of transaction>, <amount>.
GetAuthAmount
String
Used in partial redemption transactions where only part of the amount was
authorized. Returns the actual authorized amount.
GetBalanceTransferCount
String
Returns the number of Balance Transfers in the current batch
GetBalanceTransferTotalAmount
String
Returns the total dollar amount of Balance Transfers in the current batch
GetCaptured
Boolean
The GetCaptured method returns TRUE if PCCharge returns "CAPTURED" as
the result of the transaction. Otherwise, FALSE will be returned. The
GetCaptured method is used to determine if a transaction that will result in a
monetary transfer (Sale, Credit, Post-Authorization, etc.) is approved or
declined. A ―CAPTURED‖ response indicates that the transaction has been
approved.
GetCashBack
String
Used in redemption for remaining balance transactions where the transaction
amount is so close to the balance of the card that the entire balance is
authorized. Returns the remainder that is owed to the customer.
GetCreditCount
String
Returns the number of credits in the current batch
GetCreditTotalAmount
String
Returns the total dollar amount of credits in the current batch
GetErrorCode
Long
The GetErrorCode method returns an error code if an error was encountered
during the use of various methods such as the Send, Cancel, DeleteUserFiles,
and PccSysExists.
GetErrorDesc
String
The GetErrorDesc method returns a string representation of the error that
was encountered during the use of the various methods.
GetExp
String
Returns the expiration date for processors who issue expiration dates in the
response.
GetGiftCardBalance
String
Returns the gift card balance.
GetGiftCardIssuer
String
The GetGiftCardIssuer method returns the gift card issuer of the card that is
present in the Card property. Currently, there are no standards for indicating
what type of gift card is present. Therefore, whatever value is in the
Processor property is what will be returned.
54
Returned
Value
GetGiftCardType
String
The GetGiftCardType method returns the gift card issuer of the card that is
present in the Card property or the optional card parameter that is passed to
the GetGiftCardType method (the GetGiftCardType is the same as
GetGiftCardIssuer). Currently, there are no standards for indicating what
type of gift card is present. Therefore, whatever value is in the Processor
property is what will be returned.
GetGiftPin
String
Only used for the processor SVS. Returned on activation if the virtual gift
card tag is set to ―1‖.
GetMerchantNumber
String
Returns the merchant number that was specified in the MerchantNumber
property.
GetPointsCount
String
Returns the number of points transactions in the current batch
GetPointsTotalAmount
String
Returns the total dollar amount of points transactions in the current batch
GetProcRespCode
String
The processor response code. Only returned by the processor SVS.
GetRefNumber
String
The GetRefNumber returns the Reference field from the .oux file. The
Reference field is used for different purposes (depending on the gift card
processor). For GVEX Register transaction: The first eleven digits of an
account number will be returned. For all VTEC transactions: The account‘s
remaining balance will be returned. For a VTEC batch function: use this
method to retrieve the number of activations done that day and the total
amounts of activations in the following format <# of transaction>,
<amount>.>. For a BPS Redemption transaction, returns the retrieval
reference number.
GetRespCode
String
Returns the response code that is provided by the processor. This value is not
GetResult
String
Returns the result, which indicates the transaction‘s status upon completion.
Refer to the Transaction Result Constants section (see page 81) for a list of
valid values and descriptions.
GetRet
String
For GVEX: Returns the loyalty balance. For VLNK: Returns the trace number.
For a VTEC batch function: : use this method to retrieve the number of Gift
Transactions Voids performed that day. You can call GetVoidBalance to
determine the total amount of the voids.
GetSaleCount
String
Returns the number of redemptions in the current batch
GetSaleTotalAmount
String
Returns the total dollar amount of redemptions in the current batch
String
The GetTicket method returns the Ticket field from the .oux file. The Ticket
field will return the ticket for all transactions except for a VTEC batch
function. For a VTEC batch function: use this method to retrieve the
number of gift card that has been de-activated that day and the total
amounts of de-activations in the following format <# of transaction>,
<amount>.>.
GetTicket
String
The GetTicket method returns the Ticket field from the .oux file. The Ticket
field will return the ticket for all transactions except for a VTEC batch
function. For a VTEC batch function: use this method to retrieve the
number of gift card that has been de-activated that day and the total
amounts of de-activations in the following format <# of transaction>,
<amount>.>.
GetTIM
String
Returns the Time of the transaction. This value is not returned by all
processing companies. For VTEC, returns the Amount Due.
GetTipCount
String
Returns the number of Tip transactions in the current batch
GetTipTotalAmount
String
Returns the total dollar amount of Tip transactions in the current batch
GetTransDateTime
String
Returns the transaction date and time when passed back by a processor.
Method Name
GetTI
55
Method Name
Returned
Value
GetTransNum
String
Returns the Internal Sequence Number, which is a PCCharge-assigned unique
number for each transaction. This number is stored in the Number field in
the PCCharge database (PCCW.MDB) for each transaction.
GetTroutD
String
Returns the TroutD (Transaction Routing ID) for the transaction. The TroutD
is a PCCharge-assigned unique identifier that is associated with the
transaction throughout its ―lifespan‖. This number is stored in the TroutD
field in the PCCharge database (PCCW.MDB) for each transaction.
GetUpdateData
String
Used internally
GetVoidBalance
String
Returns the Void Balance
GetVoidCount
String
Returns the number of voids in the current batch
GetVoidTotalAmount
String
Returns the total dollar amount of Voids in the current batch
String
The GetXMLResponse method is used to echo the text that is returned in the
response file associated with the transaction. The response (.oux) file
contains XML string data. The text that is retrieved can be used by
integrators that wish to parse the results of the transaction themselves or for
troubleshooting purposes. Note: This method must be called prior to calling
the DeleteUserFiles method.
GetXMLRequest
String
This method is used to echo the text that is sent in the request file
associated with the transaction. The request (.inx) file contains XML string
data. The text that is sent in the .inx file can be used to view the message
of any transaction sent to the server. Note: This method must be called
after the calling send and before DeleteUserFiles method.
GetPreAuthCount
String
Only for GAPI, this returns the total number of gift card pre-auth transactions
processed that day.
GetPreAuthAmount
String
Only for GAPI , this returns the total amount of gift card pre-auth transaction
processed that day.
GetPostAuthCount
String
Only for GAPI, this returns the total number of the gift card post-auth
transactions processed that day.
GetPostAuthAmount
String
Only for GAPI, this returns the total amount of the post-auth transactions
processed that day.
GetIssuanceCount
String
Only for GAPI, this returns the total number of gift cards issued that day.
GetIssuanceTotalAmount
String
Only for GAPI, returns the total amount of the gift cards issued that day.
GetDeactivateCount
String
Only for GAPI, this returns how many gift cards where deactivated that day.
GetDeactivateTotalAmount
String
Only for GAPI, this returns the total amount of gift card deactivations that
day.
GetBalanceAdjustCount
String
Only for GAPI, this returns the number of gift cards that were balance
adjusted that day.
GetBalanceAdjustTotalAmount
String
Only for GAPI, this returns the total amount of balance adjustment on gift
cards that day.
GetBalanceMergeCount
String
Only for GAPI, this returns the total number of the gift cards that were
balance merged that day.
GetBalanceMergeTotalAmount
String
Only for GAPI, this returns the total amount of gift card balance merges that
day.
GetReportLostStolenCount
String
Only for GAPI, returns the total reported stolen or lost gift cards that day.
GetReportLostStolenTotalAmount
String
Only for GAPI, returns the total amount of all stolen or reported lost gift
cards that day.
GetCashoutTotalAmount
String
Only for GAPI, returns the total amount of all cashout transactions processed
that day.
GetCashoutCount
String
Only for GAPI, returns the total number of the cashout transactions
processed that day.
GetXMLResponse
56
Method Name
Returned
Value
GetReactivateCount
String
Only for GAPI, returns the total number of gift cards that have been
reactivated that day.
GetReactivateTotalAmount
String
Only for GAPI, the total amount of all gift cards that have been reactivated
that day.
57
Integrating to PAYware PC, PAYware Transact or PAYware
Connect
When integrating to the PAYware PC, PAYware Transact or PAYware Connect Payment Engines, only these transaction
properties should be used.

Note
PAYware Transact is the recommended integration setting for PAYware PC. Consult the
PAYware PC Server documentation for instruction on configuring PAYware
Transact/PAYware PC integration.
PAYware PC, PAYware Transact/PAYware Connect Properties
Data Type
Description
Action
Property
Enum
performed. Consult Appendix A for a description of values that may
be returned.
Amount
String
Send method. Consult the section System Error Codes and
Descriptions for a list of valid errors that will be returned.
AmxChargeDescription
String
The American Express Charge Description.
This is a general
description describing merchandise: the AMEX representative and the
merchant will decide on an appropriate description. Note: Only
Required for Retail, MOTO and Restaurant transactions when using
AMEX direct settlement or TSYS. Max Length: 23 bytes
AmxDescription_1
String
This field is optional and should only be provided if the transaction will
be settled directly with Amex or TSYS.
AmxDescription_2
String
58
Data Type
Description
AmxDescription_3
Property
String
AmxDescription_4
String
AuthCode
String
The Authorization code. This value is returned by the issuing bank and
should only be set in a transaction request when processing a PostAuthorization and if the Post-Authorization is being used to add a
Voice-Authorization to the batch or to ―store‖ a Voice-Authorization.
(For information on stored Voice-Authorizations.
The AuthCode
property does not need to be set if the Post-Authorization completes a
standard Pre-Authorization using the TroutD value of the PreAuthorization. See the section Follow On Transactions for more
information.
BatchTraceID
String
Value used to trace a transaction response back to its original request.
BankNetDate
String
The Banknet Date returned from the original auth
Note: Paymentech Salem Only – Visa / MC Extension record
Format: MMDD
BeverageAmount
String
CREDIT: The Beverage Amount of transaction
Similar to the TIP_AMOUNT Only applicable for Global. Format:
DDDDDD.CC (This value must include dollar and cents separated by a
decimal point (.))
BusinessDate
String
If this value is populated, PAYware Connect or PAYware Transact
stores the business date for reporting purposes. For example, if a
Merchant‘s business is open and processes a transaction after midnight
and wishes for it to appear in the previous day‘s business, the
merchant should pass the Business/Batch Date value of the previous
day.
Format: MMDDYY
Card
String
transaction. Max Length: 20 characters. Example: 5424180279791765
CardIDCode
String
Used in conjunction with CVV2. For keyed transactions.
Valid Values:
0 – CVV2 value bypassed or not provided by merchant
1 – Value present (default)
2 – CVV2 value present on card but illegible
9 – Cardholder states the card does not contain a CVV2
CashBack
String
The amount of cash back that the customer will receive. This amount
is included in the value entered in Amount property. For example, if
the total amount of the sale is $10 and the customer has requested $5
cash back, Amount should be set to $15 and CashBack should be set to
$5. The CashBack property should be formatted the same the Amount
property. Max Length: 9 characters. Note: Some processors do not
support the cash back feature.
CashierNum
String
The Cashier number or Server ID
CDD
String
GIFT: The customer-defined data.
ClerkNum
String
GIFT: The clerk number.
59
Data Type
Description
COL1
Property
String
Allows the merchant to pass a value that will then be inserted into the
PAYware Transact XREF table along with the INTRN_SEQ_NUM of the
transaction being processed. This value is not passed to the processor.
COL2
String
Allows the merchant to pass a value that will then be inserted, into
the PAYware Transact XREF table along with the INTRN_SEQ_NUM of
the transaction being processed. This value is not passed to the
processor.
COL3
String
Allows the merchant to pass a value that will then be inserted into the
PAYware Transact XREF table along with the INTRN_SEQ_NUM of the
transaction being processed. This value is not passed to the processor.
CustCode
String
Customer code for purchasing/commercial cards. This property must
be set for commercial card transactions in order to get the best
discount rate. Additionally, the transaction‘s action code must
indicate that the transaction is a commercial card transaction. Note:
Global East (NDC), terminal based, requires the customer code be all
upper case. Max Length: 25 characters, alphanumeric only.
CustomerCity
String
Used for extended AVS.
CustomerFirstName
String
CustomerLastName
String
CustomerState
String
CustomerIPAddress
String
Required for all Echo Transactions.
CustomerPhone
String
Required for all Echo Transactions
CVRespType
String
CVV2 Response Type
Valid Values:
0 – normal response code returned in response
1 – normal response code and CVV2 result returned in response
CVV2
String
The CVV2 value for the transaction. The card verification value (CVV2
for Visa, CVC2 for MasterCard, and CID for AMEX and Discover) is a 3 or
4 digit number that is embossed in the signature panel for Visa,
MasterCard, and Discover and on the front of the card for AMEX. All
AMEX cards utilize a 4 digit CID. Max Length: 4 characters. CVV2
should only be passed on non-swiped transactions.
CVV2RespType
String
CREDI T: CVV2 Response Type
Valid Values:
0 - normal response code returned in response
1 - normal response code and CVV2 result returned in responseSPACE
holder can be sent.
DestZipCode
String
Destination Zip Code for American Express purchasing/commercial
cards. This property must be set for American Express commercial
card transactions when using American Express as the processor (or via
split dial) in order to get the best discount rate. Additionally, the
transaction‘s action code must indicate that the transaction is a
commercial card transaction.
DevType
String
This is a string sent to identify the device being used in connection
with PAYware Connect. This is directly connected to SERIAL_NUM.
Examples: MX870, MX830, Vx670, etc.
Max Length: 20 characters.
DeviceKey
String
Only for PAYware Connect.
Key used for Device Level Authentication. Please see Device
Authentication in PAYware Connect Integration Guide.
60
Data Type
Description
EBTVoucherNum
Property
String
The EBT Voucher Number.
Valid Values:
0 – Food Stamp
1 – Cash Benefits
EcommGoodsInd
String
Ecommerce Goods Indicator. For Ecommerce transactions only.
Valid Values:
P – Physical
D – Digital
EmpNum
String
GIFT: The employee number.
EstGratuityAmount
String
For use with Restaurant transactions only. The estimated gratuity
amount for a Sale (action code 1) or Pre-Authorization (action code 4)
transaction.
If the EstGratuityAmount is populated, PCCharge will
submit the sum of the values in the Amount and EstGratuityAmount
fields for authorization. If the transaction is authorized, only the
value in the Amount field will be placed in the PCCharge settlement
file (if running a Sale). By using the EstGratuityAmount, the merchant
can help ensure that the customer has enough available credit on their
card to leave a tip. Once the customer indicates the amount of the tip
that will be left, a gratuity transaction (action code 13) must be
performed on the sale prior to settlement in order to add the actual
gratuity to the transaction.
Format: DDDDDD.CC. Max Length: 9
characters, including the decimal. The value may not be negative.
Note: The amount MUST include the decimal point and the cents even
if the amount is a whole dollar amount. Example: ―3.00‖, not ―3‖ or
―3.‖ If sending less than one dollar, the zero placeholder must be sent
as well.
See the section Restaurant Transactions for more
information. Note: It is recommended to check with the processor or
merchant service provider for guidance on what amount to set this
value to. Incorrectly setting this value can result in downgrades.
ExpDate
String
Example: 1208
ForceFlag
String
By passing the ForceFlag with the transactions, allows the merchant to
enter a duplicate transaction having the same account number and
amount of another transaction in the same batch or on the same day.
Valid Values: TRUE or FALSE
GiftSecurityCode
String
GIFT: The gift security code.
GiftTranID
String
GIFT: The gift transaction ID.
GratuityAmount
String
For use with Restaurant transactions only. The actual gratuity
amount for a Sale with Gratuity (action code 14), Gratuity (action
code 13), or Post-Authorization (action code 5) transaction.
Note: The Amount property should include the GratuityAmount.
Installment
String
Installment Billing Flag. Allows the ability to establish transactions to
be processed on a repetitive schedule for a pre-determined number of
times. This value requires that MULTI_CLR_SEQ_NUM (See page 157)
and MULTI_CLR_SEQ_CNT (See page 157) be set. This value is
applicable for Direct Marketing only.
Valid Values:
Y or N
IssueNumber
String
Required for Switch/Solo users
ItemID
String
The Item ID for the transaction. This field is only used for Chase
Paymentech (GSAR) and can store five (5) four-digit codes that are
defined by Chase Paymentech. Example: If the ItemID is set to
00010002000300040005, it stores 5 item IDs (0001, 0002, 0003, 0004,
and 0005). These numbers must be obtained from Chase Paymentech.
61
Data Type
Description
LaneNum
Property
String
GIFT: The lane number.
Language
Enum
Language setting for the prompts on the SC 5000 Interac PIN pad.
Values: 0 – English, 1 – French. English is the default.
MCC
String
The Merchant Category Code. Code that corresponds to a description
of the merchant‘s primary business. The MCC for authorization and
deposit per transaction must match.
Note: Paymentech Salem Only - Visa / MC Extension record PAYware
Connect Integration Guide
MCSC
String
The Multiple Count Sequence Count. This is the total number of
installments that will be charged in a non-restaurant recurring billing
scenario. Max Length: 2 characters. Example: If there are 5 payments
to be made, set this property to ―5‖.
MCSN
String
In a restaurant environment: The server or cashier id. Max Length: 2.
This field should be passed for reporting and reconciliation purposes.
See the section Restaurant Transactions for more information.
In a non-restaurant environment, this field is the Multiple Count
Sequence Number. This is the transaction number within the total
number of payment installments in a recurring billing scenario. Max
Length: 2 characters. Example: If there are 5 payments to be made
and this transaction is the first transaction, set this property to ―1‖.
The first transaction should also include the CVV property, but this
value should not be stored or sent for subsequent transactions.
Member
String
MimeType
Enum
The desired file type for the storage of the signatures.
Values:
JPG = 0 (default)
BMP = 1
PNG = 2
TIFF = 3
Multi
String
PCCharge GUI. Note that PCCharge can only keep the connection open
as long as is allowed by the processing company. Valid values: 1 =
TRUE, 0 = FALSE Default value: 0. This Flag has no effect if
OrigSeqNum
String
GIFT: The original sequence number.
PhoneType
String
Used in conjunction with CustomerPhone for extended AVS.
Valid Values:
W – Work
H – Home
62
Data Type
Description
POSAuthSrc
Property
String
The source of the authorization. Most POS Source Code terminals and
electronic cash registers (ECR) capture this information when it is
returned from the authorizing Vendor.
Note: If the value is unknown, the field may be left blank.
Valid values:
0 - Source Code unavailable
1 - Stand-in processor (STIP), time out response
2 - LCS response (amount below floor limit)
3 - STIP (issuer in suppress inquiry mode)
4 - STIP (issuer unavailable)
5 – Issuer Provided
7 - Acquire approval (BASE I down)
8 - Acquired approval of a referral
D - Referral (auth code manually keyed)
E - Offline approval (auth code manually keyed)
POSCapability
String
The ability of the POS terminal or cash register.
Note: Paymentech Salem Only - Visa / MC Extension record
Note: If this information is unavailable, this field must contain blanks
Note: The value of ―9‖ will not qualify for the lowest interchange rate.
Valid values:
2 - Magnetic strip reader. (Only valid for best retail interchange rate).
5 – Chip capable terminal
9 - Keyed entry only.
POSCardID
String
The method utilized for identifying the cardholder at the point of sale.
Valid values:
1 - Signature obtained (only valid value for best retail interchange
rate).
2 - Personal Identification Number (PIN) utilized.
3 - Unattended terminal, no PIN pad.
4 - Mail order (not valid for retail interchange).
POSEntryMode
String
How the transaction was entered.
Note: If the value is unknown, the field may be left blank. The value
―90‖ is required to qualify for the lowest interchange rate.
Valid values:
01 - Manually keyed.
02 - Magnetic stripe read. (General or Track 2)
05 - Initiated by a chip card; CVV data may be reliable
06 - Magnetic stripe read. (Track 1)
81 - Manually keyed E-Commerce (MasterCard Only)
90 - Entire magnetic stripe read and transmitted
95 - Initiated by a chip card; CVV data may be unreliable
PostType
String
The Card Type of the POST operation
Paymentech Salem Only - Visa / MC Extension record
Valid Values:
MC=MasterCard
VI=VISA
CardPresent
String
Mainly for manually entered transactions (if the card is swiped, then
PAYware Connect and PAYware Transact knows it was present).
Valid Values:
1 - card not present
2 - card present
3 - card swiped
PurchaseID
String
Purchase order number. Assigned by the merchant for the purchasing
card transaction. May be required for a Global completion.
63
Data Type
Description
Quasicash
Property
String
Used for purchase of semi-cash items such as casino chips, travelers
checks, stamps, etc.
CREDIT: Only Global supports Quasicash payments
Valid Values:
TRUE
FALSE (Default)
RBAccount
String
Account number for recurring billing. Note: PAYware Connect Only
RBContractID
String
Contract ID for recurring billing. Note: PAYware Connect Only
RBCustomerID
String
Customer ID for recurring billing. Note: PAYware Connect Only
RBEmail
String
Email for recurring billing. Note: PAYware Connect Only
Recurring
String
Recurring Billing Flag. Flag to indicate the transaction is recurring.
Only applicable to Direct Marketing. Do not submit AVS (Street or Zip)
when using this flag.
Valid Values:
Y or N
RefTroutD
String
Value is presented during a follow-on transaction with PAYware
Connect. This value should be the original TroutD received in the
response during the initial authorization. Once this value is added it
replaces the need to resubmit the original ACCOUNT_NUM, EXP_DATE,
and TRACK_DATA.
NOTE: The only reference transactions supported are:
ELAS
HTUA_ERP
HTUA_ECIOV
HTUA_TSOP
ReturnACI
String
Authorization Characteristics Indicator
The ACI is generated by the merchant's processor company.
SerialNumber
String
Unique string sent to PAYware Connect. This string should accompany
transactions when using a device in connection with PAYware Connect.
This should be accompanied by DEVTYPE.
Note: PAYware Connect Only.
ShiftID
String
The Shift ID
An Alphanumeric code for a server‘s shift. Example: L = lunch
SignatureData
String
Signature data in base 64 format collected from the .GetSignatureData
method.
StartDate
String
Required for Switch/Solo users.
StatementDescription
String
Item Descriptor for ―M‖ Record
Integration Guide
Note: Paymentech Salem Only Max Length:
18 bytes (if StatementName = 3
Payment Processing. PAYware Connect
M record processing
bytes)
bytes)
bytes)
StatementInfo
String
Merchant Information such as telephone number, city, etc.
Note: Paymentech Salem Only - M record processing
Max Length: 13 bytes.
StatementName
String
Note: Paymentech Salem Only - M record processing
The Merchant‘s Name
64
Data Type
Description
Street
Property
String
The cardholder's billing street address. The Street property is used for
address verification. Address verification can only be performed on
non-swiped transactions. For FDC: Use first 5 digits only. Note: For
manually keyed transactions, Street is required to qualify for the
lowest transaction rates. Max Length: 20 characters
Surcharge
String
Optional surcharge amount for Canadian Debit transactions.
TaxAmt
String
The tax amount. This is the portion of the amount that is tax.
Providing the tax amount is required to obtain the best rate on
commercial card transactions. Max Length: 9 characters (including
the decimal). Format: DDDDDD.CC. The transaction's action code must
indicate that it is a commercial transaction. Tax amount should be
included in the amount field.
Ticket
String
characters. Note: For manually keyed transactions, Ticket is required
to qualify for the lowest transaction rates. Note: When using Elavon
(NOVA), ticket numbers can only be alphanumeric, no hyphens.
TotalNumCards
String
GIFT: The total number of cards being activated.
TransactionCode
String
GIFT: The transaction code.
TransSeqFlag
String
GIFT: The transaction sequence flag.
TroutD
String
UseTIMPassthrough
Boolean
This property should be set to TRUE when using the TIM in conjunction
with the SIM.DLL. For more information See Appendix E.
Note: PAYware Connect only.
ValidCode
String
Validation Code.
Assigned by the VISA authorization system.
Zip
String
The cardholder's zip code. The Zip property is used for address
verification. Max Length: 9 digits. Address verification can only be
performed on non-swiped transactions. Note: For manually keyed
transactions, the Zip is required to qualify for the lowest transaction
rates. Note: For manually keyed transactions, the Zip is required to
qualify for the lowest transaction rates. Note: If submitting the 9digit zip, do not include the dash.
Dynamic Currency Conversion (DCC)
DCCIndicator
String
Set with the value ―Y‖. The host will convert the transaction to the
cardholder‘s currency based on the BIN.
DCCCustomerCurrency
String
Used for currency selection. Cardholder ISO currency code. Refer to
table below.
DCCExponent
String
Used for currency selection. Number of exponent digits in the
DCC_RATE. Numerical value only.
DCCRate
String
Used for currency selection. Foreign currency exchange rate.
65
Data Type
Description
DCCCustomerAmount
Property
String
Used for currency selection. Cardholder transaction amount.
= (TRANS_AMOUNT * exchange rate)
Modifier
String
CheckType
Enum
Valid Values: 0 = Personal, 1 = Business
CustomerName
String
The name on the customer‘s ID.
CustomerCity
String
The Customer‘s City
CheckReaderCode
String
Passes the type of Check Reader that is being used.
Valid Values:
001 - Magtek mini micr
002 - EnCheck 3000
003 - IVI 2500
004 - IVI 430
005 - IVI 431
006 - ICE 5700
007 - MagtekImager
008 - VeriFone CR1000i
009 - Epson - TMH6000
010 - Epson - TMH6000Imager
011 - WelchAllyn ScanTeam 8300
012 - VeriFone CR600
013 - Magtek Imager with Modem
014 - IBM 4610 reader/printer
015 - Ingenico EC2600
016 - RDM EC5000
017 - RDM EC6000
018 - NCR 7158 and 7167
019 - LS 100
020 - MagTek Excella
021 - MagTek Excella (DL Capture & F&B check images)
022 - VeriFone Model Quartet
MICR
String
The full swipe from Check Read
Note: MICR is required if check is swiped. The MICR contains the 9digit ABA Number immediately followed by the checking account
number (up to 14 digits) and then optional check number.
Note: MICR stands for Magnetic Ink Character Recognition
MICRReaderStatus
String
Valid Values:
15 = Valid read by MICR reader
15I = Valid read by MICR reader with imaging capability
9 = Manual only
State
String
The Customer‘s State.
CHECK: State from which the ID was issued
Required when CUSTOMER_ID_TYPE used.
License
String
Driver‘s License Number
DLTrack2
String
The parsed TrackII data from the driver‘s license.
ABANumber
String
The Transit Routing number / Bank Number
This value should not be passed if the MICR is sent. This value is
required if check is manually keyed.
Note: ABA stands for American Bankers Association
Note: Must be exactly 9 characters when using Fifth-Third.
PhoneNumber
String
Customer‘s Phone Number.
Example: 9125551234
Check Properties
66
Data Type
Description
DOB
Property
String
Customer Date of Birth. Format: MMDDYYYY
Example: 01012001 for someone born January 1st, 2001.
CheckNumber
String
The Check Number
This value should be passed if MICR not sent.
ManagerNumber
String
Optional Manager Number for manager override.
CashierNumber
String
The Cashier Number
FirstName
String
The Customer‘s First Name
LastName
String
The Customer‘s Last Name.
Payee
String
The Payee.
The name of the check's recipient
CustomerAddress
String
CustomerAddress2
String
CustomerAcctType
String
The Customer Account Type
Specifies whether transaction involves a business account check or a
personal check. If the checking account is designated as a business,
personal identification parameters are not applicable. Valid for Echo
Valid Values: (Echo)
Personal Accounts:
PC - Personal Checking
PS - Personal Savings
PL - Personal Loan
Personal Accounts:
BC - Business Checking
BS - Business Savings
BL - Business Loan
ACHType
String
The ACH Payment Type as defined by the National Automated Clearing
House Association
Populate only if CUSTOMER_ACCT_TYPE=PC
Note: Echo only
Note: NACHA regulations require that either the session in which the
order was taken be recorded, or the consumer be notified in writing
prior to initiation of the transaction.
Valid Values:
PPD - (Prearranged Payment and Deposit Entry) Used to submit
prearranged credit and debit transactions such as payroll deposits and
periodic bill payments against a consumer's account.
WEB - (Internet-Initiated Entry). Used to submit debit entries pursuant
to an authorization that has been obtained from the consumer via the
Internet. DEFAULT for personal checks
TEL - (Telephone-Initiated Entry). Used to submit transactions
pursuant to an oral authorization obtained from the consumer via the
telephone.
CCD = Cash Concentration or Disbursement (default for business
checks)
CTX = Corporate Trade Exchange (business checks)
CustomerStreet
String
Note: In some cases, this value may be truncated to meet the
processor‘s field length specifications.
CustomerStreet2
String
67
Data Type
Description
Suffix
Property
String
The customer suffix (Ex: Jr, Sr)
PhoneNumberType
String
Phone Number Type
Valid Values:
H = Home
W = Work
D = Day
N = Night
CustomerIDType
String
The Customer‘s ID Type. The type of Identification being used to
identify the owner of the checking account.
Valid Values:
DL - Drivers License
MI - Military ID
GN - Generic ID
SS - Social Security or Government ID
Note: Required if CustomerIDNum is used
Note: Required for Echo unless this is a business check transaction.
CustomerIDNum
String
The driver‘s license (ID) number of the individual writing the check.
CustomerIDDay
String
Expiration Day – Format: DD
CustomerIDMonth
String
Expiration Month – Format: MM
CustomerIDYear
String
Expiration Year – Format: YY
SaleType
String
Echo Check Deposit
Optional
Enter for ACH only – without verification.
Valid Value: ―ACH_ONLY‖
OtherName
String
Optional
Other name on the check
CustomerCountry
String
Valid Values:
CA – Canada
MX – Mexico
US – USA (Default)
*Interac Canadian Debit available only for PAYware Connect and PAYware Transact
68
PAYware PC, PAYware Transact/PAYware Connect Methods
Method
Returned Description
Value
Cancel
Boolean
The Cancel method attempts to cancel the transaction in progress. Calling the Cancel
method does not guarantee that the transaction will be canceled; it simply attempts to
cancel the transaction. It will return false if the transaction has already been submitted to
the server for authorization.
Clear
None
The Clear method will clear the values in all properties and methods
It is recommended that this method be called:
After the transaction results have been retrieved by using the various .get methods
After the DeleteUserFiles method has been called
Prior to running the next transaction
GetAuthCode
String
For approved transactions, returns the authorization code from the issuing bank. For
declined transactions, returns the reason why the transaction was declined (if the issuing
bank provides one) or why the transaction was rejected.
GetAVS
String
Returns the AVS response code from the issuing bank. If performing Address Verification on
card-not-present transactions, this code indicates how well the AVS information passed in
matches what the issuing bank has on file for the cardholder. Consult Appendix C for a
description of values that may be returned.
GetBatchResult
String
Returns the result of a settlement attempt
GetBatchBalance
String
Returns the total balance of the current batch file.
GetBatchNumber
String
Returns the batch number for the current batch
GetBatchCount
String
Returns the batch item count for the current batch.
GetBatchError
String
Returns the error code from the processor if one is provided for a declined transaction. All
processors do not support this field.
GetBatchReference
String
The reference field returns the response from the processor if the response is a declined.
This field is not returned for all processors.
GetBatchStatus
String
Returns the status of the batch. If the batch was successfully closed this status will indicate
that, if the batch was not closed and there was a problem, it will return the response from
the processor. For example, if TSYS sends back a rejected batch response this method will
return the RB# number that TSYS returns.
GetBatchTraceID
String
Value used to trace a transaction response back to its original request.
When a value for BatchTraceID is passed in, that same value will be returned in the response.
This value is not stored in the database.
Format: Alphanumeric, unlimited length
GetBatchInternalSettlementNumber String
Returns the Settlement number that is stored in association with the transaction in
PCCharge‘s database. This number is not returned from the processor but is PCCharge‘s
internal sequencing number scheme.
GetCashBenefitsAvailBalance
String
Returns the available cash benefits balance.
GetClientID
String
Returns the Client ID being used in the transaction.
GetCVV2
String
Returns the CVV2/CVC2/CID response code from the issuing bank.
If performing
CVV2/CVC2/CID validation on card-not-present transactions, this code indicates if the
CVV2/CVC2/CID code passed in matches what the issuing bank has on file for the cardholder.
Consult Appendix C for a description of values that may be returned.
GetDeviceKey
String
Retrieve Device Key.
GetEstGratuityAmount
String
The GetEstGratuityAmount echoes the estimated gratuity from the original transaction.
GetFoodStampAvailBalance
String
Returns the available food stamp balance.
GetGratuityAmount
String
The GetGratuityAmount echoes the gratuity amount from the original transaction.
GetInternalSeqNum
String
Returns the Internal Sequence Number, which is a PCCharge-assigned unique number for
each transaction.
This number is stored in the Number field in the PCCharge database
69
Method
Value
GetPaymentMedia
String
Code that identifies the issuer of the card. Consult Appendix C for a description of values
that may be returned.
GetReference
String
Returns the reference number associated with the transaction. The reference number is
assigned by the card associations. The reference number is used to help identify the
transaction and is useful for the cardholder and merchant when doing research. This value is
not returned with all transactions.
GetRespCode
String
Returns the response code that is provided by the processor. This value is not returned by all
processing companies.
GetResponseCommercialType
String
Returns the type of commercial card that was used for the transaction. This value is not
Valid Return Values:
B – Business
C – Corporate
P – Purchase
GetResponseText
String
Response text from the processor or PAYware PC/PAYware Connect/PAYware Transact
Transaction specific data that is returned by the processor, bank, or PAYware PC/PAYware
Connect/PAYware Transact. Varies by transaction type and processor.
GetRestrictCode
String
Note: Only supported on Fleet One. The product restriction code.
GetResult
String
Returns the result, which indicates the transaction‘s status upon completion. Consult
Appendix C for a description of values that may be returned.
GetResultCode
String
Returns the response code that is provided by the processor. This value is not returned by all
processing companies. Consult Appendix C for a description of values that may be returned.
GetSettlementDetails
String
Returns the result of the settlement as a string of parsed data in place of an XML response.
The string will appear as follows:
<STX>InternalSeqNum<FS>TerminationStatus<FS>ResultCode<FS>Result
<GS>BatchCount
<RS>BatchSeqNum<FS>ResultCode<FS>Result<FS>ResponseText<FS>BatchCount
<FS>BatchBalance<FS>TransSeqFirst<FS>TransSeqLast
<GS>ExceptionCount
<RS>ExceptionElements<FS>Reason
<ETX>
GetStatus
String
Returns current status.
GetTBatch
String
Returns the active batch number for the transaction. This value is not returned by all
processing companies.
GetTermStatus
String
The Termination Status of the transaction request
Note: This value is assigned and returned by
PAYware PC/PAYware Connect/PAYware Transact.
Consult Appendix C for a description of values that may be returned.
Note: If SUCCESS is returned, it simply indicates that
PAYware PC /PAYware Connect/PAYware Transact processed the request properly. It DOES
NOT mean that a request, transaction, settlement, etc., was accepted or closed by the
processor. Check the RESULT value and RESULT_CODE returned to determine the status of a
transaction request. When a value other than "SUCCESS" is returned, it means that the
request was not processed properly by
PAYware PC /PAYware Connect/PAYware Transact. The request must be re-submitted to
PAYware PC/PAYware Connect/PAYware Transact (unless NOT_PROCESSED_COMM_FAILURE"
is the TERMINATION_STATUS of a PAYMENT transaction and fault tolerance queuing is
enabled).
GetTerminalName
String
Returns the name of the terminal.
GetTicket
String
Returns the ticket number or invoice of the transaction. This value is echoed back from the
original transaction or is generated by PCCharge if one is required to complete the
transaction.
70
Method
Value
GetTraceCode
String
Value returned by the processor used for tracking purposes.
Note: For Debit transactions, this value must be printed on the customer receipt.
GetTransSeqFirst
String
The sequence number of the first transaction in the settled batch segment.
GetTransSeqLast
String
The sequence number of the last transaction in the settled batch segment.
GetTransSeqNum
String
The sequence number of the transaction in the current open batch.
Note: This value is assigned and returned by
PAYware PC /PAYware Connect/PAYware Transact.
GetTroutD
String
Returns the TroutD (Transaction Routing ID) for the transaction. The TroutD is a PCChargeassigned unique identifier that is associated with the transaction throughout its ―lifespan‖.
This number is stored in the TroutD field in the PCCharge database (PCCW.MDB) for each
transaction. See the section Follow On Transactions for more information.
GetXMLResponse
String
The GetXMLResponse method is used to echo the text that is returned in the response file
associated with the transaction.
GetXMLRequest
String
This method is used to echo the text that is sent in the request file associated with the
transaction.
GetPyRespCode
String
GIFT: Response code returned by processing company. Response code returned only when
using Paymentech.
Valid Return Values:
E - Error
A - Approved
If E is returned, the error code will be returned in the AUTH_RESP_CODE field. If A is
returned the authorization code will be returned in the AUTH_CODE field.
GetAvailBalance
String
GIFT: The Gift Card Available Balance. Returns Gift Card balance if available from card.
GetApprovedAmount
String
GIFT: The Approved Amount. If processing a Gift card partial redemption, then Paymentech
will approve the transaction as long as there is a balance on the card. If the card‘s available
balance will not cover the TRANS_AMOUNT, Paymentech will approve the amount up to the
balance on the card. APPROVED_AMOUNT contains the amount Paymentech approved for the
partial redemption. If the customer owes a difference then the DIFF_AMOUNT_DUE field will
contain the amount the customer owes towards the transaction.
GetDiffDueAmount
String
GIFT: The Difference due from the customer. If processing a Gift card partial redemption,
then Paymentech will approve the transaction as long as there is a balance on the card. If
the card‘s available balance will not cover the TRANS_AMOUNT, Paymentech will approve the
amount up to the balance on the card. APPROVED_AMOUNT contains the amount Paymentech
approved for the partial redemption. If the customer owes a difference then the
DIFF_AMOUNT_DUE field will contain the amount the customer owes towards the transaction.
GetOrigTransAmount
String
GIFT: The Original Transaction Amount. If processing a Gift card partial redemption,
populated if APPROVED_AMOUNT does not match original TRANS_AMOUNT.
GetAuthRespCode
String
GIFT: The Authorization Response Code. Populated if declined. Error code returned from
network. Only returned when using the processor Global, CardNet or Paymentech.
GetLCLTransDate
String
GIFT: Returns the local transaction date.
GetLCLTransTime
String
GIFT: Returns the local transaction time.
GetTransDate
String
GIFT: The transaction date.
GetTransTime
String
GIFT: The transaction time.
GetAcctCurrencyCode
String
GIFT: Returns the account currency code.
GetAcctNum
String
GIFT: The Gift Card Account Number.
registered is returned in the response.
GetTransAmount
String
GIFT: The amount of the original transaction.
GetTraceAuditNum
String
GIFT: Value returned by the processor used for tracking purposes.
GetCardBal
String
GIFT: Returns the gift card balance.
GetInvNum
String
GIFT: Returns the original invoice number.
71
For Register transactions, the gift card number
Method
Value
GetStoreDivNum
String
GIFT: Returns the store division number.
GetTransCurrencyCode
String
GIFT: Returns the currency code.
GetRemainingBalance
String
GIFT: Returns the remaining balance of the gift card.
GetTransConversionRate
String
GIFT: Returns the transaction conversion rate.
GetSVSMerchNum
String
GIFT: Returns the SVS merchant number used for gift cards.
GetProcessingCode
String
GIFT: Returns the processing code from the gift card processor.
GetTransactionCode
String
GIFT: Returns the transaction code from the gift card processor.
GetAmountBalance
String
GIFT: The amount of usable funds remaining on gift card.
GetDCCMerchantCurrency
String
Returns Merchant ISO currency code.
GetDCCCustomerCurrency
String
Returns Cardholder ISO currency code.
GetDCCExponent
String
Returns number of exponent digits in the DCC_RATE. Numerical value only.
GetDCCRate
String
Returns Foreign currency exchange rate.
GetDCCCustomerAmount
String
Returns Cardholder transaction amount.
= (TRANS_AMOUNT * exchange rate)
GetDCCUpdateDetails
String
This is available when performing a DCC Update Inquiry. The string will be in the following
format:
<STX>Number of DCC Records<RS>DCC Exponent<FS>DCC Rate<FS>DCC Customer Detail<ETX>
Example:
<STX>5
<RS>5<FS>148316<FS>AUD
<RS>5<FS>127265<FS>CAD
<RS>5<FS>76459<FS>EUR
<RS>5<FS>10079997<FS>JPY
<RS>5<FS>70894<FS>GBP
<ETX>
GetReturnCheckFee
String
Returns the response from the processor, which indicates the fee for returned checks.
GetReturnCheckNote
String
Returns the response from the processor, which displays a note for returned checks.
GetEchoDeclineCode
String
Returns Echo Specific code if transaction is declined.
Dynamic Currency Conversion (DCC)
Check Methods
72
73
Appendix A – SIM.DLL Constants
Action Codes
The .Action property is of enumerated type. The integrator can choose to use the enumeration or the action code to set
this property. For example:


.Action = 1
or
.Action = SIM.Charge.Command.Credit_Sale
Credit Card Actions
Action
Code
Description
Enumeration
1
Sale
SIM.Charge.Command.Credit_Sale
2
Return
SIM.Charge.Command.Credit_Return
3
Void
SIM.Charge.Command.Credit_Void
4
Pre-Auth
SIM.Charge.Command.Credit_Pre_Auth
5
Post-Auth
SIM.Charge.Command.Credit_Post_Auth
6
Void Return
SIM.Charge.Command.Credit_Void_Return
7
Void Post-Auth
SIM.Charge.Command.Credit_Void_Post_Auth
8**
P-Card Sale
SIM.Charge.Command.Credit_Commercial_Card_ Sale
9**
P-Card Return
SIM.Charge.Command.Credit_Commercial_Card_Return
10**
P-Card Post-Auth
SIM.Charge.Command.Credit_Commercial_Card_ Post_Auth
13
Gratuity
SIM.Charge.Command.Credit_Gratuity
14
Sale w/ Gratuity
SIM.Charge.Command.Credit_Sale_with_Gratuity
91*
Completion
SIM.Charge.Command.Credit_Completion
92*
Voice-Auth
SIM.Charge.Command.Credit_Voice_Auth
93*
Add Tip
SIM.Charge.Command.Credit_Add_Tip
94*
P-Card Follow on
SIM.Charge.Command.Credit_Commercial
95*
Reset Tip
SIM.Charge.Command.Credit_Reset_Tip
110*
Sends Signature Data SIM.Charge.Command.Credit_Store_Signature
*These actions are only for use with PAYware PC, PAYware Transact, or PAYware Connect
**These actions are only for use with PCCharge
74
Debit Card Actions
Action
Code
Description
Enumerated
41
Sale
SIM.Charge.Command.Debit_Sale
42
Return
SIM.Charge.Command.Debit_Return
43*
Void
SIM.Charge.Command.Debit_Void
46*
Void Return
SIM.Charge.Command.Debit _Void_ Return
48*
Sale Recovery
SIM.Charge.Command.Debit_Sale_Recovery
49*
Return Recovery
SIM.Charge.Command.Debit_Return_Recovery
EBT Card Actions
Action
Description
Code
Enumerated
60
Inquiry
SIM.Charge.Command.EBT_Inquiry
61
Cash Withdrawal
SIM.Charge.Command.EBT_Cash_Withdrawal
62
Food Stamp Purchase
SIM.Charge.Command.EBT_Food_Stamp_Purchase
63
Food Stamp Return
SIM.Charge.Command.EBT_Food_Stamp_Return
64
Cash Post Auth
SIM.Charge.Command.EBT_Cash_Post_Auth
65
Food Stamp Post Auth
SIM.Charge.Command.EBT_Food_Stamp_Post_Auth
66
Food Stamp Credit Post Auth
SIM.Charge.Command.EBT_Food_Stamp_Credit_Post_Auth
67
Cash Void
SIM.Charge.Command.EBT_Cash_Void
68
Food Stamp Void
SIM.Charge.Command.EBT_Food_Stamp_Void
69
Food Stamp Credit Void
SIM.Charge.Command.EBT_Food_Stamp_Credit_Void
70
Purchase
SIM.Charge.Command.EBT_Purchase
71
Food Stamp Purchase Recovery
SIM.Charge.Command.EBT_Food_Stamp_Purchase_Recovery
72
Food Stamp Credit Recovery
SIM.Charge.Command.EBT_Food_Stamp_Credit_Recovery
73
Food Stamp Post Auth Recovery
SIM.Charge.Command.EBT_Food_Stamp_Post_Auth_Recovery
74
Cash Withdrawal Recovery
SIM.Charge.Command.EBT_Cash_Withdrawal_Recovery
75
Cash Purchase Recovery
SIM.Charge.Command.EBT_Cash_Purchase_Recovery
*These actions are only for use with PCCharge and PAYware Transact/PAYware Connect
75
Gift Card Actions
Action
Description
Code
Enumerated
18
Balance Inquiry
SIM.Charge.Command.Gift_Balance_Inquiry
25
Redemption
SIM.Charge.Command.Gift_Redemption
26
Register
SIM.Charge.Command.Gift_Register
27
Add Value
SIM.Charge.Command.Gift_Add_Value
28
Activate
SIM.Charge.Command.Gift_Activate
29
Void
SIM.Charge.Command.Gift_Void
76
Deactivate
SIM.Charge.Command.Gift_Deactivate
77
Refund
SIM.Charge.Command.Gift_Refund
78
Totals Inquiry
SIM.Charge.Command.Gift_Totals_Inquiry
79
Previous Day Total
SIM.Charge.Command.Gift_Previous_Day_Total
80
Balance with Lock
SIM.Charge.Command.Gift_Balance_with_Lock
85
Post Auth
SIM.Charge.Command.Gift_Post_Auth
86
Redeem Points
SIM.Charge.Command.Gift_Redeem_Points
87
Balance Merge
SIM.Charge.Command.Gift_Balance_Merge
88
Balance Adjustment
SIM.Charge.Command.Gift_Balance_Adjustment
89
Balance Transfer
SIM.Charge.Command.Gift_Balance_Transfer
96
Report Lost/Stolen
SIM.Charge.Command.Gift_Report_Lost_Stolen
97
Cashout
SIM.Charge.Command.Gift_Cashout
98
Add Tip
SIM.Charge.Command.Gift_AddTip
99
Pre Auth
SIM.Charge.Command.Gift_PreAuth
100
Completion
SIM.Charge.Command.Gift_Completion
101
Decrement
SIM.Charge.Command.Gift_Decrement
102
Close
SIM.Charge.Command.Gift_Close
103
Block Activate
SIM.Charge.Command.Gift_Block_Activate
*These actions are only for use with PCCharge and PAYware Transact/PAYware Connect.
76
Check Actions
Action
Description
Code
Enumerated
20
MICR Verify
SIM.Charge.Command.Check_MICR_Verify
21
COD Phone Verify
SIM.Charge.Command.Check_COD_Phone_Verify
22
Driver‘s License
SIM.Charge.Command.Check_Drivers_License
23
Double ID Verify
SIM.Charge.Command.Check_Double_ID_Verify
24
Void Check
SIM.Charge.Command.Check_Void_Check
50
MICR Truncation
SIM.Charge.Command.Check_MICR_Truncation
51
Sale w/ MICR
SIM.Charge.Command.Check_Sale_MICR
52
Void MICR
SIM.Charge.Command.Check_Void_MICR
53
Force MICR
SIM.Charge.Command.Check_Force_MICR
54
Manager Override
SIM.Charge.Command.Check_Manager_Override
55
ECA Authorization
SIM.Charge.Command.Check_ECA_Authorization
56
ECA Adjustment
SIM.Charge.Command.Check_ECA_Adjustment
57
ECA Completion Accepted
SIM.Charge.Command.Check_ECA_Completion_Accepted
58
ECA Completion Refused
SIM.Charge.Command.Check_ECA_Completion_Refused
59
Settle MICR
SIM.Charge.Command.Check_Settle_MICR
120
Check Credit (Refund)
SIM.Charge.Command.Check_Credit
121
Check Status
SIM.Charge.Command.Check_Status
122
Check Inquiry
SIM.Charge.Command.Check_Inquiry
Settlement Actions
Action
Description
Code
Enumerated
30*
Batch Inquiry
SIM.Charge.Command.Batch_Inquiry
31*
Batch Settle
SIM.Charge.Command.Batch_Settle
34**
Batch Credit Settle
SIM.Charge.Command.Batch_Credit_Settle
35**
Batch Debit Settle
SIM.Charge.Command.Batch_Debit_Settle
36**
Batch Local Settle
SIM.Charge.Command.Batch_Local_Settle
*These actions are only for use with PCCharge
**These actions are only for use with PAYware PC, PAYware Transact and PAYware Connect
77
Error Codes
These error codes and descriptions will be returned when either the Err event has fired or the Process method returns
false.
Error
Code
Error
Description
Description
1
Unable to
Communicate
SIM.DLL was unable to communicate with the payment engine.
payment engine is running
6
Timeout
SIM.DLL did not receive a response from the payment engine in the amount of time
allotted by the .Timeout property.
20
Exception
A General Error Exception has occurred
21
Insufficient
Transaction Data
The amount of data, or the data inputted, is insufficient to carry out that particular
transaction.
22
Merchant Account
Error
The merchant account information is incorrectly formatted or incorrectly entered for the
selected payment engine.
23
Device Data Error
The device (PIN pad) data entered is insufficient to properly use the device.
24
Communication Data
Error
The communication data entered is insufficient to connect to the server or has been
incorrectly entered
25
Invalid Command
The action code entered is not supported by the selected payment engine.
26
PIN pad initialization
Failed
The initialization of the PIN pad failed. The PIN pad will not be able to collect swipe data
or extract pin entry data unless it is initialized.
27
Error Reading Card
From Device
The card swipe encountered an error
28
Error In Line Display
The Everest encountered an error updating the display message
29
Error in Pin
An error occurred while trying to extract the pin data
30
Unable to Open Line
Display
The line display module of the Everest PIN pad was unable to open. This generally means
that the Com Port selected is already in use by another program
Unable to Open MSR
The mag stripe reader module of the Everest PIN pad was unable to open. This generally
means that the Com Port selected is already in use by another program
Unable to Open PIN
pad
The PIN pad module of the Everest PIN pad was unable to open. This generally means
33
Unable to Open
Keyboard
The keyboard module of the Everest PIN pad was unable to open. This generally means
34
Customer Initiated
Cancel
The customer pressed the ―Clear‖ or ―Cancel‖ button on the device.
35
Transaction has been
sent. Can not cancel
This error occurs when a cancel is initiated by the integrated application by calling the
Cancel method, but the transaction has already been submitted to the payment engine.
36
Timeout waiting for
swipe
The amount of time permitted by the .SwipeTimeout property has elapsed. The customer
did not swipe their card through the device in this amount of time.
37
Interac Transaction
Failed
An error occurred during the transmission of a Interac transaction to PAYware Transact,
PAYware Connect or the SC 5000
38
Key Load failed
An error occurred during the Key Load procedure to PAYware Transact, PAYware Connect
or the SC 5000.
31
32
78
Check to see if the
Appendix B – PCCharge Constants
Address Verification Response Codes
Response Code
Address Match
A
Address matches, ZIP code does not
B
Address matches, postal code does not
C
No match on address or postal code
D
Street address and postal code matches
E
AVS error
G
Service not supported by non-US issuer
I
Address not verified for international transaction
M
Street address and postal code matches
N
No match on address or ZIP code
P
Postal code matches, address does not
R
Retry, system is unavailable or timed out
S
Service not supported by issuer (card type does not support AVS)
U
Address information is unavailable
W
9-digit ZIP code matches, address does not
X
Exact match
Y
Address and 5-digit ZIP code match
Z
0
No response sent
CVV2/CVC2/CID Response Codes
Response Code
Address Match
M
CVV2/CVC2/CID match
N
CVV2/CVC2/CID mismatch
P
Not processed -- Either the CVV2/CVC2/CID was not provided, or the card does not have a
CVV2/CVC2/CID value. If the CVV2/CVC2/CID was left blank, resubmit as a zero dollar
amount for the transaction so the customer's credit line won't be affected by the second
CVV2/CVC2/CID request.
S
Issuer indicates that the CVV2/CVC2/CID data should be present on the card, but the
merchant has indicated that the CVV2/CVC2/CID data is not present on the card.
U
Issuer has not certified for CVV2/CVC2/CID or issuer has not provided Visa/MasterCard with
the CVV2/CVC2/CID encryption keys.
79
Processing Company Codes

Note:
The processor drop-down lists found in the various setup screens in PCCharge also serve as
accurate lists of the available processor codes.
Credit Card
Processing Company
Processor Code
Alliance Data Systems, Inc.
ADSI
American Express
AMEX
BuyPass, Inc.
BPAS
Citibank Private Label
CITI
ECHO
ECHO
FDMS Nashville / Envoy
FDCN
FDMS North Nash
FDNN
FDMS North / Cardnet
CES
FDMS Omaha / FDR
FDC
FDMS South / NaBanco
NB
Fifth-Third Bank – St. Pete
BPS
Global Payment-East
NDC
Heartland Payment Systems
HPTS
RBS WorldPay
LYNK
National Bankcard Services
NBS
National Processing Company
NPC
Elavon
NOVA
Chase Paymentech
GSAR
TSYS (Formerly Vital)
VISA
Debit
Processing Company
Processor Code
Alliance Data Systems, Inc.
ADSI
BuyPass, Inc.
BPAS
FDMS North / CardNet
CES
FDMS Omaha / FDR
FDC
FDMS South / NaBanco
NB
Fifth-Third Bank – St. Pete
BPS
Global Payments / East
NDC
Heartland Payment Systems
HPTS
RBS WorldPay
LYNK
National Bankcard Services
NBS
National Processing Company
NPC
Elavon
NOVA
Chase Paymentech
GSAR
TSYS (Formerly Vital)
VISA
80
PCCharge Transaction Result Constants
These results are returned by the .GetResult method of SIM.DLL
Result
Transaction Type
Description
CAPTURED
Monetary
Successful online transaction now ready for settlement
NOT CAPTURED
Varies
Unsuccessful online transaction
APPROVED
Non-Monetary
Successful offline transaction for Terminal based processors, or
successful Pre-Authorization for Host based processors)
NOT APPROVED
Varies
Unsuccessful offline transaction or unsuccessful Pre-Authorization
for Host based processors
PROCESSED
Off-line Transaction, Report
Transaction was processed (Terminal based processors only); report
was generated
CANCELLED
Any
Transaction canceled by operator or modem never connected
VOIDED
Void
Successful (with most Terminal based processors)
SALE NOT FOUND
Follow On (Void, Gratuity,
etc.)
Unsuccessful (with most Terminal based processors)
GRATUITY ADDED
Gratuity
Successful (Offline Transaction for Terminal based processors.
Depending on the processor and amount, some Gratuity
transactions may be authorized online for Terminal based
processors)
Error
Varies
Unsuccessful transaction
Problem
Report
Unsuccessful Report Request
SALE RECOVERED
Debit Sale Recovery
Successful Debit Sale Recovery
RETURN RECOVERED
Debit Return Recovery
Successful Return Recovery
Settle Error
Settlement
Unsuccessful Settlement
Closed
Batch Close
Successful Batch Close
not closed
Batch Close
Unsuccessful Batch Close
OPEN TO BUY
Private Label
Successful Open to Buy Inquiry on an ADSI Private Label card
INVALID PARAM
Transaction Inquiry
Account number or TroutD not passed to Transaction Inquiry
command
Accepted
Settlement
Successful Settlement
Result Code = 2
Settlement
Batch Closed/Settled
81
Result
Transaction Type
Description
Result Code = 6
Settlement
Batch Declined
Result Code = 8
Settlement
Batch Deferred
82
Appendix C – PAYware PC, PAYware Transact and PAYware
Connect Constants
Address Verification Response Codes
Response Code
Address Match
A
Address matches, ZIP code does not
E
Not a mail-order/phone order
N
No match on address or ZIP code
R
Retry, system is unavailable or timed out
S
Service not supported by issuer (card type does not support AVS)
U
Address information is unavailable
W
X
Exact match, 5 digit zip
Y
Exact Match, 9 digit zip
Z
CVV2/CVC2/CID Response Codes
Response Code
Address Match
M
CVV2/CVC2/CID match
N
CVV2/CVC2/CID mismatch
P
Not processed -- Either the CVV2/CVC2/CID was not provided, or the card does not have
a CVV2/CVC2/CID value. If the CVV2/CVC2/CID was left blank, resubmit as a zero dollar
amount for the transaction so the customer's credit line won't be affected by the second
CVV2/CVC2/CID request.
S
Issuer indicates that the CVV2/CVC2/CID data should be present on the card, but the
merchant has indicated that the CVV2/CVC2/CID data is not present on the card.
U
Issuer has not certified for CVV2/CVC2/CID or issuer has not provided Visa/MasterCard
with the CVV2/CVC2/CID encryption keys.
83
Payment Media
Credit Card Issuer
Credit Card Type
American Express
"AMEX"
Carte Blanche
"CBLN"
Diner‘s Club
"DCCB"
Discover
"DISC"
Enroute
"ENRT"
Fleet One
"FLT1"
Fuelman
"FUEL"
JAL
"JAL "
JCB
"JCB "
MasterCard
"MC "
Wright Express
"WEX "
Visa
"VISA"
Voyager
"VGER"
84
PAYware Transact and PAYware Connect Transaction Result Constants
These results are returned by the .GetResult method of SIM.DLL
Result
Result Code
Description
SUCCESS
-1
Successful API Call
UNKNOWN
0
Unknown Result
APPROVED
5
Successful offline transaction for Terminal based processors, or
successful Pre-Authorization for Host based processors)
CAPTURED
4
The transaction was approved and captured in the batch
Unsuccessful offline transaction or unsuccessful Pre-Authorization
for Host based processors
NOT APPROVED
DECLINED
6
The transaction was declined
Transaction was processed (Terminal based processors only); report
was generated
PROCESSED
The result of the transaction is deferred to each batch segment
DEFERRED
VOIDED
7
Successful (with most Terminal based processors)
COMPLETED
10
PARTCOMP
11
Partial Completion
TIP MODIFIED
17
Tip modification
The transaction was completed successfully and placed in the batch
The ERROR value will be returned if the Termination Status is
anything other than SUCCESS.
ERROR
SETTLED
2
Successful Batch Close
DECLINE
092
Transaction Encrypted, No Terminal Keys.
Note: PAYware Connect Only
Note: VeriShield Protect (VSP) Transactions Only
NOT AVAILABLE
30000
Backend Payment Engine is not available
85
*There are various error result
codes that are not listed. For
more information on these
codes, contact VeriFone support.
Termination Status
Response Code
Address Match
SUCCESS
Successful transaction request (check the Result or ResultCode value to determine if the
transaction was approved, declined, etc.)
NOT PROCESSED
API call not successful
NOT PROCESSED DB
FAILURE
API call not successful. Database failure
NOT PROCESSED
PARAMETER ERROR
API call not successful. Parameter error
NOT PROCESSED COMM
FAILURE
API call not successful. Communication failure
NOT PROCESSED ENGINE
Backend payment engine is not available
NOT ACCESSABLE
INDETERMINATE STATUS API call not successful. Indeterminate status
PROCESSED DB FAILURE API call successful. Database failure
UNKNOWN
Unknown error
86
Appendix D - Unmanaged Code
It is possible to have PAYware SIM run in Debug with Unmanaged Code. This is any environment outside .NET. The
environment could be Vb6, C++, FoxPro, etc. It is, however, necessary to run the COM-Dev.bat file on the development
machine. This is located with PAYware SIM development kit files. Please make sure to change the path in the .bat file prior
to running it. This .bat file will create a .tlb file in the SIM.DLL path. This is the file you will need to reference in your
code.
In the client environment the .tlb file is not necessary. SIM.DLL will still need to be registered on any client machine when
dealing with Unmanaged Code (anything other than .NET). Upon deployment, the integrator should run the COM.bat file
instead.

Note
When using the .bat file, it is important to make sure there are no spaces in the path.
Examples
C:\Program Files – Incompatible Path
C:\VeriFone\SIM – Compatible Path
87
Appendix E – TIM: Store and Forward Module
TIM (Terminal Interface Module) provides a Store and Forward option for PAYware Connect. TIM is used in conjunction with
SIM.DLL. It is important to note that TIM should not be configured to drive devices such as PIN pads when used in
conjunction with PAYware SIM.
88
Appendix F – VeriShield Protect©
VeriShield Protect© (VSP) allows an integrator to pass card swipe data (Track II) securely to PAYware Connect. The
merchant will need to have a device that supports VSP and an account setup with PAYware Connect that also has VSP
enabled. PAYware Connect requires Track II Data (Track), Serial Number (SerialNumber), and Device Type (DevType) to
process a VSP transaction. This ensures the transaction is properly encrypted. At this time only Track II data is supported.
The merchant uses a Command Card to generate the encryption key. This must be sent prior to submitting any other
transactions. A Command Card looks like a credit card, but is specifically issued to the merchant to initiate commands.
These commands are passed to PAYware Connect like any other SALE transaction. These transactions will have a RESULT of
DECLINE and a TERMINATION_STATUS of NOT_PROCESSED. Please check the RESULT_CODE and RESULT_TEXT to determine
the success of the command.
If an encryption key is not generated prior to the first transaction, the merchant will receive the following:
<RESPONSE>
<RESPONSE_TEXT>TRX ENCRYPTED, NO TERMINAL KEYS</RESPONSE_TEXT>
<RESULT>DECLINE</RESULT>
<RESULT_CODE>092</RESULT_CODE>
<TERMINATION_STATUS>NOT_PROCESSED</TERMINATION_STATUS>
</RESPONSE>

Note
See PAYware Connect Developer‘s manual, section Appendix B: VeriShield, for more
information regarding VeriShield Protect© and transactions.
89
Appendix G - MX Passthrough FormAgent Commands










REQ packets are sent from the POS (PC side) to the Terminal.
RSP packets are sent from the Terminal side to the POS (PC side).
The normal link-level packet protocol will be observed, i.e., all packets on either side will be responded to with
an ACK or NAK if the LRC is good or bad respectively. The 'RSP' responses shown below are packet-level responses
from the terminal to the POS, and indicate a success/failure status after processing the packet.
The LRC (Longitudinal Redundancy Check) is computed by exclusive OR'ing (i.e., XOR‘ing) all characters in the
message except the STX but including the ETX. Both the sending and receiving sides perform this calculation.
In all RSP packets below, the RetVal field signifies a Boolean value (0=Failure, 1=Success) unless otherwise
specified.
All data in the request (REQ) packets below in general are textual strings (i.e., there are no binary fields), except
for special protocol characters such as <STX>, <ETX>, <FS> and {LRC} (Longitudinal Redundancy Check character).
E.g., the OverwriteFlag field of the SFL command is either ‗0‘ (hex 30) or ‗1‘ (hex 31).
All packets will contain a leading <FS>-separated command name, followed by a string of fieldname or
―fieldname=fieldvalue‖ sequences, each separated by an <FS> character.
All packets being sent/received via TCP/IP will have a leading 2-byte message length header/prefix in networkbyte order, indicating the length of the trailing data.
If the POS application displays a form containing buttons or other controls that generate events, or enables the
magnetic /RFID card reader, due to the asynchronous nature of events such as magnetic card swipes, RFID card
taps or button presses, it MUST be prepared to receive asynchronous event packets (e.g., 81., XEVT, ...) at any
time.
All objects drawn on the form have an associated ControlID. This is used as a key. The ControlIDs are contained in
the file ctrlids.h, which is generated when the other form files are generated.
90
Command
SFL
Function/Description
StoreFile
Request/Response Packets and notes
REQ: <STX>SFL<FS>FileName<FS>FileSize<FS>BlockSize<FS>OverwriteFlag<ETX>{LRC}
RSP: <STX>SFL<FS>RetVal<FS>RetValString<ETX>{LRC}
Where:
FileName = name of file to download to device
FileSize = size of file
BlockSize = number of bytes being transmitted in one block
OverwriteFlag = boolean value,
0 => Don‘t overwrite file if it exists
1 => overwrite file if it exists
DATA BLOCK record packet formats:
REQ: <STX>XDAT<FS>MPPPPSSSS{data upto PPPP bytes}<ETX>{LRC} *** DATA record
Where: M = more records indicator; Y = Yes, N = No
The last XDAT record has M=N
PPPP = number of data bytes in *this* packet
SSSS = Sequence number of block
RSP: <STX>XDAT<FS>{RetVal}<ETX>{LRC}
Where:
RetVal = 1 will indicate a good XDAT was received; file write was successful.
RetVal = 0 will indicate failure.
Final RSP: <STX>SFL<FS>RetVal<FS>RetValString<ETX>{LRC}
The RSP SFL1 comes after the initial REQ, and also after the last XDAT block has been received (SFL2)
and acknowledged.
RetVal = 0 - Unsuccessful operation
1 - Successful operation
RetValString - contains a text description of the result.
Purpose: Used to download files to the terminal at runtime.
Sample trace:
Transmit: <STX>SFL<FS>SIG1_100_100.PTS<FS>410<FS>0256<FS>1<ETX>J -- HEADER
Receive : <ACK>
Receive : <STX>SFL1<FS>1<FS>SUCCESS<ETX>(
-- HEADER RSP
Transmit: <ACK>
Transmit: <STX>XDAT<FS>Y02560001{data...}<ETX>{LRC} } Multiple -- DATA BLOCK(s)
Receive : <ACK>
} of
Receive : <STX>XDAT<FS>1<ETX>'
} these -- DATA BLOCK RSP(s)
Transmit: <ACK>
}
...
Receive : <STX>SFL2<FS>1<FS>SUCCESS[*]<ETX>(
-- TRAILER RSP
Transmit: <ACK>
NOTE:
If the file being downloaded has the following extensions, it is automatically expanded after being
downloaded:
.tar (regular tar archive)
.tgz –or- tar.gz (gnu zipped format)
.bz2 (binary zipped format)
1
This is the initial SFL response indicating whether the download will be permitted or not.
This is the final SFL response:
[*]
SUCCESS
-– normal case
–orSUCCESS:DEVICE REBOOTING -- device is about to reboot after download
2
91
-
-
XRFL
RemoveFile
XIFM
InitForm
XSFM
ShowForm
REQ: <STX>XRFL<FS>FileName<ETX>{LRC}
RSP: <STX>XRFL<FS>RetVal<ETX>{LRC}
Purpose: Remove a file on the terminal
REQ: <STX>XIFM<FS>FormName<ETX>{LRC}
RSP: <STX>XIFM<FS>RetVal<ETX>{LRC}
Purpose: Used to initialize a form, preparing it for display on the terminal.
REQ: <STX>XSFM<ETX>{LRC}
-or<STX>XSFM<FS>PresentationMode<ETX>{LRC}
RSP: <STX>XSFM<FS>RetVal<ETX>{LRC}
Where PresentationMode is:
‗1‘ = PM_NORMAL
– default: new form overlays old form
‗2‘ = PM_LEFT_TO_RIGHT
- new form moves in from left to right
‗3‘ = PM_RIGHT_TO_LEFT
- new form moves in from right to left
‗4‘ = PM_TOP_DOWN
– new form moves in top-down
‗5‘ = PM_BOTTOM_UP
– new form moves in bottom-up
‗6‘ = PM_FADE
- new form fades in
Purpose: Used to show a form on the screen that was previously initialized via InitForm.
XGPV
XSPV
GetPropValue
SetPropValue
Note: The above PresentationMode capability is useful only if operating in a buffered mode (i.e.,
BUFFERED_UI_UPDATES=1), and for the very first XSFM command after a form is newly initialized with
XIFM. Although the presentation modes 2 through 6 take effect for subsequent XSFM calls from then on
for the form, it is not as appealing visually or recommended: use normal mode instead.
REQ: <STX>XGPV<FS>ControlID<FS>PropName<FS>PropType<ETX>{LRC}
RSP: <STX>XGPV<FS>PropValue<ETX>{LRC}
Purpose: Used to get a property value from a control in the form. See the PropName and PropType
sections below for possible values.
REQ: <STX>XSPV<FS>ControlID<FS>PropName<FS>PropType<FS>PropValue<ETX>{LRC}
RSP: <STX>XSPV<FS>RetVal<ETX>{LRC}
Purpose: Used to set a property value on a control in the form. See the PropName and PropType
sections below for possible values.
NOTE: All the XSPV/SetPropValue functions will be ignored if there is a blocked MessageBox currently
displayed on the screen.
REQ: <STX>XIFL<FS>FormName<ETX>{LRC}
RSP: <STX>XIFL<FS>RetVal<ETX>{LRC}
XIFL
IsFormLoaded
XGLF
GetLoadedForm
Purpose: Used to query if the specified form is currently loaded or not.
REQ: <STX>XGLF<ETX>{LRC}
RSP: <STX>XGLF<FS>FormName<ETX>{LRC}
XCLB
ClearListBox
Purpose: Used to return the currently loaded form.
REQ: <STX>XCLB<FS>ControlID<ETX>{LRC}
RSP: <STX>XCLB<FS>RetVal<ETX>{LRC}
Purpose: Used to clear the contents of a listbox control in the current form. (The listbox control must
be present in the current form).
92
XALI
AddListBoxItem
REQ: <STX>XALI<FS>ControlID<FS>ItemIndex<FS>ItemText<FS>KeepCopyFlag<ETX>{LRC}
RSP: <STX>XALI<FS>RetVal<ETX>{LRC}
ItemIndex is zero-based.
ItemIndex = 0  will add the item to the TOP of the list
= -1  will add the item to the END of the list
>=0 and < ListCount-1  will add the item at the specified index KeepCopyFlag = 1  Keep
shadow copy of item (for use in XLRS command)
XRLI
XGLI
RemoveListBoxItem
GetListBoxItem
XGLC
GetListBoxItemCount
XGLS
GetListboxSelectedItem
XSLT
XLRS
XLCS
SetListBoxTopItem
ListboxRestoreState
ListboxClearState
Purpose: Used to add a line of item text to a listbox control specified by ControlID.
REQ: <STX>XRLI<FS>ControlID<FS>ItemIndex<ETX>{LRC}
RSP: <STX>XRLI<FS>RetVal<ETX>{LRC}
Purpose: Used to remove a line of item text at the specified index (ItemIndex) from a listbox control
specified by ControlID.
REQ: <STX>XGLI<FS>ControlID<FS>ItemIndex<ETX>{LRC}
RSP: <STX>XGLI<FS>ItemText<FS>RetVal<ETX>{LRC}
Purpose: Used to return a line of item text from the specified index (ItemIndex) from a listbox control
specified by ControlID.
REQ: <STX>XGLC<FS>ControlID<ETX>{LRC}
RSP: <STX>XGLC<FS>ItemCount<ETX>{LRC}
Purpose: Used to get a count of the number of items in the listbox control specified by ControlID.
REQ: <STX>XGLS<FS>ControlID<ETX>{LRC}
RSP: <STX>XGLS<FS>ItemIndex<ETX>{LRC}
Purpose: Used to get the index of the currently selected list item.
REQ: <STX>XSLT<FS>ControlID<FS>ItemIndex<ETX>{LRC}
RSP: <STX>XSLT<FS>RetVal<ETX>{LRC}
Purpose: Used to set the specified list item index as the topmost visible item in the specified listbox
control.
Note: A best-case attempt is made to satisfy this command. E.g., if there is a listbox that can have 6
items visible at a time and there are only 4 items added, and this command is sent to make the 3 rd item
the top-most, nothing will be done (since there are 2 empty rows below the last item). On the other
hand, if there are 10 items in the list and a command is sent to make the 3rd item the top-most, the
item with index 3 will be made the topmost, and the items with indices 3, 4, 5, 6, 7, 8 will all be
visible.
REQ: <STX>XLRS<FS>ControlID<ETX>{LRC}
RSP: <STX>XLRS<FS>RetVal<ETX>{LRC}
RetVal  Count of listbox items restored
Purpose: Used in conjunction with the XALI command; used to update a listbox control with a cached
copy of listbox items.
REQ: <STX>XLCS<ETX>{LRC}
RSP: None
Purpose: Used in conjunction with the XALI and XLRS commands; used to clear the cache of listbox
items
93
XMBX
MessageBox
REQ: <STX>XMBX<FS>Title<FS>Text<FS>Icon<FS>Buttons<FS>Blocked<ETX>{LRC}
RSP: <STX>XMBX<FS>RetVal<ETX>{LRC}
Where:
Icon can have one of the following values:
1 = ERROR Icon
2 = INFO Icon
3 = QUERY Icon
4 = WARNING Icon
Buttons can have one of the following values:
0 = No buttons
1 = OK button
2 = CANCEL button
3 = YES and NO buttons
4 = YES, NO and CANCEL button
Blocked can have one of the following values:
0 = messagebox is not blocked
1 = messagebox is blocked
RetVal has one of the following values:
- for Blocked messageboxes:
-1 = Invalid packet
1 = OK button
2 = CANCEL button
3 = YES button
4 = NO button
- for Unblocked messageboxes:
0 = Failed to display messagebox
1 = messagebox successfully displayed
XMBH
HideMsgBox
XDIA
DisplayImageAt
Purpose: Used to display a messagebox to the user.
NOTE: All the XSPV/SetPropValue functions will be ignored if there is a blocked MessageBox currently
displayed on the screen.
REQ: <STX>XMBH<ETX>{LRC}
RSP: None
Purpose: Hide a displayed MessageBox.
REQ: <STX>XDIA<FS>X<FS>Y<FS>ImageFileName<FS>
[Width<FS>Height<FS>OptionsMask]ETX>{LRC}
RSP: <STX>XDIA<FS>RetVal<FS>RetValString<ETX>{LRC}
ImageFileName – MUST be a PNG or JPG file, with '.jpg'/'.png' filename extension
OptionsMask:
Bit position
3
Meaning
0x0004:
Scale image (up or down) to match Height and Width values (if
specified)
If this option bit is set, the image will be scaled to match the
specified height and width values.
If this option bit is not set, the image will be shown with its true
height and width
Purpose: Used to display an image file at the specified [X,Y] pixel coordinates.
94
-
XGID
GetInputData
NOTE:
1) Width, Height and OptionsMask fields are optional; however, if present, ALL must be present
(i.e., a total of 7 fields).
2) There is another (recommended) solution to update an image on a form: an Image control can
be setup on a form and used as a template/placeholder with a default image file. Then at runtime,
the IMAGE_FILE_NAME property of the Image control can be updated by using XSPV/SetPropValue
to set it to the new image filename.
3) Currently if present, the OptionsMask value must be set to ―4‖ to perform scaling. If an invalid
value is specified, the image will be shown with its true dimensions.
4) If no/invalid image dimensions are specified or scaling is not specified, the image's true
dimensions from the image file are used.
REQ: <STX>XGID<ETX>{LRC}
RSP: <STX>XGID<FS>ControlID1<FS>FieldType1<FS>FieldValue1<FS>
ControlID2<FS>FieldType2<FS>FieldValue2<FS>
...
ControlIDN<FS>FieldTypeN<FS>FieldValueN<ETX>{LRC}
ControlID = control ID of individual checkboxes in the form.
Field Type = always BOOL for checkboxes.
Field Value = 1 => Checkbox checked
Field Value = 0 => Checkbox unchecked
XCLS
ClearScreen
Purpose: Use this function/packet to get the state of all checkboxes in a form.
REQ: <STX>XCLS<FS>X1<FS>Y1<FS>X2<FS>Y2<ETX>{LRC}
RSP: <STX>XCLS<FS>RetVal<ETX>{LRC}
X1 = starting X coordinate
Y1 = starting Y coordinate
X2 = ending X coordinate
Y2 = ending Y coordinate
XRST
RestartTerminal
Purpose: Clears the ENTIRE screen area. The X1,Y2,X2,Y2 coordinate values are optional, but are
maintained for backward compatibility with the Omni 7100 command packet API. If not present, the
entire screen is cleared. If present however, ALL 4 field values must be supplied.
REQ: <STX>XRST<ETX>{LRC}
RSP: None
Purpose: Reboots the terminal.
XRSTAPP
RestartApp
XDTX
DisplayText
NOTE:
If using USB communication, the PC application should close the virtual USB COM port, so that the OS
(Windows) will properly create it again when the Mx870 USB device is re-detected after it boots up.
REQ: <STX>XRSTAPP<ETX>{LRC}
RSP: None
Purpose: Restarts the FormAgent application.
REQ: <STX>XDTX<FS>X<FS>Y<FS>
WrapRow<FS>WrapColumn<FS>OptionsMask<FS>FontName<FS>
FontSize<FS>Text[<FS>Colors]<ETX>
RSP: <STX>XDTX<FS>RetVal<FS>NewX<FS>NewY<ETX>{LRC}
where:
FontName - is a pipe-separated list of sub-fields containing font names for normal, bold, italics
AND bold-italics, without ―.ttf‖ extension.
The normal fontname is MANDATORY; any of the other FontName sub-fields may simply
o
be left blank, in which case, the normal font name will be used.
E.g., VeraMono|VeraMoBd||VeraMoBI -- the Italics fontname (VeraMoIt) is not specified, so the normal
fontname (VeraMono) is used in lieu of it
Colors - is a OPTIONAL pipe-separated list of background (BGColor), foreground (FGColor) and
selection (SelColor) colors:
BGColor|FGColor|SelColor – in RRGGBB format
95
E.g., BGColor = FFFFFF – for white background
FGColor = 008000 – for green text
SelColor = FFFF00 – for yellow highlighter text
Purpose: Used to display text with embedded attributes at the specified [X,Y] pixel coordinates. The
text will automatically wrap on the screen at the specified WrapColumn.
The Text parameter can contain embedded directives for turning on bold, italics, underline, reversevideo (selection) and strike-through attributes for sections of the text. You can intersperse font
attributes throughout the text:
- For bold, will turn ON the bold attribute, the next will turn it OFF
- For italics, will turn ON the italics attribute, the next will turn it OFF
- For underline, will turn ON the underline attribute, the next will turn it OFF
- For selection, <R> will turn ON the selection attribute (i.e., will display text in the specified SelColor),
the next <R> will turn it OFF
- For strikethrough, <S> will turn ON the strike-through attribute, the next <S> will turn it OFF
The effects of an attribute once turned on remain in effect until turned off. Thus you may have
multiple attributes ON at the same time, and all attribute effects will be applied to the relevant text
block.
OptionsMask – mask value representing the decimal value of the sum of the options. Bit value 0 implies
the option is OFF, value 1 implies the option is ON.
Mask
Meaning
0x0001
Visible: 0 = not visible; 1 = visible
0x0002
Border Visible: 0 = border not visible; 1 = border visible
0x0200
Display border if scrollbars are displayed
0x0400
Add vertical scrollbar
0x0800
Add horizontal scrollbar
0x1000
Strip leading blanks in line of text
0x2000
Ignore height parameter, display all text provided
0x4000
Auto-wrap text
0x8000
Make text background transparent
// E.g.
If the following command is sent:
XDTX<FS>10<FS>10<FS>100<FS>300<FS>21507<FS>VeraMono|VeraMoBd|VeraMoIt|VeraMoBI
<FS>12<FS><R>Note:<R> Please pick up your <S>TWO<S> FIVE complimentary tickets at the
customer service desk on the way out.<FS>FFFFFF|008000|FFFF00
...the text display on the screen (wrapped accordingly) will look like:
Error! Objects cannot be created from editing field codes.
NewX – new X coordinate (pixel) for next write operation
NewY – new Y coordinate (pixel) for next write operation
96
XATT
AddTextboxText
XCTT
ClearTextboxText
XEVT
FormEvent
REQ: <STX>XATT<FS>ControlID<FS>Text<ETX>{LRC}
RSP: <STX>XATT<FS>RetVal<ETX>{LRC}
Purpose: Used to add (append) text to a textbox control.
REQ: <STX>XCTT<FS>ControlID<ETX>{LRC}
RSP: <STX>XCTT<FS>RetVal<ETX>{LRC}
Purpose: Used to clear text in the textbox control.
RSP: <STX>XEVT<FS>ControlType<FS>ControlID<FS>ControlData<ETX>{LRC}
Where:
ControlType = identifier indicating which type of control fired the event
ControlID = Control Identifier assigned by Form Manager tool.
ControlData = <FS>-separated values specific to the EventType.
Purpose: This packet is sent whenever an event occurs on a form and there is an associated callback
function specified. E.g., a button is pressed or a listbox item is selected.
XEVT response by control type:
For Button controls:
<STX>XEVT<FS>2<FS>ControlID<FS>0<ETX>
For CheckBox controls:
<STX>XEVT<FS>6<FS>ControlID<FS>SelectedState<ETX>
Where:
SelectedState: 0=Not selected; 1=selected
For Animation controls:
<STX>XEVT<FS>8<FS>ControlID<FS><ETX>
For KeyPad controls:
<STX>XEVT<FS>0<FS>ControlID<FS>KeyEvent<FS>Value<ETX>
Where:
KeyEvent: 1=ON_KEYPRESS; 2=ON_ENTER; 3=ON_CANCEL
Value:
When KeyEvent=ON_ENTER, this is the entered value, or empty if no value is entered
When KeyEvent=ON_CANCEL, this indicates the reason code for cancellation:
1=USER_ABORT (user pressed CANCEL); 2=PGM_ABORT (application abort)
Q1/Q12
Q11
Q13
GetCardData(TracksToRead)
NOTE:
If the PC POS developer wishes to suppress an event for any Control on a Form (except Buttons), then
all that is required is that the callback function name of the control be deleted in the Form Manager
designer. Then when the form is generated, that Control‘s events are effectively disabled.
REQ: <STX>Q1<ETX>{LRC}
}
REQ: <STX>Q12<ETX>{LRC} } Possible requests
REQ: <STX>Q11<ETX>{LRC} }
REQ: <STX>Q13<ETX>{LRC} }
RSP: <STX>81.CardData<FS>CardDataSource<ETX>{LRC}
Where:
TracksToRead = string containing tracks to read, e.g., ―1‖, ―2‖, ―3‖, ―12‖, ―13‖, ―23‖.
CardData = <FS>-separated track data in sequential order:
{Track1}<FS>{Track2}<FS>{Track3}
CardDataSource = „M‟ => for magstripe card-swipe
= „R‟ => for RFID card tap
Purpose: Used to enable the magnetic stripe reader (and RFID reader) to get card data from the
terminal.
97
S00
GetSignatureData
REQ: <STX>S00<ETX>{LRC}
RSP: <STX>S01xxxxxyyyyzerrr<ETX>{LRC}
<STX>S02Muuuu{sigdata}<ETX>{LRC} – one or more of these records
Where: xxxxx = total number of bytes (5 bytes long)
yyyy = Number of bytes per packet
z = Signature file format (0 = Raw, 1 = TIFF100, ..., 4 = TIFF400,
5 = 3BA, 6 = Windows BMP)
e = 0 = Big Endian, 1 = Little Endian (only used when savemode m=0)
rrr = Signature filter resolution
M = More indicator: Y (for more data) or N (for no more data)
The last S02 record has M=N
uuuu = Actual size of signature data in current packet
(excluding 11-byte envelope: <STX>S02Muuuu (9) and <ETX>{LRC} (2))
{sigdata} = Actual signature data
Purpose: Used to initiate signature capture on the terminal.
S03
SetSigCapParams
NOTE:
1) The application developer is expected to display an appropriate sigcap form containing
Complete and Cancel buttons and a signing box (also see #3 below) and issuing a S04 command to
indicate the sigcap region before issuing a S00 request. (Sending a S00 command without these
preliminary commands will result in the display of a default sigcap region without any Complete
and Cancel buttons!)
2) The response will be one S01 packet with one or more S02 packets. Each S02 packet contains
the field ‗M‘ above indicating whether another S02 packet will follow.
3) The Complete and Cancel buttons MUST have HotSpot IDs of 1 and 2 respectively (since this is
what is needed in the OS call on the terminal. You can use the FormManager to change). Only
―VeriFone raw‖ sigcap format is supported at this time. Use the S03 command to indicate what the
response format should be. The signature is streamed up to the PC in the above S01/S02 packet
format. Note that during the sigcap (i.e., after S00 is sent), the Complete and Cancel buttons are
controlled by the OS sigcap routine. After the sigcap is done, however, pressing these buttons will
send back regular XEVT event packets. This should not be an issue since, on receiving the
signature, the POS will navigate off to another form.
4) After signature capture and before displaying the next form, the POS may optionally send the
XPNG command to get the signature directly off the terminal screen in Portable Network Graphics
(PNG) file format (only the signature within the signing box region will be returned in the
snapshot).
REQ: <STX>S03sssdddxerrrmF{fn}<ETX>{LRC}
RSP: None
Where:
sss = Max time in seconds to wait for user to begin signing.
Range is 000 - 300 (3 bytes); 000 indicates no timeout.
ddd = Max time in seconds to wait after a user completes signing.
Range is 000 - 300 (3 bytes); 000 indicates no timeout.
x = display mode, if zero, do not erase display when the
first pen down is detected (1 byte)
e = 0 = Big Endian, 1 = Little Endian (only used when savemode m=0)
rrr = Signature resolution
Range is 000 - 999. (3 bytes)
m = Save mode (1 byte)
0 = VFI RAW file format
1 = Save a 100 DPI TIF File
5 = 3-Byte ASCII (3BA) File
6 = Windows Bitmap File (BMP)
F = File saved in flash or not (1 byte)
0 = Do not save in flash file system
1 = Save in flash file system
{fn} = Filename to be used, up to six characters (optional field)
98
No extension is needed.
Purpose: Updates the signature capture parameters.
S04
XPNG
SetSigCapBoxArea
GetScreenShot
REQ: <STX>S04xxxyyyXXXYYYC<ETX>
RSP: None
Where:
xxx,yyy = start X,Y coordinates of sigbox
XXX,YYY = end X,Y coordinates of sigbox
C = Clear area flag: 0=OFF, 1=ON
Purpose: Sets the coordinates of the signature box.
NOTE: This packet MUST be sent before a S00 packet.
REQ: <STX>XPNG<FS>X<FS>Y<FS>Width<FS>Height<ETX>{LRC}
RSP: <STX>XPNG<FS>NNNNN<FS>BBBB<ETX>{LRC}
Where NNNNN = file size
BBBB = bytes per packet
-- HEADER record
<STX>XDAT<FS>MPPPPSSSS{data upto PPPP bytes}<ETX>{LRC} -- DATA record
Where: M = more records indicator; Y = Yes, N = No
PPPP = actual number of bytes in *this* packet
SSSS = Sequence number of block
FAILURE RSP:
<STX>XPNG<FS>RetVal<FS>RetValString<ETX>{LRC}
XBEL
SoundTone
72
ResetTerminalState
Z60
GetPinUsingMS –orGetPinUsingDUKPT
Purpose: Used to grab screen shots in PNG format.
NOTE: The DATA records contain the image in PNG format.
REQ: <STX>XBEL<FS>TONE<FS>INTERVAL<FS>REPETITIONS<ETX>
RSP: None
Where:
TONE
= 0 => ERROR TONE, 1 => NORMAL TONE
INTERVAL = Interval between tones in milliseconds
REPETITIONS = Number of times to repeat the tone
Purpose: Used to sound a tone.
REQ: <STX>72<ETX>
RSP: None
Purpose: Resets the terminal application state. This packet should also be sent anytime there is an
outstanding device request that you wish to cancel (such as a S00 sigcap request, a Q1x magstripe
reader request, etc.)
Purpose: Used to initiate a PIN request on the terminal.
For Master/Session (M/S):
REQ: <STX>Z60.{AA..A}<FS>WWWWWWWWWWWWWWWW<ETX>  M/S request packet
RSP: <STX>71.0LL01PPPPPPPPPPPPPPPP<ETX>
-or<STX>71.<EOT><ETX>  if CANCEL is pressed or
other error [e.g., Terminal is in M/S mode (MK=0)]
-or<STX><EOT><ETX>  if PIN pad is not injected with proper key(s)
For DUKPT:
REQ: <STX>Z60.{AA..A}<ETX>  DUKPT request packet
99
RSP: <STX>73.00000KKKKKKKKKKKKKKKKKKKKPPPPPPPPPPPPPPPP<ETX>
-or<STX>73.<EOT><ETX>  if CANCEL is pressed or
other error [e.g., Terminal is in DUKPT mode (MK=1)]
-or<STX><EOT><ETX>  if PIN pad is not injected with proper key(s)
AA..A = Card Account Number (8-19 digits)
WW..W = 16-byte Working Key
LL = PIN length (Range 04-12)
PP..P = 16-byte encrypted PIN Block
KK..K = 10-20 byte Key Serial Number (KSN) with leading F‘s suppressed
Z62
GetPinExUsingMS –orGetPinExUsingDUKPT
NOTE:
The minimum and maximum PIN length is 4 digits and 12 digits respectively.
The FormAgent application automatically uses a built-in form (PINE.FRM) to display a PIN pad for
PIN entry. The POS application does not need and in fact should NOT use one of its own forms for
PIN entry.
Null PIN is not allowed
For Master/Session (MK=0):
-
REQ: <STX>Z62.{AA..A}<FS>WWWWWWWWWWWWWWWWmmMMn{P1}<FS>{P2}<FS>{P3}
{CCNVFlag}<ETX>
RSP: <STX>71.0LL01PPPPPPPPPPPPPPPP<ETX>
-or<STX>71.<EOT><ETX>  if CANCEL is pressed or other error
-or<STX>71.<ETX>  if ENTER is pressed with Null PIN
For DUKPT (MK=1):
REQ: <STX>Z62.AA..A<FS>mmMMn{P1}<FS>{P2}<FS>{P3}{CCNVFlag}<ETX>
RSP: <STX>73.00000KKKKKKKKKKKKKKKKKKKKPPPPPPPPPPPPPPPP<ETX>
-or<STX>73.<EOT><ETX>  if CANCEL is pressed or other error
-or<STX>73.<ETX>  if ENTER is pressed with Null PIN
AA..A = Card Account Number (8-19 digits)
WW..W = 16-byte Working Key
mm = minimum PIN length
MM = maximum PIN length
n
= NULLPIN flag; Y => Null PIN allowed, N => Null PIN not allowed
P1 = Prompt1 – Part 1 of PIN prompt; max length = 16 characters
P2 = Prompt2 – Part 2 of PIN prompt; max length = 16 characters
P3 = Prompt3 – Message displayed after PIN is entered and ENTER is pressed;
Max length is 16 characters.
LL = PIN length (Range 04-12)
PP..P = 16-byte encrypted PIN Block
KK..K = 10-20 byte Key Serial Number (KSN) with leading F‘s suppressed
CCNVFlag = Credit Conversion flag – used ONLY if NULLPIN flag in packet = ‗Y‘;
0 = no credit conversion during PIN entry
1 = Credit conversion during PIN entry (ONLY if NULLPIN=Y);
KeyPad‘s ENTER key starts off with ‗CREDIT‘ label,
then changes to ENTER if/when PIN entry is started.
NOTE:
The advantage of using this packet/function over Z60 is that the minimum and maximum PIN

lengths can be specified.
Note that the maximum for P1 + P2 is 32 characters, and they will be
concatenated together
for the PIN entry prompt.
100

XDLD
ZonTalkDownload

The filename pinpadbg.png is used by the internal PIN entry screens for the PIN form background.
It can be changed to something more suitable if required, to create a uniform background image
scheme being used by the forms in the application.
REQ: <STX>XDLD<FS>FileName<FS>DownloadType<ETX>{LRC}
RSP: <STX>XDLD<FS>RetVal<FS>RetValString<ETX>{LRC}
Where:
FileName = name of file to be downloaded
DownloadType = ‗P‘ = PARTIAL download (contents of file system are NOT erased)
‗F‘ = FULL download (contents of file system are erased)
Purpose: Used to perform a programmatic download of a file using the ZonTalk protocol. If the file
being downloaded has a .tar or .tgz extension, it is automatically expanded after being downloaded.
REQ: <STX>XVER<ETX>{LRC}
RSP: <STX>XVER<FS>APP={App_Version}<FS>
OS={OS_RFS_Version}<FS>
GUIMGR={GUI_Library_Version}<FS>
UNITID={UnitIDNumber}<FS><ETX>
XVER
E.g.
<STX>XVER<FS>APP=0.06<FS>OS=Mx0001US/RFS00013<FS>GUIMGR=0.06<FS>
UNITID=763-000-063/12000000<FS>CLOCK=20060716161116<FS><ETX>
XLED
LEDControl
NOTE: The CLOCK field contains the device‘s current date/time setting.
REQ: <STX>XLED<FS>ON_OFF<ETX>{LRC}
RSP: None
Where:
ON_OFF = ‗0‘ = Turn LEDs OFF
‗1‘ = Turn LEDs ON
Purpose: Turn LEDs on or off.
XSETVOL
SetVolumeControl
Note:
If the AUTOLED configuration variable is 1 (on), the LEDs are automatically turned on whenever a
MSR cardswipe request is issued, and turned off automatically when the card swipe occurs.
The default value for AUTOLED is 1 (on).
Typically applications that need to control LED behavior will have the AUTOLED value set to 0
(off), and will explicitly control turning them on/off via this command.
REQ: <STX>XSETVOL<FS>Volume<FS>Bass<FS>Treble<ETX>{LRC}
RSP: None; the specified volume setting are applied
Where:
Volume - accepted values 0 - 100; 0 = Sound off; 100 = Max vol
Bass - accepted values: 50 - 100
Treble - accepted values: 50 – 100
XGETVOL
GetVolumeControl
XFTPGET
XFTPPUT
FTPGetFile
FTPPutFile
Purpose: Apply specified volume/bass/treble settings.
Note:
Values below minimum get automatically converted to allowed minimum value.
Values above maximum get automatically converted to allowed maximum value.
REQ: <STX>XGETVOL<ETX>{LRC}
RSP: <STX>XGETVOL<FS>Volume<FS>Bass<FS>Treble<ETX>{LRC}
Purpose: Return current volume/bass/treble settings.
REQ: XFTPGET<FS>FTPHOST={IPAddress}<FS>FTPPORT={Port}<FS>
FTPUSER={UserID}<FS>FTPPWD={Password}<FS>FILENAME={FileName}<FS>
RSP: XFTPGET<FS>RETVAL={N}<FS>RETVALSTRING={S}<FS>
101
-
Purpose: Get a file from the specified FTP server.
REQ: XFTPPUT<FS>FTPHOST={IPAddress}<FS>FTPPORT={Port}<FS>
FTPUSER={UserID}<FS>FTPPWD={Password}<FS>FILENAME={FileName}<FS>
RSP: XFTPPUT<FS>RETVAL={N}<FS>RETVALSTRING={S}<FS>
Purpose: Put a file to the specified FTP server.
XSETVAR
SetConfigVariable
XGETVAR
GetConfigVariable
XCLOCK
SetDeviceClock
Where:
{IPAddress} = IP address of FTP server in dotted decimal notation
{Port} = Port FTP Server is operating on
{UserID} = User ID to use on FTP server
{Password} = Password to use on FTP server
{FileName} = Name of file to upload, with proper path and extension
{N} = Return value: 0=Failure,
1=Success (Normal)
2=Success (Normal AND Device is rebooting)
{S} = Return value string:
e.g., when N=0: ―FAIL:<additional error description>‖
When N=1: ―SUCCESS‖
When N=2: "SUCCESS:DEVICE REBOOTING"
REQ: XSETVAR<FS>Parameter1=Value1<FS>Parameter2=Value2<FS>...<FS>
ParameterN=ValueN<ETX>{LRC}
RSP: XSETVAR<FS>RetVal1<FS>RetVal2<FS>...<FS>RetValN<FS><ETX>{LRC}
REQ: XGETVAR<FS>Parameter1<FS>Parameter2<FS>...<FS>
ParameterN<ETX>{LRC}
RSP: XGETVAR<FS>Parameter1=Value1<FS>Parameter2=Value2<FS>...<FS>
ParameterN=ValueN<ETX>{LRC}
REQ: XCLOCK<FS>{DateTime}
RSP: XCLOCK<FS>RetVal
Where {DateTime} = clock string to set in CCYYMMDDhhmmss format
XBATCH
BatchCommand
NOTE: The ‗seconds‘ portion of the clock string (ss) is optional.
REQ: <STX>XBATCH<FS>{REQ-Packet-1}<RS>{REQ-Packet-2}...<RS>
{REQ-Packet-N}<ETX>{LRC}
RSP: <STX>XBATCH<FS>{RSP-Packet-1}<RS>{RSP-Packet-2}...<RS>
{RSP-Packet-N}<ETX>{LRC}
NOTES:
An XBATCH request packet can be used to submit multiple sub-request packets to the terminal. All
sub-request packets will be separated by the <RS> character (where <RS> is the Record Separator
hex character 0x1E).

Sub-request and sub-response packets will NOT have any <STX> / <ETX> / LRC envelope. 
Only certain request packets can be sent in XBATCH requests. Those that result in multiple response 
packets (e.g., XPNG) cannot be sent. A quick check will be made on the packets contained in the
XBATCH request. If the XBATCH request packet contains such sub-request packets, the entire XBATCH
request will be rejected immediately.
ALL sub-request packets WILL contain a corresponding sub-response packet in the XBATCH response
packet. If the sub-request packet does not a high-level response packet, the corresponding subresponse field will be left empty.
E.g., a 72 packet does not have a high-level response:
REQ: <STX>XBATCH<FS>XSPV<FS>12<FS>VISIBLE<FS>BOOL<FS>1<RS>72<RS>
XSETVAR<FS>KP200=0<ETX>{LRC}
102

RSP: <STX>XBATCH<FS>XSPV<FS>1<RS><RS>XSETVAR<FS>1<ETX>{LRC}
NOTE the empty sub-response packet for the 72 sub-request packet.
Since the terminal application will have to process more requests in one shot, the POS PC will have to 
adjust it's wait timeout accordingly.
Note that for USB, the USB virtual COM port driver only supports packet sizes of around 500 bytes. 
XBATCH example for sigcap (no responses for S04, S03, S00): 
REQ: <STX>XBATCH<FS>XIFM<FS>SIGCAP<RS>XSFM<RS>S040041043162041<RS>
S030300100000060SIG.BMP<RS>S00<ETX>{LRC}
RSP: <STX>XBATCH<FS>XIFM<FS>1<RS>XSFM<FS>1<RS><RS><RS><ETX>{LRC}
103
Commands for PAYware Vision Support
These commands will be active when the PAYware Vision module is enabled in FormAgent.
Command
XSTX
Function/Description
StartTransaction
Request/Response Packets and notes
REQ: <STX>XSTX<FS>Key1=Value1<FS>Key2=Value2
..<FS>KeyN=ValueN<ETX>{LRC}
RSP: <STX>XSTX<FS>RetVal<FS>RetValString<ETX>{LRC}
Where Key value pairs can be any information the ECR/PCPOS and the VP
Server have agreed to share.
Purpose: Used to initialize data capture and send preliminary transaction
information to the PAYware Vision Server.
XETX
EndTransaction
REQ: <STX>XETX<FS>Key1=Value1<FS>Key2=Value2
RSP: <STX>XETX<FS>RetVal<FS>RetValString<ETX>{LRC}
Purpose: Used to terminate data capture with information like receiptTrailer
to the PAYware Vision Server.
XPAY
SendPaymentData
REQ: <STX>XPAY<FS>Key1=Value1<FS>Key2=Value2
RSP: <STX>XPAY<FS>RetVal<FS>RetValString<ETX>{LRC}
XLST
SendLineItem
Purpose: Used to transaction payment information to the PAYware Vision
Server.
REQ: <STX>XLST<FS>Key1=Value1<FS>Key2=Value2
RSP: <STX>XLST<FS>RetVal<FS>RetValString<ETX>{LRC}
XTMO
SendTerminalManagementOptions
Purpose: Used to send line item transaction data to the PAYware Vision
Server. This information can be used to reproduce the receipt.
REQ: <STX>XTMO<FS>Key1=Value1<FS>Key2=Value2
RSP: <STX>XTMO<FS>RetVal<FS>RetValString<ETX>{LRC}
Purpose: Used to set terminal management parameters that identify a
terminal with the PAYware Vision Server.
104
A sample flow of command packets is as follows:
Set Terminal Management options:
Ideally set once during initialization of the device.
XTMO<FS>COMPANYID=VFI<FS>STOREID=12345<FS>DEPTID=1111<FS>LANEID=001
Start of Transaction.
This packet indicates the beginning of a new transaction.
XSTX<FS>invoiceNumber=22222<FS>companyId=008
Send Line item information.
These packets contain information needed to regenerate the receipt at the PAYware Vision server.
XLST<FS>displayString= Panini Sandwich
$5.00
XLST<FS>displayString= Coke
$1.00
XLST<FS>displayString= Total (7% tax)
$6.42
XLST<FS>displayString=
Payment information.
This packet contains information related to the payment for the transaction.
XPAY<FS>mop=CREDIT<FS>accountNum=4012888888881881<FS>expYear=08<FS>expMonth=12<FS>cardholder=SADIQ
MOHAMMED<FS>paymentMedia=VISA<FS>transAmount=6.42
Signature information
Signature information is automatically sent to the PAYware Vision server, when PAYware Vision is enabled.
End of transaction.
This packet indicates the end of the transaction.
XETX<FS>ReceiptTrailer=THANK YOU
Property Types: (use for PropType fields above)
BOOL
SHORT
LONG
STRING
Property Names: (use for PropName fields above)
105
BOOL Properties:
VISIBLE
BORDER_VISIBLE
BEEP_ON_PRESS
STAY_PRESSED
SELECTED
NO_SCROLL
RUN
– shows/hides a control
– enables/disables the border of a control
– enables/disables the BeepOnPress flag of a Button control
– enables/disables the StayPressed flag of a Button control
– set/get Checkbox Selected property value
- enables/disables the scrollbars for ListBox and TextBox controls
- starts/stops an Animation control
TRANSPARENT
- enables/disables the Transparent flag of a Label control
SHORT Properties:
OPTIONS
TEXT_JUSTIFICATION
FONT_ATTRIBUTES
STYLE
ITEMS_TO_SCROLL
MIN_ENTRIES
- set/get
- set/get
- set/get
- set/get
- set/get
- set/get
KEYPAD_TYPE
KEYPAD_IMAGE_POS_LEFT
KEYPAD_IMAGE_POS_TOP
BUTTON_STATE
BUTTON_RESET_STATE
DELAY_INTERVAL
LOOP_COUNT
PRES_EFFECT
control options
text justification values
font attributes
control style
number of items to scroll when up/down buttons are pressed in Listbox or Textbox control
minimum number of characters to accept in Keypad control
- set/get Keypad control type (Numeric, Alphanumeric, Custom)
- set/get left coordinate of custom Keypad control‘s PNG/JPG
- set/get top coordinate of custom Keypad control‘s PNG/JPG
- get state of Button control (1=pressed/0=unpressed)
- reset state of Button control to 0=unpressed (for resetting state of StayPressed buttons
that have been pressed, to their 0=Up/Normal state)
- set/get delay interval in milliseconds for Animation control
- set/get loop count in milliseconds for Animation control
- set/get presentation effect for Animation control\
0=PE_NORMAL, 1=PE_FADE,
2=PE_SLIDE_LEFT_RIGHT, 3=PE_SLIDE_RIGHT_LEFT,
4=PE_SLIDE_TOP_DOWN, 5=PE_SLIDE_BOTTOM_UP, 7=PE_EXPLODE
LONG Properties:
BG_COLOR
FG_COLOR
- set/get background color property of certain controls (Label, Button, ListBox, Marquee, …)
- set/get foreground color property of certain controls (Label, Button, CheckBox, ListBox, Marquee, …)
STRING Properties:
CAPTION
UP_IMAGE_FILE_NAME
DOWN_IMAGE_FILE_NAME
IMAGE_FILE_NAME
UNCHECKED_FILE_NAME
CHECKED_FILE_NAME
DISPLAY_STRING
- set/get Caption property of Label/Button control
- set/get name of PNG/JPG file of Button control‘s unpressed image
- set/get name of PNG/JPG file of Button control‘s pressed image
- set/get name of PNG/JPG file of Image control
- set/get name of PNG/JPG file of Button control‘s unchecked image
- set/get name of PNG/JPG file of Button control‘s checked image
- set/get display mask of Keypad control
FORMAT_STRING
CUSTOM_IMAGE_FILE_NAME
ANIM_FILE_NAME
- set/get format mask of Keypad control
- set/get name of PNG/JPG file of custom Keypad control
- set/get name of EET file for Animation control
106
.profile Parameters in FormAgent application
THEME_PATH=/home/usr1/themes
Required for location of theme files. Do not change.
LD_LIBRARY_PATH= /lib:/home/usr1/lib:$LD_LIBRARY_PATH Required to specify library search path. Do not change.
FP_EMULATE=320x234
FP_ORIENTATION=landscape
Do not change.
Do not change.
FP_POINTER=0
Mouse pointer flag; if set to 1, this will define a 2 x 2 pixel pointer defined by the color
specified by the FP_POINTER_COLOUR parameter (see below).
FP_POINTER_COLOUR=0,0,0,0
FP_MEDIA_AUDIO_OSS_SOFT_DELAY=1
EVAS_DEBUG_SHOW=1
DBGIP=10.64.82.40
Do not change.
This will define a mouse color in {Red, Green, Blue, Alpha} format.
e.g., FP_POINTER_COLOUR=255,0,0,255 will define a solid Red color mouse pointer
Do not change.
Do not change unless asked to by technical support.
DBGPRT=5678
DEBUG=0
DEBUG_GUIMGR=0
BUTTON_ACTION_ON_RELEASE=0
This value determines whether an event fires on the button push on the Down or the
Up/release. A setting of ―0‖ causes the event to fire on the Down, and this is the preferred
setting.
Note:
If the BUTTON_ACTION_ON_RELEASE setting is not found, the default setting is 1.
When set to fire on the up/release, the finger/stylus must be released within the
bounding rectangular area of the button for the event to fire.
This value determines if a ShowForm is required for any screen updates such as an InitForm,
SetPropertyValue, etc. A value of ―1‖ requires a ShowForm, and a value of ―0‖ causes any
command to have immediate UI update, thus no ShowForm is ever required.
Note:
The setting of ―1‖ is very useful when the POS program needs to refresh multiple areas
of the form in one go (e.g., updating a ListBox lineitem and corresponding Subtotal, Tax
and Total Label controls), with no flicker.
This is the background ―curtain‖ image that is behind all forms.
Note:
The image filename used can be a png or jpg file.
If the filename is not found or in invalid, or the parameter is not set, a default black
rectangle background is automatically used instead.
SIGRESET=1 => Default behavior; allow SIGCAP_RESET_SESSION status to be sent to
application when CANCEL is pressed after signature begins + automatically clear signing
region + start a new signature capture session.
If SIGRESET env var is missing in .profile, this would be the default behavior.
The guimgr library also ensures that the CANCEL button does not have
StayPressed=TRUE, to allow user to press it twice during signature capture; if the button
did have StayPressed=TRUE, it is restored on exit, so the second CANCEL button hit will
cause the button to remain pressed on exit.
SIGRESET=0 => don't send SIGCAP_RESET_SESSION status to application; always send
SIGCAP_ABORT_KEY when CANCEL is pressed (whether signature has begun or not). With
this setting, pressing the CANCEL button ONCE aborts sigcap.
BUFFERED_UI_UPDATES=1
SCREEN_BACKGROUND=guimgrbg.png
SIGRESET=1
NOTE:
If running in SIGRESET=1 mode, the DONE button on the sigcap form is hidden as soon as
sigcap is initiated and shown when the first pen-down is detected. It is again hidden
when the CANCEL button is pressed after signing, when the signature box is cleared. It is
recommended that the DONE button have its hidden flag set via FormManager in design
mode.
107
Configuration Parameters in FormAgent application
*GO=frmAgent.exe
The application (process) to startup on powerup.
*ZR=8
Used to indicate download baud rate of 115200 for D99-initiated downloads.
*DHCP=0
Used to indicate whether DHCP is ON (1) or OFF (0)
*IFCONFIG=eth0 192.168.0.199 netmask 255.255.255.0 IP address and netmask of terminal (used when DHCP=0)
*TELNET=1
If set to 1, this will start the Telnet server daemon
*NETIP=192.168.0.1
IP address of terminal (used when DHCP=0)
*NETGTW=192.168.0.1
Network gateway of terminal (used when DHCP=0)
*NETDNS1=192.168.0.1
Network primary DNS IP address (used when DHCP=0)
*NETDNS2=192.168.0.1
Network secondary DNS IP address (used when DHCP=0)
*NETMASK=255,255,255,0
Network mask (used when DHCP=0)
DEBUG=0
Used to turn ON debug mode for debug version of application
DBGIP=192.168.0.103
IP address of PC running SocketListener program for debug version of application
DBGPRT=5678
Listening port number of PC running SocketListener program for debug version of application
HOSTIP=192.168.0.103
IP address of PC register when running in TCP/IP mode
HOSTPRT=9000
Port number of PC register when running in TCP/IP mode
SERVER=1
Indicates whether terminal is Server (1) or Client (0) when running in TCP/IP mode
TERMPRT=9001
Port number of terminal when it is a Server, when running in TCP/IP mode
COMMTYPE=RS232
Indicates communication type of terminal application (other possible values: USB, TCPIP)
If COMMTYPE=TCPIP, the parameters *NET???? (See above), DHCP, SERVER, TERMPRT, HOSTIP,
HOSTPRT are also required
COM port (on terminal block) used by terminal application (Note: this is NOT the PC‘s COM port)
Baud rate used by terminal application (common values: 8=115200, 7=38400, 6=19200, 5=9600,
4=4800)
Default: 8 (for 115200 baud)
Protocol format;
Some common values: 4 = {8 data bits, no parity, 1 stop bit}, 0 = {7 data bits, even parity, 1 stop
bit}
External port selection - ABCD format,
Where:
A=port number (1-3)
B=baud rate; common values for B: 8=115200, 7=38400, 6=19200, 5=9600, 4=4800, 3=2400, 2=1200
C=format;
Common values for C:
4 = {8 Data bits, No parity, 1 Stop bit}
0 = {7 Data bits, Even parity, 1 Stop bit}
D=command scheme
Values for D:
0=<STX><ETX>LRC used
1=<CR> terminates command
CP=1
BD=8
PROT=4
PS1=2641
STP1=13
PS2=3641
NOTE:
The config variable PS1 is used to specify settings when connecting a PP1000SE external PINPAD
device to the Mx870.
External comm port 1 stop char in decimal (13 = carriage return)
External port selection - ABCD format,
Where A=port number (1-3), B=baud rate, C=format, D=command scheme
Common values for B: 8=115200, 6=19200, 5=9600
Common values for C: 4 = {8 data bits, no parity, 1 stop bit}, 0 = {7 data bits, even parity, 1 stop
bit}
Values for D: 0=<STX><ETX>LRC used, 1=<CR> terminates command
108
STP2=13
External comm port 2 stop char in decimal (13 = Carriage return
SIGBLK=480
SIGRES=0
SigCap block size – Note that with USB the maximum size of a packet is 512 bytes and it is
recommended that the max value used is 480.
SigCap filter resolution (0=no filtering)
SIGEND=0
SigCap endianness (0=big endian, 1=little endian)
MK=1
Used to indicate the type of PIN pad Key Management being used; MK=0 is for Master/Session, 1 is
for DUKPT. (A common misconception is that this indicates the type of key encryption used;
encryption for us is always DES (1-DES or 3-DES, as indicated by the 3DES parameter)
TRKDLM=1
FS=200
Track delimiter flag (1=send entire track buffer, 0=do not send first character of track buffer)
Minimum flash size needed by the application in units of 1000 bytes (KB); needed for downloads
into flash; if the available flash is less than this value, the app will automatically do a flash
coalesce to create flash space
ScreenSaver timeout in seconds (to indicate when the touch panel should be shutoff; a setting of 0
disables the screensaver).
SSTO=0
RETRYTO=3
Retry timeout in seconds (to indicate after what interval a packet should be retried if it fails to get
an ACK/NAK).
TPRCTM=0200
Touch Panel Recalibration Time (default = ―0200‖, for 2 AM in the morning). Used to automatically
recalibrate the touch panel at the specified time; typically a time when the store is guaranteed to
be idle and there is no chance of any body parts/fingers being near the touch panel when the
recalibration is being performed.
Indicates whether the LEDs should automatically flash when any of the Q commands are issued.
Note: the LEDs are automatically shut off once the Q command is satisfied/responded to after a
card is swiped or a RFID contactless card is tapped.
Determines whether to use the KP200 keyboard for PIN entry.
0 = don‘t use KP200 keypad; use normal NUMERIC keypad.
1 = use KP200 keypad
0 = 1-DES encryption for PINs. Default value.
1 = 3-DES encryption for PINs.
Indicates DUKPT engine to use. Possible values are 0, 1 and 2.
Default value is 0.
Flag indicating whether to display error message box on bad card reads.
The message that is displayed is "Card Read Error! Please Slide Card Again.", with a STOP icon.
Default is 0 (off).
Indicates the name of form file (without extension) to display after powerup and after display of
FormAgent application version information. Very useful to display the customer's starting screen
with logo, marquees, etc. This facility is provided in lieu of the legacy LOGOBMP and LOGODT
parameters.
Optional.
PIN entry timeout value in seconds.
Default value: 60
AUTOLED=1
KP200=0
3DES=0
DUKPTENGINE=0
BADMAGREADMSGBOX=0
STARTUPFORM=
PINTO=60
109
PAYware Vision-specific parameters
*VPS=0
*VPDOWNPORT=5016
*VPSERVERPORT=5015
*VPSERVERADDRESS=10.64.82.96
NumChkPts=N
Flag to enable PAYware Vision functionality in the application.
Default value: 0 (off)
Port number that application will listen on for Device Solutions and Content Solutions messages
from the PAYware Vision server.
Port that PAYware Vision server is monitoring for device-initiated Signature and Receipt packets
(Signature Solutions messages).
IP address of PAYware Vision server.
Number of checkpoints for content management via PAYware Vision, where:
N = a number from 1 - 10
Corresponding to the NumChkPts value, there must also exist parameters Chkpt1, Chkpt2, … till
ChkptN, where each ChkptX parameter is set to the name of the form that will receive content
from the PAYware Vision server, as specified at the VP server for the defined checkpoint.
ChkptN=<formname>
The number of checkpoints set must match the number of forms used by the POS application for
content management via PAYware Vision.
<formname> = Name of form that will receive content from the PAYware Vision server as specified
at the VP server for the defined checkpoint.
NOTE: This maps to a ‗Placement code‘ setting in PAYware Vision.
E.g. the following defines 4 checkpoints/formnames/placement codes...
Chkpt1=Welcome
Chkpt2=Scroll
Chkpt3=Process
Chkpt4=Goodbye
...Where Welcome, Scroll, Process, Goodbye correspond to the ‗soft‘ checkpoints/ placement
codes configured in PAYware Vision server.
110
MultiPay-specific parameters
MULTIPAY=0
Flag to turn on/off MultiPay emulation mode.
Default value: 0 (off)
For the following MultiPay flags used in the application, please refer to the standard MultiPay specification.
BM=1
CASHBK=02000
CLR=1
FIRST=1
HBENBL=0
HS=0
IS=X
MKIDX=0
OFL=1
PNUL=1
SFK=X2XX1453
TS=XXXXXXXX
VER=1.02A_1.01B
Z3TIM=1
CLANG=0
CBF=10203040
PP2000=0
Q40EMUL=0
3BA=1
111
.PrintReceipt string XML format for the Duet.
Tag
<SPPRINT>
Data Element
N/A
<PCOL>
<PRESPOOL>
<SPSTYLE>
<FORMAT>
<SPCENTER>
<SPLR>
Maximum Width
Number
N/A
0 – Reset to Default
1 – Double Wide
2 – Double High
4 - Inverse
Text to be printed
N/A
<L>
<R>
<FEED>
<POSTSPOOL>
<SPLREXT>
Text to be printed
Text to be printed
N/A
Number
N/A
<SPRIGHT>
Text to be printed
<SPLINE>
<TEAR> *
Text to be printed
N/A
Description
Root tag of the print package. All other commands are encapsulated
in this tag.
Maximum width of the print lines. The default is 32.
Will print as many blank lines as indicated by ―number‖.
Parent of <FORMAT>, not required.
Controls the formatting of any print commands following. Can be
used multiple times in a print package. Values can be combined to
produce multiple style changes.
Will center the given text on a line.
Begins a data block describing two pieces of data, formatted to
justify on the left and right sides of a print line, respectively. Uses
the <L> and <R> child tags.
Left portion of a print line.
Right portion of a print line.
Linefeed.
Will print as many blank lines as indicated by ―number‖.
Begins a data block describing two pieces of data. The <L> child tag
controls what text to print on the left justified, and the <R> child tag
provided a pad character to fill the remainder of the line.
Uses the <L> and <R> child tags similar to <SPLR>, but Text will be
right justified.
Text will be left justified.
Form feeds a receipt and triggers a wait for keypress from the user.
* When sending the <TEAR> tag, the device will wait for a user to press a button on the device to continue. A button must
be pressed in order for the SIM.DLL to resume communications with the device. To avoid having to press a button to
continue, you can press several line feeds <FEED> instead of <TEAR> to achieve the same result.
112
Appendix H - Editing/Creating the SIM Form Deck
With the Mx800 Form Manager (developer edition), you can load the SIM‘s form deck that it uses during payment
processing and edit them to your own specifications and design. Or you could create an entirely new form application
using the Mx800 Form Manager and add the SIM forms from scratch. If editing the current SIM form deck, in the Mx800
Form Manager, go to File > Open Application and select the SIMForms.APP file in the SIM Form Deck folder.
The following table details the minimum form requirements that the SIM needs in order to work properly. More items can
be added than are listed, but the SIM needs at a minimum what is detailed in the required controls column. The form
name is case sensitive. The number in parenthesis is the control ID number of the item on that form.
MX devices vary in available keys, such as number and function keys, and dimensions. For that reason the SIM will call on
different forms that serve the same purpose as other forms, but that have been customized to either the dimensions of
that device or the availability of buttons on the device. Pay close attention to this as you are editing or creating these
forms.
Please follow these instructions careful as an error in the form could cause the SIM not to work properly.
Form
Name
SWIPE
Used in
Devices
MX830
MX850
MX870
Description
Required Controls Type(Control ID #)
Displayed when prompting the customer to
swipe their card.
No required controls
Label (1) – Where the question is asked
Button (2) – Yes button
Button (3) – No button
Button (2) – Yes button
Button (3) – No button
FunctionKeyButton (2) – Yes button. Associated with the F3 function key.
Should match up with the 3rd blue function key from the top.
FunctionKeyButton (3) – No button. Associated with the F4 function key
Should match up with the 4th blue function key from the top
RETR_YN
MX870
Displays a form with a prompt asking a Yes or
No question to the customer
RYN860
MX860
RYN830
MX830
MX850
RETR_N
MX830
MX850
MX870
Displays a form prompting to enter a desired
cashback amount
RETN860
MX860
Displays a form prompting to enter a desired
cashback amount
DISPLAY
MX830
MX850
MX870
For displaying messages on the device via the
ChangeDisplay method of the SIM.
Label (1)
DISP860
MX860
For displaying messages on the device via the
ChangeDisplay method of the SIM.
Label (1)
PROC
MX830
MX850
MX870
Displays a form informing that their payment
is in progress, or processing
PROC860
MX860
Displays a form informing that their payment
is in progress, or processing
Keypad (1)
Label (2)
Keypad (1)
Label (2)
113
Form
Name
Used in
Devices
Description
Required Controls Type (Control ID #)
For manual credit card entry
Box (2) – This is the signature area. All other controls should be outside of this box. This
box should be hidden. Should have the following dimensions:

Left: 0

Top: 96

Width: 320

Height: 76
Button (4) – Ok button. This box should be hidden
Button (5) – Clear button
Box (2) – This is the signature area. All other controls should be outside of this box. This
box should be hidden. Should have the following dimensions:

Left: 0

Top: 120

Width: 480

Height: 80
Button (4) – Ok button. This box should be hidden
Button (5) – Clear button
Keypad (2)
For manual credit card entry
Editfield (2)
For manual
For manual
entry
For manual
entry
For manual
entry
Keypad (2)
SIGCAP
MX830
MX850
MX870
Form that allows customer to
enter their signature
SIG860
MX860
Form that allows customer to
enter their signature
CARD_ENT
CARD860
MX870
MX830
MX850
MX860
EXP_ENT
MX870
EXP_830
MX830
MX850
CARD_830
EXP860
PMT_TYPE
PTYPE860
PTYPE830
MX860
MX870
MX860
MX830
MX850
credit card entry
expiration date
expiration date
expiration date
For selecting the payment type
of the transaction
of the transaction
of the transaction
Keypad (2)
Editfield (2)
Keypad (2)
Button (2) – Credit button
Button (3) – Debit button
Button (4) – EBT button
Button (5) – Gift button
Label (6) – Credit label
Label (7) – Debit label
Label (8) – EBT label
Label (9) – Gift label
Button (2) – Credit button
Button (3) – Debit button
Button (4) – EBT button
Button (5) – Gift button
FunctionKeyButton (2) – Credit button. Associated with the F1 function key.
FunctionKeyButton (3) – Debit button. Associated with the F2 function key.
FunctionKeyButton (4) – EBT button. Associated with the F3 function key.
FunctionKeyButton (5) – Gift button. Associated with the F4 function key.
Buttons should match up in order of control ID with the blue function buttons.
114

SIM Integration Guide - Verifone Support Portal

Transcription

Similar documents

Flemish String Board Attachment

READY TO FLY!!!

in pdf format here - UNGEGN Norden Division

gruffalo`s child

RE/MAX vs. THE INDUSTRY

A Question of Scale

Making String Heddles for the Gilmore Inkle Loom

sponsorship package

Knotted Friendship Bracelet

Scout Skills – Camp Gadgets