Electronic Payment Processing Software Users Manual

Copyright Aug-07, VeriFone, Inc. Version 5.7.1 Release I SP8

Notice
Copyright August 07 VeriFone, Inc. All rights reserved. active-Charge, active-Charge SDK, PCCharge Payment Server, PCCharge Pro, PCCharge DevKit, Virtual-Charge, IP-Charge are trademarks and PCCharge is a registered trademark of VeriFone, Inc. Microsoft is a registered trademark and Windows is a trademark of Microsoft Corporation. Other brands and their products are trademarks or registered trademarks of their respective holders and should be noted as such. VeriFone, Inc. 8001 Chatham Center Drive, Suite 500 Savannah, Georgia 31405 Development Support: (877) 659-8983 Technical Support: (877) 659-8981 Fax: (912) 527-4596

Table of Contents
Table of Contents .......................................................................................................... 3 Software License........................................................................................................... 7 Important Security Notice............................................................................................. 8
Payment Processing Industry Specifications and Regulations .............................................................. 8 General Recommendations.................................................................................................................... 8 Card Security Programs ......................................................................................................................... 8 Merchant Responsibility ......................................................................................................................... 9

CHAPTER 1 -- PCCharge DevKit Introduction .......................................................... 10

Introduction ................................................................................................................................................. 11 PCCharge DevKit ................................................................................................................................. 11 PCCharge DevKit Suite ........................................................................................................................ 11 Product Components .................................................................................................................................. 12 PCCharge DevKit ................................................................................................................................. 12 PCCharge DevKit Development Support ............................................................................................. 12 PCCharge Pro and PCCharge Payment Server .................................................................................. 12

CHAPTER 2 -- Getting Started.................................................................................... 15

Getting Started ............................................................................................................................................ 16 1) Install the DevKit and the PCCharge Products ................................................................................ 16 2) Install the Test Merchant Accounts .................................................................................................. 16 3) Verify that PCCharge is Set Up Properly ......................................................................................... 17 4) Determine Which Integration Method Will Be Used ......................................................................... 18 5) Determine Which PCCharge Product(s) Will Be Supported ............................................................ 24 6) Review Payment Processing Basics and Integration Information and Settings .............................. 28

CHAPTER 3 -- Payment Processing Basics.............................................................. 29

Credit Card Processing ............................................................................................................................... 30 Host based and Terminal based Processors ....................................................................................... 30 Credit Card Transactions...................................................................................................................... 31 A Normal Credit Card Processing Day................................................................................................. 32 Credit Card Transaction Rates ............................................................................................................. 33 Debit Card Processing ................................................................................................................................ 34 Debit Card Transactions....................................................................................................................... 35 A Normal Debit Card Processing Day .................................................................................................. 35 Check Processing ....................................................................................................................................... 36 Check Conversion ................................................................................................................................ 36 Check Transactions.............................................................................................................................. 37 A Normal Check Conversion Processing Day...................................................................................... 37 EBT Processing .......................................................................................................................................... 38 A Normal Day of Processing EBT Transactions................................................................................... 39 Gift Card Processing ................................................................................................................................... 41 A Normal Day of Gift Card Processing................................................................................................. 41

CHAPTER 4 -- Integration Information and Settings ................................................ 42

Warnings, Tips, and Guidelines .................................................................................................................. 43 Timeouts...................................................................................................................................................... 47 Understanding Timeouts ...................................................................................................................... 47 Transaction Delays ............................................................................................................................... 47 Dial-Up Modem Backup Settings.......................................................................................................... 48 Setting the Integrated Applications Timeout Value.............................................................................. 48

Handling Timeouts................................................................................................................................ 49 Multi-User Support ...................................................................................................................................... 50 Support for Multiple Workstations......................................................................................................... 50 Support for Simultaneous Transaction Requests................................................................................. 50 Setting up Multi-user support................................................................................................................ 52 Additional Users.................................................................................................................................... 52 Unlimited User License......................................................................................................................... 53 Limitations of PCCharges Multi-User Feature ..................................................................................... 53 Alternatives ........................................................................................................................................... 54 Multi-trans Wait ........................................................................................................................................... 55 Multi-Merchant Support............................................................................................................................... 56 Multi-Merchant Integration.................................................................................................................... 56 Use Default Processor.......................................................................................................................... 57 Follow On Transactions .............................................................................................................................. 58 Overview............................................................................................................................................... 58 Examples .............................................................................................................................................. 59 Implementing Follow On Transactions ................................................................................................. 62 Non-TroutD Post-Authorizations........................................................................................................... 63 Commercial Card Transactions .................................................................................................................. 65 Overview............................................................................................................................................... 65 Supporting Commercial Card Transactions ......................................................................................... 65 Using Bin.mdb ...................................................................................................................................... 65 Submitting Commercial Card Transactions.......................................................................................... 67 Example................................................................................................................................................ 68 Restaurant Transactions ............................................................................................................................. 69 Overview............................................................................................................................................... 69 Benefits of XML .................................................................................................................................... 69 Integration............................................................................................................................................. 69 Examples .............................................................................................................................................. 70 Processor Specific Notes ..................................................................................................................... 73 Gift Card Transactions ................................................................................................................................ 74 VeriFone Stored Value API (GAPI)............................................................................................................. 76 Pre-Paid Credit Card Transactions ............................................................................................................. 77 Canadian (Interac) Debit Transactions................................................................................................. 78 Overview............................................................................................................................................... 78 Definitions ............................................................................................................................................. 78 Integration Notes .................................................................................................................................. 79 Integration............................................................................................................................................. 80 Process Flow when using the processor Global Payments East (NDC).............................................. 81 Process Flow when using the processor Chase Paymentech (GSAR)................................................ 84 Transaction Inquiry ............................................................................................................................... 85 Overview............................................................................................................................................... 85 Usage ................................................................................................................................................... 85 Example................................................................................................................................................ 87 Batch Settlement .................................................................................................................................. 88 Health Message Transaction ...................................................................................................................... 90 Batch Totals Storage................................................................................................................................... 91 BatchTotals Table................................................................................................................................. 91 Command Line Switches ............................................................................................................................ 92

CHAPTER 5 -- DevKit Constants................................................................................ 93

DevKit Constants ........................................................................................................................................ 94 Action Codes ........................................................................................................................................ 94 Address Verification Response Codes................................................................................................. 98 CVV2/CVC2/CID Response Codes...................................................................................................... 98 Credit Card Types................................................................................................................................. 98

System Error Codes and Descriptions ................................................................................................. 99 SYS.PCC Codes and Descriptions..................................................................................................... 100 Processing Company Codes .............................................................................................................. 101 Transaction Result Constants ............................................................................................................ 103

CHAPTER 6 -- PCCharge Integration Methods ....................................................... 104

Pseudo-code ............................................................................................................................................. 105 Credit Card Sale/Pre-Authorization Retail / Card Present .............................................................. 106 Credit Card Sale/Pre-Authorization Card Not Present .................................................................... 110 Level II (Commercial, Purchasing, etc.) Card Sale ............................................................................ 114 Credit Card Void ................................................................................................................................. 118 Credit Card Sale/Pre-Authorization Restaurant .............................................................................. 121 Credit Card Gratuity Restaurant ...................................................................................................... 125 Debit Sale ........................................................................................................................................... 128 Reports ............................................................................................................................................... 132 OCX (ActiveX) Method.............................................................................................................................. 135 Charge.OCX ....................................................................................................................................... 138 Debit.OCX........................................................................................................................................... 151 Check.OCX......................................................................................................................................... 159 EBT..................................................................................................................................................... 166 GiftCard.OCX...................................................................................................................................... 167 VeriFone Stored Value API (GAPI)........................................................................................................... 167 Batch.OCX.......................................................................................................................................... 176 Device.OCX ........................................................................................................................................ 182 SC550.OCX ........................................................................................................................................ 185 SC5X.OCX.......................................................................................................................................... 193 SC5X.OCX Error Codes ..................................................................................................................... 197 Reporting ............................................................................................................................................ 198 DLL (ActiveX) Method ............................................................................................................................... 202 Charge Class ...................................................................................................................................... 203 Debit Class ......................................................................................................................................... 216 Check Class........................................................................................................................................ 223 EBT..................................................................................................................................................... 230 Gift Class ............................................................................................................................................ 231 VeriFone Stored Value API (GAPI)........................................................................................................... 231 Batch Class......................................................................................................................................... 239 Offline Class ....................................................................................................................................... 244 Reporting ............................................................................................................................................ 246 OLE/COM Method..................................................................................................................................... 250 PccCharge Class ................................................................................................................................ 252 PCCDebit Class.................................................................................................................................. 263 PccCheck Class.................................................................................................................................. 270 PCCEBT Class ................................................................................................................................... 276 PCCGiftCard Class............................................................................................................................. 282 VeriFone Stored Value API (GAPI)........................................................................................................... 282 PccBatch Class................................................................................................................................... 290 PccSettle Class................................................................................................................................... 292 PccSettleGift Class............................................................................................................................. 295 PccPinPad Class ................................................................................................................................ 297 PccSC550 Class................................................................................................................................. 300 PccBin Class....................................................................................................................................... 302 Reporting ............................................................................................................................................ 303 Utility Related Classes........................................................................................................................ 307 Setup Related Classes ....................................................................................................................... 311 Classes No Longer Supported / Internal Use Classes ....................................................................... 408 Introduction ......................................................................................................................................... 409

File Method Integration....................................................................................................................... 409 File Layout Specifications................................................................................................................... 411 Credit File Layouts.............................................................................................................................. 413 Debit File Layouts ............................................................................................................................... 420 Check File Layouts ............................................................................................................................. 424 EBT File Layouts ................................................................................................................................ 427 Gift File Layouts.................................................................................................................................. 430 VeriFone Stored Value API (GAPI)........................................................................................................... 434 Batch File Layouts .............................................................................................................................. 434 Report File Layouts ............................................................................................................................ 436 Configuration File Layouts.................................................................................................................. 438 Various Utility File Layouts ................................................................................................................. 439 TCP Interface ............................................................................................................................................ 441

CHAPTER 7 -- Code Sample Information ................................................................ 442

Code Samples........................................................................................................................................... 443 Java Client .......................................................................................................................................... 443 Web-based Integration Samples............................................................................................................... 445 System Requirements ........................................................................................................................ 445 PCCharge Virtual Terminal Sample ................................................................................................... 446 ASP Sample ....................................................................................................................................... 451 Cold Fusion......................................................................................................................................... 452 Java .................................................................................................................................................... 453 General Troubleshooting........................................................................................................................... 455 Permissions ........................................................................................................................................ 455

Appendix.................................................................................................................... 456
Test Credit Cards and Merchant Accounts ............................................................................................... 457 Test Credit Card Numbers.................................................................................................................. 457 Test Track Data .................................................................................................................................. 458 Test Merchant Account Information.................................................................................................... 459 Integration Troubleshooting ...................................................................................................................... 464 IODebug.log........................................................................................................................................ 464 Transaction Request Duplication........................................................................................................ 465 Communication Log............................................................................................................................ 465 Error Log............................................................................................................................................. 466 Troubleshooting a Live Installation ..................................................................................................... 466 Contacting Support............................................................................................................................. 467 Distribution and Deployment ..................................................................................................................... 468 Distribution Methods........................................................................................................................... 468 Demo Mode ........................................................................................................................................ 469 Evaluation Mode ................................................................................................................................. 469 Warehousing/Block Inventory............................................................................................................. 469 Activation ............................................................................................................................................ 470 Support Policy ........................................................................................................................................... 471 Philosophy .......................................................................................................................................... 471 Contact ............................................................................................................................................... 471 More Information................................................................................................................................. 471

Software License
1. GRANT OF LICENSE. VeriFone, Inc. grants you the right to use a single copy of this Software, including documentation, on one computer of your choice. You may physically transfer each License, without cost, to a different computer, providing it is removed from the first computer. Please remember that when you buy Software, you are actually buying the rights to use the Software on one computer at a time. It is against Federal laws to use this Software on more than one computer at a time. 2. RESTRICTED USE. The Program may not be copied except for backup purposes. Copying of the Manual and Interface Specifications is prohibited. You may not remove any product identification, copyright, or other proprietary notices from the Software or Documentation. 3. WARRANTY. VeriFone, Inc. warrants that the original compact disc is free from defects in material and workmanship for a period of 30 days from the date of purchase. If a defect occurs during this time, VeriFone, Inc. will replace your compact disc free of charge. 4. DISCLAIMER. The PCCharge DevKit package is Licensed on an "as is" basis. There are no warranties, expressed or implied, including, but not limited to, warranties of merchantability, of fitness for a particular purpose, and all such warranties are expressly and specifically disclaimed. VeriFone, Inc. shall have no liability or responsibility to you or any other person or entity with respect to any liability, loss, or damage caused or alleged to be caused directly or indirectly by the PCCharge DevKit. Use of the PCCharge DevKit system signifies agreement with this disclaimer and is subject to the License Agreement provided with the installation compact disc.

Important Security Notice

Payment Processing Industry Specifications and Regulations
Just like any other industry, the payment processing industry has its own particular requirements, standards, and restrictions. It is extremely important that merchants contact their payment processing company and find out what information they need to know and what procedures they must follow before processing a single credit card. This is important because merchants will regularly deal with potentially large sums of money. Over the last fifty years, the payment processing industry has developed certain rules and guidelines in an attempt to protect merchants and customers from fraud, human error, and unpredictable difficulties. Unfortunately, VeriFone, Inc. cannot provide merchants with specific information on the policies and conditions of other companies. Merchants will need to contact their payment processing company to obtain security rules and recommendations specific to that company. VeriFone, Inc. can, however, supply merchants with the following general recommendations:

General Recommendations
The credit card number and the expiration date can be stored by the merchant in an encrypted state, but other data cannot. The data that should not be stored includes (but is not limited to): Magnetic strip track I/II data CVV2/CVC2/CID number

Again, this is a general list. VeriFone, Inc. highly recommends that merchants contact their payment processing company and find out exactly what they mandate and/or recommend. Doing so may help merchants protect themselves from fines and fraud.

Card Security Programs

In April 2000, Visa introduced its Cardholder Information Security Program (CISP). This program is an attempt to establish certain standards for the storage, transfer, and maintenance of sensitive credit card information. As an example of some of the things merchants and developers can do to help protect themselves and their customers, here are the CISP requirements: 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. Install and maintain a working firewall to protect data Keep security patches up-to-date Protect stored data Encrypt data sent across public networks Use and regularly update anti-virus software Restrict access by "need to know" Assign unique ID to each person with computer access Don't use vendor-supplied defaults for passwords and security parameters Track all access to data by unique ID Regularly test security systems and processes

11. Implement and maintain an information security policy 12. Restrict physical access to data Please contact Visa if to learn more about this program. Alternatively, visit http://usa.visa.com/business/merchants/cisp_index.html for online information.

Merchant Responsibility
Although VeriFone, Inc. has gone to great lengths to secure PCCharge, it is the merchants responsibility to secure the system on which PCCharge resides and the environment in which it is used. Further, it is the developer's responsibility to secure any transmission of data between PCCharge and integrated applications. Hackers continually find new ways to commit fraud, and therefore it is crucial that an ongoing and layered approach to security is taken. Use multiple tools and protect all areas (the network, individual PCs, laptops, servers, databases, backup data, etc.) that contain or transmit sensitive data. At a minimum, VeriFone recommends that the following suggestions are implemented: 1. If the computer running PCCharge has any kind of Internet connection, install a firewall prior to processing financial transactions. Even if a firewall is already in place, check for new versions to ensure that the firewall is the most up to date that is available. Industry standards should be followed for strengthening the firewall prior to processing financial transactions. 2. Printed material documenting sensitive merchant information (Merchant ID, Terminal ID, etc.) should be safeguarded. 3. Keep software up to date, including (but not limited to): operating systems, e-mail programs, and Internet browsers. Microsoft security updates and patches can be downloaded by visiting http://www.microsoft.com/. 4. Control access to computer equipment during open and closed hours. 5. If a remote user accesses the computer through a program such as pcAnywhere, take measures to lock the program down (see pcAnywhere manual). User names and passwords must be set -orchange the settings to allow for Windows-based security. The default users Guest and Anonymous should also be disabled. 6. For more information related to security, visit: http://usa.visa.com/business/merchants/cisp_index.html http://www.sans.org/resources http://www.microsoft.com/security/default.asp https://sdp.mastercardintl.com/

CHAPTER 1 -- PCCharge DevKit Introduction

10

Introduction
Thank you for purchasing the PCCharge DevKit or the PCCharge DevKit Suite. VeriFone, Inc. is committed to providing integrators and merchants with the most comprehensive electronic payment processing solutions available today. If you have any suggestions as to how we can improve our products, support, or documents, please call us at (877) 659-8983 or e-mail us at [email protected]. This chapter is an introduction to the PCCharge DevKit. It will familiarize you with the various components and typical uses of this bundle of products.

PCCharge DevKit
The PCCharge DevKit is a bundle of applications, tools, code examples, and documents used to enable electronic payment processing in third party applications. The PCCharge DevKit is designed to guide developers while they are building an interface in their application to PCCharge Payment Server and/or PCCharge Pro. The PCCharge DevKit includes evaluation copies of PCCharge Pro and PCCharge Payment Server for use only during integration and testing. Please note: The evaluation copies of PCCharge may not be used to perform live payment processing. Merchants must purchase a licensed copy of either PCCharge Payment Server or PCCharge Pro in order to perform live payment processing. Licenses for distribution to resellers and customers are available by contacting an authorized reseller or by calling (800) 725-9264.

PCCharge DevKit Suite

The PCCharge DevKit Suite is also a bundle of applications, tools, code examples, and documents used to enable electronic payment processing in third party applications. In fact, the manual, media, code examples, etc. are identical to those in the PCCharge DevKit. The only difference between the two products is that the PCCharge DevKit Suite contains the following licenses which allow live payment processing: One (1) live license for either PCCharge Payment Server or PCCharge Pro. One (1) Unlimited User license that can be activated within PCCharge Payment Server or PCCharge Pro.

Note: In this manual, both the PCCharge DevKit and PCCharge DevKit Suite are commonly referred to as the PCCharge DevKit or DevKit.

11

Product Components
PCCharge DevKit
The PCCharge DevKit is this manual and a group of examples of the various interface methods available to integrate payment processing into applications. Sample code for FoxPro, VB.Net, VB6, C++.Net, C#.Net, Access, Java, Delphi, ASP, Java, and Cold Fusion is included to demonstrate the OCX (ActiveX), DLL (ActiveX), OLE (COM), TCP Interface, and File Methods of integration.

PCCharge DevKit Development Support

The PCCharge DevKit includes three hours of telephone developer support to be used within twelve months. After that, a DevKit upgrade may be purchased in order to receive three additional hours of support. Alternatively, telephone/e-mail developer support is provided at a charge of $75.00 per half hour billed in advance in half hour increments. Consultative coding support is $1500 per day at the VeriFone, Inc. offices in Savannah, Georgia or $1500 per day plus travel and expenses at the developers location.

PCCharge Pro and PCCharge Payment Server

The PCCharge DevKit includes copies of PCCharge Payment Server and PCCharge Pro. PCCharge Payment Server and PCCharge Pro are the transaction engines that handle all payment processing requests submitted by the third-party integrated application. Both PCCharge Payment Server and PCCharge Pro include a GUI (Graphical User Interface) that is used for setup. This GUI can also be used for reporting, settlement, maintenance, and transaction processing if needed. When distributing an integrated application, either PCCharge Payment Server or PCCharge Pro must be installed and activated on the merchants computer or on a computer located in the merchants LAN in order to enable payment processing. Note: Merchants should not attempt to process transactions or run reports directly from the PCCharge GUI while the integrated application is processing transactions or settling batches. If the merchant wishes to process transactions or run reports directly with PCCharge (instead of through the integrated application), it is highly recommended that they use the PCCharge Client. The PCCharge Client is included on the PCCharge Pro and Payment Server CD, and can be installed on the same (or on a different) computer as PCCharge. The PCCharge Client has payment processing and reporting capabilities. The following outlines the features of PCCharge Pro and PCCharge Payment Server:

Payment Types Supported

Credit Cards -- PCCharge supports credit card transaction processing according to specifications of supported payment processors for the following major credit cards: VISA, MasterCard, Discover, American Express, Optima, Carte Blanche, Diners Club, and some private label cards. Debit Cards PCCharge supports debit card transaction processing according to specifications of supported payment processors for both online (ATM) and offline debit cards.

12

Checks PCCharge supports verification and conversion of a variety of types of paper-based checks including personal, government, payroll, travelers, and so forth. When performing verification transactions, primary and secondary forms of identification are accepted for each check type according to the specifications of the supported check processors. EBT PCCharge supports EBT transaction processing according to the specifications of the supported payment processors for both food stamp and cash benefit transactions. Gift Cards PCCharge supports gift card processing according to the specifications of the supported payment processors. PCCharge includes support for the following gift card programs (availability depending on processor): loyalty transactions, points-based transactions, multiple issuance, and standard transactions (Sale, Void, etc.).

Hardware Devices Supported

The PCCharge graphical user interface (GUI) includes support for many industry-standard hardware devices in addition to new devices that support the OPOS standard. Some of these devices are accessed via a standard COM port, whereas others may be connected to the keyboard (PS2) port. The devices include, but are not limited to the following: Report Printers Receipt Printers Magnetic Stripe Readers PINpads Check Readers

Note: In order for an integrated application to support these types of devices, the developer must create an interface to each hardware device that will be supported. Some devices simulate keyboard entry (such as Magnetic Stripe Readers) and do not require any special coding to support. However, some devices, such as PINpads, require a complete integration such as a serial port interface. VeriFone, Inc. provides an ActiveX control and an OLE/COM class that can be used to integrate to some PINpads. To support PINpads and other hardware that are not included in the control or the class, check with the various hardware providers for information on hardware integration. For a current list of the hardware devices that are supported by the PCCharge GUI, visit the VeriFone, Inc. website at www.pccharge.com

Reporting
The following reports are available in PCCharge. All reports contain filters (such as date, card number, member name, and so forth), allowing applications to designate the specific information to appear on the reports. All reports can be viewed on the screen if using the PCCharge GUI. Integrated applications can request that reports be sent to a printer or written to a file. Transaction Summary Report This report summarizes information for credit, debit, check, EBT, and gift transactions that have been performed. Detail Report Each payment type (credit, debit, check, EBT, and gift) has a detail report available. The reports show line item detail for each transaction. Batch Pre-Settle Report This report lists transactions that have been authorized but not settled.

13

Batch Post-Settle Report This report lists transactions that have been settled.

Security
Transaction Database Encryption -- PCCharge automatically encrypts account numbers within the programs database. Account numbers appearing will show only the first and last four digits of the account number. PIN Encryption -- PCCharge supports PIN data entry devices (as listed in previous sections) for use with online debit card processing. Each PINpad supported by PCCharge supports one or more of the two following PIN encryption standards:

1. Derived Unique Key Per Transaction (DUKPT) -- Derives a transaction key for the current or next transaction from the previous key plus other data. The scheme generates keys based on a finite list known only to the host and PINpad. The key sequence is unique to each PINpad, resulting in a unique key per transaction. DUKPT is the standard in the U.S., with other DUKPT schemes internationally. 2. Master/Session Key Management -- In this method, a key is injected into the PINpad in a secure environment. This "master" key is not used to encrypt PINs. Instead, it is used to decrypt a session or working key that has been encrypted by the host (using the master key) then transmitted over the network to the PINpad. This session key is used to encrypt PINs. The session key can be changed as frequently as every transaction. This encryption method is being phased out in the U.S.

Database Support
PCCharge uses a Microsoft Access database to store and maintain transaction information. This openarchitecture, industry-standard database is accessible through ODBC drivers, DAO or ADO.

Utilities
PCCharge includes a number of utilities to facilitate maintenance of the system. These include the ability to back up and restore data files, compact and repair the database, archive transaction history, as well as a number of modem detection and configuration options.

14

CHAPTER 2 -- Getting Started

15

Getting Started
It is recommended that several tasks be performed prior to coding. The DevKit and the PCCharge products will need to be installed, the test merchant accounts will need to be set up and tested, the method of integration will need to be chosen, and the differences between PCCharge Payment Server and PCCharge Pro should be reviewed.

Follow the steps below to set up PCCharge in a development environment:

1) Install the DevKit and the PCCharge Products

To install, insert the DevKit CD and follow the installation instructions. Once the DevKit installation has concluded, the installation program will prompt to install both PCCharge Pro and PCCharge Payment Server. It is recommended that both products be installed. The default installation options should be chosen while installing the DevKit and the PCCharge products.

2) Install the Test Merchant Accounts

The PCCharge DevKit comes with test merchant accounts that can be used while integrating credit card processing into third-party applications. The test merchant accounts should be utilized to avoid testing with live merchant accounts. Follow the procedure below to install the test merchant accounts: 1) Remove any floppy disks from drive A: 2) Start PCCharge Pro (use the PCCharge Pro shortcut in Start | Programs | Verifone | PCCharge Pro). If prompted, enter serial number 1234-1234-123456-54. 3) After a modem detection completes, the following message will appear: Do you have a configuration disk? 4) Click Yes and then OK. 5) When prompted to insert a disk in Drive A, click Cancel. 6) When the Copy Configuration Files From box appears, browse to the following directory: C:\Program Files\active-charge SDK\Test Merchant Info 7) Several files ending in .pcc will appear. Click Open. 8) When prompted to overwrite files, click Yes each time. 9) When prompted to Enter Serial Number, enter the serial number that was provided with the DevKit and click OK. Enter serial number 1234-1234-123456-54. 10) Click OK to each box that appears. PCCharge Pro is now set up with the Test Merchant Accounts. This process should now be repeated for PCCharge Payment Server.

16

Installing the Test Merchant Accounts Manually

The following is an alternative method for installing the test merchant accounts. The test merchant accounts are included in text-based configuration files (*.pcc) that are located in the directory C:\Program Files\active-charge SDK\Test Merchant Info. To install the test merchant accounts manually, close PCCharge and then copy these files directly into the directories where PCCharge Payment Server and PCCharge Pro reside: C:\Program Files\Active-Charge (for PCCharge Payment Server) C:\Program Files\PCCW (for PCCharge Pro )

When prompted to overwrite files, choose Yes. Note: Installing the test merchant accounts will overwrite any existing merchant configuration that was previously set up in PCCharge. A backup of the PCCharge directory is recommended if PCCharge was previously set up on the computer.

3) Verify that PCCharge is Set Up Properly

Prior to integrating, it is important to make sure that the test merchant accounts have been set up properly in PCCharge Payment Server and PCCharge Pro. This should be done by running test credit card transactions directly from the GUI of each program. Follow the procedure below to run credit card transactions in either PCCharge Payment Server or PCCharge Pro: 1) Start PCCharge Payment Server or PCCharge Pro. Note: After the initial setup of PCCharge Payment Server, its GUI is hidden by default each time the program starts. Double-click the dollar sign icon in the system tray to open the GUI. 2) From PCCharge, select one of the processors from the drop-down list at the bottom of PCCharge. Note: All processors in this list support dial-up processing, and many of them support direct TCP/IP processing. If testing of dial-up processing is required, refer to the PCCharge Payment Server or PCCharge Pro manual for information on setting up a modem with PCCharge. Refer to the web-based certification list to determine which processors support dial-up and TCP/IP processing: http://www.pccharge.com/products/pccharge_certs.htm Note: Not all processors allow test merchant accounts to be distributed in the PCCharge DevKit. This drop-down list represents only a subset of the processors that PCCharge supports. Note: The sample Chase Paymentech merchant account included with the DevKit will not allow TCP/IP testing as-is. The password must be updated in the Chase Paymentech Advanded Options screen in PCCharge prior to using the NetConnect functionality. See the Chase Paymentech entry in the Test Merchant Account Information section (see page 459) for more information. 3) Click the Visa / MasterCard icon. 4) Key in a transaction using one of the test credit card numbers that appear in the Test Credit Cards and Merchant Accounts section of the Appendix (see page 457).

17

5) Use 12XX as the expiration date (where XX is the last two digits of the current year: e.g., 1208). 6) Use the amount of $1.00 (many processors will decline test transactions if the amount is different than $1.00). 7) Click Process. If prompted for additional information, click No to each prompt. 8) A result of CAPTURED and an auth code will be returned if PCCharge is set up properly. (Note: A NOT CAPTURED may also be returned with some sort of a declined response. This is also a valid response from the processor and means PCCharge is set up properly.) Note: Not every card works with every test merchant number. If errors or decline messages are returned by PCCharge, attempt running transactions using different credit card numbers.

4) Determine Which Integration Method Will Be Used

There are five PCCharge integration methods available. This section will help the developer determine which method(s) should be used. The five integration methods are: 1) 2) 3) 4) 5) OCX (ActiveX) DLL (ActiveX) OLE/COM File Method TCP Interface

Note: Integration methods 1-3 (OCX, DLL, and OLE/COM) each create a text file that is sent to and processed by PCCharge. Thus, all three of these integration methods are essentially sending transaction information to PCCharge via the File Method. These three integration methods provide various classes, which include properties and methods to simplify integration. The properties and methods are very similar between the three integration methods, making it relatively easy to migrate from one to the other if needed.

OCX Method
The OCX Method should be considered if programming will occur in a visual environment that supports ActiveX technology and all client machines that will process transactions are Windows-based. The OCX controls are visual wrappers around code to create a flat text input file containing transaction data. Also, the OCX controls handle all of the file I/O (Input / Output) and automatically parse the output file that is created and returned by PCCharge. All of these operations are done by setting properties, calling methods, and monitoring events fired by the OCX controls. The use of events allows for asynchronous communication to PCCharge. A choice of two different communication methods is provided with the OCX: file transfer or TCP/IP. If file transfer is selected, the OCX will build a file to be sent to the specified path. If TCP/IP is selected, the OCX will build a string, and send that string through sockets to the IP address specified. To make use of the TCP/IP functionality a dependency file called the DartSecure2.dll will need to be distributed with the OCX file and registered on the client machine. This file is installed with PCCharge Pro or Payment Server and can be found in the System32 folder of any machine that has PCCharge installed on it.

18

When using TCP/IP, it is imparitive that the port be opened in PCCharge. To do this, open the PCCharge interface and select Setup > Configure System. Click advanced and select Use TCP/IP Connection. This is the port number setting that will be used in the OCX. Future Versions of PCCharge will have the ability to accept TCP/IP transaction via SSL. This functionality is written into the OCX. For now, this functionality must be turned off. Please consult the OCX documentation for instruction on how to turn this functionality off. Note: For the File Transfer method, in a client/server environment, the directory in which PCCharge resides must be shared so that the clients that are generating transactions have read, write, and execute permissions.

DLL Method
If programming will occur in a Windows programming environment that does not support the ActiveX OCX technology, then consider using the DLL Method (PSCharge.dll). PSCharge.dll is a wrapper around code to create a flat text input file containing transaction data. Also, PSCharge.dll handles all of the file I/O (Input / Output) and automatically parses the output file that is created and returned by PCCharge. All of these operations are done by setting properties and calling methods that are provided by PSCharge.dll. PSCharge.dll performs processing in a synchronous manner. A choice of two different communication methods is provided with the DLL: file transfer or TCP/IP. If file transfer is selected, the DLL will build a file to be sent to the specified path. If TCP/IP is selected, the DLL will build a string, and send that string through sockets to the IP address specified. To make use of the TCP/IP functionality a dependency file called the DartSecure2.dll will need to be distributed with the DLL file and registered on the client machine. This file is installed with PCCharge Pro or Payment Server and can be found in the System32 folder of any machine that has PCCharge installed on it. When using TCP/IP, it is imparitive that the port be opened in PCCharge. To do this, open the PCCharge interface and select Setup > Configure System. Click advanced and select Use TCP/IP Connection. This is the port number setting that will be used in the DLL. Future Versions of PCCharge will have the ability to accept TCP/IP transaction via SSL. This functionality is written into the DLL. For now, this functionality must be turned off. Please consult the DLL documentation for instruction on how to turn this functionality off. Note: For the File Transfer method, in a client/server environment, the directory in which PCCharge resides must be shared so that the clients that are generating transactions have read, write, and execute permissions. Note: If the application will be web-based (e.g., a shopping cart, eCommerce-enabled website, etc.), and will be hosted on a Windows-based web server, consider using the DLL Method. Web-based languages such as ASP and Cold Fusion support referencing DLLs.

OLE/COM Method
If programming will occur in a Windows programming environment that allows directly referencing the exposed classes of an executable, then consider the OLE/COM method of integration. The OLE/COM Method makes it possible to completely hide the PCCharge interface from the user. All aspects from setup and configuration to processing transactions can be done programmatically. It is

19

possible to make calls to set properties or show PCCharge forms by accessing the classes exposed through OLE/COM. All processing is done by setting properties, calling methods, and monitoring events. The use of events allows for asynchronous communication to PCCharge. The OLE/COM method also supports synchronous communication to PCCharge. Note: In order to use the OLE/COM Method, PCCharge must reside on the same computer as the integrated application. The OLE/COM Method will not typically work in a client/server environment (i.e., multi-user or multi-station). Note: When new versions of PCCharge are released (and the OLE/COM Method is used to integrate with PCCharge), the integrated application must be re-compiled for it to support these new versions. This is a limitation of OLE/COM, not of the PCCharge products.

File Method
The File Method is typically used by integrators who prefer to handle the creating, reading, and parsing of flat text files themselves. All of the required file I/O and polling must also be handled by the integrator. The widest variety of programming languages support the File Method. Integration via the File Method is required if programming will occur in an environment that does not support ActiveX, OLE/COM, or socket communications. When integrating via the File Method, the message format used to communicate with PCCharge is XML. The primary benefits to using the File Method are: It is operating system independent. It can be used in any programming language that supports file I/O.

In addition, the PCCharge File Method is very similar to the File Method for RiTA Server. RiTA Server, also designed by VeriFone, Inc., is an enterprise level payment processing product. If the integrator feels that an integration to the RiTA Server product might occur in the future, migration to the RiTA product is easier if the File Method is used when integrating with PCCharge. Note: Although the File Method is operating system independent, PCCharge must be running on a Windows machine somewhere on the networkonly the client machines may run on other operating systems. Note: In a client/server environment, the directory in which PCCharge resides must be shared so that the clients that are generating transactions have read, write, and execute permissions. Note: If the application will be web-based (e.g., a shopping cart, eCommerce-enabled website, etc.), the File Method may be used. Many Web based languages support file I/O.

TCP Interface
Any integrator using a programming language that supports the use of TCP/IP communication should consider utilizing the TCP Interface method. The primary advantage of using the TCP Interface method is that it is not file-based. This provides several benefits to the integrator: When PCCharge is used in a client/server environment, the TCP Interface does not require that the PCCharge directory be shared on the network. All other integration methods require that the PCCharge directory be shared on the network in a client/server environment.

20

The TCP Interface utilizes the operating systems TCP/IP stack and does not require any additional controls or additional object overhead to perform payment processing. The TCP Interface is operating system independent.

In addition, the PCCharge TCP Interface method is very similar to the TCP Interface method for RiTA Server. RiTA Server, also designed by VeriFone, Inc., is an enterprise level payment processing product. If the integrator feels that an integration to the RiTA Server product might occur in the future, migration to the RiTA product is easier if the TCP Interface is used when integrating with PCCharge. Note: Although the TCP Interface method is operating system independent, PCCharge must be running on a Windows machine somewhere on the networkonly the client machines may run on other operating systems. In a client/server environment, the client machines must have TCP connectivity to the Windows-based computer on which PCCharge resides. Note: If the application will be web-based (e.g., a shopping cart, eCommerce-enabled website, etc.), consider using the TCP Interface. Web based languages usually support socket communication. When integrating via the TCP Method, the message format used to communicate with PCCharge is XML.

21

Charts of Integration Methods

The following chart summarizes several of the characteristics of each integration method. Characteristics that are bold-faced are considered benefits of the integration method.
Requires PCCharge directory to be shared for client/server communication yes yes n/a yes Requires Properties and bundling controls methods provided with the / results parsed integrated automatically application yes yes yes

Integration Method

Platforms supported

Supports client/server communication

Supports Web-based integration

OCX DLL OLE/COM File Method TCP Interface

Windows Windows Windows

YES YES
no

no

YES
no

YES YES YES

no no

All All

YES YES

YES YES

NO

NO NO

22

The following chart lists the various Payment Types and functions that can be integrated along with the integration methods that support them.
Payment Types / Functions Integration Method OCX (Charge.OCX) DLL (PSCharge.dll Charge Class) OLE/COM (PccCharge Class) File Interface TCP Interface OCX (Debit.OCX & Device.OCX) DLL (PSCharge.dll Debit Class) OLE/COM (PCCDebit & PccPinPad Classes) File Interface TCP Interface OCX (Check.OCX) DLL (PSCharge.dll Check Class) OLE/COM (PccCheck Class) File Interface TCP Interface OCX (Debit.OCX & Device.OCX) DLL (PSCharge.dll Debit Class) OLE/COM (PCCEBT & PccPinPad Classes) File Interface TCP Interface OCX (GiftCard.OCX) DLL (PSCharge.dll Gift Class) OLE/COM (PCCGiftCard Class) File Interface TCP Interface OCX (Batch.OCX) DLL (PSCharge.dll Batch Class) OLE/COM (PccBatch & PccSettle Classes) File Interface TCP Interface OCX (Charge.OCX) DLL (PSCharge.dll Charge Class) OLE/COM (PccCharge Class) File Interface TCP Interface OLE/COM (Various Classes) OCX (Charge.OCX) DLL (PSCharge.dll Charge Class) OLE/COM (PCCDebit Class) File Interface TCP Interface

Credit Card Transactions

Debit Card Transactions

Check Transactions

EBT Card Transactions

Gift Card Transactions

Batch Settle/Close

Reporting

Configuration

Utilities (Transaction Inquiry, etc.)

23

5) Determine Which PCCharge Product(s) Will Be Supported

The DevKit includes copies of both PCCharge Payment Server and PCCharge Pro. Both products are provided so that the integrator can kick the tires on each product while integrating and testing. This section is designed to assist integrators in deciding which PCCharge product(s) to support in their applications.

Common Questions
What is the difference between PCCharge Payment Server and PCCharge Pro? Which product should I integrate with? What are the advantages of PCCharge Payment Server over PCCharge Pro and vice versa? These are common questions that are often asked by integrators and merchants. Unfortunately, there is not one correct answer to each of these questions. However, it is important for integrators and merchants to know the differences between the two products so that they can determine which one (or both) will meet their needs.

Differences and Similarities

The following are the differences between PCCharge Payment Server and PCCharge Pro: Directory / Executable PCCharge Pro is installed in the c:\Program Files\PCCW directory by default. PCCharge Pros executable is named Pccw.exe. PCCharge Payment Server is installed in the c:\Program Files\Active-Charge directory by default. PCCharge Payment Servers executable is named Active-Charge.exe.

GUI (Graphical User Interface) PCCharge Pro has a full-featured GUI that loads automatically. PCCharge Payment Server has a hidden GUI. The GUI can be accessed manually by the user by double-clicking a dollar sign icon in the system tray.

Error Message Suppression PCCharge Pro does not support Error Message Suppression. If the PCCharge Pro GUI pops up an error message, processing will halt until the error message is cleared manually by an enduser. PCCharge Payment Server supports Error Message Suppression. If the PCCharge Payment Server GUI is hidden (the default setting), any error messages generated by PCCharge Payment Server will automatically be logged to an error file, thus allowing payment processing to proceed normally.

Customer Database and Recurring Billing PCCharge Pro has a Customer Database and Recurring Billing feature available via the GUI. Note: These features cannot be integrated. PCCharge Payment Server does not support the Customer Database or Recurring Billing.

24

Reporting (in the GUI) Both PCCharge Pro and PCCharge Payment Server have reporting capabilities available via the GUI. However, PCCharge Pro has more reports than PCCharge Payment Server. PCCharge Payment Server has fewer reports, mainly because all reports related to the Customer Database and Recurring Billing have been omitted.

Batch Management Both PCCharge Pro and PCCharge Payment Server support Batch Management features. These features cannot be integrated. o With PCCharge Payment Server or PCCharge Pro, these features can be accessed from the GUI via the Batch menu or via a separate program that is included on the PCCharge Payment Server or PCCharge Pro installation CD.

Note: For more information on the Customer Database, Recurring Billing, Reporting (in the GUI), and Batch Management please refer to the PCCharge Pro or PCCharge Payment Server manuals.

The following are the similarities of PCCharge Payment Server and PCCharge Pro: Transaction Processing Engine Identical in both PCCharge Payment Server and PCCharge Pro

API (Application Programming Interface) Identical in both PCCharge Payment Server and PCCharge Pro

Processor Certifications Identical in both PCCharge Payment Server and PCCharge Pro

Database (Microsoft Access database) Identical in both PCCharge Payment Server and PCCharge Pro

Multi-User and Multi-Merchant Number Support Identical in both PCCharge Payment Server and PCCharge Pro

25

Illustration of Basic Differences and Similarities

The following graphic shows the basic differences and similarities of PCCharge Payment Server and PCCharge Pro:

Description of the diagram from the bottom up: P1, P2, P3, Pn and API: These sections represent the processor interfaces (aka Processor Certifications) that VeriFone, Inc. has coded into the PCCharge products. The processors provide VeriFone, Inc. with an API to code to in order for PCCharge to communicate with the processors network. Notice that there is only one set of processor interfaces. The processor interfaces are identical for both PCCharge Payment Server and PCCharge Pro. Note: When a processor interface is added and certified or updated by VeriFone, Inc., it is added or updated in all of the PCCharge products. Transaction Processing Engine and API: These sections represent the main PCCharge product and interface. This includes the PCCharge API, database, utilities, etc. Note: The API is identical for both PCCharge Payment Server and PCCharge Pro. Graphical User Interface: PCCharge Pro includes a full-featured GUI. This GUI appears when PCCharge Pro is started on a computer. When a user does transaction processing via the PCCharge Pro GUI, the GUI actually communicates to the Transaction Processing Engine via the API using the File Method of integration. In essence, the PCCharge Pro GUI is an integration to the Transaction Processing Engine. Hidden GUI: PCCharge Payment Server also includes a GUI. However, this GUI is not loaded by default and does not appear when PCCharge Payment Server is started on a computer. After PCCharge Payment Server has loaded, the user has the option of loading and viewing the GUI if they wish. Like PCCharge Pros GUI, the PCCharge Payment Server GUI also communicates to the Transaction Processing Engine via the API using the File Method of integration.

26

The Choice
Now that the differences and similarities have been outlined, merchants and integrators should now consider which product(s) will be used and supported.

PCCharge Payment Server

The following features of PCCharge Payment Server make it an appealing choice for most integrators: Hidden GUI Error Message Suppression

The Hidden GUI allows the integrator to hide the PCCharge Payment Server interface from the merchant completelymaking it appear as if all transaction processing is occurring solely in the third-party integration. This is desirable to many integrators. Also, Error Message Suppression is ideal if PCCharge Payment Server is running in an unattended environment (i.e., running in a data center, running in an office behind locked doors, or processing payments on a 24/7 eCommerce website, etc.). If an error message was to pop up in this type of environment, and no operator was immediately available to clear the message, payment processing would halt if Error Message Suppression was not available. Because of the above features, most integrators choose to integrate and support PCCharge Payment Server.

PCCharge Pro
Many integrators and merchants have found that they require some (or all) of the following features of PCCharge Pro that are not available in PCCharge Payment Server: Customer Database and Recurring Billing (only available via the GUI)

If these features are required, it may be necessary to integrate to and support PCCharge Pro. Keep in mind, though, that PCCharge Pro does not support the Hidden GUI and Error Message Suppression features of PCCharge Payment Server.

Both
Based on past experience and customer feedback, VeriFone, Inc. has found that most integrators decide to support both products, and then allow their merchants to decide which product works best based on their needs. Because of this, both PCCharge Pro and PCCharge Payment Server are included with the DevKit. It is suggested that developers integrate to and support both products. Because the APIs are identical, an integration to PCCharge Payment Server will also work with PCCharge Pro and vice versa. If using the TCP Interface method, there are no differences in the integration whatsoever. With the other integration methods, the main difference between integrating with PCCharge Pro and PCCharge Payment Server is the target directory. An integration that supports both products would provide a userselectable option to select the target directory for PCCharge rather than hard-coding the target directory.

27

6) Review Payment Processing Basics and Integration Information and Settings

The next chapter, CHAPTER 3 -- Payment Processing Basics, includes information about the basics of processing payments and a description of each payment type supported by PCCharge. This chapter should be reviewed by integrators before any coding begins. The integration of PCCharge will go much smoother if the integrator has an understanding of how transaction processing occurs on a day-to-day basis. It is also recommended that integrators review the information contained in CHAPTER 4 -- Integration Information and Settings (see page 42). This chapter includes warnings, integration tips, and guidelines that should be followed while integrating, and includes important information about Users, Merchant Accounts, Timeouts, Follow On transactions, etc. After PCCharge has been set up and these chapters have been reviewed, the integration may begin. Refer to the DevKit Constants section (see page 94) and CHAPTER 6 -- PCCharge Integration Methods (see page 104) for information on integrating payment processing using PCCharge.

28

CHAPTER 3 -- Payment Processing Basics

29

Credit Card Processing

This section provides a general overview of credit card processing and how processing differs between Host based and Terminal based Processors.

Host based and Terminal based Processors

The most important concept for integrators to understand is what Host based and Terminal based processors are and what the differences are between them. Depending on which type of processor will be used by the merchant, certain tasks must be performed by the merchant either directly from the PCCharge GUI or from the integrated application to enable them to receive funds from their credit card transactions. Processing credit card transactions is a two-step process. When a credit card sale transaction is performed by the merchant, the customers limit to buy on their credit card account is reduced and the transaction is placed in a batch. A batch is defined as a collection of transactions that are approved but have not yet been submitted for end of day settlement. Before funds can be deposited into the merchants bank account, a second step, re-transmission, must occur. When using PCCharge, the re-transmission process is called Batch Settlement or Batch Close. Terminal based processors have batches that are settled, and Host based processors have batches that are closed. Regardless, all credit card transactions in a batch have to be re-submitted to the processing company. With certain processing companies, this step takes place automatically. With others, the process must be performed manually. So, in this context, there are two types of processing companies: 1) Terminal based If the merchant is using a Terminal based processor, PCCharge stores the batch of transactions in a file in the PCCharge directory. This file is commonly known as a Settlement File. With Terminal based processors, batch settlement must be done manually, usually at the end of each business day. This procedure can be performed, by the merchant, from the PCCharge GUI. This procedure can also be accessed programmatically by the integrator. 2) Host based - With a Host based system, the batch is stored on the credit card processor's computer system. With a Host based system, merchants can be set up in one of two ways: a. Auto (Time Initiated) Close At a certain time during the day, the Host based system will scan its computer system. If a merchant has an open batch of transactions, the system will automatically close the batch. Usually, the merchant can specify the time when the batch will be closed each day. If a merchant is set up for Auto Close with their Host based processor, there are no steps needed to initiate the batch close process. b. Manual Close Credit card transactions will sit in an open batch indefinitely. The merchant is responsible for indicating to the Host based processor that the batch should be closed. This step can be performed by the merchant from the PCCharge GUI. This procedure can also be accessed programmatically by the integrator. WARNING: Without settling or closing the batch, the merchant will not receive any funds from credit card transactions!

30

Credit Card Transactions

There are several types of credit card transactions. The different types of transactions are referred to as actions in PCCharge. The following is a list of the various actions with general descriptions. Sale - This action reduces the cardholder's limit to buy, and places the transaction in the open batch. This action is commonly used in retail and restaurant environments. Void Sale - This action removes a sale transaction from the open batch. No funds will be deposited into the merchants bank account at settlement/close. The Void Sale action is typically used for same day returns or to correct cashier mistakes. This action can only be performed before the batch is settled/closed (this usually means the action has to be performed on the same day as the sale). Credit - This action is used to refund money to the cardholder. This action is typically used after the batch that contains the Sale (or Post-Authorization) transaction has been settled or closed. This action will increase the cardholder's limit to buy once the batch containing the credit has been settled. Void Credit - This action removes a credit transaction from the batch. This action can only be performed before the batch is settled/closed (this usually means the action has to be performed on the same day as the credit). This transaction is not available with all processing companies. If the Void Credit action is not available, use the Void Sale action. Pre-Authorization - This action only reduces the cardholders limit to buy. It does not place a transaction in the open batch. A Pre-Authorization can be considered the first half of a sale. A Pre-Authorization reduces the limit to buy for only a predetermined amount of time, usually 7-10 days. The credit cards issuing bank determines the amount of time. To place the transaction in the open batch, a follow-on transaction (called a Post-Authorization) must occur. This action is commonly used in MOTO (Mail Order / Telephone Order) and eCommerce environments. Voice-Authorization A Voice-Authorization is similar to a Pre-Authorization, except that it is not a PCCharge action. A Voice-Authorization is a way for a merchant to receive an approval and an authorization code from their processing company via a telephone operator or an automated system. This type of authorization is necessary if the processing companys Internet interface or modems are down, or if the merchant has experienced a power failure, computer crash, or other issue that does not allow them to process electronically. A Voice-Authorization may also need to occur if a credit card transaction is flagged as fraudulent by the credit card issuer. In order to place a Voice-Authorization in the open batch, a follow-on transaction, called a PostAuthorization, must occur. Post-Authorization - This action places an approved Pre-Authorization transaction into the open batch. This action can be considered the second half of a sale. This follow-on transaction must occur before a Pre-Authorization can be settled/closed. This Post-Authorization may also be used to place an approved Voice-Authorization in the batch. Void Post-Authorization - This action removes a Post-Authorization transaction from the open batch. This action can only be performed before the batch is settled/closed (this usually means the action has to be performed on the same day as the Post-Authorization). This transaction is not available with all processing companies. If Void Post-Authorization is not available, use the Void Sale action. Commercial Card Sale - This action reduces the cardholder's limit to buy, and places the transaction in the open batch. This action is similar to a standard credit card sale, but is typically used if the card tendered is a procurement, purchasing, business, government, or commercial

31

card. Two additional values, the Tax amount and customer code, must be passed with this type of card in order for the merchant to qualify for the lowest transaction rate. Note: Global East (NDC), terminal based, requires the customer code be all upper case. Commercial Card Credit - This action is typically used after the batch that contains the Procurement Card Sale (or Procurement Card Post-Authorization) transaction has been settled or closed. This action is similar to a standard credit card credit, but is typically used if the card tendered is a procurement, purchasing, business, government, or commercial card. This action will increase the cardholder's limit to buy once the batch containing the credit has been settled. Two additional values, the Tax amount and customer code, must be passed with this type of card in order for the merchant to qualify for the lowest transaction rate. Note: Global East (NDC), terminal based, requires the customer code be all upper case. Commercial Card Post-Authorization - This action places an approved Pre-Authorization transaction into the open batch. This action is similar to a standard credit card Post-Authorization, but is typically used if the card tendered is a procurement, purchasing, business, government, or commercial card. This action can be considered the second half of a sale. This follow-on transaction must occur before a Pre-Authorization can be settled/closed. This Post-Authorization may also be used to place an approved Voice-Authorization in the batch. Two additional values, the Tax amount and customer code, must be passed with this type of card in order for the merchant to qualify for the lowest transaction rate. Note: Global East (NDC), terminal based, requires the customer code be all upper case. Sale with Gratuity Used only in a restaurant environment, this action allows a server to authorize the amount of the meal plus the gratuity and place the entire amount in the batch. When settled, the amount plus the gratuity is deducted from the cardholders account. Gratuity Used only in a restaurant environment, this action adds or adjusts the gratuity amount on an existing Sale transaction. This action must be performed prior to batch settlement/close. Note: There is no action to void a Pre-Authorization. This is because Pre-Authorization cannot be voided.

A Normal Credit Card Processing Day

This section discusses a normal day of processing credit card transactions. This section assumes that merchants will have access to the reports provided in the PCCharge GUI and that these reports can be compared to reports available in the integrated application. Processing credit card transactions consists of six steps: 1) By performing the first credit card transaction of the day, the batch is opened. 2) Run transactions throughout the day. 3) After processing has been completed for the day, it is time to prepare for settlement: a. Look at the PCCharge Daily Transaction Summary Report for the day. b. Compare the PCCharge Daily Transaction Summary Report with summary data provided by the integrated application. c. Does the report look correct and do the totals match up with the integrated applications totals? 4) If the reports indicate discrepancies, use the PCCharge Credit Card Detail and Batch Pre-Settle Reports (if the processor is Terminal based) to investigate and resolve any discrepancies. 5) If the processor is Host based, settlement will occur automatically.

32

6) If the processor is Terminal based, settlement must be done manually. Start the settlement process now. Repeat these six steps each day of processing credit card transactions.

Credit Card Transaction Rates

It is important for integrators to understand credit card transaction rates. The card associations (Visa, MasterCard, etc.) require certain data to be submitted with each transaction in order for the merchant to qualify for the lowest transaction fees. While integrating, it is important that the application be designed to allow merchant to pass any and all rate-qualifying data while performing transactions. Below is a general list of information that should be submitted in order for the merchant to receive the best rates: Best Rates -- Card Swiped Fair Rates -- Card Not Present & Ticket Number & Street Address & Zip Code Worst Rates -- Card Not Present & No Address Information Transaction rates are based on risk. They vary based on the size of the merchant organization and that merchants ratings, markets, and how transactions occur. For instance, a very large traditional walk-in, multi-store retail organization with check out lanes will have the lowest rates. A new mail order or eCommerce merchant, with no retail facilities and no face-to-face or "card present" transactions, will typically have to pay the highest transaction rates. Based on some of these variables, each transaction can have qualifiers for higher or lower rates. A properly written integrated application can help MOTO or eCommerce merchants get better rates (and reduce fraud) by using the Address Verification Service (AVS). AVS captures ZIP codes and addresses of the cardholders billing address. AVS information is then compared to the cardholders ZIP code and address that the card issuer has on file. Address and ZIP code mismatches help the merchant to decide whether or not they wish to go through with the transaction, thus helping to reduce fraud.

Commercial Cards Note

If a merchant will accept procurement, purchasing, business, government, or commercial cards, the integrated application must be written to allow merchants to pass the tax amount and customer code for these types of cards. This information helps the cardholder by allowing them to receive this detail on their monthly statements and also benefits the merchant by allowing them to qualify for the lowest rates when accepting these types of cards. Commercial card transactions that do not include this additional information will be downgraded. Note: Global East (NDC), terminal based, requires the customer code be all upper case.

33

Debit Card Processing

Debit cards were designed to be used more like a check than a credit card. Unlike credit cards with a line of credit, the debit card causes the amount of the purchase to be deducted from the debit cardholders checking account. Like ATM cards, debit cards can be used to withdraw money from a bank account, debiting the account immediately. However, unlike debit cards, ATM-only cards cannot be used as cards for purchases. Some debit cards, called check cards, can be used as debit, ATM, and credit cards. If used as a debit or ATM with the PIN, transactions are considered to be online and debited immediately from the cardholders account. Debit check cards used as credit cards are considered offline transactions and must go through the credit settlement process; thus, taking several days to reach the bank and be debited from the cardholders account. Although merchants accept either credit cards or debit check cards, most merchants are unaware of the distinction by just looking at the card. However, credit cards normally have a percentage of the transaction as the fee while debit transactions are normally a smaller set fee.

There are three important points to know about processing debit transactions: 1) There are two types of debit card transactions: a. Online - Online debit refers to debit card processing that requires a debit card to be swiped and a PIN to be entered when processing a transaction. b. Offline - Offline debit refers to debit card processing that allows a debit card to be swiped or keyed in and PIN entry does not occur. Essentially, these card are processed as normal credit cards. A debit card supports offline debit if it has a VISA or MasterCard logo on the front of it. Cards that support offline debit are commonly referred to as check cards. Refer to the previous section for general information on processing credit cards. 2) Online Debit Transactions may only be performed in a Retail or "face to face" environment. Mail Order/Telephone Order, and eCommerce businesses cannot perform online debit transactions. 3) Online debit transactions require that the card be swiped and that the customer enters their PIN on a PINpad. Each cash register or computer that will support Online debit transactions must have a card swipe device and PINpad connected to it. As with credit card processing, debit processing is a two-step process. Debit processing requires retransmission of information, referred to as Closing. Typically, Debit processors are Host based. That means the information to be re-transmitted is stored on the host computer systems or the processor's computer system. Merchants can be set up one of two ways: Time Initiated Close At a certain time during the day (usually specified by the merchant), a Host based system will scan its database. If a merchant has an open batch (transactions that have not been deposited), the host system will automatically close the batch. Manual Close Authorized transactions will sit in an open batch indefinitely. The merchant is responsible for indicating to the host processor that the batch should be closed. If the merchant is set up for Manual Close, they will need to perform a Close to complete their debit transactions. If the merchant is processing credit card transactions as well as debit transactions, the debit transactions will be closed at the time that the credit card transactions are settled.

34

Debit Card Transactions

There are several types of debit card transactions. The different types of transactions are referred to as actions in PCCharge. The following is a list of the actions with general descriptions. Sale - This action deducts funds from the cardholder's bank account. Return - This action deposits funds into the cardholder's bank account. Void This action voids a Sale or Return.

A Normal Debit Card Processing Day

This section discusses a normal day of processing Debit transactions. This section assumes that merchants will have access to the reports provided in the PCCharge GUI and that these reports can be compared to reports available in the integrated application. Processing Debit transactions consists of six steps: 1) By performing the first Debit card transaction of the day, the batch is opened. 2) Run transactions throughout the day. 3) After processing has been completed for the day, it is time to prepare for settlement: a. Look at the PCCharge Daily Transaction Summary Report for the day. b. Compare the PCCharge Daily Transaction Summary Report with summary data provided by the integrated integration. c. Does the report look correct and do the totals match up with the integrated applications totals? 4) If the reports indicate discrepancies, use the PCCharge Debit Summary report to investigate and resolve any discrepancies. 5) If the processor is Host based, settlement will occur automatically. 6) If the processor is Terminal based, settlement must be done manually. Start the settlement process now. Repeat these six steps each day of processing debit card transactions.

35

Check Processing
Check Guarantee and Check Verification services do not involve an electronic transfer of funds. The merchant performs Check Verification to determine that if check writer has an account and if the check writer has any current outstanding (bounced) checks. Check Guarantee services extend a guarantee that the merchant will get his money, even if the check bounces. Normally, a higher fee is charged for guarantee service (usually a fee similar to credit card processing fees). Check Verification and Check Guarantee are one-step processes. There are three types of Check transactions: 1) Check Verification - Verification allows the merchant to verify that the check writer has a checking account and does not have any outstanding bad checks. 2) Check Guarantee - Guarantee allows the merchant to verify that the check writer has an account and guarantees that the funds are available. 3) Check Conversion Conversion allows the merchant to use the MICR information on a check to electronically deposit funds. This transaction eliminates the need to deposit a paper check.

Check Conversion
Check Conversion is a process by which a checking account is debited electronically. Check conversion is a two-step process. As with credit cards, there is a secondary transmission of information needed to complete a transaction. The second step is called Truncation Close. The important thing to remember is that without re-transmission of the check information, the merchant will not receive their money. Every day that a merchant performs truncations, they should perform a Truncation Close after all transactions are complete.

36

Check Transactions
There are a few different types of check conversion transactions. The following is a list of actions with general descriptions: Verify This action allows the merchant to verify that a checking account exists for the customer and guarantees that the amount of the transaction is available. This action also allows the merchant to perform the first half of a sale transaction. This action does not make information available for retransmission. Sale This action reduces the balance of the customers checking account. A sale actually performs two functions. First, a sale will Verify / Guarantee a check. Second, it will make the transaction available for re-transmission. Void This action removes a Sale or Force transaction from the re-transmission information. The transaction will be deleted; no funds will be received from this transaction. The Void Sale action is used to correct mistakes and on same day returns. This action can only be performed before retransmission. Force This action makes a verified check transaction available for re-transmission. A Verify followed by a Force is equivalent to a Sale.

A Normal Check Conversion Processing Day

This section discusses a normal day of processing check transactions. This section assumes that merchants will have access to the reports provided in the PCCharge GUI and that these reports can be compared to reports available in the integrated application. Processing Check transactions consists of six steps: 1) By performing the first check conversion transaction of the day, the batch is opened. 2) Run transactions throughout the day. 3) After processing has been completed for the day, it is time to prepare for settlement: a. Look at the PCCharge Daily Transaction Summary Report for the day. b. Compare the PCCharge Daily Transaction Summary Report with summary data provided by the integrated integration. c. Does the report look correct and do the totals match up with the integrated applications totals? 4) If the reports indicate discrepancies, use the PCCharge Check Summary report to investigate and resolve any discrepancies. 5) If the processor is Host based, settlement will occur automatically. 6) If the processor is Terminal based, settlement must be done manually, start the settlement process now. Repeat these six steps each day of processing check conversion transactions.

37

EBT Processing
Electronic Benefits Transfer (EBT) is a way of issuing and processing certain benefits electronically. The government issues Food Stamps and aid to families with dependent children on EBT cards that resemble credit or debit cards. The government is issuing Social Security payments, Disability payments, and many other government issued payments on these EBT cards. With EBT processing, these payments can processed just as a debit card would be processed. More and more state governments and the federal government will be moving to this form of payment processing to reduce paper work and control fraud. With EBT transactions, keep these two simple rules in mind. 1) EBT transactions can only be performed in a Retail or "face to face" environment. If the merchant is a Mail Order type business, they cannot perform EBT transactions. 2) EBT transactions require that the merchant have a card swipe and PINpad attached to their computer. As with debit card processing, EBT processing is a two-step process. EBT processors are typically Host based. As with every Host based System, merchants may have the ability to be set up for either Time Initiated (Automatic) Close or Manual Close. There are four types of EBT card transactions. The types are based on the kind of benefit being processed. For instance, if the merchant will process a transaction with food stamps, they will want to use the transaction type called Food Stamps. The reason for the different types of transactions is that there are different rules governing each type of benefit. 1) Cash Use this transaction type to process a transaction with an EBT card that was issued for a Social Security payment. 2) Food Stamp Use this transaction type to process a food stamp transaction to deduct money from the EBT card. 3) Food Stamp Credit Use this transaction type to process a food stamp transaction to credit money back onto the EBT card. 4) Account Inquiry This transaction allows the merchant to inquire into a customer's account. The merchant is able to dial into the EBT processing company and view a customers account. This transaction is not specific to a benefit type. Merchants will be able to perform an inquiry, regardless of the type of benefit. In the next four sections, we will break down each transaction type and describe each action available.

Cash EBT Transactions

All transactions that are not food stamp related should be processed as Cash EBT Transactions. Cash EBT transactions are very similar to debit transactions because customers can receive cash back from transactions. There are three types of cash transactions. To maintain consistency, they will be referred to as actions. 1) Withdrawal This action deducts from the cardholder's limit to buy. Money will be deducted from the account. 2) Post This action makes an approved Voice Authorization transaction available for retransmission. This action is the second half of a withdrawal. 3) Void This action removes a withdrawal transaction from the re-transmission information. The transaction will be deleted. Merchants will not receive funds from this transaction. Use the Void action to correct mistakes and on same day returns. This action has to be performed on the same day as the original transaction.

38

Food Stamp EBT Transactions

When performing a sale transaction using food stamp benefits, use the Food Stamp EBT Transaction. 1) Withdrawal This action deducts from the cardholder's limit to buy. Money will be deducted from the account. 2) Post This action makes an approved Voice Authorization transaction available for retransmission. This action is the second half of a withdrawal. 3) Void This action removes a withdrawal transaction from the re-transmission information. The transaction will be deleted. Merchants will not receive funds from this transaction. Use the Void action to correct mistakes and on same day returns. This action has to be performed on the same day as the original transaction.

Food Stamp Credit EBT Transactions

When performing a return transaction using food stamp benefits, use the Food Stamp Credit EBT Transactions. 1) Withdrawal This action increases the cardholder's limit to buy. Funds will be credited back to the account. 2) Post This action makes an approved Voice Authorization transaction available for retransmission. This action is the second half of a withdrawal. 3) Void This action removes a withdrawal transaction from the re-transmission information. The transaction will be deleted. Use the Void Sale action to correct mistakes. This action has to be performed on the same day as the original transaction.

Account Inquiry EBT Transaction

This transaction type is intended only as a maintenance function. It is used when merchants need to verify that there is a certain amount in a customer EBT account. Merchants simply enter the card number and expiration.

A Normal Day of Processing EBT Transactions

This section discusses an average day of processing EBT transactions. This section assumes that merchants will have access to the reports provided in the PCCharge GUI and that these reports can be compared to reports available in the integrated application. Processing EBT transactions consists of six steps: 1) By performing the first EBT transaction of the day, the batch is opened. 2) Run transactions throughout the day. 3) After processing has been completed for the day, it is time to prepare for settlement: a. Look at the PCCharge Daily Transaction Summary Report for the day. b. Compare the PCCharge Daily Transaction Summary Report with summary data provided by the integrated application. c. Does the report look correct and do the totals match up with the integrated applications totals? 4) If the reports indicate discrepancies, use the PCCharge EBT Summary report to investigate and resolve any discrepancies. 5) If the processor is Host based, settlement will occur automatically.

39

6) If the processor is terminal based, settlement must be done manually. Start the settlement process now. Repeat these six steps each day of processing EBT transactions.

40

Gift Card Processing

A typical gift card program allows the merchant to offer their customers full-color, plastic electronic gift cards instead of traditional paper gift certificates. Customers purchase these cards (using cash, check, or credit card), and the card is activated on the spot with a simple 'swipe' through the card reader. This activation records the starting dollar amount in a central location. The card's magnetic strip can also identify the cardholder, card number, and merchant location for which the card has been issued. Gift cards are used just like a credit or debit card to purchase goods or services, and they are authorized using a system similar to that of the credit card processing systems. The dollar value of the purchase is subtracted from the account total in the database, the purchase is logged, and the new card value is recorded.

A Normal Day of Gift Card Processing

This section discusses a normal day of processing gift card transactions. This section assumes that merchants will have access to the reports provided in the PCCharge GUI and that these reports can be compared to reports available in the integrated application. Note: Gift Card Processors are Host based. Gift Cards do not require settlement. Processing Gift Card transactions consists of three steps: 1) Run transactions throughout the day. 2) After processing has been completed for the day, it is time to reconcile: a. Look at the PCCharge Daily Transaction Summary Report for the day. b. Compare the PCCharge Daily Transaction Summary Report with summary data provided by the integrated application. c. Does the report look correct and do the totals match up with the integrated applications totals? 3) If the reports indicate discrepancies, use the PCCharge Gift Card report to investigate and resolve any discrepancies. Typically, these three steps should be repeated each day of processing Gift Card transactions.

41

CHAPTER 4 -- Integration Information and Settings

42

Warnings, Tips, and Guidelines

The following are warnings, integration tips, and guidelines to follow while integrating PCCharge. It is suggested that integrators adhere to all guidelines to keep integrated applications running smoothly and to keep merchants compliant with all payment processing rules and regulations. XML Message Format It is strongly recommended that the XML message format is used when integrating to PCCharge. Starting with PCCharge version 5.6.0, the PCCharge products were updated to support the XML message format. The XML message format is recommended because: o Transaction requests and responses are formatted in a flexible, variable-width message format when using XMLthus allowing any number of fields to be passed back and forth to PCCharge. The legacy INP message format is proprietary and transaction requests are restricted to a fixed width (256 characters). When using the INP message format, many transaction requests require the re-use of fields. All new features and enhancements to PCCharge require the use of the XML message format. Some of these features include Follow-On transactions, Transaction Inquiries, Gratuity Adjustments, and Canadian debit. Starting with the 5.7 release of the DevKit, all documentation assumes that the XML message format is being used by the integrator. When using the legacy INP format, some PCCharge reports may not update the transaction status for follow-on transactions. This is a limitation of the legacy INP format. This can be remedied by using the XML message format. The INP message format will eventually be phased out.

o o

If an existing integration was written using the INP message format, it is highly recommended that the integration be updated to use the XML message format. The XML message format is available in all five integration methods. To enable the use of the XML message format when using the OCX, DLL, or OLE/COM methods of integration, set the message format parameter to 3 when calling the Send method. OCX / DLL: .Send 3 OLE/COM: .Send , 3 To use the XML message format when using the File Method or TCP Interface, simply follow the File Layout Specifications outlined in the File Method section (see page 411). Note: The legacy INP message format is selected as default in the OCX, DLL, and OLE/COM Methods of integration for backwards compatibility reasons. If the message format parameter is not set to 3 when calling the Send method, the various controls and classes will default to the INP message format. Note: Older copies of the DevKit that outline the INP message format are available for integrators upon request. Contact VeriFone, Inc. at 800-725-9264 to request a copy of an older DevKit manual. Cardholder Information Security Program (CISP). It is extremely important to always adhere to CISP guidelines while integrating. The following are the most pertinent to the integrator: o Magnetic Stripe Data The integrated application should not store or print credit card magnetic stripe data. Make sure that all printouts, files, databases, logfiles, etc. do not contain this information. Refer to the Important Security Notice (see page 8) for more information.

43

Card Verification Data The integrated application should not store or print the CVV2, CVC2, or CID data from the back or front of credit cards. Make sure that all printouts, files, databases, logfiles, etc. do not contain this information. Refer to the Important Security Notice (see page 8) for more information. Credit Card Numbers / Expiration Dates If the integrated application will store credit card account numbers and expiration dates, these values must be encrypted in all files, databases, logfiles, etc. Refer to the Important Security Notice (see page 8) for more information.

Receipt Printing If the integrated application will print receipts, it is a good idea to provide an option in the integrated application that allows masking of the digits of the credit card number and the removal of the expiration date on a receipt that will be given to a customer. The integrated application should not print the full card number and expiration date on a customer receipt. Many states have laws regarding the information that is printed on receipts. The merchant should familiarize themselves with the laws that pertain to them. Transaction Processing - Because of the single-threaded architecture of PCCharge, it is important that the integrated application refrains from submitting (or importing) transactions while PCCharge is performing the following functions: o o o o Settlement / Batch Close Database Repair / Compact Backup or Restore of configuration files and database Database Transaction archive

If the integrated application submits transactions while any of the above functions are taking place, database corruption and/or lost transactions may occur. If integrating with the OCX, DLL, or OLE/COM methods, always use the PccSysExists method to check if these functions are being performed prior to submitting a transaction. If PccSysExists returns TRUE, do not submit the transaction. See CHAPTER 6 PCCharge Integration Methods (see page 104) for more information on using the PccSysExists method. If using the File Method, always check for the presence of the SYS.PCC file in the PCCharge directory prior to submitting the transaction. If this file appears in the directory, the integrated application should not submit the transaction. The contents of the SYS.PCC file can be checked to determine what function is being performed by PCCharge. Refer to the section SYS.PCC Codes and Descriptions (see page 100) for more information. If using the TCP Interface, the SYS.PCC check is not necessary. When using the TCP Interface, if PCCharge is "busy" performing tasks, it will either queue up the transaction and process it once the task has been completed (such as in batch settlement) or it will return a "transaction cancelled, system busy" message if other tasks are running. Direct Database Access - If an integrated application will access the PCCharge database (pccw.mdb) directly, it is important that the integrated application refrains from accessing the database while transactions are being processed or while batches are being settled. Because of the limitations of Microsoft Access, if an integrated application tries to access the database (even in read-only mode), PCCharge may not be able to read or update records in the database. This has been known to cause database corruption, settlement errors, and lost transactions. Remote Access - We currently do not support accessing PCCharge via Windows Remote Desktop, Virtual Private Network (VPN), or any other remote interface application. Programs like these allow PCCharge to initiate multiple instances of itself, causing lost transactions, duplicate charges, and database corruption. Instead, we recommend that you use either PCCharge Client or PCCharge DevKit (via integration) to remotely access PCCharge.

44

Terminal Service environment - PCCharge is not supported in a Terminal Service environment. Terminal Services allows multiple instances of the same application to run simultaneously. PCCharge cannot be supported in such an environment. Running multiple instances of PCCharge often results in duplicate charges and lost transactions. PCCharge GUI - Merchants should not attempt to process transactions or run reports directly from the PCCharge GUI while the integrated application is processing transactions or settling batches. If the merchant wishes to process transactions or run reports directly with PCCharge (instead of through the integrated application), it is highly recommended that they use the PCCharge Client. The PCCharge Client is included on the PCCharge Pro and Payment Server CD, and can be installed on the same (or on a different) computer as PCCharge. The PCCharge Client has payment processing and reporting capabilities. Default User Name - The default user name, User1, should not be renamed under any circumstances. PCCharge relies on this user name to perform several internal functions. If different user names are desired, they should be added in the PCCharge Users setup screen. See the section Multi-User Support (see page 50) for more information on users. Clearing Variables - If the OCX, DLL, or OLE/COM methods of integration will be used, always destroy the object (or use the Clear or ClearVariables methods) after the transaction has been processed, the results have been retrieved, and the DeleteUserFiles method has been called. Running the next transaction without clearing the properties and methods from the previous transaction has been known to cause duplicate transactions and double-charges. Duplicate Transactions It is very important that merchants always enable the Require Duplicate Transactions to be Forced option in the PCCharge configuration screen and that the integrated application handles duplicate transactions properly. A duplicate transaction is defined as a transaction that contains the same account number, the same expiration date, and the same amount on the same day. If the forced duplicates option is enabled and a duplicate transaction is submitted to PCCharge, PCCharge will respond immediately with the error response Duplicate Trans; F+Card# to Force. Enabling the forced duplicates option ensures that customers are not double charged because of errors (either human error, an error in the integrated application, or an error in PCCharge). If the duplicate transaction is legitimate, the integrated application should provide the end-user the ability to force the transactionwhich is defined as adding the character F to the beginning of the card number. This character will override the forced duplicates option on a per-transaction basis. Note: The forced duplicates option is enabled by default in PCCharge, but many merchants disable it when the Duplicate Trans error message occursthus potentially allowing any transaction to be duplicated. Enhanced Transaction Force PCCharge supports an enhanced transaction force feature. This feature allows forcing a duplicate transaction unless the ticket number is the same as a previous transaction. By placing an E in front of the card number, PCCharge is instructed to force the transaction unless all of the standard fields for a duplicate transaction (account number, expiration date, and amount) PLUS the ticket number are identical to a previous transaction. For example, if the E is included in front of the account number and the ticket number is different, the transaction will be accepted. However, if the ticket number is the same, the transaction will be considered a duplicate and will return the error response Duplicate Trans; F+Card# to Force. FDMS South / NaBanco Special Note - FDMS South / NaBanco (NB) will occasionally return certain pieces of transaction information that contain spaces. PCCharge changes each of these spaces to an asterisk (*) to make the resulting information more legible. Previous versions of PCCharge did not convert these spaces to asterisks. Therefore, if upgrading from a previous

45

version of the DevKit and the integrated application supports FDMS South / NaBanco, it is recommended that the application be updated to correctly parse the information with asterisks. Unexpected results may occur if the application is not updated. Global East/NDC Special Note When processing manual (non-swiped) Visa or Discover card transactions where the CVV or CID values are not supplied, the following data must be passed in the CVV2 parameter: o o o 0 Deliberated bypassed 2 CVV value illegible 9 Card has no CVV value

CES Special Note When processing manual (non-swiped) Visa or Discover card transactions where the CVV or CID values are not supplied, the following data must be passed in the CVV2 parameter: o o o 0 Deliberated bypassed 2 CVV value illegible 9 Card has no CVV value

NOVA Special Note When processing manual (non-swiped) Visa or Discover card transactions where the CVV or CID values are not supplied, the following data must be passed in the CVV2 parameter: o o o 0 Deliberated bypassed 2 CVV value illegible 9 Card has no CVV value

ADSI Special Note When processing manual (non-swiped) Visa or Discover card transactions where the CVV or CID values are not supplied, the following data must be passed in the CVV2 parameter: o o o 0 Deliberated bypassed 2 CVV value illegible 9 Card has no CVV value

46

Timeouts
It is very important that integrated applications handle Timeout errors properly so that customers are not double-charged. Several of the PCCharge integration methods support options for handling Timeout errors.

Understanding Timeouts
The first step in handling Timeout errors properly is to understand why they occur. A Timeout error will occur if a transaction has not completed processing in PCCharge in the allotted time that the integrated application has provided. For example, if the integrated application has allotted 20 seconds for a transaction to be processed, the integrated application will only poll for a transaction response for 20 seconds. If a response has not been received from PCCharge in that amount of time, a Timeout error will occur in the integrated application. Even if a Timeout error occurs in the integrated application, PCCharge will continue to process the transaction. Imagine, in this example, the transaction was processed by PCCharge in 25 seconds, and was approved. Because the transaction took more than 20 seconds to complete, the integrated application assumes the transaction was not successful. However, PCCharge received an approved response and added the transaction to the batch. The problem this could cause is that a cashier will receive a message stating the transaction timed out will assume it was not approved--when it really was approved. The cashier will then attempt process the transaction again, thus potentially double-charging the customers card and creating other reconciliation issues.

Transaction Delays
Transaction delays are the main reason why Timeout errors occur. Most delays are caused by payment processor issues, but some delays can be caused by modem issues, Internet connectivity issues, or configuration settings. The most typical causes for transaction delays are: PCCharge is attempting to process a transaction over the Internet, and the Internet connection or the payment processors TCP/IP interface is down or is running slow. PCCharge is attempting to process a transaction using a dial-up modem and the modem is unable to connect, the payment processors network is down, or the transaction is simply taking a long time to complete. PCCharge is attempting to process a transaction using a modem and the primary phone number is busy. PCCharge hangs up, pauses, and then dials the secondary number to receive an authorization. The Internet connection or the payment processors TCP/IP interface is down, and PCCharge attempts to process the transaction using a modem (Dial-Up Modem Backup). PCCharge has several transactions waiting in the queue during a busy period, thus delaying transaction processing. See the section Multi-User Support (see page 50) for more information on transaction queuing.

To determine how much time should be allotted to PCCharge to process transactions, the merchant should take into consideration all of the reasons why transaction delays would occur.

47

Dial-Up Modem Backup Settings

PCCharge provides a Dial-Up modem backup feature for many of the payment processors that support Internet connectivity. When activating this feature, it is important that the default value in the setting Internet Authorization Timeout Value (seconds) be reviewed. This setting is located in the Advanced settings of the processors extended data screen. This setting determines how long PCCharge will wait for an Internet transaction to complete prior to failing over to the modem to process the transaction. Because most Internet transactions take only a few seconds to complete, the default value of 60 seconds should be lowered. If not, a cashier would have to wait for at least a minute (or more) for each transaction to process. If using the Dial-Up Modem Backup feature, this settings value will need to be factored in when determining the integrated applications Timeout value.

Setting the Integrated Applications Timeout Value

To allow integrators to handle Timeouts properly, the various integration methods support a Timeout variable. If using the OCX, DLL, or OLE/COM Methods of integration, integrators may use the TimeOut property to set this variable. The default Timeout setting in each control and class is 90 seconds. If using the TCP Interface, integrators may use the TXN_TIMEOUT tag to set this variable. Note: There is no Timeout setting for the File Method. Integrators must build in their own support for timeouts when using the File Method (the TXN_TIMEOUT tag has no effect on transactions submitted via the File Method). When setting the Timeout value, several factors should be taken into consideration: 1. The maximum amount of time it would take to process a transaction: a. A typical transaction processed over the Internet takes about 3-5 seconds; a typical transaction that is processed using a modem averages about 25 seconds, but can take longer. b. If using a modem to process transactions, PCCharge will attempt to dial the secondary number if the primary number is busy. This can add 25 seconds or more to the transaction. c. If an Internet transaction fails, PCCharge will attempt to process the transaction using the modem if the Dial-Up Modem Backup feature is activated. The Internet Authorization Timeout Value (seconds) setting must be factored in as well as the dial time. (Again, if the primary phone number is busy, PCCharge will attempt to dial the secondary number.)

2. How long the merchant is willing to wait for a response after the maximum amount of time has elapsed. Setting the Timeout to a high number (90 seconds, for example) would typically take the above factors into consideration, thus lowering the number of Timeout errors that would occur. However, setting this value too high could cause problems. For example, if a payment processors network was down, cashiers would have to wait 90 seconds each time they submitted a transaction to receive an error response. Setting the Timeout to a low number (10 seconds, for example) would alleviate the cashier wait time, but a greater number of Timeout errors would occur. Most likely, none of the transactions that used the Dial-

48

Up Modem backup feature would register as approved in the integrated application. Cashiers would surely attempt to process the transaction again, thus double-charging a customers card. However, if Duplicate Transaction checking is enabled, the cashier would immediately receive a Duplicate Trans message. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. The best way to determine how many seconds should elapse before a Timeout error occurs is to test the integrated application thoroughly. Testing will help to determine the normal amount of time that it takes to process transactions.

Handling Timeouts
OCX, DLL, or OLE/COM
If using the OCX, DLL, or OLE/COM methods of integration, the Timeout countdown begins when the Send method is called. Once the number of seconds set in Timeout has elapsed, an error event will fire or a response with a Result of Error will be returned. An error code of 6 will also be set (this can be retrieved using the .GetErrorCode method) to indicate a Timeout error. Once a Timeout error occurs, it is suggested that the Cancel or Abort methods (if available) be called immediately to cancel the transaction. Because there is no guarantee that the Cancel or Abort methods will successfully cancel the transaction, it is suggested that a message be provided to the user of the integrated application that indicates a Timeout error has occurred. It is also suggested that the user review the PCCharge reports to determine whether the transaction was canceled properly or successfully processed. Note: If using the OLE/COM Method of integration, the Timeout value will only be used if the application is written to process transactions in an asynchronous manner. If programming synchronously, PCCharge will ignore the Timeout value and always use pre-set timeouts when processing transactions. Changing the Timeout value when programming in a synchronous manner will not work due to the internal workings of PCCharge.

TCP Interface
If using the TCP Interface and the TXN_TIMEOUT flag, the countdown begins once PCCharge receives the transaction request. Once the number of seconds set in TXN_TIMEOUT have elapsed, PCCharge will return a RESULT of NOT CAPTURED and an AUTH_CODE of Timeout and will attempt to cancel the transaction in progress. Because there is no guarantee that the transaction will be successfully canceled, it is suggested that a message be provided to the user of the integrated application that indicates a Timeout error has occurred. It is also suggested that the user review the PCCharge reports to determine whether the transaction was canceled properly or successfully processed.

File Method
Although a tag named TXN_TIMEOUT appears in the File Layout section of the File Method, this tag may only be used when processing transactions using the TCP Interface. The integrated application must provide its own Timeout handling.

49

Multi-User Support
Multi-user support can be defined as PCCharges ability to: Support multiple workstations or registers Handle simultaneous transaction requests

PCCharge is able to handle multiple workstations and simultaneous request through the use of Users. Users are unique PCCharge user names that must be purchased and configured in PCCharge by the merchant. Users must also be supported by the integrated application. The following describes how and why the Multi-User feature of PCCharge should be supported. Note: Both PCCharge Pro and PCCharge Payment Server support multiple users. All PCCharge integration methods support multiple users.

Support for Multiple Workstations

In order for a integrated client/server application to work properly with PCCharge, PCCharge and each of the integrated client stations must support and be configured to use unique PCCharge user names. In a typical client/server environment, PCCharge will be running on a Windows-based computer in a data center (or in the back office of a restaurant). Each employee or clerk (or waiter/waitress) that needs to process payments will typically have the integrated client running on their own workstation (or restaurant station). When a credit card, debit card, check, etc. is swiped (or keyed in), the integrated client will communicate to PCCharge over the LAN. In order for the integrated client and PCCharge to know which transaction response matches each workstation request, the integrated client must be uniquely identified by a user name. When coding to support this scenario, make sure that the user name property can be set for each integrated client by the end-user. Typically, this user name setting would appear in a setup menu or properties page provided in the client. When configuring each client station, the merchant should assign a unique user name to each client station (such as User1, User2, etc.). Once configured, this setting determines what is set in the User property of the Active X controls, OLE/COM classes, or TCP Interface. If using the File Method, the property will determine the name of the text file created by the client. In order to communicate to PCCharge using the user names that have been set up at each client station, each user name must be added in PCCharge. User names are added by utilizing the User settings screen in the PCCharge GUI. This screen can be accessed from the Setup | Users menu in PCCharge. Alternatively, the Unlimited User License can be added rather than adding individual user names see below for more information. Note: Do not rename the default user name (User1). PCCharge uses this user name for several internal functions.

Support for Simultaneous Transaction Requests

PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. However, PCCharge can be configured to handle multiple simultaneous transaction requests. Once configured to support multiple simultaneous transaction requests, PCCharge still only processes

50

these requests one at a time. PCCharge handles multiple requests through the use of queuing. The queuing feature of PCCharge processes the requests in a first in first out (FIFO) manner. Simultaneous transaction requests usually occur in the following environments: Client/Server (i.e., multiple terminals, cash registers, or workstations) eCommerce enabled web-sites Multi-threaded applications

Support for simultaneous transaction requests is very similar to multiple workstation support. In fact, once multiple workstation support has been configured (see above), the ability to submit simultaneous transaction requests is already supported. However, the use of multiple workstations is not necessarily required to support simultaneous transaction requests. To support simultaneous transaction requests, Multi-user support must be activated in PCCharge. At least two users or the Unlimited User License must be set up. When coding an application to send multiple requests, each request must have a unique user name. For example, User1, User2, etc. Again, PCCharge will queue up these transactions and will process them in the order that they are received. Keep in mind that no two transaction requests can be submitted at the same time with the same user name. To reuse the same user name, the integration must wait until the transaction has been processed completely by PCCharge, the client has received the response, and deleted the response file (except for the socket method, there is no response file). Only then can the user name be reused to send another transaction request.

Known Issue with Simultaneous Transaction Requests

PCCharge has a known issue with processing simultaneous transactions that have certain characteristics. Invalid TroutD errors may be returned when multiple transactions are submitted to PCCharge and have all the following characteristics: The transactions are submitted simultaneously. Specifically, multiple transaction requests are all submitted to PCCharge within 0.5 seconds (0.5 seconds is the default Queue Timer Interval setting in PCCharge. This is how often PCCharge polls for incoming transaction request files.) The transactions that are submitted use the same processing company but have different merchant accounts with different communication settings. For example, if TSYS will be used as the processing company, one transaction will use a TSYS merchant account that is set up to process via modem and another transaction will use a TSYS merchant account that is set up to process via the Internet. or Some transactions are processed by the processing company and others are processed via Split-dial directly to AMEX. For example, if Split-Dial is activated, a Visa credit card transaction will be processed by TSYS, and an American Express credit card transaction will be processed via Split-dial directly to American Express.

Again, keep in mind that all of the above characteristics must be met in order for this issue to occurand this error only occurs when submitting simultaneous transactions. Currently, the only workaround is to avoid submitting simultaneous transactions that have all of the above characteristics. If the error occurs, the transaction should be re-submitted.

51

The issue occurs because of the design of the queuing module in PCCharge. VeriFone, Inc. is currently working on updating the queuing module to handle simultaneous transaction requests properly. This update will be available in a future release of PCCharge.

Setting up Multi-user support

Each copy of PCCharge Payment Server and PCCharge Pro ships, by default, with a single user license activated. If the integration will be multi-threaded, will be used in a client/server environment, or will somehow send more than one transaction at a time to PCCharge, support for additional users or unlimited users is required. The integrator has the option to decide whether the application supports additional users or unlimited users or both. Note: Every single transaction that PCCharge processes has a user name assigned to it. If the transaction originates in the PCCharge GUI or is submitted through the file interface (the OCX, DLL, OLE/COM, or File Methods), the file name that is used is the PCCharge user name. If the transaction is sent through the TCP Interface, the <USER_ID> field assigns the user name to the transaction once the transaction has begun processing in PCCharge. Note: If using the File Method, the name of the file must match the <USER_ID> tag contained in the transaction request message.

Additional Users
Typically, merchants would add additional users if they have a static number (and usually a small amount) of workstations or client machines that will need to access PCCharge. For example, if a merchant had three cash registers or workstations, they would need to purchase two additional users (PCCharge already includes the first user license), and then set up the three registers or workstations with the three unique user names. Now, when the registers or workstations submit transactions, PCCharge can identify each register or workstation by its unique user name. Also, if transactions are sent from more than one register simultaneously, PCCharge can now queue these transactions. In essence, this merchant has enabled queuing and the queue can hold up to three transactions. Note: It is recommended that the PCCharge naming convention for users (User + X) be used when adding additional users. PCCharge ships by default with a single user named User1. When adding users, VeriFone, Inc., suggests that merchants use User2, User3, etc. It is not a requirement that this naming convention be followed, however, if there are problems in the future, using the default naming convention may decrease the amount of time needed on a technical support call. Regardless, all user names must be eight characters or less and can be alphanumeric, no spaces. Note: Do not rename the default user name (User1). PCCharge uses this user name for several internal functions. If additional users are not added to PCCharge and a client is set up to send transactions with a user name other than User1, the transactions will fail. Specifically, if any client attempts to process transactions with user names that do not appear in the PCCharge user screen, the transaction requests will be immediately rejected by PCCharge and the message "User Not Found" will be returned. If the integrated application will support additional users, merchants will need to purchase additional user licenses and activate them in PCCharge to take advantage of the Multi-user features of the application. Once purchased, additional user licenses may be activated by contacting VeriFone, Inc.s technical

52

support department or by submitting an additional user request via the Support section of VeriFone, Inc.s website: http://www.pccharge.com. For information on how to add additional users to PCCharge Pro or PCCharge Payment Server, see the product manuals for each product. For information on pricing, merchants my contact an authorized VeriFone, Inc. reseller or call 800-725-9264.

Unlimited User License

Typically, merchants would opt for an unlimited user license if they have a variable number and/or a large number of workstations or client machines that will need to access PCCharge. For example, if a merchant had twenty cash registers or workstations, it is recommended that they purchase and activate an Unlimited Users license. This would allow the merchant to set up as many registers or workstations as needed. The only requirement for Multi-User processing with an Unlimited User License is that all registers or workstations would need to be set up with unique user names. This allows PCCharge to identify each register or workstation by its unique user name. Also, if transactions are sent from more than one register simultaneously, PCCharge can now queue these transactions. In essence, this merchant has enabled queuing and the queue can hold an unlimited number of transactions. If the merchant needs to add registers or workstations in the future, there are no additional costs or configuration in PCCharge that would need to occur. The merchant would simply set up any new client machines with unique user names and begin processing. An example of an environment that would require Unlimited Users would be a real-time eCommerceenabled website. The Unlimited User License allows multiple customers to submit payments at the same time. Typically, real-time web applications would use a user naming scheme involving SessionIDs (a variable used by web servers). Note: Some developers prefer integrating to support only the Unlimited User License. This type of integration assumes that the Unlimited User License will be activated in PCCharge. The developer can programmatically create unique user names on the fly, thus simplifying the coding and configuration aspects of a client/server installation or multi-threaded application. Note: By adding the Unlimited User license to PCCharge, the restriction of the client applications user name having to match a user name set up in PCCharge is removed. Any valid alphanumeric eight character or less user name can be used by the client. However, each user name, when submitted must be uniqueit cannot be the same as another transactions user name. Once the transaction has been processed, however, the user name can be reused. If the integrated application will support unlimited users, merchants will need to purchase the unlimited user license and activate it in PCCharge to take advantage of the Multi-user features of the application. Once purchased, the unlimited user license may be activated by contacting VeriFone, Inc.s technical support department or by submitting an additional user request via the Support section of VeriFone, Inc.s website: http://www.pccharge.com/. For information on how to add additional users to PCCharge Pro or PCCharge Payment Server, see the product manuals for each product. For information on pricing, merchants my contact an authorized VeriFone, Inc. reseller or call 800-725-9264.

Limitations of PCCharges Multi-User Feature

Although there are no technical or programmatic limitations of how many users are supported or how many transactions can be processed by PCCharge, there are realistic limitations.

53

Because PCCharge is a single-threaded application, it can only process one transaction at a time. This could cause throughput issues if a large number of transactions are submitted simultaneously. In addition, if the merchant will be processing transactions via modem, or if PCCharge is used to connect via modem to multiple processors, delays can become severe. For example, if 50 transactions are submitted simultaneously to PCCharge (and PCCharge is configured to support that many simultaneous transactions), PCCharge will queue up all 50 transactions and process them one at a time. If the Internet will be used to connect to the processing company, processing will average about four seconds per transaction. In this scenario, it will take almost 3.5 minutes for PCCharge to process all of the transactions in real-time (meaning the client that submitted the 50th transaction will have to wait almost 3.5 minutes to get a response.) If a customer or clerk is waiting on the response, this amount of time may not be acceptable. Further, if PCCharge is required to dial different processors during this type of scenario, all of the dial and disconnect time would be factored in as well. This could greatly increase the amount of time it takes for the operation to complete. Aside from throughput issues, the way PCCharge stores transaction data should also be taken into consideration. PCCharge stores all transaction data in a Microsoft Access database. Access databases are designed for use in a single-user or small workgroup environment. Access can easily handle a moderate amount of workstations and several hundred transactions per day. But, because of the characteristics of Microsoft Access, PCCharge is not designed to be implemented in an enterprise environment. If PCCharge is expected to store thousands of transactions a day; reporting, archival, settlement, and other operations may become difficult to perform or may take a long time to complete.

Alternatives
If a single copy of PCCharge is being used to support many workstations (or even multiple store locations), consider implementing multiple copies of PCCharge. Adding additional copies of PCCharge to a location or simply installing a copy of PCCharge at each store may alleviate throughput and data storage issues. Only one copy of PCCharge should be installed on a single machine. Keep in mind that merchants will need to purchase additional copies of PCCharge and may incur additional expenses for supporting multiple merchant accounts in this type of scenario. Merchants should check with their processing company or merchant services provider for more information on additional merchant account fees. If using multiple copies of PCCharge is not an option, consider integrating and supporting RiTA Server or IPCharge. IPCharge is VeriFones new gateway product. The IPCharge DevKit is included with the PCCharge DevKit. RiTA Server is a scaleable, multi-threaded application that is designed to support high transaction volumes and unlimited merchant numbers and users. If the File Method or TCP Interface method is used for the PCCharge integration, integration to RiTA Server would be very similar.

54

Multi-trans Wait
Enabling the Multi-trans Wait feature allows PCCharge to attempt to keep the modem connected to the processor for a certain amount of time (usually a few seconds) after each transaction is processed. If PCCharge will communicate to the processing company via dial-up modem, the Multi-trans Wait feature of PCCharge can greatly increase throughput during busy periods or when performing batches of transactions. As long as transactions are submitted to PCCharge within a short period of time (or if transactions are currently queued in PCCharge), each transaction will be processed on the same call and will not require a re-dial to the processing company. If Multi-trans Wait is not supported by the processor, a call will need to be made to the processing company for each transaction that is submitted. Note: If the merchant will connect via the Internet to do payment processing, the Multi-trans Wait feature has no effect on processing. Although PCCharge supports Multi-trans Wait, whether or not this feature will actually hold the modem line open depends completely on the processing company. If the processor doesnt support Multi-trans Wait, the processor will send a hang up command to PCCharge after each transaction. Also, the length of time that the call will stay connected also depends on the processing company. The length of time can range from half a second to twenty seconds or more. Some processors support Multi-trans by default. If Multi-trans does not appear to be working after the Multi-trans Wait setting has been enabled in PCCharge, the merchant should contact their processing company or merchant services provider to request that the feature be activated for their merchant account(s). In some cases, merchants can also request how long the call will stay connected after each transaction. By default, Multi-trans Wait is disabled in PCCharge. This feature can be enabled in two ways: 1) Through the GUI: The merchant should check the Multi-trans Wait option in the GUI of PCCharge Payment Server or PCCharge Pro (Setup | Configure System | Advanced). 2) Through the API: To enable this feature programmatically, set the "Multi" property of the OCX, DLL, or OLE/COM methods or the MULTI_FLAG property in the File Method or TCP Interface to "1" when submitting a transaction. If this setting is sent programmatically, it will override the GUIs Multi-trans Wait setting.

55

Multi-Merchant Support
PCCharge is designed to handle multiple merchant accounts. Each PCCharge product (PCCharge Pro and PCCharge Payment Server) includes a license for a single merchant account. In order for merchants to use more than one merchant account in PCCharge, they must first purchase and then activate additional merchant accounts.

Multi-Merchant Integration
In order for an integrated application to support multiple merchant accounts, the integrated application must provide the end-user the ability to choose which merchant account will be used to process transactions and allow this information to be passed to PCCharge. This can be accomplished by providing a setup option that allows the end-user to specify their merchant account information and then populating the proper properties or XML tags with that information. The merchants account information is defined as the merchant account number and a valid processor code. For example, assume an end-user has three merchant accounts set up in PCCharge. Two of the merchant accounts are with FDMS South (NB): 67888882701 & 67888882702, and the other merchant account is with Chase Paymentech (GSAR): 999999999999519. In order for the end-user to designate which merchant account should be used to process the transaction, the end-user must have a way to indicate to the integrated application to send the proper merchant account number and the processor code to PCCharge. In this example, if the merchant will use the second FDMS South merchant account to process the transaction, the integration must send the 67888882702 account number and the NB processor code to PCCharge. To pass the account number and processor code using the OCX, DLL, or OLE/COM Methods of integration, use the MerchantNumber and Processor properties. To pass the account number and processor code using the File Methods or TCP Interface, use the <PROCESSOR_ID> and <MERCH_NUM> tags. Note: Choosing the processor code will be easier (and less error-prone) for the end-user if the integrated application provides a list that allows the end-user to choose their processor code rather than requiring them to type it in. A list of valid processor codes is located in the section DevKit Constants (see page 94). Also, the processor drop-down lists found in the various setup screens in PCCharge serve as accurate lists of the available processor codes.

GetMerchantInfo Method
The OCX, DLL, and OLE/COM Methods of integration provide a method named GetMerchantInfo. This method is located in Charge.OCX, in the Batch class of PSCharge.dll, and in the PccConfig OLE/COM class. This method provides the integrated application with a string that includes a list of merchant numbers and processor codes that are currently set up in PCCharge. In addition, it will also return a character indicating if the processor is Host or Terminal based. Specifically, this method accesses the tid.pcc file that resides in the PCCharge directory, and will return all merchant accounts, processor codes, and terminal/host indicators that are set up in the file. The following is an example of a string that will be returned if three merchant numbers are set up in PCCharge:
<STX>CES <FS>000000927996296767<FS>T<GS>GSAR<FS>999999999999519<FS>T<GS>VISA <FS>999999999911<FS>T<ETX>

Once retrieving this information at run-time, the integrated application could then display a user-friendly list of all of the merchant accounts that are set up in PCCharge. The end-user could then choose the proper merchant account from the list. This list would eliminate the need for an end-user to key in merchant account numbers and would reduce errors caused by typos.

56

OCX / DLL Method Note: PCCharge does not have to be running in order for the GetMerchantInfo method to return the string. However, a valid Path variable must be set prior to calling the GetMerchantInfo method.

Use Default Processor

Many merchants that use PCCharge require only a single merchant account. If only a single merchant account will be set up in PCCharge, integrators should consider supporting the Use Default Processor option. Enabling this option in PCCharge allows the integrator to omit the merchant number and processor code from transaction requests. If the option is enabled and the merchant number and processor code are omitted, PCCharge will automatically use the active merchant account set up in PCCharge to process the transaction. The Use Default Processor option is available in the PCCharge Configure System setup screen. This option is disabled by default.

57

Follow On Transactions
Overview
When integrating to PCCharge, developers must make a decision on whether or not to support follow on transactions in their application. While a few integrators decide to support only basic transactions such as Sales or Pre-Authorizations in their application, most integrators choose to support the majority of available follow on transactions, such as Voids, Post-Authorizations, and Gratuities. PCCharge requires that follow on transaction requests include the TroutD (Transaction ROUTing ID) from the original Sale or Pre-Authorization when they are submitted. The TroutD is a PCCharge-assigned unique number associated with a single transaction--or, in the case of follow on transactions, a TroutD can be associated with an interrelated series of transactions. For simplicity, PCCharge usually requires that only the TroutD of the original Sale or Pre-Authorization transaction and the action code be set in order to perform follow on transactions. The TroutD enables PCCharge to pull all needed information (merchant number, card number, expiration date, auth code, etc.) from the transaction record in the PCCharge database in order to submit the follow on transaction. In some cases, additional values may be sent with the follow on transaction. For example, if performing a Post-Authorization for a different amount than the original Pre-Authorization, the different amount may be sent in with the Post-Authorization. Note: Support for TroutD follow on transactions was added starting with PCCharge version 5.6. Follow on transaction support is available in all integration methods.

58

Examples
The following examples show common uses for follow on transactions:

File Method / TCP Interface Examples:

This example demonstrates performing a Void on a Sale using the File Method or TCP Interface. Refer to the section File Method (see page 409) for more information on the File Method or TCP Interface API. 1. A Sale transaction is processed and PCCharge assigns a unique TroutD number (1024) to it. Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>1</COMMAND> <PROCESSOR_ID>VISA</PROCESSOR_ID> <MERCH_NUM>999999999911</MERCH_NUM> <ACCT_NUM>5424180279791765</ACCT_NUM> <EXP_DATE>1208</EXP_DATE> <MANUAL_FLAG>0</MANUAL_FLAG> <TRANS_AMOUNT>10.00</TRANS_AMOUNT> </XML_REQUEST> </XML_FILE>

Response:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <TROUTD>1024</TROUTD> <RESULT>CAPTURED</RESULT> <AUTH_CODE>124954</AUTH_CODE> <TRANS_DATE>1231</TRANS_DATE> <INTRN_SEQ_NUM>1024</INTRN_SEQ_NUM> <TRANS_ID>0412MCC364698</TRANS_ID> <RET>A014</RET> <ACI>P</ACI> </XML_REQUEST> </XML_FILE>

59

2. Later, a second Sale transaction is processed and PCCharge assigns a unique TroutD number (1025) to it. Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>1</COMMAND> <PROCESSOR_ID>VISA</PROCESSOR_ID> <MERCH_NUM>999999999911</MERCH_NUM> <ACCT_NUM>5424180279791765</ACCT_NUM> <EXP_DATE>1208</EXP_DATE> <MANUAL_FLAG>0</MANUAL_FLAG> <TRANS_AMOUNT>11.00</TRANS_AMOUNT> </XML_REQUEST> </XML_FILE>

Response:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <TROUTD>1025</TROUTD> <RESULT>CAPTURED</RESULT> <AUTH_CODE>124956</AUTH_CODE> <TRANS_DATE>1231</TRANS_DATE> <INTRN_SEQ_NUM>1025</INTRN_SEQ_NUM> <TRANS_ID>0412MCC729964</TRANS_ID> <RET>A014</RET> <ACI>P</ACI> </XML_REQUEST> </XML_FILE>

3. The merchant decides to process a Void transaction on the first Sale transaction. To Void the transaction, the integrated application sends the action code for a Void transaction (action code 3) and the TroutD number of the transaction to be voided (1024, in this example). Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>3</COMMAND> <TROUTD>1024</TROUTD> </XML_REQUEST> </XML_FILE>

Response:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <TROUTD>1024</TROUTD> <RESULT>VOIDED</RESULT> <INTRN_SEQ_NUM>1026</INTRN_SEQ_NUM> <PURCH_CARD_TYPE>0</PURCH_CARD_TYPE> </XML_REQUEST> </XML_FILE>

4. PCCharge does not need any additional information to process the Void. Of course, if a follow on transaction will be performed that modifies some aspect of the original transaction (such as a Post-Authorization whose amount is less than the original Pre-Authorization), that information would need to be sent to PCCharge in addition to the action code and TroutD.

60

File Method / TCP Interface Restaurant Example:

Assume the merchant above is operating in a restaurant environment. This merchant still has one transaction left in the batch. Now, the merchant wishes to modify the second Sale transaction by adding a gratuity to it. (Note: The processor used must support restaurant transactions in order to add gratuities) 1. To add the gratuity to the second transaction, the application sends the action code for a Gratuity transaction (action code 13), the TroutD of the Sale transaction (1025, in this example), and the gratuity amount in the <GRATUITY_AMNT> tag ($2.51, in this example). Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>13</COMMAND> <TROUTD>1025</TROUTD> <GRATUITY_AMNT>2.51</GRATUITY_AMNT> </XML_REQUEST> </XML_FILE>

Response:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <TROUTD>1025</TROUTD> <RESULT>GRATUITY ADDED</RESULT> <AVS_CODE>0</AVS_CODE> <INTRN_SEQ_NUM>1027</INTRN_SEQ_NUM> <ACI>N</ACI> <CMRCL_TYPE>0</CMRCL_TYPE> <PURCH_CARD_TYPE>0</PURCH_CARD_TYPE> <CARD_ID_CODE>N</CARD_ID_CODE> <ACCT_DATA_SRC>T</ACCT_DATA_SRC> </XML_REQUEST> </XML_FILE>

2. If, prior to settlement, the merchant wishes to adjust the gratuity amount of this transaction for some reason, the same information (Action code 13, TroutD 1025) for the transaction can be sent in with the new gratuity amount ($3.51, in this example). Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>13</COMMAND> <TROUTD>1025</TROUTD> <GRATUITY_AMNT>3.51</GRATUITY_AMNT> </XML_REQUEST> </XML_FILE>

The gratuity amount has been adjusted.

61

Implementing Follow On Transactions

In order to allow an integrated application to process follow on transactions effectively, it is recommended that the application: 1) Store the TroutD value 2) Store the status of the transaction: a. Whether it has been voided b. Whether it has been post-authorized c. Whether the gratuity has been added d. Whether it has been settled (and is not eligible for further follow on transactions) The TroutD for each transaction can be retrieved either from the <TroutD> tag of the response (in the File or TCP Methods) or by using the GetTroutD method (available in the OCX, DLL, or OLE/COM methods). Once this information is available to the application, lists or menu options should be provided by the application that allow merchants to perform follow on transactions easily. Alternatively, the merchant can be instructed to view the PCCharge detail reports to acquire TroutD values and manually enter them in a screen provided by the application or even into the PCCharge GUI. The following is a list of credit card transactions that can be processed using TroutD follow on support: Credit Card Transactions: Void Sale Post-Authorization (amount is optional) Void Credit Void Post-Authorization Procurement Card Post-Authorization (amount is optional, tax and customer code should be passed for lowest rates). Note: Global East (NDC), terminal based, requires the customer code be all upper case. Gratuity (gratuity amount is required) Void Book

62

Non-TroutD Post-Authorizations
Post-Authorizations
In some cases, non-TroutD Post-Authorizations may need to occur. Specifically, if the merchant has called the processors voice authorization center to receive an authorization code, the merchant will need to be able to manually enter the entire transaction as a Post-Authorization (action code 5). In this case, all fields that would typically be used for a standard Sale or Pre-Authorization should be entered plus the authorization code that the merchant received from the voice operator. Once this transaction is submitted to PCCharge, the transaction will be placed into the open batch. Note: Voice-Authorizations will not qualify for the most favorable rates. The processors VoiceAuthorization system should be used only when absolutely necessary. The following is an example of a Post-Authorization used to add a Voice-Authorization to the open batch: Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>5</COMMAND> <PROCESSOR_ID>VISA</PROCESSOR_ID> <MERCH_NUM>999999999911</MERCH_NUM> <ACCT_NUM>5424180279791765</ACCT_NUM> <EXP_DATE>1208</EXP_DATE> <MANUAL_FLAG>0</MANUAL_FLAG> <TRANS_AMOUNT>6.00</TRANS_AMOUNT> <REFERENCE>123456</REFERENCE> <TICKET_NUM>999999999</TICKET_NUM> <CARDHOLDER>VERIFONE TEST 1</CARDHOLDER> <TOTAL_AUTH>6.00</TOTAL_AUTH> <AUTH_CODE>123456</AUTH_CODE> </XML_REQUEST> </XML_FILE>

Response:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <TROUTD>1078</TROUTD> <RESULT>PROCESSED</RESULT> <AUTH_CODE>123456</AUTH_CODE> <TICKET>999999999</TICKET> <INTRN_SEQ_NUM>1078</INTRN_SEQ_NUM> <CMRCL_TYPE>0</CMRCL_TYPE> <PURCH_CARD_TYPE>0</PURCH_CARD_TYPE> <AUTH_SRC_CODE>E</AUTH_SRC_CODE> <CARD_ID_CODE>N</CARD_ID_CODE> <ACCT_DATA_SRC>@</ACCT_DATA_SRC> </XML_REQUEST> </XML_FILE>

Notice that the AVS data (the street and zip code) and Card Verification data (CVC2) were omitted in this Post-Authorization. It is not necessary to pass this information because the transaction has already been authorized. Note: If a post-authorization is sent with a TroutD and an authorization code, PCCharge will reject the transaction with an error of "Invalid TroutD or Auth Code". The format above for a voice-authorization must be followed if an authorization code is sent.

63

Note: When using the processor National Bankcard Services (NBS), Voice-Authorizations are not supported for Fuelman or Fleet One cards, an error will be returned. The transaction should be submitted as a standard Post-Authorization.

Stored Voice-Authorizations
Another type of Non-TroutD Post-Authorization is a Stored Voice-Authorization. This type of transaction is similar to a Post-Authorization except that a stored Voice-Authorization is not added to the open batch. Instead, it essentially becomes a Pre-Authorization. A second transaction, a TroutD Post-Authorization, must be submitted to add the Stored Voice-Authorization to the batch. A Stored Voice-Authorization would be useful in a MOTO environment if an authorization was received from a voice operator the day a product was ordered, and product was not scheduled to ship until a few days later. The Stored VoiceAuthorization would be processed the day the product was ordered, and the TroutD Post-Authorization would be processed the day that the product shipped. To submit a stored Voice-Authorization, use action code 5, and set the Store or TRANS_STORE flag. The following is an example of a Stored VoiceAuthorization: Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>5</COMMAND> <PROCESSOR_ID>VISA</PROCESSOR_ID> <MERCH_NUM>999999999911</MERCH_NUM> <ACCT_NUM>5424180279791765</ACCT_NUM> <EXP_DATE>1208</EXP_DATE> <MANUAL_FLAG>0</MANUAL_FLAG> <TRANS_AMOUNT>7.00</TRANS_AMOUNT> <REFERENCE>987654</REFERENCE> <TICKET_NUM>123456789</TICKET_NUM> <CARDHOLDER>VERIFONE TEST 1</CARDHOLDER> <TOTAL_AUTH>7.00</TOTAL_AUTH> <TRANS_STORE>1</TRANS_STORE> <AUTH_CODE>987654</AUTH_CODE> </XML_REQUEST> </XML_FILE>

Note: Only some processors support stored Voice-Authorizations. If the processor does not support stored Voice-Authorizations, an error will be returned. The transaction should be submitted as a standard Post-Authorization.

64

Commercial Card Transactions

Overview
A Commercial Card transaction is defined as any credit card transaction that requires the customer code and the tax amount of the transaction to be submitted. This information, commonly known as Level II data, is submitted for the customers records and is required for the merchant to qualify for the lowest transaction rates. In general, if a customer is using one of the following types of credit cards, Level II data must be submitted: Commercial Cards Government Cards Purchasing Cards Procurement Cards Fleet Cards

If the end-user of an integrated application will accept Commercial Cards, the integrated application must be able to support the action codes and Level II data required to process Commercial Card transactions. Treating a Commercial Card transaction as a standard credit card transaction will cause the transaction to downgrade, thus increasing the fees the merchant must pay. Note: Some processors do not support Level II data. A list of processors and what features they support can be found on VeriFone, Inc.s website (http://www.pccharge.com/). Click Developers and then PCCharge Certified Processors to view the list. The column labeled P-Card II indicates which processors support Level II data.

Supporting Commercial Card Transactions

The key to supporting Commercial Card transactions is the ability to identify a Commercial Card and then prompt for the Level II data. The first six digits of each credit card account number is called the Bank Identification Number (BIN) and the next three digits determine the card type. These first nine digits of credit card account numbers allow merchants to identify what type of credit card is being used. A database that includes valid Commercial Card BIN ranges is installed with each of copy of PCCharge. This database is named Bin.mdb and is installed automatically in the PCCharge directory. If the first nine digits of the credit card being submitted is within one of the ranges included in Bin.mdb, the integrated application should then prompt for Level II data.

Using Bin.mdb
OCX or DLL Method
If using the OCX or DLL Methods of integration, the Charge.OCX and the PSCharge.dll Charge class provide two methods that can be used to access the Commercial Card information contained in the Bin.mdb database. The first method, CommercialCardType, is used to determine if a credit card is a commercial card. To use this method, set the Path variable, and then pass the credit card number as a parameter to the method. The method will return TRUE if the card is a Commercial Card, FALSE if it is not. For example:

65

If .CommercialCardType(Account Number) Then Prompt for Level II data Else Do not Prompt for Level II data End If The second method, GetCommercialCardType, is used to determine the Commercial Card type. To use this method, set the Path variable, and then pass the credit card number as a parameter to the method. This method will return a character that indicates the Commercial Card Type. For example: CommercialCardTypeChar = .getCommercialCardType(Account Number)

OLE/COM Method
If using the OLE/COM Method of integration, the PccBin class provides two functions that can be used to determine if a credit card is a commercial card and what type of commercial card it is. The first function, CommercialCard, is a Boolean function that is used to determine if a credit card is a commercial card. To use this function, pass the credit card number as a parameter. This function will return TRUE if the card is a Commercial Card, FALSE if it is not. For example: If .CommercialCard(Account Number) then Prompt for Level II data Else Do not Prompt for Level II data End If The second function, CommercialCardType, is used to determine the Commercial Card type. The function does not require any parameters and must called after the CommercialCard function has been used. This function returns the commercial card type for the credit card number that was submitted via the CommercialCard function. This function will return a character that indicates the Commercial Card Type. For example: CommercialCardTypeChar = .CommercialCardType

File Method or TCP Interface

If using the File Method or TCP Interface, integrated applications must access the Bin.mdb database directly. The following code sample is a Visual Basic 6 function that checks if a credit card account number falls into one of the Commercial Card BIN ranges in the Bin.mdb database. Note: This code sample assumes that a reference to the "Microsoft DAO 2.5/3.51 Compatibility Library" has been set in the project. Public Function CommercialCard (CreditCard As String) As Boolean Returns true if the credit card account numbers BIN falls within a valid commercial card BIN range, else, returns false. Dim dbBin As Database Dim rsRange As Recordset Dim CCBIN, strQuery As String

66

CCBIN = Left(CreditCard, 9) The Credit Card BIN is the first 9 digits of the account number Set dbBin = OpenDatabase(C:\Program Files\Pccw\Bin.mdb") strQuery = "SELECT * FROM BIN WHERE LowRange <= " & CCBIN & _ " AND HighRange >= " & CCBIN Set rsRange = dbBin.OpenRecordset(strQuery) If Not rsRange.EOF Then if the account number BIN was found in the database, return True CommercialCard = True Also, to determine the Commercial Card type, use the following command to check the Type column: rsRange("Type").Value End If End Function

Submitting Commercial Card Transactions

Once it has been determined that the credit card is a Commercial Card, the integrated application should perform the following steps: 1. Prompt for Level II data from the end-user and/or customer. 2. Create the Commercial Card transaction request. Pass the following values in the transaction request (refer to CHAPTER 6 -- PCCharge Integration Methods (see page 104) for information on the properties or tags that are used to pass the data): a. The request should contain all of the standard credit card Sale, Credit, or PostAuthorization values (card number, expiration date, amount, etc.) b. The request should contain Level II data (customer code and tax amount). The request should also indicate if the purchase is tax exempt (if applicable). The request should also include the Destination Zip Code if processing an American Express card and using American Express as your processor or via split dial. Note: Global East (NDC), terminal based, requires the customer code be all upper case. c. The request should contain the Commercial Card Flag character. (This is the character returned by the various methods above and is the character that appears in the Type column of the Bin.mdb database) d. Make certain that the request uses the proper Commercial Card action code. Valid Commercial Card codes are 8, 9, and 10. See the section DevKit Constants section (see page 94) for more information 3. Submit the transaction to PCCharge.

67

Example
The following is an example of a Commercial Card Sale using the File Method or TCP Interface. Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>8</COMMAND> <PROCESSOR_ID>VISA</PROCESSOR_ID> <MERCH_NUM>999999999911</MERCH_NUM> <ACCT_NUM>4055011111111111</ACCT_NUM> <EXP_DATE>1208</EXP_DATE> <MANUAL_FLAG>1</MANUAL_FLAG> <TRANS_AMOUNT>5.30</TRANS_AMOUNT> <TRACK_DATA>4055011111111111=08121011000001234567</TRACK_DATA> <CUSTOMER_CODE>02</CUSTOMER_CODE> <TAX_AMOUNT>0.30</TAX_AMOUNT> <TICKET_NUM>123456789</TICKET_NUM> <CARDHOLDER>John Doe</CARDHOLDER> <CMRCL_FLAG>P</CMRCL_FLAG> <TAX_EXEMPT>0</TAX_EXEMPT> </XML_REQUEST> </XML_FILE>

Response:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <TROUTD>1138</TROUTD> <RESULT>CAPTURED</RESULT> <AUTH_CODE>TSYS 4</AUTH_CODE> <REFERENCE>411921002550</REFERENCE> <AVS_CODE>0</AVS_CODE> <TRANS_DATE>042804</TRANS_DATE> <TICKET>123456789</TICKET> <INTRN_SEQ_NUM>1138</INTRN_SEQ_NUM> <TRANS_ID>000000000009548</TRANS_ID> <MSI>E</MSI> <PEM>5</PEM> <TIM>173952</TIM> <ACI>E</ACI> <PROC_RESP_CODE>00</PROC_RESP_CODE> <CMRCL_TYPE>0</CMRCL_TYPE> <PURCH_CARD_TYPE>0</PURCH_CARD_TYPE> <CARD_ID_CODE>@</CARD_ID_CODE> <ACCT_DATA_SRC>D</ACCT_DATA_SRC> </XML_REQUEST> </XML_FILE>

68

Restaurant Transactions
Overview
Integrating PCCharge into a restaurant point-of-sale system is similar to integrating PCCharge into any other type of retail point-of-sale system. Once Restaurant is selected as the business type in the processor's extended data fields, PCCharge will be able to send "restaurant certified" transactions to the processor. Note: Some processors do not support restaurant transactions. A list of processors and what features they support can be found on VeriFone, Inc.s website (http://www.pccharge.com/). Click Support and then PCCharge DevKit and then PCCharge Certified Processing Companies to view the list. The column labeled Restaurant indicates which processors support restaurant transactions.

Benefits of XML
Starting with PCCharge version 5.6.0, the PCCharge products were updated to support restaurant integration using the XML message format. If an existing integration was written using the INP message format, it is highly recommended that the integration be updated to use the XML message format. Problems may occur with reports and when adding gratuities when using the INP message formatthese problems have been resolved with the XML message format. In addition, the XML message format supports gratuity adjustments, the INP message format does not.

o The INP message format will eventually be phased out.

Note: The XML message format is available in all five integration methods. To activate the XML message format when using the OCX, DLL, or OLE/COM methods of integration, use the parameter 3 when calling the Send method. For example: OCX / DLL: .Send 3 OLE/COM: .Send , 3

Integration
To properly send restaurant transactions from an integrated application to PCCharge, restaurant transactions should basically be treated as standard retail transactions. In addition, include the following information in restaurant transaction requests: Estimated gratuity This amount may be sent with a Sale (action code 1) or a Pre-Authorization (action code 4) transaction. The amount that PCCharge sends to the processor for authorization is the sale amount + the estimated gratuity. Sending the estimated gratuity helps to assure that the customer has enough available credit to leave a tip. The amount that is recorded for settlement by PCCharge (or the processor, if Host based) is the sale amount only. 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. Gratuity Sending the gratuity is the second step of a restaurant transaction. If the original transaction was a Sale, send the gratuity amount in a gratuity transaction (action code 13). A Gratuity transaction adds the actual gratuity to the amount recorded for settlement. If the original transaction was a Pre-Authorization, a Post-Authorization (action code 5) should be used to complete the Pre-

69

Authorization. This completion records the sale amount plus the gratuity for settlement. A Sale with Gratuity (action code 14) transaction authorizes and records the sale amount plus gratuity in one step. A Gratuity transaction (action code 13) may also be used to adjust an existing gratuity prior to settlement. Server ID -- This value should be sent with all restaurant Sale (action code 1), Pre-Authorization (action code 4), or Sale with Gratuity (action code 14) transactions. This two digit ID is stored in the transaction record and is used in PCCharges gratuity reports to determine the amount of Gratuity each server has received. This value is required by some processors. To force entry of this value for each transaction, the Require Server ID box should be checked in the processor's extended data fields in PCCharge. Use the MSCN tag or property to pass the Server ID.

Examples
The following are examples, using the File Method or TCP Interface, that show common transactions used in a restaurant environment. For more information on the File Method of integration, refer to the section File Method (see page 409).

Restaurant Sale
The following is an example of a restaurant sale for $6.00 with an estimated gratuity of $0.85. The total amount that will be authorized is $6.85. However, only $6.00 will be added to the settlement file. A gratuity transaction must be submitted later to finalize (add the actual gratuity amount to) this transaction. Note about estimated gratuity: 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. Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>1</COMMAND> <PROCESSOR_ID>GSAR</PROCESSOR_ID> <MERCH_NUM>999999999999519</MERCH_NUM> <ACCT_NUM>4012000033330026</ACCT_NUM> <EXP_DATE>1208</EXP_DATE> <MANUAL_FLAG>1</MANUAL_FLAG> <TRANS_AMOUNT>6.00</TRANS_AMOUNT> <TRACK_DATA>4012000033330026=08121011000001234567</TRACK_DATA> <TICKET_NUM>9999</TICKET_NUM> <CARDHOLDER>VERIFONE TEST 3</CARDHOLDER> <MCSN>02</MCSN> <PRESENT_FLAG>1</PRESENT_FLAG> <GRATUITY_AMNT_EST>0.85</GRATUITY_AMNT_EST> </XML_REQUEST> </XML_FILE>

Response:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <TROUTD>1102</TROUTD> <RESULT>CAPTURED</RESULT> <AUTH_CODE>096899</AUTH_CODE> <REFERENCE>00000000</REFERENCE> <TRANS_DATE>0404</TRANS_DATE> <TICKET>9999</TICKET> <INTRN_SEQ_NUM>1102</INTRN_SEQ_NUM>

70

<PURCH_CARD_TYPE>0</PURCH_CARD_TYPE> </XML_REQUEST> </XML_FILE>

Because the Sale transaction was successful, the Restaurant Point-of-Sale should store the TroutD value (1102 for this transaction) to enable the server to add the gratuity.

71

Gratuity
The following is an example of a Gratuity Transaction used to finalize a sale. In this example, the Gratuity transaction is finalizing the Restaurant sale from above. To finalize the Sale, pass the Gratuity action code (13), the TroutD from the original Sale (1102 for this transaction), and the actual Gratuity amount ($1.00 for this transaction). A Result of GRATUITY ADDED indicates the gratuity was successfully added to the Sale. Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>13</COMMAND> <TROUTD>1102</TROUTD> <GRATUITY_AMNT>1.00</GRATUITY_AMNT> </XML_REQUEST> </XML_FILE>

Response:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <TROUTD>1102</TROUTD> <RESULT>GRATUITY ADDED</RESULT> <TRANS_DATE>0404</TRANS_DATE> <INTRN_SEQ_NUM>1103</INTRN_SEQ_NUM> <PURCH_CARD_TYPE>0</PURCH_CARD_TYPE> </XML_REQUEST> </XML_FILE>

Gratuity Adjustment
A gratuity adjustment is defined as a transaction that modifies a gratuity that has already been processed. Typically, a gratuity adjustment would be used to correct order-entry errors. The syntax for a gratuity adjustment is exactly the same as a gratuity. Simply pass in the Gratuity action code (13), the TroutD from the original Sale (1102 for this transaction), and the new Gratuity amount ($2.00 for this transaction). Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>13</COMMAND> <TROUTD>1102</TROUTD> <GRATUITY_AMNT>2.00</GRATUITY_AMNT> </XML_REQUEST> </XML_FILE>

Response:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <TROUTD>1102</TROUTD> <RESULT>GRATUITY ADDED</RESULT> <TRANS_DATE>0404</TRANS_DATE> <INTRN_SEQ_NUM>1109</INTRN_SEQ_NUM> <PURCH_CARD_TYPE>0</PURCH_CARD_TYPE> </XML_REQUEST> </XML_FILE>

72

Processor Specific Notes

The processors Global Payments East (NDC) and FDMS South (NB) have unique restrictions related to gratuity based transactions. These two processors will not allow the actual total sale plus gratuity amount to exceed 120% of the originally authorized total sale plus gratuity amount. Example: 1. The customers bill is $10.00. The server estimates the gratuity will be $1.00 (10%). The restaurant application will then submit a Sale transaction (action code 1) with the amount of $10.00 and the estimated gratuity of $1.00. Therefore, PCCharge will request an authorization for $11.00. This authorization is approved by the processor. 2. After the meal has concluded, the customer decides to leave a gratuity of $5.00 This gratuity amount would result in a total amount of $15.00, which is greater than 120% of the originally authorized total of $11.00. The merchant could not, in this situation, add the gratuity by performing a Gratuity transaction. 3. Instead, the server will need to perform a Void Sale (action code 3) on the original transaction, and then enter a Sale with Gratuity (action code 14) with the amount of $10.00 and a gratuity amount of $5.00.

73

Gift Card Transactions

This section details the various action codes and transaction types that are applicable for each Gift Card processor. Although several of the transaction types are similar among all Gift Card processors (such as Balance or Redemption transactions), most Gift Card processors support very unique transaction types. It is recommended that the developer review the various screens in the PCCharge GUI to determine what values should be set for each transaction type. Also, many Gift Card processors also recommend that developers contact them directly to discuss the usage and integration of their services. Note: VeriFone, Inc. does not provide test merchant accounts for any of the Gift Card processors. Developers should contact the various Gift Card processors directly to request test merchant accounts.

Givex (GVEX)
18 Balance 25 Redemption 26 Register 27 Increment 28 Activate 29 Cancel 0Q Adjustment (amount may be either positive or negative) 0N Points

Valuetec (VTEC)
18 Balance 25 Redemption (Loyalty) / Sale (Non-Loyalty) 26 Replace 27 Purchase (Loyalty) / Add Value (Non-Loyalty) 28 Activation 29 Void 0A Deactivate 0C Current Day Totals 0D Previous Day Totals

ValueLink (VLNK)
18 Balance 28 Activate 25 Redemption 27 Reload 29 Void 0H (Restaurant OR E-Commerce) with Simulate Pre-Auth Set up: Balance with Lock 0I (Restaurant OR E-Commerce) with Simulate Pre-Auth Set up: Redemption Unlock 0P Balance Merge 0Q Balance Adjustment 0R Balance Transfer 0S Report Lost/Stolen 0T Cash Out

74

Chase Paymentech (GSAR)

18 Balance Inquiry 25 Redemption & Prior Redemption 27 Issuance/Add Value 29 Void 0A Deactivate 0E Reactivate

World (WRLD)
18 Balance 25 Sale 27 Add Value 28 Activate 0N Redeem Points

Fifth-Third Bank-St Pete (BPS)

18 Balance 25 Redemption 27 Reload 28 Activate 29 Void 0A Close 0B Refund 0Q Unload 0V Pre-Auth 0I Post-Auth

RBS Lynk (LYNK)

18 Balance 25 Redemption 27 Add Value 29 Void Add value

Datamark Gift Card (DMRK)

18 Balance Inquiry 25 Redemption & Prior Redemption 27 Issuance/Add Value 29 Void 0A Deactivate 0E Reactivate

Smart Transaction Systems (SMTS)

18 Balance Inquiry 25 Redemption 27 Add Value 28 Activation 29 Void

75

0B Credit 0C Totals Inquiry (Current only) 0N Redeem Points 0R Balance Transfer 0U Add Tip

Secure Payment Systems (SPS)

18 Balance Inquiry 25 Redemption 27 Add Value (non-Loyalty only) 28 Activation 29 Void 0B Credit 0C Totals Inquiry 0R Balance Transfer

Stored Value Systems (SVSI)

18 Balance Inquiry 25 Redemption 27 Issuance 28 Activation 29 Void 0B Refund 0I Post-Auth 0Q Recharge 0T Cash Out 0U Tip 0V Pre-Auth

VeriFone Stored Value API (GAPI)

The VeriFone Stored Value API (GAPI) is a proprietary specification that allows for stored value card processors to add themselves to PCCharge. Applications using GAPI can also integrate with PCCharge using the various integration methods. For more information on adding a stored value card processor to PCCharge, and how to obtain the VeriFone Stored Value API, please contact VeriFone sales at 1-800725-9264.

76

Pre-Paid Credit Card Transactions

Pre-paid credit cards are similar to regular credit cards, the only difference is that they carry a fixed amount. PCCharge supports Visa, MasterCard, American Express and Discover pre-paid card types (with the processor NOVA only). Additional support for other processors will be added in future releases. The main action codes for pre-paid credit card transactions are: P1 - Balance Inquiry P2 - Partial Authorization Reversal Regular Credit card action codes can be used. P1: Used to determine the balance available in a pre-paid credit card. P2: This transaction format is used to submit a POS generated Reversal message for a previously approved Partial Authorization Credit Card transaction. This transaction type is only supported for the Visa, MasterCard and Discover card types and will return SERV NOT ALLOWED for any other transaction. This transaction type is not supported for any PIN Based Debit card transactions. Note: Reversals are not available for American Express pre-paid credit cards.

77

Canadian (Interac) Debit Transactions

Overview
Starting with PCCharge 5.7, the integration of Canadian (Interac) debit transactions is supported when using Global Payments East (NDC) as the processing company and the VeriFone SC5000 PINpad. Canadian debit transactions are also supported when using the processing company Chase Paymentech (GSAR) and the VeriFone SC5000 PINpad. Specifically, the use of these processors and PINpad allows merchants to process transactions for customers using Interac debit cards. Currently, PCCharge only supports a dial-up connection to Global Payments East (NDC). For the processor Chase Paymentech (GSAR), TCP/IP and dial-up connectivity are supported. Also, the programming language used by the integrator must support ActiveX OCX controls in order to support Canadian Debit transactions. Note: The integration of Canadian debit transactions is more complicated than the integration of U.S. debit transactions. Prior to coding, it is highly recommended that integrators review this section, review the various API layouts that are referenced in this section, and then contact VeriFone, Inc.s Development Support department to discuss the integration. Note: If the processor Global Payments East (NDC) is used, once the integration is completed, the integration must be certified by Global Payments East (NDC). If the processor Chase Paymentech (GSAR) is used, no certification may be required. Contact VeriFone, Inc.s Development Support department for more details. Note: Canadian Debit is only supported when using the XML message format.

Definitions
MAC - Message Authentication Code Canadian banks require MACing when performing debit transactions. MACing provides security when processing transactions because it ensures that the messages used to communicate to the PINpad and to the processor are authentic. (Note: This acronym is commonly pronounced as mack.) MAC Block String data generated by the PINpad and the processor based on the transaction data submitted. Interac Association Interac is a Canadian organization responsible for the development of Canada's national debit service. This service is known as Interac Direct Payment (IDP). IDP was rolled out across Canada in 1994. Interac request string - The Interac request string is a string of text that is sent from the integrated application to the PINpadthe transaction-specific data contained in this string is used by the PINpad to prompt the customer to verify the amount of the transaction, choose which back account will be used, enter their PIN, and optionally, specify a tip amount. Once this information has been entered by the customer, the encrypted PIN, MAC Block, and other data is returned to the integrated application in an Interac response string. OMC (Out MaCing) and IMC (In MaCing) files Files that PCCharge creates in the background to perform MACing and data validation. ReMACing ReMACing is the process of sending the MAC data portion of the Interac request string to the PINpad to retrieve a new MAC Block from the PINpad. During the ReMACing process, the customer

78

is not prompted to enter any data on the PINpad. ReMACing will need to performed if the transaction details change during the process of building the debit transaction. Specifically, ReMACing is necessary when adding a tip to a transaction or when the bank account type changes during the transaction.

Integration Notes
Prior to sending the first Canadian debit transaction with the Verifone SC5000 PINpad, a key change must occur. A key change is performed from the PINpad setup menu in the PCCharge GUI. Choose Verifone SC5000 from the list and the appropriate radio button, either Global Payments East (NDC) or Chase Paymentech (GSAR), modify the Com port settings if necessary, and then click the Key Change button. PCCharge will connect via modem to Global Payments East (NDC) or Chase Paymentech and perform the key change. A message will be returned indicating whether or not the key change operation was successful. An error code 63, returned from Global Payments East (NDC) when processing transactions, indicates that a key change request must be performed. This error can occur even after the initial key change request has been performed. Canadian debit transactions must be coded to process in a single threaded manner for each PINpad used. For example, for each PINpad, the first transaction must fully complete prior to sending the second transaction. Only two transaction types are supported when processing Canadian debit transactions with Global Payments East (NDC). These transaction types are Purchase (action code 41) and Refund (action code 42). With Chase Paymentech (GSAR), Sale (action code 41), Return (action code 42), Online Void Sale (action code D1), Online Void Return (action code D2), and Current Key Request/Key Change Request (action code M1) are supported. When testing (or running live) Canadian debit transactions, Interac debit cards must be used. Standard U.S. credit cards or debit cards will not work. The track II information is encoded differently on Interac debit cards than it is on U.S. credit or debit cards. Specifically, Interac debit cards have a character encoded on track II that indicates the language code of the card (English or French), U.S. cards do not. The option Allow Duplicate Transactions in the NDC Debit Setup extended screen must be checked if the same card and amount will be sent to Global Payments East (NDC) more than once. Duplicate transactions are common in testing. If this option is not set and a duplicate transaction is sent to the processor, the response AP DUP will be returned. After a transaction has been successfully processed by Global Payments East (NDC), the PinSC550.Initialize and PinSC550.GetSerialBlock methods must be called, in that sequence, to reset the PINpad prior to calling the PinSC550.StartMSR method. If these methods are not called in this sequence, the PINpads chip serial number will not be passed properly to Global Payments East (NDC). This will cause transactions to decline. When using the processor Global Payments East (NDC), it is highly recommended that the integrator set the option to automatically process OMC files. To activate this option, first, set the PinSC550.ServerPath property to the PCCharge directory, and then set the PinSC550.AutoProcess property to TRUE. If the integrator chooses to manually process the data in OMC and IMC files on their own (not recommended), the PinSC550 class provides three methods to facilitate manual processing. Base64Decode and Base64Encode allow integrators to encode and decode the Base 64 data in the OMC files. Encoding and decoding is required because the XML message format does not support the non-standard characters that appear in these files. InteracAnalysis allows integrators to send the string in the OMC file (after it is decoded) to the PINpad for verification. Once the string is verified by the PINpad, the merchant is assured that the transaction message returned by the processor is genuine. Again, these three methods will not be used if the OMC files will be processed automatically by the PinSC550 class. Global Payments East (NDC) requires the use of a POS Sequence Number for each PINpad used to process transactions. The POS Sequence Number for each PINpad is stored by Global Payments East (NDC) and passed to PCCharge with each transaction response. Because of

79

this, when using a new PINpad, the first transaction should be processed with a blank POS Sequence numberthis transaction will decline and return a result of NOT CAPTURED and reference of Invalid Seq. Num. This error indicates that Global Payments East (NDC) has passed the current POS Sequence Number to PCCharge, and that PCCharge has updated a file located in the PCCharge directory named NDCDebitMsg.txt with the correct sequence number. At this point, future transactions with this PINpad will be able to retrieve the correct POS Sequence Number and process successfully. The GetPOSSequenceNumber method is provided in the OCX, DLL, and OLE/COM methods of integration to retrieve the POS Sequence Number from a text file. This text file is named NDCDebitMsg.txt and appears in the PCCharge directory. The POS Sequence Number is unique to each PINpad and is required when processing transactions. If the File Method or TCP Interface will be used to process transactions, the integrator must manually retrieve the POS Sequence Number from this text file. The POS Sequence Number is stored in the file in the format: <ChipSN><POSSeqNum>. For example, 658A3P777 would indicate the Chip Serial Number of 658A3P and the POS Sequence Number of 777. Note: If multiple PINpads are used, this file will contain multiple Chip Serial Number / POS Sequence Number entries. When processing transactions that include tips, Global Payments East (NDC) only processes the total amount of the transaction (the total amount is defined as the amount of the sale plus the tip). However, PCCharge requires that two properties, Amount and Gratuity, be populated when submitting transactions that include tips. Once these two properties are set, their values will be added together automatically by PCCharge when the transaction is submitted to Global Payments East (NDC). The PinSC550 class has a communications monitor that can be used by the integrator to troubleshoot integration and processing issues. To activate the communication monitor, set the CommVisible property to TRUE. The OLE/COM method of integration may also be used to integrate Canadian Debit transactions. When using the OLE/COM method, the class must be declared asynchronously in order to activate events. For example, use Dim WithEvents in the declaration section. When calling the .Send method in the PCCDebit class, pass the TRUE parameter to execute the transaction asynchronously. This is only supported with Global Payments East (NDC).

Integration
Tools
The DevKit includes a control named SC550.OCX and the SC5X.OCX. This control contains two classes that are used to communicate to the Verifone SC5000 PINpad and to build and parse Interac request strings: SC550.PinSC550 This class provides properties and methods that allow client applications to communicate with the Verifone SC5000 PINpad. Tables with the descriptions of the properties and methods that are available in the SC550.PinSC550 class can be found starting on page 186. Only used for the processor Global Payments East (NDC). SC550.clsInteracReq This class provides properties and methods to build and parse the Interac strings that are required to communicate to the PINpad. Tables with the descriptions of the properties and methods that are available in the SC550.clsInteracReq class can be found starting on page 191. Only used for the processor Global Payments East (NDC). SC5X.OCX This OCX provides the properties and methods to communicate with the SC5000 pinpad. Only used for the processor Chase Paymentech (GSAR).

80

The DevKit also includes three tools that are also used to process Canadian debit card transactions with PCCharge: Debit.OCX (OCX Method) Debit Class (DLL Method) PCCDebit Class (OLE/COM Method) Depending on the integration method, one of the above tools should be used to enable the client application to communicate to PCCharge. Refer to tables found in the applicable sections in CHAPTER 6 -- PCCharge Integration Methods (see page 104) for descriptions of the properties and methods used while integrating.

Process Flow when using the processor Global Payments East (NDC)
The following explains the steps that are required to integrate Canadian Debit transactions. There are three general categories: 1. Start Up The steps outlined in Start Up should typically be performed each time the integrated application is started. 2. Transaction Processing The steps outlined in Transaction Processing should typically be performed each time a debit card transaction is processed. 3. Shut Down The steps outline in Shut Down should typically be performed when the integrated application shuts down. Note: In the steps below, when referencing the various properties and methods in the Debit.OCX, the Debit class in PSCharge.dll, and the PCCDebit OLE class, all three of these tools will be referred to as the debit control for simplicity.

Start Up When the integrated application starts up, the following steps should be performed:
1. Set the initial properties. In the PinSC550 class, set the initial communication properties for the PINpad. These properties are marked with a in the SC550.PinSC550 Class Properties table. 2. Open the port. Use the OpenPort Method in the PinSC550 class to open the Com port that the PINpad is connected to. 3. Initialize the PINpad. Use the Initialize Method in the PinSC550 class to initialize the PINpad. 4. Retrieve the PINpads Chip Serial Number. Use the GetSerialBlock Method in the PinSC550 class to retrieve the PINpads Chip Serial Number. Once the serial number has been retrieved from the PINpad, the PinSC550 class will fire the ActionUpdate event and the GPSPinPadAction will be set to ENUM_ACTION_REQ_SERIAL (5). The ChipSN property in the PinSC550 class will contain the PINpads Chip Serial Number. Store the Chip Serial Number value as a variableit will need to be passed to the debit control.

81

5. Activate the automatic processing of OMC files (recommended). To active the automatic processing of OMC files, set the properties marked with a in the SC550.PinSC550 Class Properties table. The values that should be set are noted below: Set the ServerPath property of the PinSC550 class to the PCCharge directory Set the AutoProcess property of the PinSC550 class to TRUE (default is FALSE) Set the AutoInterval property of the PinSC550 class. This property determines often the class will poll for the OMC files. Default is 1000 (milliseconds).

Transaction Processing Once all of the Start Up steps have been completed, perform the
following steps to process transactions: 1. Indicate to the PINpad to prompt the customer to swipe their debit card. Use the StartMSR Method in the PinSC550 class to prompt the customer to swipe their debit card. The message SWIPE CARD / GLISSER CARTE will appear on the PINpads screen. 2. Wait for the customer to swipe the card. After it is swiped, retrieve and parse the track II data and retrieve the language code. Once the card has been swiped in the PINpad, the PinSC550 class will fire the ActionUpdate event and the GPSPinPadAction will be set to ENUM_ACTION_MSR_RECEIVED_DATA (7). The TrackII property of the PinSC550 class will now contain the track II string from the card. Parse this string to retrieve the card number and expiration date. Store the track II data, card number, and expiration date values as variablesthey will need to be passed to the debit control. Also, the LanguageCode property of the PinSC550 class will contain the language code that was retrieved from the track II data. Store the language code value as a variableit will need to be passed back to the PinSC550 class when calling the RequestInterac method. 3. Retrieve the POS Sequence Number from PCCharge. PCCharge stores the POS Sequence Number for each PINpad in a file in the PCCharge directory named NDCDebitMsg.txt. In order to retrieve this number, set the debit controls Path property to the PCCharge directory and then call the GetPOSSequenceNumber method in the debit control. Note: The PINpads Chip Serial Number must be passed as a parameter when calling the GetPOSSequenceNumber method. Store the POS Sequence Number value as a variableit will need to be passed back to the clsInteracReq class when calling the BuildInteracRequest method. 4. Build the Interac request string. To build the Interac request string, instantiate the clsInteracReq class, populate the required properties, and then call the BuildInteracRequest method in the clsInteracReq class. The properties that are required when building the string are marked with a in the SC550.clsInteracReq Class Properties table. The method will return the Interac request string. Store the Interac request string as a variableit will need to be passed back to the PinSC550 class when calling the RequestInterac method. IMPORTANT: Do not clear or change any of the properties in the clsInteracReq class or destroy the object at this point. If ReMACing is required when processing this transaction, many of the properties that have already been set will be re-used. 5. Send the Interact request string (from step 4) and the cards language code (from step 2) to the PINpad. This will instruct the PINpad to prompt the customer to confirm the transaction amount, enter a tip amount (optional), choose the bank account type (Chequing or Savings), and enter their PIN. Use the RequestInterac method in the PinSC550 class to send the Interac request string to the PINpad. This will instruct the PINpad to prompt for the customer for various information. The RequestInterac method requires two parameters: the Interact request string from step 4 and the language code from step 2. Once the RequestInterac method is executed, the

82

PINpad will prompt the customer to 1) confirm the transaction amount; 2) specify the tip amount (optional); 3) choose their bank account type; and 4) enter their PIN. 6. Wait for the transaction-specific data to be entered by the customer on the PINpad. When the PINpad indicates the data has been entered, parse the data. Once data entry by customer has completed on the PINpad, the PinSC550 class will fire the ActionUpdate event and the GPSPinPadAction will be set to ENUM_ACTION_INTERAC_RECEIVED_DATA (16). The Interac response string returned by the PINpad will be placed in the DeviceData property of the PinSC550 class. To parse the string, pass it to the ParseResponseData method in the clsInteracReq class. When the ParseResponseData method returns TRUE, the properties marked with a in the SC550.clsInteracReq Class Properties table will be populated with the transaction-specific data. Store the value returned in TipAmount as a variableit may need to be passed to the debit control. Also, store the values returned in MacBlock and PinBlock as variablesthey will need to be passed to the debit control. 7. Determine if ReMACing must occur. If ReMACing is not necessary, skip to step 9. To determine if ReMACing must occur, check the value of the Boolean property RequireReMac in the PinSC550 class. If this property is set to TRUE, then ReMACing is required. Otherwise, ReMACing is not required, skip to step 9.

8. Request a new MAC block from the PINpad. If RequireReMac is set to TRUE, a new MAC block must be retrieved from the PINpad. The ReMacData property will contain a string of data that must be sent to the PINpad to retrieve a new MAC block. To perform the ReMAC, pass the string in the ReMacData property to the PINpad by using the RequestMAC method in the PinSC550 class. The RequestMAC method requires one parameter, the string of MAC data, to be passed to it. Once the PINpad creates and returns the new MAC block, the MACBlock property of the PinSC550 class will contain the new MAC block. Store the value returned in the MACBlock property as a variableit will need to be passed to the debit control. 9. Process the transaction. To process the transaction, set the path to the PCCharge directory in the debit control, check if SYS.PCC exists, and then populate the required properties in the debit control with the variables that have been stored by the application. The properties required to process a transaction are marked with a in the various debit control tables in CHAPTER 6 -- PCCharge Integration Methods (see page 104). Once the properties are populated, call the Send method. The Send method will instruct the debit control to send the transaction to PCCharge. PCCharge will then dial out to Global Payments East (NDC) and submit the transaction request. Once the transaction is processed by Global Payments East (NDC), a response is returned to PCCharge and the POS Sequence Number is updated. If the option to automatically process the OMC files is selected, PCCharge will validate the response message automatically, and then return the status of the transaction via the debit control to the integrated application. The most important information is returned in the GetResult, GetAuth, and GetRefNumber methods. Once all response data has been retrieved from the debit control, call the Clear or ClearVariables method to reset all of the properties. Note: If the OMC files will not be processed automatically, the integrator must poll for and then process the data returned in the OMC files to validate the transaction. 10. Prepare the PINpad for the next transaction. Once the transaction has completed, the PINpads screen will display to the customer whether or not the transaction was approved. After a few moments, the message OBTAIN CARD will

83

appear on the PINpads screen. In order to prepare the PINpad for the next transaction, call the Initialize Method in the PinSC550 class. The PINpads screen will display the message WELCOME/BONJOUR. To process the next transaction, return to step 1 of Transaction Processing.

Shut Down When the integrated application has finished processing transactions, the following step should be followed:
1. Shut down the Port. In the PinSC550 class, shut down the port by calling the ClosePort method in the PinSC550 class. Note: All steps listed above are only applicable when using the processor Global Payments East (NDC).

Process Flow when using the processor Chase Paymentech (GSAR)

1. Initialize the VeriFone SC5000 PINpad. Using the SC5X.OCX, initialize the VeriFone SC5000 PINpad by setting the required properties (see p. 193 for SC5X.OCX properties). The RetrieveCreditSwipe method can be called to set the PINpad to a ready state and will prompt for the swipe. Once the swipe occurs, if successful, the .Card, .Member, .ExpDate, and .Track properties will be populated automatically, and the PINpad will prompt for the PIN number. 2. Send the transaction to PCCharge. Send the transaction to PCCharge by calling the .Send 3 method of the SC5X.OCX. The transaction will be sent to the Path specified in the .ServerPath property of the SC5X.OCX. 3. Retrieve the response. Once PCCharge has processed the transaction request, call the various .Get methods to retrieve the response. Once the response has been retrieved, parse the results to determine the outcome of the transaction (see p. 194 for SC5X.OCX methods).

84

Transaction Inquiry
Overview
The PCCharge integration methods provide the ability to submit Transaction Inquiry requests. A Transaction Inquiry request (action code ZI) retrieves transaction data stored in the PCCharge database (pccw.mdb) based on the TroutD or account number that is submitted. The response provided by PCCharge will include all available transaction records returned in XML tags that correspond to the appropriate database fields. All five integration methods support the Transaction Inquiry request. Note: Sensitive information such as credit card numbers are encrypted in the PCCharge database. The transaction inquiry command will not return credit card numbers in plain text. If credit card numbers from past transactions are needed, these numbers must be stored in the integrated application. See the sections Important Security Notice (see page 8) and Warnings, Tips, and Guidelines (see page 43) for more information on the storage of sensitive cardholder data and the regulations related to data storage.

Usage
OCX Method and DLL Method
To submit a Transaction Inquiry request via the OCX or DLL Methods, use the Charge.OCX control or the Charge class of PSCharge.dll. Populate the following properties: User A valid user name in PCCharge Path The path to the PCCharge directory Command ZI TroutD or Card Populate only one of these properties. The request will return the results based on the value passed in either one of these properties.

Once the properties are populated, call the Send method. Once the request is processed, the response can be retrieved by calling the GetXMLResponse method. This method returns the contents of the .oux file that is returned by PCCharge.

OLE/COM Method
To submit a Transaction Inquiry request via the OLE/COM Method, use the debit class (the charge class cannot be used because charges action property is defined as long and this property will not accept the ZI action code. Populate the following properties in the debit class: User A valid user name in PCCharge Path The path to the PCCharge directory Action ZI TroutD or Card Populate only one of these properties. The request will return the results based on the value passed in either one of these properties.

Once the properties are populated, call the Send method. Once the request is processed, the response can be retrieved by calling the GetXMLResponse method. This method returns the contents of the .oux file that is returned by PCCharge.

85

File Method / TCP Interface

To submit a Transaction Inquiry request via the File Method or TCP Interface, pass a request to PCCharge that contains the following tags: USER_ID - A valid user name in PCCharge COMMAND - ZI TROUTD or ACCT_NUM - Use only one of these tags. The request will return the results based on the value passed in either one of these tags.

Once the request is processed, PCCharge returns the response in an .oux file. General Note: The RECORD_COUNT tag in the XML response indicates how many transaction records are returned for each account number or TroutD value. Multiple transaction records will be returned (as nested XML tags) if this is the case. For example, if a Pre-Authorization was completed with a PostAuthorization, and then Voided, RECORD_COUNT would indicate 3 and three transaction records would be returned.

86

Example
This example demonstrates performing a Transaction Inquiry request using the File Method or TCP Interface. Refer to the section File Method (see page 409) for more information on the File Method or TCP Interface API. Request:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>ZI</COMMAND> <TROUTD>1003</TROUTD> </XML_REQUEST> </XML_FILE>

Response:
<TRANS_INQUIRY> <RECORD_COUNT>1</RECORD_COUNT> <TRANS_RECORD> <TABLE>Trans</TABLE> <Number>1003</Number> <Ticket>123456789</Ticket> <Date>5/6/2004</Date> <Time>10:32:25</Time> <Station>User1</Station> <Processor>NOVA</Processor> <TID>99988836</TID> <Issuer>Visa</Issuer> <Member>VERIFONE TEST 3</Member> <ExpDate>1208</ExpDate> <Action>1</Action> <Manual>False</Manual> <Amount>$1.00</Amount> <Ref>00000000</Ref> <Result>CAPTURED</Result> <Auth>TESTVI</Auth> <Result_Ref>035</Result_Ref> <Tax_Amount>$0.00</Tax_Amount> <Total_Auth>$1.00</Total_Auth> <Trans_Indicator>1</Trans_Indicator> <ReqACI>Y</ReqACI> <RetACI>B</RetACI> <TransDate>0506</TransDate> <TransTime>103226</TransTime> <Card>4012........0026</Card> <PeriodicPayment>False</PeriodicPayment> <BatchNumber>0</BatchNumber> <ItemNumber>35</ItemNumber> <CVV2_Resp>X</CVV2_Resp> <Selected>False</Selected> <Commercial_Card>N</Commercial_Card> <Offline>N</Offline> <Status>A</Status> <TroutD>1003</TroutD> <CardPresent>0</CardPresent> <Business_Type>0</Business_Type> </TRANS_RECORD> </TRANS_INQUIRY>

87

Batch Settlement
To submit a batch settlement request via the File Method or TCP Interface, pass a request to PCCharge that contains the following tags: USER_ID - A valid user name in PCCharge COMMAND (see below) MERCH_NUM The merchant number PROCESSOR_ID The processor ID

Once the request is processed, PCCharge returns the response in an .oux file if using the File Method interface. If using TCP, the response is returned in the data stream.
Action Code 30 31 32 33 Description Batch Inquiry Batch Close/Settle Private Label Batch Close Amex Split Settle

39 Close/Settle Batches for all merchant numbers* * When using action code 39, an appropriate timeout value must be set to allow for closing/settling of all merchant numbers set up in PCCharge. If action code 39 is chosen, a default value of 1200 seconds is selected. If a longer time is needed, the timeout property must be set to an adequate value.

Example: 1) Example of batch settlement request: <XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>31</COMMAND> <PROCESSOR_ID>GSAR</PROCESSOR_ID> <MERCH_NUM>999999999999519</MERCH_NUM> </XML_REQUEST> </XML_FILE> Example of batch settlement response: <XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <RESULT>Accepted</RESULT> <AUTH_CODE>026 0207 9999</AUTH_CODE> <REFERENCE>999999999999519</REFERENCE> <INTRN_SEQ_NUM>1.00</INTRN_SEQ_NUM> <TRANS_ID>026 0207 9999</TRANS_ID> <TICODE>1</TICODE> <RET>1</RET> <TIM>1</TIM> <BATCH_NUMBER>26</BATCH_NUMBER> </XML_REQUEST> </XML_FILE>

88

Example: 2) When the batch exceeds the maximum size allowed or that is configured in PCCharge, a response file should look similar to this:

<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <RESULT>Accepted</RESULT> <AUTH_CODE>00001</AUTH_CODE> <REFERENCE>000192000903</REFERENCE> <INTRN_SEQ_NUM>8.00</INTRN_SEQ_NUM> <TRANS_ID>00001</TRANS_ID> <TICODE>5</TICODE> <RET>2</RET> <TIM>1</TIM> <BATCH_NUMBER>001</BATCH_NUMBER> </XML_REQUEST> <XML_REQUEST> <USER_ID>User1</USER_ID> <RESULT>Accepted</RESULT> <AUTH_CODE>00002</AUTH_CODE> <REFERENCE>000192000903</REFERENCE> <INTRN_SEQ_NUM>13.00</INTRN_SEQ_NUM> <TRANS_ID>00002</TRANS_ID> <TICODE>5</TICODE> <RET>1</RET> <TIM>2</TIM> <BATCH_NUMBER>002</BATCH_NUMBER> </XML_REQUEST> </XML_FILE> Note: In the event there are multiple batches waiting to be settled in one settlement, the integrated application will need to be designed to loop through the settlement response to retrieve the response for each batch.

89

Health Message Transaction

This is a transaction that will tell the state of PCCharge to determine if it is available accept transactions. The Action Code for this transaction is ZH. No parameters other than this action and the user are needed. This function will return a string with a code that reflects PCCharges state. Note: PCCharge must be running for the ZH command to function. The codes are as follow: 0 = OK response, transactions should process fine (No sys.pcc exists) 2 = Sys.pcc exists with no predefined code in it 3 = A Batch is in progress (Sys.pcc exists with a code 1 in the sys.pcc file) 4 = Database is being repaired (Sys.pcc exists with a code 2 in the sys.pcc file) 5 = Backup Zip is in progress (Sys.pcc exists with a code 3 in the sys.pcc file) 6 = Modem is being initialized (Sys.pcc exists with a code 4 in the sys.pcc file) 7 = Database is being archived (Sys.pcc exists with a code 5 in the sys.pcc file) 8 = The settlement file is locked (Sys.pcc exists with a code 6 in the sys.pcc file) 9 = A Reversal is in process 10 = A reversal is waiting (Only used for Buypass) 11 = Reserved 12 = Reserved 13 = Reserved For testing purposes, create a sys.pcc with the codes outlined above; verify that the response contains the correct associated result code.

Request Example: <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>ZH</COMMAND> </XML_REQUEST>

Response Example: <XML_REQUEST> <USER_ID>User1</USER_ID> <RESULT>0</RESULT> </XML_REQUEST>

90

Batch Totals Storage

PCCharge stores batch totals in the BatchTotals table of the PCCharge database. Developers can access this table by building database queries. The data in this table can be used to write custom reports that can assist merchants with reconciliation. Note: This functionality is currently available only for Buypass dial, lease-line, and TCP/IP Pass through connections. Other processors and connection types will be added in future releases.

BatchTotals Table
PCCharge stores batch totals received from the processor in the PCCW.mdb database. These totals are stored in the BatchTotals table after the completion of an inquiry or settlement. Information stored includes:
Column Name TransNum Date Time Action TID GrandTotal Net Database Data Type Text 10 characters Date/time Text 8 characters Text 2 characters Text 32 characters Currency Currency Description Transaction number from PCCharge Date of transaction Time of transaction Action code of transaction: 30 = Inquiry 31 = Settlement Terminal ID number for merchant account Gross amount of settlement/inquiry (includes totals plus returns plus voids) Net amount of settlement/inquiry (includes totals minus returns minus voids)

Additional columns include the following processor dependent columns: fee amount, returns, voids, debit, EBT, check, stored value totals, and totals for each card issuer along with transaction counts. More columns will be added in the future. The totals information can be tracked using transaction number, date, time, action code, merchant number, or any combination thereof. Queries can be linked with the settlement table.

91

Command Line Switches

The following table lists various command line switches that can be used to customize how PCCharge Pro or Payment Server runs. Simply add these switches to the end of target line of the PCCharge Pro or Payment Server shortcut.
Command Line Switch /UI /IOL /D Description Loads the PCCharge Payment Server graphical user interface (GUI) on initialization. (PCCharge Payment Server only) Disables the writing of transaction records to the included pccw.mdb database. Turns on the IODebug.log file. This file is used for troubleshooting purposes. Activates Demo mode. In Demo Mode, PCCharge will operate with all five integration methods if the XML message format is used. Important Note: Prior to activation, the Demo mode command line switch must be deleted to enable LIVE mode.

Command Line Switch Format

"C:\Program Files\PCCW\Pccw.exe" [/IOL] [/D] "C:\Program Files\Active-Charge\Active-Charge.exe" [/UI] [/IOL] [/D] Text inside [ ] is optional. The command line switches must appear in the order specified above.

92

CHAPTER 5 -- DevKit Constants

93

DevKit Constants
Action Codes
Refer to CHAPTER 3 -- Payment Processing Basics (see page 29) for further descriptions of the various transactions.

Credit Card
Action Code 1 2 3 4 5 6 7 8 9 10 11 13 14 15 17 P1 P2 Description Sale Credit Void Sale Pre-Authorization Post-Authorization Void Credit Void Post-Authorization Commercial Card Sale Commercial Card Credit Commercial Card Post-Authorization Pre-Authorization Return Note: Only available for processor NBS Gratuity (finalizes or modifies a Restaurant Sale) Sale with Gratuity Book Void Ship Pre-Paid Credit Card Balance Inquiry Note: Only available for processor NOVA Pre-Paid Credit Card Authorization Reversal Note: Only available for processor NOVA

Debit
Action Code 40 41 42 43 44 46 47 48 49 M1 D1 D2 S21 Description Pre-Authorization Note: Only available for processor NBS Sale Return Void Debit Card Balance Inquiry Note: Only available for processor NOVA Void Return Post-Authorization Note: Only available for processor NBS Sale Recovery Return Recovery Key Change Request (Canadian Debit only) Online Void Sale (Canadian Debit via Chase Paymentech GSAR only) Online Void Return (Canadian Debit via Chase Paymentech GSAR only) Gratuity (Canadian Debit via Chase Paymentech GSAR only)

The SC5X.OCX supports gratuity with the S21 action code. Gratuity is input by the user into the VeriFone SC5000 exclusively before the transaction is sent to PCCharge. Gratuity adjustments after the transaction are not available.

Check Verification
Action Code 20 21 22 23 Description MICR (verify) COD / Phone (verify) Drivers License (verify) Double ID (verify)

94

50 54

MICR (verify in truncation mode) Manager Override

Check Conversion
Action Code 24 51 52 53 59 Description Void Check Sale (MICR) Void (MICR) Force (MICR) Settle (MICR)

Check Conversion (Telecheck Only)

Action Code 51 Transaction ECA Sale Description PCCharge sends the ECA request and automatically handles the status request Properties Required: .User .Path .Processor .MerchantNumber .Amount .MICRStatus .CHECK_READER _CODE .CheckType .MICR_DATA or .Check_Number .Account_Number .Transit_Number Conditional .DL_TRACK_II or .Drivers_License .State .Phone_Number Optional: .CustomerCity .CustomerStreet .Zip_Code .CustomerName .Birth_Date .Ticket Required: .User .Path .TroutD Optional: .Ticket Required: .User .Path .TroutD .Amount Optional: .Ticket Required: .User .Path .Processor .MerchantNumber .Amount .MICRStatus .CHECK_READER _CODE .CheckType

52

ECA Void

PCCharge sends the void request to TeleCheck

56

ECA Adjustment

PCCharge sends the Adjustment request to TeleCheck

C4

ECA Authorization

PCCharge sends only the ECA Auth request and waits for the POS to send either a C5 or C6 prior to sending the status message

95

C4 (continued)

C5

ECA Completion Accepted

PCCharge sends the status message indicating the ECA has been Accepted

C6

ECA Completion Refused

PCCharge sends the status message indicating the ECA as been Refused. The merchant may still hold the check for paper deposit.

.MICR_DATA or .Check_Number .Account_Number .Transit_Number Conditional .DL_TRACK_II or .Drivers_License .State .Phone_Number Optional: .CustomerCity .CustomerStreet .Zip_Code .CustomerName .Birth_Date .Ticket Required: .User .Path .TroutD Optional: .Ticket Required: .User .Path .TroutD Optional: .Ticket

EBT
Action Code 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 Description Account Inquiry (GSAR: Cash Benefits / Food Stamp Balance Inquiry) Cash Withdrawal Food Stamp Purchase (GSAR: Food Stamp Sale) Food Stamp Credit (Return) (GSAR: Food Stamp Return) Cash Post-Authorization (GSAR: Cash Benefits Prior Auth Sale) Food Stamp Post-Authorization (Electronic Voucher) (GSAR: Food Stamp Prior Auth Sale) Food Stamp Credit Post-Authorization Cash Void Food Stamp Void Food Stamp Credit Void Purchase or Purchase w/Cashback (GSAR: Cash Benefits Sale with or w/o Cash Back) Foodstamp Purchase Recovery Foodstamp Credit Recovery Foodstamp Post-Auth Recovery Cash Withdrawal Recovery Cash Purchase Recovery

Gift
Note: Refer to the section Gift Card Transactions (see page 74) for a list of Gift Card processors and the action codes they support.
Action Code 18 25 26 Description Balance Inquiry Redemption / Sale Register / Replace

96

27 28 29 0A 0B 0C 0D 0H 0I 0N 0P 0Q 0R 0S 0T 0U 0V

Add Value / Prior Issuance / Increment / Reload Activation / Activate Void / Cancel Deactivate / Close Refund / Credit Totals Inquiry / Current Day Totals Previous Day Totals Balance with Lock Post-Authorization / Redemption Unlock Redeem Points Balance Merge Balance Adjustment / Unload Balance Transfer Report Lost / Stolen Cash Out / Cash Back Add Tip Pre-Auth

Batch
Action Code 30 31 32 33 39 Description Batch Inquiry Batch Close/Settle Private Label Batch Close Amex Split Settle Close/Settle Batches for all merchant numbers*

* When using action code 39, an appropriate timeout value must be set to allow for closing/settling of all merchant numbers set up in PCCharge. If action code 39 is chosen, a default value of 1200 seconds is selected. If a longer time is needed, the timeout property must be set to an adequate value.

Report
Action Code 81 82 83 Description Credit Card Detail report Batch Pre-Settle report Batch Post-Settle report

84 Check Summary report *Action code 80 is no longer a supported action code.

Miscellaneous
Action Code 90 99 ZA ZC ZI ZH Zm ZM ZS Description Reinitialize Modem Pre-Dial Transaction Archive Database Archive Configuration Transaction Inquiry Health Message Minimize PCCharge window Maximize PCCharge window Shut down PCCharge

97

Address Verification Response Codes

Response Code A B C D E G I M N P R S U W X Y Z 0 Address Match Address matches, ZIP code does not Address matches, postal code does not No match on address or postal code Street address and postal code matches AVS error Service not supported by non-US issuer Address not verified for international transaction Street address and postal code matches No match on address or ZIP code Postal code matches, address does not Retry, system is unavailable or timed out Service not supported by issuer (card type does not support AVS) Address information is unavailable 9-digit ZIP code matches, address does not Exact match Address and 5-digit ZIP code match 5-digit ZIP code matches, address does not No response sent

CVV2/CVC2/CID Response Codes

Response Code M N Address Match CVV2/CVC2/CID match CVV2/CVC2/CID mismatch 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. 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. Issuer has not certified for CVV2/CVC2/CID or issuer has not provided Visa/MasterCard with the CVV2/CVC2/CID encryption keys.

S U

Credit Card Types

Credit Card Issuer American Express Carte Blanche Diners Club Discover Enroute Fleet One Fuelman JAL JCB MasterCard Credit Card Type "AMEX" "CBLN" "DCCB" "DISC" "ENRT" "FLT1" "FUEL" "JAL " "JCB " "MC "

98

Wright Express Visa Voyager

"WEX " "VISA" "VGER"

Note: All card types are padded with spaces to four characters.

System Error Codes and Descriptions

If an error occurs while using the OCX, DLL, or OLE/COM methods of integration, the GetErrorCode and GetErrorDesc methods available in each class should be used to determine to cause of the error. The table below shows the errors and descriptions that are returned by these methods.
Error Code Error Description -14 -1 PC-Charge not running Description A valid tid.pcc file does not exist in the directory provided in the Path property. If an error occurred while calling PccSysExists (and PccSysExists did not set the error code), this error code will be set. When processing a credit card transaction, if the Send is called and the CheckCard property is set to TRUE, Send will attempt to verify the credit card. If the card fails that test, this error code will be set. If there was an error while using the DeleteUserFiles method, File Error will be placed in the Error Description field (GetErrorDesc). Indicates that there were no errors while the function was being performed. This error will occur if PCCharge is not running. This error will occur If PCCharge is running a batch function (close/inquire/settle). This error will occur if PCCharge is running a repair or compact This error will occur If PCCharge is in the process of backing up or restoring its system files. If PCCharge was unable to initialize the modem, this error will occur. If the transaction times out waiting for a reply from PCCharge, a timeout error will occur. This error will occur if a database backup is in progress in PCCharge. If the credit card is not a valid credit card and VerifyCreditCard is called, VerifyCreditCard will set the error code and description to Invalid Credit Card Number (for the OCX Method, it will not fire the error event.) If the Service property is set to a service that the processor specified does not support, this error will occur. If the expiration date is not a valid date and VerifyExpDate is called, VerifyExpDate will set the error code and description to invalid expiration date (for the OCX Method, it will not fire the error event.) If the amount is set to a negative amount or no decimal is provided and VerifyAmount is called, VerifyAmount will set the error code and description to invalid amount (for the OCX Method, it will not fire the error event.) If the LastValidDate property is set to an invalid format the Charge.OCX will set the error code and description (for the OCX Method, it will not fire the error event). This error will occur if a settlement file in PCCharge is locked. This error will occur if there is a configuration change in progress. If the files cannot be erased before processing the function, this error will occur. This error will occur if the sys.pcc file is an unknown state. If the .pro file is deleted while the function is being processed and the class never receives an .oux file, this error will occur. If the Birth_Date property is set to an invalid format (Example: 11/02), this error will occur. If the Amount property is set to an invalid format, .2, (for the OCX Method, the ERROR event will fire).

-1

Invalid Card Number

File Error 0 1 2 3 4 5 6 7 8 No Error PC-Charge not running Batch function in progress Repair/Compact in progress Backup or restore in progress Unable to initialize Modem Timeout Database backup in progress Invalid Credit Card Number

Check Service not supported

10

Invalid Expiration Date

11

Invalid Amount Invalid Last Valid Date Settlement File Locked Configuration Change Unable to erase system files Sys.pcc unknown state Transaction Canceled Invalid Birth Date Invalid Format

12 13 14 15 16 17 18 19

99

50

Need to enter Drivers License For SPS check, the Drivers License number must be supplied when the amount of the when transaction amount is sale transaction is greater than the DL Limit amount specified in the PCCharge SPS greater than $XX.XX settings. Need to enter State Code when transaction amount is greater than $XX.XX Need to enter Date of Birth when transaction amount is greater than $XX.XX Need to enter Phone Number Invalid File Name File Not Found Invalid Record Number Invalid Pccw Path Error Erasing TMP File For SPS check, the State Code (GA, CA, NY, FL, etc) must be supplied when the amount of the sale transaction is greater than the DL Limit amount specified in the PCCharge SPS settings. For SPS check, the Date of Birth must be supplied when the amount of the sale transaction is greater than the DL Limit amount specified in the PCCharge SPS settings. For SPS check, the Phone number must be supplied on all transactions. If no file name or merchant number are provided before calling a method that accesses a file in the PSCharge.Offline class, this error will occur. If the file name that was provided is not a valid file name, and a method in the PSCharge.Offline class tries to access the file, this error will occur. If attempting to void a record in a .bch file and that record does not exist, this error will occur. If PccwPath was not provided while performing the ProcessFile method, this error will occur. If there is a problem sending the .tmp file to the Recycle Bin while performing the Compact method, this error will occur.

51

52 53 100 110 120 150 200

SYS.PCC Codes and Descriptions

The presence of a file named SYS.PCC in the PCCharge directory indicates a busy or an error state. The following are PCCharge system (application) codes that will appear the SYS.PCC file if it is present. The SYS.PCC file will be written to the PCCharge directory and contain one of the following code only if PCCharge shuts down or if it is in the middle of a function that will not allow transactions to be processed. Once PCCharge is ready to process transactions again, the file will be deleted automatically.

Code 0 1 2 3 4 5 6 7

Description PCCharge is not running Batch Function in progress Repair / Compact in progress Backup or restore in progress Unable to initialize modem Database backup in progress Settlement file locked Configuration change in progress

Note: If using the OCX, DLL, or OLE/COM methods of integration, the following methods may be used: PccSysExists use to check for the existence of the SYS.PCC GetErrorCode if SYS.PCC exists, use to retrieve the code from SYS.PCC GetErrorDesc if SYS.PCC exists, use to retrieve the error description associated with the code

100

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 Alliance Data Systems, Inc. American Express BuyPass, Inc. Citibank Private Label ECHO FDMS Nashville / Envoy FDMS North / Cardnet FDMS Omaha / FDR FDMS South / NaBanco Fifth-Third Bank St. Pete Global Payment-East Heartland Payment Systems RBS Lynk National Bankcard Services National Processing Company NOVA Chase Paymentech TSYS (Formerly Vital) Processor Code ADSI AMEX BPAS CITI ECHO FDCN CES FDC NB BPS NDC HPTS LYNK NBS NPC NOVA GSAR VISA

Debit
Processing Company Alliance Data Systems, Inc. BuyPass, Inc. FDMS North / CardNet FDMS Omaha / FDR FDMS South / NaBanco Fifth-Third Bank St. Pete Global Payments / East Heartland Payment Systems RBS Lynk National Bankcard Services National Processing Company NOVA Chase Paymentech TSYS (Formerly Vital) Processor Code ADSI BPAS CES FDC NB BPS NDC HPTS LYNK NBS NPC NOVA GSAR VISA

101

Check Verification / Conversion

Processing Company Alliance Data Systems, Inc. ArJay/SCAN Data Corporation Certegy Check Services powered by RMRS CrossCheck FDMS North / CardNet Fifth-Third Bank St. Pete National Check Network NOVA Check Services Chase Paymentech Check Services Secure Payment Systems TeleCheck International, Inc. Processor Code ADSI ARJ EFAX EZCK CRCK CES BPS RMRS NOVA GSAR SPS TECK

EBT
Processing Company Alliance Data Systems, Inc. Buypass, Inc. Fifth-Third Bank St. Pete National Processing Company Chase Paymentech TSYS (Formerly Vital) Processor Code ADSI BPAS BPS NPC GSAR VISA

Gift
Processing Company Buypass, Inc. Datamark Gift Card Fifth-Third Bank St. Pete Givex RBS Lynk Mellennia Chase Paymentech Secure Payment Systems Smart Transaction Systems Stored Value Systems ValueLink Valutec World Processor Code BPAS DMRK BPS GVEX LYNK MELL GSAR SPS SMTS SVSI VLNK VTEC WRLD

102

Transaction Result Constants

Result CAPTURED NOT CAPTURED APPROVED NOT APPROVED PROCESSED CANCELLED VOIDED SALE NOT FOUND GRATUITY ADDED Error Problem SALE RECOVERED RETURN RECOVERED Settle Error Closed not closed OPEN TO BUY INVALID PARAM Accepted Result Code = 2 Result Code = 6 Result Code = 8 Transaction Type Monetary Varies Non-Monetary Varies Off-line Transaction, Report Any Void Description Successful online transaction now ready for settlement Unsuccessful online transaction Successful offline transaction for Terminal based processors, or successful Pre-Authorization for Host based processors) Unsuccessful offline transaction or unsuccessful Pre-Authorization for Host based processors Transaction was processed (Terminal based processors only); report was generated Transaction canceled by operator or modem never connected Successful (with most Terminal based processors) Successful (Offline Transaction for Terminal based processors. Depending on the processor and amount, some Gratuity transactions may be authorized online for Terminal based processors ) Unsuccessful transaction Unsuccessful Report Request Successful Debit Sale Recovery Successful Return Recovery Unsuccessful Settlement Successful Batch Close Unsuccessful Batch Close Successful Open to Buy Inquiry on an ADSI Private Label card Account number or TroutD not passed to Transaction Inquiry command Successful Settlement Batch Closed/Settled Batch Declined Batch Deferred

Follow On (Void, Gratuity, etc.) Unsuccessful (with most Terminal based processors) Gratuity Varies Report Debit Sale Recovery Debit Return Recovery Settlement Batch Close Batch Close Private Label Transaction Inquiry Settlement Settlement Settlement Settlement

103

CHAPTER 6 -- PCCharge Integration Methods

104

Pseudo-code
This section includes several programming algorithms that may be followed when using the OCX, DLL, or OLE/COM methods of integration to perform payment processing. 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.

105

Credit Card Sale/Pre-Authorization Retail / Card Present

This algorithm demonstrates the coding required to perform a swiped credit card transaction in a retail environment. Note: The processor must be configured for Retail or Restaurant in the Credit Card Company Setup in PCCharge to support swiped transactions. Create A Charge Object Set Charge = new ChargeComponentOrReference With Charge Set Required Initial Properties .Path = C:\Program Files\active-charge\ Set path to the PCCharge directory .User = User1 The username set up in PCCharge .Processor = PROC Processor Code set up in PCCharge .MerchantNumber = 12345 Merchant Number set up in PCCharge .Action = 1 1 = sale, 4 = pre-Authorization Set Optional Initial Properties .TimeOut = 45 .Multi = 1 .LastValidDate = 12 .PrintReceipts = 1 TimeOut value in seconds Multi-trans Wait flag Last Valid Date that can be accepted Number of receipts printed by PCCharge

Check to see if PCCharge is running and available to process transactions If .PccSysExists then Notify user of error and exit procedure

Print Error: & .GetErrorCode Print Description: & .GetErrorDesc Else PCCharge is running and ready to process transactions

Collect the transaction data from card reader and user input and set the credit card transaction properties: .Card = Account Number .ExpDate = MMYY Credit Card Account Number - REQUIRED Expiration Date on the Credit Card REQUIRED The transaction amount in two decimal places format without commas - REQUIRED

.Amount = 1.00

.Member = Cardholder Name The Cardholder Name - OPTIONAL .Manual = 1 .CardPresent = 1 Manual flag. 1 = card is swiped - REQUIRED 1 = card is present

Card Present flag. OPTIONAL

.Track = Track II data

Track II data from the credit card

106

REQUIRED Track II data qualifies the merchant for the best transaction rate .Ticket = 123456789 Invoice or ticket number assigned by the integrator or merchant CONDITIONAL (required by some processors)

Validate the input. The various .Verify methods can be used to validate the credit card number, expiration date, and amount. Validation should also occur at input time. If .VerifyCreditCard (Account Number) = False Then Exit and return to credit card input If .VerifyExpDate = False Then Exit and return to credit card input If .VerifyAmount = False Then Exit and return to credit card input

Process the transaction by calling the .Send method .Send 3 OCX / DLL - the 3 parameter activates the XML message format .Send , 3 OLE/COM - the 3 parameter activates the XML message format NOTE: Some languages such as Delphi and C++ require that a variable be set and that all optional arguments must be passed. Check with language documentation for variable settings and syntax. Var TTYPE_XML: LongWord; TTYPE_XML := 3; .Send(FileType(TTYPE_XML)); C++ equivalent would be a long

The .Send method with the 3 parameter creates a file called <username>.inx that contains the transaction request and drops it in the PCCharge directory. Depending on how integration occurs, the Send method is either a blocking (synchronous) or a non-blocking (asynchronous) call. The OCX supports asynchronous (event-driven) programming. The DLL Method supports synchronous programming. The OLE/COM method supports both synchronous and asynchronous programming. If the integration is event-driven (asynchronous), the FINISH event will fire within a few moments indicating that the transaction has completed processing. If the transaction cannot be submitted or a TimeOut occurs, an ERROR event will fire instead. These events should kick off result checking sub-routines in the application. If the integration is not event-driven, place the result checking subroutines immediately after the .Send method. Check the results of the transaction using the GetResult method Select Case Trim(.GetResult)

107

If the transaction is approved, display the results of the transaction on the users screen, print a receipt, etc. Case CAPTURED , APPROVED Print Print Print Print Print Successful results

TRANSACTION SUCCESSFUL .GetResult Transaction Result Constant .GetAuth Authorization code from Issuing bank .GetRefnumber Reference number .GetTroutD PCCharge Transaction Routing ID

Use any of the other .Get methods in the class to display information about the transaction. If the transaction is approved, store pertinent information such as the TroutD, Authorization code, Result, Amount, Cardholder name, etc. in a database table or other storage medium. This information can used for reporting purposes and to enable follow-on transactions such as Voids and Post-Authorizations. INSERT INTO DatabaseTable (.GetTroutD, .GetAuth, .GetResult, .Amount, .Member) VALUES The PCCharge Transaction Routing ID Authorization code from Issuing bank Transaction result constant Transaction amount Cardholder name

Store any other data desired. Please note that the credit card associations prohibit the storing any type of Track I or Track II data. If the credit card number and expiration date are to be stored, they must stored in an encrypted state. If the transaction is not approved, display the results to the user. Case "NOT CAPTURED", "NOT APPROVED", "CANCELED", Error Print TRANSACTION NOT SUCCESSFUL Print .GetResult Transaction Result Constant Print .GetAuth The reason why transaction was not approved. This value is provided by the processor. If an error occurs (such as a TimeOut error), display the error code and description to the user. If the integration is event-driven, this code would be placed in the ERROR event. Case Else Print Error: & .GetErrorCode Print Description: & .GetErrorDesc End Select Once the transaction has completed and all data has been extracted from the result file, delete the file from the PCCharge directory. .DeleteUserFiles Deletes all files associated with the transaction. If

108

the integration is event-driven, DeleteUserFiles should be called in both the FINISH and ERROR events to avoid double-charging or reconciliation issues. End if .PccSysExists check End With IMPORTANT - Destroy the Charge object to reset all properties and methods. Also, the Clear method or ClearVariables method can be used to reset all properties and methods in the object. Set Charge = Nothing

109

Credit Card Sale/Pre-Authorization Card Not Present

This algorithm demonstrates the coding required to perform a manually keyed credit card transaction in the following industries: Retail, eCommerce, and Mail Order/Telephone Order Create A Charge Object Set Charge = new (ChargeComponentOrReference) With Charge Set Required Initial Properties .Path = C:\Program Files\active-charge\ Set path to the PCCharge directory .User = User1 The username set up in PCCharge .Processor = PROC Processor Code set up in PCCharge .MerchantNumber = 12345 Merchant Number set up in PCCharge .Action = 1 1 = sale, 4 = pre-Authorization Set Optional Initial Properties .TimeOut = 45 .Multi = 1 .LastValidDate = 12 .PrintReceipts = 1 TimeOut value in seconds Multi-trans Wait flag Last Valid Date that can be accepted Number of receipts printed by PCCharge

Check to see if PCCharge is running and available to process transactions If .PccSysExists then Notify user of error and exit procedure

Print Error: & .GetErrorCode Print Description: & .GetErrorDesc Else PCCharge is running and ready to process transactions

Collect the transaction data from user input and set the credit card transaction properties: .Card = Account Number .ExpDate = MMYY Credit Card Account Number - REQUIRED Expiration Date on the Credit Card REQUIRED The transaction amount in two decimal places format without commas - REQUIRED

.Amount = 1.00

.Member = Cardholder Name The Cardholder Name - OPTIONAL .Manual = 0 Manual flag. REQUIRED 0 = card is manually keyed

.CardPresent = 0

Card Present flag. 1 = card is present; 0 = card is not present OPTIONAL (passing 1 may improve rates if keying in a card in a retail environment)

110

.Ticket = 123456789

Invoice or ticket number assigned by the integrator or merchant REQUIRED for lowest rate (also required by some processors) Cardholders street address REQUIRED for lowest rate Cardholders zip code REQUIRED for lowest rate Card Verification Value - OPTIONAL

.Street = Billing Street

.Zip = Billing Zip

.CVV2 = 123

Validate the input. The various .Verify methods can be used to validate the credit card number, expiration date, and amount. Validation should also occur at input time. If .VerifyCreditCard (Account Number) = False Then Exit and return to credit card input If .VerifyExpDate = False Then Exit and return to credit card input If .VerifyAmount = False Then Exit and return to credit card input Process the transaction by calling the .Send method .Send 3 OCX / DLL - the 3 parameter activates the XML message format .Send , 3 OLE/COM - the 3 parameter activates the XML message format The .Send method with the 3 parameter creates a file called <username>.inx that contains the transaction request and drops it in the PCCharge directory. Depending on how integration occurs, the Send method is either a blocking (synchronous) or a non-blocking (asynchronous) call. The OCX supports asynchronous (event-driven) programming. The DLL Method supports synchronous programming. The OLE/COM method supports both synchronous and asynchronous programming. If the integration is event-driven (asynchronous), the FINISH event will fire within a few moments indicating that the transaction has completed processing. If the transaction cannot be submitted or a TimeOut occurs, an ERROR event will fire instead. These events should kick off result checking sub-routines in the application. If the integration is not event-driven, place the result checking subroutines immediately after the .Send method. Check the results of the transaction using the GetResult method Select Case Trim(.GetResult) Case CAPTURED , APPROVED Successful results If the transaction is approved, display the results of the transaction on the users screen, print a receipt, etc. Print TRANSACTION SUCCESSFUL

111

Print Print Print Print Print Print

.GetResult .GetAuth .GetRefnumber .GetAVS .GetCVV2 .GetTroutD

Transaction Result Constant Authorization code from Issuing bank Reference number Address Verification Response from card issuer Card Verification Response from card issuer PCCharge Transaction Routing ID

Use any of the other .Get methods in the class to display information about the transaction. If the transaction is approved, store pertinent information such as the TroutD, Authorization code, Result, Amount, Cardholder name, etc. in a database table or other storage medium. This information should used for reporting purposes and to enable follow-on transactions such as Voids and Post-Authorizations. INSERT INTO DatabaseTable (.GetTroutD, .GetAuth, .GetResult, .Amount, .Member) VALUES The PCCharge Transaction Routing ID Authorization code from Issuing bank Transaction result constant Transaction amount Cardholder name

Store any other data desired. Please note that the credit card associations prohibit the storing of the CVV2, CVC2, or CID values. If the credit card number and expiration date are to be stored, they must stored in an encrypted state. If the transaction is not approved, display the results to the user. Case NOT CAPTURED, NOT APPROVED, CANCELED, ERROR Print TRANSACTION NOT SUCCESSFUL Print .GetResult Transaction Result Constant Print .GetAuth The reason why transaction was not approved. This value is provided by the processor. If an error occurs (such as a TimeOut error), display the error code and description to the user. If the integration is event-driven, this code would be placed in the ERROR event. Case Else Print Error: & .GetErrorCode Print Description: & .GetErrorDesc End Select Once the transaction has completed and all data has been extracted from the result file, delete the file from the PCCharge directory. .DeleteUserFiles Deletes all files associated with the transaction. If the integration is event-driven, DeleteUserFiles should be called in both the FINISH and ERROR events to avoid double-charging or reconciliation issues. End if .PccSysExists check

112

End With IMPORTANT - Destroy the Charge object to reset all properties and methods. Also, the Clear method or ClearVariables method can be used to reset all properties and methods in the object. Set Charge = Nothing

113

Level II (Commercial, Purchasing, etc.) Card Sale

This algorithm demonstrates the coding required to perform a swiped Level II Sale transaction. Typically, commercial, purchasing, procurement, business, and government card transactions require additional information in order for them to qualify for the lowest rates.

Create A Charge Object Set Charge = new ChargeComponentOrReference With Charge Set Required Initial Properties .Path = C:\Program Files\active-charge\ Set path to the PCCharge directory .User = User1 The username set up in PCCharge .Processor = PROC Processor Code set up in PCCharge .MerchantNumber = 12345 Merchant Number set up in PCCharge If Level II card processing will supported in the application, use the .CommercialCardType method (in Charge.OCX or in the DLLs Charge class) or the .CommercialCard function (in the PccBin OLE Class) to determine whether the credit card is a commercial card prior to assigning the .Action. For example, if the transaction is a sale, and the card is a commercial card, the action code should be set to 8 and customer should be prompted for the level II data (tax and customer code). Otherwise, the action code should be set to 1 for a standard credit card sale. .Action = 8 Set Optional Initial Properties .TimeOut = 45 .Multi = 1 .LastValidDate = 12 .PrintReceipts = 1 TimeOut value in seconds Multi-trans Wait flag Last Valid Date that can be accepted Number of receipts printed by PCCharge 8 = Level II card sale

Check to see if PCCharge is running and available to process transactions If .PccSysExists then Notify user of error and exit procedure

Print Error: & .GetErrorCode Print Description: & .GetErrorDesc Else PCCharge is running and ready to process transactions

Collect the transaction data from card reader and user input and set the credit card transaction properties: .Card = Account Number .ExpDate = MMYY Credit Card Account Number - REQUIRED Expiration Date on the Credit Card REQUIRED

114

.Amount = 1.00

The transaction amount in two decimal places format without commas - REQUIRED

.Member = Cardholder Name The Cardholder Name - OPTIONAL .Manual = 1 .CardPresent = 1 Manual flag. 1 = card is swiped - REQUIRED 1 = card is present

Card Present flag. OPTIONAL

.Track = Track II data

Track II data from the credit card REQUIRED Track II data qualifies the merchant for the best transaction rate Invoice or ticket number assigned by the integrator or merchant CONDITIONAL (required by some processors) rates

.Ticket = 123456789

.CustCode = Customer Code Cardholders Customer code REQUIRED for lowest rates .TaxAmt = 0.05 The amount of tax included in the total amount (inclusive). Set to 0.00 if customer is tax exempt - REQUIRED Tax Exempt Flag REQUIRED

.TaxExempt = False

If using the OCX or DLL Method, use the following code to set the .CommercialCardFlag: .CommercialCardFlag = .getCommercialCardType(Account Number) If using the OLE/COM Method, the PccBin class must also be used. following code to set the .CmrclCardFlag: If PccBin1.CommercialCard(Account Number) Then .CmrclCardFlag = PccBin1.CommercialCardType End If Validate the input. The various .Verify methods can be used to validate the credit card number, expiration date, and amount. Validation should also occur at input time. If .VerifyCreditCard (Account Number) = False Then Exit and return to credit card input If .VerifyExpDate = False Then Exit and return to credit card input If .VerifyAmount = False Then Exit and return to credit card input Use the

Process the transaction by calling the .Send method

115

.Send 3 OCX / DLL - the 3 parameter activates the XML message format .Send , 3 OLE/COM - the 3 parameter activates the XML message format The .Send method with the 3 parameter creates a file called <username>.inx that contains the transaction request and drops it in the PCCharge directory. Depending on how integration occurs, the Send method is either a blocking (synchronous) or a non-blocking (asynchronous) call. The OCX supports asynchronous (event-driven) programming. The DLL Method supports synchronous programming. The OLE/COM method supports both synchronous and asynchronous programming. If the integration is event-driven (asynchronous), the FINISH event will fire within a few moments indicating that the transaction has completed processing. If the transaction cannot be submitted or a TimeOut occurs, an ERROR event will fire instead. These events should kick off result checking sub-routines in the application. If the integration is not event-driven, place the result checking subroutines immediately after the .Send method. Check the results of the transaction using the GetResult method Select Case Trim(.GetResult) If the transaction is approved, display the results of the transaction on the users screen, print a receipt, etc. Case CAPTURED , APPROVED Print Print Print Print Print Successful results

TRANSACTION SUCCESSFUL .GetResult Transaction Result Constant .GetAuth Authorization code from Issuing bank .GetRefnumber Reference number .GetTroutD PCCharge Transaction Routing ID

Use any of the other .Get methods in the class to display information about the transaction. If the transaction is approved, store pertinent information such as the TroutD, Authorization code, Result, Amount, Cardholder name, etc. in a database table or other storage medium. This information can used for reporting purposes and to enable follow-on transactions such as Voids and Post-Authorizations. INSERT INTO DatabaseTable (.GetTroutD, .GetAuth, .GetResult, .Amount, .Member) VALUES The PCCharge Transaction Routing ID Authorization code from Issuing bank Transaction result constant Transaction amount Cardholder name

Store any other data desired. Please note that the credit card associations prohibit the storing any type of Track I or Track II data. If the credit card number and expiration date are to be stored, they must stored in an encrypted state. If the transaction is not approved, display the results to the user.

116

Case "NOT CAPTURED", "NOT APPROVED", "CANCELED", Error Print TRANSACTION NOT SUCCESSFUL Print .GetResult Transaction Result Constant Print .GetAuth The reason why transaction was not approved. This value is provided by the processor. If an error occurs (such as a TimeOut error), display the error code and description to the user. If the integration is event-driven, this code would be placed in the ERROR event. Case Else Print Error: & .GetErrorCode Print Description: & .GetErrorDesc End Select Once the transaction has completed and all data has been extracted from the result file, delete the file from the PCCharge directory. .DeleteUserFiles Deletes all files associated with the transaction. If the integration is event-driven, DeleteUserFiles should be called in both the FINISH and ERROR events to avoid double-charging or reconciliation issues. End if .PccSysExists check End With IMPORTANT - Destroy the Charge object to reset all properties and methods. Also, the Clear method or ClearVariables method can be used to reset all properties and methods in the object. Set Charge = Nothing

117

Credit Card Void

This algorithm demonstrates the coding required to perform a credit card void transaction. A void is considered a PCCharge follow-on transaction because of its use of the TroutD functionality. Create A Charge Object Set Charge = new (ChargeComponentOrReference) With Charge Set Required Initial Properties .Path = C:\Program Files\active-charge\ Set path to the PCCharge directory .User = User1 The username set up in PCCharge .Action = 3 3 = void; 6 = void credit; 7 = void post-authorization; 17 = void ship Set Optional Initial Properties .TimeOut = 45 .Multi = 1 .PrintReceipts = 1 TimeOut value in seconds Multi-trans Wait flag Number of receipts printed by PCCharge

Check to see if PCCharge is running and available to process transactions If .PccSysExists then Notify user of error and exit procedure

Print Error: & .GetErrorCode Print Description: & .GetErrorDesc Else PCCharge is running and ready to process transactions

The third-party application should provide a list of transactions that can be voided (or other similar option). The application should allow the user to pick the transaction to be voided from the list. The third-party application should now pass the transactions stored TroutD value to PCCharge: .TroutD = 1234 Transaction Routing ID from the original Sale or Post-Authorization that will be voided REQUIRED

Process the transaction by calling the .Send method .Send 3 OCX / DLL - the 3 parameter activates the XML message format .Send , 3 OLE/COM - the 3 parameter activates the XML message format The .Send method with the 3 parameter creates a file called <username>.inx that contains the transaction request and drops it in the PCCharge directory. Depending on how integration occurs, the Send method is either a blocking (synchronous) or a non-blocking (asynchronous) call. The OCX supports asynchronous (event-driven) programming. The DLL Method supports synchronous programming. The OLE/COM method supports both synchronous and asynchronous programming.

118

If the integration is event-driven (asynchronous), the FINISH event will fire within a few moments indicating that the transaction has completed processing. If the transaction cannot be submitted or a TimeOut occurs, an ERROR event will fire instead. These events should kick off result checking sub-routines in the application. If the integration is not event-driven, place the result checking subroutines immediately after the .Send method. Check the results of the transaction using the GetResult method Select Case Trim(.GetResult) Case VOIDED, CAPTURED Successful results

If the transaction is voided, display the results of the transaction on the users screen, print a receipt, etc. Print Print Print Print Print TRANSACTION SUCCESSFUL .GetResult Transaction Result Constant .GetAuth Void Response (may be returned) .GetRefnumber Reference number (may be returned) .GetTroutD PCCharge Transaction Routing ID

Use any of the other .Get methods in the class to display information about the transaction. If the transaction is voided successfully, update the transactions status in the third-party applications database table. SELECT * FROM DatabaseTable WHERE TroutD=1234 "Status".Value = "VOIDED" If the void fails for some reason, display the results to the user. Case Sale Not Found, Error Print TRANSACTION NOT SUCCESSFUL Print .GetResult Transaction Result Constant Print .GetAuth The reason why transaction was not approved. This value is provided by the processor. If an error occurs (such as a TimeOut error), display the error code and description to the user. If the integration is event-driven, this code would be placed in the ERROR event. Case Else Print Error: & .GetErrorCode Print Description: & .GetErrorDesc End Select

Once the transaction has completed and all data has been extracted from the result file, delete the file from the PCCharge directory.

119

.DeleteUserFiles Deletes all files associated with the transaction. If the integration is event-driven, DeleteUserFiles should be called in both the FINISH and ERROR events to avoid reconciliation issues. End if .PccSysExists check End With IMPORTANT - Destroy the Charge object to reset all properties and methods. Also, the Clear method or ClearVariables method can be used to reset all properties and methods in the object. Set Charge = Nothing

120

Credit Card Sale/Pre-Authorization Restaurant

This algorithm demonstrates the coding required to perform a swiped credit card transaction in a restaurant environment. Note: The processor must support and be configured for Restaurant in the Credit Card Company Setup in PCCharge to support restaurant transactions. Note: Manually keyed transactions are also supported in a restaurant environment. If transactions will be manually keyed, make sure the appropriate rate qualifying information is sent with each transaction. See the Credit Card Sale/Pre-Authorization Card Not Present algorithm (see page 110) for more information. Create A Charge Object Set Charge = new (ChargeComponentOrReference) With Charge Set Required Initial Properties .Path = C:\Program Files\active-charge\ Set path to the PCCharge directory .User = User1 The username set up in PCCharge .Processor = PROC Processor Code set up in PCCharge .MerchantNumber = 12345 Merchant Number set up in PCCharge .Action = 1 1 = sale, 4 = pre-Authorization Set Optional Initial Properties .TimeOut = 45 .Multi = 1 .LastValidDate = 12 .PrintReceipts = 1 TimeOut value in seconds Multi-trans Wait flag Last Valid Date that can be accepted Number of receipts printed by PCCharge

Check to see if PCCharge is running and available to process transactions If .PccSysExists then Notify user of error and exit procedure

Print Error: & .GetErrorCode Print Description: & .GetErrorDesc Else PCCharge is running and ready to process transactions

Collect the transaction data from card reader and user input and set the credit card transaction properties: .Card = Account Number .ExpDate = MMYY Credit Card Account Number - REQUIRED Expiration Date on the Credit Card REQUIRED The transaction amount in two decimal places format without commas - REQUIRED

.Amount = 10.00

.Member = Cardholder Name The Cardholder Name - OPTIONAL

121

.Manual = 1 .CardPresent = 1

Manual flag.

1 = card is swiped - REQUIRED 1 = card is present

Card Present flag. OPTIONAL

.Track = Track II data

Track II data from the credit card REQUIRED to qualify the merchant for the best transaction rate Invoice or ticket number assigned by the integrator or merchant CONDITIONAL (required by some processors)

.Ticket = 123456789

.EstGratuityAmount = 1.50 The estimated gratuity amount (not added to settlement amount) in two decimal places format without commas- OPTIONAL .MCSN = 02 The Server ID - OPTIONAL

Validate the input. The various .Verify methods can be used to validate the credit card number, expiration date, and amount. Validation should also occur at input time. If .VerifyCreditCard (Account Number) = False Then Exit and return to credit card input If .VerifyExpDate = False Then Exit and return to credit card input If .VerifyAmount = False Then Exit and return to credit card input Process the transaction by calling the .Send method .Send 3 OCX / DLL - the 3 parameter activates the XML message format .Send , 3 OLE/COM - the 3 parameter activates the XML message format The .Send method with the 3 parameter creates a file called <username>.inx that contains the transaction request and drops it in the PCCharge directory. Depending on how integration occurs, the Send method is either a blocking (synchronous) or a non-blocking (asynchronous) call. The OCX supports asynchronous (event-driven) programming. The DLL Method supports synchronous programming. The OLE/COM method supports both synchronous and asynchronous programming. If the integration is event-driven (asynchronous), the FINISH event will fire within a few moments indicating that the transaction has completed processing. If the transaction cannot be submitted or a TimeOut occurs, an ERROR event will fire instead. These events should kick off result checking sub-routines in the application. If the integration is not event-driven, place the result checking subroutines immediately after the .Send method. Check the results of the transaction using the GetResult method Select Case Trim(.GetResult)

122

Case CAPTURED , APPROVED successful results If the transaction is approved, display the results of the transaction on the users screen, print a receipt, etc. Print Print Print Print Print TRANSACTION SUCCESSFUL .GetResult Transaction Result Constant .GetAuth Authorization code from Issuing bank .GetRefnumber Reference number .GetTroutD PCCharge Transaction Routing ID

Use any of the other .Get methods in the class to display \ information about the transaction. If the transaction is approved, store pertinent information such as the TroutD, Authorization code, amount, cardholder name, etc. in a database table or other storage medium. This information should used for reporting purposes and to enable follow-on transactions such as Gratuity, Voids and Post-Authorizations. INSERT INTO DatabaseTable (.GetTroutD, .GetAuth, .GetResult, .Amount, .Member) VALUES The PCCharge Transaction Routing ID Authorization code from Issuing bank Transaction result constant Transaction amount Cardholder name

Store any other data desired. Please note that the credit card associations prohibit the storing any type of Track I or Track II data. If the credit card number and expiration date are to be stored, they must stored in an encrypted state. If the transaction is not approved, display the results to the user. Case "NOT CAPTURED", "NOT APPROVED", "CANCELED", Error Print TRANSACTION NOT SUCCESSFUL Print .GetResult Transaction Result Constant Print .GetAuth The reason why transaction was not approved. This value is provided by the processor. If an error occurs (such as a TimeOut error), display the error code and description to the user. If the integration is event-driven, this code would be placed in the ERROR event. Case Else Print Error: & .GetErrorCode Print Description: & .GetErrorDesc End Select Once the transaction has completed and all data has been extracted from the result file, delete the file from the PCCharge directory. .DeleteUserFiles Deletes all files associated with the transaction. If

123

the integration is event-driven, DeleteUserFiles should be called in both the FINISH and ERROR events to avoid double-charging or reconciliation issues. End if .PccSysExists check End With IMPORTANT - Destroy the Charge object to reset all properties and methods. Also, the Clear method or ClearVariables method can be used to reset all properties and methods in the object. Set Charge = Nothing

124

Credit Card Gratuity Restaurant

This algorithm demonstrates the coding required to perform a gratuity in a restaurant environment. A Gratuity is considered a PCCharge follow-on transaction because of its use of the TroutD functionality. Note: The processor must support and be configured for Restaurant in the Credit Card Company Setup in PCCharge to support restaurant transactions. Note: PCCharge supports gratuity adjustments. If, for any reason, an existing gratuity is incorrect or the gratuity must be changed after it has been added to the transaction, the gratuity action (action code 13) can be used to correct or change the amount as many times as needed prior to settlement.

Create A Charge Object Set Charge = new (ChargeComponentOrReference) With Charge Set Required Initial Properties .Path = C:\Program Files\active-charge\ Set path to the PCCharge directory .User = User1 The username set up in PCCharge .Action = 13 13 = Gratuity add / adjustment Set Optional Initial Properties .TimeOut = 45 .Multi = 1 .PrintReceipts = 1 TimeOut value in seconds Multi-trans Wait flag Number of receipts printed by PCCharge

Check to see if PCCharge is running and available to process transactions If .PccSysExists then Notify user of error and exit procedure

Print Error: & .GetErrorCode Print Description: & .GetErrorDesc Else PCCharge is running and ready to process transactions

The third-party application should provide a list of transactions that can be voided (or other similar option). The application should allow the user to pick the transaction to be voided from the list. The third-party application should now pass the transactions stored TroutD value to PCCharge:

.TroutD = 1234

Transaction Routing ID from the original Sale or Post-Authorization that will be voided REQUIRED The estimated gratuity amount - REQUIRED

.GratuityAmount = 1.50

Process the transaction by calling the .Send method .Send 3 OCX / DLL - the 3 parameter activates the XML message format

125

.Send , 3 OLE/COM - the 3 parameter activates the XML message format The .Send method with the 3 parameter creates a file called <username>.inx that contains the transaction request and drops it in the PCCharge directory. Depending on how integration occurs, the Send method is either a blocking (synchronous) or a non-blocking (asynchronous) call. The OCX supports asynchronous (event-driven) programming. The DLL Method supports synchronous programming. The OLE/COM method supports both synchronous and asynchronous programming. If the integration is event-driven (asynchronous), the FINISH event will fire within a few moments indicating that the transaction has completed processing. If the transaction cannot be submitted or a TimeOut occurs, an ERROR event will fire instead. These events should kick off result checking sub-routines in the application. If the integration is not event-driven, place the result checking subroutines immediately after the .Send method. Check the results of the transaction using the GetResult method Select Case Trim(.GetResult) Case Gratuity Added Successful result

If the gratuity is added or adjusted, display the results of the transaction on the users screen, print a receipt, etc. Print Print Print Print Print TRANSACTION SUCCESSFUL .GetResult Transaction Result Constant .GetAuth Void Response (may be returned) .GetRefnumber Reference number (may be returned) .GetTroutD PCCharge Transaction Routing ID

Use any of the other .Get methods in the class to display information about the transaction. If the gratuity is added or adjusted successfully, in the third-party applications database table: add the gratuity to the transaction and update the transactions status. SELECT * FROM DatabaseTable WHERE TroutD=1234 "Status".Value = "Gratuity Added" "Gratuity Amount".Value = .GratuityAmount

If the gratuity transaction fails for some reason, display the results to the user. Case Sale Not Found, Error Print TRANSACTION NOT SUCCESSFUL Print .GetResult Transaction Result Constant Print .GetAuth The reason why transaction was not approved. This value is provided by the processor. If an error occurs (such as a TimeOut error), display the error code and

126

description to the user. If the integration is event-driven, this code would be placed in the ERROR event. Case Else Print Error: & .GetErrorCode Print Description: & .GetErrorDesc End Select Once the transaction has completed and all data has been extracted from the result file, delete the file from the PCCharge directory. .DeleteUserFiles Deletes all files associated with the transaction. If the integration is event-driven, DeleteUserFiles should be called in both the FINISH and ERROR events to avoid reconciliation issues. End if .PccSysExists check End With IMPORTANT - Destroy the Charge object to reset all properties and methods. Also, the Clear method or ClearVariables method can be used to reset all properties and methods in the object. Set Charge = Nothing

127

Debit Sale
This algorithm demonstrates the coding required to perform an online debit transaction in a retail environment. Specifically, this algorithm demonstrates processing a debit transaction using DUKPT encryption using a Verifone 1000/101 PINpad. Also, this algorithm only applies to U.S.-based debit processing companies. To integrate a PINpad, use Device.OCX or the PccPinPad OLE class provided with the DevKit. Alternatively, a direct integration to the PINpad may also be used. Contact the PINpad manufacturer(s) for details on integrating directly to PINpads.

Declare local variables to store the Key Serial Number and the PIN that are retrieved from the PINpad. Dim KSN, EncryptedPIN as String Initialize the PINpad. To initialize using Device.OCX or the PccPinPad OLE class, set required properties such as the baud rate, parity, etc. and then call the .Initialize method. If PinPad.Initialize Then MsgBox PINpad Initialized Create A Debit Object Set Debit = new DebitComponentOrReference With Debit Set Required Initial Properties .Path = C:\Program Files\active-charge\ Set path to the PCCharge directory .User = User1 The username set up in PCCharge .Processor = PROC Processor Code set up in PCCharge .MerchantNumber = 12345 Merchant Number set up in PCCharge .Action = 41 41 = Debit sale Set Optional Initial Properties .TimeOut = 45 TimeOut value in seconds

Check to see if PCCharge is running and available to process transactions If .PccSysExists then Notify user of error and exit procedure

Print Error: & .GetErrorCode Print Description: & .GetErrorDesc Else PCCharge is running and ready to process transactions

Collect the debit transaction information from the card reader and user input. Once the debit transaction information has been collected, prompt the cardholder for their PIN.

128

If using the Device.OCX: Set the .Card and .Amount properties and then call the .GetPin method: PinPad.Card = Account Number PinPad.Amount = 25.00 Must send Debit Card Number to PINpad Must send transaction Amount + CashBack amount to PINpad

Collect the data by calling the .GetPin and .GetKeySerialNumber methods: EncryptedPIN = .GetPin KSN = .GetKeySerialNumber Prompts the returns the Returns the returned by customer for the PIN and Encrypted PIN value Key Serial Number not all PINpads

If using the PccPinPad OLE class: Set the .Card and .Amount properties and then call the .GetPin method: PinPad.Card = Account Number PinPad.Amount = 25.00 Must send Debit Card Number to PINpad Must send transaction Amount + CashBack amount to PINpad Prompts the customer for the PIN. After the customer has successfully entered the PIN into the PINpad, the .GetPin method will return TRUE. The encrypted PIN and Key Serial Number are available in the .PIN and .KeySerialNumber properties The Encrypted PIN value The Key Serial Number not returned by all PINpads

If PinPad.GetPin Then

EncryptedPIN = .PIN KSN = .KeySerialNumber

End If If using a direct integration to a PINpad, collect the Encrypted PIN and Key Serial Number from the PINpad and assign these values to the proper variables.

Set the debit card transaction properties: .Card = Account Number .ExpDate = MMYY .Amount = 20.00 Debit Card Account Number - REQUIRED Expiration Date on the Debit Card - REQUIRED The transaction amount in two decimal places format without commas REQUIRED The CashBack amount in two decimal places format without commas - OPTIONAL

.CashBack = 5.00

.Member = Cardholder Name The Cardholder Name - OPTIONAL

129

.Manual = 1 .Track = Track II data .Ticket = 123456789

Manual flag.

1 = card is swiped - REQUIRED

Track II data from the debit card REQUIRED Invoice or ticket number assigned by the integrator or merchant CONDITIONAL (required by some processors) PIN from PINpad - REQUIRED Key Serial number from PINpad CONDITIONAL (populate if returned by the PINpad)

.Pin = EncryptedPIN .KeySerialNumber = KSN

Process the transaction by calling the .Send method .Send 3 OCX / DLL - the 3 parameter activates the XML message format .Send , 3 OLE/COM - the 3 parameter activates the XML message format The .Send method with the 3 parameter creates a file called <username>.inx that contains the transaction request and drops it in the PCCharge directory. Depending on how integration occurs, the Send method is either a blocking (synchronous) or a non-blocking (asynchronous) call. The OCX supports asynchronous (event-driven) programming. The DLL Method supports synchronous programming. The OLE/COM method supports both synchronous and asynchronous programming. If the integration is event-driven (asynchronous), the FINISH event will fire within a few moments indicating that the transaction has completed processing. If the transaction cannot be submitted or a TimeOut occurs, an ERROR event will fire instead. These events should kick off result checking sub-routines in the application. If the integration is not event-driven, place the result checking subroutines immediately after the .Send method. Check the results of the transaction using the GetResult method Select Case Trim(.GetResult) If the transaction is approved, display the results of the transaction on the users screen, print a receipt, etc. Case CAPTURED , APPROVED Print Print Print Print Successful results

TRANSACTION SUCCESSFUL .GetResult Transaction Result Constant .GetAuth Authorization code from Issuing bank .GetTroutD PCCharge Transaction Routing ID

Use any of the other .Get methods in the class to display information about the transaction. If the transaction is approved, store pertinent information such as the TroutD, Authorization code, Result, Amount, Cardholder name, etc. in a database table or other storage medium. This information can used for reporting purposes.

130

INSERT INTO DatabaseTable (.GetTroutD, .GetAuth, .GetResult, .Amount, .Member)

VALUES The PCCharge Transaction Routing ID Authorization code from Issuing bank Transaction result constant Transaction amount Cardholder name

Store any other data desired. Please note that the card associations prohibit the storing any type of Track I or Track II data or PIN information. If the debit card number and expiration date are to be stored, they must stored in an encrypted state. If the transaction is not approved, display the results to the user. Case "NOT CAPTURED", "NOT APPROVED", "CANCELED", Error Print TRANSACTION NOT SUCCESSFUL Print .GetResult Transaction Result Constant Print .GetAuth The reason why transaction was not approved. This value is provided by the processor. If an error occurs (such as a TimeOut error), display the error code and description to the user. If the integration is event-driven, this code would be placed in the ERROR event. Case Else Print Error: & .GetErrorCode Print Description: & .GetErrorDesc End Select Once the transaction has completed and all data has been extracted from the result file, delete the file from the PCCharge directory. .DeleteUserFiles Deletes all files associated with the transaction. If the integration is event-driven, DeleteUserFiles should be called in both the FINISH and ERROR events to avoid double-charging or reconciliation issues. End if .PccSysExists check End With IMPORTANT - Destroy the Debit object to reset all properties and methods. Also, the Clear method or ClearVariables method can be used to reset all properties and methods in the object. Set Debit = Nothing

131

Reports
This algorithm demonstrates the coding required to submit a report request to PCCharge. To submit a report request using the OCX Method, use Charge.OCX, for the DLL Method, use PSCharge.charge, and for OLE/COM, use ActiveCharge.PccCharge. Create A Charge Object Set Charge = new (ChargeComponentOrReference) With Charge Set Required Initial Properties .Path = C:\Program Files\active-charge\ Set path to the PCCharge directory .User = User1 The username set up in PCCharge .CheckCard = False Turns of credit card validity testing. Only necessary for the OCX and DLL methods .Action = 81 81 = Credit Card Detail; 82 = Batch PreSettle; 83 = Batch Post-Settle; 84 = Check Summary

Set Optional Initial Properties .TimeOut = 45 TimeOut value in seconds

If no other parameters are passed, PCCharge will print a report for the current 24 hour period to the default report printer that is set up in PCCharge once the Send method is called. Integrators may pass in optional parameters for output and filtering to customize the reports and how they are delivered. Set Optional Output parameters .PeriodicPayment = "1" Output type: 0 Print to PCCharges default report printer; 1 Print to file using filename specified in TRANSID Destination directory for output file (40 characters max)

.Track = "C:\Documents and Settings\JohnD\Desktop\"

.CustCode = "ReportDirectory\"

Continuation of destination directory if directory name is greater than 40 characters. The values in Track and CustCode are concatenated together once submitted. The last character of the directory name must be \. (25 characters max) Filename and extension of the report file. The extension determines the file type returned. Valid extensions: .pdf, .rtf, or .txt

.TRANSID = Report.pdf

132

Set Optional Filter parameters .Card = "User1" .MerchantNumber = "999999999911" .Street = 04/07/08 12:00:00 PM .Member = 04/08/08 11:00:00 AM .Manual = 1 User name Filter Merchant Number Filter Starting Date / Time Filter Ending Date / Time Filter Transaction Result Filter: 0 = all (default); 1 = approved; 2 = declined

Check to see if PCCharge is running and available to accept requests If .PccSysExists then Notify user of error and exit procedure

Print Error: & .GetErrorCode Print Description: & .GetErrorDesc Else PCCharge is running and ready to process transactions

Submit the report request by calling the .Send method .Send 3 OCX / DLL - the 3 parameter activates the XML message format .Send , 3 OLE/COM - the 3 parameter activates the XML message format The .Send method with the 3 parameter creates a file called <username>.inx that contains the transaction request and drops it in the PCCharge directory. Depending on how integration occurs, the Send method is either a blocking (synchronous) or a non-blocking (asynchronous) call. The OCX supports asynchronous (event-driven) programming. The DLL Method supports synchronous programming. The OLE/COM method supports both synchronous and asynchronous programming. If the integration is event-driven (asynchronous), the FINISH event will fire within a few moments indicating that the report request has completed. If the report request cannot be submitted or a TimeOut occurs, an ERROR event will fire instead. These events should kick off result checking sub-routines in the application. If the integration is not event-driven, place the result checking subroutines immediately after the .Send method. Check the results of the report request using the GetResult method Select Case Trim(.GetResult) Case Processed If the report request is successful, notify the user that the report has been printed or the report file is available. If accessing the report programmatically, begin parsing the report. Print REPORT NOW AVAILABLE Case Problem If the report request fails for some reason, display a message to the user.

133

Print REPORT REQUEST UNSUCCESSFUL If an error occurs (such as a TimeOut error), display the error code and description to the user. If the integration is event-driven, this code would be placed in the ERROR event. Case Else Print Error: & .GetErrorCode Print Description: & .GetErrorDesc End Select

Once the report request has completed and all data has been extracted from the result file, delete the file from the PCCharge directory. .DeleteUserFiles Deletes all files associated with the transaction. If the integration is event-driven, DeleteUserFiles should be called in both the FINISH and ERROR events. End if .PccSysExists check End With IMPORTANT - Destroy the Charge object to reset all properties and methods. Also, the Clear method or ClearVariables method can be used to reset all properties and methods in the object. Set Charge = Nothing

134

OCX (ActiveX) Method

Several OCX controls are included with the DevKit. These controls allow developers to access various processing functions using any Windows-based visual programming environment that supports OCX controls. Before an OCX control can be used, the control must be added to the visual programming language toolbox or equivalent. For example, in Microsoft Visual Basic 6, follow the procedure below: 1. Choose Project | Components from the Visual Basic menu bar. 2. After the Components window opens, from the list, scroll to and check the box next to the control(s) that will be used: VeriFones Charge ActiveX Control (for Credit card integration) VeriFones Debit ActiveX Control (for Debit card or EBT integration) VeriFones Check ActiveX Control (for Check integration) VeriFones GiftCard ActiveX Control (for Gift/Loyalty integration) VeriFones Batch ActiveX Control (for Batch/Settlement integration) VeriFones Device ActiveX Control (for PINpad integration) VeriFone's SC550 ActiveX Control (for VeriFone SC5000 PINpad integration-Canadian debit for Global Payments East NDC) VeriFones SC5X ActiveX Control (for VeriFone SC5000 PINpad integration-Canadian debit for Chase Paymentech GSAR)

and click OK. Note: The DevKit installation registers the controls by default. If the controls are not yet registered on the system, use regsvr32.exe to register them, or use the Browse button on the Components window to register the component and add it to the toolbar. 3. The control(s) will now be added to the toolbar. Each control can be added to the project by placing it in the desired area on the form. Each controls properties, methods, and events can be viewed through the object browser. If MS VB6 is not being used, refer to the language documentation for instructions on using ActiveX OCX Controls.

Note to .Net Framework Users

The OCX method is available in .Net through the use of the provided Charge-net.OCX, Debit-net.OCX and Batch-net.OCX. The regular Check.OCX, GiftCard.OCX, Device.OCX can be used with .Net.

Note to Delphi Users

The OCX method is available in Delphi through use of the provided Type Library Files (.tlb) for the corresponding Control. Rather than importing the OCX components to the tool palette, import the Type Libraries and create a wrapper. This can be done by following the procedure below: 1. Select Project | Import Type Library from the menu bar. (In Delphi 2005 / 2006, select Component | Import Component from the menu bar. Make sure that the radio button for Import a Type Library is selected, and then click the Next button)

135

2 A list of Libraries (.dll, .ocx, .olb, .tlb) will be available from which to choose. Click on the Add button, and browse to the location of the Type Library Files you wish to import. Once the new Library is highlighted (click the Next button in Delphi 2005 / 2006), there will be property fields indicating the classes of the Library, the palette page, the Unit Dir Name, and the Search Path. These fields can be left as default. Make sure that Create Wrapper is checked (Delphi 7 and below), and select Create Unit (click the Next button in Delphi 2005 / 2006 and then Create Unit). 3. This will add a text wrapper the Delphi Project. The name of this wrapper will be the name of the Library plus _TLB.pas. (For example: if importing the Charge.tlb, the wrapper name will be Charge_TLB.pas). Save this file to your projects working directory. It then must be added to the Uses clause of the .pas file in which it is intended to be used. unit Unit1; Interface Uses Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms, Dialogs, StdCtrls, StrUtils, Charge_TLB;

4. The next step would be to instantiate the main class of the Library, and load the OCX into memory so that the properties are accessible. One way to dynamically load the OCX into memory is to declare a THandle variable and a variable to hold the class, use LoadLibrary.The following example shows how to load the Charge OCX using this method: Type TCharge1 = class(OCXCharge) End; // // Instantiate the main class of the Library //

procedure TForm1.ProcessButtonClick(Sender: TObject); var hCharge: THandle; // Create a handle for the Library Charge: TCharge1; // Variable to hold the Charge Class Begin hCharge := LoadLibrary(Charge.ocx); if (hCharge = 0) then Begin ShowMessage(Error Loading Library); Exit; End Else If (hCharge <> 0) then Begin Charge := TCharge1.Create(Self); End; 5. Now all of the Properties for the main class of the Charge OCX will be available.

Note to Visual FoxPro 6 Users

The instruction "application.autoyield = .F." must be executed before the Send method can be called for any of the ActiveX controls. A sample Visual FoxPro 6 application is included. It is located in the directory C:\Program Files\active-charge SDK\Ocx\FoxPro\.

136

Note to Visual C++ Users

The standard versions of the OCX controls can be used in a Visual C++ project. The control can be added by going to Project | Components | Add Registered Controls. Visual C++ will provide a wrapper that will give the project access to the various properties and methods in the control. A sample Visual C++ application is included. It is located in the directory C:\Program Files\active-charge SDK\Ocx\Cpps\.

137

Charge.OCX
Charge.OCX provides integrators with properties and methods used to submit credit card transactions to PCCharge. To use Charge.OCX to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the transaction to be performed and validate the values using the various .Verify methods. (The properties marked with a in the Charge.OCX properties table are the minimum required to process a Sale or Pre-Authorization transaction.) 3. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format) 4. Wait for the Error or Finish event to occur. 5. Call the various .Get methods to determine the outcome of the transaction. The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error. 6. Call the DeleteUserFiles method to delete all files related to the transaction. 7. Call the Clear method to reset all the properties and methods related to the transaction or destroy the object. Consult the Pseudo-code section (see page 105) for various examples that may be followed when using the Charge.OCX to perform transaction processing. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

138

Charge.OCX Properties
Property Action Data Type Long Description - Charge.OCX Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). 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 American Express Description data. Additional description or information about merchandiseif 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 . American Express Description data. Additional description or information about merchandiseif 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 . American Express Description data. Additional description or information about merchandiseif 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 . American Express Description data. Additional description or information about merchandiseif 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 . The Authorization code. This value is returned by the issuing bank and should only be set in a transaction request 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, see page 63). 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. See the section Follow On Transactions for more information (see page 58). Only valid for Visa debit and credit transactions. It is used to indicate the transaction is being processedfor payment of a bill (ultilty, monthly gym dues, etc.) Valid values: 0 Non-Bill payment transaction 1 Bill payment transaction The credit card number that will be used when processing the transaction. Max Length: 20 characters. Example: 5424180279791765

Amount

String

AmxChargeDescription

String

AmxDescription_1

String

AmxDescription_2

String

AmxDescription_3

String

AmxDescription_4

String

AuthCode

String

Billpay

String

Card

String

139

Property

Data Type

Description - Charge.OCX Properties 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) Flag that indicates whether to activate credit card validity testing. Valid Values: TRUE; FALSE. Default value: TRUE. This value must be set to FALSE when performing Follow on transactions such as Voids or Gratuities because the card number is omitted from these transaction requests. The action code that identifies what type of transaction will be performed. Valid Values: 1-10, 13-15, ZI, ZH. Example: If running a credit card sale, set the action code to 1. Consult the section DevKit Constants for a list of valid values (see page 94). Note: Because the Action property is defined as long, this property was added to allow action codes that contain strings (such as Transaction Inquiry - ZI). If the Command property is set, its value will override the value set in Action. The type of commercial card being submitted. The getCommercialCardType method should be used to retrieve the 1 character value from PCCharge that indicates what type of commercial card will be submitted. See the section Commercial Card Transactions (see page 65) for more information. Max Length: 1 character Valid values: B Business P,L,G -- Purchase C Corporate F Fleet Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. 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 transactions 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. The credit plan number, only applicable when using Citi as the processor for private label cards. 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 nonswiped transactions. The demo mode flag. In demo mode, a simulated response is returned in which even amounts return approved, and odd amounts return declined. Valid Values: TRUE Activates demo mode FALSE Deactivates demo mode (default) 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 transactions action code must indicate that the transaction is a commercial card transaction. Driver identification field. Only required for Wright Express, Voyager and Fleet One cards. Driver personal identification number. Only required for Fuelman cards. For use with TCP/IP CommMethod only. SSL is not yet available with PCCharge. Leave this set to false.

CardPresent

String

CheckCard

Boolean

Command

String

CommercialCardFlag

String

CommMethod

Enum

CustCode

String

CreditPlanNumber

String

CVV2

String

Demo

Boolean

DEST_ZIP_CODE

String

DriverID DriverPIN EnableSSL

String String Boolean

140

Property

Data Type

Description - Charge.OCX Properties 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 place holder must be sent as well. See the section Restaurant Transactions (see page 69) 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. The expiration date associated with the credit card number that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 For use with Restaurant transactions only. The actual gratuity amount for a Sale with Gratuity (action code 14) , Gratuity (action code 13) , or PostAuthorization (action code 5) transaction. See the section Restaurant Transactions (see page 69) for more information. Only required for Voyager cards, dependant on Restriction Code. Four to six digits. Note: Only used for Pre-Authorization transactions For use with TCP/IP CommMethod only. IPAddress of machine where PCCharge is running. Defaults to 127.0.0.1 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. The last year that will be considered a valid expiration date. Currently, the default value in the control is 09. It is recommended that a setting is provided by which the end-user can change this property; otherwise, in the future, end users will require a new control to be distributed to resolve expiration date issues. Length: 2 digits. Format: YY Example: If LastValidDate is set to 05, then cards between 06 and 99 are considered to be 1906 to 1999, and cards between 00 and 05 are 2000 to 2005. Flag that indicates whether the transaction was manually entered or swiped. If the transaction was swiped, the Track property must also be set. Valid values: 0 = manual transaction, 1 = swiped transaction 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. 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 (see page 69) 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. The cardholders name. Max Length: 20 characters.

EstGratuityAmount

String

ExpDate

String

GratuityAmount

String

IDNumber IPAddress

String String

ItemID

String

LastValidDate

String

Manual

Long

MCSC

String

MCSN

String

Member

String

141

Property

Data Type String Boolean Boolean String Boolean

Description - Charge.OCX Properties The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Credit Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. No longer supported No longer supported No longer supported No longer supported 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line. The odometer reading. Only required for Fleet One (7 digits), Voyager (7 digits), and Fuelman (6 digits) cards. 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 The delay time before the PCCharge directory is polled for a transaction response file (.oux file). The default is 0.25 seconds. This value should only be modified if the integration is not performing properly. This could be caused if the client machine is slow or there is network lag that causes the server to spend more time checking for .oux files than processing transactions. For use with File_Tranfer CommMethod only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

MerchantNumber *** MSMQEncrypted MSMQOffSite MSMQServerName MSMQTransaction

Multi

String

Odometer

String

Offline

String

OutDelay

Single

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\".

PeriodicPayment

String String 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. For use with TCP/IP CommMethod only. Open port of PCCharge. 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. 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 the Processing Company Codes section (see page 101). Note: Only required for the processor NBS. This is the total dollar amount for PRODUCT_DETAIL_PRODUCT_CODE_XX 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 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.

Port

PrintReceipts

Processor ***

String

ProductDetailAmount_XX

String

ProductDetailCount

String

142

Property ProductDetailCode_XX

Data Type String

Description - Charge.OCX Properties Note: Only required for the processor NBS. This is the number of items for PRODUCT_DETAIL_PRODUCT_CODE_XX. Currently, PCCharge will support 0 1 10. Note: Only used for the processor NBS. This is the unit price for PRODUCT_DETAIL_PRODUCT_CODE_XX. This is only used for Fleet One and Fuelman. Currently, PCCharge will support 01 10. 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, see page 63). The Reference property does not need to be set if the PostAuthorization completes a standard Pre-Authorization using the TroutD value of the Pre-Authorization. See the section Follow On Transactions for more information (see page 58). 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. 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. Set to 1 if card information was read from RFID (Radio Frequency Identification) device. If card was read from from RFID, track data must be populated and manual flag must be set to 1. Set to 0 otherwise. Flag indicating whether a Voice Authorization transaction should be stored. This flag should only be submitted when performing a Post-Authorization transaction (action code 5) that includes an authorization code from the voice operator. For more information on stored Voice-Authorizations, see page 63. Valid Value: 1 - Store the Voice Authorization transaction. The cardholder's billing street address. The Street property is used for address verification. Address verification can only be performed on nonswiped 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 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. 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. 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 NOVA, ticket numbers can only be alphanumeric, no hyphens. The number of seconds after which a timeout error will be returned from the control. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. No longer needed

ProductDetailQuantity_XX

String

Reference

String

RestrictionCode

String

RFID

String

Store

String

Street

String

TaxAmt

String

TaxExempt

String

Ticket

String

TimeOut

Long

TotalAmount

String

143

Property

Data Type

Description - Charge.OCX Properties The track II data captured from the magnetic strip of the credit card. The track II data is required to ensure the lowest per-transaction rate from the processing company when performing swiped transactions (Retail and Restaurant). Sending the track II data is not allowed if the merchant's industry type is MOTO or eCommerce. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in. Alternatively, the GetParseData method can be used to parse the track data and set the Card, ExpDate, and Track properties automatically. 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50). Only required for Wright Express cards (5 digits) and Voyager cards (8 digits). Note: Required for both manual and swiped transactions. Set to True to activate the XML message format. It is recommended that the 3 parameter be passed to the Send method to activate the XML message format instead of using the XMLtran property. See the description for the Send method for more information. The cardholder's zip code. The Zip property is used for address verification. Max Length: 9 digits. Address verification can only be performed on nonswiped 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 9-digit zip, do not include the dash. The database archive configuration type setup in PCCharge. Valid value: Currently, only 0 is supported.

Track

String

TroutD

String

User **

String

VehicleID

String

XMLtran

Boolean

Zip

String

CfgType

Long 0 = CFG_TXN_ARCHIVE = Configure Transaction Archive. Use action code ZC.

CfgEnabled CfgPath CfgSizeLimit

Boolean String String String

Enable or disable current database archive configuration (1 = Enable, 0 = Disable). Specify path for saved output files (Example: backed up transaction database). Must end with a backslash \. Transaction archive size limit for GUI archive prompting and validation. Specified in megabytes. Transaction archive preservation range. All transactions within the past number of keep days will remain in the pccw.mdb database following a transaction archive command.

CfgKeepDays

These properties are the minimum required to process a Sale or Pre-Authorization transaction. ** 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 (see page 50). 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. Consult the Multi-Merchant Support section (see page 56) for more information on the Use Default Processor option. In addition, Processor and MerchantNumber should not be set when doing follow-on transactions. Refer to the section Follow On Transactions (see page 58) for more information.

144

Charge.OCX Methods
Method Returned Value Boolean Description - Charge.OCX Methods The Abort method attempts to cancel the transaction in progress and will return a Boolean value that indicates whether or not the transaction was canceled. Note: This method is not available when integrating using FoxPro. Use the Cancel method instead. The About method will display the About box associated with the control. 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. The Clear method will clear the values in all properties and methods. It is recommended that this method be called: a. after the transaction results have been retrieved by using the various .get methods b. after the DeleteUserFiles method has been called c. prior to running the next transaction The CommercialCardType method is used to determine whether or not a credit card is a commercial card. CommercialCardType requires that a string parameter, the credit card number, is passed when calling the method, that the Path property is set to a valid PCCharge directory, and that a valid Bin.mdb database resides in that directory. CommercialCardType returns TRUE if the BIN range of the card appears in the Bin.mdb database, FALSE if it does not. The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). *Not for use with TCP/IP CommMethod. Returns the entry method of the transaction. 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. Only supported on Fleet One, this field contains miscellaneous additional text returned from host. Currently PCCharge will support GetAddText1GetAddText4. The GetApproved method returns TRUE if PCCharge returns "APPROVED" as the result of the transaction. Otherwise, FALSE will be returned. An APPROVED response indicates that a Pre-Authorization has been approved, but not placed in the open batch. 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. 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 the section DevKit Constants for a description of values that may be returned (see page 94). Returns the PrePaid card balance. Only for pre-paid credit cards with NOVA.

Abort

About Cancel

MsgBox None

Clear

None

CommercialCardType

String

DeleteUserFiles

None

GetAcctDataSrc GetACI

String String

GetAddText1

String

GetApproved

Boolean

GetAuth

String

GetAVS

String

GetCCAvailBalance

String

145

Method

Returned Value

Description - Charge.OCX Methods 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, and that the transaction has been placed in the open batch. Returns a code that is used to verify the identity of the cardholder. The getCommercialCardType method requires a string parameter, the credit card number, and will determine the credit card numbers commercial card type. This method requires that the Path variable be set to a valid PCCharge directory and it uses the Bin.mdb database in the PCCharge directory to determine the commercial card type. Valid return values: B Business P,L,G -- Purchase C Corporate F Fleet Example: getCommercialCardType(4055011111111111) will return P. The GetCreditCardIssuer method returns the abbreviation of the credit card issuer's name for the card number that is present in the Card property. Consult the section DevKit Constants for a description of values (see page 94). The GetCreditCardType method returns either the abbreviation of the credit card issuer of the card that is present in the Card property, or the optional card parameter that is passed to the GetCreditCardType method. Consult the section DevKit Constants for descriptions of values (see page 94). (GetCreditCardType is the same as GetCardIssuer). Current transaction database size in bytes. Current configured size limit for transaction archive in bytes. 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 the section DevKit Constants for a description of values that may be returned (see page 94). Returns the available balance on pre-paid debit cards. Only for pre-paid debit cards with NOVA. 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetEstGratuityAmount echoes the estimated gratuity from the original transaction. The GetGratuityAmount echoes the gratuity amount from the original transaction.

GetCaptured

Boolean

GetCardIDCode

Boolean

getCommercialCardType

String

GetCreditCardIssuer

String

GetCreditCardType

String

GetCurrentDBSize GetConfigDBSize

String String

GetCVV2

String

GetDCAvailBalance

String

GetErrorCode

Long

GetErrorDesc

String

GetEstGratuityAmount GetGratuityAmount

String String

146

Method

Returned Value

Description - Charge.OCX Methods The GetHostType method returns an integer that indicates if a processor / merchant number is Host based or Terminal based. GetHostType requires three parameters: 1) Processor code - Consult the section DevKit Constants (see page 94) for a list of valid processor codes 2) Merchant account - Must be a valid merchant account set up in PCCharge 3) TID type - Valid Values for TID type: 0 Credit; 1 Check; 2 Debit; 3 EBT; 4 GiftCard GetHostType will return one the following values based on the parameters passed in: 0 The processor is Host based 1 The processor is Terminal based -1 The processor is a Hybrid (supports both Host and Terminal processing) or invalid processor / merchant number. Example: .GetHostType(VISA, 999999999911, 0) will return 0 Note: Chase Paymentech (GSAR), NOVA (NOVA), and FDMS South / NaBanco (NB) are considered hybrid processors. GetHostType will return a -1 for these processors. 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. The GetItemID echoes the item ID from the original transaction. The GetMerchantInfo method returns a string containing all of the merchant numbers and processors set up in PCCharge. The string will also indicate whether the processor is Host based (H), Terminal based (T), or a hybrid (Y). The string will begin with STX and will end with ETX. GS will separate each record, and FS will separate fields within a record. Example: <STX>CES <FS>000000927996296767<FS>T<GS>GSAR<FS> 999999999999519<FS>T<GS>VISA<FS>999999999911<FS>T<ETX> Refer to the section Multi-Merchant Support (see page 56) for more information on the GetMerchantInfo method. Returns the merchant number that was specified in the MerchantNumber property. Returns the Market Specific Indicator. This value indicates the transactions market segment. This value is assigned by the card associations and is not returned with all transactions. The GetParseData method will parse a string (containing credit card track data) passed to it and populate the Card, ExpDate, Member, and Track properties with the appropriate data. GetParseData will return an integer indicating its success. Valid return values: 0 (error parsing data), 1 (track I successful), or 2 (track I & II successful). Retrieves the private label Processor ID currently setup in PCCharge. The .path property must be specified. Retrieves the private label Merchant Number currently setup in PCCharge. The .path property must be specified. 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 Returns the Point of Entry Mode that is associated with the transaction. This value is not returned by all processing companies. PS2000 Data. This data will be as received during the original authorization processing. It will not be present for offline transactions. PS2000 Data is a variable; it will either be one character or up to 20. It is data concerning the card type and transaction that the processor will send back during the authorization process. This value is not returned by all processing companies. The number of records matching the inquiry 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.

GetHostType

Integer

GetIND GetItemID

String String

GetMerchantInfo

String

GetMerchantNumber

String String

GetMSI

GetParseData

String

GetPLProcessor GetPLMerchantNumber

String String

GetPCard

String

GetPEM

String

GetPS2000

String

GetRecordCount

String String

GetRefNumber

147

Method GetRespCode GetResponseCommercialType

Returned Value String String

Description - Charge.OCX Methods Returns the response code that is provided by the processor. This value is not returned by all processing companies. Returns the type of commercial card that was used for the transaction. This value is not returned by all processing companies. Returns a flag indicating whether the processor indicated whether the card was a Purchasing Card or not. This value is not returned by all processing companies. Valid values: 1 = Purchasing Card, 0 = Otherwise Note: Only supported on Fleet One. The product restriction code. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. Returns the Retrieval reference number. This value is not returned by all processing companies Returns the trace number from the processor. Only for pre-paid credit cards with NOVA. Returns the active batch number for the transaction. This value is not returned by all processing companies. Returns the date that the transaction was processed. This value is not returned by all processing companies. This will indicate the transaction Identifier for VISA or AMEX, it will also return the MC Bank Net reference if the card is a MasterCard. This value is not returned by all processing companies. 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. 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. Returns the Time of the transaction. This value is not returned by all processing companies. Returns the Transaction Item number or the number that is associated with the transaction in the settlement file. This value is not returned by all processing companies. 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. Contains nested XML tags providing information on transaction(s) pulled from Trans table in the PCCharge database (pccw.mdb) Returns the transaction reference number from the processor. Only for prepaid credit cards with NOVA. 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. See the section Follow On Transactions (see page 58) for more information. 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 from the .oux file can be used to view the results of a Transaction Inquiry (ZI) transaction. Refer to the section Transaction Inquiry (see page 85) for more information. The text can also be used by integrators that wish to parse the results of the transaction themselves or for troubleshooting purposes. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. 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.

GetResponsePurchaseCardType String GetRestrictCode GetResult String String String String String String String

GetRET GetTraceNumber GetTBatch GetTDate

GetTI

GetTicket

String

GetTICode GetTIM

String String String

GetTitem

GetTransNum

String String

GetTransRecord

GetTransactionReferenceNumb String er

GetTroutD

String

GetXMLResponse

String

GetXMLRequest

String

148

Method

Returned Value

Description - Charge.OCX Methods The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. *Not for use with TCP/IP CommMethod. The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the control will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send 3 Note: The other values that appear in the enumerated list are for internal use onlydo not attempt to use any values other than the ones listed above. The ValidCardLength method returns TRUE if the card is of the correct length, or FALSE if it is not. ValidCardLength has an optional string parameter in which a card can be passed. If that parameter is blank, ValidCardLength will analyze the value set in the Card property. The ValidDate method returns TRUE if the expiration date provided in the ExpDate property is valid, or FALSE if it is not. The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The VerifyCreditCard method returns TRUE if the credit card numbers format is valid and meets the requirements set forth by the credit card companies, FALSE if it does not. If FALSE is returned, use the GetErrorCode and GetErrorDesc methods to determine the reason for failure. VerifyCreditCard has an optional string parameter in which a credit card number can be passed. If the parameter is left blank, VerifyCreditCard will analyze the value set in the Card property. The VerifyExpDate method returns TRUE if the expiration date provided in the ExpDate property is correct and in the right format, or FALSE if it is not. VerifyExpDate calls the ValidDate function to validate the expiration date. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

PccSysExists

Boolean

Send

Integer

ValidCardLength

Boolean

ValidDate

Boolean

VerifyAmount

Boolean

VerifyCreditCard

Boolean

VerifyExpDate

Boolean

149

Method

Returned Value

Description - Charge.OCX Methods The VerifyMerchantNumber method returns TRUE if the merchant number that is passed to it is set up in PCCharge, otherwise, FALSE is returned. Specifically, this method checks for the merchant number in the file TID.PCC, which is located in the PCCharge directory. The Path property must be set before calling this Method. No longer supported

VerifyMerchantNumber

Boolean

VerifyProcessor

Boolean

Charge.OCX Events
Event Error Description Charge.OCX Events The Error event is fired any time an error occurs in the control. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the Transaction Result Constants section (see page 103).

Finish

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

150

Debit.OCX
Debit.OCX provides integrators with properties and methods used to submit debit card and EBT transactions to PCCharge. To use Debit.OCX to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Retrieve pertinent data, such as the PIN, the Key Serial Number (if DUKPT), etc., from the PINpad. Device.OCX may be used to collect data from the PINpad. See page 182 for more information on Device.OCX.

3. Assign the appropriate values to the properties required for the transaction to be performed and validate the values using the various .Verify methods. (The properties marked with a in the Debit.OCX properties table are the minimum required to process a Debit Sale transaction.)

4. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format)

5. Wait for the Error or Finish event to occur.

6. Call the various Get methods to determine the outcome of the transaction. The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error.

7. Call the DeleteUserFiles method to delete all files related to the transaction.

8. Call the Clear method to reset all the properties and methods related to the transaction or destroy the object.

When processing debit cards, a PINpad is required to allow the customer to enter their PIN. In addition, debit card information is always collected via a card swipe device, never via keyboard entry. Because of this, a card reader is also required. (Some EBT transactions can be manually entered). Refer to the Device.OCX section (see page 182) for information on integrating to a PINpad device. Device.OCX gives the application the ability to retrieve the PIN from the PINpad and use it to process debit card transactions. When processing U.S. debit card transactions, merchants have the option of allowing the customer to receive cash back on a transaction. For instance, the customer purchases $50 of products and wants $25 cash back, set the Amount to 50.00 and CashBack to 25.00. This will withdraw a total of $75 from the debit card account, $50 for the products and $25 for cash to give to the customer. Consult the Pseudo-code section (see page 105) for an example that may be followed when using the Debit.OCX to perform transaction processing.

151

For information on integrating Canadian Debit, see the section Canadian (Interac) Debit Transactions (see page 77). Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

152

Debit.OCX Properties
Property Name Action Data Type Long Description Debit.OCX Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Note: If performing an EBT Balance Inquiry transaction and providing an amount, set this property to 0.00. EBT Only: For an EBT Post (Prior Auth Sale) or Force transaction: The Authorization code from the original voice authorization. Only valid for Visa debit and credit transactions. It is used to indicate the transaction is being processed for payment of a bill (ultilty, monthly gym dues, etc.) Valid values: 0 Non-Bill payment transaction 1 Bill payment transaction The Debit/EBT card number that will be used when processing the transaction. Max Length: 20 characters. Example: 5424180279791765 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 debit processors do not support the cash back feature. Because the Action property is defined as long, this property was added to allow action codes that contain strings. This property is only used for action code M1 (Key Change Request). Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the bank account type that the customer specified when entering transaction data into the PINpad. Valid Values: Chequing or Savings For use with TCP/IP CommMethod only. SSL is not yet available with PCCHarge. Leave this set to false. The expiration date associated with the Debit/EBT card number that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Set this property if there is an expiration date associated with the Debit/EBT card. EBT Only: Indicates what type of EBT transaction will be performed. Valid Values: 1 Food stamp transaction; 0 Cash benefits transaction Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. This is the Gratuity Amount of the transaction. For use with TCP/IP CommMethod only. IPAddress of machine where PCCharge is running. Defaults to 127.0.0.1

Amount

String

AuthCode

String

Billpay

String

Card

String

CashBack

String

Command

String

CommMethod

Enum

DebitType

String

EnableSSL

Boolean

ExpDate

String

FoodStamp Gratuity IPAddress

Boolean String String

153

Property Name

Data Type

Description Debit.OCX Properties If a Key Serial Number is returned from the PINpad, this property should be populated with that number. If processing transactions with a PINpad using DUKPT encryption, this value is sixteen or twenty characters long (depending on the processors encryption). The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. If processing transactions with a Verifone SC5000 PINpad, set this property to the Chip Serial Number of the PINpad. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the language that is indicated by the Language Code that is encoded in the track II data on the customers card. Valid Values: English or French (pass in the literal string) Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the MAC Block value returned by the PINpad. Flag that indicates whether the transaction was swiped or manually entered. This property must be set to 1 (swiped) for Debit transactions or swiped EBT transactions. If the transaction was swiped, the Track property must also be set. If performing a manually keyed EBT transaction, such as a Force or Voucher, set this property to 0 (manually entered). The cardholders name. Max Length: 20 characters. The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Debit Card Setup window or EBT Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. The Original Purchase Data. Used when performing a Debit Return with the processors TSYS, Heartland, Lynk, and NPC. This is the original transaction date. Format: DDMMhhmm The delay time before the PCCharge directory is polled for a transaction response file (.oux file). The default is 0.25 seconds. This value should only be modified if the integration is not performing properly. This could be caused if the client machine is slow or there is network lag that causes the server to spend more time checking for .oux files than processing transactions. For use with File_Tranfer CommMethod only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

KeySerialNumber

String

LanguageCode

String

MACData

String

Manual

Boolean

Member

String

MerchantNumber ***

String

OrigPurchData

String

OutDelay

Single

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\". The encrypted PIN block that is retrieved from the PINpad. The PIN is provided to the processor for verification. Length: 16 characters. The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. For use with TCP/IP CommMethod only. Open port of PCCharge. 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 the Processing Company Codes section (see page 101).

Pin

String

Port

String

Processor ***

String

154

Property Name

Data Type

Description Debit.OCX Properties Note: Only required for the processor NBS. This is the total dollar amount for PRODUCT_DETAIL_PRODUCT_CODE_XX 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 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. Note: Only required for the processor NBS. This is the number of items for PRODUCT_DETAIL_PRODUCT_CODE_XX. Currently, PCCharge will support 0 1 10. Note: Only used for the processor NBS. This is the unit price for PRODUCT_DETAIL_PRODUCT_CODE_XX. This is only used for Fleet One and Fuelman. Currently, PCCharge will support 01 10. Required by some processors for returns. The reference number is returned with the original transaction. 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. Set to 1 if card information was read from RFID (Radio Frequency Identification) device. If card was read from from RFID, track data must be populated and manual flag must be set to 1. Set to 0 otherwise. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. The Shift ID. This value is optional. Format: Alphanumeric Max Length: 1 character. 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: When using NOVA, ticket numbers can only be alphanumeric, no hyphens. The number of seconds after which a timeout error will be returned from the control. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. The track II data captured from the magnetic strip of the card. The track II data is required for Debit transactions and for swiped EBT transactions. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in. No longer needed 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50). EBT Only: The voucher number for an EBT force transaction. The voucher is provided by the processor at the time of authorization and must be supplied to clear the voucher. Set to True to activate the XML message format. It is recommended that the 3 parameter be passed to the Send method to activate the XML message format instead of using the XMLtran property. See the description for the Send method for more information.

ProductDetailAmount_XX

String

ProductDetailCount

String

ProductDetailCode_XX

String

ProductDetailQuantity_XX

String

Reference

String

RFID

String

ShiftID

String

Ticket

String

TimeOut

Long

Track

String

TransNum

String

TroutD

String

User **

String

Voucher

String

XMLtran

Boolean

These properties are required to process a Debit Sale transaction.

155

 These properties are required to process a Canadian Debit Sale transaction using Global Payments East (NDC) and the SC5000 PINpad.

** 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 (see page 50). 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. Consult the Multi-Merchant Support section (see page 56) for more information on the Use Default Processor option. In addition, Processor and MerchantNumber should not be set when doing follow-on transactions. Refer to the section Follow On Transactions (see page 58) for more information.

Debit.OCX Methods
Method Name About Cancel Returned Value Boolean None Description - Debit.OCX Methods The About method will display the About box associated with the control. 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. The Clear method will clear the values in all properties and methods. It is recommended that this method be called: a. after the transaction results have been retrieved by using the various .get methods b. after the DeleteUserFiles method has been called c. prior to running the next transaction No longer supported The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). For use with file transfer CommMethod only No longer supported The GetApproved method returns TRUE if PCCharge returns "APPROVED" as the result of the transaction. Otherwise, FALSE will be returned. 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. When using the SC5000 PINpad, returns the ISO response code EBT Only: The GetAvlBalance method returns the available balance on the EBT card. This value is not returned by all processing companies. 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, and that the transaction has been placed in the open batch. EBT Only: Returns the remaining balance on a Cash Benefits card. This value is not returned by all processing companies.

Clear

None

Connect

Boolean

DeleteUserFiles

None

Disconnect GetApproved

None Boolean String String String

GetAuth GetAuxRespCode GetAvlBalance

GetCaptured

Boolean

GetEBTCashBalance

String

156

Method Name GetEBTFoodBalance

Returned Value String

Description - Debit.OCX Methods EBT Only: Returns the remaining balance on a Food Stamp card. This value is not returned by all processing companies. 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). For Debit Master Session: Returns the new master key (if one exists) sent by the processor that should be passed to the PINpad. Returns the merchant number that was specified in the MerchantNumber property. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Returns the current POS Sequence Number for the PINpad. The Path property must be set to the PCCharge directory and the PINpads Chip Serial Number must be passed as a parameter when calling the GetPOSSequenceNumber method. Returns the reference number associated with the transaction. 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. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. For GSAR Debit US only: Returns the surcharge amount that was charged by the bank when using debit with GSAR. This value has to be called in order for the developer to know how much the card was actually charged in addition to the transaction amount and cash back. For GSAR EBT: Returns terminal fee sent back by processor. The terminal fee is any surcharge defined and set up by Chase Paymentech and the EBT network of the cardholders EBT card. For Debit Master Session: Returns the new working key (if one exists) sent by the processor that should be passed to the PINpad for the next transaction. For GSAR EBT: Returns the ledger balance. For GSAR EBT: Returns the trace number sent back by processor. The trace number is a reference number generated by Chase Paymentech. 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. 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. See the section Follow On Transactions (see page 58) for more information. 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. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. 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.

GetErrorCode

Long

GetErrorDesc

String

GetMSI GetMerchantNumber

String String

GetPOSSequenceNumber

String

GetRefNumber

String

GetResult

String

GetSurchargeAmount

String

GetTermFee

String

GetTI

String String String

GetTraceNum

GetTransNum

GetTroutD

String

GetXMLResponse

String

GetXMLRequest

String

157

Method Name

Returned Value

Description - Debit.OCX Methods The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. For use with File_Transfer CommMethod only The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the control will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above. The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

PccSysExists

Boolean

Send

None

VerifyAmount

Boolean

Debit.OCX Events
Event Error Description - Debit.OCX Events The Error event is fired any time an error occurs in the control. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the Transaction Result Constants section (see page 103).

Finish

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

158

Check.OCX
Check.OCX provides integrators with properties and methods used to submit check verification, guarantee, and conversion transactions to PCCharge. To use Charge.OCX to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the transaction to be performed. (The properties marked with a in the Check.OCX properties table are the minimum required to process a check verification transaction.) 3. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format) 4. Wait for the Error or Finish event to occur. 5. Call the various .Get methods to determine the outcome of the transaction. The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error. 6. Call the DeleteUserFiles method to delete all files related to the transaction. 7. Call the Clear method to reset all the properties and methods related to the transaction or destroy the object. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

159

Check.OCX Properties
Property Name Account_Number Action Data Type String String Description - Check.OCX Properties For Check, MICR, or Double ID: The account number that will be used when processing the transaction. Max Length: 20 characters. The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Total amount of the transaction after adjustment (i.e. if the original transaction was $5.00 and it should have been $50.00, the adjustment transaction request should have the .Amount property set equal to 50.00). The date of birth of the check writer. Length: Exactly six characters. Format: MMDDYY. The birth date is required for DL (Drivers License) check transactions. 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. The Cashier Number Valid Values: 0 = Personal check, 1 = Business check Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The check number of the check that will be used when processing the transaction. Max Length: 10 characters. Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. The customers city. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The first and last name of the customer. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI.

Amount

String

AdjustmentAmount

String

Birth_Date

String

Cash_Back

String

CashierNum CheckType Check_Number

String String String

CommMethod

Enum

CustomerCity CustomerName

String String

160

Property Name

Data Type

Description - Check.OCX Properties Passes the type of Check Reader that is being used. Currently only used by Telecheck and will only be set if TECK is the set processor. Cannot be configured in the PCCharge GUI. Valid Values: 1 - Magtek_mini_micr 2 - EnCheck_3000 3 - IVI_2500 4 - IVI_430 5 - IVI_431 6 - ICE_5700 7 - MagtekImager 8 - VeriFone_CR1000i 9 - Epson_TMH6000 10 - Epson_TMH6000Imager 11 - WelchAllyn_ScanTeam 8300 12 - VeriFone_CR600 13 - Magtek_Imager_with_Modem 14 - IBM_4610_reader_printer 15 - Ingenico_EC2600 16 - RDM_EC5000 17 - RDM_EC6000 18 - NCR_7158_and_7167 19 - LS_100 20 - Magtek_Excella 21 - Magtek_Excella_DLCapture_FBChkImg 22 - Verifone_Model_Quartet The street address of the customer. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The parsed TrackII data from the drivers license. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The drivers license number of the individual writing the check. Max Length: 20 characters. The drivers license is required for DL (Drivers License) transactions and when performing Double ID transactions. For use with TCP/IP CommMethod only. SSL is not yet available with PCCharge. Leave this set to false. For use with TCP/IP CommMethod only. The IPAddress of the computer on which PCCharge is running. Used for BPS Double ID transactions. Optional Manager Number for manager override. Flag that indicates whether the transaction was manually entered or swiped. Valid values: 0 = manual transaction, 1 = swiped transaction The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Check Services Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. The raw MICR data from the bottom of the check. Used for conversion transactions. Valid Values: 15 = Valid read by MICR reader, 15I = Valid read by MICR reader with imaging capability, 9 = Manual only Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line. The delay time before the PCCharge directory is polled for a transaction response file (.oux file). The default is 0.25 seconds. This value should only be modified if the integration is not performing properly. This could be caused if the client machine is slow or there is network lag that causes the server to spend more time checking for .oux files than processing transactions.

CheckReaderCode

Enum

CustomerStreet DLTrackII

String String String Boolean String String String

Drivers_License EnableSSL IPAddress ManagerNum Manual

MerchantNumber

String

MICR_DATA

String String

MICRStatus

Multi

String

OutDelay

Single

161

Property Name

Data Type

Description - Check.OCX Properties For use with File_Transfer Method only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\".

Phone_Number Port

String String

The phone number of the individual writing the check. Max Length: 7 digits. Format: digits only. The phone number is required for COD (Checks On Delivery). For use with TCP/IP CommMethod only. Open port of PCCharge. 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 the Processing Company Codes section (see page 101).

Processor

String

Services

The type of check verification to be performed. This property may be specified by using a numerical value or an enumerated value if the programming language being used supports enumerated values. Valid values: 0 (MICR) MICR ServicesTyp 1 (COD) Checks-On-Delivery 2 (DL) Drivers License e 3 (DI) Double ID 4 (SPS) Use if Check processor is SPS Note: The value set in the Services property overrides the value set in the Action property. 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. The state code of the state that issued the check writers drivers license. The state code is required for DL (Drivers License). Format: 2 characters. 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: When using NOVA, ticket numbers can only be alphanumeric, no hyphens. The number of seconds after which a timeout error will be returned from the control. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. The Transit Routing Number / ABA number that will be used when processing the transaction. This value indicates which bank issued the check. Max Length: 9 characters. This value is required for MICR transactions and when performing Double ID transactions. 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50).

PrintReceipts

String

State

String

Ticket

String

TimeOut

Long

Transit_Number

String

TroutD

String

User **

String

162

Property Name

Data Type

Description - Check.OCX Properties Set to True to activate the XML message format. It is recommended that the 3 parameter be passed to the Send method to activate the XML message format instead of using the XMLtran property. See the description for the Send method for more information. The check writers ZIP code. Max Length: 9 characters. Format: digits only. This value is required for COD transactions. Note: If submitting the 9-digit zip, do not include the dash.

XMLtran

Boolean

Zip_Code

String

Note: To perform Double ID, both the MICR_DATA and Drivers_License fields must be populated. These properties are required, regardless of service type. ** 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 (see page 50). This section contains detailed information about user names and how they should be implemented. COD -- required for Checks-On-Delivery DL -- required for Drivers License MICR -- required for MICR

Check.OCX Methods
Method Name About Cancel Returned Value None None Description - Check.OCX Methods The About method will display the About box associated with the control. 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. The Clear method will clear the values in all properties and methods. It is recommended that this method be called: a. after the transaction results have been retrieved by using the various .get methods b. after the DeleteUserFiles method has been called c. prior to running the next transaction The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). For use only with File_transfer CommMethod The GetApproved method returns TRUE if PCCharge returns "APPROVED" as the result of the transaction. Otherwise, FALSE will be returned. An APPROVED response indicates that a Verification has been approved. 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. 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 conversion transaction that will result in a monetary transfer is approved or declined. A CAPTURED response indicates that the transaction has been approved, and that the transaction has been placed in the open batch. 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

Clear

None

DeleteUserFiles

None

GetApproved

String

GetAuth

String

GetCaptured

Boolean

GetErrorCode

Long

163

Method Name

Returned Value String

Description - Check.OCX Methods The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns the merchant number that was specified in the MerchantNumber property. Returns the response code that is provided by the processor. This value is not returned by all processing companies. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. Returns the result code that is provided by the processor. This value is not returned by all processing companies. Returns the response from the processor which indicates the fee for returned checks. Note: Only used for the processor TECK Returns the response from the processor which displays a note for returned checks. Note: Only used for the processor TECK Returns the reference number that is provided by the processor. This value is not returned by all processing companies 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. 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. See the section Follow On Transactions (see page 58) for more information. Only for TECK. Returns the Trace ID associated with the transaction. 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 from the .oux file can be used by integrators that wish to parse the results of the transaction themselves or for troubleshooting purposes. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. 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. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. For use only with File_Transfer CommMethod

GetErrorDesc

GetMerchantNumher GetRespCode

String String String String String String String String

GetResult

GetResultCode GetReturnCheckFee GetReturnCheckNote GetReference

GetTransNum

GetTroutD

String

GetTraceID

String

GetXMLResponse

String

GetXMLRequest

String

PccSysExists

Boolean

164

Method Name

Returned Value

Description - Check.OCX Methods The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the control will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send 3 Note: The other values that appear in the enumerated list are for internal use onlydo not attempt to use any values other than the ones listed above. The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

Send

None

VerifyAmount

Boolean

Check.OCX Events
Event Error Description Check.OCX Events The Error event is fired any time an error occurs in the control. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the Transaction Result Constants section (see page 103).

Finish

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

165

EBT
The structure of EBT transactions is similar enough to debit transactions that both are handled via the Debit.OCX. Consult the section Debit.OCX for more information on this ActiveX Control (see page 151).

166

GiftCard.OCX
GiftCard.OCX provides integrators with properties and methods used to submit gift card transactions to PCCharge. To use GiftCard.OCX to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the transaction to be performed and validate the values using the various .Verify methods. (The properties marked with a in the GiftCard.OCX properties table are the minimum required to process a Gift Card Redemption / Sale transaction.)

3. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format)

4. Wait for the Error or Finish event to occur.

5. Call the various .Get methods to determine the outcome of the transaction. The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error.

6. Call the DeleteUserFiles method to delete all files related to the transaction.

7. Call the Clear method to reset all the properties and methods related to the transaction or destroy the object. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

VeriFone Stored Value API (GAPI)

The VeriFone Stored Value API (GAPI) is a proprietary specification that allows for stored value card processors to add themselves to PCCharge. Applications using GAPI can also integrate with PCCharge using the various integration methods. For more information on adding a stored value card processor to PCCharge, and how to obtain the VeriFone Stored Value API, please contact VeriFone sales at 1-800725-9264.

167

GiftCard.OCX Properties
Property Name Action Data Type String Description GiftCard.OCX Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder must be sent as well. Example: 0.50. For Valuelink (VLNK) Balance Adjustment: Format: +/DDDDD.CC. Used for VTEC, VLNK and GSAR Void transactions. For VTEC and VLNK, set to auth code of original transaction (the one to be voided). For GSAR and MELL, set to reference number of the original transaction (the one to be voided). For BPS, set to retrieval reference number of original transaction (the one to be voided). For BPS, set to retrieval reference number of original transaction (the one to be voided). The gift card number that will be used when processing the transaction. Max Length: 20 characters. For GSAR multi Issuance, sequence number of cards issued at time of transaction. Example: Ten cards are being issued. The fifth is being sent, so set CardSeqNum to 5. VTEC and VLNK (optional) numeric value that identifies the cashier performing the transaction. Flag that indicates whether to activate gift card validity testing. Valid Values: TRUE; FALSE. Default value: TRUE. This value must be set to FALSE when performing Follow on transactions because the card number is omitted from these transaction requests. Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. The demo mode flag. In demo mode, a simulated response is returned in which even amounts return approved, and odd amounts return declined. Valid Values: 1 Activates demo mode 0 Deactivates demo mode (default) For use with TCP/IP CommMethod only. SSL is not yet available with PCCharge. Leave this set to false. The expiration date associated with the gift card that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Note: Most gift cards do not have an expiration date. Set to TRUE to process a transaction for which an approval code has already been issued -- only valid for a GSAR Redemption transaction or a single GSAR Issuance/Add Value transaction. The gratuity amount for the transaction. Tip should be no more than 9 characters long (including the decimal). Format: DDDDDD.CC. Only used for the processor SVS. To retrieve pin, call GetGfitPin upon activation. Used for only for virtual gift card transactions. Indicates industry type (1 = retail, 2 = restaurant). For VLNK (0 = retail, 1 = restaurant, 2 = e-Commerce). For use with TCP/IP CommMethod only. IPAddress of machine where PCCharge is running. Defaults to 127.0.0.1

Amount

String

Authcode

String

Card CardSeqNum

String String String

CashierID

CheckCard

Boolean

CommMethod

Enum

Demo

String

EnableSSL

Boolean String

ExpDate

FORCE

Boolean

GratuityAmount GiftPin Industry IPAddress

String String String String

168

Property Name

Data Type

Description GiftCard.OCX Properties The last year that will be considered a valid expiration date. Currently, the default value in the control is 09. It is recommended that a setting is provided by which the end-user can change this property; otherwise, in the future, end users will require a new control to be distributed to resolve expiration date issues. Length: 2 digits. Format: YY Example: If LastValidDate is set to 05, then cards between 06 and 99 are considered to be 1906 to 1999, and cards between 00 and 05 are 2000 to 2005. VTEC loyalty transaction flag (0 = non-loyalty, 1 = loyalty). Flag that indicates whether the transaction was manually entered or swiped. If the transaction was swiped, the Track property must also be set. Valid values: 0 = manual transaction, 1 = swiped transaction 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. See the section Multi-trans Wait for more information (see page 58). This Flag has no effect if processing will occur over IP or leased line. The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Gift Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. For VTEC Replace transaction. Set to account number of old card. For VLNK, Balance Merge and Balance Transfer. The delay time before the PCCharge directory is polled for a transaction response file (.oux file). The default is 0.25 seconds. This value should only be modified if the integration is not performing properly. This could be caused if the client machine is slow or there is network lag that causes the server to spend more time checking for .oux files than processing transactions. For GSAR: Flag indicating whether the transaction is a partial redemption transaction. For use with File_Transfer CommMethod method only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

LastValidDate

String

Loyalty Manual

Boolean Long

Multi

String

MerchantNumber

String

OldCard

String

OutDelay

Single

Partial

Boolean

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a \.

Points Port

String String String

For GVEX Points transactions. Set to number of loyalty points for account. For use with TCP/IP CommMethod only. Open port of PCCharge. 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. 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 the Processing Company Codes section (see page 101). Used for GVEX: A code defined by the merchant that affects the calculation from amount and units to points. 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 Set to 1 if card information was read from RFID (Radio Frequency Identification) device. If card was read from from RFID, track data must be populated and manual flag must be set to 1. Set to 0 otherwise.

PrintReceipts

Processor

String

PromoCode

String

Refund

String

RFID

String

169

Property Name Ticket

Data Type String

Description GiftCard.OCX Properties 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 gift processors support ticket numbers. The number of seconds after which a timeout error will be returned from the control. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. The tip amount for the transaction. TIP should be no more than 9 characters long (including the decimal). Format: DDDDDD.CC. Currently, tips are supported via the TIP property only for VTEC and VLNK restaurant transactions. For GSAR multi Issuance, total number of cards being issued at time of transaction. The track II data captured from the magnetic strip of the card.. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in. Alternatively, the GetParseData method can be used to parse the track data and set the Card, ExpDate, Member, and Track properties automatically. 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50). 0 - False, 1-True Only used for the processor SVS. Only used on an activation to determine if a pin should be returned. Set to True to activate the XML message format. It is recommended that the 3 parameter be passed to the Send method to activate the XML message format instead of using the XMLtran property. See the description for the Send method for more information. Only used for GAPI in restaurant mode. This is the table number of the gift card holder Only used for GAPI. The Track I information associated with the card

TimeOut

Long

TIP

String

TotalCardNum

String

Track

String

TroutD

String

User **

String

VirtualGiftCardFlag

Boolean

XMLtran

Boolean

TableNumber TrackI

String String

These properties are required to process a gift card redemption or sale transaction. Required for VTEC gift card transactions ** 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 (see page 50). This section contains detailed information about user names and how they should be implemented.

GiftCard.OCX Methods
Method Name Returned Value Boolean Description GiftCard.OCX Methods The Abort method attempts to cancel the transaction in progress and will return a Boolean value that indicates whether or not the transaction was canceled. Note: This method is not available when integrating using FoxPro. Use the Cancel method instead. The About method will display the About box associated with the control.

Abort

About

MsgBox

170

Method Name

Returned Value None

Description GiftCard.OCX Methods 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. The Clear method will clear the values in all properties and methods. It is recommended that this method be called: a. after the transaction results have been retrieved by using the various .get methods b. after the DeleteUserFiles method has been called c. prior to running the next transaction The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). For use only with File_Transfer CommMethod Returns the number of activations in the current batch Returns the total dollar amount of activations in the current batch Returns the number of AddPoints Transactions in the current batch Returns the total dollar amount of AddPoints transactions in the current batch Returns the number of AddValue transactions in the current batch Returns the total dollar amount of AddValue transactions in the current batch Used in partial redemption transactions where only part of the amount was authorized. Returns the remainder amount that is owed to the merchant. 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 transactions 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>. Used in partial redemption transactions where only part of the amount was authorized. Returns the actual authorized amount. Returns the number of Balance Transfers in the current batch Returns the total dollar amount of Balance Transfers in the current batch 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. 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. Returns the number of credits in the current batch Returns the total dollar amount of credits in the current batch 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

Cancel

Clear

None

DeleteUserFiles

None

GetActivationCount GetActivationTotalAmount GetAddPointsCount GetAddPointsTotalAmount GetAddValueCount GetAddValueTotalAmount GetAmountDue

String String String String String String String

GetAuth

String

GetAuthAmount GetBalanceTransferCount

String String

GetBalanceTransferTotalAmou String nt

GetCaptured

Boolean

GetCashBack GetCreditCount GetCreditTotalAmount

String String String

GetErrorCode

Long

GetErrorDesc

String

171

Method Name GetExp GetGiftCardBalance GetGiftCardIssuer GetGiftCardType GetGiftPin GetLevel GetMerchantNumber

Returned Value String String String String String String String

Description GiftCard.OCX Methods Returns the expiration date for processors who issue expiration dates in the response. Returns the gift card balance. Returns the gift card issuer. Consult the section DevKit Constants for description of values (see page 94). Returns type of gift card represented by card property. Consult the section DevKit Constants for description of values (see page 94). Only used for the processor SVS. Returned on activation if the virtual gift card tag is set to 1. Returns the customers loyalty level. Only used for VTEC loyalty gift cards. Returns the merchant number that was specified in the MerchantNumber property. The GetParseData method will parse a string (containing credit card track data) passed to it and populate the Card, ExpDate, and Track properties with the appropriate data. GetParseData will return an integer indicating its success. Valid return values: 0 (error parsing data), 1 (track I successful), or 2 (track I & II successful). Returns points balance for loyalty cards Returns the number of points transactions in the current batch Returns the total dollar amount of points transactions in the current batch The processor response code. Only returned by the processor SVS. 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 accounts 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. Returns the response code that is provided by the processor. This value is not returned by all processing companies. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. 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. Returns the number of redemptions in the current batch Returns the total dollar amount of redemptions in the current batch The GetTI method returns the TI field from the .oux file. The TI field is used for different purposes (depending on the gift card processor and transaction type). For GVEX Register: The remaining digits of an account number will be returned. For GVEX Redemption, Increment, and Cancel: The balance remaining on the card will be returned. For a VTEC batch function: : use this method to retrieve the number Add Value Transactions done that day and the total amounts of Add Value in the following format <# of transaction>, <amount>>. 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>.>. Returns the Time of the transaction. This value is not returned by all processing companies. For VTEC, returns the Amount Due. Returns the number of Tip transactions in the current batch Returns the total dollar amount of Tip transactions in the current batch Returns the transaction date and time when passed back by a processor.

GetParseData

String

GetPointsBalance GetPointsCount GetPointsTotalAmount GetProcRespCode

String String String String

GetRefNumber

String

GetRespCode

String String

GetResult

GetRet

String String String

GetSaleCount GetSaleTotalAmount

GetTI

String

GetTicket

String

GetTIM GetTipCount GetTipTotalAmount GetTransDateTime

String String String String

172

Method Name

Returned Value String

Description GiftCard.OCX Methods 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. 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. See the section Follow On Transactions (see page 58) for more information. Used internally Returns the Void Balance Returns the number of voids in the current batch Returns the total dollar amount of Voids in the current batch 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 from the .oux file can be used by integrators that wish to parse the results of the transaction themselves or for troubleshooting purposes. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. 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. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. For use only with File_Transfer CommMethod The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the control will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send 3 Note: The other values that appear in the enumerated list are for internal use onlydo not attempt to use any values other than the ones listed above.

GetTransNum

GetTroutD

String

GetUpdateData GetVoidBalance GetVoidCount GetVoidTotalAmount

String String String String

GetXMLResponse

String

GetXMLRequest

String

PccSysExists

Boolean

Send

None

ValidCardLength ValidDate

Boolean Boolean

Returns TRUE for card of correct length The ValidDate method returns TRUE if the expiration date provided in the ExpDate property is valid, or FALSE if it is not.

173

Method Name ValidIssuer

Returned Value Boolean

Description GiftCard.OCX Methods Returns TRUE for valid card issuer The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The VerifyAmount2 method returns TRUE if the amount provided in the Amount property is in a valid format (+/-DDDDD.CC). or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). The difference between VerifyAmount and VerifyAmount2 is that VerifyAmount2 allows a + or to be in the first position of the Amount property. This is needed for Balance Adjustment transactions. The VerifyExpDate method returns TRUE if the expiration date provided in the ExpDate property is correct and in the right format, or FALSE if it is not. VerifyExpDate calls the ValidDate function to validate the expiration date. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The VerifyGiftCard method verifies that a card is provided and the card is the expected length and return TRUE is it passes, otherwise FALSE will be returned. No Longer Supported No Longer Supported Only for GAPI, this returns the total number of gift card pre-auth transactions processed that day. Only for GAPI , this returns the total amount of gift card pre-auth transaction processed that day. Only for GAPI, this returns the number of the gift card post-auth transactions processed that day. Only for GAPI, this returns the total amount of the post-auth transactions processed that day. Only for GAPI, this returns the total number of gift cards issued that day. Only for GAPI, returns the total amount of the gift cards issued that day. Only for GAPI, this returns how many gift cards where deactivated that day. Only for GAPI, this returns the total amount of gift card deactivations that day. Only for GAPI, this returns the total number of gift cards that were balance adjusted that day. Only for GAPI, this returns the total amount of balance adjustments on gift cards that day. Only for GAPI, this returns the number of the gift cards that were balance merged that day. Only for GAPI, this returns the total amount of gift card balance merges that day. Only for GAPI, returns the total reported stolen or lost gift cards that day. Only for GAPI, returns the total amount of all stolen or reported lost gift cards that day. Only for GAPI, returns the total amount of all cashout transactions processed that day. Only for GAPI, returns the total number of the cashout transactions processed that day. Only for GAPI, returns the total number of gift cards that have been reactivated that day. Only for GAPI, the total amount of all gift cards that have been reactivated that day.

VerifyAmount

Boolean

VerifyAmount2

Boolean

VerifyExpDate

Boolean

VerifyGiftCard VerifyMerchantNumber VerifyProcessor GetPreAuthCount GetPreAuthAmount GetPostAuthCount GetPostAuthAmount GetIssuanceCount GetIssuanceTotalAmount GetDeactivateCount GetDeactivateTotalAmount GetBalanceAdjustCount

Boolean Boolean Boolean String String String String String String String String String

GetBalanceAdjustTotalAmount String GetBalanceMergeCount GetBalanceMergeTotalAmount GetReportLostStolenCount String String String

GetReportLostStolenTotalAmo String unt GetCashoutTotalAmount GetCashoutCount GetReactivateCount GetReactivateTotalAmount String String String String

174

GiftCard.OCX Events
Event Name Error Description GiftCard.OCX Events The Error event is fired any time an error occurs in the control. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the Transaction Result Constants section (see page 103).

Finish

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

175

Batch.OCX
Batch.OCX provides integrators with properties and methods used to perform batch settle, close, and inquire operations. This control may be used with both Host based and Terminal based processors. To use Batch.OCX to perform batch operations, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to perform batch operations by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the batch operation to be performed. (The properties marked with a in the Batch.OCX properties table are the minimum required to settle a batch.)

3. Call the Send method.

4. Wait for the Error or Finish event to occur.

5. Call the various .Get methods to determine the outcome of the transaction. The most important information can be acquired by calling the GetResult method. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error.

6. Call the DeleteUserFiles method to delete all files related to the transaction.

7. Call the Clear method to reset all the properties and methods related to the transaction or destroy the object.

Note: When using action code 39, an appropriate timeout value must be set to allow for closing/settling of all merchant numbers installed in PCCharge. If action code 39 is chosen, a default value of 1200 seconds is selected. If a longer time is needed, the timeout property must be set to an adequate value. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

176

Batch.OCX Properties
Property Name Action Data Type Single Description Batch.OCX Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). Flag that determines what type of batch close will occur. This flag only supported by Buypass and Fifth-Third when using action code 30 or 31 Valid values: 1 Standard End of Day Batch Close (Default) 2 Shift Close 3 Fifth-Third Terminal Based Batch Close of Debit, EBT, or Gift Set the Cancel property to TRUE to attempt to cancel the settle/close function. Check the GetResult method to see if the function was Canceled. Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. For use with TCP/IP CommMethod only. SSL is not yet available with PCCharge. Leave this set to false. For use with TCP/IP CommMethod only. IPAddress of machine where PCCharge is running. Defaults to 127.0.0.1 Account number issued to merchant by processor The delay time before the PCCharge directory is polled for a transaction response file (.oux file). The default is 0.25 seconds. This value should only be modified if the integration is not performing properly. This could be caused if the client machine is slow or there is network lag that causes the server to spend more time checking for .oux files than processing transactions. For use with File_Transfer CommMethod method only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory. Path String Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a \. Port String For use with TCP/IP CommMethod only. Open port of PCCharge. The code for the processing company that will be used to perform batch operations. 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 the Processing Company Codes section (see page 101). Only used when settling the processor CITI for private label transactions. Set this property to the main credit card processor ID code being used. The number of seconds after which a timeout error will be returned from the control. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). 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 more information on user names, consult the Multi-User Support section (see page 50). Set to True to activate the XML message format. It is recommended that the 3 parameter be passed to the Send method to activate the XML message format instead of using the XMLtran property. See the description for the Send method for more information.

BatchCloseType

String

Cancel

Boolean

CommMethod

Enum

EnableSSL IPAddress MerchantNumber

Boolean String String

OutDelay

Single

Processor

String

SplitProcessor

String

TimeOut

Long

User **

String

XMLtran

Boolean

These properties are required to settle a batch.

177

** 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 (see page 50). This section contains detailed information about user names and how they should be implemented.

The following properties are no longer available in the Batch.OCX and should be ignored:
AmexAmount AmexCount Balance BatchDate BatchNumber CIC ItemCount PurchaseCount Response ReturnAmount ReturnCount Store Terminal VisaMCAmount

PurchaseAmount VisaMCCount

178

Batch.OCX Methods
Method Name About Returned Value Single Description - Batch.OCX Methods The About method will display the About box associated with the control. The Clear method will clear the values in all properties and methods. It is recommended that this method be called: a. after the transaction results have been retrieved by using the various .get methods b. after the DeleteUserFiles method has been called c. prior to running the next transaction The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). For use only with File_Transfer CommMethod Index is an integer. Returns TRUE if batch settle/close was accepted Returns dollar value of batch Returns number of batches for settlement After a terminal-based batch settles, returns the batch number. The GetErrorCode method returns an error code if an error was encountered during the use of various methods such as the Send, DeleteUserFiles, and PccSysExists. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns the number of transactions in the batch The GetNumberIndexs method returns the number of merchant numbers that are stored in PCCharge. This number indicates how many batches will be settled or closed if an action code of 39 is submitted. Returns the merchant number that was specified in the MerchantNumber property. Returns TRUE if inquiry is successful Returns the response code for the batch if the close batch command was given. The response code indicates whether or not the transaction was successfully closed. If the batch is declined, the GetResult method will provide more information indicating why the transaction was not approved. Valid Values: 2 = Settled, 6 = Declined, or 8 = Deferred. GetResult GetSettleAmount GetSettleNumber String None String Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. No Longer Supported Returns sequence number of batch Returns the status of the batch when performing an inquiry or a batch close/settle operation. If performing a batch close/settlement operation, GetStatus will return a response from the processor that indicates whether or not the batch was successfully closed or settled. Example: If TSYS rejects the batch, GetStatus will return the RB (rejected batch) number from TSYS . If TSYS accepts the batch, GetStatus will return the batch number and an ACCEPTED response will be returned.

Clear

None

DeleteUserFiles

None

GetAccepted(Index) GetBalance GetBatches GetBatchNumber

Boolean String String String

GetErrorCode

Long

GetErrorDesc

String String Integer String Boolean

GetItemCount GetNumberIndexs

GetMerchantNumber GetProcessed

GetRespCode

String

GetStatus

String

179

Method Name

Returned Value

Description - Batch.OCX Methods The GetSystemInfo method is used to set the MerchantNumber and Processor properties of Batch.OCX. To use GetSystemInfo, pass the index number of a merchant number that is registered in PCCharge as a parameter (for example, the first Merchant number that is set up in PCCharge is assigned the index of 1 ). Once the index number has been passed to PCCharge via GetSystemInfo, the merchant number and processor can be retrieved using the MerchantNumber and Processor properties. No Longer Supported 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 from the .oux file can be used by integrators that wish to parse the results of the transaction themselves or for troubleshooting purposes. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. 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. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. For use only with File_Transfer CommMethod The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the Batch.OCX will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

GetSystemInfo

None

GetTotals

Boolean

GetXMLResponse

String

GetXMLRequest

String

PccSysExists

Boolean

Send

None

The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). Valid values: 3 (TTYPE_XML) XML message format RECOMMENDED Example: Send 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above.

Batch.OCX Events
Event Error Description - Batch.OCX Events The Error event is fired any time an error occurs in the control. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the Transaction Result Constants section (see page 103).

Finish

180

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

Note: In the event there are multiple batches waiting to be settled in one settlement, the integrated application will need to be designed to loop through the settlement response to retrieve the response for each batch.

181

Device.OCX
The Device.OCX allows integration to PINpads connected to the serial port. Currently, the Device.OCX supports the following devices: VeriFone 101/1000 (PIN entry only) VeriFone 2000 (Card Swipe and PIN entry only) Ingenico eN-Crypt 2100 (Card swipe and PIN entry) VeriFone SC5000 (Card Swipe and Pin Entry only. Only SC5000 with VeriFone 2000 emulation) VeriFone Everest (Card Swipe, Pin Entry, and Display Manipulation) VeriFone Omni 3730 (Card Swipe, Pin Entry, Printing)

Additional devices will be added in the future. The Device.OCX provides the functionality to Initialize a PINpad and retrieve the PIN from the cardholder. If using the Ingenico eN-Crypt 2100, Verifone Everest, 2000, VeriFone Omni 3730, or SC5000, it also allows retrieving the card swipe data. The PINpad must be initialized once prior to retrieving the PIN. If the PINpad is powered off and back on, it must be re-initialized. If the object is destroyed and then instantiated, the PINpad must be re-initialized.

182

Device.OCX Properties
Property Name Amount Baud Card Databits Data Type String String String String String Description - Device.OCX Properties Amount of transaction. This amount displayed to customer on the PINpad for approval Baud rate Debit card number Databits (Example: "7" or "8") The default message for the PINpad that is connected to the machine the Device.OCX will be communicating with. For example, if this is set to "Welcome", "Welcome" will appear on the screen at times of inactivity. Note: Not applicable for all PinPads. The Demo mode flag. Indicates whether the Device.OCX should run in demo mode. In demo mode, a simulated response is returned in which the Pin and KeySerialNumber are set to demo values. Valid Values: TRUE Activates demo mode FALSE Deactivates demo mode (default) The PINpad that will be used. This parameter is specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). Valid values: 0 (ppdVerifone_101) Verifone 101 or 1000 1 (ppdIVICheckMate_2100) Ingenico EN-CRYPT 2100 2 (ppdVerifone_2000) Verifone 2000 or Verifone SC5000(with Verifone 200 emulator) 3 (ppdVerifone_Everest) Verifone Everest 4 (ppdVerifone_SC5000) Verifone SC5000 (w/ 2000 emulation) 5 (ppdVerifone_3730) Verifone Omni 3730 Example: Device = 0 For Verifone Everest only. Sets message that will display on Pin Pad. Must be set before initializing or calling RefreshDisplay. Maximum length of characters that the Everest can display is 34. The Encryption method that will be used. This parameter is specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). Valid values: 0 (ppmMasterSession) Master Session encryption (only used with NOVA) 1 (ppmDUKPT) DUKPT (Derived Unique Key Per Transaction Example: EncryptMethod = 1 Contains the Master Key for Master Session encryption. Not all processors who do Master Session encryption will have a Master Key. Set MasterKey to "0" if no Master Key is present. Parity ("E" for even, "O" for odd, "N" for none) Number of the COM port to be used (Example: "1" used for COM port 1) For VeriFone Everest only. Refreshes display on Pin Pad to the DisplayString property. Must set DisplayString property before calling this method. For VeriFone Omni 3730 only. Cancels the application and closes the port. The number of seconds after which a timeout error will be returned from the control. The default timeout value is 15 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). Processors working key. This value is required for Master Session.

DefaultMessage

Demo

Boolean

Device

Enum

DisplayString

String

EncryptMethod

Long

MasterKey Parity Port RefreshDisplay ShutDownApp TimeOut WorkingKey

String String String String None Long String

These properties must be set before Initialize can be called. These properties must be set before GetPin can be called.

183

Device.OCX Methods
Method Name About Returned Value None Description - Device.OCX Methods The About method will display the About box associated with the control. The Cancel method attempts to cancel the GetPin method. Calling the Cancel method does not guarantee that GetPin will be canceled; it simply attempts to cancel the transaction. Returns TRUE if Cancel was successful, FALSE if not. This method will close the PINpads Com port. 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. The GetCard method returns the card number that was obtained when the GetCardSwipe method was called. The GetCardSwipe method can only be used for the IVI eN-Crypt 2100 and will wait for a card to be swiped with the PINpad. If the card is not swiped within the timeout value, a timeout will occur. The GetErrorCode method returns an error code if an error was encountered during the use of various methods such as the Cancel, Initialize, or GetPin. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetExpDate method returns the expiration date that was obtained when the GetCardSwipe method was called. Gets the Key Serial Number. Only used for DUPKT encryption. The GetMember method returns the cardholder's name that was obtained when the GetCardSwipe method was called. Gets the PIN from the PINpad. This will prompt the user to enter his/her PIN. GetPin will then return the encrypted PIN. GetPin will return nothing if a timeout or cancel occurs. The GetTrack1 method returns the track I data of the card that was obtained when the GetCardSwipe method was called. Only for the IVI eN-Crypt 2100. Currently, PCCharge does not support any Track 1 data for any processors. The GetTrack2 method returns the track II data of the card that was obtained when the GetCardSwipe method was called. Initializes the PINpad. 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.

Cancel

Boolean

Clear

Boolean

GetCard

String

GetCardSwipe

Boolean

GetErrorCode

Long

GetErrorDesc

String

GetExpDate GetKeySerialNumber GetMember

String String String

GetPin

String

GetTrack1

String

GetTrack2

String

Initialize

Boolean

Device.OCX Events
Event CardSwipe Description - Device.OCX Events Used only for the Verifone 2000(including SC5000 with 2000 emulator), Omni 3730, Everest. Once the PINpad is initialized and a card is swiped, this event will fire. Once the event fires, call the various get methods (GetCard, GetExpDate, GetTrack2, GetMember) to retrieve data from the magnetic stripe of the card. The Error event is fired any time an error occurs in the control. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

Error

184

SC550.OCX
The SC550.OCX allows integration to the Verifone SC5000 PINpad. The Verifone SC5000 PINpad is only used when performing Canadian Debit transactions with Global Payments East (NDC). Refer to the section Canadian (Interac) Debit Transactions (see page 77) for more information on using SC550.OCX to integrate Canadian Debit transactions.

185

SC550.PinSC550 Class Properties

Property Name Account ActionPending Data Type String Description SC550.PinSC550 Class Properties The bank account type

ENUM_ACTION_PENDING_INTERAC GPSActionP ENUM_ACTION_PENDING_MSR ENUM_ACTION_PENDING_NONE ending ENUM_ACTION_PENDING_PRINTER String This property contains the AppName of the PINpad. This data will be available once the GetSerialBlock method has been executed successfully. Example: [GPS/CA/CC/1.0b]. Provided for informational purposes only. Sets how often the PinSC550 class polls for the OMC and IMC (Out MAC and In MAC) files Format: Milliseconds Default Value: 1000. Determines whether the PinSC550 class will poll for and automatically process the OMC and IMC (Out MAC and In MAC) files in the PCCharge directory. Valid Values: TRUE enable automatic processing (recommended) FALSE disable automatic processing (default) Settlement number Baud Rate used to communicate with the PINpad. Default Value: 9600 This property will contain the Chip Serial Number of the PINpad. This field is populated by running the GetSerialBlock method. The Chip Serial Number is passed as a parameter to the Debit.OCXs GetPOSSequenceNumber method. This property contains the Chip Status of the PINpad. This data will be available once the GetSerialBlock method has been executed successfully. Example: 00. Provided for informational purposes only. Used to determine whether the PINpad communication monitor is displayed or hidden. Set to TRUE to display the monitor, FALSE to hide the monitor (default). The communication monitor is typically used to troubleshoot an integration to the PINpad. DataBits used to communicate with the PINpad. Default Value: 8 English or French for Canadian Debit The property will contain string data returned from the PINpad. This property is populated when performing various PINpad operations with the PINpad. For example, when the Interac response data is returned from PINpad, the data is available in this property.

AppName

AutoInterval

String

AutoProcess

Boolean

BatchCode Baud

String String

ChipSN

String

ChipStatus

String

CommVisible

Boolean

DataBits DefaultLanguageCode

String String String

DeviceData

DeviceState

GPSRespSt Returns the state of the PINpad. Valid return values are listed in the atus GPSRespStatus Values table (see below) String This property contains the Facility code of the PINpad. This data will be available once the GetSerialBlock method has been executed successfully. Example: 002. Provided for informational purposes only. This property contains the firmware version of the PINpad. This data will be available once the GetSerialBlock method has been executed successfully. Example: 1513. Provided for informational purposes only. This property contains the Kernel ID of the PINpad. This data will be available once the GetSerialBlock method has been executed successfully. Example: K1N8LE10. Provided for informational purposes only.

FacilityCode

FirmVersion

String

KernelID

String

KeyType

GPSKeyMan ENUM_DUKPT agementTyp ENUM_MAC ENUM_MASTERSESSION e Language Code used when communicating with and displaying messages on the PINpad. GPSLangCo Valid Values: de 0 English (default) 1 French

LanguageCode

186

Property Name MacBlock

Data Type String

Description SC550.PinSC550 Class Properties The MAC block returned from the PINpad. Once the RequestMAC method is called, this property will be populated with the MAC Block information that is returned from the PINpad. Parity used to communicate with the PINpad. Valid Values: E even O odd N None (default) PinBlock information from the PINpad. This property contains the PINpad type. This data will be available once the GetSerialBlock method has been executed successfully. Example: 001A. Provided for informational purposes only. Port Number to be used to communicate with PINpad. Default Value: COM1

Parity

String

PinBlock PinPadType

String String String

Port PortState

GPSRespSt Returns the state of the PINpads Port. Valid return values are listed in the atus GPSRespStatus Values table (see below) String This property contains the Prod Data of the PINpad. This data will be available once the GetSerialBlock method has been executed successfully. Example: 020605. Provided for informational purposes only. If ReMACing will need to occur, this property will contain the string that needs to be sent to the PINpad to retrieve the new MAC block. Use the RequestMAC method to request the new MAC block. If ReMACing is required this property will return TRUE, otherwise, this property will return FALSE. If TRUE, use the RequestMAC method to pass the string that appears in the ReMacData property to retrieve a new MAC block.

ProdData

ReMacData

String

RequireReMac

Boolean

RespCode

GPSRespCo Returns a value that indicates the status of various operations. Valid return de values are listed in the GPSRespCode Values table (see below) String Returns a string that is the English text that describes the GPSRespStatus enumerated value or code. Pass, as a parameter, either an enumerated value or code as defined in the GPSRespStatus Values table (see below). Returns a string that is the English text that describes the GPSRespCode enumerated value or code. Pass, as a parameter, either an enumerated value or code as defined in the GPSRespCode Values table (see below). This property contains the ROM Version of the PINpad. This data will be available once the GetSerialBlock method has been executed successfully. Example: 01. Provided for informational purposes only. The path to the directory in which the PCCharge executable resides. This property must be set prior to setting the AutoProcess property to TRUE.

ResponseAsString

ResponseCodeAsString

String

ROMVersion

String

ServerPath

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a \.

TimeOut

String

The Timeout value Default Value: 5 This property contains the Track II data from the card. This data will be available once the customer swipes a card in the PINpad. Note: The value will contain the sentinels (; and ?) that are captured from the magnetic stripe of the card. Example: ;1234123412341234=08121234123412340001? Note: The value between the ; and = is the card number. The first four digits after the = is the expiration date in YYMM format (Note: The expiration date must be sent to PCCharge in MMYY format). The last digit (the digit before the ?) is the language code. Chip Serial Number of the PINpad

TrackII

String

VFIBlock

String

Must be set correctly prior executing the Initialize method Properties used to enable the automatic processing of OMC files.

187

SC550.PinSC550 Class Methods

Method Name Base64Decode Base64Encode Cancel ClosePort DispBankResponse DispGenMsg DispObtainCard DispPrinterDown GetSerialBlock Returned Value String String None None None None None None None Description SC550.PinSC550 Class Methods Used to Base 64 decode a string that comes back from PCCharge. Only used if AutoProcess is disabled (not recommended). Used to Base 64 encode a string. Use this prior to sending info to PCCharge. Only used if AutoProcess is disabled (not recommended). Cancels the transaction. Closes the port that the PINpad is connected to. Displays the bank response. Displays a general message on the PINpad, 3 parameters, string, string, language code Displays text message onto the PINpad Obtain Card. Displays message onto the PINpad Printer Down. Obtains the Chip Serial Number from the PINpad. This method populates the ChipSN property with the PINpads Chip Serial Number. Initializes PINpad. The properties in the SC550.PinSC550 Class Properties table that are marked with a must be set correctly prior to calling the OpenPort and Initialize methods. If the AutoProcess property is set to FALSE (meaning that the integrator has chosen to manually process OMC and IMC filesNOT recommended), this method is used to verify the transaction response from the processor. If AutoProcess is set to TRUE, this method is not needed to process transactions. This method sends the data contained in the OMC file in the PCCharge directory to the PINpad for verification. Two parameters, the string from OMC file, and language code must be passed when calling this method. Before passing the string to this method, it must be decoded using the Base64Decode method. Used to load the key into the PINpad. Pass the key as a parameter. Enables the port for PINpad. This method must be called first. The properties in the SC550.PinSC550 Class Properties table that are marked with a must be set prior to calling the OpenPort and Initialize methods. This method is used to instruct the PINpad to prompt the customer to confirm the amount of the transaction, indicate the tip amount, indicate the bank account type, and enter their PIN. This method requires two parameters: The Interac request string (the string returned from clsInteracReq.BuildInteracRequest method) and the Language code of the card. Once the customer enters the data, the ActionEvent event will fire indicating the PINpad has returned the transaction-specific data such as the MAC block, the PIN block, the bank account type, and the tip amount. If ReMACing is required, this method is used to request a new MAC block from the PINpad. This method requires a parameter, the MAC data portion of the Interac request string, to be sent as a variable. Once the PINpad returns the new MAC block, the MacBlock property will be populated with the new MAC block value. Use the RequireReMac property in the PinSC550 class to determine if ReMACing must occur. If ReMACing is required, pass the data in the ReMacData property as a variable when using this method. Sends a command to the PINpad to prompt the customer to swipe their card. Once the card is swiped, the PINpad will read the magnetic data on the debit card, and then populate the TrackII property with the track II data from the card.

Initialize

None

InteracAnalysis

None

LoadKey OpenPort

None None

RequestInterac

None

RequestMAC

None

StartMSR

None

Must be called prior to executing the StartMSR method

188

SC550.PinSC550 Class Events

Event Description SC550.PinSC550 Class Events The ActionUpdate event will fire when the state of PINpad changes. Once the ActionUpdate event has fired, two values, eAction and eResp, are set and can be used to determine the current state of the PINpad. EAction will contain one of the values defined in the GPSPinPadAction Values table (see below) and eResp will contain one of the values defined in the GPSRespStatus Values table (see below). The value returned in eResp can be passed to the ResponseAsString method to provide an English description of the code.

ActionUpdate

GPSPinPadAction Values
Code 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 Enumerated Value GPSPinPadAction Values ENUM_ACTION_PORT_STATE_CHANGE ENUM_ACTION_INIT_PINPAD ENUM_ACTION_MSR_START ENUM_ACTION_MSR_STOP ENUM_ACTION_REQ_SERIAL ENUM_ACTION_DEVICE_STATE_CHANGE ENUM_ACTION_MSR_RECEIVED_DATA ENUM_ACTION_MSG_DISP_GEN ENUM_ACTION_MSG_DISP_OBTAIN ENUM_ACTION_MSG_DISP_BANKRESP ENUM_ACTION_MSG_DISP_PRINTERDOWN ENUM_ACTION_PTR_RECEIVED_DATA ENUM_ACTION_DEVICE_ACTION_CHANGE ENUM_ACTION_REQ_MAC ENUM_ACTION_REQ_INTERAC ENUM_ACTION_INTERAC_RECEIVED_DATA ENUM_ACTION_ANALYSIS_INTERAC ENUM_ACTION_KEY_LOAD ENUM_ACTION_AUTOPROCESS_CHANGE

GPSRespCode Values
Code -1 0 1 2 3 4 6 7 9 11 13 14 16 98 Enumerated Value GPSRespCode Values ENUM_RCODE_CLEAR ENUM_RCODE_SUCCESSFUL ENUM_RCODE_UNSUCCESSFUL ENUM_RCODE_TIMEOUT ENUM_RCODE_CANCELED ENUM_RCODE_CORRKEY ENUM_RCODE_INVALID_ACCTLEN ENUM_RCODE_MAC_NOVERIFY ENUM_RCODE_MAC_NOBLOCK ENUM_RCODE_KEY_DECRYPT_ERROR ENUM_RCODE_KEY_LOCATION_ERROR ENUM_RCODE_KEY_MTK_NOSELECT ENUM_RCODE_KEY_LOAD_FAIL_REVERT ENUM_RCODE_KEY_LOAD_FAIL_NOREVERT

189

GPSRespStatus Values
Code -35 -34 -30 -29 -28 -27 -20 -19 -18 -17 -16 -10 -9 0 1 2 3 4 Enumerated Value GPSRespStatus Values ENUM_STATUS_AUTOPROCESS_ON ENUM_STATUS_AUTOPROCESS_OFF ENUM_STATUS_PENDING_NONE ENUM_STATUS_PENDING_MSR ENUM_STATUS_PENDING_PRINTER ENUM_STATUS_PENDING_INTERAC ENUM_STATUS_DEVICE_IDLE ENUM_STATUS_DEVICE_PROCESS ENUM_STATUS_DEVICE_CANCEL ENUM_STATUS_DEVICE_WAITING ENUM_STATUS_DEVICE_INPUT_PENDING ENUM_STATUS_PORT_OPEN ENUM_STATUS_PORT_CLOSED ENUM_STATUS_OK ENUM_STATUS_INVALID_ACTION ENUM_STATUS_DEVICE_INPROCESS ENUM_STATUS_DEVICE_TIMEOUT ENUM_STATUS_UNKNW_ERROR

190

SC550.clsInteracReq Class Properties

Property Name Data Type Description SC550.clsInteracReq Class Properties After the ParseResponseData method has been called, this property will contain the customer-specified bank account type. Possible return values: A Chequing B Savings If this customer-specified bank account type is different that the bank account type specified in the AccType when building the Interac Request, a ReMAC must occur. Use the RequireReMac property in the PinSC550 class to determine if ReMACing must occur. The customers bank account type used when processing the transaction. 1 or ENUM_ACC_CHEQ Chequing 1 or ENUM_ACC_SAV Savings Note: When populating this property to build the initial Interac request string, the customers bank account type will not be known by the merchant (the customer will enter it once prompted). This value must be hard-coded. It is suggested to hard-code this value to 1 if most of the merchants customers use their checking accounts when purchasing products or 2 if most of the merchants customers use their saving account when purchasing products. Note: A new MAC value must be requested from the PINpad if the account chosen by the merchant differs from the account chosen by the customer. Use the RequireReMac property in the PinSC550 class to determine if ReMACing must occur. Amount String Set this property to the Amount of the transaction to be processed. This property should not contain any decimals or commas. Example: to specify a $1.00 transaction, set this property to 100 Set this property to the amount of the transaction. The amount specified is displayed to the customer for confirmation on the PINpad. This amount should include the decimal point and trailing zeros, if applicable. Example: to specify a $1.00 transaction, set this property to 1.00 After the ParseResponseData method has been called, this property will contain the MAC block information that was returned from the PINpad. After the ParseResponseData method has been called, this property will contain the customers encrypted PIN that was returned from the PINpad. The POS Sequence number. Set this property to the value that was returned by PCCharge when calling the GetPOSSequenceNumber method in the Debit.OCX control. Set this property to the Chip Serial Number of the PINpad. Use the GetSerialBlock method in the PinSC550 class to acquire the Chip Serial Number of the PINpad. After the ParseResponseData method has been called, this property will contain the optional customer-specified tip amount. If this property is populated with a value greater than 0, a ReMAC must occur. Use the RequireReMac property in the PinSC550 class to determine if ReMACing must occur. Determines if the PINpad will prompt the customer to enter a tip amount and also determines if the PINpad will display a suggested tip amount prior to prompting for the tip amount. Valid Values: 0 The customer is not prompted to enter a tip amount (Default) 1 The customer is prompted to enter a tip amount. 2 through 99 The PINpad will calculate a suggested tip amount and display it on the PINpad prior to prompting the customer for the tip amount. The integer value passed in represents the percentage that will be used to calculate the tip. For example, 20 would calculate a 20% tip amount. The customer would see this suggested tip amount and would then be prompted to key in the actual tip amount. Set this property to the track II data from the magnetic stripe of the card. For example: ;1234123412341234=08121234123412340001?

Account

String

AccType

String

DisplayAmount

String

MacBlock PinBlock

String String

SequenceNum

String

TermID

String

TipAmount

String

TipType

Integer

TrackII

String

191

Property Name

Data Type

Description SC550.clsInteracReq Class Properties

TransCode

Set this property to the type of transaction being processed. This should be set GPSTransC to the same transaction type specified in the TransNameID property. ode 0 or ENUM_TCODE_PURCH_NORM Purchase (default) 4 or ENUM_TCODE_REFUND Refund Set this property to the type of transaction being processed. The property indicates to the PINpad to displays the type of transaction being processed to the customer. This should be set to the same transaction type specified in the GPSTransID TransCode property. Valid Values: 0 or ENUM_TID_PURCH Displays PURCHASE (default) 1 or ENUM_TID_REFUND Displays REFUND String After the ParseResponseData method has been called, this property will contain the PINpads Chip Serial Number.

TransNameID

VFISerial

These properties must be set prior to calling the BuildInteracRequest method. These properties will be set after the ParseResponseData method completes successfully.

SC550.clsInteracReq Class Methods

Property Name BuildInteracRequest BuildRemacData ClearData Returned Value String String None Description SC550.clsInteracReq Class Methods Builds and returns the Interac request string that will be sent to the PINpad. The properties in the SC550.clsInteracReq Class Properties table that are marked with a must be set prior to calling this method. Used internally The ClearData method will clear the values in all properties. Parses the Interac response string returned by the PINpad. The response string is returned by the PINpad in the DeviceData property of the PinSC550 class. If the string is parsed successfully, TRUE is returned, FALSE otherwise. When the string is parsed successfully, the properties marked with a in the SC550.clsInteracReq Class Properties table will be populated with the customer entered data.

ParseResponseData

Boolean

192

SC5X.OCX
The SC5X.OCX allows integration to the Verifone SC5000 PINpad. The Verifone SC5000 PINpad is only used when performing Canadian Debit transactions with Chase Paymentech (GSAR). Refer to the section Canadian (Interac) Debit Transactions (see page 77) for more information on using SC5X.OCX to integrate Canadian Debit transactions.

193

SC5X.OCX Properties
Property Name Action Amount Baud Command CommMethod Data Type String String String String Integer String Description SC5X.OCX Properties Transaction Action Code Transaction Base Amount Baud Rate used to communicate with the PINpad. Default Value: 9600 Transaction Action Code Defines the Method that the OCX will send the transaction to PCCharge 0 INX File Method 1 TCP/IP (For Future Use) DataBits used to communicate with the PINpad. Default Value: 8 Parity used to communicate with the PINpad. Valid Values: E even O odd N None (default) Timeout value for the PinPad Default Value: 5 Port Number to be used to communicate with PINpad. Default Value: COM1 The IP address of PCCharge. Only used when using the TCP/IP portion of the SC5X.OCX For Future Use The port used to communicate with PCCharge. Only used when using the TCP/IP portion of the SC5X.OCX For Future Use The path to the directory in which the PCCharge executable resides. This property must be set prior to setting the AutoProcess property to TRUE. ServerPath String Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a \. SurchargeAmount SwipeTimeout Ticket TimeOut String String String String Surcharge Amount assigned to the transaction. This is inputted for each transaction and is not to be included in the amount. The amount of time the pinpad will wait for a card swipe. Default Value: 255 (seconds) Ticket The Timeout value for the Transaction Default Value: 90 Used to determine if PINpad will prompt for gratuity. Only used with the S21 action code. Valid Values: True - Prompt for gratuity False - Do not prompt for gratuity Used to determine if PINpad will prompt for cash back. Only used with the S21 action code. Valid Values: True - Prompt for cash back False - Do not prompt for cash back Used to determine whether the PINpad communication monitor is displayed or hidden. Set to TRUE to display the monitor, FALSE to hide the monitor (default). The communication monitor is typically used to troubleshoot an integration to the PINpad. Note: Only for use in development environment.

DataBits

Parity

String

PinPadTimeout Port IPAddress TcpIPPort

String String String String

RequestTip

Boolean

RequestCashBack

Boolean

CommVisible

Boolean

Must be set correctly prior executing the Initialize method

194

SC5X.OCX Methods
Method Name Cancel CancelPin Returned Value None None Description SC5X.OCX Methods Cancels the transaction. Cancels the pin pad request Initializes PINpad. The properties in the SC5X.OCX Class Properties table that are marked with a must be set correctly prior to calling the OpenPort and Initialize methods. The initialize command will attempt to initialize the PINpad 3 times prior to returning a response. Returns the result, which indicates the transactions status upon completion. The GetApproved method returns TRUE if PCCharge returns "APPROVED" as the result of the transaction. Otherwise, FALSE will be returned. 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. 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, and that the transaction has been placed in the open batch. Returns the cash back entered by the card holder. The GetErrorCode method returns an error code if an error was encountered during the use of various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned Returns the merchant number that was specified in the MerchantNumber property. Returns the required receipt data, including tip amount. Returns the reference number associated with the transaction. 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. Returns the tip amount entered by the card holder. 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. See the section Follow On Transactions for more information. Returns the Raw XML from the oux response Enables the port for PINpad. This method must be called first. The properties in the SC5X.OCX Class Properties table that are marked with a must be set prior to calling the OpenPort and Initialize methods. Closes the port and shuts down the OCX timer.

Initialize

None

GetResult GetApproved

String Boolean String

GetAuth

GetCaptured

Boolean

GetCashBack GetErrorCode

String Long

GetErrorDesc

String

GetMerchantNumber GetReceipt

String String String String

GetRefNumber

GetTipAmount

GetTroutD

String

GetXMLResponse OpenPort Shutdown

String None None

195

Method Name

Returned Value

Description SC5X.OCX Methods This method communicates with the Pinpad. Card number and expiration date are not required to be assigned to the pinpad before calling this method. This method requires the following properties of the OCX to be set: MerchantNumber Processor Action/Command Amount Path The following properties are optional but must be set if used. Ticket CashBack SurchargeAmount CommMethod Language TroutD Timeout Baud Parity PinPadTimeout Example: Send 3 Once this is called, the Pinpad will have the MSR function called. The merchant/customer swipes the card, then the pinpad gets reset to "ready". If successful, the function returns true. Then, the integrator can call: GetCard GetMember GetExpDate GetTrack If unsuccessful, the function returns false. Then, the integrator can call: GetErrorCode GetErrorDesc This is the same as RetrieveCreditSwipe, yet the processor code must be passed in. Example: .RetrieveGiftCardSwipe("VLNK"). Once this is called, the Pinpad will have the MSR function called. The merchant/customer swipes the card, then the pinpad gets reset to "ready". If successful, the function returnes true. Then, the integrator can call: GetCard GetMember GetExpDate GetTrack If unsuccessful, the function returns false. Then, the integrator can call: GetErrorCode GetErrorDesc

Send

None

RetrieveCreditSwipe

Boolean

RetrieveGiftCardSwipe

Boolean

196

SC5X.OCX Error Codes

ErrorCode -1 -2 -3 -4 -5 -6 -7 -8 -9 -10 -11 -12 -13 -14 -15 -16 -17 -18 -19 -20 -21 ErrorDescription Port Open Error Invalid Command Invalid Amount Invalid Baud Invalid Port Invalid Parity Invalid Databits Invalid Path Invalid Processor Invalid Merchant Number Invalid Card Invalid Expiration Date Chip Serial Number Error Key Change Request Was Required. Retry Transaction. Card Swipe Error Confirm Amount Error Surcharge Was Rejected Pin Error Initialization Error Invalid Swipe Timeout Card Swipe Timeout Description The OCX could not open the port to the pinpad The Command is not currently supported by the ocx The amount was not set or was in an incorrect format The baud was not set or was in an incorrect format The pinpad port was not set or was in an incorrect format The pinpad parity was not set or was in an incorrect format The pnpad databits were not set or was in an incorrect format The Path was not set Processor is not supported for Interac with this OCX (currently only Chase Paymentech) Merchant Number is not a valid Merchant Number for the selected processor (currently only Chase Paymentech) Credit Only. This card does not pass the Luhn Check. Expiration Date is expired or invalid The OCX could not obtain the Chip Serial Number from the Pinpad A Current Key Request was required and has finished. Continue with the original transaction. The card swipe did not return the correct information There was an error in the Confirm Amount dialogue of the pinpad. The customer rejected the surcharge amount. There was an error obtaining the Pin Block The OCX was unable to initialize the pinpad The passed in Swipe Timeout exceeds 255 seconds. This is the length of time that the pinpad will sit at "Swipe Card" Card was not swiped within timeout value

Notes: In order to test Canadian Debit with Chase Paymentech (GSAR), the integrator will need to obtain a test merchant account directly from Chase Paymentech (GSAR) and a VeriFone SC5000 PINpad that is configured properly for use with Canadian Debit and the Chase Paymentech (GSAR) test merchant account. MAC data is specific to the PINpad and merchant number. If EBT transactions will be supported, a separate PINpad device is required.

197

Reporting
The Charge.OCX control may be used by integrators to submit report requests. A report request can have PCCharge print a report to its default report printer or have PCCharge generate a file containing the report output. If generating a file, the PCCharge reporting interface supports three different file types: 1. Portable Document Format (.pdf) 2. Rich Text Files (.rtf) 3. Standard Text files (.txt) Note: The reporting interface cannot be configured to send reports directly to the screen. The following outlines the properties used for submitting report requests to PCCharge with the Charge.OCX control. The properties in Charge.OCX that are not documented below should be left blank when submitting report requests.
Property Data Type Long Description Charge.OCX Reporting Properties The action code that identifies what type of report will be requested. Valid Values: 81-84. Example: If running a credit card detail report, set the action code to 81. Consult the section DevKit Constants for a list of valid values (see page 94). User name filter. If a valid user name is set in the Card property, the report will be filtered by that user name. The report returned will consist of only those transactions processed by the user name specified. Example: User1. If this property is left blank, the report will show transactions processed by all users. Flag that indicates whether to activate credit card validity testing. Valid Values: TRUE; FALSE. Default value: TRUE. This value must be set to FALSE when submitting a report request. Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. For use with TCP/IP CommMethod only. SSL is not yet available with PCCharge. Leave this set to false. For use with TCP/IP CommMethod only. IPAddress of machine where PCCharge is running. Defaults to 127.0.0.1 Result filter. Use this filter to create a report consisting of only those transactions with the result specified. Valid Values: 0 = all (default), 1 = approved, 2 = declined Example: 1 Ending Date/Time filter. Specifies the end date and end time of the report. Format: Date: MM/DD/YY Time: HH:MM:SS PM. When used in conjunction with Street; will create a report consisting of only those transactions processed between the start and end date/time specified (inclusive). If an end date is not specified, todays date is assumed. If an end time is not specified, 11:59:59 PM is assumed. The end date can be passed without the end time. However, the end time cannot be passed without the end date. Examples: 07/06/05 06:00:00 PM or 07/06/05 Merchant Number filter. Set this property to filter the report by the merchant number specified. Setting this property will generate a report consisting of only those transactions processed via the merchant number specified. To generate a report that includes all merchant numbers in PCCharge, set this property to ALL or leave blank. Example: 99999999911

Action

Card

String

CheckCard

Boolean

CommMethod

Enum

EnableSSL IPAddress

Boolean String Long

Manual

Member

String

MerchantNumber

String

198

Property

Data Type

Description Charge.OCX Reporting Properties For use with File_Transfer CommMethod only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a \.

PeriodicPayment

String String

Report Output setting. Determines if the report will be printed by PCCharge or written to a file. Valid Values: 0 = print to default printer specified in PCCharge (default). 1 = print to file using filename specified in TransID and path specified in TRACK. For use with TCP/IP CommMethod only. Open port of PCCharge. Starting Date/Time Filter (Optional) Specifies the start date and start time of the report. Format: Date: MM/DD/YY Time: HH:MM:SS PM. Use to create a report consisting of only those transactions processed on or after the date specified. If a start date is not specified, today's date is assumed. If a start time is not specified, 12:00:00 AM is assumed. The start date can be passed without the start time. However, the start time cannot be passed without the start date. Examples: "03/04/05 09:00:00 AM" or 03/04/05 The number of seconds after which a timeout error will be returned from the control. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). Destination Directory for Report File. Specifies the destination directory where the report file will be generated by PCCharge (if PeriodicPayment is set to "1"). Example: C:\My Documents\PCCReports\ Path Formats: UNC, MS-DOS(8 Characters) and Long. Max Length: 40 characters (if the Destination Directory is longer than 40 characters, use CustCode for the additional characters. Must end with a "\" unless the directory name will be continued in the CustCode property. Note: If running in a Client/Server environment, this property is the path from the server running PCCharge, not the client. For example, if a client submitted a report request that specified C:\ as the destination directory, the report would be written to the local hard drive of the server running PCCharge, not to the clients hard drive.

Port

Street

String

TimeOut

Long

Track

String

CustCode

String

Destination Directory for Report File (continued). Continuation of the destination directory (if the directory name is greater than 40 characters). Max Length: 25 characters. Must end with a "\" Report File name/Report File Type. Specifies the filename and extension of the report file generated by PCCharge (if PeriodicPayment is set to "1"). Also determines what file type will be used when PCCharge generates the report. To specify the file type, set the extension to one of the following: .pdf Create the report file in the Portable Document Format. Ex. Report.pdf .rtf Create the report file in Rich Text. Ex. Report.rtf .txt Create a report file in flat text. Ex. Report.txt Default: .txt (If an extension other than the ones listed is passed, the report will be returned as flat text and a .txt extension will be added to the filename) 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 more information on user names, consult the Multi-User Support section (see page 50).

TransID

String

User

String

These properties are required to submit a report request.

199

The following outlines the methods used to process report requests. The methods in Charge.OCX that are not documented below will not be used when processing report requests.
Method Returned Value Boolean Description - Charge.OCX Reporting Methods The Abort method attempts to cancel the transaction in progress and will return a Boolean value that indicates whether or not the transaction was canceled. Note: This method is not available when integrating using FoxPro. Use the Cancel method instead. The About method will display the About box associated with the control. 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. The Clear method will clear the values in all properties and methods. It is recommended that this method be called: a. after the transaction results have been retrieved by using the various .get methods b. after the DeleteUserFiles method has been called c. prior to running the next transaction The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). For use only with File_Transfer CommMethod 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. 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. For use only with File_Transfer CommMethod

Abort

About Cancel

MsgBox None

Clear

None

DeleteUserFiles

None

GetAuth

String

GetErrorCode

Long

GetErrorDesc

String

GetResult

String

PccSysExists

Boolean

200

Method

Returned Value

Description - Charge.OCX Reporting Methods The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the control will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above. The VerifyMerchantNumber method returns TRUE if the merchant number that is passed to it is set up in PCCharge, otherwise, FALSE is returned. Specifically, this method checks for the merchant number in the file TID.PCC, which is located in the PCCharge directory. The Path property must be set before calling this Method.

Send

Integer

VerifyMerchantNumber

Boolean

Charge.OCX Events
Event Error Description - Charge.OCX Events The Error event is fired any time an error occurs in the control. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the Transaction Result Constants section (see page 103).

Finish

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

201

DLL (ActiveX) Method

A DLL called PSCharge.dll is included in the DevKit. This DLL allows developers to access various processing functions using any Windows-based programming environment that supports referencing ActiveX DLLs. Before PSCharge.dll can be used, it must be added as a reference in the programming environment. For example, in Microsoft Visual Basic 6, follow the procedure below: 1. Choose Project | References from the Visual Basic menu bar. 2. After the References window opens, from the list, scroll to and check the box next to: VeriFones ActiveX Payment Server DLL

and click OK. (The DevKit installation registers the PSCharge.dll by default. If PSCharge.dll is not yet registered on the system, use regsvr32.exe to register it, or use the Browse button on the References window to register PSCharge.dll and add it as a reference to the project). Once registered, PSCharge.dll provides the developer with several classes to allow the integration of payment processing: Charge contains properties and methods for credit card processing Debit contains properties and methods for debit and EBT processing. Check contains properties and methods for check processing. Gift contains properties and methods for gift/loyalty processing. Batch contains properties and methods for performing end-of-day inquiry and batch settlement. Offline contains properties and methods for processing offline transactions.

The properties and methods of the DLLs various classes can be viewed through the object browser. If MS VB6 is not being used, refer to the language documentation for instructions on using ActiveX DLLs. Note: The additional classes in PSCharge.dll that do not appear in the list above are currently not supported for transaction processing.

Using PSCharge.dll
Create an instance of any of the DLLs classes by using the following line of code: Set <instance name> = New <object name>

For example, to create an instance based on the Charge class, the following line of code would be used in MS VB6: Set Charge = New PSCharge.Charge

202

Charge Class
The Charge class provides integrators with properties and methods used to submit credit card transactions to PCCharge. To use the Charge class to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the transaction to be performed and validate the values using the various .Verify methods. (The properties marked with a in the Charge Class properties table are the minimum required to process a Sale or Pre-Authorization transaction.) 3. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format) 4. Wait for the transaction to process and then call the various .Get methods to determine the outcome of the transaction (code using the .Get methods may be placed immediately after the Send method). The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error. 5. Call the DeleteUserFiles method to delete all files related to the transaction. 6. Call the Clear method to reset all the properties and methods related to the transaction or destroy the object. Consult the section Pseudo-code (see page 105) for various examples that may be followed when using the Charge class to perform transaction processing. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

203

Charge Class Properties

Property Action Data Type Long Description - Charge Class Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder must be sent as well. Example: 0.50. 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 American Express Description data. Additional description or information about merchandiseif 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 . American Express Description data. Additional description or information about merchandiseif 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 . American Express Description data. Additional description or information about merchandiseif 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 . American Express Description data. Additional description or information about merchandiseif 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 . The Authorization code. This value is returned by the issuing bank and should only be set in a transaction request 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, see page 63). 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. See the section Follow On Transactions for more information (see page 58). Only valid for Visa debit and credit transactions. It is used to indicate the transaction is being ran for payment of a bill (ultilty, monthly gym dues, etc.) Valid values: 0 Non-Bill payment transaction 1 Bill payment transaction The credit card number that will be used when processing the transaction. Max Length: 20 characters. Example: 5424180279791765 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)

Amount

String

AmxChargeDescription

String

AmxDescription_1

String

AmxDescription_2

String

AmxDescription_3

String

AmxDescription_4

String

AuthCode

String

Billpay

String

Card

String

CardPresent

String

204

Property

Data Type Boolean

Description - Charge Class Properties Flag that indicates whether to activate credit card validity testing. Valid Values: TRUE; FALSE. Default value: TRUE. This value must be set to FALSE when performing Follow on transactions such as Voids or Gratuities because the card number is omitted from these transaction requests. The action code that identifies what type of transaction will be performed. Valid Values: 1-10, 13-15, ZI, ZH. Example: If running a credit card sale, set the action code to 1. Consult the section DevKit Constants for a list of valid values (see page 94). Note: Because the Action property is defined as long, this property was added to allow action codes that contain strings (such as Transaction Inquiry - ZI). If the Command property is set, its value will override the value set in Action. The type of commercial card being submitted. The getCommercialCardType method should be used to retrieve the 1 character value from PCCharge that indicates what type of commercial card will be submitted. See the section Commercial Card Transactions (see page 65) for more information. Max Length: 1 character Valid values: B Business P,L,G -- Purchase C Corporate F Fleet Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. 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 transactions 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. The credit plan number, only applicable when using Citi as the processor for private label cards. 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 nonswiped transactions. The demo mode flag. In demo mode, a simulated response is returned in which even amounts return approved, and odd amounts return declined. Valid Values: TRUE Activates demo mode FALSE Deactivates demo mode (default) 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 transactions action code must indicate that the transaction is a commercial card transaction. Driver identification field. Only required for Wright Express, Voyager and Fleet One cards. Driver personal identification number. Only required for Fuelman cards.

CheckCard

Command

String

CommercialCardFlag

String

CommMethod

Enum

CustCode

String

CreditPlanNumber

String

CVV2

String

Demo

Boolean

DEST_ZIP_CODE

String

DriverID DriverPIN

String String

205

Property

Data Type

Description - Charge Class Properties 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 place holder must be sent as well. See the section Restaurant Transactions (see page 69) 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. The expiration date associated with the credit card number that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 For use with TCP/IP CommMethod only. SSL is not yet available with PCCharge. Leave this set to false. For use with Restaurant transactions only. The actual gratuity amount for a Sale with Gratuity (action code 14) , Gratuity (action code 13) , or PostAuthorization (action code 5) transaction. See the section Restaurant Transactions (see page 69) for more information. Only required for Voyager cards, dependant on Restriction Code. Four to six digits. Note: Only used for Pre-Authorization transactions The Merchant Number index. If Index is set to a value greater than 0, the Charge class will access the file tid.pcc file and use the merchant number at that index in the file. Index and Path should be set prior to calling the GetCompanyCity, GetCompanyName, GetCompanyState, GetCompanyStreet, or GetCompanyZip methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. For use with TCP/IP CommMethod only. IPAddress of machine where PCCharge is running. Defaults to 127.0.0.1 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. The last year that will be considered a valid expiration date. Currently, the default value in the charge class is 09. It is recommended that a setting is provided by which the end-user can change this property; otherwise, in the future, end users will require a new PSCharge.dll to be distributed to resolve expiration date issues. Length: 2 digits. Format: YY Example: If LastValidDate is set to 05, then cards between 06 and 99 are considered to be 1906 to 1999, and cards between 00 and 05 are 2000 to 2005. Flag that indicates whether the transaction was manually entered or swiped. If the transaction was swiped, the Track property must also be set. Valid values: 0 = manual transaction, 1 = swiped transaction 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.

EstGratuityAmount

String

ExpDate EnableSSL

String Boolean

GratuityAmount

String

IDNumber

String

Index

Long

IPAddress

String

ItemID

String

LastValidDate

String

Manual

Long

MCSC

String

206

Property

Data Type

Description - Charge Class Properties 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 (see page 69) 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. The cardholders name. Max Length: 20 characters. The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Credit Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. No Longer Supported. 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line. The odometer reading. Only required for Fleet One (7 digits), Voyager (7 digits), and Fuelman (6 digits) cards. 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 The delay time before the PCCharge directory is polled for a transaction response file (.oux file). The default is 0.25 seconds. This value should only be modified if the integration is not performing properly. This could be caused if the client machine is slow or there is network lag that causes the server to spend more time checking for .oux files than processing transactions. For use with File Transfer CommMethod only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

MCSN

String

Member

String String Boolean

MerchantNumber *** MTS

Multi

String

Odometer

String

OffLine

String

OutDelay

Single

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a \.

PeriodicPayment

String String 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. For use with TCP/IP CommMethod only. Open port of PCCharge. 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. 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 the Processing Company Codes section (see page 101).

Port

PrintReceipts

Processor ***

String

207

Property

Data Type

Description - Charge Class Properties Note: Only required for the processor NBS. This is the total dollar amount for PRODUCT_DETAIL_PRODUCT_CODE_XX 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 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. Note: Only required for the processor NBS. This is the number of items for PRODUCT_DETAIL_PRODUCT_CODE_XX. Currently, PCCharge will support 0 1 10. Note: Only used for the processor NBS. This is the unit price for PRODUCT_DETAIL_PRODUCT_CODE_XX. This is only used for Fleet One and Fuelman. Currently, PCCharge will support 01 10. 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, see page 63). The Reference property does not need to be set if the PostAuthorization completes a standard Pre-Authorization using the TroutD value of the Pre-Authorization. See the section Follow On Transactions for more information (see page 58). 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. 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. Set to 1 if card information was read from RFID (Radio Frequency Identification) device. If card was read from from RFID, track data must be populated and manual flag must be set to 1. Set to 0 otherwise. Flag indicating whether a Voice Authorization transaction should be stored. This flag should only be submitted when performing a Post-Authorization transaction (action code 5) that includes an authorization code from the voice operator. For more information on stored Voice-Authorizations, see page 63. Valid Value: 1 - Store the Voice Authorization transaction. The cardholder's billing street address. The Street property is used for address verification. Address verification can only be performed on nonswiped 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 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. 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.

ProductDetailAmount_XX

String

ProductDetailCount

String

ProductDetailCode_XX

String

ProductDetailQuantity_XX

String

Reference

String

RestrictionCode

String

RFID

String

Store

String

Street

String

TaxAmt

String

TaxExempt

Boolean

208

Property

Data Type

Description - Charge Class Properties 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 NOVA, ticket numbers can only be alphanumeric, no hyphens. The number of seconds after which a timeout error will be returned from the class. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. No longer needed The track II data captured from the magnetic strip of the credit card. The track II data is required to ensure the lowest per-transaction rate from the processing company when performing swiped transactions (Retail and Restaurant). Sending the track II data is not allowed if the merchant's industry type is MOTO or eCommerce. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in. Alternatively, the GetParseData method can be used to parse the track data and set the Card, ExpDate, and Track properties automatically. 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50). Only required for Wright Express cards (5 digits) and Voyager cards (8 digits). Note: Required for both manual and swiped transactions. Set to True to activate the XML message format. It is recommended that the 3 parameter be passed to the Send method to activate the XML message format instead of using the XMLtrans property. See the description for the Send method for more information. The cardholder's zip code. The Zip property is used for address verification. Max Length: 9 digits. Address verification can only be performed on nonswiped transactions. 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. The database archive configuration type setup in PCCharge. Valid value: Currently, only 0 is supported.

Ticket

String

TimeOut

Long

TotalAmount

String

Track

String

TroutD

String

User **

String

VehicleID

String

XMLtrans

Boolean

Zip

String

CfgType

Long 0 = CFG_TXN_ARCHIVE = Configure Transaction Archive. Use action code ZC.

CfgEnabled CfgPath CfgSizeLimit

Boolean String String String

Enable or disable current database archive configuration (1 = Enable, 0 = Disable). Specify path for saved output files (Example: backed up transaction database). Must end with a backslash \. Transaction archive size limit for GUI archive prompting and validation. Specified in megabytes. Transaction archive preservation range. All transactions within the past number of keep days will remain in the pccw.mdb database following a transaction archive command.

CfgKeepDays

These properties are the minimum required to process a Sale or Pre-Authorization transaction.

209

** 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 (see page 50). 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. Consult the Multi-Merchant Support section (see page 56) for more information on the Use Default Processor option. In addition, Processor and MerchantNumber should not be set when doing follow-on transactions. Refer to the section Follow On Transactions (see page 58) for more information.

Charge Class Methods

Method Returned Value String Description - Charge Class Methods The AddMatch method returns a string representation of the address verification response received from PCCharge. The address response code will be used to determine what string should go into AddMatch. 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. The Clear method will clear the values in all properties and methods. It is recommended that this method be called: a. after the transaction results have been retrieved by using the various .get methods b. after the DeleteUserFiles method has been called c. prior to running the next transaction The CommercialCardType method is used to determine whether or not a credit card is a commercial card. CommercialCardType requires that a string parameter, the credit card number, is passed when calling the method, that the Path property is set to a valid PCCharge directory, and that a valid Bin.mdb database resides in that directory. CommercialCardType returns TRUE if the BIN range of the card appears in the Bin.mdb database, FALSE if it does not. The CVV2Match method returns a string representation of the card verification response that is received from PCCharge. The card verification response code will be used to determine what string should go into CVV2Match. For use with File Transfer CommMethod only. The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). Returns the entry method of the transaction. 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. Only supported on Fleet One, this field contains miscellaneous additional text returned from host. Currently PCCharge will support GetAddText1GetAddText4. 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.

AddMatch

Cancel

None

Clear

None

CommercialCardType

String

CVV2Match

String

DeleteUserFiles

None

GetAcctDataSrc GetACI

String String

GetAddText1

String

GetAuth

String

210

Method

Returned Value

Description - Charge Class Methods 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 the section DevKit Constants for a description of values that may be returned (see page 94) Returns the PrePaid card balance. Only for pre-paid credit cards with NOVA. 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, and that the transaction has been placed in the open batch. Returns a code that is used to verify the identity of the cardholder. The getCommercialCardType method requires a string parameter, the credit card number, and will determine the credit card numbers commercial card type. This method requires that the Path variable be set to a valid PCCharge directory and it uses the Bin.mdb database in the PCCharge directory to determine the commercial card type. Valid return values: B Business P,L,G -- Purchase C Corporate F Fleet Example: getCommercialCardType(4055011111111111) will return P. The GetCompanyCity method returns the city of the merchant that is registered in PCCharge. The Index and Path properties must be set correctly for this method to work. The GetCompanyName method returns the company name of the merchant that is registered in PCCharge. The Index and Path properties must be set correctly for this method to work. The GetCompanyState method returns the state of the merchant that is registered in PCCharge. The Index and Path properties must be set correctly for this method to work. The GetCompanyStreet method returns the street address of the merchant that is registered in PCCharge. The Index and Path properties must be set correctly for this method to work. The GetCompanyZip method returns the zip code of the merchant that is registered in PCCharge. The Index and Path properties must be set correctly for this method to work. The GetCreditCardIssuer method returns the abbreviation of the credit card issuer's name for the card number that is present in the Card property. Consult the section DevKit Constants for a description of values (see page 94). The GetCreditCardType method returns either the abbreviation of the credit card issuer of the card that is present in the Card property, or the optional card parameter that is passed to the GetCreditCardType method. Consult the section DevKit Constants for descriptions of values (see page 94). (GetCreditCardType is the same as GetCardIssuer). Returns the available balance on pre-paid debit cards. Only for pre-paid debit cards with NOVA. 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 the section DevKit Constants for a description of values that may be returned (see page 94)

GetAVS

String

GetCCAvailBalance

String

GetCaptured

Boolean

GetCardIDCode

String

getCommercialCardType

String

GetCompanyCity

String

GetCompanyName

String

GetCompanyState

String

GetCompanyStreet

String

GetCompanyZip

String

GetCreditCardIssuer

String

GetCreditCardType

String

GetDCAvailBalance

String

GetCVV2

String

211

Method

Returned Value

Description - Charge Class Methods 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetEstGratuityAmount returns the estimated gratuity amount of the original transaction. The GetGratuityAmount returns the gratuity amount of the original transaction. The GetHostType method returns an integer that indicates if a processor / merchant number is Host based or Terminal based. GetHostType requires three parameters: 1) Processor code - Consult the section DevKit Constants (see page 94) for a list of valid processor codes 2) Merchant account - Must be a valid merchant account set up in PCCharge 3) TID type - Valid Values for TID type: 0 Credit; 1 Check; 2 Debit; 3 EBT; 4 GiftCard GetHostType will return one the following values based on the parameters passed in: 0 The processor is Host based 1 The processor is Terminal based -1 The processor is a Hybrid (supports both Host and Terminal processing) or invalid processor / merchant number. Example: .GetHostType(VISA, 999999999911, 0) will return 0 Note: Chase Paymentech (GSAR), NOVA (NOVA), and FDMS South / NaBanco (NB) are considered hybrid processors. GetHostType will return a -1 for these processors. 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. The GetIndex returns the index of the Processor and MerchantNumber combination that is stored in PCCharge file tid.pcc. The GetIndex function will not work property if valid Path, Processor, and MerchantNumber properties are not provided. The GetItemID echoes the item ID from the original transaction. Returns the Market Specific Indicator. This value indicates the transactions market segment. This value is assigned by the card associations and is not returned with all transactions. Returns the merchant number that was specified in the MerchantNumber property. The GetParseData method will parse a string (containing credit card track data) passed to it and populate the Card, ExpDate, and Track properties with the appropriate data. GetParseData will return an integer indicating its success. Valid return values: 0 (error parsing data), 1 (track I successful), or 2 (track I & II successful). Retrieves the private label Processor ID currently setup in PCCharge. The .path property must be specified. Retrieves the private label Merchant Number currently setup in PCCharge. The .path property must be specified. The GetPCard method returns the PurchaseCard field from the .oux file. Not all processors support this field. Valid Values: 1 = purchasing card, 0 = otherwise Returns the Point of Entry Mode that is associated with the transaction. This value is not returned by all processing companies.

GetErrorCode

Long

GetErrorDesc

String

GetEstGratuityAmount GetGratuityAmount

String String

GetHostType

Integer

GetIND

String

GetIndex

Long

GetItemID GetMSI

String String String

GetMerchantNumber

GetParseData

String

GetPLProcessor GetPLMerchantNumber

String String String String

GetPCard

GetPEM

212

Method

Returned Value

Description - Charge Class Methods PS2000 Data. This data will be as received during the original authorization processing. It will not be present for offline transactions. PS2000 Data is a variable; it will either be one character or up to 20. It is data concerning the card type and transaction that the processor will send back during the authorization process. This value is not returned by all processing companies. The number of records matching the inquiry Only used for CITI private label cards. Returns the disclosure agreement. 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. Returns the response code that is provided by the processor. This value is not returned by all processing companies. Returns the type of commercial card that was used for the transaction. This value is not returned by all processing companies. Returns a flag indicating whether the processor indicated whether the card was a Purchasing Card or not. This value is not returned by all processing companies. Valid values: 1 = Purchasing Card, 0 = Otherwise Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. Note: Only supported on Fleet One. The product restriction code. Returns the Retrieval reference number. This value is not returned by all processing companies Returns the active batch number for the transaction. This value is not returned by all processing companies. Returns the date that the transaction was processed. This value is not returned by all processing companies. This will indicate the transaction Identifier for VISA or AMEX, it will also return the MC Bank Net reference if the card is a MasterCard. This value is not returned by all processing companies. 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. 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. Returns the Time of the transaction. This value is not returned by all processing companies. Returns the trace number from the processor. Only for pre-paid credit cards with NOVA. Returns the Transaction Item number or the number that is associated with the transaction in the settlement file. This value is not returned by all processing companies. Contains nested XML tags providing information on transaction(s) pulled from Trans table in the PCCharge database (pccw.mdb) Returns the transaction reference number from the processor. Only for prepaid credit cards with NOVA. 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. 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. See the section Follow On Transactions (see page 58) for more information.

GetPS2000

String

GetRecordCount GetReceipt

String String String

GetRefNumber

GetRespCode GetResponseCommercialType

String String

GetResponsePurchaseCardType String

GetResult GetRestrictCode GetRet GetTBatch GetTDate

String String String String String String

GetTI

GetTicket

String

GetTICode GetTIM GetTraceNumber

String String String String String

GetTitem

GetTransRecord

GetTransactionReferenceNumb String er GetTransNum String

GetTroutD

String

213

Method

Returned Value

Description - Charge Class Methods 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 from the .oux file can be used to view the results of a Transaction Inquiry (ZI) transaction. Refer to the section Transaction Inquiry (see page 85) for more information. The text can also be used by integrators that wish to parse the results of the transaction themselves or for troubleshooting purposes. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. 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. For use with File Transfer CommMethod only. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: (TTYPE_XML) XML message format (RECOMMENDED) Example: Send 3 Note: The other values that appear in the enumerated list are for internal use onlydo not attempt to use any values other than the ones listed above. The ValidCardLength method returns true if the card is of the correct length. Otherwise, false will be returned. ValidCardLength has an optional string parameter in which a card number can be passed. If the parameter is blank, it will use the Card property. The ValidDate method returns TRUE if the expiration date provided in the ExpDate property is valid, or FALSE if it is not. The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

GetXMLResponse

String

GetXMLRequest

String

PccSysExists

Boolean

Send

Boolean

ValidCardLength

Boolean

ValidDate

Boolean

VerifyAmount

Boolean

214

Method

Returned Value

Description - Charge Class Methods The VerifyCreditCard method returns TRUE if the credit card numbers format is valid and meets the requirements set forth by the credit card companies, FALSE if it does not. If FALSE is returned, use the GetErrorCode and GetErrorDesc methods to determine the reason for failure. VerifyCreditCard has an optional string parameter in which a credit card number can be passed. If the parameter is left blank, VerifyCreditCard will analyze the value set in the Card property. The VerifyExpDate method returns TRUE if the expiration date provided in the ExpDate property is correct and in the right format, or FALSE if it is not. VerifyExpDate calls the ValidDate function to validate the expiration date. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The VerifyMerchantNumber method returns TRUE if the merchant number that is passed to it is set up in PCCharge, otherwise, FALSE is returned. Specifically, this method checks for the merchant number in the file TID.PCC, which is located in the PCCharge directory. The Path property must be set before calling this Method. Current transaction database size in bytes. Current configured size limit for transaction archive in bytes.

VerifyCreditCard

Boolean

VerifyExpDate

Boolean

VerifyMerchantNumber

Boolean

GetCurrentDBSize GetConfigDBSize

String String

215

Debit Class
The Debit class provides integrators with properties and methods used to submit debit card and EBT transactions to PCCharge. To use the Debit class to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Retrieve pertinent data, such as the PIN, the Key Serial Number (if DUKPT), etc., from the PINpad.

3. Assign the appropriate values to the properties required for the transaction to be performed and validate the values using the various .Verify methods. (The properties marked with a in the Debit Class properties table are the minimum required to process a Debit Sale transaction.)

4. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format)

5. Wait for the transaction to process and then call the various .Get methods to determine the outcome of the transaction (code using the .Get methods may be placed immediately after the Send method). The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error.

6. Call the DeleteUserFiles method to delete all files related to the transaction.

7. Call the ClearVariables method to reset all the properties and methods related to the transaction or destroy the object.

When processing debit cards, a PINpad is required to allow the customer to enter their PIN. In addition, debit card information is always collected via a card swipe device, never via keyboard entry. Because of this, a card reader is also required. (Some EBT transactions can be manually entered). When processing U.S. debit card transactions, merchants have the option of allowing the customer to receive cash back on a transaction. For instance, the customer purchases $50 of products and wants $25 cash back, set the Amount to 50.00 and CashBack to 25.00. This will withdraw a total of $75 from the debit card account, $50 for the products and $25 for cash to give to the customer. Consult the section Pseudo-code (see page 105) for various examples that may be followed when using the Debit class to perform transaction processing. For information on integrating Canadian Debit, see the section Canadian (Interac) Debit Transactions (see page 77). Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

216

Debit Class Properties

Property Name Action Data Type Long Description Debit Class Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Note: If performing an EBT Balance Inquiry transaction and providing an amount, set this property to 0.00. EBT Only: For an EBT Post (Prior Auth Sale) or Force transaction: The Authorization code from the original voice authorization. Only valid for Visa debit and credit transactions. It is used to indicate the transaction is being ran for payment of a bill (ultilty, monthly gym dues, etc.) Valid values: 0 Non-Bill payment transaction 1 Bill payment transaction The Debit/EBT card number that will be used when processing the transaction. Max Length: 20 characters. Example: 5424180279791765 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 debit processors do not support the cash back feature. Because the Action property is defined as long, this property was added to allow action codes that contain strings. This property is only used for action code M1 (Key Change Request). Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the bank account type that the customer specified when entering transaction data into the PINpad. Valid Values: Chequing or Savings For use with TCP/IP CommMethod only. SSL is not yet available with PCCharge. Leave this set to false. The expiration date associated with the Debit/EBT card number that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Set this property if there is an expiration date associated with the Debit/EBT card. EBT Only: Indicates what type of EBT transaction will be performed. Valid Values: 1 Food stamp transaction; 0 Cash benefits transaction Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. This is the Gratuity Amount of the transaction. For use with TCP/IP CommMethod only. IPAddress of machine where PCCharge is running. Defaults to 127.0.0.1

Amount

String

AuthCode

String

Billpay

String

Card

String

CashBack

String

Command

String

CommMethod

Enum

DebitType

String

EnableSSL

Boolean

ExpDate

String

FoodStamp Gratuity IPAddress

Boolean String String

217

Property Name

Data Type

Description Debit Class Properties If a Key Serial Number is returned from the PINpad, this property should be populated with that number. If processing transactions with a PINpad using DUKPT encryption, this value is sixteen or twenty characters long (depending on the processors encryption). The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. If processing transactions with a Verifone SC5000 PINpad, set this property to the Chip Serial Number of the PINpad. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the language that is indicated by the Language Code that is encoded in the track II data on the customers card. Valid Values: English or French (pass in the literal string) Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the MAC Block value returned by the PINpad. Flag that indicates whether the transaction was swiped or manually entered. This property must be set to 1 (swiped) for Debit transactions or swiped EBT transactions. If the transaction was swiped, the Track property must also be set. If performing a manually keyed EBT transaction, such as a Force or Voucher, set this property to 0 (manually entered). The cardholders name. Max Length: 20 characters. The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Debit Card Setup window or EBT Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. The Original Purchase Data. Used when performing a Debit Return with the processors TSYS, Heartland, Lynk, and NPC. This is the original transaction date. Format: DDMMhhmm The delay time before the PCCharge directory is polled for a transaction response file (.oux file). The default is 0.25 seconds. This value should only be modified if the integration is not performing properly. This could be caused if the client machine is slow or there is network lag that causes the server to spend more time checking for .oux files than processing transactions. For use with File Transfer CommMethod only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

KeySerialNumber

String

LanguageCode

String

MACData

String

Manual

Long

Member

String

MerchantNumber ***

String

OrigPurchData

String

OutDelay

Single

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a \. The encrypted PIN block that is retrieved from the PINpad. The PIN is provided to the processor for verification. Length: 16 characters. The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. For use with TCP/IP CommMethod only. Open port of PCCharge. Note: Only required for the processor NBS. This is the total dollar amount for PRODUCT_DETAIL_PRODUCT_CODE_XX 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 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.

Pin

String

Port

String

ProductDetailAmount_XX

String

ProductDetailCount

String

218

Property Name ProductDetailCode_XX

Data Type String

Description Debit Class Properties Note: Only required for the processor NBS. This is the number of items for PRODUCT_DETAIL_PRODUCT_CODE_XX. Currently, PCCharge will support 0 1 10. Note: Only used for the processor NBS. This is the unit price for PRODUCT_DETAIL_PRODUCT_CODE_XX. This is only used for Fleet One and Fuelman. Currently, PCCharge will support 01 10. 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 the Processing Company Codes section (see page 101). 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. Set to 1 if card information was read from RFID (Radio Frequency Identification) device. If card was read from from RFID, track data must be populated and manual flag must be set to 1. Set to 0 otherwise. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. The Shift ID. This value is optional. Format: Alphanumeric Max Length: 1 character. 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: When using NOVA, ticket numbers can only be alphanumeric, no hyphens. The number of seconds after which a timeout error will be returned from the class. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. The track II data captured from the magnetic strip of the card. The track II data is required for Debit transactions and for swiped EBT transactions. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in. No longer needed 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50). EBT Only: The voucher number for an EBT force transaction. The voucher is provided by the processor at the time of authorization and must be supplied to clear the voucher. Set to True to activate the XML message format. It is recommended that the 3 parameter be passed to the Send method to activate the XML message format instead of using the XMLtran property. See the description for the Send method for more information.

ProductDetailQuantity_XX

String

Processor ***

String

Reference

String

RFID

String

ShiftID

Ticket

String

TimeOut

Long

Track

String

TransNum

String

TroutD

String

User **

String

Voucher

String

XMLtran

Boolean

These properties are required to process a Debit Sale transaction. These properties are required to process a Canadian Debit Sale transaction using Global Payments East (NDC) and the SC5000 PINpad.

219

** 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 (see page 50). 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. Consult the Multi-Merchant Support section (see page 56) for more information on the Use Default Processor option. In addition, Processor and MerchantNumber should not be set when doing follow-on transactions. Refer to the section Follow On Transactions (see page 58) for more information.

Debit Class Methods

Method Name Returned Value Description - Debit Class Methods The ClearVariables method will clear the values in all properties and methods. It is recommended that this method be called: a. after the transaction results have been retrieved by using the various .get methods b. after the DeleteUserFiles method has been called c. prior to running the next transaction For use with File Transfer CommMethod only. The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). The GetApproved method returns TRUE if PCCharge returns "APPROVED" as the result of the transaction. Otherwise, FALSE will be returned. 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. When using the SC5000 PINpad, returns the ISO response code EBT Only: The GetAvlBalance method returns the available balance on the EBT card. This value is not returned by all processing companies. 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, and that the transaction has been placed in the open batch. EBT Only: Returns the remaining balance on a Cash Benefits card. This value is not returned by all processing companies. EBT Only: Returns the remaining balance on a Food Stamp card. This value is not returned by all processing companies. 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

ClearVariables

None

DeleteUserFiles

None

GetApproved

Boolean String String String

GetAuth GetAuxRespCode GetAvlBalance

GetCaptured

Boolean

GetEBTCashBalance GetEBTFoodBalance

String String

GetErrorCode

Long

GetErrorDesc

String

220

Method Name

Returned Value

Description - Debit Class Methods The GetMerchantInfo method returns a string containing all of the debit merchant numbers and processors set up in PCCharge. The string will begin with STX and will end with ETX. GS will separate each record, and FS will separate fields within a record. Example: <STX>CES <FS>000000927996296767<GS>GSAR<FS> 999999999999519<GS>VISA<FS>999999999911<ETX> Refer to the section Multi-Merchant Support (see page 56) for more information on the GetMerchantInfo method. Returns the merchant number that was specified in the MerchantNumber property. For Debit Master Session: Returns the new master key (if one exists) sent by the processor that should be passed to the PINpad. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Returns the current POS Sequence Number for the PINpad. The Path property must be set to the PCCharge directory and the PINpads Chip Serial Number must be passed as a parameter when calling the GetPOSSequenceNumber method. Returns the reference number associated with the transaction. 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. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. For GSAR Debit US only: Returns the surcharge amount that was charged by the bank when using debit with GSAR. This value has to be called in order for the developer to know how much the card was actually charged in addition to the transaction amount and cash back. The GetTermFee method returns the terminal fee that applies to the transaction. The terminal fee is designated by the processor. Not all processors return the terminal fee. For Debit Master Session: Returns the new working key (if one exists) sent by the processor that should be passed to the PINpad for the next transaction. For GSAR EBT: Returns the ledger balance. The GetTraceNum method returns the trace number for the transaction that was returned by the processor. Not all processors support this field. 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. 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. See the section Follow On Transactions (see page 58) for more information. 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. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. 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.

GetMerchantInfo

String

GetMerchantNumber GetMSI

String String

GetPOSSequenceNumber

String

GetRefNumber

String

GetResult

String

GetSurchargeAmount

String

GetTermFee

String

GetTI

String String

GetTraceNum

GetTransNum

String

GetTroutD

String

GetXMLResponse

String

GetXMLRequest

String

221

Method Name

Returned Value

Description - Debit Class Methods For use with File Transfer CommMethod only. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above. The VerifyAmount method returns true if the amount provided in the Amount property is in a valid format (DDDDDD.CC). Otherwise, VerifyAmount will return false. If false is returned, check the error code to determine the reason for failure Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99).

PccSysExists

Boolean

Send

None

VerifyAmount

Boolean

222

Check Class
The Check class provides integrators with properties and methods used to submit check verification, guarantee, and conversion transactions to PCCharge. To use the Check class to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the transaction to be performed. (The properties marked with a in the Check Class properties table are the minimum required to process a check verification transaction.) 3. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format) 4. Wait for the transaction to process and then call the various .Get methods to determine the outcome of the transaction (code using the .Get methods may be placed immediately after the Send method). The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error. 5. Call the DeleteUserFiles method to delete all files related to the transaction. 6. Call the Clear method to reset all the properties and methods related to the transaction or destroy the object. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

223

Check Class Properties

Property Name Account_Number Action Data Type String String Description - Check Class Properties For Check, MICR, or Double ID: The account number that will be used when processing the transaction. Max Length: 20 characters. The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Total amount of the transaction after adjustment (i.e. if the original transaction was $5.00 and it should have been $50.00, the adjustment transaction request should have the .Amount property set equal to 50.00). The date of birth of the check writer. Length: Exactly six characters. Format: MMDDYY. The birth date is required for DL (Drivers License) check transactions. 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. The Cashier Number Valid Values: 0 = Personal check, 1 = Business check Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The check number of the check that will be used when processing the transaction. Max Length: 10 characters. Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. The customers city. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The first and last name of the customer. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI.

Amount

String

AdjustmentAmount

String

Birth_Date

String

Cash_Back

String

CashierNum CheckType Check_Number

String String String

CommMethod

Enum

CustomerCity CustomerName

String String

224

Property Name

Data Type

Description - Check Class Properties Passes the type of Check Reader that is being used. Currently only used by Telecheck and will only be set if TECK is the set processor. Cannot be configured in the PCCharge GUI. Valid Values: 1 - Magtek_mini_micr 2 - EnCheck_3000 3 - IVI_2500 4 - IVI_430 5 - IVI_431 6 - ICE_5700 7 - MagtekImager 8 - VeriFone_CR1000i 9 - Epson_TMH6000 10 - Epson_TMH6000Imager 11 - WelchAllyn_ScanTeam 8300 12 - VeriFone_CR600 13 - Magtek_Imager_with_Modem 14 - IBM_4610_reader_printer 15 - Ingenico_EC2600 16 - RDM_EC5000 17 - RDM_EC6000 18 - NCR_7158_and_7167 19 - LS_100 20 - Magtek_Excella 21 - Magtek_Excella_DLCapture_FBChkImg 22 - Verifone_Model_Quartet The street address of the customer. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The drivers license number of the individual writing the check. Max Length: 20 characters. The drivers license is required for DL (Drivers License) transactions and when performing Double ID transactions. The parsed TrackII data from the drivers license. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. For use with TCP/IP CommMethod only. SSL is not yet available with PCCharge. Leave this set to false. For use with TCP/IP CommMethod only. IPAddress of machine where PCCharge is running. Defaults to 127.0.0.1 Used for BPS Double ID transactions. Optional Manager Number for manager override. Flag that indicates whether the transaction was manually entered or swiped. Valid values: 0 = manual transaction, 1 = swiped transaction The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Check Services Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. The raw MICR data from the bottom of the check. Used for conversion transactions. Valid Values: 15 = Valid read by MICR reader, 15I = Valid read by MICR reader with imaging capability, 9 = Manual only Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line. The delay time before the PCCharge directory is polled for a transaction response file (.oux file). The default is 0.25 seconds. This value should only be modified if the integration is not performing properly. This could be caused if the client machine is slow or there is network lag that causes the server to spend more time checking for .oux files than processing transactions.

CheckReaderCode

Enum

CustomerStreet

String String String Boolean String String String

Drivers_License DLTrackII EnableSSL IPAddress ManagerNum Manual

MerchantNumber

String

MICR_DATA

String String

MICRStatus

Multi

String

OutDelay

Single

225

Property Name

Data Type

Description - Check Class Properties For use with File Transfer CommMethod only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\".

Phone_Number Port

String String

The phone number of the individual writing the check. Max Length: 7 digits. Format: digits only. The phone number is required for COD (Checks On Delivery). For use with TCP/IP CommMethod only. Open port of PCCharge. 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 the Processing Company Codes section (see page 101).

Processor

String

Services

The type of check verification to be performed. This property may be specified by using a numerical value or an enumerated value if the programming language being used supports enumerated values. Valid values: 0 (MICR) MICR ServicesTyp 1 (COD) Checks-On-Delivery 2 (DL) Drivers License e 3 (DI) Double ID 4 (SPS) Use if Check processor is SPS Note: The value set in the Services property overrides the value set in the Action property. 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. The state code of the state that issued the check writers drivers license. The state code is required for DL (Drivers License). Format: 2 characters. 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: When using NOVA, ticket numbers can only be alphanumeric, no hyphens. The number of seconds after which a timeout error will be returned from the class. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. The Transit Routing Number / ABA number that will be used when processing the transaction. This value indicates which bank issued the check. Max Length: 9 characters. This value is required for MICR transactions and when performing Double ID transactions. 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50).

PrintReceipts

String

State

String

Ticket

String

TimeOut

Long

Transit_Number

String

TroutD

String

User **

String

226

Property Name

Data Type

Description - Check Class Properties Set to True to activate the XML message format. It is recommended that the 3 parameter be passed to the Send method to activate the XML message format instead of using the XMLtrans property. See the description for the Send method for more information. The check writers ZIP code. Max Length: 9 characters. Format: digits only. This value is required for COD transactions. Note: If submitting the 9-digit zip, do not include the dash.

XMLtrans

Boolean

Zip_Code

String

Note: To perform Double ID, both the MICR_DATA and Drivers_License fields must be populated. These properties are required, regardless of service type. ** 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 (see page 50). This section contains detailed information about user names and how they should be implemented. COD -- required for Checks-On-Delivery DL -- required for Drivers License MICR -- required for MICR

Check Class Methods

Method Name Returned Value Description - Check Class Methods The Clear method will clear the values in all properties and methods. It is recommended that this method be called: d. after the transaction results have been retrieved by using the various .get methods e. after the DeleteUserFiles method has been called f. prior to running the next transaction For use with File Transfer CommMethod only. The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). The GetApproved method returns TRUE if PCCharge returns "APPROVED" as the result of the transaction. Otherwise, FALSE will be returned. An APPROVED response indicates that a Verification has been approved. 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. 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 conversion transaction that will result in a monetary transfer is approved or declined. A CAPTURED response indicates that the transaction has been approved, and that the transaction has been placed in the open batch. 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns the merchant number that was specified in the MerchantNumber property.

Clear

None

DeleteUserFiles

None

GetApproved

Boolean

GetAuth

String

GetCaptured

Boolean

GetErrorCode

Long

GetErrorDesc

String

GetMerchantNumber

String

227

Method Name GetRespCode

Returned Value String String String String String String String

Description - Check Class Methods Returns the response code that is provided by the processor. This value is not returned by all processing companies. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. Returns the result code that is provided by the processor. This value is not returned by all processing companies. Returns the response from the processor which indicates the fee for returned checks. Note: Only used for the processor TECK Returns the response from the processor which displays a note for returned checks. Note: Only used for the processor TECK Returns the reference number that is provided by the processor. This value is not returned by all processing companies. 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. 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. See the section Follow On Transactions (see page 58) for more information. Only for TECK. Returns the Trace ID associated with the transaction. 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. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. 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. For use with File Transfer CommMethod only. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions.

GetResult

GetResultCode GetReturnCheckFee GetReturnCheckNote GetReference

GetTransNum

GetTroutD

String

GetTraceID

String

GetXMLResponse

String

GetXMLRequest

String

PccSysExists

Boolean

228

Method Name

Returned Value

Description - Check Class Methods The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: (TTYPE_XML) XML message format (RECOMMENDED) Example: Send 3 Note: The other values that appear in the enumerated list are for internal use onlydo not attempt to use any values other than the ones listed above. The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

Send

None

VerifyAmount

Boolean

229

EBT
Because Debit and EBT transaction are similar, the Debit Class should be used to perform EBT transactions. Consult the section Debit Class for more information (See page 216)

230

Gift Class
The Gift class provides integrators with properties and methods used to submit gift card transactions to PCCharge. To use the Gift class to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the transaction to be performed and validate the values using the various .Verify methods. (The properties marked with a in the Gift Class properties table are the minimum required to process a Gift Card Redemption / Sale transaction.)

3. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format)

4. Wait for the transaction to process and then call the various .Get methods to determine the outcome of the transaction (code using the .Get methods may be placed immediately after the Send method). The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error.

5. Call the DeleteUserFiles method to delete all files related to the transaction.

6. Call the Clear method to reset all the properties and methods related to the transaction or destroy the object. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

VeriFone Stored Value API (GAPI)

The VeriFone Stored Value API (GAPI) is a proprietary specification that allows for stored value card processors to add themselves to PCCharge. Applications using GAPI can also integrate with PCCharge using the various integration methods. For more information on adding a stored value card processor to PCCharge, and how to obtain the VeriFone Stored Value API, please contact VeriFone sales at 1-800725-9264.

231

Gift Class Properties

Property Name Action Data Type String Description Gift Class Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder must be sent as well. Example: 0.50. For Valuelink (VLNK) Balance Adjustment: Format: +/DDDDD.CC. The auth code property that will be used for processing Voids for VTEC, VLNK, MELL, and GSAR. For VTEC and VLNK, set this property to the auth code of the original transaction to be voided. For GSAR and MELL, set this property to the reference number of the original transaction to be voided. For BPS, set to retrieval reference number of original transaction (the one to be voided). The gift card number that will be used when processing the transaction. Max Length: 20 characters. The card sequence number for the transaction. Currently, GSAR is the only processor that uses this property. If sending multiple transactions to GSAR, this should be the sequence number of the transaction. For example, if ten cards are being issued and this is the fifth in the sequence, set CardSeqNum to 5. CardSeqNum should be no more than two characters long. The numeric cashier ID for the gift card transaction. The only gift card processors that currently support the CashierID are VTEC and VLNK. Flag that indicates whether to activate gift card validity testing. Valid Values: TRUE; FALSE. Default value: TRUE. This value must be set to FALSE when performing Follow on transactions because the card number is omitted from these transaction requests. Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. The demo mode flag. In demo mode, a simulated response is returned in which even amounts return approved, and odd amounts return declined. Valid Values: TRUE Activates demo mode FALSE Deactivates demo mode (default) For use with TCP/IP CommMethod only. SSL is not yet available with PCCharge. Leave this set to false. The expiration date associated with the gift card that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Note: Most gift cards do not have an expiration date. The Force flag. The Force flag indicates whether or not an approval code has already been issued. The Force flag is used only by GSAR Redemption or a single GSAR Issuance/Add Value transaction. Only used for the processor SVS. To retrieve pin, call GetGfitPin upon activation. Used for only for virtual gift card transactions. The gratuity amount for the transaction. Tip should be no more than 9 characters long (including the decimal). Format: DDDDDD.CC. The industry type for the transaction. Valid Values: 1 = retail, 2 = restaurant. For VLNK: 0 = retail, 1 = restaurant, 2 = e-Commerce. For use with TCP/IP CommMethod only. IPAddress of machine where PCCharge is running. Defaults to 127.0.0.1

Amount

String

Authcode

String

Card

String

CardSeqNum

String

CashierID

String

CheckCard

Boolean

CommMethod

Enum

Demo

Boolean

EnableSSL

Boolean String

ExpDate

Force

Boolean String String String String

GiftPin GratuityAmount Industry IPAddress

232

Property Name

Data Type

Description Gift Class Properties The last year that will be considered a valid expiration date. Currently, the default value in the class is 09. It is recommended that a setting is provided by which the end-user can change this property; otherwise, in the future, end users will require a new class to be distributed to resolve expiration date issues. Length: 2 digits. Format: YY Example: If LastValidDate is set to 05, then cards between 06 and 99 are considered to be 1906 to 1999, and cards between 00 and 05 are 2000 to 2005. The Loyalty flag indicates whether or not the transaction is a loyalty transaction. Currently, only VTEC supports the Loyalty flag. The default value of the Loyalty flag is false. Flag that indicates whether the transaction was manually entered or swiped. If the transaction was swiped, the Track property must also be set. Valid values: 0 = manual transaction, 1 = swiped transaction The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Gift Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. 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. See the section Multi-trans Wait for more information (see page 58). This Flag has no effect if processing will occur over IP or leased line. The old card property. OldCard should be no more than twenty characters long. For VTEC: OldCard will be used for the Replace transaction. For VLNK: OldCard will be used for the Balance Merge and Balance Transfer transactions. The delay time before the PCCharge directory is polled for a transaction response file (.oux file). The default is 0.25 seconds. This value should only be modified if the integration is not performing properly. This could be caused if the client machine is slow or there is network lag that causes the server to spend more time checking for .oux files than processing transactions. For GSAR: Flag indicating whether the transaction is a partial redemption transaction. For use with File Transfer CommMethod only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

LastValidDate

String

Loyalty

Boolean

Manual

Long

MerchantNumber

String

Multi

String

OldCard

String

OutDelay

Single

Partial

Boolean

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a \.

Points Port

String String String

The number of points that will be redeemed in a Loyalty Points transaction. Points should be no more than nine characters long. For use with TCP/IP CommMethod only. Open port of PCCharge. 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. 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 the Processing Company Codes section (see page 101). Used for GVEX: A code defined by the merchant that affects the calculation from amount and units to points.

PrintReceipts

Processor

String

PromoCode

String

233

Property Name

Data Type String

Description Gift Class Properties 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 Set to 1 if card information was read from RFID (Radio Frequency Identification) device. If card was read from from RFID, track data must be populated and manual flag must be set to 1. Set to 0 otherwise. 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 gift processors support ticket numbers. The number of seconds after which a timeout error will be returned from the class. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. The tip amount for the transaction. TIP should be no more than 9 characters long (including the decimal). Format: DDDDDD.CC. Currently, tips are supported via the TIP property only for VTEC and VLNK restaurant transactions. The total number of cards that will be sent to PCCharge. GSAR is currently the only processor that uses this property. If sending multiple transactions to PCCharge, this should be the total number of the transactions that will be sent. Example: If ten cards are being issued, set TotalCardNum to 10. TotalCardNum should be no more than two characters long. The track II data captured from the magnetic strip of the card.. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in. Alternatively, the GetParseData method can be used to parse the track data and set the Card, ExpDate, and Track properties automatically. 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50). Only used for the processor SVS. 0 - False, 1 - True Only sent on an activation to determine if a pin should be returned. Set to True to activate the XML message format. It is recommended that the 3 parameter be passed to the Send method to activate the XML message format instead of using the XMLtran property. See the description for the Send method for more information. Only used for GAPI in restaurant mode. This is the table number of the gift card holder Only used for GAPI. The Track I information associated with the card

Refund

RFID

String

Ticket

String

TimeOut

Long

TIP

String

TotalCardNum

String

Track

String

TroutD

String

User **

String

VirtualGiftCardFlag

Boolean

XMLtran

Boolean

TableNumber TrackI

String String

These properties are required to process a gift card redemption or sale transaction. Required for VTEC gift card transactions ** 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 (see page 50). This section contains detailed information about user names and how they should be implemented.

234

GiftCard Class Methods

Method Name Returned Value Boolean Description - GiftCard Class Methods The Abort method attempts to cancel the transaction in progress and will return a Boolean value that indicates whether or not the transaction was canceled. Note: This method is not available when integrating using FoxPro. Use the Cancel method instead. 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. The Clear method will clear the values in all properties and methods. It is recommended that this method be called: g. after the transaction results have been retrieved by using the various .get methods h. after the DeleteUserFiles method has been called i. prior to running the next transaction For use with File Transfer CommMethod only. The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). Returns the number of activations in the current batch Returns the total dollar amount of activations in the current batch Returns the number of AddPoints Transactions in the current batch Returns the total dollar amount of AddPoints transactions in the current batch Returns the number of AddValue transactions in the current batch Returns the total dollar amount of AddValue transactions in the current batch Used in partial redemption transactions where only part of the amount was authorized. Returns the remainder amount that is owed to the merchant. 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 transactions 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>. Used in partial redemption transactions where only part of the amount was authorized. Returns the actual authorized amount. Returns the number of Balance Transfers in the current batch Returns the total dollar amount of Balance Transfers in the current batch 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. 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. Returns the number of credits in the current batch

Abort

Cancel

None

Clear

None

DeleteUserFiles

None

GetActivationCount GetActivationTotalAmount GetAddPointsCount GetAddPointsTotalAmount GetAddValueCount GetAddValueTotalAmount GetAmountDue

String String String String String String String

GetAuth

String

GetAuthAmount GetBalanceTransferCount

String String

GetBalanceTransferTotalAmou String nt

GetCaptured

Boolean

GetCashBack GetCreditCount

String String

235

Method Name GetCreditTotalAmount

Returned Value String

Description - GiftCard Class Methods Returns the total dollar amount of credits in the current batch 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns the expiration date for processors who issue expiration dates in the response. Returns the gift card balance. 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. 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. Only used for the processor SVS. Returned on activation if the virtual gift card tag is set to 1. Returns the merchant number that was specified in the MerchantNumber property. The GetParseData method will parse a string (containing credit card track data) passed to it and populate the Card, ExpDate, and Track properties with the appropriate data. GetParseData will return an integer indicating its success. Valid return values: 0 (error parsing data), 1 (track I successful), or 2 (track I & II successful). Returns the number of points transactions in the current batch Returns the total dollar amount of points transactions in the current batch The processor response code. Only returned by the processor SVS. 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 accounts 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. Returns the response code that is provided by the processor. This value is not returned by all processing companies. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. 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. Returns the number of redemptions in the current batch Returns the total dollar amount of redemptions in the current batch 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>.>.

GetErrorCode

Long

GetErrorDesc

String

GetExp GetGiftCardBalance

String String

GetGiftCardIssuer

String

GetGiftCardType

String

GetGiftPin GetMerchantNumber

String String

GetParseData

String

GetPointsCount GetPointsTotalAmount GetProcRespCode

String String String

GetRefNumber

String

GetRespCode

String String

GetResult

GetRet

String String String

GetSaleCount GetSaleTotalAmount

GetTI

String

236

Method Name

Returned Value

Description - GiftCard Class Methods 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>.>. Returns the Time of the transaction. This value is not returned by all processing companies. For VTEC, returns the Amount Due. Returns the number of Tip transactions in the current batch Returns the total dollar amount of Tip transactions in the current batch Returns the transaction date and time when passed back by a processor. 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. 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. See the section Follow On Transactions (see page 58) for more information. Used internally Returns the Void Balance Returns the number of voids in the current batch Returns the total dollar amount of Voids in the current batch 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. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. 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. For use with File Transfer CommMethod only. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions.

GetTicket

String

GetTIM GetTipCount GetTipTotalAmount GetTransDateTime GetTransNum

String String String String String

GetTroutD

String

GetUpdateData GetVoidBalance GetVoidCount GetVoidTotalAmount

String String String String

GetXMLResponse

String

GetXMLRequest

String

PccSysExists

Boolean

237

Method Name

Returned Value

Description - GiftCard Class Methods The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: (TTYPE_XML) XML message format (RECOMMENDED) Example: Send 3 Note: The other values that appear in the enumerated list are for internal use onlydo not attempt to use any values other than the ones listed above. The ValidCardLength method returns true if the card is of the correct length. Otherwise, ValidCardLength will return false. ValidCreditCard has an optional string parameter in which a card number can be passed. If the parameter is blank, it will use the Card property. If false is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). The ValidDate method returns TRUE if the expiration date provided in the ExpDate property is valid, or FALSE if it is not. Returns TRUE for valid card issuer The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The VerifyAmount2 method returns TRUE if the amount provided in the Amount property is in a valid format (+/-DDDDD.CC). or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). The difference between VerifyAmount and VerifyAmount2 is that VerifyAmount2 allows a + or to be in the first position of the Amount property. This is needed for Balance Adjustment transactions. The VerifyExpDate method returns TRUE if the expiration date provided in the ExpDate property is correct and in the right format, or FALSE if it is not. VerifyExpDate calls the ValidDate function to validate the expiration date. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The VerifyGiftCard method verifies that a card is provided and that the card is the expected length. VerifyGiftCard will return true if these conditions are met. Otherwise, VerifyGiftCard will return false. No Longer Supported No Longer Supported Only for GAPI, this returns the total number of gift card pre-auth transactions processed that day. Only for GAPI , this returns the total amount of gift card pre-auth transaction processed that day.

Send

None

ValidCardLength

Boolean

ValidDate ValidIssuer

Boolean Boolean

VerifyAmount

Boolean

VerifyAmount2

Boolean

VerifyExpDate

Boolean

VerifyGiftCard VerifyMerchantNumber VerifyProcessor GetPreAuthCount GetPreAuthAmount

Boolean Boolean Boolean String String

238

Method Name GetPostAuthCount GetPostAuthAmount GetIssuanceCount GetIssuanceTotalAmount GetDeactivateCount GetDeactivateTotalAmount GetBalanceAdjustCount

Returned Value String String String String String String String

Description - GiftCard Class Methods Only for GAPI, this returns the total number of the gift card post-auth transactions processed that day. Only for GAPI, this returns the total amount of the post-auth transactions processed that day. Only for GAPI, this returns the total number of gift cards issued that day. Only for GAPI, returns the total amount of the gift cards issued that day. Only for GAPI, this returns how many gift cards where deactivated that day. Only for GAPI, this returns the total amount of gift card deactivations that day. Only for GAPI, this returns the number of gift cards that were balance adjusted that day. Only for GAPI, this returns the total amount of balance adjustment on gift cards that day. Only for GAPI, this returns the total number of the gift cards that were balance merged that day. Only for GAPI, this returns the total amount of gift card balance merges that day. Only for GAPI, returns the total reported stolen or lost gift cards that day. Only for GAPI, returns the total amount of all stolen or reported lost gift cards that day. Only for GAPI, returns the total amount of all cashout transactions processed that day. Only for GAPI, returns the total number of the cashout transactions processed that day. Only for GAPI, returns the total number of gift cards that have been reactivated that day. Only for GAPI, the total amount of all gift cards that have been reactivated that day.

GetBalanceAdjustTotalAmount String GetBalanceMergeCount GetBalanceMergeTotalAmount GetReportLostStolenCount String String String

GetReportLostStolenTotalAmo String unt GetCashoutTotalAmount GetCashoutCount GetReactivateCount GetReactivateTotalAmount String String String String

Batch Class
Batch Class Properties
Property Name Action Data Type Single Description Batch Class Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). Flag that determines what type of batch close will occur. This flag only supported by Buypass and Fifth-Third when using action code 30 or 31 Valid values: 1 Standard End of Day Batch Close (Default) 2 Shift Close 3 Fifth-Third Terminal Based Batch Close of Debit, EBT, or Gift Set the Cancel property to TRUE to attempt to cancel the settle/close function. Check the GetResult method to see if the function was Canceled. Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. The demo mode flag. In demo mode, a simulated response is returned. Valid Values: 1 Activates demo mode 0 Deactivates demo mode (default) For use with TCP/IP CommMethod only. SSL is not yet available with PCCharge. Leave this set to false.

BatchCloseType

String

Cancel

Boolean

CommMethod

Enum

Demo

String

EnableSSL

String

239

Property Name IPAddress

Data Type String

Description Batch Class Properties For use with TCP/IP CommMethod only. IPAddress of machine where PCCharge is running. Defaults to 127.0.0.1 The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the various setup windows of PCCharge. Max Length: 32 characters. This value can be alphanumeric. The delay time before the PCCharge directory is polled for a transaction response file (.oux file). The default is 0.25 seconds. This value should only be modified if the integration is not performing properly. This could be caused if the client machine is slow or there is network lag that causes the server to spend more time checking for .oux files than processing transactions. For use with File Transfer CommMethod only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

MerchantNumber

String

OutDelay

Single

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a \.

Port

String

For use with TCP/IP CommMethod only. Open port of PCCharge. The code for the processing company that will be used when performing batch operations. 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 the Processing Company Codes section (see page 101). Only used when settling the processor CITI for private label transactions. Set this property to the main credit card processor ID code being used. The number of seconds after which a timeout error will be returned from the class. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). 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 more information on user names, consult the Multi-User Support section (see page 50). Set to True to activate the XML message format. It is recommended that the 3 parameter be passed to the Send method to activate the XML message format instead of using the XMLtrans property. See the description for the Send method for more information.

Processor

String

SplitProcessor

String

TimeOut

Long

User

String

XMLtrans

Boolean

The following properties are no longer available in the Batch class and should be ignored:
AmexAmount AmexCount Balance BatchDate BatchNumber CIC ItemCount MTS PurchaseAmount PurchaseCount Response ReturnAmount ReturnCount Store Terminal VisaMCAmount VisaMCCount

240

Batch Class Methods

Method Name Returned Value Description - Batch Class Methods The Clear method will clear the values in all properties and methods. It is recommended that this method be called: j. after the transaction results have been retrieved by using the various .get methods k. after the DeleteUserFiles method has been called l. prior to running the next transaction For use with File Transfer CommMethod only. The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). The GetAccepted method returns a value of true if the batch was accepted (for Terminal based processors) or processed (for Host based processors). If the batch was not accepted or processed, GetAccepted will return a value of false. Index is an optional parameter. If multiple batches have been settled, there will be several entries in the .oux file. GetNumber(Index) will return the number of merchant accounts that will be in the .oux file. GetBalance String The GetBalance method returns the dollar amount of the last settled batch or the amount waiting to be settled in the open batch. The GetBatches method can only be used with Batch Inquiry transactions. This method returns the number of batches that will be settled for a particular merchant number. Example: If a merchant account is set up as TSYS using TCP/IP, there is a limitation on how many transactions can be sent across on a single batch. Therefore, PCCharge breaks the batch up into smaller batches. GetBatches returns the number of smaller batches that would be created for that merchant account. After a terminal-based batch settles, returns the batch number. The GetErrorCode method returns an error code if an error was encountered during the use of various methods such as the Send, DeleteUserFiles, and PccSysExists. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns the file extension for the files the batch class will be accessing. The GetItemCount method returns the number of transactions that are in the batch for which the function was performed. The GetMerchantInfo method returns a string containing all of the merchant numbers and processors set up in PCCharge. The string will also indicate whether the processor is Host based (H), Terminal based (T), or a hybrid (Y). The string will begin with STX and will end with ETX. GS will separate each record, and FS will separate fields within a record. Example: <STX>CES <FS>000000927996296767<FS>T<GS>GSAR<FS> 999999999999519<FS>T<GS>VISA<FS>999999999911<FS>T<ETX> Refer to the section Multi-Merchant Support (see page 56) for more information on the GetMerchantInfo method. Returns the merchant number that was specified in the MerchantNumber property.

Clear

None

DeleteUserFiles

None

GetAccepted

Boolean

GetBatches

String

GetBatchNumber

String

GetErrorCode

Long

GetErrorDesc

String String String

GetFileExt GetItemCount

GetMerchantInfo

String

GetMerchantNumber

String

241

Method Name GetNumberIndexs

Returned Value Integer String Boolean

Description - Batch Class Methods The GetNumberIndexs method returns the number of merchant numbers that are stored in PCCharge. This number indicates how many batches will be settled or closed if an action code of 39 is submitted. Returns the processor ID specified in the Processor property. Only returned with CITI settlement. The GetProcessed method returns true if the result of the action performed was Processed. Processed is a response that PCCharge returns for an inquiry transaction and a Close on a Host based processor. Returns the response code for the batch if the close batch command was given. The response code indicates whether or not the transaction was successfully closed. If the batch is declined, the GetResult method will provide more information indicating why the transaction was not approved. Valid Values: 2 = Settled, 6 = Declined, or 8 = Deferred. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. The GetAccepted or GetProcessed methods will indicate whether or not the batch operation was successful. However, if both GetAccepted and GetProcessed are FALSE, the GetResult method will provide more information about why the batch operation was not successful. No Longer Supported The GetSettleNumber method returns the settlement number that is stored in association with the transaction in PCCharges database. This number is a sequencing number PCCharge generates internally; the processing company does not generate it. Returns the status of the batch when performing an inquiry or a batch close/settle operation. If performing a batch close/settlement operation, GetStatus will return a response from the processor that indicates whether or not the batch was successfully closed or settled. Example: If TSYS rejects the batch, GetStatus will return the RB (rejected batch) number from TSYS . If TSYS accepts the batch, GetStatus will return the batch number and an ACCEPTED response will be returned. The GetSystemInfo method is used to set the MerchantNumber and Processor properties of the Batch class. To use GetSystemInfo, pass the index number of a merchant number that is registered in PCCharge as a parameter (for example, the first Merchant number that is set up in PCCharge is assigned the index of 1 ). Once the index number has been passed to PCCharge via GetSystemInfo, the merchant number and processor can be retrieved using the MerchantNumber and Processor properties. 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. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. 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.

GetProcessor

GetProcessed

GetRespCode

String

GetResult

String

GetSettleAmount

None String

GetSettleNumber

GetStatus

String

GetSystemInfo

None

GetXMLResponse

String

GetXMLRequest

String

242

Method Name

Returned Value

Description - Batch Class Methods For use with File Transfer CommMethod only. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above.

PccSysExists

Boolean

Send

None

Note: In the event there are multiple batches waiting to be settled in one settlement, the integrated application will need to be designed to loop through the settlement response to retrieve the response for each batch.

243

Offline Class
Offline Class Properties
Property Name GetInProcessRecord Data Type Long Description - Offline Class Properties Returns the index of the record in the .bch file that is currently being processed. This property will be updated during the ProcessFile function to reflect the stage of the process. Returns true if the transaction requested is marked as void. GetVoid will take an integer and a string as arguments. The integer is the Index of the record to be checked, and the string is the name of the .bch file. If an error is encountered, GetVoid will set the error code and description and exit the function. The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Credit Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. MerchantNumber will be used to process the transactions when the .bch file is processed. The path of the directory in which the .bch file resides. Example: C:\Program Files\PCCW\MyBatchFiles. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory. PccwPath String Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\". 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 the Processing Company Codes section (see page 101). Processor will also be used to determine the index that will be used for processing the .bch file. 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 more information on user names, consult the Multi-User Support section (see page 50). Sets the flag that indicates whether or not that transaction should be marked as voided. Usage: Load the transaction. Set the Void property to true. Use the UpdateRecord method to save the data.

GetVoid

Boolean

MerchantNumber

String

Path

String

Processor

String

User

String

Void

Boolean

Offline Class Methods

Method Name Returned Value Description - Offline Class Properties The Compact method takes all transactions marked as voided out of the .bch file. If no .bch file is passed in when Compact is called, it will use a file name that consists of the processor and index. Example: Visa1.bch. If an error is encountered during processing, Compact will set the error code and description and will exit the function.

Compact

Boolean

244

Method Name

Returned Value

Description - Offline Class Properties The Connect method sets an internal class to the object that is passed in to the Connect method. During the processing of the ProcessFile method, the object will call the OnUpdate function of that object and pass to that method an integer that identifies the record that is being processed. Connect will return true if it successfully sets the class to the object passed. Otherwise, Connect will be return false. The Disconnect method sets the internal class to Nothing. The internal class is the same class that is modified when Connect is called. The EraseFile method sends the .bch file to the Recycle Bin. If no .bch file is passed in when EraseFile is called, it will use a file name that consists of the processor and index. Example: Visa1.bch. If EraseFile encounters an error during processing, the error code and description will be set and will exit the function. The GetAmount method returns the amount of the transaction in the current record. The GetRecord method must be called first. The GetAppCode method returns the approval code of the transaction in the current record. The GetRecord method must be called first. The GetBalance method returns the total balance of the current batch file. This balance will be set after calling GetTotals or ProcessFile. The GetBchFile method returns a file name if one is not provided. The file name will consist of the processor code and index. Example: Visa1.bch. The GetCard method returns the card of the transaction in the current record. The GetRecord method must be called first. The GetCount method returns the number of transactions that are stored in the .bch file. This variable will be updated after the Compact, GetTotals, and ProcessFile. The GetErrorCode method returns an error code if an error was encountered during use of various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetExpDate method returns the expiration date of the transaction in the current record. The GetRecord method must be called first. The GetIndex method returns the index of the process and merchant number combinations in the file tid.pcc. The MerchantNumber and Processor properties will be used to determine the index. The GetItem method returns the item or record number of the transaction in the current file. The GetRecord method must be called first. The GetRecord method updates the current transaction data with the data at the index that is provided when calling GetRecord. The GetRecords method returns the number of records that are in a particular .bch file. This data will be updated after calling the GetVoid, GetTotals, and ProcessFile method. The GetTicket method returns the ticket number of the transaction in the current record. The GetRecord method must be called first. The GetTotals method updates the balance, counts the transactions in the .bch file, and puts them in local variables. These figures can be retrieved with the GetCount and GetBalance. The GetTransType method returns a string representation of the type of transaction in the current record. Example: Sale, Void, Credit, etc. The GetRecord method must be called first. The ProcessFile method accesses the .bch file provided (or calls GetBCHFile if not provided), and processes the transactions in the file. If an error occurs while processing the file, ProcessFile will update the error code and description and processing will be terminated.

Connect

Boolean

Disconnect

Boolean

EraseFile

Boolean

GetAmount GetAppCode GetBalance GetBchFile GetCard

String String Currency String String

GetCount

Long

GetErrorCode

Long

GetErrorDesc

String

GetExpDate

String

GetIndex

Long

GetItem GetRecord

String Boolean

GetRecords

Long

GetTicket

String

GetTotals

Boolean

GetTransType

String

ProcessFile

Boolean

245

Method Name

Returned Value

Description - Offline Class Properties The UpdateRecord method accesses the .bch file provided (or calls GetBCHFile if not provided), and marks the records provided as voided if the Void flag is set to true. If an error occurs while processing the file, UpdateRecord will update the error code and description and processing will be terminated.

UpdateRecord

Boolean

Reporting
The Charge class may be used by integrators to submit report requests. A report request can have PCCharge print a report to its default report printer or have PCCharge generate a file containing the report output. If generating a file, the PCCharge reporting interface supports three different file types: 1. Portable Document Format (.pdf) 2. Rich Text Files (.rtf) 3. Standard Text files (.txt) Note: The reporting interface cannot be configured to send reports directly to the screen. The following outlines the properties used for submitting report requests to PCCharge with the Charge class. The properties in the Charge class that are not documented below should be left blank when submitting report requests.
Property Data Type Long Description Charge Class Reporting Properties The action code that identifies what type of report will be requested. Valid Values: 81-84. Example: If running a credit card detail report, set the action code to 81. Consult the section DevKit Constants for a list of valid values (see page 94). User name filter. If a valid user name is set in the Card property, the report will be filtered by that user name. The report returned will consist of only those transactions processed by the user name specified. Example: "User1". If this property is left blank, the report will show transactions processed by all users. Flag that indicates whether to activate credit card validity testing. Valid Values: TRUE; FALSE. Default value: TRUE. This value must be set to FALSE when submitting a report request. Specifies which communication method will be used. 0 File_Transfer 1 TCP/IP Please refer to page 20 for a description of these methods. If TCP/IP is selected, the IPAddress, Port and EnableSSL properties must also be set. If File_Transfer is set then the Path property must be set. For use with TCP/IP CommMethod only. SSL is not yet available with PCCharge. Leave this set to false. For use with TCP/IP CommMethod only. IPAddress of machine where PCCharge is running. Defaults to 127.0.0.1 Result filter. Use this filter to create a report consisting of only those transactions with the result specified. Valid Values: 0 = all (default), 1 = approved, 2 = declined Example: 1 Ending Date/Time filter. Specifies the end date and end time of the report. Format: Date: MM/DD/YY Time: HH:MM:SS PM. When used in conjunction with Street; will create a report consisting of only those transactions processed between the start and end date/time specified (inclusive). If an end date is not specified, todays date is assumed. If an end time is not specified, 11:59:59 PM is assumed. The end date can be passed without the end time. However, the end time cannot be passed without the end date. Examples: 07/06/05 06:00:00 PM or 07/06/05

Action

Card

String

CheckCard

Boolean

CommMethod

Enum

EnableSSL IPAddress

Boolean String Long

Manual

Member

String

246

Property

Data Type

Description Charge Class Reporting Properties Merchant Number filter. Set this property to filter the report by the merchant number specified. Setting this property will generate a report consisting of only those transactions processed via the merchant number specified. To generate a report that includes all merchant numbers in PCCharge, set this property to ALL or leave blank. Example: 99999999911 For use with File Transfer CommMethod only. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

MerchantNumber

String

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ (default) Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a \.

PeriodicPayment

String String

Report Output setting. Determines if the report will be printed by PCCharge or written to a file. Valid Values: 0 = print to default printer specified in PCCharge (default). 1 = print to file using filename specified in TransID and path specified in TRACK. For use with TCP/IP CommMethod only. Open port of PCCharge. Starting Date/Time Filter (Optional) Specifies the start date and start time of the report. Format: Date: MM/DD/YY Time: HH:MM:SS PM. Use to create a report consisting of only those transactions processed on or after the date specified. If a start date is not specified, today's date is assumed. If a start time is not specified, 12:00:00 AM is assumed. The start date can be passed without the start time. However, the start time cannot be passed without the start date. Examples: "03/04/05 09:00:00 AM" or 03/04/05 The number of seconds after which a timeout error will be returned from the class. The count will start when the Send method is called. The default timeout value is 90 seconds. It is highly recommended that integrators review the section Timeouts (see page 47). Destination Directory for Report File. Specifies the destination directory where the report file will be generated by PCCharge (if PeriodicPayment is set to "1"). Example: C:\My Documents\PCCReports\ Path Formats: UNC, MS-DOS(8 Characters) and Long. Max Length: 40 characters (if the Destination Directory is longer than 40 characters, use CustCode for the additional characters. Must end with a "\" unless the directory name will be continued in the CustCode property. Note: If running in a Client/Server environment, this property is the path from the server running PCCharge, not the client. For example, if a client submitted a report request that specified C:\ as the destination directory, the report would be written to the local hard drive of the server running PCCharge, not to the clients hard drive.

Port

Street

String

TimeOut

Long

Track

String

CustCode

String

Destination Directory for Report File (continued). Continuation of the destination directory (if the directory name is greater than 40 characters). Max Length: 25 characters. Must end with a "\" Report File name/Report File Type. Specifies the filename and extension of the report file generated by PCCharge (if PeriodicPayment is set to "1"). Also determines what file type will be used when PCCharge generates the report. To specify the file type, set the extension to one of the following: .pdf Create the report file in the Portable Document Format. Ex. Report.pdf .rtf Create the report file in Rich Text. Ex. Report.rtf .txt Create a report file in flat text. Ex. Report.txt Default: .txt (If an extension other than the ones listed is passed, the report will be returned as flat text and a .txt extension will be added to the filename) 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 more information on user names, consult the Multi-User Support section (see page 50).

TRANSID

String

User

String

247

 These properties are required to submit a report request.

The following outlines the methods used to process report requests. The methods in the Charge class that are not documented below will not be used when processing report requests.
Method Returned Value None Description - Charge Class Reporting Methods 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. The Clear method will clear the values in all properties and methods. It is recommended that this method be called: a. after the transaction results have been retrieved by using the various .get methods b. after the DeleteUserFiles method has been called c. prior to running the next transaction For use with File Transfer CommMethod only. The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). 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. 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. For use with File Transfer CommMethod only. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions.

Cancel

Clear

None

DeleteUserFiles

None

GetAuth

String

GetErrorCode

Long

GetErrorDesc

String

GetResult

String

PccSysExists

Boolean

248

Method

Returned Value

Description - Charge Class Reporting Methods The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has an optional parameter that indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above. The VerifyMerchantNumber method returns TRUE if the merchant number that is passed to it is set up in PCCharge, otherwise, FALSE is returned. Specifically, this method checks for the merchant number in the file TID.PCC, which is located in the PCCharge directory. The Path property must be set before calling this Method.

Send

Integer

VerifyMerchantNumber

Boolean

249

OLE/COM Method
Several exposed OLE classes in PCCharge allow integrators to perform various processing functions. Before these classes can be used, a reference will need to be made to the PCCharge executable. For example, in Microsoft Visual Basic 6, follow the procedure below. 1. Choose Project | References from the Visual Basic menu bar. 2. After the References window opens, from the list, scroll to and check the box next to either: PCCharge Pro (to reference PCCharge Pro) Active-Charge Payment Server (to reference PCCharge Payment Server)

and click OK. (The DevKit installation attempts to install both PCCharge Pro and PCCharge Payment Server by default. If the programs have not yet been installed on the system, install them from the DevKit CD and refer to the section Getting Started (see page 16) to set up both products.) PCCharge Pro and PCCharge Payment Server provide the developer with several OLE classes to allow the integration of payment processing: PccCharge (for Credit card integration) PCCDebit (for Debit card integration) PccCheck (for Check integration) PCCEBT (for EBT card integration) PCCGiftCard (for Gift/Loyalty integration) PccBatch & PccSettle (for Batch/Settlement integration) PccPinPad (for PINpad integration) PccBin (for utilities used to determine Commercial Card information)

The properties and methods of the various classes can be viewed through the object browser. If MS VB6 is not being used, refer to the language documentation for instructions on adding OLE references. Note: The additional classes that are exposed that do not appear in the list above do not provide transaction processing functionality. These classes provide various utilities or provide setup functionality. See the sections Utility Related Classes (see page 307) and Setup Related Classes (see page 311) for more information on these additional classes. Note: The OLE method of integration was primarily designed to be used for integrations in which the PCCharge engine and the integrated application both reside on the same machine. WARNING: If integrating via OLE, the integrated application must use the same version of PCCharge as the version of the PCCharge DevKit used to create the integration.

250

Using the OLE classes to integrate synchronously

To program in a synchronous manner, create an instance of any of the OLE classes by using the following line of code: Set <instance name> = New <object name>

For example, to create an instance based on the PccCharge class, the following line of code would be used in MS VB6: Set Charge = New ActiveCharge.PccCharge

Using the OLE classes to integrate asynchronously

To program in an asynchronous manner using the OLE classes, the object definition for the OLE class must indicate to use events. Also, a parameter must be passed with the Send method that indicates asynchronous communication. To define an object that indicates to use events based on the PccCharge class, the following line of code would be used in MS VB6: Dim WithEvents Charge As ActiveCharge.PccCharge To create an instance based on the PccCharge class, the following line of code would be used in MS VB6: Set Charge = New ActiveCharge.PccCharge To pass the parameter that indicates asynchronous communication to the Send method, use the following format: .Send [TRUE (for asynchronous) or FALSE (for synchronous)], 3 (XML message format)] For example, the following line of code would indicate asynchronous communication using the XML message format: .Send True, 3

251

PccCharge Class
The PccCharge class provides integrators with properties and methods used to submit credit card transactions to PCCharge. To use the PccCharge class to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the transaction to be performed and validate the values using the various .Verify methods. (The properties marked with a in the PccCharge Properties table are the minimum required to process a Sale or Pre-Authorization transaction.) 3. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format) 4. If programming asynchronously, wait for the Error or Finish event to occur. 5. If programming synchronously, code using the .Get methods may be placed immediately after the Send method 6. Call the various .Get methods to determine the outcome of the transaction. The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error. 7. Call the DeleteUserFiles method to delete all files related to the transaction. 8. Call the Clear method to reset all the properties and methods related to the transaction or destroy the object. Consult the Pseudo-code section (see page 105) for various examples that may be followed when using the Charge.OCX to perform transaction processing. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

252

PccCharge Properties
Property Name Action Data Type Long Description - PccCharge Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder must be sent as well. Example: 0.50. 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 American Express Description data. Additional description or information about merchandiseif 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 . American Express Description data. Additional description or information about merchandiseif 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 . American Express Description data. Additional description or information about merchandiseif 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 . American Express Description data. Additional description or information about merchandiseif 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 . The Authorization code. This value is returned by the issuing bank and should only be set in a transaction request 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, see page 63). 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. See the section Follow On Transactions for more information (see page 58). The Business / Batch Date. If populated, this value will be placed in the Business Date column of the transaction record in the PCCharge database (pccw.mdb). Format: MMDDYY Only valid for Visa debit and credit transactions. It is used to indicate the transaction is being ran for payment of a bill (ultilty, monthly gym dues, etc.) Valid values: 0 Non-Bill payment transaction 1 Bill payment transaction The credit card number that will be used when processing the transaction. Max Length: 20 characters. Example: 5424180279791765

Amount

String

AmxChargeDescription

String

AmxDescription_1

String

AmxDescription_2

String

AmxDescription_3

String

AmxDescription_4

String

AuthCode

String

BDate

String

Billpay

String

Card

String

253

Property Name

Data Type

Description - PccCharge Properties 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) The action code that identifies what type of transaction will be performed. Valid Values: 1-10, 13-15, ZI, ZH. Example: If running a credit card sale, set the action code to 1. Consult the section DevKit Constants for a list of valid values (see page 93). Note: Because the Action property is defined as long, this property was added to allow action codes that contain strings (such as Transaction Inquiry - ZI). If the Command property is set, its value will override the value set in Action. The type of commercial card being submitted. The CommercialCardType function in the PccBin class should be used to retrieve the 1 character value from PCCharge that indicates what type of commercial card will be submitted. See the section Commercial Card Transactions (see page 65) for more information. Max Length: 1 character Valid values: B Business P,L,G -- Purchase C Corporate F Fleet 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. 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. The credit plan numbers are established by the processor CITI for each merchant, they define the type of Disclaimer to print on receipts. This information will vary from merchant to merchant. Driver identification field. Only required for Wright Express, Voyager and Fleet One cards. Driver personal identification number. Only required for Fuelman cards. 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. Used internally The expiration date associated with the credit card number that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Used internally For use with Restaurant transactions only. The actual gratuity amount for a Sale with Gratuity (action code 14) , Gratuity (action code 13) , or PostAuthorization (action code 5) transaction. See the section Restaurant Transactions (see page 69) for more information.

CardPresent

String

Command

String

CmrclCardFlag

String

CustCode

String

CVV2

String

CreditPlanNumber

String String String

DriverID DriverPIN

DEST_ZIP_CODE

String

EnhancedTransFlag ExpDate ExtMsg

Boolean String String String

GratuityAmnt

254

Property Name

Data Type

Description - PccCharge Properties 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 GratuityAmntEst is populated, PCCharge will submit the sum of the values in the Amount and GratuityAmntEst 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 GratuityAmntEst, 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 place holder must be sent as well. See the section Restaurant Transactions (see page 69) 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. Only required for Voyager cards, dependant on Restriction Code. Four to six digits. Note: Only used for Pre-Authorization transactions Used internally Used internally 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 ItemCodes is set to 00010002000300040005, it stores 5 item IDs (0001, 0002, 0003, 0004, and 0005). These numbers must be obtained from Chase Paymentech. Used internally The last year that will be considered a valid expiration date. This value can be set programmatically or through the PCCharge GUI. Length: 2 digits. Format: YY Example: If LastValidDate is set to 05, then cards between 06 and 99 are considered to be 1906 to 1999, and cards between 00 and 05 are 2000 to 2005. Used internally Used internally Flag that indicates whether the transaction was manually entered or swiped. If the transaction was swiped, the Track property must also be set. Valid values: 0 = manual transaction, 1 = swiped transaction 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. 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 (see page 69) 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. The cardholders name. Max Length: 20 characters. The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Credit Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric.

GratuityAmntEst

String

IDNumber ImpTransFlag IsPurchaseCard

String Boolean Boolean

ItemCodes

String

LanguageCode

String

LastValidDate

String

MACData MACState Manual

String MACState Long

MCSC

String

MCSN

String

member

String String

MerchantNumber ***

Method

TxnMethodT Used internally ype

255

Property Name

Data Type

Description - PccCharge Properties 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line. The odometer reading. Only required for Fleet One (7 digits), Voyager (7 digits), and Fuelman (6 digits) cards. 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 The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

Multi

String

Odometer

String

Offline

String

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\".

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. 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. 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 the Processing Company Codes section (see page 101). Note: Only required for the processor NBS. This is the total dollar amount for PRODUCT_DETAIL_PRODUCT_CODE_XX 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 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. Note: Only required for the processor NBS. This is the number of items for PRODUCT_DETAIL_PRODUCT_CODE_XX. Currently, PCCharge will support 0 1 10. Note: Only used for the processor NBS. This is the unit price for PRODUCT_DETAIL_PRODUCT_CODE_XX. This is only used for Fleet One and Fuelman. Currently, PCCharge will support 01 10. The reference number from the original transaction (returned by the processor). Set this property only if processing a Post-Authorization and the PostAuthorization is being used to add a Voice-Authorization to the batch or to store a Voice-Authorization. (For information on stored Voice-Authorizations, see page 63). The Reference property does not need to be set if the PostAuthorization completes a standard Pre-Authorization using the TroutD value of the Pre-Authorization. See the section Follow On Transactions for more information (see page 58). 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.

PrintReceipts

String

Processor ***

String

ProductDetailAmount_XX

String

ProductDetailCount

String

ProductDetailCode_XX

String

ProductDetailQuantity_XX

String

Reference

String

256

Property Name

Data Type

Description - PccCharge Properties 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. Set to 1 if card information was read from RFID (Radio Frequency Identification) device. If card was read from from RFID, track data must be populated and manual flag must be set to 1. Set to 0 otherwise. Used internally Used internally Used internally Flag indicating whether a Voice Authorization transaction should be stored. This flag should only be submitted when performing a Post-Authorization transaction (action code 5) that includes an authorization code from the voice operator. For more information on stored Voice-Authorizations, see page 63. Valid Value: 1 Store the Voice Authorization transaction. 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 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. 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. 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 NOVA, ticket numbers can only be alphanumeric, no hyphens. The number of seconds after which a timeout error will be returned from PCCharge. The count will start when the Send method is called. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. Note: The TimeOut properly is only applicable when programming in an asynchronous manner. No longer needed The track II data captured from the magnetic strip of the credit card. The track II data is required to ensure the lowest per-transaction rate from the processing company when performing swiped transactions (Retail and Restaurant). Sending the track II data is not allowed if the merchant's industry type is MOTO or eCommerce. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in.

RestrictionCode

String

RFID ShiftID SmartTermMsg SmartTermRequest

String String String Boolean

Store

String

Street

String

TaxAmt

String

TaxExempt

Boolean

Ticket

String

TimeOut

Long

TotalAmount

String

Track

String

257

Property Name

Data Type

Description - PccCharge Properties 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50). Only required for Wright Express cards (5 digits) and Voyager cards (8 digits). Note: Required for both manual and swiped transactions. 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: If submitting the 9-digit zip, do not include the dash.

TroutD

String

User **

String

VehicleID

String

Zip

String

These properties are the minimum required to process a Sale or Pre-Authorization transaction. ** 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 (see page 50). 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. Consult the Multi-Merchant Support section (see page 56) for more information on the Use Default Processor option. In addition, Processor and MerchantNumber should not be set when doing follow-on transactions. Refer to the section Follow On Transactions (see page 58) for more information.

PccCharge Methods
Method Name Cancel CheckPCard Returned Value None Boolean Description - PccCharge Methods Cancels transaction in progress Used to determine whether a credit card is a commercial card or not. This method requires that a credit card number be passed as a parameter. Returns TRUE if a commercial card, FALSE otherwise. The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered (if asynchronous) and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). Returns the Authorization Characteristics Indicator is that is provided by the card associations. This value is stored for settlement. Only supported on Fleet One, this field contains miscellaneous additional text returned from host. Currently PCCharge will support GetAddText1GetAddText4. Returns the amount due. Only used for the processor NOVA. 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. Returns the authorization amount for the transaction. Only used for the processor NOVA.

DeleteUserFiles

None

GetACI

String String String String String

GetAddText1 GetAmountDue GetAuth

GetAuthAmount

258

Method Name

Returned Value

Description - PccCharge Methods 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 the section DevKit Constants for a description of values that may be returned (see page 94) 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, and that the transaction has been placed in the open batch. The GetCreditCardType method returns the abbreviation of the credit card issuer. This method requires that a credit card number be passed as a parameter. Consult the section DevKit Constants for descriptions of values (see page 94). (GetCreditCardType is the same as GetCardIssuer). Returns the PrePaid card balance. Only for pre-paid credit cards with NOVA. 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 the section DevKit Constants for a description of values that may be returned (see page 94) Returns the available balance on pre-paid debit cards. Only for pre-paid debit cards with NOVA. 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetHostType method returns an integer that indicates if a processor / merchant number is Host based or Terminal based. GetHostType requires three parameters: 1) Processor code - Consult the section DevKit Constants (see page 94) for a list of valid processor codes 2) Merchant account - Must be a valid merchant account set up in PCCharge 3) TID type - Valid Values for TID type: 0 Credit; 1 Check; 2 Debit; 3 EBT; 4 GiftCard GetHostType will return one the following values based on the parameters passed in: 0 The processor is Terminal based 1 The processor is Host based -1 The processor is a Hybrid (supports both Host and Terminal processing) or invalid processor / merchant number. Example: .GetHostType(VISA, 999999999911, 0) will return 0 Note: Chase Paymentech (GSAR), NOVA (NOVA), and FDMS South / NaBanco (NB) are considered hybrid processors. GetHostType will return a -1 for these processors. 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. Returns the Market Specific Indicator. This value indicates the transactions market segment. This value is assigned by the card associations and is not returned with all transactions. Returns the merchant number that was specified in the MerchantNumber property. Returns 1 if PCCharge recognizes the card as a purchasing/corporate card. Otherwise, PCCharge returns 0.

GetAVS

String

GetCaptured

Boolean

GetCreditCardType

String String

GetCCAvailBalance

GetCVV2

String

GetDCAvailBalance

String

GetErrorCode

Long

GetErrorDesc

String

GetHostType

Integer

GetIND

String

GetMSI

String String String

GetMerchantNumber GetPCard

259

Method Name GetPEM GetRecordCount

Returned Value String String String

Description - PccCharge Methods Returns the Point of Entry Mode that is associated with the transaction. This value is not returned by all processing companies. The number of records matching the inquiry (ZI command). 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. Returns the response code that is provided by the processor. This value is not returned by all processing companies. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. Note: Only supported on Fleet One. The product restriction code. Returns the Retrieval reference number. This value is not returned by all processing companies Returns the active batch number for the transaction. This value is not returned by all processing companies. Returns the date that the transaction was processed. This value is not returned by all processing companies. Returns the Transaction Identifier that is returned from the processor. This value is not returned by all processing companies. 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. Returns the Transaction Indicator Code that is returned from the processor. The Transaction Indicator Code is a Validation code for VISA / MasterCard. This value is not returned by all processing companies. Returns the Time of the transaction. This value is not returned by all processing companies. Returns the Transaction Item number or the number that is associated with the transaction in the settlement file. This value is not returned by all processing companies. Returns the trace number from the processor. Only for pre-paid credit cards with NOVA. 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. Contains nested XML tags providing information on transaction(s) pulled from Trans table in the PCCharge database (pccw.mdb) (ZI command). Returns the transaction reference number from the processor. Only for prepaid credit cards with NOVA. 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. See the section Follow On Transactions (see page 58) for more information. Used internally 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 from the .oux file can be used by integrators that wish to parse the results of the transaction themselves or for troubleshooting purposes. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method.

GetRefNumber

GetRespCode

String String String String String String String String

GetResult GetRestrictCode GetRET GetTBatch GetTDate GetTI

GetTicket

GetTICode

String String String String String String

GetTIM

GetTitem

GetTraceNumber

GetTransNum

GetTransRecord

GetTransactionReferenceNumb String er

GetTroutD

String

GetUpdateData

String

GetXMLResponse

String

260

Method Name

Returned Value

Description - PccCharge Methods The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has two optional parameters. The first parameter indicates whether the Send method will process transactions synchronously or asynchronously. Note: The object must defined to use events in order to allow asynchronous communication. Valid Values: True process asynchronously (Default) False process synchronously

PccSysExists

Boolean

Send

None

The second parameter indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send True, 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above.

ValidCardLength ValidCardLengthII ValidDate ValidIssuer

Boolean Boolean Boolean Boolean

Returns TRUE for card of correct length Returns TRUE for card of correct length The ValidDate method returns TRUE if the expiration date provided in the ExpDate property is valid, or FALSE if it is not. Returns TRUE for valid card issuer The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The VerifyCreditCard method returns TRUE if the credit card numbers format is valid and meets the requirements set forth by the credit card companies, FALSE if it does not. If FALSE is returned, use the GetErrorCode and GetErrorDesc methods to determine the reason for failure. VerifyCreditCard has a required string parameter in which the credit card number to be checked must be passed.

VerifyAmount

Boolean

VerifyCreditCard

Boolean

261

Method Name

Returned Value

Description - PccCharge Methods The VerifyExpDate method returns TRUE if the expiration date provided in the ExpDate property is correct and in the right format, or FALSE if it is not. VerifyExpDate calls the ValidDate function to validate the expiration date. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The VerifyMerchantNumber method returns TRUE if the merchant number that is passed to it is set up in PCCharge, otherwise, FALSE is returned. Specifically, this method checks for the merchant number in the file TID.PCC, which is located in the PCCharge directory. The Path property must be set before calling this Method. Returns TRUE if processor is valid

VerifyExpDate

Boolean

VerifyMerchantNumber

Boolean

VerifyProcessor

Boolean

PccCharge Events
Event Name Error Description - PccCharge Events The Error event is fired any time an error occurs in the class. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the Transaction Result Constants section (see page 103).

Finish

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

262

PCCDebit Class
The PCCDebit class provides integrators with properties and methods used to submit credit card transactions to PCCharge. To use the PCCDebit class to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the transaction to be performed and validate the values using the various .Verify methods. (The properties marked with a in the PCCDebit Properties table are the minimum required to process a Debit Sale transaction.) 3. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format) 4. If programming asynchronously, wait for the Error or Finish event to occur. 5. If programming synchronously, code using the .Get methods may be placed immediately after the Send method 6. Call the various .Get methods to determine the outcome of the transaction. The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error. 7. Call the DeleteUserFiles method to delete all files related to the transaction. 8. Destroy the object. When processing debit cards, a PINpad is required to allow the customer to enter their PIN. In addition, debit card information is always collected via a card swipe device, never via keyboard entry. Because of this, a card reader is also required. When processing U.S. debit card transactions, merchants have the option of allowing the customer to receive cash back on a transaction. For instance, the customer purchases $50 of products and wants $25 cash back, set the Amount to 50.00 and CashBack to 25.00. This will withdraw a total of $75 from the debit card account, $50 for the products and $25 for cash to give to the customer. Consult the section Pseudo-code (see page 105) for various examples that may be followed when using the Debit class to perform transaction processing. For information on integrating Canadian Debit, see the section Canadian (Interac) Debit Transactions (see page 77). This is a Multi Use class. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

263

PCCDebit Properties
Property Name Action Data Type Long Description - PCCDebit Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The AuthCode field is only applicable to EBT transactions. The Business / Batch Date. If populated, this value will be placed in the Business Date column of the transaction record in the PCCharge database (pccw.mdb). Format: MMDDYY Only valid for Visa debit and credit transactions. It is used to indicate the transaction is being ran for payment of a bill (ultilty, monthly gym dues, etc.) Valid values: 0 Non-Bill payment transaction 1 Bill payment transaction The Debit card number that will be used when processing the transaction. Max Length: 20 characters. Example: 5424180279791765 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 debit processors do not support the cash back feature. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the bank account type that the customer specified when entering transaction data into the PINpad. Valid Values: Chequing or Savings Driver identification field. Only required for Wright Express, Voyager and Fleet One cards. Driver personal identification number. Only required for Fuelman cards. Used internally Used internally The expiration date associated with the Debit card number that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Set this property if there is an expiration date associated with the Debit card. Used internally Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. This is the Gratuity Amount of the transaction. Only required for Voyager cards, dependant on Restriction Code. Four to six digits. Note: Only used for Pre-Authorization transactions If a Key Serial Number is returned from the PINpad, this property should be populated with that number. If processing transactions with a PINpad using DUKPT encryption, this value is sixteen or twenty characters long (depending on the processors encryption). The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. If processing transactions with a Verifone SC5000 PINpad, set this property to the Chip Serial Number of the PINpad.

Amount

String

AuthCode BDate

String String

Billpay

String

Card

String

CashBack

String

DebitType

String

DriverID DriverPIN EBTType EnhancedTransFlag ExpDate ExtFile Gratuity IDNumber

String String String Boolean String File String String

KeySerialNumber

String

264

Property Name

Data Type

Description - PCCDebit Properties Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the language that is indicated by the Language Code that is encoded in the track II data on the customers card. Valid Values: English or French (pass in the literal string) Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the MAC Block value returned by the PINpad. Used internally Flag that indicates whether the transaction was swiped or manually entered. This property must be set to 1 (swiped) and the Track property must also be set. The cardholders name. Max Length: 20 characters. The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Debit Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric.

LanguageCode

String

MACData MACState Manual member MerchantNumber ***

String MACState Integer String String

Method

TxnMethodT Used internally ype 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line. The odometer reading. Only required for Fleet One (7 digits), Voyager (7 digits), and Fuelman (6 digits) cards. The Original Purchase Data. Used when performing a Debit Return with the processors TSYS, Heartland, Lynk, and NPC. This is the original transaction date. Format: DDMMhhmm The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

Multi

Boolean

Odometer

String String

OrigPurchData

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\". The encrypted PIN block that is retrieved from the PINpad. The PIN is provided to the processor for verification. Length: 16 characters. The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. 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 the Processing Company Codes section (see page 101). Note: Only required for the processor NBS. This is the total dollar amount for PRODUCT_DETAIL_PRODUCT_CODE_XX 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 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.

Pin

String

Processor ***

String

ProductDetailAmount_XX

String

ProductDetailCount

String

265

Property Name ProductDetailCode_XX

Data Type String

Description - PCCDebit Properties Note: Only required for the processor NBS. This is the number of items for PRODUCT_DETAIL_PRODUCT_CODE_XX. Currently, PCCharge will support 0 1 10. Note: Only used for the processor NBS. This is the unit price for PRODUCT_DETAIL_PRODUCT_CODE_XX. This is only used for Fleet One and Fuelman. Currently, PCCharge will support 01 10. 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. 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. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. The Shift ID. This value is optional. Format: Alphanumeric Max Length: 1 character. Used internally Used internally 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: When using NOVA, ticket numbers can only be alphanumeric, no hyphens. The number of seconds after which a timeout error will be returned from PCCharge. The count will start when the Send method is called. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. Note: The TimeOut properly is only applicable when programming in an asynchronous manner. The track II data captured from the magnetic strip of the card. The track II data is required. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in. 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50). Only required for Wright Express cards (5 digits) and Voyager cards (8 digits). Note: Required for both manual and swiped transactions.

ProductDetailQuantity_XX

String

Reference

String

RestrictionCode

String

ShiftID SmartTermMsg SmartTermRequest

String String Boolean

Ticket

String

TimeOut

Long

Track

String

TroutD

String

User **

String

VehicleID

String

These properties are required to process a Debit Sale transaction. These properties are required to process a Canadian Debit Sale transaction using Global Payments East (NDC) and the SC5000 PINpad. ** 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 (see page 50). This section contains detailed information about user names and how they should be implemented.

266

*** 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. Consult the Multi-Merchant Support section (see page 56) for more information on the Use Default Processor option. In addition, Processor and MerchantNumber should not be set when doing follow-on transactions. Refer to the section Follow On Transactions (see page 58) for more information.

PCCDebit Methods
Method Name Cancel Returned Value None Description - PCCDebit Methods Cancels current transaction The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered (if asynchronous) and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). Only supported on Fleet One, this field contains miscellaneous additional text returned from host. Currently PCCharge will support GetAddText1GetAddText4. The GetApproved method returns TRUE if PCCharge returns "APPROVED" as the result of the transaction. Otherwise, FALSE will be returned. 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. When using the SC5000 PINpad, returns the ISO response code 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). For Debit Master Session: Returns the new master key (if one exists) sent by the processor that should be passed to the PINpad. Returns the merchant number that was specified in the MerchantNumber property. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Returns the current POS Sequence Number for the PINpad. The Path property must be set to the PCCharge directory and the PINpads Chip Serial Number must be passed as a parameter when calling the GetPOSSequenceNumber method. Returns the reference number associated with the transaction. 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. Returns the response code that is provided by the processor. This value is not returned by all processing companies. Note: Only supported on Fleet One. The product restriction code. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. Returns the Transaction Identifier that is returned from the processor. This value is not returned by all processing companies. Returns the Transaction Indicator Code that is returned from the processor. This value is not returned by all processing companies.

DeleteUserFiles

None

GetAddText1

String Boolean String String

GetApproved

GetAuth GetAuxRespCode

GetErrorCode

Long

GetErrorDesc

String

GetMSI GetMerchantNumber

String String

GetPOSSequenceNumber

String

GetRefNumber

String

GetRespCode GetRestrictCode GetResult

String String String String String

GetTI GetTICode

267

Method Name

Returned Value String

Description - PCCDebit Methods 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. 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. See the section Follow On Transactions (see page 58) for more information. Used internally 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 from the .oux file can be used to view the results of a Transaction Inquiry (ZI) transaction. Refer to the section Transaction Inquiry (see page 85) for more information. The text can also be used by integrators that wish to parse the results of the transaction themselves or for troubleshooting purposes. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has two optional parameters. The first parameter indicates whether the Send method will process transactions synchronously or asynchronously. Note: The object must defined to use events in order to allow asynchronous communication. Valid Values: True process asynchronously (Default) False process synchronously

GetTransNum

GetTroutD

String

GetUpdateData

String

GetXMLResponse

String

PccSysExists

Boolean

Send

None

The second parameter indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send True, 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above.

268

Method Name

Returned Value

Description - PCCDebit Methods The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

VerifyAmount

Boolean

PCCDebit Events
Event Name Error Description - PCCDebit Events The Error event is fired any time an error occurs in the class. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the Transaction Result Constants section (see page 103).

Finish

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

269

PccCheck Class
The PccCheck class provides integrators with properties and methods used to submit check verification, guarantee, and conversion transactions to PCCharge. To use the PccCheck class to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the transaction to be performed and validate the values using the various .Verify methods. (The properties marked with a in the PccCheck Properties table are the minimum required to process a check verification transaction.) 3. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format) 4. If programming asynchronously, wait for the Error or Finish event to occur. 5. If programming synchronously, code using the .Get methods may be placed immediately after the Send method 6. Call the various .Get methods to determine the outcome of the transaction. The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error. 7. Call the DeleteUserFiles method to delete all files related to the transaction. 8. Destroy the object. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

270

PccCheck Properties
Property Name Account_Number Action Data Type String Long Description - PccCheck Properties For Check, MICR, or Double ID: The account number that will be used when processing the transaction. Max Length: 20 characters. The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The date of birth of the check writer. Length: Exactly six characters. Format: MMDDYY. The birth date is required for DL (Drivers License) check transactions. 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. The Cashier Number The check number of the check that will be used when processing the transaction. Max Length: 10 characters. The drivers license number of the individual writing the check. Max Length: 20 characters. The drivers license is required for DL (Drivers License) transactions and when performing Double ID transactions. Used internally Used internally Used for BPS Double ID transactions. Optional Manager Number for manager override. Flag that indicates whether the transaction was manually entered or swiped. Valid values: 0 = manual transaction, 1 = swiped transaction The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Check Services Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric.

Amount

String

Birth_Date

String

Cash_Back

String

CashierNum Check_Number

String String String Boolean String String Long

Drivers_License EnhancedTransFlag LanguageCode ManagerNum Manual

MerchantNumber

String

Method MICR

TxnMethodT Used internally ype String The raw MICR data from the bottom of the check. Used for conversion transactions. 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

Multi

Boolean

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\".

271

Property Name Phone_Number

Data Type String

Description - PccCheck Properties The phone number of the individual writing the check. Max Length: 7 digits. Format: digits only. The phone number is required for COD (Checks On Delivery). 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 the Processing Company Codes section (see page 101). The type of check verification to be performed. Valid values: 0 MICR 1 Checks-On-Delivery 2 Drivers License 3 Double ID Note: The value set in the Services property overrides the value set in the Action property.

Processor

String

Services

Integer

ShiftID State

String String

Used internally The state code of the state that issued the check writers drivers license. The state code is required for DL (Drivers License). Format: 2 characters. 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: When using NOVA, ticket numbers can only be alphanumeric, no hyphens. The number of seconds after which a timeout error will be returned from PCCharge. The count will start when the Send method is called. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. Note: The TimeOut properly is only applicable when programming in an asynchronous manner. The Transit Routing Number / ABA number that will be used when processing the transaction. This value indicates which bank issued the check. Max Length: 9 characters. This value is required for MICR transactions and when performing Double ID transactions. 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50). The check writers ZIP code. Max Length: 9 characters. Format: digits only. This value is required for COD transactions. Note: If submitting the 9-digit zip, do not include the dash.

Ticket

String

TimeOut

Long

Transit_Number

String

TroutD

String

User **

String

Zip_Code

String

Note: To perform Double ID, both the MICR and Drivers_License fields must be populated. These properties are required, regardless of service type. ** 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 (see page 50). This section contains detailed information about user names and how they should be implemented. COD -- required for Checks-On-Delivery DL -- required for Drivers License MICR -- required for MICR

272

PccCheck Methods
Method Name Cancel Returned Value None Description - PccCheck Methods Cancels transaction in progress The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered (if asynchronous) and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). The GetApproved method returns TRUE if PCCharge returns "APPROVED" as the result of the transaction. Otherwise, FALSE will be returned. An APPROVED response indicates that a Verification has been approved. 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. 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns the merchant number that was specified in the MerchantNumber property. Returns the reference number associated with the transaction. The reference number is used to help identify the transaction and is useful for the check writer and merchant when doing research. This value is not returned with all transactions. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. 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. See the section Follow On Transactions (see page 58) for more information. Used internally 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 from the .oux file can be used by integrators that wish to parse the results of the transaction themselves or for troubleshooting purposes. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions.

DeleteUserFiles

None

GetApproved

Boolean

GetAuth

String

GetErrorCode

Long

GetErrorDesc

String

GetMerchantNumber

String

GetRefNumber

String

GetResult

String

GetTroutD

String

GetUpdateData

String

GetXMLResponse

String

PccSysExists

Boolean

273

Method Name

Returned Value

Description - PccCheck Methods The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has two optional parameters. The first parameter indicates whether the Send method will process transactions synchronously or asynchronously. Note: The object must defined to use events in order to allow asynchronous communication. Valid Values: True process asynchronously (Default) False process synchronously

Send

None

The second parameter indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send True, 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above. The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

VerifyAmount

Boolean

274

PccCheck Events
Event Name Error Description - PccCheck Events The Error event is fired any time an error occurs in the class. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the Transaction Result Constants section (see page 103).

Finish

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

275

PCCEBT Class
The PCCEBT class provides integrators with properties and methods used to submit EBT transactions to PCCharge. To use the PCCEBT class to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the transaction to be performed and validate the values using the various .Verify methods. (The properties marked with a in the PCCEBT Properties table are the minimum required to process an EBT transaction.) 3. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format) 4. If programming asynchronously, wait for the Error or Finish event to occur. 5. If programming synchronously, code using the .Get methods may be placed immediately after the Send method 6. Call the various .Get methods to determine the outcome of the transaction. The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error. 7. Call the DeleteUserFiles method to delete all files related to the transaction. 8. Destroy the object.

When processing EBT cards, a PINpad is required to allow the customer to enter their PIN. In addition, debit card information is always collected via a card swipe device, never via keyboard entry. Because of this, a card reader is also required. (Some EBT transactions can be manually entered). When processing EBT card transactions, merchants have the option of allowing the customer to receive cash back on a transaction. For instance, the customer purchases $50 of products and wants $25 cash back, set the Amount to 50.00 and CashBack to 25.00. This will withdraw a total of $75 from the EBT card account, $50 for the products and $25 for cash to give to the customer. This is a Multi Use Class. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

276

PCCEBT Properties
Property Name Action Data Type Long Description - PCCEBT Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). For an EBT Post (Prior Auth Sale) or Force transaction: The Authorization code from the original voice authorization. The Business / Batch Date. If populated, this value will be placed in the Business Date column of the transaction record in the PCCharge database (pccw.mdb). Format: MMDDYY Only valid for Visa debit and credit transactions. It is used to indicate the transaction is being ran for payment of a bill (ultilty, monthly gym dues, etc.) Valid values: 0 Non-Bill payment transaction 1 Bill payment transaction The EBT card number that will be used when processing the transaction. Max Length: 20 characters. Example: 5424180279791765 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 debit processors do not support the cash back feature. Indicates what type of EBT transaction will be performed. Valid Values: F Food stamp transaction; C Cash benefits transaction Used internally The expiration date associated with the EBT card number that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Set this property if there is an expiration date associated with the EBT card. Used internally If a Key Serial Number is returned from the PINpad, this property should be populated with that number. This value is only applicable for PINpads using DUKPT encryption. This value is sixteen or twenty characters long (depending on the processors encryption). The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. Used internally Used internally Flag that indicates whether the transaction was swiped or manually entered. This property must be set to 1 (swiped) for swiped EBT transactions. If the transaction was swiped, the Track property must also be set. If performing a manually keyed EBT transaction, such as a Force or Voucher, set this property to 0 (manually entered). The cardholders name. Max Length: 20 characters. The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the EBT Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric.

Amount

String

AuthCode

String String

BDate

Billpay

String

Card

String

CashBack

String

EBTType EnhancedTransFlag

String Boolean String String

ExpDate

ExtFile

KeySerialNumber

String

MACData MACState

String MACState

Manual

Integer

member

String String

MerchantNumber

277

Property Name Method

Data Type

Description - PCCEBT Properties

TxnMethodT Used internally ype 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line. Not needed for EBT Transactions. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

Multi

Boolean

OrigPurchData

String

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\". The encrypted PIN block that is retrieved from the PINpad. The PIN is provided to the processor for verification. Length: 16 characters. The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. 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 the Processing Company Codes section (see page 101). No longer needed Used internally Used internally 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: When using NOVA, ticket numbers can only be alphanumeric, no hyphens. The number of seconds after which a timeout error will be returned from PCCharge. The count will start when the Send method is called. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. Note: The TimeOut properly is only applicable when programming in an asynchronous manner. The track II data captured from the magnetic strip of the card. The track II data is required for swiped EBT transactions. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in. 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 more information on user names, consult the Multi-User Support section (see page 50). The voucher number for an EBT force transaction. The voucher is provided by the processor at the time of authorization and must be supplied to clear the voucher.

Pin

String

Processor

String

Reference SmartTermMsg SmartTermRequest

String String Boolean

Ticket

String

TimeOut

Long

Track

String

TroutD

String

User

String

VoucherNum

String

278

 These fields are required to process a transaction. ** 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 (see page 50). This section contains detailed information about user names and how they should be implemented.

PCCEBT Methods
Method Name BalanceTotals Cancel Returned Value String None Description - PCCEBT Methods Current amount of EBT transactions Cancels current transaction The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered (if asynchronous) and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). The GetApproved method returns TRUE if PCCharge returns "APPROVED" as the result of the transaction. Otherwise, FALSE will be returned. 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. When using the SC5000 PINpad, returns the ISO response code Returns the remaining balance on a Cash Benefits card. This value is not returned by all processing companies. Returns the remaining balance on a Food Stamp card. This value is not returned by all processing companies. 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns the merchant number that was specified in the MerchantNumber property. Returns the reference number associated with the transaction. 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. Returns the response code that is provided by the processor. This value is not returned by all processing companies. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. Returns the Transaction Identifier that is returned from the processor. This value is not returned by all processing companies. Returns the Transaction Indicator Code that is returned from the processor. This value is not returned by all processing companies. 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.

DeleteUserFiles

None

GetApproved

Boolean String String String String

GetAuth GetAuxRespCode GetEBTCashBalance GetEBTFoodBalance

GetErrorCode

Long

GetErrorDesc

String

GetMerchantNumber

String

GetRefNumber

String

GetRespCode

String String String String String

GetResult

GetTI GetTICode

GetTransNum

279

Method Name

Returned Value

Description - PCCEBT Methods 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. See the section Follow On Transactions (see page 58) for more information. Used internally 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 from the .oux file can be used by integrators that wish to parse the results of the transaction themselves or for troubleshooting purposes. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has two optional parameters. The first parameter indicates whether the Send method will process transactions synchronously or asynchronously. Note: The object must defined to use events in order to allow asynchronous communication. Valid Values: True process asynchronously (Default) False process synchronously

GetTroutD

String

GetUpdateData

String

GetXMLResponse

String

PccSysExists

Boolean

Send

None

The second parameter indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send True, 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above. The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

VerifyAmount

Boolean

280

PCCEBT Events
Event Name Error Description - PCCEBT Events The Error event is fired any time an error occurs in the class. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the Transaction Result Constants section (see page 103).

Finish

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

281

PCCGiftCard Class
The PCCGiftCard class provides integrators with properties and methods used to submit gift card transactions to PCCharge. To use the PCCGiftCard class to integrate transaction processing, follow the procedure below: 1. Set the path to the PCCharge directory and check to see if PCCharge is running and available to process transactions by using the PccSysExists method. 2. Assign the appropriate values to the properties required for the transaction to be performed and validate the values using the various .Verify methods. (The properties marked with a in the PCCGiftCard Properties table are the minimum required to process a Gift Card Redemption / Sale transaction.) 3. Call the Send method. (Note: When calling the Send method, it is recommended that 3 is passed as a parameter to activate the XML message format) 4. If programming asynchronously, wait for the Error or Finish event to occur. 5. If programming synchronously, code using the .Get methods may be placed immediately after the Send method 6. Call the various .Get methods to determine the outcome of the transaction. The most important information can be acquired by calling the GetResult and GetAuth methods. If an error occurs, call the GetErrorCode and GetErrorDesc methods to determine the nature of the error. 7. Call the DeleteUserFiles method to delete all files related to the transaction. 8. Destroy the object. Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

VeriFone Stored Value API (GAPI)

The VeriFone Stored Value API (GAPI) is a proprietary specification that allows for stored value card processors to add themselves to PCCharge. Applications using GAPI can also integrate with PCCharge using the various integration methods. For more information on adding a stored value card processor to PCCharge, and how to obtain the VeriFone Stored Value API, please contact VeriFone sales at 1-800725-9264.

282

PCCGiftCard Properties
Property Name Action Data Type Long Description - PCCGiftCard Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 place holder must be sent as well. Example: 0.50. For Valuelink (VLNK) Balance Adjustment: Format: +/DDDDD.CC. For Void transactions. For VTEC and VLNK, set to auth code of original transaction (the one to be voided). For GSAR and MELL, set to ref num of original transaction (the one to be voided). For BPS, set to retrieval reference number of original transaction (the one to be voided). The Business / Batch Date. If populated, this value will be placed in the Business Date column of the transaction record in the PCCharge database (pccw.mdb). Format: MMDDYY The gift card number that will be used when processing the transaction. Max Length: 20 characters. For GSAR multi Issuance, sequence number of cards issued at time of transaction. Example: Ten cards are being issued. To send the fifth, set CardSeqNum to 5. VTEC and VLNK -- (optional) numeric value that identifies the cashier performing the transaction. 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 Used internally The expiration date associated with the gift card that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Note: Most gift cards do not have an expiration date. Used internally Set to true (1 = true, 0 = false) to process a transaction for which an approval code has already been issued -- only valid for a GSAR Redemption transaction or a single GSAR Issuance/Add Value transaction. Only used for the processor SVS. To retrieve pin, call GetGfitPin upon activation. Used for only for virtual gift card transactions. Indicates industry type (1 = retail, 2 = restaurant). VLNK -- (0 = retail, 1 = restaurant, 2 = e-commerce). Used internally The last year that will be considered a valid expiration date. Length: 2 digits. Format: YY Example: If LastValidDate is set to 05, then cards between 06 and 99 are considered to be 1906 to 1999, and cards between 00 and 05 are 2000 to 2005. VTEC loyalty transaction flag (0 = non-loyalty, 1 = loyalty). The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Gift Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric.

Amount

String

Authcode

String

BDate

String String String String

Card CardSeqNum

CashierID

DeactivateRefund

Boolean Boolean String String Boolean String String String String Boolean String

EnhancedTransFlag ExpDate ExtFile FORCE

GiftPin IndType LanguageCode

LastValidDate

Loyalty

MerchantNumber

Method

TxnMethodT Used internally ype 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line.

Multi

Boolean

283

Property Name OldCard

Data Type String Boolean

Description - PCCGiftCard Properties VTEC -- Replace transaction. Set to account number of old card. VLNK -Balance Merge and Balance Transfer transactions. Set to account number of old card. For GSAR: Flag indicating whether the transaction is a partial redemption transaction. The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory.

Partial

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ Path Formats: UNC, MS-DOS (8 Characters) and Long. 100 characters maximum. Must end with a "\".

Pin Points

String String String

Used internally for Givex. For GVEX Points transactions. Set to number of loyalty points for account. 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. 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 the Processing Company Codes section (see page 101). Used for GVEX: A code defined by the merchant that affects the calculation from amount and units to points. 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 Used internally No longer needed 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 gift processors support ticket numbers. The number of seconds after which a timeout error will be returned from PCCharge. The count will start when the Send method is called. It is highly recommended that integrators review the section Timeouts (see page 47). Setting the TimeOut value improperly could cause reconciliation issues and problems such as double-charging a customers account. Note: The TimeOut properly is only applicable when programming in an asynchronous manner. Used for VTEC and VLNK restaurant transactions. For GSAR multi Issuance, total number of cards being issued at time of transaction. The track II data captured from the magnetic strip of the card. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in. 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. Only used for the processor SVS. 0 - False, 1 - True Only sent on an activation to determine if a pin should be returned.

PrintReceipts

Processor

String

PromoCode

String

Refund

String String String String

ShiftID TI

Ticket

TimeOut

Long

TIP TotalCardNum

String String

Track

String

TroutD

String

VirtualGiftCardFlag

Boolean

284

Property Name User **

Data Type String

Description - PCCGiftCard Properties 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 more information on user names, consult the Multi-User Support section (see page 50).

These properties are required to process a gift card redemption or sale transaction. Required for VTEC gift card transactions ** 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 (see page 50). This section contains detailed information about user names and how they should be implemented.

PCCGiftCard Methods
Method Name Cancel Returned Value None Description - PCCGiftCard Methods Cancels transaction in progress The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered (if asynchronous) and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). Returns the number of activations in the current batch Returns the total dollar amount of activations in the current batch Returns the number of AddPoints Transactions in the current batch Returns the total dollar amount of AddPoints transactions in the current batch Returns the number of AddValue transactions in the current batch Returns the total dollar amount of AddValue transactions in the current batch Used in partial redemption transactions where only part of the amount was authorized. Returns the remainder amount that is owed to the merchant. 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 transactions 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>. Used in partial redemption transactions where only part of the amount was authorized. Returns the actual authorized amount. Returns the number of Balance Transfers in the current batch Returns the total dollar amount of Balance Transfers in the current batch 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. 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. Returns the number of credits in the current batch Returns the total dollar amount of credits in the current batch

DeleteUserFiles

None

GetActivationCount GetActivationTotalAmount GetAddPointsCount GetAddPointsTotalAmount GetAddValueCount GetAddValueTotalAmount GetAmountDue

String String String String String String String

GetAuth

String

GetAuthAmount GetBalanceTransferCount

String String

GetBalanceTransferTotalAmou String nt

GetCaptured

String

GetCashBack GetCreditCount GetCreditTotalAmount

String String String

285

Method Name

Returned Value

Description - PCCGiftCard Methods 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns the expiration date for processors who issue expiration dates in the response. Returns the gift card balance. Returns type of gift card represented by card property. Consult the section DevKit Constants for descriptions of values (see page 94). Only used for the processor SVS. Returned on activation if the virtual gift card tag is set to 1. Returns the MiscMessage Returns the merchant number that was specified in the MerchantNumber property. Returns the number of points transactions in the current batch Returns the total dollar amount of points transactions in the current batch The processor response code. Only returned by the processor SVS. 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 accounts 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. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. 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. Returns the number of redemptions in the current batch Returns the total dollar amount of redemptions in the current batch 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>.>. 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>.>. Returns the Time of the transaction. This value is not returned by all processing companies. For VTEC, returns the Amount Due. Returns the number of Tip transactions in the current batch Returns the total dollar amount of Tip transactions in the current batch Returns the transaction date and time when passed back by a processor. 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.

GetErrorCode

Long

GetErrorDesc

String

GetExp GetGiftCardBalance GetGiftCardType GetGfitPin GetMiscMessage GetMerchantNumber GetPointsCount GetPointsTotalAmount GetProcRespCode

String String String String String String String String String

GetRefNumber

String

GetResult

String

GetRET

String String String

GetSaleCount GetSaleTotalAmount

GetTI

String

GetTicket

String

GetTIM GetTipCount GetTipTotalAmount GetTransDateTime GetTransNum

String String String String String

286

Method Name

Returned Value

Description - PCCGiftCard Methods 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. See the section Follow On Transactions (see page 58) for more information. Used internally Returns the Void Balance Returns the number of voids in the current batch Returns the total dollar amount of Voids in the current batch 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 from the .oux file can be used by integrators that wish to parse the results of the transaction themselves or for troubleshooting purposes. Refer to the section File Method (see page 409) for a description of the tags and values that are returned. Note: This method must be called prior to calling the DeleteUserFiles method. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions. The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has two optional parameters. The first parameter indicates whether the Send method will process transactions synchronously or asynchronously. Note: The object must defined to use events in order to allow asynchronous communication. Valid Values: True process asynchronously (Default) False process synchronously

GetTroutD

String

GetUpdateData GetVoidBalance GetVoidCount GetVoidTotalAmount

String String String String

GetXMLResponse

String

PccSysExists

Boolean

Send

None

The second parameter indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send True, 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above.

ValidCardLength ValidDate ValidIssuer

Boolean Boolean Boolean

Returns TRUE for card of correct length The ValidDate method returns TRUE if the expiration date provided in the ExpDate property is valid, or FALSE if it is not. Returns TRUE for valid card issuer

287

Method Name

Returned Value

Description - PCCGiftCard Methods The VerifyAmount method returns TRUE if the amount provided in the Amount property is in a valid format (DDDDDD.CC), or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The VerifyAmount2 method returns TRUE if the amount provided in the Amount property is in a valid format (+/-DDDDD.CC). or FALSE if it is not. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). The difference between VerifyAmount and VerifyAmount2 is that VerifyAmount2 allows a + or to be in the first position of the Amount property. This is needed for Balance Adjustment transactions. The VerifyExpDate method returns TRUE if the expiration date provided in the ExpDate property is correct and in the right format, or FALSE if it is not. VerifyExpDate calls the ValidDate function to validate the expiration date. If FALSE is returned, check the error code to determine the reason for failure. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns TRUE if card is correctly formatted The VerifyMerchantNumber method returns TRUE if the merchant number that is passed to it is set up in PCCharge, otherwise, FALSE is returned. Specifically, this method checks for the merchant number in the file TID.PCC, which is located in the PCCharge directory. The Path property must be set before calling this Method. Returns TRUE if processor is valid Only for GAPI, this returns the total number of gift card pre-auth transactions processed that day. Only for GAPI, this returns the total amount of gift card pre-auth transactions processed that day. Only for GAPI, this returns the total number of gift card post-auth transactions processed that day. Only for GAPI, this returns the total amount of gift card post-auth transactions processed that day. Only for GAPI, this returns the total number of gift cards issued that day. Only for GAPI, returns the total amount of the gift cards issued that day. Only for GAPI, this returns how many gift cards where deactivated that day. Only for GAPI, this returns the total amount of gift card deactivations that day. Only for GAPI, this returns the number of gift cards that were balance adjusted that day. Only for GAPI, this returns the total amount of balance adjustments on gift cards that day. Only for GAPI, this returns the total number of the gift cards that were balance merged that day. Only for GAPI, this returns the total amount of gift card balance merges that day. Only for GAPI, returns the total reported stolen or lost gift cards that day. Only for GAPI, returns the total amount of all stolen or reported lost gift cards that day. Only for GAPI, returns the total amount of all cashout transactions processed that day. Only for GAPI, returns the total number of the cashout transactions processed that day. Only for GAPI, returns the total number of gift cards that have been reactivated that day. Only for GAPI, the total amount of all gift cards that have been reactivated that day.

VerifyAmount

Boolean

VerifyAmount2

Boolean

VerifyExpDate

Boolean

VerifyGiftCard

Boolean

VerifyMerchantNumber

Boolean

VerifyProcessor GetPreAuthCount GetPreAuthAmount GetPostAuthCount GetPostAuthAmount GetIssuanceCount GetIssuanceTotalAmount GetDeactivateCount GetDeactivateTotalAmount GetBalanceAdjustCount

Boolean String String String String String String String String String

GetBalanceAdjustTotalAmount String GetBalanceMergeCount GetBalanceMergeTotalAmount GetReportLostStolenCount String String String

GetReportLostStolenTotalAmo String unt GetCashoutTotalAmount GetCashoutCount GetReactivateCount GetReactivateTotalAmount String String String String

288

PCCGiftCard Events
Event Name Error Description - PCCGiftCard Events The Error event is fired any time an error occurs in the class. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the Transaction Result Constants section (see page 103).

Finish

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

289

PccBatch Class
The PccBatch class is used to perform inquire and close operations on Host based merchant accounts. To perform a batch operation, follow the procedure below: 1. Assign the appropriate values to at least the minimum set of properties (marked with a in the PccBatch Properties table). 2. Call the BatchFunction method to initiate the operation. BatchFunction will respond when the operation is complete. 3. Grab values from the various return properties. Response contains a string that indicates how the operation was resolved.

PccBatch Properties
Property Name Action ActiveID* AmexAmount* AmexAuthSettlement AmexCount* Balance* Data Type Integer Integer String Boolean String String Description - PccBatch Properties The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). Returns the Index number of the merchant number associated with the batch operation. For example, the first Merchant number that is set up in PCCharge is assigned the index of 1 . Returns the total dollar amount of Amex transactions in current batch Amex Auth Settlement flag Returns Number of Amex transactions in current batch Returns the batch balance (the sum of all transactions in the batch) Flag that determines what type of batch close will occur. This flag only supported by Buypass and Fifth-Third when using action code 30 or 31 Valid values: 1 Standard End of Day Batch Close (Default) 2 Shift Close 3 Fifth-Third Terminal Based Batch Close of Debit, EBT, or Gift Returns the date batch was closed (not supported by all processors) Returns the batch number for the current batch Returns the compliance indicator code Returns the Debit Amount Returns the Debit Count Returns the Debit Returns Amount Returns the Debit Returns Count Returns the EBT Amount Returns the EBT Count This value specifies if the modem should be hung up on subsequent calls to the BatchFunction method. The integer value passed in will cause a delay of that amount, in seconds, after the modem hangup command is called. This allows time for the modem to hangup before batch functions are allowed to call out. Setting the value to '0', the default, will prevent the modem from being hung up. Returns the total number of transactions in the current batch The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Credit Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric.

BatchCloseType

Byte

BatchDate* BatchNumber* CIC* DebitAmount* DebitCount* DebitRetAmount* DebitRetCount* EBTAmount* EBTCount*

String String String String String String String String String

HangUpDelay

Integer

ItemCount*

String String

MerchantNumber

290

Property Name

Data Type

Description - PccBatch Properties The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the BatchFunction method.

Path

String

Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\". The code for the processing company that will be used when performing batch operations. 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 the Processing Company Codes section (see page 101). Returns the total dollar amount of all purchases (sales) in the batch. Returns the total number of all purchases (sales) in the batch. Response string returned by processor. Returns the result of the batch operation. Valid Values: 2 Batch Closed/Settled 6 Batch Declined 8 Batch Deferred Returns the total dollar amount of all returns (credits) in the batch. Returns the total number of all returns (credits) in the batch. Status of current batch. Only used when settling the processor CITI for private label transactions. Set this property to the main credit card processor ID code being used. Store number associated with merchant account. Terminal ID associated with merchant account. Totals Type Total amount of VISA/MasterCard transactions. Number of VISA/MasterCard transactions. Returns the total dollar amount of all void transactions in the batch. Returns the total number of all void transactions in the batch.

Processor

String

PurchaseAmount* PurchaseCount* Response*

String String String

ResultCode*

Byte

ReturnAmount* ReturnCount* Status* SplitProcessor Store* Terminal* TotalsType* VisaMCAmount* VisaMCCount* VoidAmount* VoidCount*

String String String String String String Byte String String String String

These properties are required to process a transaction. * The processor returns these values.

PccBatch Methods
Method Name AmexBatch BancTecBatch BatchFunction BPASBatch BPASTCPBatchCall Cancel CCRDBatch GetErrorCode Returned Value Boolean Boolean Boolean Boolean None None Boolean Long Description - PccBatch Methods Used internally Used internally Call this method to start batch operation Used internally Used internally Cancels the current batch operation Used internally The GetErrorCode method returns an error code if an error was encountered during use of various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

GetErrorDesc

String

291

PccSettle Class
This class is used for settling batches with Terminal based systems. The batch must be settled regularly (at least once per day, ideally) to ensure that the funds from transactions are deposited before the authorizations expire. PccSettle Properties
Property Name ActiveID* AmexAuthSettlement Balance* Batches* BatchNumber* Error_Record* Indeterminate* ItemCount* Data Type Integer Boolean String String String Integer Boolean String String Integer Boolean Boolean Description - PccSettle Properties Returns the Index number of the merchant number associated with the batch operation. For example, the first Merchant number that is set up in PCCharge is assigned the index of 1 . Amex Auth Settlement Flag Returns the batch balance (the sum of all transactions in the batch) Returns the number of batches settled Returns the batch number. Returns the index number of the transaction that cannot settle if an error occurs settling the batch Returns TRUE if the batch fails and returns an indeterminate response. Returns the number of items in current batch The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Credit Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. Returns the total number of messages sent to the processor Returns TRUE if PCCharge has no record of transactions to settle Returns TRUE if the processor has no record of transactions to settle The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the SettleBatch method. Path String Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\". The code for the processing company that will be used when performing batch operations. 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 the Processing Company Codes section (see page 101). Used internally Returns the result of the batch operation. Valid Values: 2 Batch Closed/Settled 6 Batch Declined 8 Batch Deferred Returns the Settlement number from the processor Returns the Response from the processor Returns the Status of the batch Returns the Number of transactions in current batch

MerchantNumber MessageCount* NoFile* NoSettle*

Processor

String

record

Integer

ResultCode

Byte

SettleNumber* SettleResponse* Status* TCount*

String String String String

These properties are required to process a transaction. * The processor returns these values.

292

PccSettle Methods
Method Name Cancel Clear ClearResponse CloseAmexSettleFile CreateAmexSettleFile CreateCESSettleFile CreateFDCNSettleFile CreateFDCSettleFile CreateGSARSettleFile CreateNBSettleFile CreateNDCSettleFile CreateNOVASettleFile CreateNPCSettleFile CreateNVUSSettleFile CreateTELMSettleFile CreateVISAKSettleFile DecryptSettleFile EncryptAmexArchiveBatches EncryptSettleFile GetAmexBatchTotal Returned Value None None None Boolean Boolean None None None None None None None None None None None Boolean Boolean Boolean Boolean Description - PccSettle Methods Cancels the current batch operation The Clear method will clear the values in all properties and methods. The Clear method will clear the values in all response related properties and methods. Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Calculates the Amex Batch total. The ItemCount and Balance properties will contain the returned data. TRUE is returned if the operation is successful, FALSE otherwise. Initiates an inquiry; returns TRUE if the inquiry was successful. Use this to determine how many batches are waiting to be settled. If multiple batches, a response will be returned for each batch. A loop must be initiated to read the response from each batch. The GetErrorCode method returns an error code if an error was encountered during use of various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Initiates AMEX direct settlement; returns TRUE if the settlement was successful. Initiates a settlement; returns TRUE if the settlement was successful Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally Used internally

GetBatchTotal

Boolean

GetErrorCode

Long

GetErrorDesc

String

SettleAmex SettleBatch UpdateSettleDB WriteAmexSettleRecord WriteCESSettleDB WriteFDCNSettleDB WriteFDCSettleDB WriteGSARSettleDB WriteNBSettleDB WriteNDCSettleDB WriteNOVASettleDB WriteNPCSettleDB WriteNVUSSettleDB WriteTELMSettleDB WriteVisaKSettleDB

Boolean Boolean None Boolean None None None None None None None None None None None

293

Note: In the event there are multiple batches waiting to be settled in one settlement, the integrated application will need to be designed to loop through the settlement response to retrieve the response for each batch.

294

PccSettleGift Class
This class is used for settling batches with Gift Card Processors. The batch must be settled regularly (at least once per day, ideally) to ensure that the funds from transactions are deposited before the authorizations expire. PccSettleGift Properties
Property Name ActiveID* Balance* Batches* Error_Record* ItemCount* Data Type Integer String String Integer String String Integer Boolean Boolean Description - PccSettleGift Properties Returns the Index number of the merchant number associated with the batch operation. For example, the first Merchant number that is set up in PCCharge is assigned the index of 1 . Returns the batch balance (the sum of all transactions in the batch) Returns the number of batches settled Returns the index number of the transaction that cannot settle if an error occurs settling the batch Returns the number of items in current batch The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Credit Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. Returns the total number of messages sent to the processor Returns TRUE if PCCharge has no record of transactions to settle Returns TRUE if the processor has no record of transactions to settle The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the SettleBatch method. Path String Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\". The code for the processing company that will be used when performing batch operations. 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 the Processing Company Codes section (see page 101). Used internally Returns the Settlement number from the processor Returns the Response from the processor Returns the Status of the batch Returns the Number of transactions in current batch

MerchantNumber MessageCount* NoFile* NoSettle*

Processor

String

record SettleNumber* SettleResponse* Status* TCount*

Integer String String String Integer

These properties are required to process a transaction. * The processor returns these values.

PccSettleGift Methods
Method Name Cancel Clear GetBatchTotal GetErrorCode Returned Value None None Boolean Long Description - PccSettleGift Methods Cancels the current batch operation The Clear method will clear the values in all properties and methods. Initiates an inquiry; returns TRUE if the inquiry was successful The GetErrorCode method returns an error code if an error was encountered during use of various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99).

295

Method Name

Returned Value String

Description - PccSettleGift Methods The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). This method returns the index of the credit card merchant number that relates to a gift card merchant number. Two parameters, the gift card merchant number and the gift card processor code must be passed when calling this method. Initiates a settlement; returns TRUE if the settlement was successful

GetErrorDesc

GetGiftTIDSeqNumber

Integer Boolean

SettleBatch

296

PccPinPad Class
The PccPinPad class allows integration to PINpad devices connected to the serial port. This is a Multi Use class. The PccPinPad class provides the functionality to Initialize a PINpad and to retrieve the PIN from the cardholder. The PINpad must be initialized once prior to retrieving the PIN. If the PINpads power is cycled, it must be re-initialized. If the object is destroyed and then instantiated, the PINpad must be reinitialized. PccPinPad Properties
Property Name Data Type Description - PccPinPad Properties

AccType

The customers bank account type used when processing the transaction. 1 or ENUM_ACC_CHEQ - Chequing 2 or ENUM_ACC_SAV Savings Note: When populating this property to build the initial Interac request string, the customers bank account type will not be known by the merchant (the customer will enter it once prompted). This value must be hard-coded. It is suggested to hard-code this value to 1 if most of the merchants customers GPSAccTyp use their checking accounts when purchasing products or 2 if most of the e merchants customers use their saving account when purchasing products. Note: A new MAC value must be requested from the PINpad if the account chosen by the merchant differs from the account chosen by the customer. Set this property to the account chosen by the customer, call the BuildInteracRequest method again and use the RequestMAC method in the PinSC5000 class to request a new MAC value from the PINpad. Set this property to the type of transaction being processed. This should be set to the same transaction type specified in the TransNameID property. 0 Purchase (default) 4 Refund Indicates whether all data has been received Amount of transaction. This amount displayed to customer on the PINpad for approval N/A Baud rate Example: 1200 Debit card number N/A Databits Example: "7" N/A The type of PINpad to be used. Types of PINpads are listed below. Example: 1 N/A Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. This is the Gratuity Amount of the transaction returned by the PINpad. The default message for the PINpad that is connected to the machine that PccPinPad will be communicating with. For example, if this is set to "Welcome", "Welcome" will appear on the screen at times of inactivity. N/A

Action

String

AllDataReceived Amount** Argements Baud* Card** Command DataBits* DataWaiting Device* ExpDate Gratuity

Variant String String Variant String String String Variant Variant String String

IdleMessage IncomingData KeyManagement* KeySerialNumber

String String

PinPadMana Type of encryption method to be used. gement String The Key Serial Number of the transaction

297

Property Name

Data Type

Description - PccPinPad Properties

LangCode

Language Code used when communicating with and displaying messages on the PINpad. Verifone SC5000 only GPSLangCo Valid Values: de 0 English (default) 1 French Variant String Integer String Byte String String String Variant String String Long N/A MAC data from the PINpad. Verifone SC5000 only. The Master Key for Master Session encryption. Not all processors who do Master Session encryption will have a Master Key. Set MasterKey to "0" if no Master Key is present. Name of cardholder This value must be set to 1 in order to communicate with the PINpad properly Parity setting for PINpad. ("E" for even, "O" for odd, "N" for none) The encrypted PIN entered by user. Number of the COM port to be used (Example: "1" used for COM port 1) Indicates whether device is in process of receiving data Response from processor Chip Serial Number from the PINpad. N/A

LastChar MACData MasterKey member OLEPinState Parity* Pin Port* ReceivingData Response SerialNumber StartTime State

PinPadSta States of PINpads are listed below te String Set this property to the Chip Serial Number of the PINpad. Use the GetSerialBlock method in the PinSC5000 class to acquire the Chip Serial Number of the PINpad. Verifone SC5000 only. Length of time after a request for PIN before PCCharge times out. It is highly recommended that integrators review the section Timeouts (see page 47). Note: The TimeOut properly is only applicable when programming in an asynchronous manner. Determines if the PINpad will prompt the customer to enter a tip amount and also determines if the PINpad will display a suggested tip amount prior to prompting for the tip amount. Valid Values: 0 The customer is not prompted to enter a tip amount (Default) 1 The customer is prompted to enter a tip amount. 2 through 99 The PINpad will calculate a suggested tip amount and display it on the PINpad prior to prompting the customer for the tip amount. The integer value passed in represents the percentage that will be used to calculate the tip. For example, 20 would calculate a 20% tip amount. The customer would see this suggested tip amount and would then be prompted to key in the actual tip amount. Raw swiped track data from card Property for future use

TermID

TimeOut

Long

TipType

Integer

TrackData WorkingKey

String String

* These properties must be set before Initialize can be called. ** These properties must be set before GetPin can be called.

PccPinPad Methods
Method Name AtallaAsciiString AtallaComm AtallaIO Cancel ClearData ClearPort Returned Value String Boolean Boolean Boolean Boolean Boolean Description - PccPinPad Methods No longer supported No longer supported No longer supported Returns TRUE if transaction was canceled Clears all data from device Clears PINpad buffer

298

Method Name ClosePort CreatPinPadFile

Returned Value Boolean None Boolean Boolean None Boolean Boolean Boolean Boolean None

Description - PccPinPad Methods Releases COM port to which PINpad is connected Used internally The GetPin method initiates the PIN entry prompt on the PINpad. If successful, TRUE will be returned. Once TRUE is returned, the PIN will be returned in the .Pin property and the Key Serial Number will be returned in the .KeySerialNumber property. Initializes PINpad N/A Perform MAC with the PINpad Captures COM port to which PINpad is connected Parse swipe data N/A Not used. Use GetPin to retrieve PIN from PINpad

GetPin

Initialize LoadKey MAC OpenPort ParseData ReceiveData Send

The following is a list of available PINpad types supported. PinPadDevice Properties

Property Name Data Type Description - PinPadDevice Properties Value = 10 Value = 5 Value = 7 Value = 6 Value = 3 Value = 0 Value = 8 Value = 1 Value = 2 Value = 4 Value = 9 Value = 12

ppdIVI_CheckMate_eNTouch100 Enum 0 ppdIVICheckmate_2100 ppdIVIeNCrypt_BMON ppdIVIPOSPad ppdIVISentinel PPDNone ppdPenWare_3100 ppdVerifone_101 PPDVerifone_2000 ppdVerifone_Everest ppdVerifone_SC500_C ppdVerifone_3730 Enum Enum Enum Enum Enum Enum Enum Enum Enum Enum Enum

The following is a list of all available PINpad states. PinPadState Properties

Property Name PPSCancel PPSIdle PPSProcess Data Type Enum Enum Enum Description - PinPadState Properties Value = 2 Value = 0 Value = 1

299

PccSC550 Class
PccSC550 Class Properties
Property Name Data Type Description - PccSC550 Class Properties

AccType

The customers bank account type used when processing the transaction. 1 or ENUM_ACC_CHEQ - Chequing 2 or ENUM_ACC_SAV Savings Note: When populating this property to build the initial Interac request string, the customers bank account type will not be known by the merchant (the customer will enter it once prompted). This value must be hard-coded. It is GPSAccTyp suggested to hard-code this value to 1 if most of the merchants customers e use their checking accounts when purchasing products or 2 if most of the merchants customers use their saving account when purchasing products. Note: A new MAC value must be requested from the PINpad if the account chosen by the merchant differs from the account chosen by the customer. Use the RequireReMac property in the PinSC5000 class to determine if ReMACing must occur.

Action Amount

String String Variant

Used internally Set this property to the Amount of the transaction to be processed. This property should not contain any decimals or commas. Example: to specify a $1.00 transaction, set this property to 100 Baud Rate used to communicate with the PINpad. Default Value: 9600 This property will contain the Chip Serial Number of the PINpad. This field is populated by running the GetChipSerialNum method. The Chip Serial Number is passed as a parameter to the Debit classes GetPOSSequenceNumber method. DataBits used to communicate with the PINpad. Default Value: 8 Set this property to the amount of the transaction. The amount specified is displayed to the customer for confirmation on the PINpad. This amount should include the decimal point and trailing zeros, if applicable. Example: to specify a $1.00 transaction, set this property to 1.00

Baud

ChipSerialNum

String

DataBits

Variant

DisplayAmount

String

LanguageCode

Language Code used when communicating with and displaying messages on the PINpad. GPSLangCo Valid Values: de 0 English (default) 1 French String After the ParseResponseData method has been called, this property will contain the MAC block information that was returned from the PINpad. Parity used to communicate with the PINpad. Valid Values: E even O odd N None (default) After the ParseResponseData method has been called, this property will contain the customers encrypted PIN that was returned from the PINpad. Port Number to be used to communicate with PINpad. Default Value: COM1 Used internally The POS Sequence number. Set this property to the value that was returned by PCCharge when calling the GetPOSSequenceNumber method in the Debit.OCX control. Set this property to the Chip Serial Number of the PINpad. Use the GetSerialBlock method in the PinSC550 class to acquire the Chip Serial Number of the PINpad.

MACBlock

Parity

Variant

PINBlock Port SC550Form SequenceNum

String String Object String

TermID

String

300

Property Name TipAmount

Data Type String

Description - PccSC550 Class Properties After the ParseResponseData method has been called, this property will contain the optional customer-specified tip amount. If this property is populated with a value greater than 0, a ReMAC must occur. Determines if the PINpad will prompt the customer to enter a tip amount and also determines if the PINpad will display a suggested tip amount prior to prompting for the tip amount. Valid Values: 0 The customer is not prompted to enter a tip amount (Default) 1 The customer is prompted to enter a tip amount. 2 through 99 The PINpad will calculate a suggested tip amount and display it on the PINpad prior to prompting the customer for the tip amount. The integer value passed in represents the percentage that will be used to calculate the tip. For example, 20 would calculate a 20% tip amount. The customer would see this suggested tip amount and would then be prompted to key in the actual tip amount. Set this property to the track II data from the magnetic stripe of the card. For example: ;1234123412341234=08121234123412340001?

TipType

Integer

TrackII

String

TransCode

Set this property to the type of transaction being processed. This should be set GPSTransC to the same transaction type specified in the TransNameID property. ode 0 or ENUM_TCODE_PURCH_NORM Purchase (default) 4 or ENUM_TCODE_REFUND Refund Set this property to the type of transaction being processed. The property indicates to the PINpad to displays the type of transaction being processed to the customer. This should be set to the same transaction type specified in the GPSTransID TransCode property. Valid Values: 0 or ENUM_TID_PURCH Displays PURCHASE (default) 1 or ENUM_TID_REFUND Displays REFUND

TransNameID

These properties must be set prior to calling the BuildInteracRequest method. These properties will be set after the ParseResponseData method completes successfully.

PccSC550 Class Methods

Property Name BuildInteracReqString Returned Value String Boolean Boolean Description - PccSC550 Class Methods Builds and returns the Interac request string that will be sent to the PINpad. The properties in the SC550.clsInteracReq Class Properties table that are marked with a must be set prior to calling this method. Obtains the Chip Serial Number from the PINpad. This method populates the ChipSerialNum property with the PINpads Chip Serial Number. Gets the PIN from the PINpad. This will prompt the user to enter his/her PIN. GetPin will then return the encrypted PIN. GetPin will return nothing if a timeout or cancel occurs. Initializes the PINpad. 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. Requests a key change from the PINpad.

GetChipSerialNum

GetPin

Initialize KeyChangeRequest

Boolean None

301

PccBin Class
This functions in this class will return information that indicates if a credit card is a Commercial Card, and what type of Commercial Card it is. See the section Commercial Card Transactions (see page 65) for more information. This is a Multi Use class. PccBin Properties
Property Name Canceled Data Type Boolean Description - PccBin Properties Used internally To test if the card is a Level II card (Business, Purchase, Corporate, or Fleet), pass the card number to this function. The function will return TRUE if the cards BIN range appears in the Bin.mdb database that resides in the PCCharge directory. FALSE will be returned if it doesnt. If TRUE is returned, check CommercialCardType to determine what type of Level II card it is. This property indicates the card type. After calling the CommercialCard function, the CommercialCardType property will be populated with one of the following values: B - Business P,L,G - Purchase C - Corporate F - Fleet N - not a Level II card If processing a commercial card, the CmrclCardFlag property in the PccCharge class should be populated with this value prior to submitting the transaction. Index MC Other VS Integer Collection Collection Collection No longer supported No longer supported No longer supported No longer supported

CommercialCard

Boolean

CommercialCardType

String

PccBin Methods
Method Name Load Save Show Returned Value Boolean Boolean Boolean Description - PccBin Methods No longer supported No longer supported No longer supported

302

Reporting
The PccCharge class may be used by integrators to submit report requests. A report request can have PCCharge print a report to its default report printer or have PCCharge generate a file containing the report output. If generating a file, the PCCharge reporting interface supports three different file types: 1. Portable Document Format (.pdf) 2. Rich Text Files (.rtf) 3. Standard Text files (.txt) Note: The reporting interface cannot be configured to send reports directly to the screen. The following outlines the properties used for submitting report requests to PCCharge with the PccCharge class. The properties in PccCharge that are not documented below should be left blank when submitting report requests.
Property Data Type Long Description - PccCharge Class Reporting Properties The action code that identifies what type of report will be requested. Valid Values: 81-84. Example: If running a credit card detail report, set the action code to 81. Consult the section DevKit Constants for a list of valid values (see page 94). User name filter. If a valid user name is set in the Card property, the report will be filtered by that user name. The report returned will consist of only those transactions processed by the user name specified. Example: "User1". If this property is left blank, the report will show transactions processed by all users. Result filter. Use this filter to create a report consisting of only those transactions with the result specified. Valid Values: 0 = all (default), 1 = approved, 2 = declined Example: 1 Ending Date/Time filter. Specifies the end date and end time of the report. Format: Date: MM/DD/YY Time: HH:MM:SS PM. When used in conjunction with Street; will create a report consisting of only those transactions processed between the start and end date/time specified (inclusive). If an end date is not specified, today's date is assumed. If an end time is not specified, 11:59:59 PM is assumed. The end date can be passed without the end time. However, the end time cannot be passed without the end date. Examples: "07/06/05 06:00:00 PM" or 07/06/05 Merchant Number filter. Set this property to filter the report by the merchant number specified. Setting this property will generate a report consisting of only those transactions processed via the merchant number specified. To generate a report that includes all merchant numbers in PCCharge, set this property to "ALL or leave blank. Example: "99999999911" The path to the directory in which the PCCharge executable resides. This property must be set prior to calling the Send, PccSysExists, and other methods that require accessing the PCCharge directory. Path String Example: C:\Program Files\PCCW\ or C:\Program Files\Active-Charge\ Path Formats: UNC, MS-DOS(8 Characters) and Long. 100 characters maximum. Must end with a "\". String Report Output setting. Determines if the report will be printed by PCCharge or written to a file. Valid Values: "0" = print to default printer specified in PCCharge (default). "1" = print to file using filename specified in TransID and path specified in TRACK.

Action

Card

String

Manual

Long

member

String

MerchantNumber

String

PeriodicPayment

303

Property

Data Type

Description - PccCharge Class Reporting Properties Starting Date/Time Filter (Optional) Specifies the start date and start time of the report. Format: Date: MM/DD/YY Time: HH:MM:SS PM. Use to create a report consisting of only those transactions processed on or after the date specified. If a start date is not specified, today's date is assumed. If a start time is not specified, 12:00:00 AM is assumed. The start date can be passed without the start time. However, the start time cannot be passed without the start date. Examples: "03/04/05 09:00:00 AM" or 03/04/05 The number of seconds after which a timeout error will be returned from PCCharge. The count will start when the Send method is called. It is highly recommended that integrators review the section Timeouts (see page 47). Note: The TimeOut properly is only applicable when programming in an asynchronous manner. Destination Directory for Report File. Specifies the destination directory where the report file will be generated by PCCharge (if PeriodicPayment is set to "1"). Example: C:\My Documents\PCCReports\ Path Formats: UNC, MS-DOS(8 Characters) and Long. Max Length: 40 characters (if the Destination Directory is longer than 40 characters, use CustCode for the additional characters. Must end with a "\" unless the directory name will be continued in the CustCode property. Note: If running in a Client/Server environment, this property is the path from the server running PCCharge, not the client. For example, if a client submitted a report request that specified C:\ as the destination directory, the report would be written to the local hard drive of the server running PCCharge, not to the clients hard drive.

Street

String

TimeOut

Long

Track

String

CustCode

String

Destination Directory for Report File (continued). Continuation of the destination directory (if the directory name is greater than 40 characters). Max Length: 25 characters. Must end with a "\" Report File name/Report File Type. Specifies the filename and extension of the report file generated by PCCharge (if PeriodicPayment is set to "1"). Also determines what file type will be used when PCCharge generates the report. To specify the file type, set the extension to one of the following: .pdf Create the report file in the Portable Document Format. Ex. Report.pdf .rtf Create the report file in Rich Text. Ex. Report.rtf .txt Create a report file in flat text. Ex. Report.txt Default: .txt (If an extension other than the ones listed is passed, the report will be returned as flat text and a .txt extension will be added to the filename) 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 more information on user names, consult the Multi-User Support section (see page 50).

TRANSID

String

User

String

These properties are required to submit a report request.

The following outlines the methods used to process report requests. The methods in PccCharge that are not documented below will not be used when processing report requests.
Method Returned Value None Description - PccCharge Class Reporting Methods 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.

Cancel

304

Method

Returned Value

Description - PccCharge Class Reporting Methods The DeleteUserFiles method attempts to delete all request and response files associated with the transaction. It will delete the files based on the value set in the User property. The DeleteUserFiles method should be called after the results have been retrieved from the transaction. If an error occurs while attempting to delete the files, the Error event will be triggered (if asynchronous) and the GetErrorDesc method will give a brief description of the error. Consult the section System Error Codes and Descriptions for a list of valid error codes and descriptions that will be returned (see page 99). 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. 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. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The GetErrorDesc method returns a string representation of the error that was encountered during the use of the various methods. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. The PccSysExists method is used to determine if PCCharge is available to process transactions. If PccSysExists returns TRUE, the file SYS.PCC exists in the PCCharge directory and PCCharge is not available to process transactions. TRUE usually indicates that PCCharge is either not running, is performing a batch or database function, or is in an error state. The GetErrorCode and GetErrorDesc methods will provide information as to why the file exists. Consult the section System Error Codes and Descriptions for a list of valid error codes that will be returned (see page 99). If PccSysExists returns FALSE, then PCCharge is ready to process transactions.

DeleteUserFiles

None

GetAuth

String

GetErrorCode

Long

GetErrorDesc

String

GetResult

String

PccSysExists

Boolean

305

Method

Returned Value

Description - PccCharge Class Reporting Methods The Send method creates a text file containing the transaction request and places the file in the PCCharge directory. The Send method will check the action code specified and perform the transaction type indicated. If an error occurs while Send executes, the class will set the error code and description, raise the Error event, and terminate processing. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Send method has two optional parameters. The first parameter indicates whether the Send method will process transactions synchronously or asynchronously. Note: The object must defined to use events in order to allow asynchronous communication. Valid Values: True process asynchronously (Default) False process synchronously

Send

Integer

The second parameter indicates what message format will be used for the request and response files. This parameter may be specified by using a numerical value (or an enumerated value if the programming language being used supports enumerated values). IMPORTANT NOTE: It is highly recommended that the XML message format parameter is set when calling the Send method. All DevKit documentation assumes that the XML message format parameter has been set. (The legacy INP message format is selected by default for backwards compatibility reasons.) Valid values: 3 (TTYPE_XML) XML message format (RECOMMENDED) Example: Send True, 3 Note: The other values that appear in the enumerated list are for internal use only-- do not attempt to use any values other than the ones listed above. The VerifyMerchantNumber method returns TRUE if the merchant number that is passed to it is set up in PCCharge, otherwise, FALSE is returned. Specifically, this method checks for the merchant number in the file TID.PCC, which is located in the PCCharge directory. The Path property must be set before calling this Method.

VerifyMerchantNumber

Boolean

PccCharge Events
Event Error Description - PccCharge Class Events The Error event is fired any time an error occurs in the class. Once an Error event has fired, call GetErrorCode and GetErrorDesc to determine what kind of error has occurred. Consult the section System Error Codes and Descriptions for a list of valid errors that will be returned (see page 99). The Finish event will fire when the transaction has been completed. This means that PCCharge has processed the transaction successfully and has placed a file with the extension of .oux in the PCCharge directory. The name of the .oux file will be what was set in the User property of the transaction request. Call the GetResult method to determine whether or not the transaction was approved. A list of valid results can be found in the DevKit Constants section (see page 94).

Finish

Note: When doing asynchronous transactions in an event-driven programming model, it is important to place all result or error routines in either the Finish or Error events. Do not place any code that uses the .get methods after invoking the Send method.

306

Utility Related Classes

OS
The OS object contains information about the operating system on the local machine. This is a Multi Use class. OS Properties
Property Name BuildNumber CSDVersion MajorVersion MinorVersion OSVersion Platform PlatformID Version Win2000 Win2003 Win95 Win98 WinME WinNT WinXP Data Type Long String Long Long EOS_VERSION String Long String Boolean Boolean Boolean Boolean Boolean Boolean Boolean Description - OS Properties Returns the build number of the operating system on the machine that PCCharge is installed Returns the CSD Version (Service Pack level) of the operating system on the on machine that PCCharge is installed Returns the Major version of the operating system on the machine that PCCharge is installed Returns the Minor version of the operating system on the machine that PCCharge is installed Returns the version of the operating system on the machine that PCCharge is installed Returns the Platform of the operating system on the machine that PCCharge is installed Returns the Platform ID of the operating system on the machine that PCCharge is installed Returns the full version information of the operating system on the machine that PCCharge is installed Indicates whether operating system of the local machine is Windows 2000. Indicates whether operating system of the local machine is Windows 2003. Indicates whether operating system of the local machine is Windows 95. Indicates whether operating system of the local machine is Windows 98. Indicates whether operating system of the local machine is Windows ME or was derived from Windows ME Indicates whether operating system of the local machine is Windows NT or was derived from Windows NT (Example: Windows 2000) Indicates whether operating system of the local machine is Windows XP or was derived from Windows XP

307

PccActiveCharge
This class contains information about the current instance of PCCharge. This is a Multi Use class.

PccActiveCharge Properties
Property Name Check CompanyName Credit CSZ Debit EBT EmailHelp Fax GiftCard HndUI License PccModem PccUtilities Phone ProgramName ShowAcUI Street Version Web Data Type Collection Variant Collection Variant Collection Collection Variant Variant Collection Long Variant PccModem PccUtilities Variant Variant Boolean Variant String Variant Description - PccActiveCharge Properties Contains merchant check processing information Merchant company information Contains merchant credit card processing information This value is read-only Contains merchant debit processing information Contains merchant EBT processing information Private label information specified in sys.cfg Private label information specified in sys.cfg Contains merchant gift card processing information This value is read-only. Contains the handle for the main UI window. If null, the UI is not loaded. In that case, set ShowAcUI to "1", then re-read HndUI. Private label information specified in sys.cfg Merchant modem information Database Utilities Private label information specified in sys.cfg Private label information specified in sys.cfg This value is write-only. If set to "1", the PCCharge COM form becomes visible. Private label information specified in sys.cfg Private label information specified in sys.cfg Private label information specified in sys.cfg

PccActiveCharge Methods
Method Name GetActiveIndex GetIndex GetMaxMerchants ReInitialize ShutDown StartUp** Returned Value Integer Integer Integer Boolean Boolean Boolean Description - PccActiveCharge Methods Returns index of active TID Returns index of specified arguments Returns number of TIDs in PCCharge Re-initializes PCCharge without shutting the program down. Shuts down current instance of PCCharge Starts up and initializes application

** Be sure to use this method to ensure that all variables and data structures are properly initialized.

308

PccDBBackup
The PccDBBackup object allows access to PCCharge's transaction archive capabilities. This feature is briefly described below, however, a detailed explanation of this feature can be found in the PCCharge Pro or Payment Server User Manuals. PCCharge offers transaction archive capabilities via integration. Archived transactions are moved from PCCharge's working database (pccw.mdb) into the archive database (pccwhist.mdb). The following archive integration methods are supported: OCX Method OLE/COM Method File Method TCP Method

The action code ZA specifies a transaction archive request. Consult the section DevKit Constants for descriptions of values (see page 94), and consult the section File Method for descriptions of transaction fields (see page 409). This is a Multi Use class.

PccDBBackup Properties
Property Name ArchivePre5_6 Cancel Data Type Boolean Boolean Description - PccDBBackup Properties Flag to indicate whether pre-PCCharge version 5.6 transactions should be archived. TRUE Archive Pre 5.6 Transactions FALSE Do not archive Pre 5.6 Transactions Set to TRUE to cancel the archive operation in progress. Enable or disable current configuration Valid values: 1 Enable 0 Disable Transaction archive preservation range. All transactions within the past number of keep days will remain in the pccw.mdb database following a transaction archive command. Specify path for saved output files (Example: backed up transaction database). Must end with a backslash \. Transaction archive size limit for GUI archive prompting and validation. Specified in megabytes.

Enabled

Boolean

KeepDays

Integer String Long

Path SizeLimit

PccDBBackup Methods
Method Name Backup(GUIPrompt) LimitExceeded Load PCCWDatabaseSize Save Returned Value Description - PccDBBackup Methods Boolean Boolean Boolean Long Boolean Perform transaction archive. Returns TRUE if successful, FALSE otherwise. Set GUIPrompt to FALSE during a transaction archive request to suppress a GUI error message if the request fails. Transaction database exceeds the configured archive limit. Load the saved archive configuration. Returns TRUE if successful, FALSE otherwise. Current transaction database size in bytes. Save the current archive configuration. Returns TRUE if successful, FALSE otherwise.

309

PccUtilities
Provides various PCCharge utilities to the integrator. PccUtilitiesMethods
Method Name BackUp Returned Value Description - PccUtilities Methods Boolean Boolean Boolean Boolean Backs up the merchant configuration files and PCCharge database to a ZIP file. Requires the path to the PCCharge directory as a parameter. Compacts the database and the settlement file. An optional parameter, the index of the merchant number, can be passed in. If this value is passed, the compact function will only compact the transactions related to that index. Calls the database engine repair function. Repairs the PCCharge database. Restores the merchant configuration files and PCCharge database into the PCCharge directory. Requires the path to the directory that contains the ZIP file as a parameter

Compact Repair Restore

310

Setup Related Classes

PccAddv
This class contains address verification system settings for the current instance of PCCharge. This is a Multi Use class. PccAddv Properties
Property Name Add5Zip Add9Zip AddNoZip Canceled Data Type Boolean Boolean Boolean Boolean Description - PccAddv Properties Indicates whether to capture transaction when address and 5-digit zip code match. Indicates whether to capture transaction when address and 9-digit zip code match. Indicates whether to capture transaction when address matches but zip code does not. Used internally The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Indicates whether to capture transaction when 5-digit zip code matches but address does not. Indicates whether to capture transaction when 9-digit zip code matches but address does not. Indicates whether to capture transaction when address and zip code do not match. Indicates whether to capture transaction when address information is not available. Indicates whether to retry address verification when processor used by system is down. Indicates whether system used to verify the address is available.

Index

Integer

NoAdd5Zip NoAdd9Zip NoMatch NotAvailable Retry ServiceNotAvailable

Boolean Boolean Boolean Boolean Boolean Boolean

PccAddv Methods
Method Name CreateAddressFile Returned Value None Description - PccAddv Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Indicates whether AVS setup form is visible Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save ShouldShow

Boolean Boolean

Show

Boolean

311

PccADSISetup
This class contains Alliance Data Systems extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccADSISetup Properties
Property Name BatchNumber BType Canceled CompanyID CompanyIdentifier DebitReturnAmount DebitReturnCount DebitSalesAmount DebitSalesCount DebitVoidAmount DebitVoidCount Data Type String Integer Boolean String String String String String String String String Description - PccADSISetup Properties The Current batch number. This value is incremented by the processor after each successful settlement. N/A Used internally The company ID assigned by the merchants bank or processor A unique company identifier assigned to each merchant by Alliance Data Systems. Amount of Debit and EBT Returns Count of Debit and EBT Returns Amount of Debit and EBT Sales Count of Debit and EBT Sales Amount of Debit and EBT Voids Count of Debit And EBT Voids The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Amount of MC Sales Count of MC Sales Flag that indicates if the merchant will accept Private Label Cards. Amount of Private Label Sales Count of Private Label Sales Amount of credit purchase Count of credit purchases or post authorizations Amount of credit Returns Count of credit Returns Unique sequence number that is assigned to each transaction. Also called a reference number. Amount of Visa Sales Count of Visa Sales Amount of credit Voids Count of credit Voids Amount of Credit Void Returns Count of credit Void Returns

Index

Integer

MCSalesAmount MCSalesCount PLabel PLabelSalesAmount PLabelSalesCount PurchasedAmount PurchasedCount ReturnedAmount ReturnedCount SequenceNumber VisaSalesAmount VisaSalesCount VoidedAmount VoidedCount VoidReturnAmount VoidReturnCount

String String Boolean String String String String String String String String String String String String String

312

PccADSISetup Methods
Method Name CreateADSIExtFile Returned Value None Description - PccADSISetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

313

PccAmexDialSetup
This class contains Amex split-dial settings for the current instance of PCCharge. This is a Multi Use class.

PccAmexDialSetup Properties
Property Name AMEXDirect BType Canceled ExpansionFactor Data Type Boolean String Boolean String Description - PccAmexDialSetup Properties Indicates whether split dial will be used The merchants business type. Valid values: 0 Retail / MOTO 4 Restaurant Used internally Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The American Express-assigned Service Establishment (SE) Number. Length: 10 bytes The Primary number that will be used when processing transactions via dial-up modem. Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required The Secondary number that will be used when processing transactions via dial-up modem. The American Express-assigned Terminal ID. Length: 2 bytes

Index

Integer

MerchantNumber PrimaryPhone

String String

RequireServerID

String

SecondaryPhone TerminalID

String String

PccAmexDialSetup Methods
Method Name CreateAmexspltFile Returned Value None Description - PccAmexDialSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

314

PccAmexSettleSetup
This class contains Amex Settlement settings for the current instance of PCCharge. This is a Multi Use class.

PccAmexSettleSetup Properties
Property Name AmexSettle BatchNumber BType Canceled CurrencyCode Data Type Boolean Integer Byte Boolean String Description - PccAmexSettleSetup Properties Used internally Used internally Used internally Used internally The Currency Code assigned by the merchants bank or processor. This parameter is used to identify the merchants settlement currency. Length: 3 digits. Valid Value: 840 U.S. Dollars General Description of what type of transactions will be processed by this merchant. This value should be determined by the merchant and American Express. Length: 23 Characters. Example: MENS WEAR, HARDWARE, ACCESSORIES The File Sequence Number is the PCID-specific, unique sequence number for a file. That means that if you deliver transactions to American Express for more than one PCID, each PCIDs transactions are forwarded in a separate Financial Settlement File with its own file sequence numbering scheme. Note: A file sequence number must not be repeated during a calendar year. Length: 6 bytes. Example: 000001 The FTP port used when processing AMEX settlements. This value is provided by American Express. The FTP address used when processing AMEX settlements. This value is provided by American Express. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Invoice Batch Code assigned by American Express. This code specifies processing options applicable to the batch. The code to be entered in this field is supplied by American Express at the same time the Process Control ID (PCID) is assigned. Length: 3 bytes The Invoice Subcode assigned by American Express. This code specifies additional Amex controls and processing requirements. The code to be entered in this field is supplied by American Express at the same time the Process Control ID (PCID) and Invoice Batch code are assigned. Length: 2 bytes The password used to send settlements to American Express via FTP. This value is provided by American Express. The Process Control ID / Username assigned by American Express. This parameter is a unique identifier code assigned to merchants, locations, and Authorized Third Party Processors so that they can directly access the American Express Financial Settlement system to deliver settlement data. In some cases, a merchant may not receive a unique PCID, because many franchises and authorized processors submit files for multiple locations under one PCID. Length: 6 bytes Used internally Not Yet Implemented Used internally Used internally Used internally

DefaultDescriptor

String

FileSeqNumber

Integer

HostPort HostURL

String String

Index

String

InvoiceBatchCode

String

InvoiceSubcode

String

Password

String

PCID

String

RecSeqNumber RequestTimeout SettlementFileName TotalTransAmt TransCount

Integer String String Long Long

315

Property Name

Data Type

Description - PccAmexSettleSetup Properties The Process Control ID / Username assigned by American Express. This parameter is a unique identifier code assigned to merchants, locations, and Authorized Third Party Processors so that they can directly access the American Express Financial Settlement system to deliver settlement data. In some cases, a merchant may not receive a unique PCID, because many franchises and authorized processors submit files for multiple locations under one PCID. Length: 6 bytes

Username

String

PccAmexSettleSetup Methods
Method Name CreateArchiveDir Returned Value Boolean Description - PccAmexSettleSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

316

PccBPASSetup
This class contains Buypass extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccBPASSetup Properties
Property Name AppID Data Type String Description - PccBPASSetup Properties Used internally The merchants business type. Valid values: 0 = Retail 1 = Mail order 2 = Electronic commerce 3 = Restaurant Used internally Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP EFSnet XML 2 TCP/IP EFSnet Leased Line 3 TCP/IP EFSnet Pass Through The Currency Code assigned by the merchants bank or processor. This parameter is used to identify the merchants settlement currency. Length: 3 digits. Valid Value: 840 U.S. Dollars Device number assigned by the merchants bank or processor. Length: 3 digits. Example: 001. Device type assigned by the merchants bank or processor. Length: 2 characters. Example: 5S. Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. Used internally Indicates method of connection to processor when processing gift cards. Valid values: 0 Dial-up 1 TCP/IP EFSnet XML 2 TCP/IP EFSnet Leased Line 3 TCP/IP EFSnet Pass Through The Currency Code assigned by the merchants bank or processor. This parameter is used to identify the merchants settlement currency. Length: 3 digits. Valid Value: 840 U.S. Dollars Device number assigned by the merchants bank or processor. Length: 3 digits. Example: 001. Device type assigned by the merchants bank or processor. Length: 2 characters. Example: 5S. Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup The system/socket port used to connect to the processor when processing via TCP/IP. A unique sequence number assigned to each transaction by PCCharge. Length: 6 digits

BType

Integer

Canceled

Boolean

Connect

String

CurrencyCode

String String String

DeviceNumber DeviceType

DialBackup

Boolean

ExpansionFactor FSInquiry

String Boolean

GiftConnect

Integer

GiftCurrencyCode

String String String

GiftDeviceNumber GiftDeviceType

GiftDialBackup

Boolean

GiftPort GiftSequenceNumber

String String

317

Property Name GiftSettleTimeOut

Data Type String

Description - PccBPASSetup Properties The Internet Settlement Timeout Value. If GiftDialBackup is set to TRUE, GiftSettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The merchants State Code. Length: 2 digits Valid Values: Alabama 01; Alaska 02; Arizona 04; Arkansas 05; California 06; Colorado 08; Connecticut 09; Delaware 10; District of Columbia 11; Florida 12; Georgia 13; Puerto Rico 14; Hawaii 15; Idaho 16; Illinois 17; Indiana 18; Iowa 19; Kansas 20; Kentucky 21; Louisiana 22; Maine 23; Maryland 24; Massachusetts 25; Michigan 26; Minnesota 27; Mississippi 28; Missouri 29; Montana 30; Nebraska 31; Nevada 32; New Hampshire 33; New Jersey 34; New Mexico 35; New York 36; North Carolina 37; North Dakota 38; Ohio 39; Oklahoma 40; Oregon 41; Pennsylvania 42; Rhode Island 44; South Carolina 45; South Dakota 46; Tennessee 47; Texas 48; Utah 49; Vermont 50; Virginia 51; Virgin Islands 52; Washington 53; West Virginia 54; Wisconsin 55; Wyoming 56 EFSnet store number assigned by the merchants bank or processor. Length: 32 digits. EFSnet store password assigned by the merchants bank or processor. Length: 64 digits The Internet Authorization Timeout Value. If GiftDialBackup is set to TRUE, GiftTimeOut determines how long PCCharge will wait for a gift card transaction to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields The system/socket port used to connect to the processor when processing via TCP/IP. 0 Retry reversals the specified number of times set in the .RetryReversalCount property. 1 Retry reversals indefinitely The number of times a reversal is retried The amount of time (in seconds) between reversal retries The amount of time (in seconds) between reversal processing Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required A unique sequence number assigned to each transaction by PCCharge. Length: 6 digits Password required for settlement The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds

GiftStateCode

String

GiftStoreID GiftStoreKey

String String String String

GiftTimeOut

GiftURL

Index

Integer

PCard

Boolean

Port ReversalOption ReversalNumberRetry ReversalSeconds

String String String String

RetryReversalSeconds String

RequireServerID

String

SequenceNumber SettlePwd SettleTimeOut

String String String

318

Property Name

Data Type

Description - PccBPASSetup Properties The merchants State Code. Length: 2 digits Valid Values: Alabama 01; Alaska 02; Arizona 04; Arkansas 05; California 06; Colorado 08; Connecticut 09; Delaware 10; District of Columbia 11; Florida 12; Georgia 13; Puerto Rico 14; Hawaii 15; Idaho 16; Illinois 17; Indiana 18; Iowa 19; Kansas 20; Kentucky 21; Louisiana 22; Maine 23; Maryland 24; Massachusetts 25; Michigan 26; Minnesota 27; Mississippi 28; Missouri 29; Montana 30; Nebraska 31; Nevada 32; New Hampshire 33; New Jersey 34; New Mexico 35; New York 36; North Carolina 37; North Dakota 38; Ohio 39; Oklahoma 40; Oregon 41; Pennsylvania 42; Rhode Island 44; South Carolina 45; South Dakota 46; Tennessee 47; Texas 48; Utah 49; Vermont 50; Virginia 51; Virgin Islands 52; Washington 53; West Virginia 54; Wisconsin 55; Wyoming 56 EFSnet store number assigned by the merchants bank or processor. Length: 32 digits EFSnet store password assigned by the merchants bank or processor. Length: 64 digits. The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP.

StateCode

String

StoreID StoreKey

String String String String

TimeOut

URL

PccBPASSetup Methods
Method Name Returned Value Description - PccBPASSetup Methods Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced. Shows a GUI form that allows the end-user to enter extended or advanced Gift Card configuration information such as the business type, communication method, or other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowGC. Used internally

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

ShowGC

Boolean

SynchronizeSequenceN None um

319

PccBPSGiftSetup
This class contains Fifth-Third St. Pete gift card extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccBPSGiftSetup Properties
Property Name BankID BType Canceled Data Type String Integer Boolean String Boolean Integer Description - PccBPSGiftSetup Properties Acquiring Institution Identification Code assigned by the merchants bank or processor. Length: 4 digits Used internally Used internally Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP N/A Indicates method of connection to processor when processing gift cards. Valid values: 0 Dial-up 1 TCP/IP Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup The Password assigned by the merchants bank or processor for TCP/IP processing. The system/socket port used to connect to the processor when processing via TCP/IP. The Internet Settlement Timeout Value. If GiftDialBackup is set to TRUE, GiftSettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Internet Authorization Timeout Value. If GiftDialBackup is set to TRUE, GiftTimeOut determines how long PCCharge will wait for a gift card transaction to time out before attempting the transaction via dial Format: Seconds The number of times to retry a reversal The amount of time (in seconds) between reversal retries The amount of time (in seconds) between reversal processing The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Username assigned by the merchants bank or processor for TCP/IP processing. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. N/A Used internally N/A The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. Retrieval Reference Number. Used to identify and track the original transaction. This value is assigned by the merchants processor. Length: 8 digits N/A

Connect

DialBackup

GiftConnect

GiftDialBackup

Boolean

GiftPassword GiftPort

String String String

GiftSettleTimeOut

GiftTimeOut GiftReversalNumberRetry GiftReversalSeconds GiftURL GiftUsername

String String String String String

GiftRetryReversalSeconds String

Index

Integer

Password PCard Port PrimaryAuthIP Retrieval SettleTimeOut

String Boolean String String String String

320

Property Name TerminalID TimeOut URL Username

Data Type String Long String String

Description - PccBPSGiftSetup Properties Contains terminal ID for merchant N/A N/A N/A

PccBPSGiftSetup Methods
Method Name Returned Value Description - PccBPSGiftSetup Methods Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced.

Load

Boolean

Save

Boolean

Show

Integer

ShowAdvanced

Boolean

321

PccBPSSetup
This class contains Fifth-Third St. Pete extended information for the current instance of PCCharge. This is a Public Not Creatable class. PccBPSSetup Properties
Property Name BankID Data Type String Description - PccBPSSetup Properties Acquiring Institution Identification Code assigned by the merchants bank or processor. Length: 4 digits The merchants business type. Valid values: 0 Retail 1 Mail order 2 Electronic Commerce Used internally Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Password assigned by the merchants bank or processor for TCP/IP processing. Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields The system/socket port used to connect to the processor when processing via TCP/IP. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. Retrieval Reference Number. Used to identify and track the original transaction. This value is assigned by the merchants processor. Length: 8 digits The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds Card Acceptor Terminal ID code. This value identifies the terminal at the merchant (card acceptor) location at which the transaction was entered. Length: 3 digits The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Username assigned by the merchants bank or processor for TCP/IP processing.

BType

Integer

Canceled

Boolean Integer

Connect

DialBackup

Boolean

Index

Integer

Password

String

PCard

Boolean

Port PrimaryAuthIP Retrieval

String String String String String String String String

SettleTimeOut

TerminalID

TimeOut

URL Username

322

PccBPSSetup Methods
Method Name CreateBPSExtFile Returned Value None Description - PccBPSSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced.

Load

Boolean

Save

Boolean

Show

Integer

ShowAdvanced

Boolean

323

PccCESSetup
This class contains FDMS North/Cardnet extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccCESSetup Properties
Property Name Data Type Description - PccCESSetup Properties The merchants business type. Valid values: 0 Retail 1 Mail order 2 Electronic Commerce Used internally Indicates if merchant is set up for check services. Valid Values: 0 None 1 ETC 2 Equifax 3 NPC 4 TeleCheck Indicates method of connection to processor. Valid values: 0 Dial-Up 1 First Data IPN (Datawire TCP/IP) The Merchants customer service phone number. This number will be printed on the customers statement if PrintCSNumber is set to TRUE. Not applicable for Retail transactions. Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup The Datawire ID. The value is provided to the merchant by their Merchant Service Provider or Processing company. The DID is required to process transactions via the Internet using the Datawire network. This value will be unique for each merchant number used. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. Specifies the maximum number of transactions per batch that PCCharge will send to the processor. If the number of transactions to be settled is greater than the number specified in this setting, PCCharge will split the batch into multiple batches, each containing (at most) the number transactions specified in this setting. The batches are then sent to the processor one at a time. Example: A merchant has 250 transaction to settle and the MaxBatchSize is set to 100. PCCharge will send two 100-transaction batches and one 50-transaction batch. Max Value: 999 N/A Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields Flag that indicates whether to print customer service phone number on receipt. Not applicable for Retail transactions. Used internally

BType

String

Canceled

Boolean

CheckService

Integer

Connect

Integer

CSNumber

String

DialBackup

Boolean

DID

String

Index

Integer

IP

String

MaxBatchSize

String

MCReversal

Integer Boolean

PCard

PrintCSNumber RetryCount

Boolean Integer

324

Property Name SecondaryIP SendError SettleTimeOut

Data Type Boolean Boolean String

Description - PccCESSetup Properties Used internally Used internally The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Secondary Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. N/A

TimeOut

String String String String Boolean

URL URL2 URLAddress VSReversal

PccCESSetup Methods
Method Name CreateCESExtFile Returned Value None Description - PccCESSetup Methods Used internally Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced.

CreateCESAdvanceFile None

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

325

PccCheckSetup
This class contains information about the credit card company setup in the current instance of PCCharge. This is a Global Multi Use class. Note: The extended information for check processors that support conversion and guarantee can be accessed by using the PccCreditSetup class.

PccCheckSetup Properties
Property Name Canceled Company DemoMode Data Type Boolean Integer Boolean Description - PccCheckSetup Properties Used internally Used internally Used internally The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Primary number that will be used when processing transactions via dial-up modem. The code for the processing company. This value can be no more than four characters and must be capitalized. A list of valid processor codes are listed in the Processing Company Codes section (see page 101). Read-only property that Indicates how many merchant numbers have been set up in the current tid.pcc file. The Secondary number that will be used when processing transactions via dial-up modem. Indicates the type of check service that is supported. Valid Values: 0 MICR 1 Checks on Delivery 2 Drivers License 3 Double ID The check company Site ID / merchant number assigned by the merchants bank or processor. Used internally

Index

Integer

PrimaryPhone

String String Integer String

Processor

Records SecondaryPhone

Service

Integer

TID Version

String String

326

PccCheckSetup Methods
Method Name CreateCheckFile CreateChkExtFile Returned Value None None Description - PccCheckSetup Methods Used internally Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved.

Load

Boolean

Save

Boolean

Show

Boolean

327

PccCompany
This class contains information about the company name setup for the current instance of PCCharge and the associated active merchant number index. This is a Multi Use class.

PccCompany Properties
Property Name Canceled City Data Type Boolean String Description - PccCompany Properties Used internally The name of city in which merchants company is located. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. N/A The name of merchants company. The abbreviation of state in which merchants company is located. The street address of merchants company. The zip code of region in which merchants company is located.

Index

Integer

LogonScreen Name State Street Zip

Boolean String String String String

PccCompany Methods
Method Name CreateCompanyFile IsCompanyInfoValid Returned Value None Boolean Description - PccCompany Methods Used internally Performs a check that determines whether or not the Merchants company information has been properly entered. Returns TRUE if the company information is valid, FALSE otherwise. Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Load. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

328

PccConfig
This class contains information about the global preferences for the current instance of PCCharge. This is a Multi Use class.

PccConfig Properties
Property Name Data Type Description - PccConfig Properties Flag that indicates whether merchant accept all card types. Valid Values: 0 Do not accept all card types (specify individual card types using the other AcceptXXXX properties and the PrivateLabel property) 1 Accept all card types Flag that Indicates whether merchant will accept American Express cards. Valid Values: 0 Do not accept American Express cards 1 Accept American Express cards Flag that Indicates whether merchant will accept Carte Blanche cards. Valid Values: 0 Do not accept Carte Blanche cards 1 Accept Carte Blanche cards Flag that Indicates whether merchant will accept Diners Club cards. Valid Values: 0 Do not accept Diners Club cards 1 Accept Diners Club cards Flag that Indicates whether merchant will accept Discover cards. Valid Values: 0 Do not accept Discover cards 1 Accept Discover cards Flag that Indicates whether merchant will accept Enroute cards. Valid Values: 0 Do not accept Enroute cards 1 Accept Enroute cards Flag that Indicates whether merchant will accept Japanese Airlines (JAL) cards. Valid Values: 0 Do not accept Japanese Airlines (JAL) cards 1 Accept Japanese Airlines (JAL) cards Flag that Indicates whether merchant will accept JCB cards. Valid Values: 0 Do not accept JCB cards 1 Accept JCB cards Flag that Indicates whether merchant will accept MasterCard cards. Valid Values: 0 Do not accept MasterCard cards 1 Accept MasterCard cards Flag that Indicates whether merchant will accept Visa cards. Valid Values: 0 Do not accept Visa cards 1 Accept Visa cards Flag that indicates whether to prompt user to have PCCharge add customer to the customer database. Valid Values: TRUE Prompt FALSE Do not prompt Note: This setting only applies to transaction processing using the PCCharge GUI. Used internally Flag that indicates whether to prompt user to indicate whether the transaction is a bill payment.

AcceptAll

String

AcceptAMEX

String

AcceptCBLN

String

AcceptDCCB

String

AcceptDISC

String

AcceptENRT

String

AcceptJAL

String

AcceptJCB

String

AcceptMC

String

AcceptVISA

String

AddCustomer

Boolean

AddVerify BillPayPrompt

Boolean Boolean

329

Property Name

Data Type

Description - PccConfig Properties Flag available for credit card duplicate checking criteria. Enables or disables duplicate checking by user name. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: Off Valid Values: 0 Off 1 - On Flag available for credit card duplicate checking criteria. Enables or disables duplicate checking by merchant number. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: On Valid Values: 0 Off 1 - On Flag available for credit card duplicate checking criteria. Enables or disables duplicate checking by card number. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: On Valid Values: 0 Off 1 - On Flag available for credit card duplicate checking criteria. Enables or disables duplicate checking by expiration date. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: On Valid Values: 0 Off 1 - On Flag available for credit card duplicate checking criteria. Enables or disables duplicate checking by ticket number. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: Off Valid Values: 0 Off 1 - On Flag available for credit card duplicate checking criteria. Enables or disables duplicate checking by amount. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: On Valid Values: 0 Off 1 - On Used internally Flag that indicates whether to process a Post-Auth if the amount of the Post-Auth is greater than the amount of the corresponding Pre-Auth. Valid Values: 0 Do not enable the processing of Post-Auths with a greater amounts than their corresponding Pre-Auths. 1 Enable the processing Post-Auths with a greater amounts than their corresponding Pre-Auths. Note: Settling a transaction with an amount that is different (whether less than or greater than) than the original authorization amount can cause transactions to downgrade. Flag that indicates whether to notify the user when recurring billing contracts are due at startup. Valid Values: TRUE Notify user FALSE Do not notify user Note: This setting only applies to transaction processing using the PCCharge GUI.

CCUser

String

CCMerchant

String

CCCard

String

CCExpDate

String

CCTicket

String

CCAmount

String

Canceled

Boolean

chkAuthAmounts

String

ChkContracts

Boolean

330

Property Name

Data Type

Description - PccConfig Properties Flag that indicates whether PCCharge requires duplicate transactions to be forced. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Valid Values: TRUE Require duplicate transactions to be forced FALSE Do not require duplicate transactions to be forced Flag that Indicates whether to activate the TCP Interface for incoming transaction requests. Consult the TCP Interface section (see page 441) for more information on using the TCP/IP Interface. Valid Values: TRUE Activate TCP Interface FALSE (Default) Do not activate TCP Interface Flag that indicates whether to activate Magnetic Strip Verification. Valid Values: 0 Do not enable Magnetic Strip Verification 1 Enable Magnetic Strip Verification Note: This setting only applies to transactions performed using the PCCharge GUI. Flag that indicates whether to prompt user for CPS 2000 Qualifiers (ticket number and zip code). Valid Values: TRUE Prompt for CPS 2000 Qualifiers FALSE Do not prompt for CPS 2000 Qualifiers Note: This setting only applies to transaction processing using the PCCharge GUI. Flag available for debit card duplicate checking criteria. Enables or disables duplicate checking by user name. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: Off Valid Values: 0 Off 1 - On Flag available for debit card duplicate checking criteria. Enables or disables duplicate checking by merchant number. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: On Valid Values: 0 Off 1 - On Flag available for debit card duplicate checking criteria. Enables or disables duplicate checking by card number. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: On Valid Values: 0 Off 1 - On Flag available for debit card duplicate checking criteria. Enables or disables duplicate checking by expiration date. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: On Valid Values: 0 Off 1 - On Flag available for debit card duplicate checking criteria. Enables or disables duplicate checking by ticket number. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: Off Valid Values: 0 Off 1 - On

ChkDuplicates

Boolean

ChkIP

Boolean

ChkMSV

String

chkPrompt

Boolean

DCUser

String

DCMerchant

String

DCCard

String

DCExpDate

String

DCTicket

String

331

Property Name

Data Type

Description - PccConfig Properties Flag available for debit card duplicate checking criteria. Enables or disables duplicate checking by amount. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: On Valid Values: 0 Off 1 - On Flag available for duplicate checking criteria. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: 01 Use Default Processor Flag. This flag indicates whether to use the first merchant number set up in PCCharge if one is not specified in the transaction request. Consult the Multi-Merchant Support section (see page 56) for more information on the Use Default Processor option. Valid Values: TRUE Use the first merchant number. FALSE Do not use the first merchant number. Flag available for EBT card duplicate checking criteria. Enables or disables duplicate checking by user name. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: Off Valid Values: 0 Off 1 - On Flag available for EBT card duplicate checking criteria. Enables or disables duplicate checking by merchant number. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: On Valid Values: 0 Off 1 - On Flag available for EBT card duplicate checking criteria. Enables or disables duplicate checking by card number. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: On Valid Values: 0 Off 1 - On Flag available for EBT card duplicate checking criteria. Enables or disables duplicate checking by ticket number. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: Off Valid Values: 0 Off 1 - On Flag available for EBT card duplicate checking criteria. Enables or disables duplicate checking by amount. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: On Valid Values: 0 Off 1 - On Flag that indicates whether to enable client-side TCP/IP reversals. Client-side TCP/IP reversals are generated for some processors when the connection to the client is lost before PCCharge is able to return the transaction response to the client. Client-side reversals, when enabled, will help prevent double charges in cases where the client does not receive the response from the client as expected. Valid Values: TRUE Enable TCP/IP Client Reversals FALSE Disable TCP/IP Client Reversals Note: This option should be disabled if using a processor other than Buypass.

DCAmount

String

Days

String

DefaultTID

Boolean

EBUser

String

EBMerchant

String

EBCard

String

EBTicket

String

EBAmount

String

EnableTCPIPClientRev Boolean ersals

332

Property Name

Data Type

Description - PccConfig Properties Flag that indicates whether to return the Total Elapsed Time with the transaction response. Valid Values: 0 Do not return the Total Elapsed Time 1 Return the Total Elapsed Time Flag that indicates whether to return the Transaction Elapsed Time with the transaction response. Valid Values: 0 Do not return the Transaction Elapsed Time 1 Return the Transaction Elapsed Time N/A Transaction data is always encrypted based on CISP guidelines. Refer to the Important Security Notice (see page 8) for more information. Flag available for duplicate checking criteria. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: 00 N/A Transaction data is always encrypted based on CISP guidelines. Refer to the Important Security Notice (see page 8) for more information. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. N/A The last year that will be considered a valid expiration date. Currently, the default value is 09. Length: 2 digits. Format: YY Example: If LastValidDate is set to 05, then cards between 06 and 99 are considered to be 1906 to 1999, and cards between 00 and 05 are 2000 to 2005. Flag available for duplicate checking criteria. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: 00 Multi-trans wait flag. This flag indicates whether PCCharge should leave the modem connection open in anticipation of other transactions that will follow shortly. Note that PCCharge can only keep the connection open as long as is allowed by the processing company. Valid Values: 0 Do not leave the modem connection open after each transaction 1 Attempt to leave the modem connection open after each transaction See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line. The password for the system user ID. Setting a password activates cashier permissions (this feature is only available in the PCCharge GUI) Note: It is recommended that a password always be set when using PCCharge in a live environment. If the TCP Interface is activated (ChkIP = TRUE), this value is the TCP port that will be used for incoming transaction requests. Consult the TCP Interface section (see page 441) for more information on using the TCP/IP Interface. Default Value: 31419 Note: The default port of 31419 should be changed to maximize security when processing transactions in a live environment. N/A Flag that Indicates whether merchant will accept Private Label cards. Valid Values: TRUE Accept Private Label cards FALSE Do not accept Private Label cards N/A This setting determines how often PCCharge will poll its directory for incoming transaction requests (.inx and .inp files). The default value of 00.50 should not be changed unless the client machine is slow or there is network lag. Format: seconds.

EnableTotTime

String

EnableTransTime

String

Encrypt

Boolean

Hours

String

EncryptSettle

Boolean

Index

Integer

IPAddress

String String

LastValidYear

Minutes

String

MTimer

String

Pass

String

Port

Integer

PrivateKey

String Boolean Boolean String

PrivateLabel

ProxyServer

QTimer

333

Property Name ReAuthAttempts

Data Type String String

Description - PccConfig Properties Used internally Flag available for duplicate checking criteria. See the description of Duplicate Transactions in the Warnings, Tips, and Guidelines section (see page 43) for more information. Default Value: 00 Flag that indicates whether to mask credit card number on the Customer Database screen. Valid Values: TRUE Mask credit card numbers FALSE Do not mask credit card numbers Note: This setting only applies to transaction processing using the PCCharge GUI. N/A Used internally

Seconds

SecureCustomerDB

Boolean

UseProxyServer Version

Boolean String

334

PccConfig Methods
Method Name CreateConfigFile Returned Value None Description - PccConfig Methods Used internally The GetMerchantInfo method returns a string containing all of the merchant numbers and processors set up in PCCharge. The string will also indicate whether the processor is Host based (H), Terminal based (T), or a hybrid (Y). The string will begin with STX and will end with ETX. GS will separate each record, and FS will separate fields within a record. Example: <STX>CES <FS>000000927996296767<FS>T<GS>GSAR<FS> 999999999999519<FS>T<GS>VISA<FS>999999999911<FS>T<ETX> Refer to the section Multi-Merchant Support (see page 56) for more information on the GetMerchantInfo method. Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

GetMerchantInfo

String

Load

Boolean

Save

Boolean

Show

Boolean

335

PccCreditSetup
This class contains information about the credit card company setup in the current instance of PCCharge. This is a Multi Use class.

PccCreditSetup Properties
Property Name Canceled Company Default Data Type Boolean Integer Boolean Description - PccCreditSetup Properties Used internally Used internally Flag that indicates whether to use default phone numbers. If this value is set to TRUE, any changes to the values in PrimaryPhone and SecondaryPhone will not take effect. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. Note: This property cannot be modified using the Save method. Provides extended setup information for Alliance Data Systems, Inc.

Index

Integer

MerchantNumber PccADSISetup PccAmexDialSetup PccAmexSettleSetup PccASISetup PccBMONSetup PccBPASSetup PccBPSSetup PccCESSetup PccDiscDialSetup PccEchoSetup PccENCNSetup PccEZCKSetup PccFDCNSetup PccFDCSetup PccGsarSetup PccHPTSSetup PccIPGSSetup PccISDNSetup PccLYNKSetup PccMDISetup PccMPSSetup PccNBSetup PccNBSSetup PccNDCSetup PccNovaSetup PccNovusSetup PccNPCSetup PccRMRSSetup

String PccADSISetup

PccAmexDialSetu Provides extended setup information for American Express split dial p PccAmexSettleSe Provides extended setup information for American Express direct settlement tup PccASISetup PccBMONSetup PccBPASSetup PccBPSSetup PccCESSetup PccEchoSetup PccENCNSetup PccEZCKSetup PccFDCNSetup PccFDCSetup PccGsarSetup PccHPTSSetup PccIPGSSetup PccISDNSetup PccLYNKSetup PccMDISetup PccMPSSetup PccNBSetup PccNBSSetup PccNDCSetup PccNovaSetup PccNovusSetup PccNPCSetup PccRMRSSetup No longer Supported No longer Supported Provides extended setup information for BuyPass, Inc. Provides extended setup information for Fifth-Third Bank St. Pete Provides extended setup information for FDMS North / Cardnet Provides extended setup information for ECHO No longer Supported Provides extended setup information for Check Services powered by RMRS (Check Conversion settings) Provides extended setup information for FDMS Nashville / Envoy Provides extended setup information for FDMS Omaha / FDR Provides extended setup information for Chase Paymentech Provides extended setup information for Heartland Payment Systems No longer Supported No longer Supported Provides extended setup information for RBS Lynk, Inc. No longer Supported No longer Supported Provides extended setup information for FDMS South / NaBanco Provides extended setup information for National Bankcard Services Provides extended setup information for Global Payments-East Provides extended setup information for NOVA No longer Supported Provides extended setup information for National Processing Company Provides extended setup information for National Check Network (Check Conversion settings)

PccDiscDialSetup No longer Supported

336

Property Name PccSPSSetup PccTelmSetup PccTMHSetup PccVisaSetup PFlag PreFix PrimaryPhone

Data Type PccSPSSetup PccTelmSetup PccTMHSetup PccVisaSetup String String String

Description - PccCreditSetup Properties Provides extended setup information for Secure Payment Systems (Check Guarantee settings) No longer Supported No longer Supported Provides extended setup information for TSYS Used internally Used internally The Primary number that will be used when processing transactions via dial-up modem. The code for the processing company. This value can be no more than four characters and must be capitalized. A list of valid processor codes are listed in the Processing Company Codes section (see page 101). Note: This property cannot be modified using the Save method. The Secondary number that will be used when processing transactions via dial-up modem. Used internally

Processor

String

SecondaryPhone Version

String String

PccCreditSetup Methods
Method Name AddMerchantNumber AddNewTID CreateCreditFile GetIndex GetPCCVersion GetRecords Returned Value Boolean None None Integer String Integer Description - PccCreditSetup Methods Used internally Used internally Used internally Used internally Returns the version number of the PCCharge that is currently running. Returns how many merchant numbers have been set up in the current tid.pcc file. Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Used internally Used internally Used internally Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. The VerifyTID method returns TRUE if the processor code merchant number that is passed to it is set up in PCCharge, otherwise, FALSE is returned. Specifically, this method checks for the merchant number in the file TID.PCC, which is located in the PCCharge directory.

Load

Boolean

ProcessorSetup RemoveTID Save

Object None Boolean

RemoveMerchantNumber Boolean

Show

None

VerifyTID

Boolean

337

PccDebitSetup
Contains debit card company information about the current instance of PCCharge. This is a Multi Use class.

PccDebitSetup Properties
Property Name Canceled Company Default Data Type Boolean String Boolean Description - PccDebitSetup Properties Used internally Used internally Flag that indicates whether to use default phone numbers. If this value is set to TRUE, any changes to the values in PrimaryPhone and SecondaryPhone will not take effect. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Used internally Used internally The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. Max Length: 32 characters. This value can be alphanumeric. Provides extended setup information for Buypass Provides extended setup information for Heartland Payment Systems Provides extended setup information for RBS Lynk No longer Supported Provides extended setup information for FDMS South / NaBanco Provides extended seup information for National Bankcard Services Provides extended setup information for Global Payments - East Provides extended setup information for National Processing Company Provides extended setup information for TSYS The Primary number that will be used when processing transactions via dial-up modem. The code for the processing company. This value can be no more than four characters and must be capitalized. A list of valid processor codes are listed in the Processing Company Codes section (see page 101). The Secondary number that will be used when processing transactions via dial-up modem. Used internally The working key. Only applicable for Debit processors using Master Session encryption.

Index

Integer

KeyManagement MasterKey MerchantNumber PccBPASSetup PccHPTSSetup PccLYNKSetup PccMPSSetup PccNBSetup PccNBSSetup PccNDCSetup PccNPCSetup PccVisaSetup PrimaryPhone

Integer Integer String PccBPASSetup PccHPTSSetup PccLYNKSetup PccMPSSetup PccNBSetup PccNBSSetup PccNDCSetup PccNPCSetup PccVisaSetup String String String String String

Processor

SecondaryPhone SerialNumber WorkingKey

338

PccDebitSetup Methods
Method Name CreateDebitFile Returned Value None Description - PccDebitSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved.

Load

Boolean

Save

Boolean

Show

Boolean

339

PccDMRKSetup
This class contains Datamark extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccDMRKSetup Properties
Property Name BatchNumber BType Canceled Client Data Type String Integer Boolean String Integer Description - PccDMRKSetup Properties The Current batch number. This value is incremented by the processor after each successful settlement. The merchants business type. Valid values: Used internally Client Number assigned by the merchants bank or processor. Length: 4 digits Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup Used internally Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Retrieval Reference Number. Used to identify and track the original transaction. This value is assigned by the merchants processor. Length: 8 digits The Password assigned by the merchants bank or processor for TCP/IP processing. The system/socket port used to connect to the processor when processing via TCP/IP. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required This field is for identifying transactions within the batch. Assigned by PCCharge Length: 3 digits The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Service Industries Incentive Program indicator flag. Used to indicate recurring payments for service industries such as insurance, telecom and utilities. The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP.

Connect

DialBackup

Boolean Integer String

EDCType ExpansionFactor

Index

Integer

LastRRefNum Password Port PrimaryAuthIP PrimaryAuthPort

String String Long String String

RequireServerID

String

Sequence

String String Boolean String String

SettleTimeOut

SIIP

TimeOut

URL

340

Property Name Username

Data Type String

Description - PccDMRKSetup Properties The Username assigned by the merchants bank or processor for TCP/IP processing.

PccDMRKSetup Methods
Method Name Returned Value Description - PccDMRKSetup Methods Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced.

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

341

PccEBTSetup
This class contains information about the EBT company setup in the current instance of PCCharge. This is a Multi Use class.

PccEBTSetup Properties
Property Name Canceled Company Default Data Type Boolean String Boolean Description - PccEBTSetup Properties Used internally Used internally Flag that indicates whether to use default phone numbers. If this value is set to TRUE, any changes to the values in PrimaryPhone and SecondaryPhone will not take effect. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Used internally Used internally The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. Max Length: 32 characters. This value can be alphanumeric. Provides extended setup information for Buypass Provides extended setup information for National Processing Company Provides extended setup information for TSYS The Primary number that will be used when processing transactions via dial-up modem. The code for the processing company. This value can be no more than four characters and must be capitalized. A list of valid processor codes are listed in the Processing Company Codes section (see page 101). The Secondary number that will be used when processing transactions via dial-up modem. N/A

Index

Integer

KeyManagement MasterKey MerchantNumber PccBPASSetup PccNPCSetup PccVisaSetup PrimaryPhone

Integer Integer String PccBPASSetup PccNPCSetup PccVisaSetup String String String String

Processor

SecondaryPhone WorkingKey

PccEBTSetup Methods
Method Name CreateEBTFile Returned Value None Description - PccEBTSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

342

PccEchoSetup
This class contains ECHO extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccEchoSetup Properties
Property Name Data Type Description - PccEchoSetup Properties The merchants business type. Valid values: 0 Retail 1 Direct Marketing 4 Telemerchant 5 Electronic Commerce Used internally Indicates modem dial protocol. Valid values: 0 Compuserve 1 Dial 800 Number The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields

BType

Integer

Canceled

Boolean Integer

Connect

Index

Integer

PCard

Boolean

PccEchoSetup Methods
Method Name CreateECHOExtFile Returned Value None Description - PccEchoSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

343

PccEZCKSetup
This class contains Check Services powered by RMRS extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccEZCKSetup Properties
Property Name BounceFee Canceled ConnectType FTPAddress FTPPassword FTPUser Data Type String Boolean String String String String FTP address for check image upload. Password for access to image upload FTP User ID for access to image upload FTP The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Owner code for image upload FTP The current Sales Balance The current Sales Count Flag that indicates whether check truncation / conversion will occur. This is a unique identifier assigned by the merchants bank or processor that identifies the merchant. It will be in the format: site idlocation idrule set , where site id can be from 1 to 5 characters (numeric), location id can be from 1 to 6 characters (numeric), and rule set can be from 1 to 4 characters (numeric). Example: 78-123456-9999 (dashes are necessary; no spaces). The current Voids Balance The current Voids Count Description - PccEZCKSetup Properties The fee used in cases of returned checks due to insufficient funds. Format: Dollars Used internally

Index

Integer

OwnerCode SalesBalance SalesCount Truncation

String String String Boolean

TruncationTID

String

VoidsBalance VoidsCount

String String

PccEZCKSetup Methods
Method Name CreateEZCKExtFile Returned Value None Description - PccEZCKSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

344

PccFDCNSetup
This class contains FDMS Nashville / Envoy extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccFDCNSetup Properties
Property Name BatchNumber Data Type String Description - PccFDCNSetup Properties The Current batch number. This value is incremented by the processor after each successful settlement. The merchants business type. Valid values: 0 Retail 1 Mail order 2 Electronic commerce Used internally Indicates method of connection to processor. Valid values: 0 Dial-Up 1 First Data IPN (Datawire TCP/IP) Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup The Datawire ID. The value is provided to the merchant by their Merchant Service Provider or Processing company. The DID is required to process transactions via the Internet using the Datawire network. This value will be unique for each merchant number used. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. Specifies the maximum number of transactions per batch that PCCharge will send to the processor. If the number of transactions to be settled is greater than the number specified in this setting, PCCharge will split the batch into multiple batches, each containing (at most) the number transactions specified in this setting. The batches are then sent to the processor one at a time. Example: A merchant has 250 transaction to settle and the MaxBatchSize is set to 100. PCCharge will send two 100-transaction batches and one 50-transaction batch. Max Value: 999 Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields Used internally The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Secondary Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP.

BType

Integer

Canceled

Boolean Integer

Connect

DialBackup

Boolean

DID

String

Index

Integer

IP

String

MaxBatchSize

String

PCard

Boolean Boolean String

SecondaryIP SettleTimeOut

TimeOut

String String String

URL URL2

345

Property Name URLAddress

Data Type String

Description - PccFDCNSetup Properties The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP.

PccFDCNSetup Methods
Method Name Returned Value Description - PccFDCNSetup Methods Used internally Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced.

CreateFDCNAdvanceFil None e CreateFDCNExtFile None

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

346

PccFDCSetup
This class contains FDMS Omaha / FDR extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccFDCSetup Properties
Property Name AVS Data Type Boolean Description - PccFDCSetup Properties Flag that indicates if merchant will use address verification when processing transactions. The merchants business type. Valid values: 0 Retail 1 Mail order 2 Electronic commerce Used internally Device Identification. This value is a merchant assigned code identifying the device at the merchants location. This field is required if there is one merchant number assigned to more than one terminal at a merchants location. Length: 4 characters Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup The Datawire ID. The value is provided to the merchant by their Merchant Service Provider or Processing company. The DID is required to process transactions via the Internet using the Datawire network. This value will be unique for each merchant number used. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Current batch number. This value is incremented by the processor after each successful settlement. Sequence number of the last transaction transmitted Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields N/A Used internally The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds Indicates whether to use the SprintNet network when processing transactions. Note: The phone number to be dialed must be a SprintNet phone number. If this option is enabled and the phone number is a direct FDMS Omaha / FDR phone number, transactions will fail. Valid values: 0 Dial direct to FDMS Omaha / FDR 1 Use SprintNet network The SprintNet address to be used if Sprint = TRUE. The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds N/A

BType

Integer

Canceled Device

Boolean String

DialBackup

Boolean

DID

String

Index

Integer

IP LBatch LItem

String String String Boolean Boolean Boolean String

PCard

Prompt SecondaryIP SettleTimeOut

Sprint

Boolean

SprintAdd TimeOut URL

String String String

347

URL2 URLAddress

String String

N/A The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP.

PccFDCSetup Methods
Method Name CreateFDCExtFile Returned Value None Description - PccFDCSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced.

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

348

PccGiftCardSetup
This class contains information about the gift card company setup in the current instance of PCCharge. This is a Multi Use class.

PccGiftCardSetup Properties
Property Name Canceled Company Data Type Boolean Integer Description - PccGiftCardSetup Properties Used internally Used internally The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. Max Length: 32 characters. This value can be alphanumeric. Provides extended setup information for Buypass Provides extended setup information for Datamark Gift Card

Index

Integer

MerchantNumber PCCBBGFSetup PccBPASSetup PccBPSGiftSetup PccDMRKSetup PccGSARGiftSetup PccGsarSetup PccGVEXSetup PccLYNKGiftSetup PccMELLSetup PCCSMTSSetup PCCSPSGiftSetup PCCSVSISetup PccVLNKSetup PccVTECSetup PccWRLDSetup PrimaryPhone

String

PCCBBGFSetup Used internally PccBPASSetup PccDMRKSetup PccBPSGiftSetup Provides extended setup information for Fifth-Third Bank-St Pete PccGSARGiftSet Provides extended setup information for Chase Paymentech up PccGsarSetup PccGVEXSetup Provides extended setup information for Chase Paymentech Provides extended setup information for Givex

PccLYNKGiftSetu Provides extended setup information for RBS Lynk, Inc. p PccMELLSetup Provides extended setup information for Mellennia PCCSMTSSetup Provides extended setup information for Smart Transaction Systems PCCSPSGiftSetu Provides extended setup information for Secure Payment Systems p PCCSVSISetup PccVLNKSetup PccVTECSetup PccWRLDSetup String String String Provides extended setup information for Stored Value Systems Provides extended setup information for ValueLink Provides extended setup information for Valutec Provides extended setup information for World The Primary number that will be used when processing transactions via dial-up modem. The code for the processing company. This value can be no more than four characters and must be capitalized. A list of valid processor codes are listed in the Processing Company Codes section (see page 101). The Secondary number that will be used when processing transactions via dial-up modem.

Processor

SecondaryPhone

349

PccGiftCardSetup Methods
Method Name CreateGCTFile Returned Value None Description - PccGiftCardSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Used internally Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

ProcessorSetup Save

Object Boolean

Show

Boolean

350

PccGSARGiftSetup
This class contains Chase Paymentech Gift Card extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccGSARGiftSetup Properties
Property Name BatchNumber BType Canceled Client Data Type String Integer Boolean String Description - PccGSARGiftSetup Properties The Current batch number. This value is incremented by the processor after each successful settlement. The merchants business type. Valid values: Used internally Client Number assigned by the merchants bank or processor. Length: 4 digits Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP Leased Line 2 TCP/IP Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup Used internally Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. The Current Gift Card batch number. This value is incremented by the processor after each successful settlement. Client Number assigned by the merchants bank or processor for gift card processing. Length: 4 digits. Note: This gift card specific property exists in case the Chase Paymentech credit and gift card client numbers are different. Retrieval Reference Number. Used to identify and track the original transaction. This value is assigned by the merchants processor. Length: 8 digits Flag the indicates whether the Clerk ID is required when processing gift transactions Valid values: 0 Clerk ID not required 1 Clerk ID required The Gift Card sequence number. This number is automatically incremented after every transaction. Indicates method of connection to processor when processing gift cards. Valid values: 0 Dial-up 1 TCP/IP Leased Line 2 TCP/IP The Password assigned by the merchants bank or processor for TCP/IP processing. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. The Username assigned by the merchants bank or processor for TCP/IP processing.

Connect

Integer

DialBackup

Boolean Integer String String String String

EDCType ExpansionFactor

gcBatchNumber

gcClient

gcLastRRefNum

gcRequireClerkID

String

gcSeqNum

String

GiftConnect

Integer

GiftPassword GiftPrimaryAuthIP GiftPrimaryAuthPort GiftUsername

String String String String

351

Property Name

Data Type

Description - PccGSARGiftSetup Properties The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Password assigned by the merchants bank or processor for TCP/IP processing. Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields The system/socket port used to connect to the processor when processing via TCP/IP. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. The Hostname, URL, or IP address used to connect to the processor when performing settlement via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required The secondary Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. Used internally The secondary Hostname, URL, or IP address used to connect to the processor when performing settlement via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. This field is for identifying transactions within the batch. Assigned by PCCharge Length: 3 digits The system/socket port used to connect to the processor when processing via TCP/IP. The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when performing settlement via TCP/IP. The Service Industries Incentive Program indicator flag. Used to indicate recurring payments for service industries such as insurance, telecom and utilities. The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Username assigned by the merchants bank or processor for TCP/IP processing.

Index

Integer

Password

String

PCard

Boolean

Port PrimaryAuthIP PrimaryAuthPort PrimarySettleIP PrimarySettlePort

Long String String String String

RequireServerID

String

SecondaryAuthIP SecondaryAuthPort SecondaryIP SecondarySettleIP SecondarySettlePort Sequence SettlePort

String String Boolean String String String Long String String Boolean String String String

SettleTimeOut

SettleURL SIIP

TimeOut

URL Username

352

PccGSARGiftSetup Methods
Method Name Returned Value Description - PccGSARGiftSetup Methods Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced. Shows a GUI form that allows the end-user to enter extended configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowGiftCard.

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

ShowGiftCard

Boolean

353

PccGsarSetup
This class contains Chase Paymentech extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccGsarSetupProperties
Property Name BatchNumber Data Type String Description - PccGsarSetup Properties The Current batch number. This value is incremented by the processor after each successful settlement. The merchants business type. Valid values: 0 Retail 1 Mail order 2 Electronic commerce 4 Restaurant Used internally Client Number assigned by the merchants bank or processor. Length: 4 digits Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP Leased Line 2 TCP/IP Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup Used internally Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. The Current Gift Card batch number. This value is incremented by the processor after each successful settlement. Client Number assigned by the merchants bank or processor for gift card processing. Length: 4 digits. Note: This gift card specific property exists in case the Chase Paymentech credit and gift card client numbers are different. Retrieval Reference Number. Used to identify and track the original transaction. This value is assigned by the merchants processor. Length: 8 digits Flag the indicates whether the Clerk ID is required when processing gift transactions Valid values: 0 Clerk ID not required 1 Clerk ID required The Gift Card sequence number. This number is automatically incremented after every transaction. Indicates method of connection to processor when processing gift cards. Valid values: 0 Dial-up 1 TCP/IP Leased Line 2 TCP/IP The Password assigned by the merchants bank or processor for TCP/IP processing. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. The Username assigned by the merchants bank or processor for TCP/IP processing.

BType

Integer

Canceled Client

Boolean String

Connect

String

DialBackup

Boolean Integer String String String String

EDCType ExpansionFactor

gcBatchNumber

gcClient

gcLastRRefNum

gcRequireClerkID

String

gcSeqNum

String

GiftConnect

Integer

GiftPassword GiftPrimaryAuthIP GiftPrimaryAuthPort GiftUsername

String String String String

354

Property Name

Data Type

Description - PccGsarSetup Properties The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Password assigned by the merchants bank or processor for TCP/IP processing. Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields The system/socket port used to connect to the processor when processing via TCP/IP. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. The Hostname, URL, or IP address used to connect to the processor when performing settlement via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required The secondary Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. Used internally The secondary Hostname, URL, or IP address used to connect to the processor when performing settlement via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. This field is for identifying transactions within the batch. Assigned by PCCharge Length: 3 digits The system/socket port used to connect to the processor when processing via TCP/IP. The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when performing settlement via TCP/IP. The Service Industries Incentive Program indicator flag. Used to indicate recurring payments for service industries such as insurance, telecom and utilities. The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Username assigned by the merchants bank or processor for TCP/IP processing.

Index

Integer

Password

String

PCard

Boolean

Port PrimaryAuthIP PrimaryAuthPort PrimarySettleIP PrimarySettlePort

String String String String String

RequireServerID

String

SecondaryAuthIP SecondaryAuthPort SecondaryIP SecondarySettleIP SecondarySettlePort Sequence SettlePort

String String Boolean String String String Long String String Boolean String String String

SettleTimeOut

SettleURL SIIP

TimeOut

URL Username

355

PccGsarSetup Methods
Method Name CreateGSARExtFile Returned Value None Description - PccGsarSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced. Shows a GUI form that allows the end-user to enter extended configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowGiftCard.

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

ShowGiftCard

Boolean

356

PccGVEXSetup
This class contains Givex extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccGVEXetup Properties
Property Name Canceled Data Type Boolean Integer Description - PccGVEXetup Properties Used internally Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Language Code. Valid values: 0 English (default) Personal identification number issued to merchant by processor The system/socket port used to connect to the processor when processing via TCP/IP. Used internally The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds Flag that indicates whether to use Points transactions. The Points service is used for tracking points in a points program. The merchant sends information on the card used and the amount of the transaction. This information is stored and is made available later. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. Flag that indicates whether to use units in conjunction with Points transactions. The points value is entered by the merchant and is tracked by the Givex system for the points program. Points could be the total number of items or some calculated unit value or anything else defined by the user. This can be used later when calculating the value to add to the card.

Connect

DialBackup

Boolean

Index

Integer

Language Pin Port Serial TimeOut

String String String String String

TrackPoints

Boolean

URL

String

UseUnits

Boolean

357

PccGVEXSetup Methods
Method Name CreateGVEXExtFile Returned Value None Description - PccGVEXSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter extended or advanced Gift Card configuration information such as the business type, communication method, or other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowGC.

Load

Boolean

Save

Boolean

Show

Boolean

ShowGC

Boolean

358

PccHPTSSetup
This class contains Heartland Payment Systems extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccHPTSSetup Properties
Property Name ABA Data Type String Description - PccHPTSSetup Properties The ABA number identifies the merchant to a direct debit switch. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 9 digits The Agent Bank Number issued by the merchants bank or processor. This parameter is used to identify a specific agent entity of the member bank or processor. Length: 6 digits. Example: 111111 N/A N/A The Current batch number. This value is incremented by the processor after each successful settlement. The Bank Identification Number issued by the merchants bank or processor. The BIN identifies the Merchant Service Provider that signed up the merchant. Length: 6 digits. Example: 999995 The merchants business type. Valid values: 0 Retail 1 Mail order 4 Restaurant Used internally The Merchant Category Code assigned by the merchants bank or processor. This parameter is used to identify the merchants industry classification. Length: 4 digits. Example: 5999 The Agent Chain Number issued by the merchants bank or processor. This parameter is used to identify a specific chain of an agent organization. Length: 6 digits. Example: 000000 The merchants postal/zip code as assigned by the merchants bank or processor. Length: 5 or 9 digits. Example: 314193262 Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP The Country Code assigned by the merchants bank or processor. This parameter is used to identify the merchants country location. Length: 3 digits. Valid Value: 840 U.S.

Agent AuthPrimaryPort AuthPrimaryURL Batch

String String String String String

Bin

BType

Integer

Canceled Category

Boolean String

Chain

String String

City

Connect

Integer

Country

String

CreditTermType

CreditTerminalTy N/A pe String The Merchant Local Telephone Number. Length: 11 characters. Format: NNNnnnnnnn where NNN is the area code and nnnnnnn is the telephone number. The hyphen is required. Example: 800-7259264 The Currency Code assigned by the merchants bank or processor. This parameter is used to identify the merchants settlement currency. Length: 3 digits. Valid Value: 840 U.S. Dollars The Bank Identification Number issued by the merchants bank or processor. The BIN identifies the Merchant Service Provider that signed up the merchant. Length: 6 digits. Example: 999995

CSPhone

CurrencyCode

String

DebitBIN

String

DebitTermType

CreditTerminalTy N/A pe Boolean Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup

DialBackup

359

Property Name DID ebtABA ebtBIN ebtFCSID ebtReimbursement ebtSettleAgent ebtSharingGroup EBTTermType

Data Type String String String String String String String

Description - PccHPTSSetup Properties N/A N/A N/A N/A N/A N/A N/A

DebitTerminalTyp N/A e String Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. Express Pay flag. This setting only applies if the Business Type is set to retail. If this flag is set to TRUE and the amount of the transaction is less than the FloorLimit amount, PCCharge will not authorize the transactionit will only place the transaction in the open batch. Express Pay is usually used in a quick service environment with small ticket items. Note: Using Express Pay will increase transaction processing costs. The floor limit amount. This setting is only applicable if the Business Type is set to retail. The floor limit is the maximum transaction amount that will be accepted by PCCharge when processing an Express Pay transaction The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. Language indicator. Length: 2 digits. Valid Values: 00 English 01 Spanish 02 Portuguese 03 Reserved for Irish 04 Reserved for French 05 Reserved for German 06 Reserved for Italian 07 Reserved for Dutch The Merchant Location Number provides additional information on the location of the merchant. Length: 5 characters. Example: 00001 Note: This value should be 00001 unless otherwise specified by the merchants bank or processor. Specifies the maximum number of transactions per batch that PCCharge will send to the processor. If the number of transactions to be settled is greater than the number specified in this setting, PCCharge will split the batch into multiple batches, each containing (at most) the number transactions specified in this setting. The batches are then sent to the processor one at a time. Example: A merchant has 250 transaction to settle and the MaxBatchSize is set to 100. PCCharge will send two 100-transaction batches and one 50-transaction batch. Max Value: 999 N/A N/A Primary phone number for settlement. If this value is set and Dial-up modem is the communication method, PCCharge will attempt to settle transactions using this phone number rather than the authorization phone number. Secondary phone number for settlement. If this value is set and Dial-up modem is the communication method, PCCharge will attempt to settle transactions using this phone number rather than the authorization phone number. The system/socket port used to connect to the processor when processing via TCP/IP.

ExpansionFactor

ExpressPay

Boolean

FloorLimit

String

Index

Integer

IP

String

Language

String

Location

String

MaxBatchSize

String

MCReversal PCard Phone1

Boolean Boolean String

Phone2

String String

Port

360

Property Name Reimbursement

Data Type String

Description - PccHPTSSetup Properties The Reimbursement Attribute designates the Reimbursement Fee applicable to a transaction. Applicable for Debit/EBT transactions. This value is assigned to the merchant by their Merchant Services Provider or Processor. Length: 1 character. Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required The Merchant Settlement Agent Number identifies the merchant settling agent. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 4 characters N/A N/A N/A N/A N/A N/A N/A The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Sharing Group contains a listing of direct debit and EBT networks that may be accessed. This value is provided to the merchant by their Merchant Services Provider or Processor. The values must correspond to one of the Visa assigned direct debit network types. This data is part of the VisaNet direct debit data. Length: 1 to 30 characters. The Store Number assigned by the merchants bank or processor. This parameter is used to identify a specific merchant store location. Length: 4 digits. Example: 0011 The Terminal Number assigned by the merchants bank or processor. This parameter is used to identify a specific store terminal. Length: 4 digits. Example: 9911. N/A The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Time Zone Differential as assigned by the merchants bank or processor. This value provides the standard local time zone differential from Greenwich Mean Time (GMT). Length: 3 digits. Valid Values: 705 Eastern 706 Central 707 Mountain 708 Pacific Note: Replace the leading 7 with a 1 if Daylight Savings is not observed. Example: 107 Arizona N/A N/A N/A

RequireServerID

String

SettleAgent SettleConnect SettleDialBackUp SettleMaxBlockCount SettleMaxBlockSize SettlePrimaryPort SettlePrimaryURL SettleTCP SettleTimeOut

String String String String String String String Boolean String

SharingGroup

String

Store

String

Terminal TID TimeOut

String String String

TimeZone

String

URL URL2 VSReversal

String String Boolean

361

PccHPTSSetup Methods
Method Name Returned Value Description - PccHPTSSetup Methods Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced. Shows a GUI form that allows the end-user to enter Debit configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowDebit. Shows a GUI form that allows the end-user to enter EBT configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowEBT.

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

ShowDebit

Boolean

ShowEBT

Boolean

362

PccImpSetup
This class contains information about the Import File setup in the current instance of PCCharge. This is a Multi Use class.

PccImpSetup Properties
Property Name APPAVS BADAVS Canceled CustName Data Type Boolean Boolean Boolean Boolean Description - PccImpSetup Properties Indicates whether to include AVS responses in .app files Indicates whether to include AVS responses in .bad files Used internally Indicates whether to include customer name in import files The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Indicates whether to include commercial / purchasing card information in import files

Index

Integer

PCardInfo

Boolean

PccImpSetup Methods
Method Name CreateImportFile Returned Value None Description - PccImpSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

363

PccLYNKGiftSetup
PccLYNKGiftSetup Properties
Property Name Bank Data Type String String String String Boolean String Description - PccLYNKGiftSetup Properties The Agent Bank Number issued by the merchants bank or processor. This parameter is used to identify a specific agent entity of the member bank or processor. Length: 6 digits. Example: 111111 The Current batch number. This value is incremented by the processor after each successful settlement. The Bank Identification Number issued by the merchants bank or processor. The BIN identifies the Merchant Service Provider that signed up the merchant. Length: 6 digits. Example: 999995 N/A Used internally The Merchant Category Code assigned by the merchants bank or processor. This parameter is used to identify the merchants industry classification. Length: 4 digits. Example: 5999 The Agent Chain Number issued by the merchants bank or processor. This parameter is used to identify a specific chain of an agent organization. Length: 6 digits. Example: 000000 The merchants postal/zip code as assigned by the merchants bank or processor. Length: 5 or 9 digits. Example: 314193262 The merchants postal/zip code as assigned by the merchants bank or processor. Length: 5 or 9 digits. Example: 314193262 The merchants name as assigned by the merchants bank or processor. The merchants state abbreviation as assigned by the merchants bank or processor. N/A The Country Code assigned by the merchants bank or processor. This parameter is used to identify the merchants country location. Length: 3 digits. Valid Value: 840 U.S. The Merchant Local Telephone Number. Length: 11 characters. Format: NNNnnnnnnn where NNN is the area code and nnnnnnn is the telephone number. The hyphen is required. Example: 800-7259264 The Currency Code assigned by the merchants bank or processor. This parameter is used to identify the merchants settlement currency. Length: 3 digits. Valid Value: 840 U.S. Dollars N/A N/A N/A N/A N/A N/A N/A N/A The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc.

Batch

Bin BType Canceled Category

Chain

String String String String String Integer String

City CompanyCity CompanyName CompanyState Connect Country

CSPhone

String

CurrencyCode DialBackup Expansion GiftConnect GiftDialBackup GiftPort GiftSettleTimeOut GiftTimeOut GiftURL

String Boolean String Integer Boolean String String Integer String

Index

Integer

364

Property Name

Data Type

Description - PccLYNKGiftSetup Properties Language indicator. Length: 2 digits. Valid Values: 00 English 01 Spanish 02 Portuguese 03 Reserved for Irish 04 Reserved for French 05 Reserved for German 06 Reserved for Italian 07 Reserved for Dutch N/A N/A N/A N/A N/A The Store Number assigned by the merchants bank or processor. This parameter is used to identify a specific merchant store location. Length: 4 digits. Example: 0011 The Terminal Number assigned by the merchants bank or processor. This parameter is used to identify a specific store terminal. Length: 4 digits. Example: 9911. N/A The Time Zone Differential as assigned by the merchants bank or processor. This value provides the standard local time zone differential from Greenwich Mean Time (GMT). Length: 3 digits. Valid Values: 705 Eastern 706 Central 707 Mountain 708 Pacific Note: Replace the leading 7 with a 1 if Daylight Savings is not observed. Example: 107 Arizona N/A

Language

String

Location Phone1 Phone2 Port SettleTimeOut Store

String String String String String String

Terminal TimeOut

String Integer

TimeZone

String

URL

String

PccLYNKGiftSetup Methods
Method Name Returned Value Description - PccLYNKGiftSetup Methods Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced. N/A

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

ValidateExt

Boolean

365

PccLYNKSetup
This class contains RBS Lynk extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccLYNKSetup Properties
Property Name ABA Data Type String Description - PccLYNKSetup Properties The ABA number identifies the merchant to a direct debit switch. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 9 digits The Agent Bank Number issued by the merchants bank or processor. This parameter is used to identify a specific agent entity of the member bank or processor. Length: 6 digits. Example: 111111 N/A N/A The Current batch number. This value is incremented by the processor after each successful settlement. The Bank Identification Number issued by the merchants bank or processor. The BIN identifies the Merchant Service Provider that signed up the merchant. Length: 6 digits. Example: 999995 The merchants business type. Valid values: 0 Retail 1 Mail order 4 Restaurant Used internally The Merchant Category Code assigned by the merchants bank or processor. This parameter is used to identify the merchants industry classification. Length: 4 digits. Example: 5999 The Agent Chain Number issued by the merchants bank or processor. This parameter is used to identify a specific chain of an agent organization. Length: 6 digits. Example: 000000 The merchants postal/zip code as assigned by the merchants bank or processor. Length: 5 or 9 digits. Example: 314193262 Indicates method of connection to processor. Valid values: 0 Dial-up 1 ISDN 2 TCP/IP The Country Code assigned by the merchants bank or processor. This parameter is used to identify the merchants country location. Length: 3 digits. Valid Value: 840 U.S.

Agent AuthPrimaryPort AuthPrimaryURL Batch

String String String String String

Bin

BType

Integer

Canceled Category

Boolean String

Chain

String String

City

Connect

Integer

Country

String

CreditTermType

CreditTerminalTy N/A pe String The Merchant Local Telephone Number. Length: 11 characters. Format: NNNnnnnnnn where NNN is the area code and nnnnnnn is the telephone number. The hyphen is required. Example: 800-7259264 The Currency Code assigned by the merchants bank or processor. This parameter is used to identify the merchants settlement currency. Length: 3 digits. Valid Value: 840 U.S. Dollars The Bank Identification Number issued by the merchants bank or processor. The BIN identifies the Merchant Service Provider that signed up the merchant. Length: 6 digits. Example: 999995

CSPhone

CurrencyCode

String

DebitBIN

String

DebitTermType

CreditTerminalTy N/A pe

366

Property Name

Data Type Boolean String String String String String String String

Description - PccLYNKSetup Properties Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup N/A N/A N/A N/A N/A N/A N/A

DialBackup

DID ebtABA ebtBIN ebtFCSID ebtReimbursement ebtSettleAgent ebtSharingGroup EBTTermType

DebitTerminalTyp N/A e String Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. Express Pay flag. This setting only applies if the Business Type is set to retail. If this flag is set to TRUE and the amount of the transaction is less than the FloorLimit amount, PCCharge will not authorize the transactionit will only place the transaction in the open batch. Express Pay is usually used in a quick service environment with small ticket items. Note: Using Express Pay will increase transaction processing costs. The floor limit amount. This setting is only applicable if the Business Type is set to retail. The floor limit is the maximum transaction amount that will be accepted by PCCharge when processing an Express Pay transaction The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. Language indicator. Length: 2 digits. Valid Values: 00 English 01 Spanish 02 Portuguese 03 Reserved for Irish 04 Reserved for French 05 Reserved for German 06 Reserved for Italian 07 Reserved for Dutch The Merchant Location Number provides additional information on the location of the merchant. Length: 5 characters. Example: 00001 Note: This value should be 00001 unless otherwise specified by the merchants bank or processor. Specifies the maximum number of transactions per batch that PCCharge will send to the processor. If the number of transactions to be settled is greater than the number specified in this setting, PCCharge will split the batch into multiple batches, each containing (at most) the number transactions specified in this setting. The batches are then sent to the processor one at a time. Example: A merchant has 250 transaction to settle and the MaxBatchSize is set to 100. PCCharge will send two 100-transaction batches and one 50-transaction batch. Max Value: 999 N/A Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields Used internally

ExpansionFactor

ExpressPay

Boolean

FloorLimit

String

Index

Integer

IP

String

Language

String

Location

String

MaxBatchSize

String

MCReversal

Boolean Boolean

PCard

PccVisaSetup_ebtFCSI String D

367

Property Name Phone1

Data Type String

Description - PccLYNKSetup Properties Primary phone number for settlement. If this value is set and Dial-up modem is the communication method, PCCharge will attempt to settle transactions using this phone number rather than the authorization phone number. Secondary phone number for settlement. If this value is set and Dial-up modem is the communication method, PCCharge will attempt to settle transactions using this phone number rather than the authorization phone number. The system/socket port used to connect to the processor when processing via TCP/IP. The Reimbursement Attribute designates the Reimbursement Fee applicable to a transaction. Applicable for Debit/EBT transactions. This value is assigned to the merchant by their Merchant Services Provider or Processor. Length: 1 character. Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required The Merchant Settlement Agent Number identifies the merchant settling agent. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 4 characters N/A N/A N/A N/A N/A N/A N/A The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Sharing Group contains a listing of direct debit and EBT networks that may be accessed. This value is provided to the merchant by their Merchant Services Provider or Processor. The values must correspond to one of the Visa assigned direct debit network types. This data is part of the VisaNet direct debit data. Length: 1 to 30 characters. The Store Number assigned by the merchants bank or processor. This parameter is used to identify a specific merchant store location. Length: 4 digits. Example: 0011 The Terminal Number assigned by the merchants bank or processor. This parameter is used to identify a specific store terminal. Length: 4 digits. Example: 9911. N/A The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Time Zone Differential as assigned by the merchants bank or processor. This value provides the standard local time zone differential from Greenwich Mean Time (GMT). Length: 3 digits. Valid Values: 705 Eastern 706 Central 707 Mountain 708 Pacific Note: Replace the leading 7 with a 1 if Daylight Savings is not observed. Example: 107 Arizona N/A N/A Indicates whether VISA reversals will be processed.

Phone2

String String String

Port

Reimbursement

RequireServerID

String

SettleAgent SettleConnect SettleDialBackUp SettleMaxBlockCount SettleMaxBlockSize SettlePrimaryPort SettlePrimaryURL SettleTCP SettleTimeOut

String String String String String String String Boolean String

SharingGroup

String

Store

String

Terminal TID TimeOut

String String String

TimeZone

String

URL URL2 VSReversal

String String Boolean

368

PccLYNKSetup Methods
Method Name Returned Value Description - PccLYNKSetup Methods Used internally Used internally Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Used internally Used internally Used internally Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced. Shows a GUI form that allows the end-user to enter Debit configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowDebit. Shows a GUI form that allows the end-user to enter EBT configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowEBT.

CreateLYNKAdvanceFil None e CreateLynkDebitExtFi None le CreateLynkExtFile None

Load

Boolean

PccVisaSetup_CreateV None isaDebitExtFile PccVisaSetup_CreateV None isaExtFile PccVisaSetup_CreateV None isaIPNExtFile Save Boolean

Show

Boolean

ShowAdvanced

Boolean

ShowDebit

Boolean

ShowEBT

Boolean

369

PccMELLSetup
This class contains Mellennia extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccMELLSetup Properties
Property Name BType Canceled Connect Data Type String Boolean Integer Description - PccMELLSetup Properties The merchants business type. Valid values: 0 Restaurant 1 Other Used internally N/A The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Indicates whether the Server ID needs to be filled for a transaction to completed. Valid Values: 0 Not required 1 Required

Index

Integer

RequireClerkID

String

PccMELLSetup Methods
Method Name CreateMELLExtFile Returned Value None Description - PccMELLSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter extended or advanced Gift Card configuration information such as the business type, communication method, or other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowGC.

Load

Boolean

Save

Boolean

Show

Boolean

ShowGC

Boolean

370

PccModem
This class allows modem configuration. Note: This class can only be accessed through the PccActiveCharge class. Restricting its instantiation eliminates the possibility of multiple instancing. See the following code fragment. 'In Declare section: Dim clsActiveCharge As ActiveCharge.PccActiveCharge Dim WithEvents clsModem As ActiveCharge.PccModem 'In Implementation section: Set clsActiveCharge = New ActiveCharge.PccActiveCharge Set clsModem = clsActiveCharge.PccModem With clsModem .Load .Validate ("AT") End With Once OnUpdate event fires: MsgBox Status This is a Public Not Creatable class.

PccModem Properties
Property Name Baud Canceled CFGFile DialBackup DialMethod DialPrefix DialString EncLogFile Index InitString LogFile LogFileBacking ModemType Port PurgeSize RespDelay TAPIFriendlyName** TAPIIndex** Data Type String Boolean Collection Boolean String String String Boolean Integer String Boolean Boolean String Integer Long String String Integer Description - PccModem Properties The baud rate (300, 1200). Used internally Allows viewing the modem strings contained in the MODEM.CFG file. Requires the index number of the modem string as a parameter. N/A The dial method. Valid values: T Tone P Pulse The dial prefix. Example: ,9 Used internally Flag that indicates whether to encrypt the communication log file. This option should be set to TRUE if providing the communication log file to VeriFone, Inc.s technical support department. N/A The modem initialization string Flag that indicates whether to create a communications log file. Flag that indicates whether to create a backup of the communications log file. Name of the modem initialization string Specifies COM port used for modem connection Specifies the size limit of the communications log to begin purging. Format: KB The Response delay used when dialing. This value should be increased if experiencing problems with WinModems. Format: seconds Name of modem as listed by TAPI drivers Which modem to use as specified by local machine TAPI modem index

371

Property Name

Data Type

Description - PccModem Properties Flag that indicates to use the Windows modem settings N/A Indicates whether to use TAPI for modem connection Flag that indicates whether to re-initialize the modem before each transaction. Activating this setting fixes issues with some WinModems.

TAPIUseDefaultSettin Boolean gs UseISDN UseTAPI WinModem Boolean Boolean Boolean

** To use these properties, UseTapi must be set to TRUE.

PccModem Methods
Method Name Cancel CreateModemFile GetBaud GetOK GetPort InitModem Returned Value Boolean None String Boolean Integer Boolean Description - PccModem Methods The Cancel method attempts to cancel the test transaction in progress. Calling the Cancel method does not guarantee that the test transaction will be canceled; it simply attempts to cancel the test transaction. Used internally Used internally Used internally Used internally Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. PccTest runs a transaction test using the currently selected merchant number and communication type. PccTest can test either TCP/IP or dial-up communicationit tests whichever communication method is selected in the extended configuration of the currently selected merchant number. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Used internally Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Used internally Used internally Used internally Validates a modem initialization string. This method requires a modem initialization string to be passed as a parameter. This method passes each portion of the initialization string to the modem. If the modem responds to a portion with an OK response, that portion is kept. If the modem responds to a portion with an ERROR response, that portion is discarded. The method then constructs a new modem initialization string with the remaining kept portions and places that string in the InitString property. TRUE is returned if the operation is successful, FALSE otherwise.

Load

Boolean

PccTest

Boolean

Save SetBaud

Boolean Integer

Show

Boolean

TAPIGetModemCount TAPIGetModemIndex TAPIGetModemName

Integer Integer String

Validate

Boolean

PccModem Events
Method Name OnUpdate Returned Value Boolean Description - PccModem Methods The OnUpdate event will fire when the PccModem class provides status messages. Once the ActionUpdate event has fired the Status value is set with the current status message provided by the PccModem class.

372

PccNBSetup
This class contains FDMS South / NaBanco merchant number extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccNBSetup Properties
Property Name Address1 Address2 AMEX BatchNumber BatchSerial Data Type String String String String String Description - PccNBSetup Properties The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The secondary Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. American Express service establishment number. Length: 9 or10 digits The Current batch number. This value is incremented by the processor after each successful settlement. Unique Terminal Serial Number for the current merchant number. Length: 2 digits. The merchants business type. Valid values: 0 Retail 1 Mail Order 4 Restaurant Used internally Carte Blanche service establishment number. Length: 10 digits The Merchant Category Code assigned by the merchants bank or processor. This parameter is used to identify the merchants industry classification. Length: 4 digits. Example: 5999 Indicates method of connection to processor. Valid values: 0 = dial-up 1 TCP/IP Lease Line 2 = First Data IPN (Datawire TCP/IP) The Country Code assigned by the merchants bank or processor. This parameter is used to identify the merchants country location. Length: 3 digits. Valid Value: 840 U.S. The Datawire ID. The value is provided to the merchant by their Merchant Service Provider or Processing company. The DID is required to process transactions via the Internet using the Datawire network. This value will be unique for each merchant number used. Count of Debit Sales Total amount of Debit Sales Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup The Datawire ID. The value is provided to the merchant by their Merchant Service Provider or Processing company. The DID is required to process transactions via the Internet using the Datawire network. This value will be unique for each merchant number used. Diners Club service establishment number. Length: 10 digits Discover service establishment number. Length: 10 digits Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI.

BType

Integer

Canceled Carte Category

Boolean String String

Connect

String

Country

String

DebitDID

String

DebitSalesCount DebitTotalSalesAmt

String String String

DialBackup

DID

String String String String

Diners Discover ExpansionFactor

373

Property Name

Data Type

Description - PccNBSetup Properties The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. JAL service establishment number. Length: 10 digits JCB service establishment number. Length: 10 digits N/A Specifies the maximum number of transactions per batch that PCCharge will send to the processor. If the number of transactions to be settled is greater than the number specified in this setting, PCCharge will split the batch into multiple batches, each containing (at most) the number transactions specified in this setting. The batches are then sent to the processor one at a time. Example: A merchant has 250 transaction to settle and the MaxBatchSize is set to 100. PCCharge will send two 100-transaction batches and one 50-transaction batch. Max Value: 999 Indicates whether merchant is using the MCI dialing option rather than a direct connection to the processor. Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields The system/socket port used to connect to the processor when processing via TCP/IP. The system/socket port used to connect to the processor when processing via TCP/IP. The secondary system/socket port used to connect to the processor when processing via TCP/IP. Used internally The Qual code identifies the merchants plan code and types cards that are accepted. This value is assigned by the merchants bank or processor. Length: 6 digits. Used internally Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required Used internally Unique Terminal Serial Number for the current merchant number. Length: 2 digits. N/A The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Merchant Category Code assigned by the merchants bank or processor. This parameter is used to identify the merchants industry classification. Length: 4 digits. Example: 5999 The State Code This value is provided to the merchant by their Merchant Service Provider or Processing company. This value identifies the merchants. Length: 2 digits Used internally Timeout value for leased-line connectivity. Valid range: 1-45 (seconds) The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. N/A The merchants zip code

Index

Integer

IP JAL JCB Mastercard

String String String Boolean

MaxBatchSize

String

MCI

Boolean

PCard

String

Port Port1 Port2 ProcessingDebit Qual ReceiptNumber

String String String Boolean String String

RequireServerID

String

SecondaryIP Serial SerialNumber SettleTimeOut

Boolean String String String

SICCode

String

State TermID Timeout URL Visa Zip

String String String String Boolean String

374

PccNBSetup Methods
Method Name CreateNBExtFile Returned Value None Description - PccNBSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Debit configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowDebit.

Load

Boolean

Save

Boolean

Show

Boolean

ShowDebit

Boolean

375

PccNBSSetup
This class contains National Bankcard Services merchant number extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccNBSSetup Properties
Property Name AcceptVMCFleet String BatchNumber BType String String Data Type Description - PccNBSSetup Properties The setting to accept Visa/MC Fleet Cards. Valid Values: 0 = No 1 = Yes The batch number. The business type. Currently, NBS only supports retail. Valid Values: 0 = Retail The CAT setting. Valid Values: 0 = No 1 = Yes The connection type. Valid Values: 0 = Dial 1 = Datawire The debit CAT setting. Valid Values: 0 = No 1 = Yes The Datawire ID. The dial backup indicator. Valid Values: 0 = No 1 = Yes The setting to enabled Product Details. Note: Must be checked if Fleet Cards will be accepted. Valid Values: 0 = No 1 = Yes Indicator used for logging into the NBS system. The maximum batch size. The PCard (commercial card) acceptance setting. Valid Values: 0 = No 1 = Yes The URL for Datawire registration. This is defaulted in PCCharge. The secondary Datawire URL. This is defaulted in PCCharge. The settlement timeout value. The default value is 240 seconds. The authorization timeout value. The default value is 60 seconds. The time zone. This is the offset from GMT. This is in the format HHMM for the first four digits, and the last digit is the Daylight Savings Time indicator (0 = No, 1 = Yes). The primary Datawire URL. This is defaulted in PCCharge.

CATType

String

Connect

String

DebitCATType

String String String

DID

DialBackup

EnableProductDetail

String

LoggedOn MaxBatchSize

String String String

PCard

RegistrationURL SecondaryURL SettleTimeout TimeOut TimeZone URL

String String String String String String

376

PccNBSSetup Methods
Method Name Returned Value Description - PccNBSSetup Methods Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Debit configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowDebit. Returns the default Datawire URL. Returns the default registration URL.

Load

Boolean

Save

Boolean

Show

Boolean

ShowDebit

Boolean

GetDefaultURL

String

GetDefaultRegistrationURL String

377

PccNDCSetup
This class contains Global Payments-East extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccNDCSetup Properties
Property Name BankID BatchAmount BatchNumber Data Type String String String Description - PccNDCSetup Properties The Bank ID assigned by the merchants bank or processor. Length: 6 digits. Balance of current batch The Current batch number. This value is incremented by the processor after each successful settlement. The merchants business type. Valid values: 0 Retail 1 Mail Order 2 E-Commerce 4 Restaurant Used internally Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP Flag that indicates if the DataPac Communications Network will be used to connect to the processor. Set to TRUE if connecting to the processor in Canada. Amount of debit purchases. Number of debit purchases. Amount of debit returns. Number of debit returns. Used only for Canadian Debit Transactions. Determines if duplicate transactions are allowed with processing Canadian debit transactions. See the section Canadian (Interac) Debit Transactions (see page 77) for more information. Valid Values: 0 Do not allow Duplicate transactions 1 Allow Duplicate transactions Used internally Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Number of transactions in current batch The Merchant Location Number provides additional information on the location of the merchant. Length: 5 characters. Example: 00001 Note: This value should be 00001 unless otherwise specified by the merchants bank or processor. Indicates whether batches will be manually opened and closed N/A Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields Amount of sale or post-authorization transactions Number of sale or post-authorization transactions

BType

Integer

Canceled

Boolean Integer

Connect

DataPack DebitPurchaseAmount DebitPurchaseCount DebitReturnAmount DebitReturnCount

Boolean String String String String

Duplicate

String

EDCType ExpansionFactor

String String

Index

Integer

ItemCount Location Manual MerchantType

String String Boolean String Boolean String String

PCard

PurchaseAmt PurchaseCount

378

Property Name

Data Type

Description - PccNDCSetup Properties Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required Amount of credits Number of credits Used internally The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds Flag that indicates if SprintNet will be used to connect to the processor. Set to TRUE if connecting to SprintNet. The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds Used only for Canadian Debit Transactions. The percentage of tip that will be displayed on the PINpad. See the section Canadian (Interac) Debit Transactions (see page 77) for more information. Used only for Canadian Debit Transactions. The type of tip calculation that will occur. See the section Canadian (Interac) Debit Transactions (see page 77) for more information. Current transaction item number N/A N/A The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP.

RequireServerID

String

ReturnAmt ReturnCount SecondaryIP SettleTimeOut

String String Boolean String

Sprint

Boolean String

TimeOut

TipPercent

String

TipType TranItem URL URL2 URLAddress

String String String String String

PccNDCSetup Methods
Method Name CreateNDCExtFile Returned Value None Description - PccNDCSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced. Shows a GUI form that allows the end-user to enter Debit configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowDebit.

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

ShowDebit

Boolean

379

PccNovaSetup
This class contains NOVA extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccNovaSetup Properties
Property Name Balance BankID BatchNumber Data Type String String String Description - PccNovaSetup Properties Balance of current batch The Bank ID assigned by the merchants bank or processor. Length: 6 digits. The Current batch number. This value is incremented by the processor after each successful settlement. The merchants business type. Valid values: 0 Retail 1 Mail order 2 Electronic Commerce Used internally Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP The record count (The number of transactions in the batch) Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup Flag that indicates whether processing will occur on NOVAs host-based system or the terminal-based system. This setting must match what NOVA has set up for the merchant (i.e. a NOVA terminal-based merchant account will not work on the hostbased system) Valid values: 0 Host 1 Terminal The Hostname, URL, or IP address used to connect to NOVAs Test System when processing via TCP/IP. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. N/A Flag that indicates whether to send transactions to NOVAs test system or to the live system. TRUE Send to NOVAs Test System FALSE Send to NOVAs live system Indicates whether batches will be manually opened and closed Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields N/A The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds

BType

Integer

Canceled

Boolean Integer String Boolean

Connect

Counter

DialBackup

EDCType

Integer

HostName

String

Index

Integer

IPDebug

Boolean Boolean Boolean Boolean String String

IPTest

Manual

PCard

Sequence TimeOut

380

PccNovaSetup Methods
Method Name CreateNOVAExtFile Returned Value None Description - PccNovaSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

381

PccNPCSetup
This class contains National Processing Company extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccNPCSetup Properties
Property Name ABA Data Type String Description - PccNPCSetup Properties The ABA number identifies the merchant to a direct debit switch. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 9 digits The Agent Bank Number issued by the merchants bank or processor. This parameter is used to identify a specific agent entity of the member bank or processor. Length: 6 digits. Example: 111111 The system/socket port used to connect to the processor when processing via TCP/IP. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Current batch number. This value is incremented by the processor after each successful settlement. The Bank Identification Number issued by the merchants bank or processor. The BIN identifies the Merchant Service Provider that signed up the merchant. Length: 6 digits. Example: 999995 The merchants business type. Valid values: 0 Retail 1 Mail order 2 Electronic Commerce Used internally The Merchant Category Code assigned by the merchants bank or processor. This parameter is used to identify the merchants industry classification. Length: 4 digits. Example: 5999 The Agent Chain Number issued by the merchants bank or processor. This parameter is used to identify a specific chain of an agent organization. Length: 6 digits. Example: 000000 The merchants postal/zip code as assigned by the merchants bank or processor. Length: 5 or 9 digits. Example: 314193262 Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP The Country Code assigned by the merchants bank or processor. This parameter is used to identify the merchants country location. Length: 3 digits. Valid Value: 840 U.S.

Agent

String String String String String

AuthPrimaryPort AuthPrimaryURL Batch

Bin

BType

Integer

Canceled Category

Boolean String

Chain

String String

City

Connect

Integer

Country

String

CreditTermType CSPhone CurrencyCode

CreditTerminalTy N/A pe String String N/A The Currency Code assigned by the merchants bank or processor. This parameter is used to identify the merchants settlement currency. Length: 3 digits. Valid Value: 840 U.S. Dollars The Bank Identification Number issued by the merchants bank or processor. The BIN identifies the Merchant Service Provider that signed up the merchant. Length: 6 digits. Example: 999995

DebitBIN

String

DebitTermType

CreditTerminalTy N/A pe Boolean Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup

DialBackup

382

Property Name DID ebtABA

Data Type String String

Description - PccNPCSetup Properties N/A The ABA number identifies the merchant to a direct debit switch. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 9 digits The Bank Identification Number issued by the merchants bank or processor. The BIN identifies the Merchant Service Provider that signed up the merchant. Length: 6 digits. Example: 999995 The Food and Consumer Identifier identifies the Merchant as being certified and approved to accept Food Stamps. Applicable to EBT transactions only. Length: 0 to 7 characters. The Reimbursement Attribute designates the Reimbursement Fee applicable to a transaction. Applicable for Debit/EBT transactions. This value is assigned to the merchant by their Merchant Services Provider or Processor. Length: 1 character. The Merchant Settlement Agent Number identifies the merchant settling agent. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 4 characters The Sharing Group contains a listing of direct debit and EBT networks that may be accessed. This value is provided to the merchant by their Merchant Services Provider or Processor. The values must correspond to one of the Visa assigned direct debit network types. This data is part of the VisaNet direct debit data. Length: 1 to 30 characters.

ebtBIN

String

ebtFCSID

String

ebtReimbursement

String

ebtSettleAgent

String

ebtSharingGroup

String

EBTTermType ExpansionFactor ExpressPay FloorLimit

DebitTerminalTyp N/A e String Boolean String N/A N/A N/A The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. Language indicator. Length: 2 digits. Valid Values: 00 English 01 Spanish 02 Portuguese 03 Reserved for Irish 04 Reserved for French 05 Reserved for German 06 Reserved for Italian 07 Reserved for Dutch N/A N/A N/A Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields Primary phone number for settlement. If this value is set and Dial-up modem is the communication method, PCCharge will attempt to settle transactions using this phone number rather than the authorization phone number. Secondary phone number for settlement. If this value is set and Dial-up modem is the communication method, PCCharge will attempt to settle transactions using this phone number rather than the authorization phone number. The system/socket port used to connect to the processor when processing via TCP/IP.

Index

Integer

IP

String

Language

String

Location MaxBatchSize MCReversal

String String Boolean Boolean

PCard

Phone1

String

Phone2

String String

Port

383

Property Name Reimbursement RequireServerID SettleAgent

Data Type String String String

Description - PccNPCSetup Properties The Reimbursement Attribute designates the Reimbursement Fee applicable to a transaction. Applicable for Debit/EBT transactions. This value is assigned to the merchant by their Merchant Services Provider or Processor. Length: 1 character. N/A The Merchant Settlement Agent Number identifies the merchant settling agent. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 4 characters The type of connection used for settlement: Valid values: 0 Dial-up 1 TCP/IP SSL 2 TCP/IP Lease Line For settlement, flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup The maximum block count used for settlement. Default value: 5 The maximum block size used for settlement. Default value: 12000 Format: bytes The system/socket port used to connect to the processor when processing via TCP/IP. The Hostname, URL, or IP address used to connect to the processor when performing settlement via TCP/IP. Flag that determines whether settlement will occur using dial-up modem or TCP/IP. TRUE Settle via TCP/IP FALSE Settle via Dial-up Modem The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Sharing Group contains a listing of direct debit and EBT networks that may be accessed. This value is provided to the merchant by their Merchant Services Provider or Processor. The values must correspond to one of the Visa assigned direct debit network types. This data is part of the VisaNet direct debit data. Length: 1 to 30 characters. The Store Number assigned by the merchants bank or processor. This parameter is used to identify a specific merchant store location. Length: 4 digits. Example: 0011 The Terminal Number assigned by the merchants bank or processor. This parameter is used to identify a specific store terminal. Length: 4 digits. Example: 9911. Terminal ID number for merchant account The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Time Zone Differential as assigned by the merchants bank or processor. This value provides the standard local time zone differential from Greenwich Mean Time (GMT). Length: 3 digits. Valid Values: 705 Eastern 706 Central 707 Mountain 708 Pacific Note: Replace the leading 7 with a 1 if Daylight Savings is not observed. Example: 107 Arizona N/A N/A Indicates whether VISA reversals will be processed.

SettleConnect

String

SettleDialBackUp

String String String String String Boolean

SettleMaxBlockCount SettleMaxBlockSize SettlePrimaryPort SettlePrimaryURL

SettleTCP

SettleTimeOut

String

SharingGroup

String

Store

String

Terminal TID TimeOut

String String String

TimeZone

String

URL URL2 VSReversal

String String Boolean

384

PccNPCSetup Methods
Method Name Returned Value Description - PccNPCSetup Methods Used internally Used internally Validates that each configuration field has been entered. Returns FALSE if any of the fields are left blank. Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced. Shows a GUI form that allows the end-user to enter Debit configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowDebit. Shows a GUI form that allows the end-user to enter EBT configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowEBT.

CreateNPCDebitExtFil None e CreateNPCExtFile IsExtendedInfoValid None Boolean

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

ShowDebit

Boolean

ShowEBT

Boolean

385

PccPrivateSetup
This class contains information about the Private Label company setup in the current instance of PCCharge. This is a Multi Use class. PccPrivateSetup Properties
Property Name Authorize BINEnd BINStart CardDescription CardIndex CardType CheckDigitType Data Type Boolean String String String Integer String String Description - PccPrivateSetup Properties Flag that indicates whether the merchant will activate the processing of Private Label cards. The ending BIN range of the private label card The starting BIN range of the private label card Description of the type of private label card to be used The card index The type of private label card to be used The type of check digit routine used to validate private label cards. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Used internally Used internally Sets maximum length of the private label card numbers. The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. Max Length: 32 characters. This value can be alphanumeric. Sets minimum length of the private label card numbers. The multiplier that is used to verify that a private label card is valid. The Primary number that will be used when processing transactions via dial-up modem. The code for the processing company. This value can be no more than four characters and must be capitalized. Valid values: PRPN Periphonic ADSI Alliance Data Systems The Secondary number that will be used when processing transactions via dial-up modem. Used internally

Index

Integer

IsSetup MaxCards MaxLength MerchantNumber MinLength Multiplier PrimaryPhone

Boolean Integer Integer String Integer String String

Processor

String

SecondaryPhone Settle

String Boolean

386

PccPrivateSetup Methods
Method Name CreatePrivateFile Returned Value None Description - PccPrivateSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

387

PccRMRSSetup
This class contains National Check Network extended information for the current instance of PCCharge. This is a Public Not Creatable class. PccRMRSSetup Properties
Property Name BounceFee Canceled FTPAddress FTPPassword FTPUser Data Type String Boolean String String String Description - PccRMRSSetup Properties The fee used in cases of returned checks due to insufficient funds. Format: Dollars Used internally FTP address for check image upload. Password for access to image upload FTP User ID for access to image upload FTP The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Owner code for image upload FTP The current Sales Balance The current Sales Count Flag that indicates whether check truncation / conversion will occur. This is a unique identifier assigned by the merchants bank or processor that identifies the merchant. It will be in the format: site idlocation idrule set , where site id can be from 1 to 5 characters (numeric), location id can be from 1 to 6 characters (numeric), and rule set can be from 1 to 4 characters (numeric). Example: 78-123456-9999 (dashes are necessary; no spaces). The current Voids Balance The current Voids Count

Index

Integer

OwnerCode SalesBalance SalesCount Truncation

String String String Boolean

TruncationTID

String

VoidsBalance VoidsCount

String String

PccRMRSSetup Methods
Method Name CreateRMRSExtFile Returned Value None Description - PccRMRSSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

388

PCCSMTSSetup
This class contains Smart Transaction Systems extended information for the current instance of PCCharge. This is a Public Not Creatable class. PCCSMTSSetup Properties
Property Name BType Canceled Data Type String Boolean String Description - PCCSMTSSetup Properties The merchants business type. Valid values: R Retail / Other F Restaurant Used internally Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The system/socket port used to connect to the processor when processing via TCP/IP. Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required This is a unique identifier assigned by the merchants bank or processor that identifies the merchant. This value may or may not be required. The merchant should check with their bank or processor. The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP.

Connect

DialBackup

Boolean

ExpansionFactor

String

Index

Integer

Port

String

RequireServerID

String

TerminalID

String

TimeOut

String String

URL

389

PCCSMTSSetup Methods
Method Name Returned Value Description - PCCSMTSSetup Methods Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced.

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

390

PCCSPSGiftSetup
This class contains Secure Payment Systems Gift extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PCCSPSGiftSetup Properties
Property Name BType Canceled Data Type String Boolean String Description - PCCSPSGiftSetup Properties N/A Used internally Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The system/socket port used to connect to the processor when processing via TCP/IP. Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required This is a unique identifier assigned by the merchants bank or processor that identifies the merchant. This value may or may not be required. The merchant should check with their bank or processor. The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP.

Connect

DialBackup

Boolean

ExpansionFactor

String

Index

Integer

Port

String

RequireServerID

String

TerminalID

String

TimeOut

String String

URL

391

PCCSPSGiftSetup Methods
Method Name Returned Value Description - PCCSPSGiftSetup Methods Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced.

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

392

PccSPSSetup
This class contains Secure Payment Systems Check extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccSPSSetup Properties
Property Name Canceled DLLimit FTPAddress FTPPassword FTPUser Guarantee Data Type Boolean String String String String Boolean Description - PccSPSSetup Properties Used internally The limit of the transaction amount after which a drivers license number is required. Format: Dollars. FTP address for check image upload. Password for access to image upload FTP User ID for access to image upload FTP Flag that indicates whether check guarantee will occur. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The system/socket port used to connect to the processor when processing via TCP/IP. The current Sales Balance The current Sales Count The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds N/A The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The current Voids Balance The current Voids Count

Index

Integer

Port SalesBalance SalesCount TimeOut Truncation URL VoidsBalance VoidsCount

String String String String Boolean String String String

PccSPSSetup Methods
Method Name CreateSPSExtFile Returned Value None Description - PccSPSSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

393

Method Name

Returned Value

Description - PccSPSSetup Methods Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced.

ShowAdvanced

Boolean

394

PccSVSISetup
This class contains Stored Value Systems Gift extended information for the current instance of PCCharge. This is a Public Not Creatable class. PccSVSISetup Properties

Property Name Canceled

Data Type Boolean

Index

Integer

Division Store CurrencyCode Timeout Terminal

String String String String String

AllowTips

String

RoutingIndicator

String

UseTestSystem

String

Description - PCCSVSISetup Used internally The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Assigned by the merchant. Identifies the division at which the card is being accepted. Assigned by the merchant. Uniquely identifies the location at which the card is being accepted. Indicates which currency to be used with the card. Determines how long PCCharge will wait for an authorization to timeout. Assigned by the merchant. Identifies the terminal where the transaction took place. Indicates if tips are supported by the merchant: Valid Values: 0 No Tips Allowed 1 Tips Allowed Six character range of values in the dial-up service providers POS routing tables provided by the processor. Indicates if transaction be sent to the development system. Valid values: 0 Do not send to development system 1 Send to development system

395

PccSVSISetup Methods
Method Name Returned Value PCCSVSISetup Methods Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the enduser using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

396

PCCVisaSetup
This class contains TSYS/Vital extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccVisaSetup Properties
Property Name ABA Data Type String Description - PccVisaSetup Properties The ABA number identifies the merchant to a direct debit switch. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 9 digits The Agent Bank Number issued by the merchants bank or processor. This parameter is used to identify a specific agent entity of the member bank or processor. Length: 6 digits. Example: 111111 N/A N/A The Current batch number. This value is incremented by the processor after each successful settlement. The Bank Identification Number issued by the merchants bank or processor. The BIN identifies the Merchant Service Provider that signed up the merchant. Length: 6 digits. Example: 999995 The merchants business type. Valid values: 0 Retail 1 Mail order 2 Electronic Commerce 4 Restaurant Used internally The Merchant Category Code assigned by the merchants bank or processor. This parameter is used to identify the merchants industry classification. Length: 4 digits. Example: 5999 The Agent Chain Number issued by the merchants bank or processor. This parameter is used to identify a specific chain of an agent organization. Length: 6 digits. Example: 000000 The merchants postal/zip code as assigned by the merchants bank or processor. Length: 5 or 9 digits. Example: 314193262 Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP The Country Code assigned by the merchants bank or processor. This parameter is used to identify the merchants country location. Length: 3 digits. Valid Value: 840 U.S.

Agent AuthPrimaryPort AuthPrimaryURL Batch

String String String String String

Bin

BType

Integer

Canceled Category

Boolean String

Chain

String String

City

Connect

Integer

Country

String

CreditTermType

Cardholder-Activated Terminal Type. This setting determines which Cardholder Identification Code that will be passed to the processor. This value determines the method used to authenticate the identify of the cardholder for the transaction. CreditTerminalTy Valid values: pe 0 Non-Terminal 1 Self-Serve Limited Amount 2 Self-Serve Terminal String The Merchant Local Telephone Number. Length: 11 characters. Format: NNNnnnnnnn where NNN is the area code and nnnnnnn is the telephone number. The hyphen is required. Example: 800-7259264 The Currency Code assigned by the merchants bank or processor. This parameter is used to identify the merchants settlement currency. Length: 3 digits. Valid Value: 840 U.S. Dollars The Bank Identification Number issued by the merchants bank or processor. The BIN identifies the Merchant Service Provider that signed up the merchant. Length: 6 digits. Example: 999995

CSPhone

CurrencyCode

String

DebitBIN

String

397

Property Name

Data Type

Description - PccVisaSetup Properties

DebitTermType

Cardholder-Activated Terminal Type. This setting determines which Cardholder Identification Code that will be passed to the processor. This value determines the CreditTerminalTy method used to authenticate the identify of the cardholder for the transaction. pe Valid values: 0 Non-Terminal 1 Automated Dispensing Boolean String String Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup N/A The ABA number identifies the merchant to a direct debit switch. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 9 digits The Bank Identification Number issued by the merchants bank or processor. The BIN identifies the Merchant Service Provider that signed up the merchant. Length: 6 digits. Example: 999995 The Food and Consumer Identifier identifies the Merchant as being certified and approved to accept Food Stamps. Applicable to EBT transactions only. Length: 0 to 7 characters. The Reimbursement Attribute designates the Reimbursement Fee applicable to a transaction. Applicable for Debit/EBT transactions. This value is assigned to the merchant by their Merchant Services Provider or Processor. Length: 1 character. The Merchant Settlement Agent Number identifies the merchant settling agent. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 4 characters The Sharing Group contains a listing of direct debit and EBT networks that may be accessed. This value is provided to the merchant by their Merchant Services Provider or Processor. The values must correspond to one of the Visa assigned direct debit network types. This data is part of the VisaNet direct debit data. Length: 1 to 30 characters.

DialBackup

DID ebtABA

ebtBIN

String

ebtFCSID

String

ebtReimbursement

String

ebtSettleAgent

String

ebtSharingGroup

String

EBTTermType

Cardholder-Activated Terminal Type. This setting determines which Cardholder Identification Code that will be passed to the processor. This value determines the DebitTerminalTyp method used to authenticate the identify of the cardholder for the transaction. e Valid values: 0 Non-Terminal 1 Automated Dispensing String Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. Express Pay flag. This setting only applies if the Business Type is set to retail. If this flag is set to TRUE and the amount of the transaction is less than the FloorLimit amount, PCCharge will not authorize the transactionit will only place the transaction in the open batch. Express Pay is usually used in a quick service environment with small ticket items. Note: Using Express Pay will increase transaction processing costs. The floor limit amount. This setting is only applicable if the Business Type is set to retail. The floor limit is the maximum transaction amount that will be accepted by PCCharge when processing an Express Pay transaction The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP.

ExpansionFactor

ExpressPay

Boolean

FloorLimit

String

Index

Integer

IP

String

398

Property Name

Data Type

Description - PccVisaSetup Properties Language indicator. Length: 2 digits. Valid Values: 00 English 01 Spanish 02 Portuguese 03 Reserved for Irish 04 Reserved for French 05 Reserved for German 06 Reserved for Italian 07 Reserved for Dutch The Merchant Location Number provides additional information on the location of the merchant. Length: 5 characters. Example: 00001 Note: This value should be 00001 unless otherwise specified by the merchants bank or processor. Specifies the maximum number of transactions per batch that PCCharge will send to the processor. If the number of transactions to be settled is greater than the number specified in this setting, PCCharge will split the batch into multiple batches, each containing (at most) the number transactions specified in this setting. The batches are then sent to the processor one at a time. Example: A merchant has 250 transaction to settle and the MaxBatchSize is set to 100. PCCharge will send two 100-transaction batches and one 50-transaction batch. Max Value: 999 N/A Flag that indicates to enable or disable the Commercial / Purchasing card fields (Tax and Customer code) in the PCCharge GUI. TRUE Enable fields FALSE Disable fields Primary phone number for settlement. If this value is set and Dial-up modem is the communication method, PCCharge will attempt to settle transactions using this phone number rather than the authorization phone number. Secondary phone number for settlement. If this value is set and Dial-up modem is the communication method, PCCharge will attempt to settle transactions using this phone number rather than the authorization phone number. The system/socket port used to connect to the processor when processing via TCP/IP. The Reimbursement Attribute designates the Reimbursement Fee applicable to a transaction. Applicable for Debit/EBT transactions. This value is assigned to the merchant by their Merchant Services Provider or Processor. Length: 1 character. Indicates whether PCCharge will require a Server ID during gratuity-related restaurant transactions. Consult the section Restaurant Transactions for more information (see page 69). Valid Values: 0 Server ID not required 1 Server ID required The Merchant Settlement Agent Number identifies the merchant settling agent. Applicable for Debit/EBT transactions. This value is provided to the merchant by their Merchant Services Provider or Processor. Length: 4 characters N/A N/A N/A N/A N/A N/A N/A The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Sharing Group contains a listing of direct debit and EBT networks that may be accessed. This value is provided to the merchant by their Merchant Services Provider or Processor. The values must correspond to one of the Visa assigned direct debit network types. This data is part of the VisaNet direct debit data. Length: 1 to 30 characters. The Store Number assigned by the merchants bank or processor. This parameter is used to identify a specific merchant store location. Length: 4 digits. Example: 0011

Language

String

Location

String

MaxBatchSize

String

MCReversal

Boolean Boolean

PCard

Phone1

String

Phone2

String String String

Port

Reimbursement

RequireServerID

String

SettleAgent SettleConnect SettleDialBackUp SettleMaxBlockCount SettleMaxBlockSize SettlePrimaryPort SettlePrimaryURL SettleTCP SettleTimeOut

String String String String String String String Boolean String

SharingGroup

String

Store

String

399

Property Name Terminal TID TimeOut

Data Type String String String

Description - PccVisaSetup Properties The Terminal Number assigned by the merchants bank or processor. This parameter is used to identify a specific store terminal. Length: 4 digits. Example: 9911. N/A The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Time Zone Differential as assigned by the merchants bank or processor. This value provides the standard local time zone differential from Greenwich Mean Time (GMT). Length: 3 digits. Valid Values: 705 Eastern 706 Central 707 Mountain 708 Pacific Note: Replace the leading 7 with a 1 if Daylight Savings is not observed. Example: 107 Arizona N/A N/A Indicates whether VISA reversals will be processed.

TimeZone

String

URL URL2 VSReversal

String String Boolean

400

PccVisaSetup Methods
Method Name Returned Value Description - PccVisaSetup Methods Used internally Used internally Used internally Used internally Used internally Validates that each configuration field has been entered. Returns FALSE if any of the fields are left blank. Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced. Shows a GUI form that allows the end-user to enter Debit configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowDebit. Shows a GUI form that allows the end-user to enter EBT configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowEBT.

CreateVisaAdvanceFil None e CreateVisaDebitExtFi None le CreateVisaEBTExtFile None CreateVisaExtFile None CreateVisaIPNExtFile None IsExtendedInfoValid Boolean

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

ShowDebit

Boolean

ShowEBT

Boolean

401

PccVLNKSetup
This class contains ValueLink extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccVLNKSetup Properties
Property Name AltMerchNum Data Type String Description - PccVLNKSetup Properties Alternate merchant ID number. Recommended use: merchant designated store/location number. The merchants business type. Valid values: 0 Retail 1 Restaurant 2 Electronic Commerce Used internally Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP Percent by which restaurant-based transactions will be incremented during gratuityrelated transactions. This setting only applies when transactions are processed using the PCCharge GUI. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. Flag that indicates whether to simulate Pre-/Post-Auth process Flag the indicates whether the Clerk/Server ID is required when processing gift transactions Valid values: 0 Clerk ID not required 1 Clerk ID required Flag that indicates whether to allow split-tender scenario The Terminal Number assigned by the merchants bank or processor. This parameter is used to identify a specific store terminal. Length: 4 digits.

BType

String

Canceled

Boolean Integer

Connect

ExpansionFactor

String

Index

Integer

PreAuth

Boolean

RequireClerkID

String

SplitTender TerminalID

Boolean String

PccVLNKSetup Methods
Method Name CreateVLNKExtFile Returned Value None Description - PccVLNKSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show.

Load

Boolean

Save

Boolean

Show

Boolean

402

Method Name

Returned Value

Description - PccVLNKSetup Methods Shows a GUI form that allows the end-user to enter extended or advanced Gift Card configuration information such as the business type, communication method, or other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowGC.

ShowGC

Boolean

403

PccVTECSetup
This class contains Valutec extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccVTECSetup Properties
Property Name Canceled CashierFlag Data Type Boolean String Integer Boolean String Integer Boolean String String Description - PccVTECSetup Properties Used internally Used internally Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP N/A Used internally Indicates method of connection to processor when processing gift cards. Valid values: 0 Dial-up 1 TCP/IP N/A The system/socket port used to connect to the processor when processing via TCP/IP. The Internet Settlement Timeout Value. If GiftDialBackup is set to TRUE, GiftSettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds The Internet Authorization Timeout Value. If GiftDialBackup is set to TRUE, GiftTimeOut determines how long PCCharge will wait for a gift card transaction to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The merchants business type. Valid values: 1 Retail 2 Restaurant The merchant card assigned by the merchants bank or processor. Length: 10 digits. Used internally Used internally Used internally Used internally Used internally The system/socket port used to connect to the processor when processing via TCP/IP. Used internally Used internally Used internally Used internally Used internally

Connect

DialBackup ExpDateFlag

GiftConnect

GiftDialBackup GiftPort

GiftSettleTimeOut

GiftTimeOut

String String

GiftURL

Index

Integer

Industry

String String String String String String String String String String String String String

MerchCardNum ModeFlag Password1 Password2 Password3 PasswordFlag Port Receipt1 Receipt2 Receipt3 Receipt4 ReceiptFlag

404

Property Name SettleTimeOut

Data Type String

Description - PccVTECSetup Properties The Internet Settlement Timeout Value. If DialBackup is set to TRUE, SettleTimeOut determines how long PCCharge will wait for a settlement operation to time out before attempting the settlement via dial Format: Seconds Flag that determines whether split tender is enabled. Valid values: 0 Split Tender disabled 1 Split Tender enabled The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds Used internally Used internally The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP.

SplitTender

String

TimeOut TipFlag TipPercent URL

String String String String

PccVTECSetup Methods
Method Name Returned Value Description - PccVTECSetup Methods Used internally Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter Advanced configuration information such as the communication method and other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowAdvanced. Shows a GUI form that allows the end-user to enter extended or advanced Gift Card configuration information such as the business type, communication method, or other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowGC.

CreateVTECAdvanceFil None e CreateVTECExtFile None

Load

Boolean

Save

Boolean

Show

Boolean

ShowAdvanced

Boolean

ShowGC

Boolean

405

PccWRLDSetup
This class contains World extended information for the current instance of PCCharge. This is a Public Not Creatable class.

PccWRLDSetup Properties
Property Name Canceled Data Type Boolean Integer Description - PccWRLDSetup Properties Used internally Indicates method of connection to processor. Valid values: 0 Dial-up 1 TCP/IP Flag that indicates whether to use the backup dial connection if the Internet connection is not available. Value Values: TRUE Use Dial-Up modem for Backup FALSE Do not us Dial-Up modem for Backup The Merchant Number index. If Index is set to a value greater than 0, the tid.pcc file will be accessed and the merchant number at that index in the file will be used. Index should be set prior to calling the Load, Save, or Show methods. The index of the merchant number is determined by the order that it was added to PCCharge. For example, the first merchant number added to PCCharge will have an index of 1, the second, 2, etc. The system/socket port used to connect to the processor when processing via TCP/IP. The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. Flag the indicates whether the Clerk ID is required when processing gift transactions Valid values: 0 Clerk ID not required 1 Clerk ID required Used internally The Secondary Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP. The Internet Authorization Timeout Value. If DialBackup is set to TRUE, TimeOut determines how long PCCharge will wait for an authorization to time out before attempting the transaction via dial Format: Seconds The Hostname, URL, or IP address used to connect to the processor when processing via TCP/IP.

Connect

DialBackup

Boolean

Index

Integer

Port PrimaryURL

String String

RequireClerkID

String

SecondaryIP SecondaryURL

Boolean String String String

TimeOut

URL

406

PccWRLDSetup Methods
Method Name CreateWRLDExtFile Returned Value None Description - PccWRLDSetup Methods Used internally Loads the configuration data from the configuration file(s) and populates the various setup properties with the data. The data in the properties can then be modified programmatically or can be modified by the end-user using the GUI form that is displayed by the Show method. If the data is modified programmatically, invoke the Save method to update the configuration file(s) with the new values. After calling Load, TRUE is returned if successful, otherwise FALSE is returned. Note: Set the Index property prior to calling Load. Updates the configuration file(s) with the values currently stored in the various setup properties. Returns TRUE if successful, FALSE otherwise. Shows a GUI form that allows the end-user to enter or modify configuration information. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling Show. Shows a GUI form that allows the end-user to enter extended or advanced Gift Card configuration information such as the business type, communication method, or other related settings. Returns TRUE if successful, FALSE otherwise. Note: If the end-user clicks OK after modifying configuration data, the data will be saved automatically. If the end-user clicks Cancel, the data will not be saved. Note: Set the Index property prior to calling ShowGC.

Load

Boolean

Save

Boolean

Show

Boolean

ShowGC

Boolean

407

Classes No Longer Supported / Internal Use Classes

The following list contains various PCCharge OLE/COM classes that are either: 1) Used internally by PCCharge 2) No longer supported by PCCharge In either case, integrators should not attempt to programmatically access the properties, methods, or events contained in any of following classes. These classes will remain exposed for backwards compatibility purposes. clsPurgeDatabase PccASISetup PCCBBGFSetup PccBMONSetup PccCallBack PccCardReader PccCcrdTcpAuth PccCCRDSetup PccCheckReader PccConnect PccDataHandler PccDiscDialSetup PccEcom PCCEnCheckMSR PccENCNAuth PccENCNSetup PccEXPRSetup PccFraud PccFHAWSetup PccFTMSSetup PccGSARAuth PccIndeterminateBatch PccIPGSSetup PccISDNSetup PccMAPPSetup PccMDISetup PccMPSSetup PccMVRKSetup PccNovusSetup PccOfflineTrans pccPenWare PccPrivateLabel PccRBOCDebit PccRBOCSetup PccReportPrinter PccResponse PccSSLTCPAuth PccSystem PccTelmSetup PccTMHSetup pccTran PccUsers PccVerification PccVTECAuth Xtimer

408

File Method
Introduction
As of PCCharge version 5.6 and above, PCCharges primary message format is XML. The XML message format has replaced the legacy INP message format so that integrators will not be limited to fixed length files for integration. All of PCCharges integration methods support the XML message format and also support backward compatibility so that integrations using the INP message format will still be able to process transactions using that format. However, all new features that are added to PCCharge will be supported only by the XML message format. All references to the INP message format have been removed from this manual. Although it is highly recommended that all new (and existing) integrations take advantage of the XML message format, older copies of the DevKit that outline the INP message format are available for integrators upon request. Contact VeriFone, Inc. at 800-725-9264 to request a copy of an older DevKit manual.

File Method Integration

The File Method allows integrators to perform integration functions using flat text files. The files can be created on a machine running any operating system (Windows, UNIX, Mac, etc.). To process transactions via the File Method, the application should: 1. Check if SYS.PCC exists in the PCCharge directory. If it does, there is an error state. The number in the first byte of the file indicates the error type. The number is an error code listed in the DevKit Constants section (see page 94). If the file does not exist, then PCCharge is running and ready to receive transactions. 2. Write the transaction information to a file in the XML message format (ASCII text) using the file layouts described in this section. 3. Name the file <user name>.inx where <user name> is a user that is registered in PCCharge*. 4. Place the <user name>.inx file into the PCCharge directory. The transaction will now be processed by PCCharge. 5. Wait for <user name>.oux to appear in the PCCharge directory. 6. Wait for <user name>.pro to be deleted from the PCCharge directory. 7. Read the values from <user name>.oux. RESULT and AUTH_CODE tags. The most important information is returned in the

8. Delete <user name>.oux. It is extremely important to delete this file. Not deleting the .oux file could cause the clients to read the same results at a later time. If PCCharge is set up with an unlimited user license, <user name> can also be any 8 character alphanumeric name. The user name must be in DOS file format, no spaces. Also, the filename must be the same as the value of that file's USER_ID tag.

409

Note: PCCharge is a single-threaded application. This means that PCCharge can only process one transaction at a time. Keep in mind that no two transaction requests can be submitted at the same time with the same user name.

410

File Layout Specifications

In order for a request to be processed, the request file (.inx) must open and close with an XML_FILE tag and each request within the file must open and close with an XML_REQUEST tag. Currently, PCCharge will only support one request per file; this may change in the future. Within the XML_REQUEST tag put the tags and values of all the data that will be needed to process the transaction. Once the request has been processed, a response file (.oux) will be returned. The response file, like the request file, will open with an XML_FILE tag and the transaction response will be wrapped within the XML_REQUEST tag.

XML Data Validation

PCCharge provides request file data validation for integrators implementing the File Method. PCCharge uses the Microsoft XDR (XML-Data Reduced) schema to provide this data validation. The file used by PCCharge to implement the data validation is called stnd.xdr. This file is installed by PCCharge and resides in the \DTD folder within the PCCharge directory. In order to perform XDR validation on the XML request: 1. 2. 3. 4. The XML_FILE tag must reference the stnd.xdr file. The tags submitted must be in the order that they appear in the stnd.xdr file. Each tag must appear only once. The content for each tag must be text only.

The following is an example of request that will be validated:

<XML_FILE xmlns="x-schema:.\dtd\stnd.xdr"> <XML_REQUEST> <USER_ID>User1</USER_ID> <COMMAND>1</COMMAND> <PROCESSOR_ID>VISA</PROCESSOR_ID> <MERCH_NUM>999999999911</MERCH_NUM> <ACCT_NUM>5424180279791765</ACCT_NUM> <EXP_DATE>1208</EXP_DATE> <MANUAL_FLAG>0</MANUAL_FLAG> <TRANS_AMOUNT>1.00</TRANS_AMOUNT> </XML_REQUEST> </XML_FILE>

Notice that the XML_FILE tag references the path of the stnd.xdr file. Also, the tags are in the same order that they appear in the stnd.xdr file. This file will be validated successfully. If a request file does not pass validation, PCCharge will return an Incomplete Trans error. The following is an example of a response that was returned because validation failed:
<XML_FILE> <XML_REQUEST> <USER_ID>User1</USER_ID> <RESULT>Error</RESULT> <AUTH_CODE>Incomplete Trans</AUTH_CODE> </XML_REQUEST> </XML_FILE>

411

Many integrators do not wish to be limited by the requirements of XDR validation; specifically, the mandated order of the tags in the request file. If this is the case, simply remove the reference to the validation file, stnd.xdr, from the XML_FILE tag. The tags inside <XML_REQUEST> can now be placed in any order that the integrator sees fit. The following is an example of request file that will not be validated but will still be processed successfully by PCCharge:
<XML_FILE> <XML_REQUEST> <ACCT_NUM>5424180279791765</ACCT_NUM> <EXP_DATE>1208</EXP_DATE> <MANUAL_FLAG>0</MANUAL_FLAG> <TRANS_AMOUNT>1.00</TRANS_AMOUNT> <PROCESSOR_ID>VISA</PROCESSOR_ID> <MERCH_NUM>999999999911</MERCH_NUM> <COMMAND>1</COMMAND> <USER_ID>User1</USER_ID> </XML_REQUEST> </XML_FILE>

Notice that the XML_FILE tag does not reference the stnd.xdr file. Note: Regardless of whether PCCharge validates the request data using the stnd.xdr file, the application should always perform input validation according to the API specifications prior to passing requests to PCCharge.

412

Credit File Layouts

This section describes the tags required to process credit card transactions.

Credit Input File (.inx)

Tag Data Type Description - Credit Input File (.inx) 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 more information on user names, consult the Multi-User Support section (see page 50). Note: The value passed in USER_ID must match the name of the .inx file. For example: <USER_ID>User2</USER_ID> and User2.inx. The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 the Processing Company Codes section (see page 101). The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Credit Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. The credit card number that will be used when processing the transaction. Max Length: 20 characters. Example: 5424180279791765 The expiration date associated with the credit card number that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Flag that indicates whether the transaction was manually entered or swiped. If the transaction was swiped, the TRACK_DATA property must also be set. Valid values: 0 = manual transaction, 1 = swiped transaction 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 place holder must be sent as well. Example: 0.50. 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, see page 63). The REFERENCE property does not need to be set if the PostAuthorization completes a standard Pre-Authorization using the TroutD value of the Pre-Authorization. See the section Follow On Transactions for more information (see page 58). 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. The track II data captured from the magnetic strip of the credit card. The track II data is required to ensure the lowest per-transaction rate from the processing company when performing swiped transactions (Retail and Restaurant). Sending the track II data is not allowed if the merchant's industry type is MOTO or eCommerce. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in.

USER_ID **

String

COMMAND

String

TROUTD

String

PROCESSOR_ID ***

String

MERCH_NUM ***

String

ACCT_NUM

String String

EXP_DATE

MANUAL_FLAG

String

TRANS_AMOUNT

String

REFERENCE

String

TRACK_DATA

String

413

Tag

Data Type

Description - Credit Input File (.inx) 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. The credit plan numbers are established by the processor CITI for each merchant, they define the type of Disclaimer to print on receipts. This information will vary from merchant to merchant. 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. 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. 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 flags must also be set to achieve the best processing rates. 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 The cardholder's zip code. The Zip property is used for address verification. Max Length: 9 digits. Address verification can only be performed on nonswiped transactions. 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. The cardholder's billing street address. The Street property is used for address verification. Address verification can only be performed on nonswiped 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 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_NUM is required to qualify for the lowest transaction rates. Note: When using NOVA, ticket numbers can only be alphanumeric, no hyphens. The cardholders name. Max Length: 20 characters. 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 (see page 69) 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. 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.

CUSTOMER_CODE

String

CREDIT_PLAN_NUMBER

String

TAX_AMOUNT

String

PRINT_RECEIPTS_FLAG

String

PERIODIC_PAYMENT_FLAG

String

OFFLINE_FLAG

String

ZIP_CODE

String

STREET

String

TICKET_NUM

String

CARDHOLDER

String

MCSN

String

MCSC

String

414

Tag

Data Type

Description - Credit Input File (.inx) 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line. 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 nonswiped transactions. 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) 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 ITEM_ID is set to 00010002000300040005, it stores 5 item IDs (0001, 0002, 0003, 0004, and 0005). These numbers must be obtained from Chase Paymentech. Only required for Voyager cards, dependant on Restriction Code. Four to six digits. Note: Only used for Pre-Authorization transactions The odometer reading. Only required for Fleet One (7 digits), Voyager (7 digits), and Fuelman (6 digits) cards. Driver identification field. Only required for Wright Express, Voyager and Fleet One cards. Driver personal identification number. Only required for Fuelman cards. Note: Only required for the processor NBS. This is the total dollar amount for PRODUCT_DETAIL_PRODUCT_CODE_XX 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 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. Note: Only required for the processor NBS. This is the number of items for PRODUCT_DETAIL_PRODUCT_CODE_XX. Currently, PCCharge will support 0 1 10. Note: Only used for the processor NBS. This is the unit price for PRODUCT_DETAIL_PRODUCT_CODE_XX. This is only used for Fleet One and Fuelman. Currently, PCCharge will support 01 10. For use with Restaurant transactions only. The actual gratuity amount for a Sale with Gratuity (action code 14) , Gratuity (action code 13) , or PostAuthorization (action code 5) transaction. See the section Restaurant Transactions (see page 69) for more information.

MULTI_FLAG

String

CVV2

String

PRESENT_FLAG

String

ITEM_ID

String

ID_NUMBER ODOMETER DRIVER_ID DRIVER_PIN

String String String String

PRODUCT_DETAIL_AMOUNT_XX

String

PRODUCT_DETAIL_COUNT

Stringq

PRODUCT_DETAIL CODE_XX

String

PRODUCT_DETAIL_QUANTITY_XX

String

GRATUITY_AMNT

String

415

Tag

Data Type

Description - Credit Input File (.inx) 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 GRATUITY_AMNT_EST is populated, PCCharge will submit the sum of the values in the TRANS_AMOUNT and GRATUITY_AMNT_EST fields for authorization. If the transaction is authorized, only the value in the TRANS_AMOUNT field will be placed in the PCCharge settlement file (if running a Sale). By using the GRATUITY_AMNT_EST, 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 place holder must be sent as well. See the section Restaurant Transactions (see page 69) 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. The type of commercial card being submitted. See the section Commercial Card Transactions (see page 65) for more information. Max Length: 1 character Valid values: B Business P,L,G -- Purchase C Corporate F Fleet 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. Max Length: 23 bytes American Express Description data. Additional description or information about merchandiseif populated, should be printed on the receipt. Note: Only used for Retail transactions when using AMEX direct settlement or TSYS . Max Length: 40 bytes This field is optional and should only be provided if the transaction will be settled directly with Amex or TSYS . American Express Description data. Additional description or information about merchandiseif 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 . American Express Description data. Additional description or information about merchandiseif 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 . American Express Description data. Additional description or information about merchandiseif 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 . Flag indicating whether a Voice Authorization transaction should be stored. This flag should only be submitted when performing a Post-Authorization transaction (action code 5) that includes an authorization code from the voice operator. For more information on stored Voice-Authorizations, see page 63. Valid Value: 1 - Store the Voice Authorization transaction.

GRATUITY_AMNT_EST

String

CMRCL_FLAG

String

AMX_CHARGE_DESCRIPTION

String

AMX_DESCRIPTION_1

String

AMX_DESCRIPTION_2

String

AMX_DESCRIPTION_3

String

AMX_DESCRIPTION_4

String

TRANS_STORE

String

416

Tag

Data Type

Description - Credit Input File (.inx) The number of seconds after which a timeout error will be returned from PCCharge. The count will start when the transaction is submitted to PCCharge. An error will be returned if the transaction has not finished processing when the time period expires. It is highly recommended that integrators review the section Timeouts (see page 47). Note: This tag only works when using the TCP Interface. The Authorization code. This value is returned by the issuing bank and should only be set in a transaction request 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, see page 63). 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. See the section Follow On Transactions for more information (see page 58). 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. 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. For Chase Paymentech Only EID Number Only valid for Visa debit and credit transactions. It is used to indicate the transaction is being ran for payment of a bill (ultilty, monthly gym dues, etc.) Valid values: 0 Non-Bill payment transaction 1 Bill payment transaction 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. Set to 1 if card information was read from RFID (Radio Frequency Identification) device. If card was read from from RFID, track data must be populated and manual flag must be set to 1. Set to 0 otherwise. Only required for Wright Express cards (5 digits) and Voyager cards (8 digits). Note: Required for both manual and swiped transactions.

TXN_TIMEOUT

String

AUTH_CODE

String

TAX_EXEMPT

String

DEST_ZIP_CODE

String

ITEM_ID

String

BILLPAY

String

RESTRICTION_CODE

String

RFID

String String

VEHICLE_ID

These properties are the minimum required to process a Sale or Pre-Authorization transaction. ** 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 (see page 50). 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_ID and MERCH_NUM 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. Consult the Multi-Merchant Support section (see page 56) for more information on the Use Default Processor option. In addition, PROCESSOR_ID and MERCH_NUM should not be set when doing follow-on transactions. Refer to the section Follow On Transactions (see page 58) for more information.

417

Charge Output File (.oux)

Tag USER_ID Data Type Description - Charge Output File (.oux) String String Returns the User name that is associated with the transaction. This value is echoed back from the original transaction. The User name will be in DOS file format, max 8 characters. Returns the merchant number that was specified in the MerchantNumber property. 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. See the section Follow On Transactions (see page 58) for more information. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. The amount due. Only used for pre-paid cards with NOVA. 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. The authorized amount of the transaction. Only used for pre-paid cards with NOVA. Returns the PrePaid card balance. Only for pre-paid credit cards with NOVA. Returns the available balance on pre-paid debit cards. Only for pre-paid debit cards with NOVA. 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. 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 the section DevKit Constants for a description of values that may be returned (see page 94) Only supported on Fleet One, this field contains miscellaneous additional text returned from host. Currently PCCharge will support GetAddText1GetAddText4. Note: Only supported on Fleet One. The product restriction code. The trace number returned from the processor. This value is not returned by all processing companies. Returns the date that the transaction was processed. This value is not returned by all processing companies. Returns the transaction reference number. This value is not returned by all processing companies. 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. 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. Returns the Transaction Item number or the number that is associated with the transaction in the settlement file. This value is not returned by all processing companies. Returns the transaction reference number from the processor. Only for prepaid credit cards with NOVA. Returns the active batch number for the transaction. This value is not returned by all processing companies.

MERCH_NUM

TROUTD

String

RESULT AMOUNT_DUE AUTH_CODE

String String String String String String

AUTH_AMOUNT CC_AVAIL_BALANCE DC_AVAIL_BALANCE

REFERENCE

String

AVS_CODE

String

ADD_TEXT RESTRICT_CODE TRACE_NUMBER TRANS_DATE

String String String String

TRANSACTION_REFERENCE_NUMBER String TICKET String

INTRN_SEQ_NUM

String

TRANS_ITEM_NUM

String

TRANSACTION_REFERENCE_NUMBER String TBATCH String

418

Tag TRANS_ID

Data Type Description - Charge Output File (.oux) String String Returns the Transaction Identifier that is returned from the processor. This value is not returned by all processing companies. Returns the Transaction Indicator Code that is returned from the processor. The Transaction Indicator Code is a Validation code for VISA / MasterCard. This value is not returned by all processing companies. 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. Returns the Market Specific Indicator. This value indicates the transactions market segment. This value is assigned by the card associations and is not returned with all transactions. Returns the Retrieval reference number. This value is not returned by all processing companies Returns the POS entry mode that is associated with the transaction. This value is not returned by all processing companies. Returns the PS2000 indicator from the processor. This value is not returned by all processing companies. Returns the Time of the transaction. This value is not returned by all processing companies. Returns the Authorization Characteristics Indicator is that is provided by the card associations. This value is stored for settlement. Returns the response code that is provided by the processor. This value is not returned by all processing companies. Returns the record number of the transaction in the reversal file. Will return -1 if the processor doesn't support reversals. This value is not returned by all processing companies. Only used for the processor CITI private label cards. CITI private label cards will return the Receipt Disclaimer to be printed on the bottom of receipts based off of the Credit Plan Number. Returns the type of commercial card that was used for the transaction. This value is not returned by all processing companies. 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 the section DevKit Constants for a description of values that may be returned (see page 94) Returns a flag indicating whether the processor indicated whether the card was a Purchasing Card or not. This value is not returned by all processing companies. Valid values: 1 = Purchasing Card, 0 = Otherwise Returns the gratuity amount if one is associated with the transaction. This value is not returned by all processing companies. Returns the estimated gratuity if one is associated with the transaction. This value is not returned by all processing companies. Returns a numerical representation of the result of the transaction. Currently, this field is only used for a batch transaction. Returns the Commercial Card Flag. This indicates what type of Commercial card was used for the transaction. This value is not returned by all processing companies. Returns a one character identification code that identifies the network on which the transaction was approved. This value is not returned by all processing companies. 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. Returns a code that is used to verify the identity of the cardholder. Returns the entry method of the transaction. Returns a value indicating whether the goods sold were digital or physical in an e-commerce environment.

TICODE

IND

String

MSI

String String String String String String String String

RET PEM PS2000 TIM ACI PROC_RESP_CODE

REC

RECEIPT

String String

CMRCL_TYPE

CVV2_CODE

String

PURCH_CARD_TYPE

String String String String String

GRATUITY_AMNT GRATUITY_AMNT_EST RESULT_CODE

CMRCL_FLAG

NET_ID

String

AUTH_SRC_CODE CARD_ID_CODE ACCT_DATA_SRC ECOMM_GOODS_IND

String String String String

419

Debit File Layouts

This section describes the tags required to process debit transactions. When processing debit cards, a PINpad is required to allow the customer to enter their PIN. In addition, debit card information is always collected via a card swipe device, never via keyboard entry. Because of this, a card reader is also required. When processing U.S. debit card transactions, merchants have the option of allowing the customer to receive cash back on a transaction. For instance, the customer purchases $50 of products and wants $25 cash back, set the Amount to 50.00 and CashBack to 25.00. This will withdraw a total of $75 from the debit card account, $50 for the products and $25 for cash to give to the customer.

Debit Input File (.inx)

Tag Data Type Description - Debit Input File (.inx) 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 more information on user names, consult the Multi-User Support section (see page 50). Note: The value passed in USER_ID must match the name of the .inx file. For example: <USER_ID>User2</USER_ID> and User2.inx. The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 the Processing Company Codes section (see page 101). The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Debit Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. The Debit card number that will be used when processing the transaction. Max Length: 20 characters. Example: 5424180279791765 The expiration date associated with the Debit card number that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Set this property if there is an expiration date associated with the Debit card. Flag that indicates whether the transaction was swiped or manually entered. This property must be set to 1 (swiped) and the TRACK_DATA property must also be set. 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 place holder must be sent as well. Example: 0.50. The track II data captured from the magnetic strip of the card. The track II data is required. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in.

USER_ID **

String

COMMAND

String

TROUTD

String

PROCESSOR_ID ***

String

MERCH_NUM ***

String

ACCT_NUM

String

EXP_DATE

String

MANUAL_FLAG

String

TRANS_AMOUNT

String

TRACK_DATA

String

420

Tag

Data Type String

Description - Debit Input File (.inx) 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. 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: When using NOVA, ticket numbers can only be alphanumeric, no hyphens. The cardholders name. Max Length: 20 characters. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. This is the Gratuity Amount of the transaction. The number of seconds after which a timeout error will be returned from PCCharge. The count will start when the transaction is submitted to PCCharge. An error will be returned if the transaction has not finished processing when the time period expires. It is highly recommended that integrators review the section Timeouts (see page 47). Note: This tag only works when using the TCP Interface. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. The Shift ID. This value is optional. Format: Alphanumeric Max Length: 1 character. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the language that is indicated by the Language Code that is encoded in the track II data on the customers card. Valid Values: English or French (pass in the literal string) If a Key Serial Number is returned from the PINpad, this property should be populated with that number. If processing transactions with a PINpad using DUKPT encryption, this value is sixteen or twenty characters long (depending on the processors encryption). The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. If processing transactions with a Verifone SC5000 PINpad, set this property to the Chip Serial Number of the PINpad. The amount of cash back that the customer will receive. This amount is in addition to value entered in TRANS_AMOUNT property. For example, if the total amount of the sale is $10 and the customer has requested $5 cash back, TRANS_AMOUNT should be set to $10 and CASHBACK_AMNT should be set to $5. The CASHBACK_AMNT property should be formatted the same the TRANS_AMOUNT property. Max Length: 9 characters. Note: Some debit processors do not support the cash back feature. The encrypted PIN block that is retrieved from the PINpad. The PIN is provided to the processor for verification. Length: 16 characters. The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the MAC Block value returned by the PINpad. Only supported by Global Payments East (NDC) Canadian Debit and the Verifone SC5000 PINpad. Set this to the bank account type that the customer specified when entering transaction data into the PINpad. Valid Values: Chequing or Savings The Original Purchase Data. Used when performing a Debit Return with the processors TSYS, Heartland, Lynk, and NPC. This is the original transaction date. Format: DDMMhhmm Only valid for Visa debit and credit transactions. It is used to indicate the transaction is being ran for payment of a bill (ultilty, monthly gym dues, etc.) Valid values: 0 Non-Bill payment transaction 1 Bill payment transaction

PRINT_RECEIPTS_FLAG

TICKET_NUM

String

CARDHOLDER GRATUITY_AMNT

String String

TXN_TIMEOUT

String

SHIFT_ID

String

LANGUAGE_CODE

String

KEY_SERIAL_NUM

String

CASHBACK_AMNT

String

PIN_BLOCK

String

MAC_BLOCK

String

DEBIT_TYPE

String

ORIG_PURCH_DATA

String

BILLPAY

String

421

Tag REFERENCE

Data Type String

Description - Debit Input File (.inx) 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. Set to 1 if card information was read from RFID (Radio Frequency Identification) device. If card was read from from RFID, track data must be populated and manual flag must be set to 1. Set to 0 otherwise.

RFID

String

These properties are required to process a Debit Sale transaction. These properties are required to process a Canadian Debit Sale transaction using Global Payments East (NDC) and the SC5000 PINpad. ** 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 (see page 50). 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_ID and MERCH_NUM 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. Consult the Multi-Merchant Support section (see page 56) for more information on the Use Default Processor option. In addition, PROCESSOR_ID and MERCH_NUM should not be set when doing follow-on transactions. Refer to the section Follow On Transactions (see page 58) for more information.

Debit Output File (.oux)

Tag USER_ID Data Type String String Description - Debit Output File (.oux) Returns the User name that is associated with the transaction. This value is echoed back from the original transaction. The User name will be in DOS file format, max 8 characters. Returns the merchant number that was specified in the MerchantNumber property. 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. See the section Follow On Transactions (see page 58) for more information. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. 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. Returns the reference number associated with the transaction. 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. Returns the date that the transaction was processed. This value is not returned by all processing companies. 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. 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. Returns the Transaction Item number or the number that is associated with the transaction in the settlement file. This value is not returned by all processing companies. Returns the active batch number for the transaction. This value is not returned by all processing companies. The TRANS_ID field returns the Working key (15 + 1 from TICode) that was provided by the processor. This field is only used for Master Session encryption, which is only supported by NOVA.

MERCH_NUM

TROUTD

String

RESULT

String

AUTH_CODE

String

REFERENCE

String

TRANS_DATE

String String

TICKET

INTRN_SEQ_NUM

String

TRANS_ITEM_NUM

String String String

TBATCH

TRANS_ID

422

Tag TICODE TIM NET_ID AUX_RESP_CODE

Data Type String String String String

Description - Debit Output File (.oux) The TICODE field contains the last byte of the Working key that is provided by the processor. Returns the Time of the transaction. This value is not returned by all processing companies. Returns a one-character identification code that identifies the network on which the transaction was approved. When using the SC5000 PINpad, returns the ISO response code

423

Check File Layouts

This section describes the tags required to process check transactions.

Check Input File (.inx)

Tag Data Type Description - Check Input File (.inx) 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 more information on user names, consult the Multi-User Support section (see page 50). Note: The value passed in USER_ID must match the name of the .inx file. For example: <USER_ID>User2</USER_ID> and User2.inx. The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 the Processing Company Codes section (see page 101). The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Check Services Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. For Check, MICR, or Double ID: The account number that will be used when processing the transaction. Max Length: 20 characters. Flag that indicates whether the transaction was manually entered or swiped. Valid values: 0 = manual transaction, 1 = swiped transaction 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 place holder must be sent as well. Example: 0.50. 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. The check writers ZIP code. Max Length: 9 characters. Format: digits only. This value is required for COD transactions. Note: If submitting the 9-digit zip, do not include the dash. 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: When using NOVA, ticket numbers can only be alphanumeric, no hyphens. 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line.

USER_ID **

String

COMMAND

String

TROUTD

String

PROCESSOR_ID

String

MERCH_NUM

String

ACCT_NUM MANUAL_FLAG

String String

TRANS_AMOUNT

String

PRINT_RECEIPTS_FLAG

String

ZIP_CODE

String

TICKET_NUM

String

MULTI_FLAG

String

424

Tag

Data Type

Description - Check Input File (.inx) The number of seconds after which a timeout error will be returned from PCCharge. The count will start when the transaction is submitted to PCCharge. An error will be returned if the transaction has not finished processing when the time period expires. It is highly recommended that integrators review the section Timeouts (see page 47). Note: This tag only works when using the TCP Interface. 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. Valid Values: 0 = Personal, 1 = Business Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The first and last name of the customer. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The customers city. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. Passes the type of Check Reader that is being used. Currently only used by Telecheck and will only be set if TECK is the set processor. Cannot be configured in the PCCharge GUI. 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 The street address of the customer. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The raw MICR data from the bottom of the check. Used for conversion transactions. Valid Values: 15 = Valid read by MICR reader, 15I = Valid read by MICR reader with imaging capability, 9 = Manual only Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The state code of the state that issued the check writers drivers license. The state code is required for DL (Drivers License). Format: 2 characters. The drivers license number of the individual writing the check. Max Length: 20 characters. The drivers license is required for DL (Drivers License) transactions and when performing Double ID transactions. The parsed TrackII data from the drivers license. Note: Used only for processor TECK. Cannot be accessed in the PCCharge GUI. The Transit Routing Number / ABA number that will be used when processing the transaction. This value indicates which bank issued the check. Max Length: 9 characters. This value is required for MICR transactions and when performing Double ID transactions.

TXN_TIMEOUT

String

CASHBACK_AMNT

String

CHECK_TYPE CUSTOMER_NAME CUSTOMER_CITY

String String String

CHECK_READER_CODE

Enum

CUSTOMER_STREET MICR

String String String String String String

MICR_READER_STATUS

STATE

LICENSE DL_TRACK_II

ABA_NUM

String

425

Tag PHONE_NUM

Data Type String

Description - Check Input File (.inx) The phone number of the individual writing the check. Max Length: 7 digits. Format: digits only. The phone number is required for COD (Checks On Delivery). The date of birth of the check writer. Length: Exactly six characters. Format: MMDDYY. The birth date is required for DL (Drivers License) check transactions. The check number of the check that will be used when processing the transaction. Max Length: 10 characters. Manager Number The Cashier Number

DOB

String String String String

CHECK_NUM MANAGER_NUM CASHIER_NUM

Note: To perform Double ID, both the MICR and LICENSE fields must be populated. These properties are required, regardless of service type. ** 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 (see page 50). This section contains detailed information about user names and how they should be implemented. COD -- required for Checks-On-Delivery DL -- required for Drivers License MICR -- required for MICR

Check Output File (.oux)

Tag USER_ID Data Type String String Description - Check Output File (.oux) Returns the User name that is associated with the transaction. This value is echoed back from the original transaction. The User name will be in DOS file format, max 8 characters. Returns the merchant number that was specified in the MerchantNumber property. 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. See the section Follow On Transactions (see page 58) for more information. Only for TECK. Returns the Trace ID associated with the transaction. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. Returns the response from the processor which indicates the fee for returned checks. Note: Only used for the processor TECK Returns the response from the processor which displays a note for returned checks. Note: Only used for the processor TECK 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. 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. 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. Returns the response code that is provided by the processor. This value is not returned by all processing companies.

MERCH_NUM

TROUTD

String

TRANS_ID RESULT

String String String String String

RETURN_CHECK_FEE RETURN_CHECK_NOTE

AUTH_CODE

TICKET

String

INTRN_SEQ_NUM

String String

PROC_RESP_CODE

426

EBT File Layouts

This section describes the tags required to process EBT transactions. When processing EBT cards, a PINpad is required to allow the customer to enter their PIN. In addition, debit card information is always collected via a card swipe device, never via keyboard entry. Because of this, a card reader is also required. (Some EBT transactions can be manually entered). When processing EBT card transactions, merchants have the option of allowing the customer to receive cash back on a transaction. For instance, the customer purchases $50 of products and wants $25 cash back, set the Amount to 50.00 and CashBack to 25.00. This will withdraw a total of $75 from the EBT card account, $50 for the products and $25 for cash to give to the customer.

EBT Input File (.inx)

Tag Data Type Description - EBT Input File (.inx) 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 more information on user names, consult the Multi-User Support section (see page 50). Note: The value passed in USER_ID must match the name of the .inx file. For example: <USER_ID>User2</USER_ID> and User2.inx. The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 the Processing Company Codes section (see page 101). The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the EBT Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. The EBT card number that will be used when processing the transaction. Max Length: 20 characters. Example: 5424180279791765 The expiration date associated with the EBT card number that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Set this property if there is an expiration date associated with the EBT card. Flag that indicates whether the transaction was swiped or manually entered. This property must be set to 1 (swiped) for swiped EBT transactions. If the transaction was swiped, the TRACK_DATA property must also be set. If performing a manually keyed EBT transaction, such as a Force or Voucher, set this property to 0 (manually entered). 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 place holder must be sent as well. Example: 0.50.

USER_ID **

String

COMMAND

String

TROUTD

String

PROCESSOR_ID

String

MERCH_NUM

String

ACCT_NUM

String

EXP_DATE

String

MANUAL_FLAG

String

TRANS_AMOUNT

String

427

Tag

Data Type

Description - EBT Input File (.inx) The track II data captured from the magnetic strip of the card. The track II data is required for swiped EBT transactions. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in. 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. The ZIP_CODE stores the reference number from the original transactions. Some processor all a type of void and for these transactions a reference number must be provided. For Chase Paymentech EBT, the auth code goes in the zip field for voucher transactions. 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: When using NOVA, ticket numbers can only be alphanumeric, no hyphens. The cardholders name. Max Length: 20 characters. Indicates what type of EBT transaction will be performed. Valid Values: F Food stamp transaction; C Cash benefits transaction The number of seconds after which a timeout error will be returned from PCCharge. The count will start when the transaction is submitted to PCCharge. An error will be returned if the transaction has not finished processing when the time period expires. It is highly recommended that integrators review the section Timeouts (see page 47). Note: This tag only works when using the TCP Interface. For an EBT Post (Prior Auth Sale) or Force transaction: The Authorization code from the original voice authorization. If a Key Serial Number is returned from the PINpad, this property should be populated with that number. This value is only applicable for PINpads using DUKPT encryption. This value is sixteen or twenty characters long (depending on the processors encryption). The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. 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 debit processors do not support the cash back feature. The encrypted PIN block that is retrieved from the PINpad. The PIN is provided to the processor for verification. Length: 16 characters. The PCCharge DevKit provides several tools for retrieving data from PINpads. If the PCCharge integration method chosen doesnt support these tools or the tools do not support the PINpad being used, a direct interface to the PINpad must be written by the integrator. The voucher number for an EBT force transaction. The voucher is provided by the processor at the time of authorization and must be supplied to clear the voucher. Set to 1 if card information was read from RFID (Radio Frequency Identification) device. If card was read from from RFID, track data must be populated and manual flag must be set to 1. Set to 0 otherwise.

TRACK_DATA

String

PRINT_RECEIPTS_FLAG

String

ZIP_CODE

String

TICKET_NUM

String

CARDHOLDER EBT_TYPE

String String

TXN_TIMEOUT

String

AUTH_CODE

String

KEY_SERIAL_NUM

String

CASHBACK_AMNT

String

PIN_BLOCK

String

EBT_VOUCHER_NUM

String

RFID

String

These fields are required to process a transaction. ** 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 (see page 50). This section contains detailed information about user names and how they should be implemented.

428

EBT Output File (.oux)

Tag USER_ID Data Type String String Description - EBT Output File (.oux) Returns the User name that is associated with the transaction. This value is echoed back from the original transaction. The User name will be in DOS file format, max 8 characters. Returns the merchant number that was specified in the MerchantNumber property. 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. See the section Follow On Transactions (see page 58) for more information. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. 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. Returns the reference number associated with the transaction. 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. Returns the date that the transaction was processed. This value is not returned by all processing companies. 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. 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. Returns the Transaction Item number or the number that is associated with the transaction in the settlement file. This value is not returned by all processing companies. Returns the active batch number for the transaction. This value is not returned by all processing companies. The TRANS_ID field returns the Working key (15 + 1 from TICode) that was provided by the processor. This field is only used for Master Session encryption, which is only supported by NOVA. The TICODE field contains the last byte of the Working key that is provided by the processor. Returns the Time of the transaction. This value is not returned by all processing companies. Returns a one character identification code that identifies the network on which the transaction was approved. Returns the remaining balance on a Food Stamp card. This value is not returned by all processing companies. Returns the remaining balance on a Cash Benefits card. This value is not returned by all processing companies.

MERCH_NUM

TROUTD

String

RESULT

String

AUTH_CODE

String

REFERENCE

String

TRANS_DATE

String String

TICKET

INTRN_SEQ_NUM

String

TRANS_ITEM_NUM

String String String String String String String String

TBATCH

TRANS_ID

TICODE TIM NET_ID EBT_FOOD_BALANCE EBT_CASH_BALANCE

429

Gift File Layouts

This section describes the tags required to process Gift/Loyalty transactions.

Gift Input File (.inx)

Tag Data Type Description - Gift Input File (.inx) 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 more information on user names, consult the Multi-User Support section (see page 50). Note: The value passed in USER_ID must match the name of the .inx file. For example: <USER_ID>User2</USER_ID> and User2.inx. The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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. Review the section Follow On Transactions (see page 58) for important information on implementing TroutD support. 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 gift processors support ticket numbers. 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 the Processing Company Codes section (see page 101). The Merchant Number. This number is issued to the merchant by the Processor or the Merchant Services Provider. The value set in this property must match what is set up in the Gift Card Setup window of PCCharge. Max Length: 32 characters. This value can be alphanumeric. The gift card number that will be used when processing the transaction. Max Length: 20 characters. The expiration date associated with the gift card that will be processed. Must be exactly four characters long. Format: MMYY Example: 1208 Note: Most gift cards do not have an expiration date. Flag that indicates whether the transaction was manually entered or swiped. If the transaction was swiped, the TRACK_DATA property must also be set. Valid values: 0 = manual transaction, 1 = swiped transaction 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 place holder must be sent as well. Example: 0.50. For Valuelink (VLNK) Balance Adjustment: Format: +/DDDDD.CC. The track II data captured from the magnetic strip of the card.. Max Length: 40 characters. Example: 5424180279791765=08121011000001234567 Note: The characters that are appended to the beginning and ending of track II (usually ; and ?) should not be passed in. 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.

USER_ID **

String

COMMAND

String

TROUTD

String

TICKET

String

PROCESSOR_ID

String

MERCH_NUM

String

ACCT_NUM EXP_DATE

String String

MANUAL_FLAG

String

TRANS_AMOUNT

String

TRACK_DATA

String

PRINT_RECEIPTS_FLAG

String

430

Tag

Data Type

Description - Gift Input File (.inx) 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. See the section Multi-trans Wait for more information (see page 55). This Flag has no effect if processing will occur over IP or leased line. The tip amount if it is a VTEC or VLNK restaurant transaction. Used for GVEX: A code defined by the merchant that affects the calculation from amount and units to points. The numeric Cashier ID for VTEC and VLNK processors. For VTEC: Flag indicating the industry. Valid Values: 1 = retail, 2 = restaurant Only used for the processor SVS. Used for only for virtual gift card transactions. The Units for points transactions. Note: Only Givex supports Points transactions. Stores the card sequence number for GSAR transactions. the total number of cards for multiple issuance for Chase Paymentech. The refund amount for VTECs deactivate transaction. For VTEC replace transaction, VLNK Balance Merge and Balance Transfer, the field should be set to the account number of the old card. Flag indicating whether the transaction should be forced for Chase Paymentech. Valid Values: 1 force, 0 dont force For GSAR: Flag indicating whether the transaction is a partial redemption transaction. Flag indicating whether the transaction is a loyalty transaction for VTEC transactions. Valid Values: 1 True 0 - False 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 Note: This flag should only be set to 1 for a Valutec deactivate if the LOYALTY_FLAG is set to 0. Valutec does not support deactivate with refund for loyalty cards. Set to 1 if card information was read from RFID (Radio Frequency Identification) device. If card was read from from RFID, track data must be populated and manual flag must be set to 1. Set to 0 otherwise. Only used for the processor SVS. 0 - False, 1 - True Only sent on an activation to determine if a pin should be returned.

MULTI_FLAG

String

GRATUITY_AMNT PROMO_CODE CASHIER_NUM IND_TYPE GIFT_PIN GIFT_UNITS GIFT_SEQ_NUM TOT_NUM_CARDS SOURCE_ACCT_NUM FORCE_FLAG PARTIAL_REDEMPTION_FLAG

String String String String String String String String String String String

LOYALTY_FLAG

String

REFUND_FLAG

String

RFID

String Boolean

VIRTUAL_GIFTCARD_FLAG

These properties are required to process a gift card redemption or sale transaction. Required for VTEC gift card transactions ** 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 (see page 50). This section contains detailed information about user names and how they should be implemented.

Gift Output File (.oux)

Tag USER_ID Data Type String String Description - Gift Output File (.oux) Returns the User name that is associated with the transaction. This value is echoed back from the original transaction. The User name will be in DOS file format, max 8 characters. Returns the merchant number that was specified in the MerchantNumber property.

MERCH_NUM

431

Tag

Data Type

Description - Gift Output File (.oux) 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. See the section Follow On Transactions (see page 58) for more information. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. The Auth Code field serves many purposes. For a GVEX Balance transaction returns the balance remaining on a gift card. For all other GVEX transactions, returns the transaction reference/Error message. For VTEC, returns the Auth Code. For a VTEC Batch function: returns the number of sales done that day and the total amounts of sales in the following format <# of transaction>, <amount>. For a VLNK transaction returns the authorization code or transaction response description. The Reference field serves many purposes. For a GVEX Register transaction returns the first eleven digits of an account number. For a VTEC batch function, returns the number of activations done that day and the total amounts of activations in the following format <# of transaction>, <amount>.>. For all other VTEC transactions, returns the accounts remaining balance. For a VLNK transaction returns the previous balance (balance before transaction was applied). For a BPS Redemption transaction, returns the retrieval reference number. For a VTEC batch function, returns the accounts Deactivates. Data is returned in the format <# of transactions>, <amount>. For all other VTEC transactions, returns the accounts remaining loyalty points. For a GSAR transaction returns the trace number. For a VLNK Activation or Reload transaction, returns the redemption amount. For a VLNK Redemption, Redemption Unlock, or Cash-out transaction, returns the cashback amount. For a VTEC batch function: returns the number of gift card that has been deactivated that day and the total amounts of de-activations in the following format <# of transaction>, <amount>.>. 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. For a GVEX Register transaction, the remaining digits of a gift card number. For a GVEX Redemption, Increment, and Cancel, the balance remaining on a gift card. For a VTEC batch function, the number Add Value Transactions done that day and the total amounts of Add Value in the following format <# of transaction>, <amount>.>. For a VLNK or GSAR transaction, returns the previous balance (balance after transaction was applied). For VLNK, returns trace number (generated by VLNK host). For GVEX, returns the point balance. For a VTEC batch function: returns the number of Gift Transactions Voids performed that day. Returns the number of activations in the current batch Returns the total dollar amount of activations in the current batch Returns the number of AddPoints Transactions in the current batch Returns the total dollar amount of AddPoints transactions in the current batch Returns the number of AddValue transactions in the current batch Returns the total dollar amount of AddValue transactions in the current batch Used in partial redemption transactions where only part of the amount was authorized. Returns the remainder amount that is owed to the merchant. Used in partial redemption transactions where only part of the amount was authorized. Returns the actual authorized amount. Returns the number of Balance Transfers in the current batch Returns the total dollar amount of Balance Transfers in the current batch 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.

TROUTD

String

RESULT

String

AUTH_CODE

String

REFERENCE

String

TICKET

String

INTRN_SEQ_NUM

String

TRANS_ID

String

RET ACTIVATION_COUNT ACTIVATION_TOTAL_AMOUNT ADDPOINTS_COUNT ADDPOINTS_TOTAL_AMOUNT ADDVALUE_COUNT ADDVALUE_TOTAL_AMOUNT AMOUNT_DUE AUTH_AMOUNT BALANCE_TRANSFER_COUNT

String String String String String String String String String String

BALANCE_TRANSFER_TOTAL_AMOU String NT CASHBACK String

432

Tag CREDIT_COUNT CREDIT_TOTAL_AMOUNT GIFT_CARD_BALANCE GIFT_PIN POINTS_COUNT POINTS_TOTAL_AMOUNT PROC_RESP_CODE SALE_COUNT SALE_TOTAL_AMOUNT TIP_COUNT TIP_TOTAL_AMOUNT TRANS_DATE_TIME VOID_BALANCE VOID_COUNT VOID_TOTAL_AMOUNT LEVEL <PRE_AUTH_COUNT> <PRE_AUTH_TOTAL_AMOUNT> <POST_AUTH_COUNT> <POST_AUTH_TOTAL_AMOUNT> <ISSUANCE_COUNT> <ISSUANCE_TOTAL_AMOUNT> <DEACTIVATE_COUNT> <DEACTIVATE_TOTAL_AMOUNT> <BALANCE_ADJUST_COUNT>

Data Type String String String String String String String String String String String String String String String String String String String String String String String String String

Description - Gift Output File (.oux) Returns the number of credits in the current batch Returns the total dollar amount of credits in the current batch Returns the gift card balance. Returns the gift pin. Used only for virtual gift cards. Returns the number of points transactions in the current batch Returns the total dollar amount of points transactions in the current batch Returns the processor response code Returns the number of redemptions in the current batch Returns the total dollar amount of redemptions in the current batch Returns the number of Tip transactions in the current batch Returns the total dollar amount of Tip transactions in the current batch Returns the transaction date and time when passed back by a processor. Returns the Void Balance Returns the number of voids in the current batch Returns the total dollar amount of Voids in the current batch Returns the customer's loyalty level. Only used for VTEC loyalty gift cards. Only for GAPI, this returns the total number of gift card pre-auth transactions processed that day. Only for GAPI , this returns the total amount of gift card pre-auth transactions processed that day Only for GAPI, this returns the total number of gift card post-auth transactions processed that day. Only for GAPI, this returns the total amount of the post-auth transactions processed that day. Only for GAPI, this returns the total number of gift cards issued that day. Only for GAPI, returns the total amount of the gift cards issued that day. Only for GAPI, this returns how many gift cards where deactivated that day. Only for GAPI, this returns the total amount of gift card deactivations that day. Only for GAPI, this returns the number of gift cards that were balance adjusted that day. Only for GAPI, this returns the total amount of balance adjustments on gift cards that day. Only for GAPI, this returns the total number of gift cards that were balance merged that day. Only for GAPI, this returns the total amount of gift card balance merges that day. Only for GAPI, returns the total reported stolen or lost gift cards that day. Only for GAPI, returns the total amount of all stolen or reported lost gift cards that day. Only for GAPI, returns the total amount of all cashout transactions processed that day. Only for GAPI, returns the total number of the cashout transactions processed that day. Only for GAPI, returns the total number of gift cards that have been reactivated that day. Only for GAPI, the total amount of all gift cards that have been reactivated that day.

<BALANCE_ADJUST_TOTAL_AMOUN String T> <BALANCE_MERGE_COUNT> String

<BALANCE_MERGE_TOTAL_AMOUNT String > <REPORT_LOST_STOLEN_COUNT> String <REPORT_LOST_STOLEN_TOTAL_A String MOUNT> <CASHOUT_TOTAL_AMOUNT> <CASHOUT_COUNT> <REACTIVATE_COUNT> <REACTIVATE_TOTAL_AMOUNT> String String String String

433

VeriFone Stored Value API (GAPI)

The VeriFone Stored Value API (GAPI) is a proprietary specification that allows for stored value card processors to add themselves to PCCharge. Applications using GAPI can also integrate with PCCharge using the various integration methods. For more information on adding a stored value card processor to PCCharge, and how to obtain the VeriFone Stored Value API, please contact VeriFone sales at 1-800725-9264.

Batch File Layouts

This section describes the tags required to perform batch/settlement functions.

Batch Input File (.inx)

Tag Data Type Description - Batch Input File (.inx) 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 more information on user names, consult the Multi-User Support section (see page 50). Note: The value passed in USER_ID must match the name of the .inx file. For example: <USER_ID>User2</USER_ID> and User2.inx. The action code that identifies what type of transaction will be performed. Consult the section DevKit Constants for a list of valid values (see page 94). 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 the Processing Company Codes section (see page 101). Sets the Merchant Number issued by the processor that identifies the account. The merchant number must be setup in the Credit Card Setup section of PCCharge. Only used when settling the processor CITI for private label transactions. Set this property to the main credit card processor ID code being used. The number of seconds after which a timeout error will be returned from PCCharge. The count will start when the settlement is submitted to PCCharge. An error will be returned if the settlement has not finished processing when the time period expires. It is highly recommended that integrators review the section Timeouts (see page 47). Note: This tag only works when using the TCP Interface.

USER_ID**

String

COMMAND

String

PROCESSOR_ID

String

MERCH_NUM

String String

SPLIT_PROCESSOR_FLAG

TXN_TIMEOUT

String

434

Tag

Data Type

Description - Batch Input File (.inx) Flag that determines what type of batch close will occur. This flag only supported by Buypass and Fifth-Third when using action code 30 or 31 Valid values: 1 Standard End of Day Batch Close (Default) 2 Shift Close 3 Fifth-Third Terminal Based Batch Close of Debit, EBT, or Gift

BATCH_CLOSE_TYPE

String

** 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 (see page 50). This section contains detailed information about user names and how they should be implemented.

Batch Output File (.oux)

Tag USER_ID Data Type String String String Description - Batch Output File (.oux) Returns the User name that is associated with the transaction. This value is echoed back from the original transaction. The User name will be in DOS file format, max 8 characters. Returns the merchant number that was specified in the MerchantNumber property. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions. The AUTH_CODE field 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. The reference field returns the response from the processor if the response is a declined. This field is not returned for all processors. The Transaction Date field returns the error code from the processor if one is provided for a declined transaction. All processors do not support this field. The INTRN_SEQ_NUM field returns the dollar amount that was settled in the batch or is waiting to be settled in the open batch. The Trans Identifier field returns the Settlement number that is stored in association with the transaction in PCCharges database. This number is not returned from the processor but is PCCharges internal sequencing number scheme. The TICode field returns the number of transactions that are in the batch for which the function was performed. The RET field is only used for Inquiries, Action 30, and returns the number of batches that will be settled for a particular merchant number. For Example, if a merchant account is setup as TSYS using TCP/IP, there is a limitation on how many transactions can be sent across on a single batch, so PCCharge breaks the batch up into smaller batches. The RET field returns the number of smaller batches that would be created for that merchant account. Returns the response code that is provided by the processor. This response code is not provided for all credit card processors. Returns a numerical representation of the result of the transaction. After a terminal-based batch settles, returns the batch number.

MERCH_NUM

RESULT

AUTH_CODE

String

REFERENCE TRANS_DATE INTRN_SEQ_NUM

String String String

TRANS_ID

String

TICODE

String

RET

String

PROC_RESP_CODE RESULT_CODE BATCH_NUMBER

String String String

Note: In the event there are multiple batches waiting to be settled in one settlement, the integrated application will need to be designed to loop through the settlement response to retrieve the response for each batch.

435

Report File Layouts

This section describes the tags required to submit report requests.

Report Input File (.inx)

Tag Data Type Description - Report Input File (.inx) 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 more information on user names, consult the Multi-User Support section (see page 50). Note: The value passed in USER_ID must match the name of the .inx file. For example: <USER_ID>User2</USER_ID> and User2.inx. The action code that identifies what type of report will be requested. Valid Values: 81-84. Example: If running a credit card detail report, set the action code to 81. Consult the section DevKit Constants for a list of valid values (see page 94). Merchant Number filter. Set this property to filter the report by the merchant number specified. Setting this property will generate a report consisting of only those transactions processed via the merchant number specified. To generate a report that includes all merchant numbers in PCCharge, set this property to "ALL or leave blank. Example: "99999999911" User name filter. If a valid user name is set in the ACCT_NUM property, the report will be filtered by that user name. The report returned will consist of only those transactions processed by the user name specified. Example: "User1". If this property is left blank, the report will show transactions processed by all users. Result filter. Use this filter to create a report consisting of only those transactions with the result specified. Valid Values: 0 = all (default), 1 = approved, 2 = declined Example: 1 Destination Directory for Report File. Specifies the destination directory where the report file will be generated by PCCharge (if PERIODIC_PAYMENT_FLAG is set to "1"). Example: C:\My Documents\PCCReports\ Path Formats: UNC, MS-DOS(8 Characters) and Long. Max Length: 40 characters (if the Destination Directory is longer than 40 characters, use CUSTOMER_CODE for the additional characters. Must end with a "\" unless the directory name will be continued in the CUSTOMER_CODE property. Note: If running in a Client/Server environment, this property is the path from the server running PCCharge, not the client. For example, if a client submitted a report request that specified C:\ as the destination directory, the report would be written to the local hard drive of the server running PCCharge, not to the clients hard drive. CUSTOMER_CODE String Destination Directory for Report File (continued). Continuation of the destination directory (if the directory name is greater than 40 characters). Max Length: 25 characters. Must end with a "\" Report Output setting. Determines if the report will be printed by PCCharge or written to a file. Valid Values: "0" = print to default printer specified in PCCharge (default). "1" = print to file using filename specified in TRANS_ID and path specified in TRACK_DATA. Starting Date/Time Filter (Optional) Specifies the start date and start time of the report. Format: Date: MM/DD/YY Time: HH:MM:SS PM. Use to create a report consisting of only those transactions processed on or after the date specified. If a start date is not specified, today's date is assumed. If a start time is not specified, 12:00:00 AM is assumed. The start date can be passed without the start time. However, the start time cannot be passed without the start date. Examples: "03/04/05 09:00:00 AM" or 03/04/05

USER_ID

String

COMMAND

String

MERCH_NUM

String

ACCT_NUM

String

MANUAL_FLAG

String

TRACK_DATA

String

PERIODIC_PAYMENT_FLAG

String

STREET

String

436

Tag

Data Type

Description - Report Input File (.inx) Ending Date/Time filter. Specifies the end date and end time of the report. Format: Date: MM/DD/YY Time: HH:MM:SS PM. When used in conjunction with Street; will create a report consisting of only those transactions processed between the start and end date/time specified (inclusive). If an end date is not specified, today's date is assumed. If an end time is not specified, 11:59:59 PM is assumed. The end date can be passed without the end time. However, the end time cannot be passed without the end date. Examples: "07/06/05 06:00:00 PM" or 07/06/05 Report File name/Report File Type. Specifies the filename and extension of the report file generated by PCCharge (if PERIODIC_PAYMENT_FLAG is set to "1"). Also determines what file type will be used when PCCharge generates the report. To specify the file type, set the extension to one of the following: .pdf Create the report file in the Portable Document Format. Ex. Report.pdf .rtf Create the report file in Rich Text. Ex. Report.rtf .txt Create a report file in flat text. Ex. Report.txt Default: .txt (If an extension other than the ones listed is passed, the report will be returned as flat text and a .txt extension will be added to the filename)

CARDHOLDER

String

TRANS_ID

String

These properties are required to submit a report request.

Report Output File (.oux)

Tag USER_ID Data Type String Description - Report Output File (.oux) Returns the User name that is associated with the transaction. This value is echoed back from the original transaction. The User name will be in DOS file format, max 8 characters. Returns the result, which indicates the transactions status upon completion. Refer to the Transaction Result Constants section (see page 103) for a list of valid values and descriptions.

RESULT

String

437

Configuration File Layouts

This section describes the tags required to configure various settings. Currently, only configuration of the Transaction Archive (pccw.mdb database backup) is supported.

Configuration Input File (.inx)

Tag COMMAND Data Type String Description - Configuration Input File (.inx) The action code that identifies what type of configuration command will be performed. First byte is always a Z. Consult the section DevKit Constants for a list of valid values (see page 94). Configuration type. Valid value: 0 = CFG_TXN_ARCHIVE = Configure Transaction Archive. Use action code ZC. Enable or disable current configuration (1 = Enable, 0 = Disable). Specify path for saved output files (Example: backed up transaction database). Must end with a backslash \. Transaction archive size limit for GUI archive prompting and validation. Specified in megabytes. Transaction archive preservation range. All transactions within the past number of keep days will remain in the pccw.mdb database following a transaction archive command.

CFG_TYPE CFG_ENABLED CFG_PATH CFG_SIZE_LIMIT

Long String String String String

CFG_KEEP_DAYS

These properties are required to submit a configuration command.

Configuration Output File (.oux)

Tag Data Type Description - Configuration Output File (.oux) Result of configuration command. Responses: CONFIG SUCCESS = Configuration updated successfully. CONFIG FAILURE = Could not update configuration. INVALID TYPE = Unsupported configuration type.

RESULT

String

438

Various Utility File Layouts

This section describes the tags required to perform various functions.

Transaction Archive Input File (.inx)

Tag Data Type Description - Transaction Archive Input File (.inx) 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 more information on user names, consult the Multi-User Support section (see page 50). Note: The value passed in USER_ID must match the name of the .inx file. For example: <USER_ID>User2</USER_ID> and User2.inx. Action code for system configuration command. Transaction Archive: ZA This field is optional when performing a size limit check, but is required to be set for a full archive. (1 = perform full database archive, 0 = check database size limit).

USER_ID

String

COMMAND MANUAL_FLAG

String String

These properties are required to submit a transaction archive command.

Transaction Archive Output File (.oux)

Tag USER_ID Data Type String Description - Transaction Archive Output File (.oux) Returns the User name that is associated with the transaction. This value is echoed back from the original transaction. The User name will be in DOS file format, max 8 characters. Result of the command. Responses: If MANUAL set to 1 for full archive: ARCHIVE SUCCESS = transactions successfully archived to pccwhist.mdb. ARCHIVE FAILURE = transactions not archived due to: feature not enabled, database under the configured size limit, or an unexpected database error occurred. If MANUAL set to 0 for size limit check : EXCEEDS LIMIT = Transaction database exceeds the configured archive limit. UNDER LIMIT = Transaction database is under the configured archive limit. CURRENT_SIZE CONFIG_SIZE INTRN_SEQ_NUM String String String Current transaction database size in bytes. Current configured size limit for transaction archive in bytes. Unique internal sequence number present for all transactions.

RESULT

String

Transaction Inquiry Input File (.inx)

Refer to the section Transaction Inquiry (see page 85) for more information on the Transaction Inquiry request.
Tag Data Type Description - Transaction Inquiry Input File (.inx) 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 more information on user names, consult the Multi-User Support section (see page 50). Note: The value passed in USER_ID must match the name of the .inx file. For example: <USER_ID>User2</USER_ID> and User2.inx. Action code for Transaction Inquiry: ZI Either the TROUTD tag OR the ACCT_NUM tag must be supplied.

USER_ID

String

COMMAND TROUTD

String String

439

Tag ACCT_NUM

Data Type String

Description - Transaction Inquiry Input File (.inx) Either the TROUTD tag OR the ACCT_NUM tag must be supplied.

These properties are required to submit a transaction inquiry command.

Transaction Inquiry Output File (.oux)

Tag RECORD_COUNT TRANS_RECORD Data Type String String Description - Transaction Inquiry Output File (.oux) The number of records matching the inquiry Contains nested XML tags providing information on transaction(s) pulled from Trans table in the PCCharge database (pccw.mdb).

440

TCP Interface
Integration via the TCP Interface is very similar to a File Method integration. Refer to the section File Layout Specifications (see page 411) for information on creating and reading transaction data. When using the TCP Interface, this data is sent and received via sockets. To process a transaction using the TCP Interface: 1. Create a string that contains the transaction request. Refer to the section File Layout Specifications (see page 411) for information on creating the transaction request string. 2. Open a socket connection to PCCharge. 3. Send the request string. 4. Once PCCharge processes the transaction, a stream of data will be returned with the results 5. Parse this data to retrieve the results of the transaction. Refer to the section File Layout Specifications (see page 411) for information on the response data. The only difference between building the message for the TCP interface and the File Method is that the <XML_FILE> tag can omitted from the request when submitting transactions via the TCP Interface, and the response will not include the <XML_FILE> tags. Note: Before attempting to send TCP transaction requests to PCCharge, the PCCharge TCP Interface must be activated. Merchants must check the Use TCP/IP Connection option in the Setup | Configure System | Advanced menu of PCCharge Pro or in the Setup | Preferences | Advanced menu of PCCharge Payment Server. This option is disabled by default. Note: Merchants should make sure the Enable TCP/IP Client Reversals option is un-checked in the Setup | Configure System | Advanced menu of PCCharge Pro and PCCharge Payment Server if using a processor other than Buypass. This option is disabled by default. Note: The default port of 31419 should be changed to maximize security when processing transactions in a live environment. The default port of 31419 may be changed if a device is already using that port on the computer running PCCharge.

441

CHAPTER 7 -- Code Sample Information

442

Code Samples
The various sections in this chapter describe several of the code samples that are included in the PCCharge DevKit. In many cases, the code samples themselves contain comments, therefore no information will be provided about those code samples in this chapter. Please refer to the comments in the code samples or contact the PCCharge Developer Support department for more information.

Java Client
The File Method Java Client demonstrates the File Method integration using Java. Note: This program is supplied for demonstration purposes only.

Purpose
This program demonstrates the use of the PCCharge File Method interface using a Java client application. It employs classes that encode/decode fields into/from INX and OUX records.

Site/User Specific Code Modifications

The values assigned to the following variables in the PCCGUI class code must be customized to what is appropriate to a specific user and site as follows: String Processor = "VISA"; // Processing company String TID = "999999999911"; // Merchant ID String User = "User1"; // ignored for unlimited user license, otherwise must be licensed user String Path = "C:\\Program Files\\active-charge\\"; // path to PCCharge directory (use two "\"s: "\" is a reserved character in Java)

Compilation
Use the following command to compile the code with JavaSoft JDK1.0.2 and JDK1.1.X: javac Pccfile.java The code also compiles and executes under Microsoft J++.

Compilation produces seven class files, which must be found in the same directory when the main class is executed.

Initiating Execution
As an application, with the Java Virtual Machine: java Pccfile

443

Operation
1. Execution produces a form with six entry fields. 2. Only Card Number, Expiration Date, and Amount fields are mandatory for a valid transaction. 3. Initiate processing by clicking on the Send button. 4. A file named User1.inx will be written to the directory specified in Path. 5. The program will block input until it reads the transaction result from the file User1.oux. A message box will report the result of the transaction.

444

Web-based Integration Samples

The PCCharge DevKit includes several samples designed to demonstrate the coding required to create a Web-based integration to PCCharge. The samples included in the DevKit do not actually perform credit card processing. They are purely an interface or "front-end" to the PCCharge processing engine. The intended audience for this chapter includes webmasters and TCP/IP application developers. It assumes basic knowledge of Web, Internet, and TCP/IP terminology, as well as familiarity with the specific web server (if any) to be used.

System Requirements
PCCharge Virtual Terminal Sample Windows NT Server 4.0 or higher with Service Pack 5 installed Internet Information Server (IIS) v3.0 or higher, running the Web Server Service Active Server Pages (ASP) For Internet-based use, host must provide a Secure Socket Layer (SSL) to ensure secure transactions. Accessing and using a PCCharge Virtual Terminal site requires either Internet Explorer v6.0 or higher or Netscape v6.0 or higher. PCCharge with Unlimited Users activated Read/write access to the PCCharge program directory

ASP Sample Windows NT Server v4.0 or higher Microsoft Internet Information Server v4.0 or higher PCCharge with Unlimited Users activated Read/write access to the PCCharge program directory

Cold Fusion Sample Windows NT Server v4.0, or higher Cold Fusion v4.0 or higher Web Server cable of executing Cold Fusion Tags (Microsoft Internet Information Server, v4.0 or higher recommended) PCCharge with Unlimited Users activated. Read/write access to the PCCharge program directory

Java Applet Sample Java-enabled Web Server Java v1.0.2 or higher or Microsoft J++ Any operating system supporting Java, including the Java socket functions PCCharge with Unlimited Users activated TCP/IP connectivity to PCCharge

445

PCCharge Virtual Terminal Sample

The PCCharge Virtual Terminal is a code sample based on Active Server Page (ASP) technology that demonstrates how merchants can view, charge, and settle credit card transactions using a browser. Typically, applications such as the PCCharge Virtual Terminal would be used in the following scenarios: 1. For ISPs that host PCCharge and set up eCommerce sites for multiple merchants. The ISP would provide a Virtual Terminal interface for their merchants to provide a way to view reports, process voids and post-Authorizations, and settle batches. 2. For Windows-based Intranets. The Virtual terminal can be used as a Virtual point-of-sale, meaning merchants would simply use their browsers to process transactions across the network, eliminating the need to install extra software on each client machine.

Installation
When installing the DevKit, the PCCharge Virtual Terminal will be installed into the directory C:\Program Files\Active-Charge SDK\Virtual Terminal. Choose a folder that will made into a virtual directory in IIS, or create a new sub-folder under an existing website directory. Copy the files and folders from the PCCharge Virtual Terminal folder into this virtual directory. If the Virtual Terminal's files and folders are copied to a machine on which the DevKit has not been installed, the file PSCharge.dll should also be copied from the directory \WINNT\System of the first machine to the directory \WINNT\System of the new machine. PSCharge.dll must also be registered for the PCCharge Virtual Terminal to work properly (use the command regsvr32 PSCharge.dll to register this file). Note: If problems occur while running PCCharge on a separate machine than the Web Server (on the same network), have the Network Administrator set up a Global User as follows: 1. Add a Global User on a trusted domain server. 2. Set the IUSR (found in the IIS Default Web Site) to this Global User. 3. Give the Global User full permissions to the PCCharge directory. In the Internet Information Services (IIS) Manager click on the Web Service Extensions folder. Here you will see that Active Server Pages are Prohibited (this is the default configuration of IIS 6) Highlight Active Server Pages and click the Allow button ASP is now active. Once installed, it is important not to change the directory structure of the PCCharge Virtual Terminal server files. Several sub-folders are created in the folder, and the files in these folders are referenced in the installed ASP/HTML files. A listing of all ASP/HTML files installed, and a brief description of the purpose of these files, is included in the following ASP/HTML Files Table:

ASP/HTML Files Table

File 81.asp 82.asp 83.asp global.asa PCCWBatch.asp PCCWBatch_post.asp Description ASP/HTML Files Table ASP code to display the Credit Card Detail report ASP code to display the Batch Pre-Settle report ASP code to display the Batch Post-Settle report Sets session variables to create connection to charge-processing-engine database and path information on start up. Displays options (buttons) for doing batch Inquiry and Settlement Displays results of batch Inquiry or Settlement

446

File PCCWBusy.asp PCCWDefault.htm PCCWDisplayRpt.asp PCCWInquire.asp PCCWInquireBusy.asp PCCWMenu.asp PCCWMerch.asp PCCWMerch_post.asp PCCWOfflinePurge.asp PCCWOfflinePurge_post.asp

Description ASP/HTML Files Table Initializes variables and displays busy message to user during processing of transaction Sets up frames for the PCCharge Virtual Terminal Displays Report Submits requests and receives responses when user clicks Inquire to do batch Inquiry Displays busy messages when user is performing batch Inquiry Provides a menu for choosing transactions, settlement, reports, and help options Screen to allow merchant to enter and save merchant number and processing company abbreviation Checks validity of entered merchant numbers and processing companies and informs user appropriately. Consult the section Virtual Terminal Security (see page 448). Deletes all offline transactions by deleting the offline transaction file. Displays a "wait" message with a spinning credit card icon during an Offline Batch Purge. Displays merchant's Offline Transaction Report if merchant has any offline transactions. Offline transactions are transactions that have been submitted to the payment-processing engine, but have not yet been authorized. These transactions are stored until the merchant decides to actually authorize them. Displays the results of an Offline Batch Purge. Updates offline transaction file stored by payment-processing engine when merchant chooses to change status of any transaction in offline file. Displays table for allowing user to enter Post Authorization transaction. Displays different Report types and options from which user can choose. Validates user selections on Report types and options screen, and sets errors or calls other reports pages as necessary. Submits stored offline transaction file for authorization. Each transaction in file not marked to be dropped is processed (authorized) by payment-processing engine. Those marked to be dropped, if any, are skipped. Displays results of processing offline transaction file. Displays busy message to user (merchant) during processing of offline transaction file. ASP code to process transactions. Displays table for allowing user to enter Sale or Pre-Authorization transaction. Submits batch settlement and checks response when user performs batch settlement. Displays busy messages to user when processing batch Settlement. Displays the VeriFone, Inc. logo and the PCCharge Virtual Terminal title. Determines what transaction type user has selected from menu and redirects user to correct page for running that transaction. Shows user any error that may have occurred while processing credit card transaction. Displayed in place of PCCWTrans_post.asp if error occurred. Shows user results of credit card transaction Displays table allowing user to enter Void transaction type

PCCWOfflineRpt.asp

PCCWOfflineRptPurge_post.asp PCCWOfflineRptUpdate.asp PCCWPost.asp PCCWPreReport.asp PCCWReports.asp

PCCWRunOffline.asp PCCWRunOffline_post.asp PCCWRunOfflineBusy.asp PCCWRunTrans.asp PCCWSale.asp PCCWSettle.asp PCCWSettleBusy.asp PCCWTitle.asp PCCWTrans.asp PCCWTrans_Err.asp PCCWTrans_post.asp PCCWVoid.asp

In addition to the ASP/HTML files installed, there are several sub-directories installed as well:

Virtual Terminal Sub-Directories

Sub-Directory help images Description Virtual Terminal Sub-Directories Contains the online Help HTML files used in PCCharge Virtual Terminal Contains all images used in PCCharge Virtual Terminal

447

Sub-Directory js css

Description Virtual Terminal Sub-Directories Contains JavaScript helper functions that make users confirm their actions when purging off-line transaction files Contains cascading style sheets used in PCCharge Virtual Terminal

Virtual Terminal Installation

The system's "Internet User" must be given full access to the directory C:\Program Files\activecharge OR C:\Program Files\pccw for the PCCharge Virtual Terminal to work properly. To find out which user is designated as the system's "Internet User": 1. Open the Internet Service Manager 2. Right click on "Default Web Site" 3. Choose Properties 4. Click on Directory Security 5. Click the Edit button next to Anonymous Access and Authentication control 6. Click the Edit button next to Allow Anonymous Access. The user name that appears next to Username (ex. IUSR_COMPUTER) is the "Internet User". Simply add this Username to the PCCharge folder's permissions list and assign the user "Full Control" permissions. Once the server files have been installed, start the Internet Service Manager and make the directory where the files are installed a virtual directory, if it is not already.

Virtual Terminal Security

Caution: Please read this section carefully. PCCharge Virtual Terminal requires Secure Socket Layer (SSL) encryption to be in place on the site before PCCharge Virtual Terminal can be hosted securely for merchants. Once an SSL certificate has been acquired for the site, verify that PCCharge Virtual Terminal is setup to use this security. To verify the security setup, follow the procedure below: 1. Open the ASP file named PCCWMerch_post.asp. 2. Find the line in this file that reads Response.Cookies("MrChant").Secure = FALSE. 3. Change the word FALSE to TRUE. 4. Save this file, and close it. This ensures that a merchant's merchant account information is encrypted when stored on the machine from which the merchant is browsing. FOR TESTING PURPOSES ONLY: With test merchant accounts on non-SSL sites, set the above line = FALSE until ready to go live with a PCCharge Virtual Terminal site. Setting the line = TRUE without using SSL will cause PCCharge Virtual Terminal to not save merchant account information properly.

448

Setting up Merchant Information

Click Setup from the menu frame to display the Merchant Setup Information screen. The information on this screen must be entered correctly before using PCCharge Virtual Terminal. Once this information is entered correctly, it will be stored in a cookie. Cookies must be enabled in the local Web browser for the PCCharge Virtual Terminal to work correctly. There are two required fields on this screen: Processing Company and Merchant Number. These values should be set to a valid Processing Company and Merchant Number that is set up in PCCharge. See the DevKit Constants section for a list a valid processor codes (see page 94).

Using Virtual Terminal

Use a web browser to open the file: PCCWDefault.htm Note: In order to use the Virtual Terminal, the Unlimited User License MUST be activated in PCCharge. See the section Multi-User Support (see page 50) for more information.

Processing Transactions
To process a transaction, follow the procedure below: 1. Select the type of transaction to be performed from the drop-down list under Transactions in the Menu frame. 2. Click the Submit button. This will display one of several transaction screens, depending on the type of transaction selected. 3. Enter data for the available fields and click the Process button. 4. ONLY CLICK THIS BUTTON ONCE per transaction and DO NOT click the Stop button on the browser after clicking Process. The transaction will be processed even if the Stop button is clicked. A busy animation will appear while processing is underway and the results of the transaction will appear when processing is complete. PCCharge Virtual Terminal can also process "offline" transactions. When the offline transaction processing is turned on, a .bch file is created that holds all transaction information entered into Virtual Terminal. To process an offline transaction, follow the procedure below: 1. Click Setup in the Menu frame. 2. Check the box next to Perform Offline Transactions. Click Update. 3. Process transactions as shown in the steps above.

Settling Batches
Selecting Settlement from the menu frame will display two settlement options: Inquire and Settle.

449

If the merchants processor is Terminal based or set up for manual open/close, batch settlement must be performed every day that transactions have been processed to ensure that funds are deposited into the merchants bank account. The two options on this screen allow merchants to view and settle their daily batches. Once one of these options have been selected, do not click the Stop button. To settle offline transactions, click the Settlement button in the Menu frame. Click Process Offline Transactions. To remove the transactions saved in the .bch file, click the Purge Offline Batch button. Inquire Use this to retrieve the current status of the pending batch (unsettled transactions). Clicking this option will return the number of items in the current batch, the current batch number, and the total dollar amount of the transactions in the batch. This option is only for viewing the batch status and does not change the status of the batch. It does not settle or close the batch. Settle This option settles or closes all of the transactions in the pending batch.

Reports
Because of updated encryption and changes in the database structure, reports are no longer available through the Virtual Terminal starting with PCCharge version 5.7.

450

ASP Sample
The ASP Sample uses Active Server Pages to communicate transaction and settlement information from a web page to PCCharge via the PSCharge.dll. This sample creates an instance of the PSCharge charge or batch class, sets a few properties, calls the send method, and then waits for the response from PCCharge. This solution is ideal for Windows-based servers running Internet Information Server. If the Web Tools were installed during the installation of the DevKit, the ASP sample will be installed in the directory C:\Program Files\active-charge SDK\Web Tools\Asp. Refer to the code and comments in the files in this directory when beginning the integration. Note: The ASP sample should not be used as-is on a public merchant website because, among other things, it allows the users to specify the transaction amount. The HTML forms of the sample may be modified for this type of website or could be used as the basis of an Intranet-based credit card processing application. The HTML samples can be installed anywhere in the web server document path. If they are to be used securely, they must be installed in a secure path area as previously configured in the web server software. PCCharge can run on the same computer as the ASP sample, or they can be separated in various ways. The required connections for the ASP Sample are as follows: The ASP pages must be installed into an IIS virtual directory so that they can be properly executed by IIS. Normally this means that they will be installed on the same computer with the web server, although this is not a strict requirement. The provided ASP sample communicates transaction requests to PCCharge via the PSCharge.dll. Thus, both the ASP pages and PCCharge may be running on the same computer or they may reside on different computers. If using separate computers, the servers must be in the same domain (or in domains that trust one another), the PCCharge directory must be shared, and proper permissions for the web server's Internet User must be assigned to the PCCharge directory. This means that the Internet User that invokes a transaction request on COMPUTER1 (IUSR_COMPUTER1, for example) must have read/write access to the PCCharge directory on COMPUTER2 (Example: \\COMPUTER2\active-charge). Also, PSCharge.dll must reside and be registered properly on the machine that hosts the ASP pages (COMPUTER1 in this case).

Creating an Object The user settable properties and methods for each of to DLL's classes are listed in the DLL (Active X) Method section of the API (See page 202) or in PSCharge.html. PSCharge.html is located in the DevKit in the C:\Program Files\active-charge SDK\Web Tools\Asp directory. Before any properties or methods can accessed, an instance of a DLL class must be made. This is done from Active Server Pages with code similar to the following: Set GO = Server.CreateObject("PSCharge.Charge")

451

Cold Fusion
The Cold Fusion Sample uses tags to communicate transaction and settlement information from a web page to PCCharge via the PSCharge.dll. This sample creates an instance of the PSCharge charge or batch class, sets a few properties, calls the send method, and then waits for the response from PCCharge. This solution is ideal for Windows-based servers running a Cold Fusion compatible web server. If the Web Tools were installed during the installation of the DevKit, the Cold Fusion sample will be installed in the directory C:\Program Files\active-charge SDK\Web Tools\Cold Fusion. Refer to the code and comments in the files in this directory when beginning the integration. Note: The Cold Fusion sample should not be used as-is on a public merchant website because, among other things, it allows the users to specify the transaction amount. The HTML forms of the sample may be modified for this type of website or could be used as the basis of an Intranet-based credit card processing application. The HTML samples can be installed anywhere in the web server document path. If they are to be used securely, they must be installed in a secure path area as previously configured in the web server software. The required connections for the Cold Fusion Sample are as follows: The Cold Fusion tags must be installed so that they can be executed as Cold Fusion script by the web server. Normally this means that they will be installed on the same computer with the web server, although this is not a strict requirement. The provided Cold Fusion sample communicates transaction requests to PCCharge via the PSCharge.dll. Both the Cold Fusion sample and PCCharge must be running on the same computer. Also, PSCharge.dll must reside and be registered properly on the machine that hosts the Cold Fusion pages (COMPUTER1 in this case).

Creating an Object

The user settable properties and methods for each of to DLL's classes are listed in the DLL (Active X) Method section of the API (See page 202) or in PSCharge.html. PSCharge.html is located in the DevKit in the C:\Program Files\active-charge SDK\Web Tools\Asp directory. Before any properties or methods can accessed, an instance of a DLL class must be made. This is done from Cold Fusion tags with code similar to the following: <CFOBJECT ACTION="Create" NAME="Charge1" CLASS="PSCharge.Charge">

452

Java
Java Applet -- This client-server based sample uses several Java classes to communicate transaction information from a Java Applet to one of our payment-processing engines via sockets. This solution is also ideal for multi-platform sites, or non-Windows-based servers.

Required Connections
PCCharge can be installed and run on the same computer as any of the samples, or they can be separated in various ways. The required connections for each configuration are as follows: Java Applet The Java Applet, the web server, and PCCharge must all reside on the same server. The Java Applet communicates with PCCharge via TCP/IP using sockets. By default, the Java Applet communicates with PCCharge via port 31419. The default port of 31419 should be changed to maximize security when processing transactions in a live environment.

TCP Interface Web Samples

The Java Applet sample communicates transaction information to PCCharge via sockets. Before attempting to use these samples, you should make sure that the PCCharge TCP Interface has been activated and that the proper user configuration has been set in PCCharge. Please refer to the TCP Interface chapter before proceeding (see page 441).

Java Applet
The folder containing the Java Applet sample contains two main files: sample.html and PCCClient.java. Before attempting to use the Java Applet, you should edit the PCCClient.java file and modify the IP Address, Port, Merchant Number, and Processor code values, if necessary. Once these values match the PCCharge configuration, you must then compile PCCClient.java using a Java compiler. The command to compile with JavaSoft is javac PCCClient.java. Alternatively, PCCClient.java may be compiled with Microsoft J++. Once compiled, seven .class files will be created. Below are the classes and their descriptions. HDR.class -- Format of the header data sent to PCCharge INX.class -- Format of transaction data sent to PCCharge OUX.class -- Format of transaction results returned from PCCharge PCCClient.class -- The main class PCCGUI.class -- Creates the data entry form and handles command events Records.class -- Super class for HDR, INP, & OUT records ReportDialog.class -- Reports transaction results

453

To run the Java Applet, simply load the sample.html form into a Java-capable web browser. The Java Applet will appear. For more information on the Java Applet, see the README.txt file that resides in the directory C:\Program Files\Web Tools\Java.

454

General Troubleshooting
Invalid merchant account? If the response page indicates an invalid merchant account, you are probably sending the wrong merchant number or processor code to PCCharge. Trouble with multiple transactions? If your application operates properly with single transactions, but has difficulty with multiple transactions, you may not have the unlimited user version of PCCharge installed. Otherwise, there is a high likelihood that your application is not handling the socket connections or data flow properly. The PCCharge TCP Interface has been tested successfully with high serial and concurrent transaction volume.

Permissions
The most common problem integrators experience while attempting to implement an ASP or Cold Fusion integration involves NT permissions. For a web site visitor to successfully submit an ASP or Cold Fusion transaction request via the PSCharge.dll, that visitor must have full access to the directory C:\Program Files\active-charge or c:\Program Files\PCCW. To set full access permissions for the visitor, follow these steps: In Microsoft IIS, go to the Internet Service Manager Right click on "Default Web Site" Choose Properties Click on Directory Security Click the Edit button next to Anonymous Access and Authentication control Click the Edit button next to Allow Anonymous Access. Note the user name that appears next to Username (ex. IUSR_COMPUTER). This is your "Internet User". Simply add this user to the permissions list of the PCCharge directory and assign the user "Full Control" permissions. If you experience problems using your Web Server and PCCharge on separate machines on the same network, you should have your Network Administrator set up a Global User as follows: 1. Add a Global User on a trusted domain server. 2. Set the IUSR (found in the IIS Default Web Site) to this Global User. 3. Give the Global User full permissions to the PCCharge directory.

455

Appendix

456

Test Credit Cards and Merchant Accounts

The PCCharge DevKit includes test merchant accounts and test credit card numbers that can be used while developing and testing integrated applications. Currently, VeriFone, Inc. includes only test merchant accounts for credit card and check processing companies. Debit, EBT, and Gift test merchant accounts can be acquired by contacting the various processing companies directly. Contact information for several processors can be found within this section.

Test Credit Card Numbers

Several credit card numbers are provided for testing purposes. The expiration date for each test card should be 12xx, where xx is the last two digits of the current year or later. Most processors require that the amount of $1.00 be used for test transactions. Some processors will decline amounts greater than $1.00. Integrators should experiment with different amounts during integration and testing. Also included is generic Address Verification Data and Card Verification Values. The processor may return a positive result if these values are used.

Credit Cards
371449635398431 (American Express) 4012000033330026 (Visa) 4387755555555550 (Visa) 4055011111111111 (Visa Commercial Card) 5424180279791765 (MasterCard) 5439750001500206 (MasterCard) 6011000998980019 (Discover) 5014861541104200412 Driver ID: 0041 (Fleet One) 70768599874125027 Driver PIN: 11411 (Fuelman) 7088869008250004273 (Voyager)

Address Verification Data

Most processors that support AVS will accept the following information as valid: Zip Code: 85284 Street: 8320 Main Street

Card Verification Values

Most processors that support CVV2, CVC2, and CID, will accept the following information as valid: VISA: 999 MasterCard: 998 Discover: 996 AMEX: 9997

457

Test Track Data

This section includes track I and II data for four different credit cards. Integrators that have access to a magnetic stripe encoding device may use this information to create their own test credit cards. Test Card 1 (Generic MasterCard): %B5424180279791765^VERIFONE TEST 1^08121011000 1111A123456789012? ;5424180279791765=08121011000001234567? Test Card 2 (Generic MasterCard): %B5439750001500206^VERIFONE TEST 2^08121011000 1111A123456789012? ;5439750001500206=08121011000001234567? Test Card 3 (Generic Visa): %B4012000033330026^VERIFONE TEST 3^08121011000 1111A123456789012? ;4012000033330026=08121011000001234567? Test Card 4 (First Data Omaha Test Card): %B0227271714569^FDMS OMAHA TEST CARD^081210054321000000000000000150A? ;0227271714569=08121011000012345678?

458

Test Merchant Account Information

Information about each test merchant account can be found below. The setup files for the test merchant accounts are included in the DevKit in the \active-charge SDK\Test Merchant Info\ directory. Values such as URLs and phone numbers are different for some processors when using the test accounts. These values have been set up properly in the test merchant account files already. This section should be used as a reference for the test merchant accounts and to acquire contact information for processors that do not provide test accounts in the DevKit. Note: Some test merchant accounts allow for or even require a real credit card number to be used while testing. If using a real credit card, no charges will be placed against a real card number, but the limit-tobuy will be reduced by the amount of the transaction. Therefore, use small amounts less than $10 when testing.

FDMS North / Cardnet (CES)

Test Credit Card Company Number: 000000925990645444 Valid Credit Card Numbers: 5499840000000329 5424180279791765 5439750001500206 4012000033330026 To test address verification, use the following: Zip code: 105232417 Street Address: 4 NOB HILL DRIVE

FDMS Omaha / FDR (FDC)

Test Credit Card Company Number: PZ95.022009001234566 Valid Credit Card Numbers: 0227271714569

FDMS South / NaBanco (NB)

Test Credit Card Company Number: 67888882701 Valid Credit Card Numbers: 5442981111111114 5424180279791765 The following phone number may be used for testing: (800) 884-8379

459

Global Payments-East (NDC)

Test Credit Card Company Number: 3112 Valid Credit Card Numbers: 4003010123456780 5424180279791765 5439750001500206 4012000033330026

Chase Paymentech (GSAR)

Test Credit Card Company Number: Valid Credit Card Numbers: 5424180279791765 5439750001500206 4012000033330026 Note: The test merchant account information that is installed by the DevKit does not include the password necessary to process transactions via Chase Paymentechs Netconnect (TCP/IP) interface. In order to process transactions successfully using Netconnect, the following password should be entered in the Chase Paymentech Advanced Options screen in PCCharge: pccharge5

Note: In order to test Canadian Debit with Chase Paymentech (GSAR), the integrator will need to obtain a test merchant account from VeriFone Developer Support, and a VeriFone SC5000 PINpad from Chase Paymentech (GSAR) that is configured properly for use with Canadian Debit. Application version 2.0H must be loaded onto the PINpad. MAC data is specific to the PINpad and merchant number. If EBT transactions will be supported, a separate PINpad device is required. Please contact VeriFone developer support at 1-877-659-8983 or [email protected] for more details.

American Express (AMEX)

Integrators may contact the following individual to set up a test account: Scott Arndt (800) 451-8413

TSYS (Formerly Vital) (VISA)

Test Credit Card Company Number: 999999999911 Test URL: ssltest.tnsi.com Port: 5004 Valid Credit Card Numbers: 5424180279791765 5439750001500206 4012000033330026

460

FDMS Nashville / Envoy (FDCN)

Test Credit Card Company Number: 0000114910300001188697 Valid Credit Card Numbers: 5424180279791765 5439750001500206 4012000033330026

National Bankcard Systems (NBS)

Test Credit Card Company Number: GO1086123456401 Valid Credit Card Numbers: 5014861541104200412 Driver ID: 0041 70768599874125027 Driver PIN: 11411 6900460430001234566 Driver ID: 410483 7088869008250004273

NPC (NPC)
Test Credit Card Company Number: 999999999911 Valid Credit Card Numbers: 5424180279791765 5439750001500206 4012000033330026

ECHO (ECHO)
Test Credit Card Company Number: 1233016004 Valid Credit Card Numbers: 5439750001500206

NOVA (NOVA)
Test Credit Card Company Number: 99988836 Valid Credit Card Numbers: 5424180279791765 5439750001500206 4012000033330026

RBS Lynk (LYNK)

RBS Lynk has not provided VeriFone with contact information to allow integrators to request a test account. Contact RBS Lynk. on the web at http://www.lynk-systems.com.

461

Alliance Data Systems, Inc. (ADSI)

Test Credit Card Company Number: GOPCCHARGE01 Valid Credit Card Numbers: 5424180279791765 5439750001500206 4012000033330026

Buypass (BPAS)
Integrators may send an email to the following address to set up a test account: [email protected] Note: Buypass requires a mini-cert in order to allow merchants to use a POS / integration with PCCharge and their network. For more information, speak with a Buypass representative.

Fifth-Third Bank-St Pete (BPS)

Integrators may contact the following individual to set up a test account: Nancy Vance (810) 714-0952 / [email protected]

Heartland Payment Systems (HPTS)

Integrators may contact either of the following individuals to set up test accounts: Dan Keegan (480) 451-1117 x4721 / [email protected] Vickie Hennings (972) 377-9500 x167 / [email protected]

462

Check Services Test Information TeleCheck International, Inc. (TECK)

Test System Phone Number: 1-800-366-8950 Site ID: 0005055522

CrossCheck (CRCK)
Test System Phone Number: 1-800-654-7346 Store#: 28324 Check: 123 State: ZZ DL#: 123456 Amount: 1.00

Certegy (EFAX)
Test System Phone Number: 1-800-237-2626 SiteID: 1009663305

463

Integration Troubleshooting
The first step in troubleshooting an integration issue is to rule out the possibility that the issue might be occurring in the PCCharge transaction engine. To determine if PCCharge is causing the problem, run the transaction directly from the PCCharge GUI. If an error occurs or the transaction is unsuccessful when processed directly from the PCCharge GUI, the issue is most likely a merchant setup or communication issue. These types of problems must be resolved before any integration troubleshooting can occur. If a merchant is using a licensed copy of PCCharge with a live merchant account, they should contact VeriFone, Inc.s technical support department to resolve the issue. If an integrator is using one of test merchant accounts that are included in the DevKit, the integrator should contact VeriFone, Inc.s development support department to resolve the issue. Once it has been determined that PCCharge is not returning the error or is cause of the problem, several tools are provided that can be used to troubleshoot the integration issue. In general, most integration issues are related to message formatting and are caused by missing or invalid properties or the invalid formatting of values. To narrow down which properties or values are causing the problem, a comparison should be made of the transaction request that is being submitted by the integrated application and the transaction request that is submitted by the PCCharge GUI. To make this comparison, first activate IO Logging in PCCharge (see below), and then run the transaction from the PCCharge GUI. After successfully running the transaction from the PCCharge GUI, run the same transaction from the integrated application. The IO Log will capture the details from both transactions, thus allowing the integrator to compare the transaction requests and determine which properties or values are causing the problem.

IODebug.log
The IODebug.log is a text file created by the PCCharge that can be used to view the transaction requests and responses that are processed by PCCharge. Logging to the IODebug.log file is disabled by default. To activate IO Logging in PCCharge, go to setup, configure system, system log. Place a checkmark under Create IODebug.Log File or, from the PCCharge GUI, hold down the Shift key and then hit the F11 key. Once logging has been enabled, the text IOLog Enabled will appear in the title bar of PCCharge. While logging is enabled, every transaction request and response (whether submitted from the PCCharge GUI or via integration) will be placed in the file IODebug.log. This file will be located in the PCCharge directory. The following is an example of the type of information that will appear in the IODebug.log file: "===================================" "PCCharge Pro for Windows v5.7.1" "-----------------------------------" "INX : 06/03/04 10:40:21 >> C:\Program Files\PCCW\User1 <XML_FILE> <XML_REQUEST><USER_ID>User1</USER_ID>... "OUX : 06/03/04 10:40:22 >> <XML_FILE><XML_REQUEST><USER_ID>User1 </USER_ID> <RESULT>Error</RESULT>... Note: In this example, text has been truncated and replaced with . The data following INX represents the details of request message and the data following OUX represents the details of the response message. The actual XML message used to process the transaction starts with <XML_FILE> tag on the INX line.

464

Note: In order to view the contents of the IODebug.log in a more readable fashion, copy just the XML message (<XML_FILE>[contents]</XML_FILE>) to a new text file. Use the extension of .xml when saving the text file. Open this new file using Internet Explorer. Internet Explorer will automatically show the XML message in a more readable format.

PCCharge Internal Use Tags

When viewing the contents of the IODebug.log, integrators will notice that there are several tags that appear in the request message that are not documented in the DevKit manual. These tags are added to each transaction request by PCCharge automatically and are reserved for Internal Use. With the exception of TROUTD, integrators should ignore these tags when determining the cause of integration issues. The tags that are reserved for internal use include (but are not limited to) the following: RESP_TYPE INTRN_SEQ_NUM INP_TYPE ENHANCED_TRANS_FLAG IMPORT_TRANS_FLAG TXN_METHOD IS_PURCHASE_CARD TROUTD (This property should be passed by integrators when performing follow-on transactions, but is automatically populated for transactions such a Sales, Credits, Pre-Authorizations, etc.)

Transaction Request Duplication

PCCharge has the ability to create a duplicate of each transaction request that is submitted to PCCharge. Unlike the IODebug.log file, the contents of the files created by this feature are encrypted. The contents of these files can only be viewed by VeriFone, Inc. support representatives. These files may be requested by VeriFone, Inc. support representatives to assist in troubleshooting. Transaction Request Duplication is disabled by default. To activate this feature, from the PCCharge GUI, hold down the Shift key and then hit the F10 key. Once this feature has been enabled, the text TransDup Enabled will appear in the title bar of PCCharge. While this feature is enabled, every transaction request will be duplicated and placed in an individual file located in the PCCharge directory. The filename will include the user name, the date and time of the transaction request, and will have an extension of .dup.

Communication Log
Another tool that can be used for troubleshooting purposes is the PCCharge Communication log. This log records the information that is passed from PCCharge to the processor. This feature is used to log communication for both modem-based and Internet-based processors. Communication logging is disabled by default. To activate communication logging, access the modem settings screen from the Setup menu in PCCharge. (If the Simple Modem Setup screen appears, click the Use Manual Modem Setup button.) Click the Advanced button and then check the Create Log File option. If the modem log will be sent to VeriFone, Inc. for assistance in troubleshooting a problem, the Encrypt Log File option must be checked and a 16-digit password must be supplied in order to encrypt

465

the file. If the file will be used by the integrator or merchant to troubleshoot the issue locally, the Encrypt Log File option must be unchecked so that the contents of the log file are readable. Once the communication log has been activated, a file called Logfile.PCC will be created in the PCCharge directory.

Error Log
PCCharge supports error logging. This feature is always enabled. Any time PCCharge encounters an internal error, the date, time, transaction number, and a description of the error will be written into a file named ErrLog.PCC. This file appears in the PCCharge directory. The information in this file can be used to troubleshoot integration issues. The most common errors that would be logged would be permission errors, database errors, and runtime errors. Note: Occasionally, information will be written to this file that is intended for informational purposes only. The existence of data in this file does not necessary indicate that an error has occurred while PCCharge is processing transactions.

Troubleshooting a Live Installation

If designed properly, integrated applications should always check for the existence of the file SYS.PCC in the PCCharge directory prior to submitting transactions. This check provides a method that can be used when troubleshooting a live customer site. When troubleshooting, it is often beneficial to see the exact contents of the .INX file that the integrated application is submitting to PCCharge. Of course, when PCCharge is running and an integrated application submits a transaction, PCCharge begins processing the transaction immediately, thus deleting the .INX file before it can be retrieved. If PCCharge is not running, the integrated application will indicate an error rather than submitting the transaction. To get around this, simply close PCCharge and then delete the SYS.PCC file prior to submitting the transaction. This procedure will circumvent the SYS.PCC check that is built into the integrated application. Once the transaction is submitted by the integrated application, the .INX file will be placed into the PCCharge directory. This file can now be moved or copied from the PCCharge directory. And, using the other tools mentioned in the section, the file can be compared to other .INX files or forwarded to VeriFone, Inc. support representatives.

466

Contacting Support
Although the tools noted in this section are provided to assist integrators in resolving integration issues, it may still be necessary to contact VeriFone, Inc.s development support department for assistance. Prior to contacting support, it is suggested that all logs are activated while processing the transactions that are causing the issue(s). The logs should be reviewed by integrator and the following may be requested by VeriFone, Inc.s developer support department: IODebug.log ErrLog.PCC Logfile.PCC Any .INX or .OUX files related to the transaction(s) Any .DUP files related to the transaction(s)

Contact information for the developer support department can be found in the section Support Policy (see page 471).

467

Distribution and Deployment

VeriFone, Inc. offers a variety of distribution and deployment methods to fit the resellers needs and resources. They are designed to reduce errors, streamline logistics, reduce shipping, and maximize deployment. VeriFone products require activation for live use. Activation requires an activation code derived from the products serial number and the individual merchants account number.

Distribution Methods
Full Distribution
VeriFones full distribution with packaged CD, user manual, and serial number is the traditional method of deploying our software CD products directly to the merchants for loading, activation, setup, and configuration. Activation information can be pre-loaded prior to shipment or loaded at the time of installation. Setup installation includes: Load Software Activate Serial Number Merchant Account Number Activation Code Configure Systems Password and Preferences Queuing and Communications Company Information Address Verification Printers Modem Advanced Configuration User Setup Credit Setup Debit Setup Check Setup Other Devices

Fast Distribution
VeriFone provides streamline activation and registration of products shipped through third party deployment to merchants. Through VeriFone fast activation, serial numbers and information is exchanged by e-mail. Registration is completed through an Internet connection to VeriFones Registration Server. Setup installation includes: Load Software Activate with Pre-Configured Setup File with Serial Number, Merchant Account Number, and Activation Code Configure Systems As Above

468

Master Disk Distribution

Master Disk distribution deploys products embedded into the POS or eCommerce solutions. This Master Disk copy provides better version control and allows easier distribution with developers applications. With Master Disk, no physical packaged media is required, only the purchase of licensed serial numbers. Activation only requires the pre-purchased serial number. Master Disk activation is authorized for new installs only, not for upgrades of existing or previously installed licenses. Contact your VeriFone Sales representative for more details on embedding and the Master Disk deployment program.

Embedding
As part of the Master Disk distribution program, participating developers are authorized to embed and automatically install one of VeriFones payment processing engines (PCCharge Payment Server or PCCharge Pro) onto each merchants computer as long as the payment processing engine is configured to run in Demo Mode. To configure either the payment processing engines to run in Demo mode, modify the PCCharge shortcut icon to include the /d command line switch. For example: PCCharge Pro: "C:\Program Files\PCCW\Pccw.exe" /D PCCharge Payment Server: C:\Program Files\Active-Charge /D

Important Note: Prior to activation, the Demo mode command line switch must be deleted to enable LIVE mode.

Demo Mode
PCCharge Payment Server or PCCharge Pro can be demonstrated in Demo Mode. In Demo Mode, pseudo-transactions will simulate transactions with sample data without actually communicating to the processor. Important Note: Prior to activation, the Demo mode command line switch must be deleted to enable LIVE mode.

Evaluation Mode
VeriFone products can be set up in Evaluation Mode with the test merchant accounts. In Evaluation Mode, PCCharge can communicate to various payment processor test sites using the modem or an Internet connection. An actual authorization takes place, but no funds are transferred. Testing under Evaluation Mode is reserved for developers doing interface testing and proof-of-concept testing. For more information on setting up the test merchant accounts to enable Evaluation mode, refer to the section Install the Test Merchant Accounts (see page 16).

Warehousing/Block Inventory
Resellers may purchase blocks of inventory to be stocked at VeriFone for later deployment. VeriFone warehousing prevents reseller inventory from becoming obsolete. CDs are not produced until the reseller is ready to install, thereby; the reseller always receives the most current version of our products. With Master Disk distribution, no CDs are produced, only serial numbers that are sent to resellers at the time of the original purchase order. At the time of installation, resellers will supply their customers or submit activation orders to VeriFone for activation. Upon activation, one license will be deducted from the resellers block of inventory.

469

Activation
VeriFone products require activation, setup, and configuration to properly function. Without precise setup and configuration, there will be a high probability that the electronic payment-processing software will not process transactions properly. Activation cannot occur without the proper merchant and processor information from the Merchant Services Provider. Therefore, it is very important during the initial setup to have the information available. Accuracy and completeness in setup will yield many dividends in reducing technical support and higher customer satisfaction.

Activation requires three components: 1. Serial Number Example: 0002 0000 000001 51 First 4 numbers -- Specific to company buying licenses from VeriFone. Second 4 numbers -- reserved for VeriFone. Last 8 numbers -- unique to merchant. Test Serial Number: 1234 1234 123456 54

2. Merchant Account Number From the Merchant Services Provider (MSP): The merchant account number can only come from the organization providing transaction services. Normally, the organization sending the merchant its monthly statement will provide the merchant account number and the processor being used.

3. Activation Code From the combination of the Serial Number and Merchant Account Number: At the time of installation, the activation code can be obtained from online setup options located on VeriFones website (www.pccharge.com), through the Reseller Den, or by calling the PCCharge Technical Support department (877-659.8981). If you do not have access to the Reseller Den, contact [email protected] to request your login and password for this valuable resource.

470

Support Policy
Philosophy
VeriFone prides itself on its exceptional customer service, and we recognize that our success in the market is directly tied to the quality of our support. Our staff undergoes continual training not only on our own product offerings, but also on Windows, modems, and other hardware.

Contact
Toll-Free Technical Support Line: (877) 659-8981 Toll-Free Developer Support Line: (877) 659-8983 Technical Support E-mail: [email protected] Developer Support E-mail: [email protected]

More Information
Support Policy
The most up-to-date information about VeriFone, Inc.s support resources can be found on the web. The following is a link to the Support Policy: http://www.pccharge.com/downloads/files/SupportPolicy.pdf

Reseller Web Site

VeriFone has created a Reseller's Den on its web site at www.pccharge.com. To access it, click the Developer link from the main index (to the left). Then, click the Reseller's Den link. To obtain a Login and Password, you'll need to be a certified VeriFone reseller. Contact our Sales Department for more information.

471