Payment Client

Transcription

1 Payment Client Deployment Guide Version 1.0

2 Disclaimer Copyright 2009 TNS Payment Technologies Pty Ltd ("TNS"). All rights reserved. This document is provided by TNS on the basis that you will treat it as confidential. No part of this document may be reproduced or copied in any form by any means without the written permission of TNS. Unless otherwise expressly agreed in writing, the information contained in this document is subject to change without notice and TNS assumes no responsibility for any alteration to, or any error or other deficiency, in this document. All intellectual property rights in the Document and in all extracts and things derived from any part of the Document are owned by TNS and will be assigned to TNS on their creation. You will protect all the intellectual property rights relating to the Document in a manner that is equal to the protection you provide your own intellectual property. You will notify TNS immediately, and in writing where you become aware of a breach of TNS' intellectual property rights in relation to the Document. The names TNS, any product names of TNS including Dialect and QSI Payments and all similar words are trademarks of TNS and you must not use that name or any similar name. TNS may at its sole discretion terminate the rights granted in this document with immediate effect by notifying you in writing and you will thereupon return (or destroy and certify that destruction to TNS) all copies and extracts of the Document in your possession or control. TNS does not warrant the accuracy or completeness of the Document or its content or its usefulness to you or your merchant cardholders. To the extent permitted by law, all conditions and warranties implied by law (whether as to fitness for any particular purpose or otherwise) are excluded. Where the exclusion is not effective, TNS limits its liability to $100 or the resupply of the Document (at TNS' option). Data used in examples and sample data files are intended to be fictional and any resemblance to real persons or companies is entirely coincidental. TNS does not indemnify you or any third party in relation to the content or any use of the content as contemplated in these terms and conditions. Mention of any product not owned by TNS does not constitute an endorsement of that product. This document is governed by the laws of New South Wales, Australia and is intended to be legally binding.

3 Contents Preface 7 Welcome to TNS... 7 About Payment Client... 7 Payment Client Documentation Set... 8 Contacting Support Payment Client Overview 11 What are e-payments? The Components of an e-payment Solution How e-payments Transfer Funds About e-payment Information Flows Integrating Payment Client 15 How to Select an Integration Model Selection Guidelines for Integration Models How to Select an Interface Selection Guidelines for Interfaces Before You Start 21 Prerequisites Java Runtime Environment (JRE) Requirements Supported Platforms Included Software Connection Details Information Required for a Java Interface Information Required for a Sockets Interface Information Required for a COM JNI Interface Installing Payment Client 27 Ensure Windows Compatibility Install a Single Payment Client Step by Step COM Installation Use COM With an Existing Payment Client PCService Use COM and Install a new Payment Client PCService Use COM and Install a Payment Client using Java JNI Step by Step Installation for a Java Interface Step by Step Installation for a Sockets Interface Install Multiple Payment Clients Step by Step Installation for Multiple Payment Clients Testing Payment Client 47 Page iii of 110 Use the Diagnostic Tool Obtain the Prerequisites for the Diagnostic Tool Configure the Diagnostic Tool (TNS hosted only) Run the Diagnostic Tool Fix Communication Errors Test the Sockets Interface Test PCService Use the PCCOM Test Tool Run the Example Code Upgrading from Earlier Versions 53

4 iv Contents Prepare for Your Upgrade Java Interface Sockets Interface COM Interface Upgrade Your Existing Payment Client Update Your Application Integration Java Interface Sockets Interface COM Interface Roll Back Your Application Integration Java Interface Sockets Interface COM Interface Managing Payment Client 77 Starting and Stopping Payment Client Starting Payment Client Stopping Payment Client Restarting Payment Client Linux-related Issues on PCService Managing Connectivity Test Connectivity Managing Security Microsoft Windows COM Installations Socket and Java Installations Secure Key Files Configuration Files Uninstall Payment Client 85 Glossary 87 Acquiring bank API Authentication Basic Authentication Bank Issuing Bank Merchant s bank Cardholder s bank Cardholder Card not present transaction Payment Response Payment Request Digital Signature e-commerce e-payment Financial transaction Interface Interactive Voice Response (IVR) IVR Application Java Virtual Machine (JVM) JSSE Payment Client ID Payment Server POS Real-time Sockets SSL Page iv of 110

5 Contents v TCP/IP Transaction Appendix A - Configuration Syntax 93 Key Files Payment Client Setup Logging Configuration Test Card Numbers Configure PCService COM DLL Configuration COM Installation Error Codes Appendix B 103 How Merchant-hosted Payments Work Merchant-hosted Information Flow Appendix C 105 How TNS-hosted Payments Work TNS-hosted Payment Information Flow How TNS-hosted Payments are Processed Index 109 Page v of 110

6

7 7 Payment Client Deployment Guide C HAPTER 1 Preface Welcome to TNS TNS Payment Technologies Pty Ltd. ("TNS") is the global communications company that enables payments, money or voices to move around the world. Our secure network is used by leading retailers, banks/processors, telecommunications companies and the financial markets - enabling the world to transact. TNS Merchant Payment Gateway solution offers a complete range of services that enable merchants to accept payments over the Internet and from other card-not-present channels. This includes any payment application where the cardholder is not present at the point-of-sale, such as call centres, IVRs, and recurring billing systems. As part of the TNS Global Payment Gateway range of solutions, our services enable merchants to authorize and settle multi-regional card transactions securely, reliably and cost-effectively. Today, our Merchant Payment Gateway solution represents the platform of choice for over 15,000 merchants, two major global card schemes, and 70+ banks worldwide. In addition, the solution utilizes the resilient, state-of-the-art TNS global network that transports billions of transactions each year. For more information on how TNS can help you with your payment processing needs, visit our website at About Payment Client Payment Client does real-time online payment processing with a variety of transaction modes to provide merchants and enterprises with an affordable Internet based payment system.payment Client supports payment from the web, Call Centres, and Interactive Voice Response systems; in fact Payment Client supports any merchant application that requires processing for credit cards in Card Present and Card Not Present transactions. Payment Client is a Java application that encrypts and digitally signs the orders going to the Payment Server. It also checks the digital signature and decrypts the receipt details being returned from the Payment Server. Payment Client allows transactions to be performed through an integrated application. It uses multiple encryption techniques to securely transmit sensitive financial data across the Internet to the Payment Server. Key enhancements in Payment Client are: enhanced security using: 1024-bit RSA keys for server and client communication in 3-party transactions server-side authentication for 2-party transactions. The server authenticates itself to the client using a digitally signed certificate from CA. The client validates the certificate using a copy of the CA digital certificate. The client also authenticates the host name before connecting to the server. Page 7 of 110

8 8 Payment Client Deployment Guide new installer with support for Java 1.5 and 1.6 versions support for the following operating systems: Windows 2000 (SP4), Windows XP (SP3), Windows Server 2003, Windows Server 2008 RHEL3, RHEL4, RHEL5 Solaris 8, Solaris 9 (Sparc), Solaris 10 (Intel and Sparc) MAC OSX v10.4, MAC OSX v10.5 Payment Client Documentation Set This document, Payment Client Deployment Guide, provides an overview of Payment Client, and contains instructions on installation and management tasks. For detailed information about integrating Payment Client with a merchant application, you will need to consult the following additional documents: Payment Client Integration Guide describes how to integrate Payment Client into your architecture and environment. Payment Client Reference Guide provides detailed reference information on the Payment Client API. Audience The Payment Client documentation set is designed for developers deploying the Payment Client in a suitable environment. It is assumed that you have at least the following: Intermediate level of technical knowledge, for example, IT graduate with 2-3 years experience. Familiarity with operating systems and basic system administration tasks for example, installing software and services and configuring the web server. Familiarity with the web environments for client-server applications. Ability to configure and debug development and deployment environments. Page 8 of 110

9 Payment Client Deployment Guide 9 About this Document The Payment Client Deployment Guide is part of the Payment Client documentation set. It contains information on how to install, configure, and manage Payment Client. In addition, this guide contains conceptual information that you should read before you attempt to install the product. The organisation of this guide is summarised below: Payment Client Overview on page 11 describes how e-payments work. Integrating Payment Client on page 15 helps you to select the most suitable integration model and interface for your environment. Before You Start on page 21 describes how to prepare to install Payment Client. Installing Payment Client on page 27 describes how to install Payment Client. Testing Payment Client on page 47 describes how to test Payment Client, PCService and the environment. Upgrading from Earlier Versions on page 53 describes how to upgrade your previous installation of Payment Client. Managing Payment Client on page 77 describes how to fine tune Payment Client to suit your requirements, if necessary. Uninstall Payment Client on page 85 describes how to uninstall your new Payment Client using the uninstaller and manually. Glossary on page 87 provides a list of commonly used terms in this document with their meanings. Appendix A on page 93 describes how to configure Payment Client for your environment using the property files. Appendix B on page 103 describes how merchant-hosted payments work. Appendix C on page 105 describes how TNS-hosted payments work. This symbol, when it appears in this manual, warns you of a potential problem. If the problem occurs, you may need to stop and get assistance. The Light Bulb symbol, when it appears in this User Guide, indicates additional information that is supplementary to the main text. Related Documents Merchant Administration User Guide describes how to monitor and manage your electronic transactions, and create and view reports, via user-friendly pages. Page 9 of 110

10 10 Payment Client Deployment Guide Contacting Support If you need help integrating Payment Client in your merchant application, please contact your Technical Support group. The information in this document is accurate at the time of publication; however, there may be inaccuracies when applying this document to the Payment Client in use. For further information, please contact your Technical Support group. Page 10 of 110

11 11 Payment Client Deployment Guide C HAPTER 2 Payment Client Overview This section is an overview of electronic payments or e-payments and how they are processed by Payment Client. You must be familiar with this information and understand the core concepts before attempting to install or update Payment Client. What are e-payments? e-payments are secure real time payments that transfer funds (via the Internet) between a consumer and the merchant s financial institutions. This is represented in the following diagram: e-payments require secure communication between all components of the e-payment process. Page 11 of 110

12 12 Payment Client Deployment Guide The Components of an e-payment Solution An end-to-end e-payment solution is made up of the following components: The Merchant application is a business application running on the merchant s system that uses Payment Client to process payments. The Integration module is a communication bridge between the merchant application and Payment Client. Payment Client provides secure communication between the merchant application and the Payment Server. Payment Client can be integrated with a number of systems including merchant applications, Interactive Voice Response (IVR) systems, and integrated ERPs Payment Server processes merchant transaction requests in real time by sending messages to the payment provider and Payment Client. The Payment Provider (also called the acquirer, acquiring bank or merchant bank ) enables the merchant s facility to accept payments online. It is where the merchant maintains their business banking account and deposits payments. How e-payments Transfer Funds e-payments transfer funds via the following steps: 1 The cardholder purchases goods/services from the merchant (for example, in person, via the Internet, over the phone). 2 The merchant application sends a Payment Client request (via the Payment Server) to the merchant s payment provider. 3 The merchant s payment provider directs the request to the cardholder s bank. 4 The cardholder s bank debits the cardholder s account and transfers the funds to the merchant s account. About e-payment Information Flows This section describes how information is transferred between the merchant application and the Payment Server. The Merchant Application To process a payment, the merchant application must send the required information to the Payment Server. The merchant application uses the Payment Client to send this information to the Payment Server using two messages: Transaction Request is sent by the Payment Client to the Payment Server to provide transaction information. Transaction Response is sent from the Payment Server to the Payment Client to indicate the outcome of the transaction (that is, successful or otherwise). A Transaction is the combination of a Transaction Request and a Transaction Response. For each customer purchase or order, merchants may issue several transactions. Page 12 of 110

13 Payment Client Deployment Guide 13 The Payment Client To securely communicate transaction information between the merchant application and the Payment Server, Payment Client: Formats, encrypts and digitally signs a Transaction Request from the merchant application; and Sends the Transaction Request to the Payment Server Receives the Transaction Response, decrypts it and processes the results. The Payment Server To complete the transaction the Payment Server: Processes the Transaction Request Transfers funds from the cardholder's account to the merchant's Payment Provider account and Returns a signed and encrypted Transaction Response to Payment Client. Page 13 of 110

14

15 15 Payment Client Deployment Guide C HAPTER 3 Integrating Payment Client Payment Client can be used in a variety of different environments and offers a number of different integration options. You must select the most appropriate options for your environment before you begin to deploy Payment Client. To determine the best way to integrate e-payments in your merchant application, you need to understand the areas where you can choose different options, and the advantages and disadvantages of each. This section provides basic information on how to enable your merchant application to process e- payments. Note: It is important that you choose the relevant options before starting the installation, as the installation prompts you for related information. How to Select an Integration Model on page 15 answers this question: Who will manage the payment process (that is, the merchant or the Payment Server)? How to Select an Interface on page 15 answers this question: How will your merchant application communicate with the Payment Client? To identify the best options for your environment, you must understand how e-payments work, as well as the advantages and disadvantages for each option. How to Select an Integration Model The integration model determines who manages the payment process. Two integration models are discussed in this section. It describes how to select an integration model for communicating with the Payment Server. It can be either: 2-Party payments is where the cardholder interacts with the merchant application only and the merchant must collect the required information (for example, credit card number, expiry date, etc). This is also called merchant-managed or direct method payments. For more information, see Appendix B on page 103. Note: 2-Party payments are higher risk than 3-Party payments as you (the merchant) are responsible for collecting cardholder card information. 3-Party payments is only for web shop transactions where the cardholder's browser is redirected away from the merchant's web site to the payment provider s site to collect the required information (for example, credit card number, expiry date, and so on). This is also called servermanaged or re-direct method payments. However, 3-Party Payments do also allow you to collect card details on your web site and pass them through with the other transactional details. If this is done the Payment Server does not display any 3-Party branded pages, keeping the branding consistent throughout the whole transaction. To do this you would have to comply with the same obligations associated with 2- Party payments noted for 2-Party payments. For more information, see Appendix C on page 105. Page 15 of 110

16 16 Payment Client Deployment Guide Selection Guidelines for Integration Models Use the following guidelines to select an integration model, depending on your application, preferred communication method, security needs, and future plans. When to use 2-Party Payments Consider using 2-Party Payments if: You are willing to collect card details and manage the associated security and privacy issues. (VISA AIS, MasterCard SDP and so forth). You are integrating an application with the Payment Client (for example, web, call centre, billing application, Interactive Voice Response (IVR) system) that does not use 3-D Secure authentication (for example, Verified by Visa and MasterCard SecureCode ). For more information see Payment Authentication. You do not want the cardholder's browser to be redirected away from your web site to the Payment Server for payment processing. You do not want to display Payment Provider-branded pages in the payment flow. When to use 3-Party Payments Consider using 3-Party Payments if: You are integrating a web browser-based application only. Call centres, IVRs and other applications cannot use this transaction mode. You want to, either now or in the future, increase security by using 3-D Secure authentication (for example, Verified by Visa and MasterCard SecureCode ). It is acceptable to have the cardholder's browser redirected away from your web site to the Payment Server. You want the Payment Provider to collect and manage the cardholder s card details and to manage the associated security and privacy issues. It is acceptable to display Payment Provider-branded pages in the payment flow. Note: If you require branding to be consistent throughout a transaction, you can collect card details and include them into the Transaction Request. However the higher risk and responsibility of collecting card details remains the same as in a 2-Party transaction. Page 16 of 110

17 Payment Client Deployment Guide 17 When to combine 3-Party and 2-Party Payments Consider using both 2-Party and 3-Party if any of the following are true: You want to use a combination of 3-Party for Web and 2-Party for call centre/ivr/other applications. You have a web application in which you want to perform some form of repeat payment, as in a subscription, where you want to take advantage of 3-D Secure authentication for the first payment and then use 2-Party payment transactions for each subsequent installment payment. (You must capture and store the card details to do this). You are willing to use 3-Party transactions for payments and are also using other transactions like refunds and queries, which are all 2-Party mode transactions. Note 1: If you are collecting card details and want to implement 3-D Secure authentication, you only need to perform 3-Party transactions for those transactions that require 3-D Secure authentication like MasterCard and Visa. Other transactions that don't use 3-D Secure authentication such as Bankcard and American Express can be performed using 2-Party transactions as they don't support Authentication. Note 2: Advanced Merchant Administration functions such as captures, refunds, voids and queries all use the 2-Party style of transaction, so if you need to use any of these transaction types through the Payment Client, you will also need to install the Payment Client with the 2-Party options installed. These operations, captures, refunds, voids and queries carry no higher risk than 3-Party as you do not need to pass in cardholder card information to carry out these transaction types. Page 17 of 110

18 18 Payment Client Deployment Guide How to Select an Interface In addition to the integration model, you must select the most appropriate interface to access Payment Client from your merchant application using one or more of the following interfaces: Java interface communicates directly with the Payment Client using native Java calls from the merchant application running in the same Java Virtual Machine (JVM). This method can be used on any operating system that supports Java, however only one Payment Client can be installed in the same JVM using this interface. TCP/IP Sockets allows a merchant application to communicate to a Payment Client located on the same machine, or on any other machine on the same local secured network via a Payment Client TCP/IP sockets listener (called PCService). More than one Payment Client can be installed using this method. Any programming language that supports TCP/IP Sockets can use this interface. Note: In a situation where the system administrator is unable or unwilling to install a Java Runtime Environment (JRE) on an application machine to run the Payment Client, the ideal solution is to install Payment Client on a separate machine with a JVM and communicate via sockets. COM (Microsoft Windows only) is a variant of the Java installation for Microsoft based programs. It provides a separate component to communicate with the Payment Client via a DLL using: Sockets-based installation in which the DLL connects to the PCService using TCP/IP sockets to pass socket requests and responses. The DLL communicates with a PCService installed on the local machine (or on a separate machine on the local secured network). More than one Payment Client can be installed in the same JVM using this method. If the DLL is communicating with a PCService operating on a separate machine, it does not require a Java Runtime Environment to be present on its own machine for the DLL to operate. Java-based installation that uses a Java Virtual Machine (JVM) and instantiates the Payment Client in the JVM. This allows commands to be passed from the DLL to the Payment Client via JNI. Only one Payment Client can be installed in the same JVM using this interface. The DLL and Payment Client must be installed in the same machine. Selection Guidelines for Interfaces This section describes how you should select the best interface for your environment. Page 18 of 110

19 Payment Client Deployment Guide 19 Use the Java interface Use the Java interface if the following describes your environment: The operating system supports Java. The application that is to be integrated with Payment Client is either Java based or able to support Java objects. Payment Client must be locally installed on the same host as the application to be integrated with the Payment Client. Only one Payment Client is to be installed. Multiple merchant profiles can be accommodated on the same Payment Client in the following manner They are all on the same Payment Server AND Your Payment Service Provider has configured all profiles to use the same Payment Client (as designated by a single PaymentClientID). Use the Sockets interface This interface provides the most generic interface across most programming environments. Use the sockets interface if the following describes your environment: The application that is to be integrated with Payment Client supports TCP Sockets based communication. You want flexibility of installation and operation. A centrally located shared Payment Client is required for multiple applications and/or hosts for ease of management and deployment. You need to install multiple Payment Clients, now or at some future date. Page 19 of 110

20 20 Payment Client Deployment Guide Use the COM interface Use the COM interface if the following describes your environment: The Microsoft based application that is to be integrated is not able to support TCP/IP Sockets. The COM.dll is being installed on a Microsoft Operating System. Use COM with Sockets Use the COM interface with sockets if the following describes your environment: You want flexibility of installation and operation. A COM object is provided to abstract TCP sockets communications. The COM Object can access a Payment Client installed with the sockets interface via a secured local network. The Payment Client with the sockets interface can be installed on the same host or on a centrally located host. You need to install multiple Payment Clients, now or at some future date. Multiple Payment Clients can use the single COM installation by connecting to different TNS Payment Client. Use COM Use COM with Java JNI Use the COM interface with Java JNI if the following describes your environment: You cannot or do not wish to use the COM with Sockets interface. The Payment Client must be locally installed on the same host as the application to be integrated with. Only one Payment Client is to be installed. Multiple merchant profiles can be accommodated on the same Payment Client as long as they are all on the same Payment Server and your Payment Service Provider has configured all merchant profiles to use the Payment Client that is being installed, as designated by the same PaymentClientID. The operating system supports Java. Page 20 of 110

21 21 Payment Client Deployment Guide C HAPTER 4 Before You Start Before you install Payment Client you should ensure that: Payment Client supports the environment in which the installation will take place You understand the software that will be installed with Payment Client You have considered the integration strategy you are going to adopt once Payment Client has been installed Prerequisites To install Payment Client you need: Java Runtime Environment (JRE) installed on your server Administrator or root privileges, allocated by your System Administrator Valid Merchant ID issued by the payment provider Java Runtime Environment (JRE) Requirements Payment Client requires at least JRE V1.3.0 with Java Secure Sockets Extensions (JSSE). The supported Java versions are Sun Microsystems Inc JRE versions 1.3.x+. Note: Payment Client v3.2 is not compatible with any version of Java older than Sun Microsystems Inc, Java JRE or the Microsoft Virtual Machine. JSSE is part of the standard installation for Sun Microsystems Inc JRE It is an optional installable download for JRE 1.3.x from the Sun Microsystems Inc Java Website (see For more information on Java or to download the JRE, see The Payment Client is a Java Application and works in any environment supporting a JRE equivalent to the Sun Microsystems Inc JRE version or higher. However, TNS only supports the Payment Client on the platforms detailed in Supported Platforms on page 22. Page 21 of 110

22 22 Payment Client Deployment Guide Supported Platforms Payment Client 3.2 is supported on the following platforms: Microsoft Windows XP (SP3) Microsoft Windows 2000 (SP4) Microsoft Windows Server 2003 (SP2) Microsoft Windows Server 2008 (SP2) Solaris 8, Solaris 9 (Sparc), Solaris 10 (Intel and Sparc) Red Hat Linux RHEL 3 Red Hat Linux RHEL 4 Red Hat Linux RHEL 5 Mac OSX v10.4, OSX v10.5 Included Software Payment Client ships with the following third party cryptographic libraries: Bouncy Castle Crypto APIs V1.43 Copyright (c) 2000 The Legion Of The Bouncy Castle. For more information, see Bouncy Castle - Clean Room Java Cryptography Extensions (JCE) V1.43 Copyright (c) 2000 The Legion Of The Bouncy Castle. For more information, see Note: JCE is only required when running Payment Client in a 1.3.x Java Runtime Environment without a JCE. Payment Client 3.2 also ships with the following libraries: Library commons-lang-2.4.jar commons-logging jar commons-httpclient jar commons-io-1.0.jar log4j.jar jakarta-regexp-1.5.jar Source Page 22 of 110

23 Payment Client Deployment Guide 23 Connection Details As part of the installation process you will need to specify details of the client-server connections you will need to make in order to process transactions. For this purpose you should determine the host IP addresses and port numbers of all payment servers with which Payment Client will potentially connect. Instructions for using this information are provided in Installing Payment Client on page 27. Information Required for a Java Interface Use the table to enter the details prior to installation. At installation, refer to this table to enter the correct options for your interface. Item Location of a compatible JVM (java.exe) Details Installation Directory The directory where Payment Client will be installed. Windows default C:\Program Files\Transaction Network Services\PaymentClient Unix/Linux default /opt/transaction Network Services/PaymentClient Proxy Configurations None SOCKS4 SOCKS5 HTTP NTLM Proxy Details not required for None" Proxy Address Proxy Port Username (Optional) Password (Optional) (not required for SOCKS4) Domain (Optional) (only required for NTLM) Location of folder for shortcuts icons Page 23 of 110

24 24 Payment Client Deployment Guide Information Required for a Sockets Interface Use the table to enter the details prior to installation. At installation, refer to this table to enter the correct options for your interface. Item Location of a compatible JVM (java.exe) Details Installation Directory The directory where Payment Client will be installed. Windows default C:\Program Files\Transaction Network Services\PaymentClient Unix/Linux default /opt/transaction Network Services/PaymentClient Proxy Configurations None SOCKS 4 SOCKS 5 HTTP NTLM Proxy Details not required for None" Proxy Address Proxy Port Username (Optional) Password (Optional) (not required for SOCKS4) Domain (Optional) (only required for NTLM) Sockets Configuration Payment Client Service Port IP Address/es Install as Windows Service (Windows only) NO YES Windows Service Name Location of folder for shortcuts icons Page 24 of 110

25 Payment Client Deployment Guide 25 Information Required for a COM JNI Interface Use the table to enter the details prior to installation. At installation, refer to this table to enter the correct options for your interface. Note:This is only available on a Windows operating system. Item Location of a compatible JVM (java.exe) Details Location of JVM.dll Installation Directory The directory where Payment Client will be installed. Windows default C:\Program Files\Transaction Network Services\PaymentClient Unix/Linux default /opt/transaction Network Services/PaymentClient Proxy Configurations None SOCKS 4 SOCKS 5 HTTP NTLM Proxy Details Not required for None Proxy Address Proxy Port Username (Optional) Password (Optional) (not required for SOCKS4) Domain (Optional) (only required for NTLM) Location of folder for shortcut icons Page 25 of 110

26

27 27 Payment Client Deployment Guide C HAPTER 5 Installing Payment Client This section describes how to perform a fresh installation of Payment Client 3.2. If you already have an earlier version of Payment Client, see Upgrading from Earlier Versions on page 53. Before installing Payment Client, ensure that you have familiarised yourself with the topics discussed in Before You Start on page 21. Page 27 of 110

28 28 Payment Client Deployment Guide Ensure Windows Compatibility If you are installing Payment Client under Windows 2003 and Windows XP some additional requirements must be considered. If you are not installing the Payment Client under Windows 2003 or Windows XP, you can skip this section. Run the Installer in Compatibility Mode You must ensure that you run the Payment Client installer in Windows 2000 compatibility mode if you require access to COM. To allow the installation of the Payment Client under Windows 2003 Server or Windows XP: 1 Extract the Payment Client bundle that has been provided by your Payment Service Provider to a temporary directory. 2 Right click on the paymentclient_ exe and select Properties from the menu. Page 28 of 110

29 Payment Client Deployment Guide 29 3 Click the Compatibility tab. 4 Select Run this program in compatibility mode for check box. 5 From the drop-down list select Windows Click the [Apply] button. 7 Click [OK]. 8 Proceed with the installation as detailed. Exclude the Payment Client from Windows DEP New security features in Windows 2003 Service Pack 1+ and Windows XP Service Pack 2+ are incompatible with the Payment Client installer, and will cause errors in Payment Client installation. To avoid these errors, when installing the Payment Client under these Service Packs, you must exclude the client installer from Windows Data Execution Prevention (DEP). To exclude the installer from being affected by DEP: Page 29 of 110

30 30 Payment Client Deployment Guide 1 Right click on My Computer and select Properties from the pop-up menu. The System Properties dialog box displays. 2 Click the Advanced tab. 3 In the Performance group, click Settings. The Performance Options dialog box displays. 4 Click the Data Execution Prevention tab. 5 Click Turn on DEP for all programs and services except those I select:. 6 Click Add to add the Payment Client to the list of excluded programs. 7 Navigate to the Payment Client installer file paymentclient_ exe. 8 Select paymentclient_ exe and click OK. 9 Click OK to close the Performance Options dialog box. 10 Click OK to close the System Properties dialog box. Page 30 of 110

31 Payment Client Deployment Guide 31 Install a Single Payment Client The steps for a single installation are: 1 Install the Java Runtime Environment (JRE) and Java Secure Sockets Extensions (JSSE). For more information, see Java Runtime Environment (JRE) Requirements on page Obtain the Payment Client software by downloading the software or extracting the software from as required. 3 Ensure you have all the pre-installation information. See Before You Start on page Extract the files from the distribution to a temporary directory. 5 Start the installer: Windows users click the install file paymentclient_[version].exe (for example,./paymentclient_3_2_0_0.exe) or execute the install file via a command prompt. UNIX/Linux users run paymentclient_[version].bin (for example, paymentclient_ 3_2_0_0.bin) or execute the install file via a command prompt. For GUI installations, the InstallAnywhere installation wrapper requires a colour depth of at least 256 colours; otherwise the installation will fail. On Unix if you cannot run the installer in a GUI, use the text-based version in the console window using i console option. For example,./paymentclient_3_2_0_0.bin i console 6 Follow the prompts and enter the relevant information as required to install the Payment Client. Assuming you have all the pre-installation information (see Before You Start on page 21), installation time on Windows or UNIX/Linux is approximately 5 minutes. 7 The following sections detail step by step examples. If required you can always run the installer again to install a different interface. For a Step by Step COM Installation (see Step by Step COM Installation on page 32). Step by Step Installation for a Java Interface (see Step by Step Installation for a Java Interface on page 45). Step by Step Installation for a Sockets Interface (see Step by Step Installation for a Sockets Interface on page 46). Page 31 of 110

32 32 Payment Client Deployment Guide Step by Step COM Installation The COM option only displays on Microsoft Windows operating systems. There are three different types of COM installations. Use COM with an existing Payment Client PCService. This is the preferred option if a Payment Client sockets listener (PCService) is installed. You may have to configure PCService to accept connections from this host. You can add or remove hosts post-install by editing PCService.properties file. Use COM and install a new Payment Client PCService. Use this option if a PCService is not installed, or a new PCService is required. If other hosts will also connect to this PCService then it will have to be configured to accept connections from those hosts, which you can do later during the install. You can add or remove hosts post-install by editing the PCService.properties file. Use COM and install a Payment Client using Java JNI This option does not require PCService to be installed. It is suitable for installations where Payment Client is only required to process a small number of transactions. With this option the COM Object uses JNI to create and connect to a Java Virtual Machine that will instantiate and run the Java Payment Client. The Java Virtual Machine will be recreated each time a COM object is used. 1 After Payment Client installation starts, the Introduction displays. Read the instructions and click Next. 2 In Choose Install Folder, in Where would you like to install? enter the location on your hard drive where Payment Client is to be installed with all its associated files. You can click Restore Default Folder to set the location to "C:\Program Files\Transaction Network Services" or Choose to navigate to a required location. Click Next. 3 In Choose An Installation Type, select No if you are installing Payment Client as a fresh installation. Select Yes if you wish to reuse the configuration parameters from a previous installation of Payment Client. For example, you may want to reuse the parameters configured for Payment Client If you wish to upgrade from your previous installation, skip this section and refer to Upgrading from Earlier Versions on page In Choose Installation Options, select COM. Click Next. Page 32 of 110

33 Payment Client Deployment Guide 33 Page 33 of 110

34 34 Payment Client Deployment Guide Use COM With an Existing Payment Client PCService Follow Steps 1 to 4 on Step by Step COM Installation on page In Select COM Configuration, select Use COM with an existing Payment Client PCService, and click Next. Page 34 of 110

35 Payment Client Deployment Guide 35 2 In COM Configuration existing PCService, enter the IP address of the machine hosting Payment Client PCService and the Port that the service is running on. Click Next. Page 35 of 110

36 36 Payment Client Deployment Guide 3 In Choose Shortcut Folder, select the location in which you want to install shortcut icons for Payment Client. Click Next. Page 36 of 110

37 Payment Client Deployment Guide 37 4 After Payment Client has been configured, the Pre-Installation Summary displays. If correct, click Install. If not, click Previous and correct your selections. Installing the Transaction Network Services Payment Client displays, followed by the Please Wait message. 5 If the installation is successful, the Install Complete message displays. Click Done to exit the installer and begin testing your newly installed Payment Client. For more details, see Testing Payment Client on page 47. If you get an error message, see Error Codes on page 102. Page 37 of 110

38 38 Payment Client Deployment Guide Use COM and Install a new Payment Client PCService Follow Steps 1 to 4 on Step by Step COM Installation on page 32. Then follow these steps: 1 In Select COM Configuration, select Use COM and install a new Payment Client PCService, and click Next. Page 38 of 110

39 Payment Client Deployment Guide 39 2 In Choose a Java Virtual Machine the installer determines the Java Virtual Machines installed on the host. The default path to the Java Virtual Machine is shown, ensure that it is correct and that the java.exe file is in the location shown. Click Next. Page 39 of 110

40 40 Payment Client Deployment Guide 3 On Choose Proxy Configuration, either select None, or, if the network that Payment Client is being installed on requires a proxy to connect to the Internet, select the type of proxy used from SOCKS4, SOCKS5, HTTP, or NTLM. Click Next. If you selected None, go to Step 5. 4 On Enter Proxy Data, enter information on the proxy that you wish to connect to. This information can be updated after installation. Click Next. Page 40 of 110

41 Payment Client Deployment Guide 41 5 In Enter Sockets Configuration, specify the configuration of Payment Client PCService and click Next. Page 41 of 110

42 42 Payment Client Deployment Guide PCService Port Enter multiple IP Addresses, separated by a space. Install Payment Client sockets listener as a Windows Service. Enter the port Payment Client PCService will listen on for incoming connections. Payment Client PCService accepts connections only from hosts specified in the IP addresses. For multiple IP addresses, you must separate each IP address with a space. You may add or remove hosts after you install Payment Client by editing the PCService.properties file. For more information on configuring Payment Client and PCService, see Appendix A - Configuration Syntax on page 93. This option is only available to Microsoft Windows Operating Systems, for example, Microsoft Windows 2000, or XP. If selected, Payment Client PCService will be installed as a service that will start automatically, when a machine is starting or restarted. The service is installed with the name specified in the Service Name field. 6 In Choose Shortcut Folder, select where you want to install shortcut icons to Payment Client. Click Next. 7 After Payment Client has been configured, the Pre-Installation Summary displays. If correct, click Install. If not, click Previous to correct your selections. Installing Transaction Network Services Payment Client displays, followed by the Please Wait message. 8 If the installation is successful, the Install Complete message displays. Click Done to exit the installer and begin testing your newly installed Payment Client. For more details, see Testing Payment Client on page 47. If you get an error message, see Error Codes on page 102. Page 42 of 110

43 Payment Client Deployment Guide 43 Use COM and Install a Payment Client using Java JNI Follow Steps 1 to 4 in Step by Step COM Installation on page In Select COM Configuration, select Use COM and install a Payment Client using Java JNI and click Next. Page 43 of 110

44 44 Payment Client Deployment Guide 2 Follow steps 2 to 4 from Use COM and install a new Payment Client PCService on page In Choose JVM Location, specify the location of the jvm.dll. The jvm.dll file uses the Java JNI technology to create a Java Runtime Environment to communicate with Payment Client from the COM object. The default jvm.dll for the machine displays. Click Next. Follow Steps 6 to 8 of Use COM and install a new Payment Client PCService on page 38. Page 44 of 110

45 Payment Client Deployment Guide 45 Step by Step Installation for a Java Interface Use the steps below to install Payment Client using a Java interface. 1 After Payment Client installation starts, the Introduction displays. Read the instructions and click Next. 2 In Choose Installation Options, select Java. Click Next. (See Choose Installation Options in Step by Step COM Installation on page 32.) 3 In Choose a Java Virtual Machine the installer determines the Java Virtual Machines installed on the host. The default path to the Java Virtual Machine is shown, ensure that it is correct and that the java.exe file is in the location shown. Click Search for Others or Choose Another to browse to and select another java.exe file if necessary. Click Next. 4 In Choose Proxy Configuration, either select None, or, if the network that Payment Client is being installed on requires a proxy to connect to the Internet, select the type of proxy used from SOCKS4, SOCKS5, HTTP, or NTLM. Click Next. If you selected None, go to Step 6. 5 On Enter Proxy Data, enter the Proxy Address and Proxy Port of the proxy that you wish to connect to. This information can be updated after installation. You can also optionally enter Username and Password. Click Next. See Step 4 Enter Proxy Data in Use COM and install a new Payment Client PCService on page Follow Steps 6 to 8 of Use COM and install a new Payment Client PCService on page 38. Page 45 of 110

46 46 Payment Client Deployment Guide Step by Step Installation for a Sockets Interface See Install Multiple Payment Clients on page 46. Install Multiple Payment Clients If you need to process payments between multiple payment providers (for example, an ISP), you must install multiple Payment Clients and select the sockets installation option. Note: Each Payment Client can only communicate with a single Payment Server. The steps to install multiple Payment Clients are: 1 Run the Installer for each Payment Client. 2 Select the Sockets installation option. 3 Specify a different installation directory and port for each Payment Client. Note that if installing the Payment Client as a Windows Service (available for Microsoft Windows based installations only), the entry in the Services list will reflect the latest PCService installed only. 4 If installing the COM Interface, the default COM object will use the latest Payment Client installed. 5 Test each installation using the procedure outlined in Testing Payment Client on page 47. Step by Step Installation for Multiple Payment Clients Do the following for each Payment Client: 1 After Payment Client Installation starts, the Introduction displays. Read the instructions and click Next. 2 In Choose Installation Options, select Sockets. Click Next. (See Step 2, Choose Installation Options in Step by Step COM Installation on page 32.) 3 In Choose a Java Virtual Machine the installer determines the JVMs installed on the host. Ensure that the default path to the JVM as displayed is correct. Click Next. (See Step 2, Choose Java Virtual Machine in Use COM and install a new Payment Client PCService on page 38.) 4 On Choose Proxy Configuration, either select None, or, if the network that Payment Client is being installed on requires a proxy to connect to the Internet, select the type of proxy used from SOCKS4, SOCKS5, HTTP, or NTLM. Click Next. If you selected None, go to Step 7. 5 On Enter Proxy Data, enter the Proxy Address and Proxy Port of the proxy that you wish to connect to. This information can be updated after installation. You can also optionally enter Username and Password. (See Step 4, Enter Proxy Data in Use COM with an existing Payment Client PCService on page 34.) 6 Ensure you enter a different port for every instance of Payment Client. Click Next. 7 Follow Steps 5 to 8 of Use COM and install a new Payment Client PCService on page 38. Page 46 of 110

47 47 Payment Client Deployment Guide C HAPTER 6 Testing Payment Client After installing your new Payment Client, you should test the installation to confirm that Payment Client is working correctly and can perform transactions with the Payment Server. To do this you should: 1 Use the Diagnostic Tool (see Use the Diagnostic Tool on page 47) 2 Test the Sockets Interface (see Test the Sockets Interface on page 50) (applicable to Sockets interface only) 3 Use the PCCOM Tool (see Use the PCCOM Tool on page 51) (applicable to COM interface only) 4 Run the Example Code (see Run the Example Code on page 52) Use the Diagnostic Tool This section describes how to test Payment Client using the diagnostic tool. These tests ensure that Payment Client itself is working correctly by instantiating itself in its native Java environment. Note: You must run a successful test transaction to ensure the test data is correct. If you cannot run a successful test transaction, do NOT continue the test process. The steps for testing Payment Client with the diagnostic tool are: 1 Obtain the prerequisites for the diagnostic tool. 2 Configure the diagnostic tool, (only required for TNS-hosted payments.) 3 Run the diagnostic tool and check the results. Obtain the Prerequisites for the Diagnostic Tool You must have the following information to use the diagnostic tool: Test Merchant ID. Test transaction information. Pre-requisite Card number information on hand (in CardNumber.profile). Payment Client configuration information (in setup.properties). For more information Contact your payment provider help desk. Contact your payment provider help desk. See Test Card Numbers on page 95. See Payment Client Setup on page 94. The user of the diagnostic tool must have write access to Transaction Network Services/PaymentClient /bin directory. Page 47 of 110

48 48 Payment Client Deployment Guide Configure the Diagnostic Tool (TNS hosted only) To configure the diagnostic tool for TNS hosted payments, you must enter a Client Return URL where the Payment Server will send the DR. Client Return URL information You can enter the Client Return URL in Payment Server Merchant Administration via Merchant Setup» Merchant Configuration. The URL must be a valid format with DR=${DR} appended as a URL-encoded variable. For example, you can set the Client Return URL using any of the following valid examples: For more information on configuring this setting, see the Merchant Administration User Guide. Run the Diagnostic Tool You can now run the Diagnostic Tool and check the results. To run the diagnostic tool: On Windows: Go to Start menu > All Programs > Transaction Network Services > PaymentClient , and click Test Payment Client; or Run the PaymentClientDiagnostics.exe file in the \bin\ directory of Payment Client installation directory. On Linux: Run the PaymentClientDiagnostics.exe file in the /bin/ directory of Payment Client installation directory You must have write access to Transaction Network Services/PaymentClient /bin directory. Note: You can terminate the test at any time using Ctrl-C. The diagnostic tool runs different tests depending on whether you select Merchant-hosted or TNShosted payments. You can check the results of the diagnostic tool by viewing the log file. The diagnostic tool logs the results to the file with the format PaymentClientDiagnosticsddmmYYYYmmhhss.log in the Transaction Network Services/PaymentClient /bin directory. The following sections demonstrate the diagnostic tool for Merchant-hosted and TNS-hosted payments. Page 48 of 110

49 Payment Client Deployment Guide 49 Example for Merchant Hosted payments Run the diagnostic tool. 1 Select test type. Type 1 (MOTO) or 3 (MOTO including currency) and click Enter. 2 Enter merchant ID. Enter the test merchant ID for the transaction. The test merchant ID should be provided to you by the Payment Server Provider. 3 Enter currency. Enter a valid currency configured for the merchant. This prompt appears if you choose test type 3 (MOTO including currency) 4 Enter session ID. Enter a unique session ID for the transaction. 5 Select or enter card information. Select the card number from the list displayed. To enter another card, type Z and manually enter the card number. 6 Enter card expiry date in YYMM format (Optional). This step is only required if you manually entered a card number in step 5. 7 Perform test. The diagnostic tool performs the test and reports whether the test was successful or failed. For example, if you run the test using the following information: test type: MOTO merchant id: m001 currency: session id: 1 card number: card expiry: 0305 The diagnostic tool displays the following output: merchant id: m001 currency: session id: 1 card number: card expiry: 0305 purchase amount: 100 locale id: en_au dr url:testing creation of PaymentClient object... OK Testing sending of MOTO digital order object... OK Checking the results from the PaymentServer... OK If you run the test using the following information: test type: MOTO merchant (include currency) id: m001 currency: AUD session id: 1 card number: card expiry: 0305 The diagnostic tool displays the following output: Page 49 of 110

50 50 Payment Client Deployment Guide merchant id: m001 currency: AUD session id: 1 card number: card expiry: 0305 purchase amount: 100 locale id: en_au dr url:testing creation of PaymentClient object... OK Testing sending of MOTO digital order object... OK Checking the results from the PaymentServer... OK Example for TNS-hosted payments Run the diagnostic tool. 1 Select test type. Enter 2 (SSL) or 4 (SSL including currency) and click Enter. 2 Enter merchant ID. Enter the test merchant ID for the transaction. The test merchant ID should be provided to you by the Payment Server Provider. 3 Enter currency. Enter a valid currency configured for the merchant. This prompt appears if you choose test type 4 (SSL including currency). 4 Enter session ID. Enter a unique session ID for the transaction. 5 Perform test transaction. The diagnostic tool opens a web browser window for you to perform a test transaction. If a browser window is not opened, the diagnostic tool prompts you to copy and paste the Digital Order URL into a new browser window. 6 Copy browser address. When the transaction completes, the diagnostic tool displays a broken URL page. Copy the URL from the Address bar of the browser and paste it into the diagnostic tool. If cannot locate the DigitalReceipt text from the browser, fail the test by entering Z. 7 Review test result. The diagnostic tool reports whether the test was successful or failed. Fix Communication Errors Merchant-hosted transactions that cannot pass through the firewall display an error message similar to: E5231:QSI.util.tls.TLSException: Error getting TLS connection to paymentserver.anybank.com.test:443 In this situation, check your network and firewall connectivity. For more information, see Test Connectivity on page 81. Test the Sockets Interface Use the PCService to test communications with Payment Client. A manual test ensures that PCService on Payment Client is correct and working. Note: If you installed multiple Payment Clients, you must test each Payment Client. Page 50 of 110

51 Payment Client Deployment Guide 51 Test PCService To test the sockets: 1 Start PCService for the Payment Client. For more information, see Configure PCService on page Open a connection. Telnet to Payment Client port by typing telnet (where 9050 is the PCService port). A telnet session opens if successful; otherwise the message: Could not open a connection to host... displays. 3 Check that PCService is running Run an "echo" command by typing 1,test. The response should be 1,echo:test 4 Check the connection Run a "getdigitalorder" command by typing 2,1,<test Merchant ID>,100,en, For example, type: 2,1,test123456,100,en, If the test result is a success, the response will be 1, digital order>. If the test fails, you will get 0,0. For more details on these commands, see Payment Client Reference Guide. 5 Close the connection by typing 99, This confirms the Payment Client communications are working. If you cannot complete the connection, PCService has not been started or Payment Client is not installed or configured correctly. Use the PCCOM Test Tool This section describes how to test your COM object using the PCCOM test tool. This test ensures that COM object itself is working correctly (Windows only). To test your COM object: 1 Double-click TestPCCOM.cmd in the bin directory of the new Payment Client installation. For example, C:\Program Files\Transaction Network Services\PaymentClient \bin\TestPCCOM.cmd. Alternatively, you can run the file from the command prompt. The test results are written to PCCOM.out file which resides in the bin directory. If the test result is a success, the file displays OK. Otherwise, it displays FAIL. Page 51 of 110

52 52 Payment Client Deployment Guide Run the Example Code Payment Client ships with example code that demonstrates how to use it in different merchant application environments, in a variety of languages. Running the appropriate example code allows you to test the environment that the merchant s application is running in. The example code demonstrates the integration code you need to write for your merchant application. For more information, see the relevant code examples. Page 52 of 110

53 53 Payment Client Deployment Guide C HAPTER 7 Upgrading from Earlier Versions Payment Client 3.2 and the earlier versions of Payment Client can both co-exist and run on the same system without interfering with each other's processes. To upgrade from an earlier Payment Client version, perform the following steps: 1 Prepare for your upgrade This section describes the considerations you need to be aware of before upgrading to your new Payment Client. For more details, see Prepare for Your Upgrade on page Install the new version of Payment Client as an upgrade Select "Re-use configuration from a previous installation of Payment Client" during installation. For more details, see Upgrade Your Existing Payment Client on page Test the installation of the new Payment Client See Testing Payment Client on page Update Your Application Integration to use the new Payment Client See Update Your Application Integration on page 62. Page 53 of 110

54 54 Payment Client Deployment Guide Prepare for Your Upgrade Depending on the options you selected when you installed your existing Payment Client, you will currently be using one of the following configurations: Java Interface Sockets Interface COM Interface (Windows only) 1. Use COM with an Existing Payment Client PCService 2. Use COM and Install a new Payment Client PCService 3. Use COM and Install a Payment Client using Java JNI When you install the new version of Payment Client as an upgrade, you will need to know the location of the setup.properties file of your existing Payment Client. This file resides in the config directory of your existing installation. Each of the aforementioned configurations have their installation components installed on a single machine except COM option 1 (Use COM with an Existing Payment Client PCService). In the case of COM option 1, typically you will have installed your existing Payment Client and PCService on a machine that is remote from your payment application and your existing COM object. It is this remote machine that will contain the setup.properties file of your existing Payment Client. Hence, your upgrade will need to be performed on the remote machine rather than the machine that hosts your payment application. It's not necessary to perform an upgrade on your COM object with COM Option 1. The following sections illustrate the typical states for each of the configurations both before and after the installation of your new Payment Client as an upgrade. When you have reached the After state following the upgrade, you will be in a position to test your new Payment Client. As mentioned, your payment application will still be able to run with your previous version of Payment Client. Before refers to a typical state that you are currently in. After refers to a typical state where you have installed your new Payment Client as an upgrade. Page 54 of 110

55 Payment Client Deployment Guide 55 Java Interface Sockets Interface Page 55 of 110

56 56 Payment Client Deployment Guide COM Interface Use COM with an Existing Payment Client PCService Page 56 of 110

57 Payment Client Deployment Guide 57 Use COM and Install a new Payment Client PCService Use COM and Install a Payment Client using Java JNI Page 57 of 110

58 58 Payment Client Deployment Guide Upgrade Your Existing Payment Client As described in the previous section, Prepare for Your Upgrade on page 54, you are currently in the Before state. To move to the After state, you will need to install your new Payment Client as an upgrade. To upgrade from your existing version: 1 Run the Payment Client installer. After Payment Client installation starts, the Introduction displays. Read the instructions and click Next. 2 In Choose Install Folder, enter the location on your hard drive where your new Payment Client is to be installed with all its associated files. You can click Restore Default Folder to set the location to "C:\Program Files\Transaction Network Services" or Choose to navigate to a required location. Click Next. Page 58 of 110

59 Payment Client Deployment Guide 59 3 In Choose An Installation Type, select Yes to reuse the configuration parameters from your previous installation of Payment Client. Page 59 of 110

60 60 Payment Client Deployment Guide 4 In Choose Existing Payment Client Config Folder, enter the location on your hard drive where the config folder of your existing Payment Client is installed. For example, C:\Dialect\PaymentClient\config. The installation will use this information to locate the "setup.properties" file from your previous installation. Page 60 of 110

61 Payment Client Deployment Guide 61 5 If your installation uses the Sockets interface, the Enter Sockets Configuration screen displays. Specify the configuration of Payment Client PCService and click Next. The port number of the new PCService defaults to the port number of the previous PCService incremented by 1. However, if this is not suitable you may select another port for the PCService to monitor. Note that you should NOT select the port number being monitored by the previous installation; otherwise the new PCService will fail to start. 6 In Choose Shortcut Folder, select where you want to install shortcut icons to Payment Client. Click Next. 7 After Payment Client has been configured, the Pre-Installation Summary displays. If correct, click Install. If not, click Previous and return to Step 3. Installing Transaction Network Services Payment Client displays, followed by the Please Wait message. 8 If the installation is successful, the Install Complete message displays. Click Done to exit the installer and begin testing your newly installed Payment Client. For more details, see Testing Payment Client on page 47. If an error message displays, see Error Codes on page 102. Note: Remember you need not uninstall your earlier version of Payment Client. Page 61 of 110

62 62 Payment Client Deployment Guide Update Your Application Integration As mentioned previously, before continuing you must first test your upgrade. See Testing Payment Client on page 47. The integration of your new Payment Client for your production environment varies based on the interfaces you are currently using. The following sections illustrate the typical states for each of these interfaces both before and after updating your application integration. Java Interface on page 63 Sockets Interface on page 64 COM Interface on page 66 Before refers to a typical state where you have successfully installed and tested the new Payment Client on your machine. After refers to a typical state where you have updated your application integration to use your new Payment Client. Page 62 of 110

63 Payment Client Deployment Guide 63 Java Interface Note: Before integrating the new Payment Client with your payment application, test the Payment Client. See Use the Diagnostic Tool on page 47. If you are currently using the Java interface: 1 Stop your payment application. 2 Change the java classpath of your payment application to include the path of your new Payment Client classes instead of the earlier version. For example, if the java classpath was set to C:\Dialect\PaymentClient\classes, change it to C:\Program Files\Transaction Network Services\PaymentClient \classes 3 Start your payment application. Page 63 of 110

64 64 Payment Client Deployment Guide Sockets Interface Note: Before integrating the new Payment Client with your payment application, test your new PCService. See Test the Sockets Interface on page 50. If you are currently using the Sockets interface: 1 Stop the new PCService installed using the new Payment Client. If you've registered PCService as a Windows Service, see Starting and Stopping Payment Client on page Modify the port number in C:\Program Files\Transaction Network Services\PaymentClient \config\PCService.properties to use the port number used by the earlier version of Payment Client. For example, PCService.properties file might have the following configuration where the new Payment Client connects to PCService using port port=9051 # Comment out the line above and uncomment the next line # to use the same port number as the previous installation (if any) # port=9050 To switch your new Payment Client to use port 9050, comment "port=9051" and uncomment "port=9050" as follows. #port=9051 # Comment out the line above and uncomment the next line # to use the same port number as the previous installation (if any) port= Stop your payment application. 4 Stop the old PCService used by the earlier version of Payment Client. 5 Start the new PCService. 6 Start your payment application. Page 64 of 110

65 Payment Client Deployment Guide 65 Page 65 of 110

66 66 Payment Client Deployment Guide COM Interface The integration steps for a COM-based installation differ with the COM option you are currently using. The three COM options are: Use COM with an Existing Payment Client PCService The upgrade for this COM option includes a new Payment Client and a new PCService. You will continue to use your old COM object. Use COM and Install a new Payment Client PCService The upgrade for this COM option includes a new Payment Client, a new PCService, and a new COM object. Use COM and Install a Payment Client using Java JNI The upgrade for this COM option includes a new Payment Client and a new COM object. Note: Before integrating the new Payment Client with your payment application, test your new COM object with PCCOM tool, PCService with telnet, and Payment Client with the Diagnostic tool. For more details, see Testing Payment Client on page 47. Use COM with an Existing Payment Client PCService For this COM option, we assume that your payment application and COM object reside on Machine A, and your Payment Client and PCService reside on Machine B (see diagram below). 1 Stop your payment application. 2 On Machine A, modify the port number in bin\ PCCOM.ini (for example, C:\Dialect\PaymentClient\bin\PCCOM.ini) to match the port number configured for the new Payment Client PCService on Machine B. In the socketport section of PCCOM.ini file, modify the value for the field "socketport" to match the port number of the new PCService. For example, socketport=9051 Note: To retrieve the port number of the new PCService, go to <new Payment Client Installation directory>\config\pcservice.properties on Machine B. The value for the field "port" in this file must match the value of "socketport" in <old Payment Client Installation directory>\bin\pccom.ini on Machine A. 3 Start your payment application. Page 66 of 110

67 Payment Client Deployment Guide 67 Page 67 of 110

68 68 Payment Client Deployment Guide Use COM and Install a new Payment Client PCService During installation on your production machine, you may have chosen not to register your new PCCOM.dll due to outage issues. This would have allowed you to test the new COM object using the PCCOM test tool. See Use the PCCOM Test Tool on page 51. To update your application integration for the new Payment Client, you must now register your new PCCOM.dll. This will automatically unregister your old COM object. 1 Stop your payment application. 2 Double-click RegisterCOM.cmd in the bin directory of the new Payment Client installation. For example, C:\Program Files\Transaction Network Services\PaymentClient \bin\RegisterCOM.cmd Note: Ensure that you start your new PCService before registering PCCOM.dll. If not, the registration will fail. Page 68 of 110

69 Payment Client Deployment Guide 69 3 Start your payment application. Page 69 of 110

70 70 Payment Client Deployment Guide Use COM and Install a Payment Client using Java JNI During installation on your production machine, you may have chosen not to register your new PCCOM.dll due to outage issues. This would have allowed you to test the new COM object using the PCCOM test tool. See Use the PCCOM Test Tool on page 51. To update your application integration for the new Payment Client, you must now register your new PCCOM.dll. This will automatically unregister your old COM object. 1 Stop your payment application. 2 Double-click RegisterCOM.cmd in the bin directory of the new Payment Client installation. For example, C:\Program Files\Transaction Network Services\PaymentClient \bin\RegisterCOM.cmd 3 Start your payment application. Page 70 of 110

71 Payment Client Deployment Guide 71 Roll Back Your Application Integration There may be occasions where you may decide to roll back your application integration to use your previous installation of Payment Client. Additionally, you will need to follow the roll back instructions before you uninstall your new Payment Client to ensure that your previous Payment Client configuration continues to work correctly. The following sections describe the steps and considerations you need to be aware of if you need to roll back on Windows: Java Interface on page 72 Sockets Interface on page 73 COM Interface on page 74 Before refers to a state where you have successfully installed, tested, and updated the application integration for your new Payment Client. After refers to a state where you have rolled back the application integration to your old Payment Client. Page 71 of 110

72 72 Payment Client Deployment Guide Java Interface If you are currently using the Java interface: 1 Stop your payment application. 2 Change the java classpath of your payment application to include the path of the earlier version of Payment Client classes. For example, if the java classpath was set to C:\Program Files\Transaction Network Services\PaymentClient \classes, change it to C:\Dialect\PaymentClient\classes 3 Start your payment application. Page 72 of 110

73 Payment Client Deployment Guide 73 Sockets Interface If you are currently using the Sockets interface: 1 Stop your payment application. 2 Stop the new PCService running on port Start the old PCService. 4 Start your payment application. Page 73 of 110

74 74 Payment Client Deployment Guide COM Interface The roll back steps for a COM-based installation differ with the COM option you are currently using. Use COM with an Existing Payment Client PCService 1 Stop your payment application. 2 On Machine A, modify the port number in bin\ PCCOM.ini (for example, C:\Program Files\Transaction Network Services\PaymentClient \bin\PCCOM.ini) to match the port number used by the old Payment Client PCService on Machine B. In the socketport section of PCCOM.ini file, modify the value for the field "socketport" to match the port number of the old PCService. For example, socketport=9050 Note: To retrieve the port number of the old PCService, go to <old Payment Client Installation directory>\config\pcservice.properties on Machine B. The value for the field "port" in this file must match the value of "socketport" in <old Payment Client Installation directory>\bin\pccom.ini on Machine A. 3 Start your payment application. Page 74 of 110

75 Payment Client Deployment Guide 75 Use COM and Install a new Payment Client PCService 1 Stop your payment application. 2 Double-click ReregisterOldCOM.cmd in the bin directory of the new Payment Client installation. For example, C:\Program Files\Transaction Network Services\PaymentClient \bin\ReregisterOldCOM.cmd Note: Ensure that you start your old PCService before registering PCCOM.dll. If not, the registration will fail. 3 Start your payment application. Page 75 of 110

76 76 Payment Client Deployment Guide Use COM and Install a Payment Client using Java JNI 1 Stop your payment application. 2 Double-click ReregisterOldCOM.cmd in the bin directory of the new Payment Client installation. For example, C:\Program Files\Transaction Network Services\PaymentClient \bin\ReregisterOldCOM.cmd 3 Start your payment application. Page 76 of 110

77 77 Payment Client Deployment Guide C HAPTER 8 Managing Payment Client Once Payment Client has been successfully installed, and is up and running, you are unlikely to need to perform management tasks very often. Occasionally, however, you may need to: Deploy patches and upgrades to take advantage of new functionality Modify the business rules you use to process transactions Troubleshoot the application as a result of failed transactions This chapter provides instructions enabling you to perform these tasks. Starting and Stopping Payment Client Although most of the time you will leave Payment Client running in the background, there will be times when you need to stop and start the service. You will need to stop and start Payment Client, for example, if you want to: Deploy new Payment Client configuration Implement a patch or an upgrade Perform tests and/or troubleshooting activities This section describes the steps for starting and stopping Payment Client using Windows Services. Starting Payment Client To start Payment Client using Windows Services: 1 Select All Programs > Control Panel > Administrative Tools > Services. 2 Scroll down the list of services and select TNS PCService. If Payment Client is not currently running, the Status column is empty. Page 77 of 110

78 78 Payment Client Deployment Guide 3 Select Action > Start. The Status column changes from empty to 'Started'. Page 78 of 110

79 Payment Client Deployment Guide 79 Stopping Payment Client To stop Payment Client using Windows Services: 1 Select All Programs > Control Panel > Administrative Tools > Services. 2 Scroll down the list of services and select TNS PCService. If Payment Client is running, the Status column displays 'Started'. 3 Select Action > Stop. The Status column changes from 'Started' to empty. Page 79 of 110

80 80 Payment Client Deployment Guide Restarting Payment Client The restart option provides an efficient way to stop and start Payment Client in a single step. When Payment Client restarts, it: Stops accepting new connections Completes the processing of any current transactions Restarts, reading the configuration from the \active directory To restart Payment Client using Windows Services: 1 Select All Programs > Control Panel > Administrative Tools > Services. 2 Scroll down the list of services and select TNS PCService. If Payment Client is not running, the Status column is empty. 3 Select Action > Restart. The Status column changes to 'Started'. Linux-related Issues on PCService This section covers a few significant Linux related issues that you need to be aware of. Page 80 of 110

81 Payment Client Deployment Guide 81 Add PCService to the Start-up Environment in Linux 1 Log in as root. 2 Navigate to /etc/rc.d directory by entering cd /etc/rc.d 3 Edit the rc.local file and add the following line at the end of the file:./<path_to_paymentclient>/bin/pcservice & For example,./opt/transaction Network Services/PaymentClient /bin/PCService & 4 Save the file and re-boot the machine. Note: You must end the line with & to run the process in the background to avoid obstructing the startup process. To check the path is current, you can run the command on the command line before entering it in the file. Managing Connectivity Whether your payment solution is merchant-hosted or TNS-hosted, Payment Client communicates with the Payment Server via the Internet using the Secure Sockets Layer protocol on port 443. You must update your network and firewall configuration to allow direct communication. Configure the network and firewall by: Using a proxy server that uses the HTTP, Socks4, Socks5, or NTLM proxy protocols. If you select the proxy option, the installation will guide you through the proxy configuration options. Opening the firewall to allow direct communication between Payment Client and the Payment Server by allowing incoming and outgoing traffic via an SSL connection on port 443. Because Payment Client always initiates the connection, you can further restrict this rule to only allow outgoing connections from Payment Client. After updating your network and firewall configuration, you should test the connection. Warning: The integration module may communicate with Payment Client in clear text over an unsecured connection. Do NOT allow this communication outside the local secured network, as it is possible that transaction data maybe intercepted and/or fraudulently altered. Test Connectivity You must test and troubleshoot your network connectivity after configuring your network and firewall. Page 81 of 110

82 82 Payment Client Deployment Guide To Check the communication Path 1 Open a command window on the Payment Client machine and enter the command: telnet PaymentServerName 443 where PaymentServerName is the host name of the Payment Server. The host name can be found in the TargetURL in the config/setup.properties file. 2 If the communication path is correct, you will establish a connection. Close the telnet session. OR 3 If the communication path is incorrect, a message displays: Could not open a connection to host... If using Microsoft Windows 2000, a blank screen will display and the connection will timeout after a period of time and will display Connection to host lost. If the communications path is incorrect, re-check your network and firewall configuration settings. For further information, contact your systems administrator. Managing Security Secure your Payment Client IT infrastructure by setting appropriate file system security levels. The following sections detail the minimum requirements for the Payment Client installation and configuration directories. You will need administrator privileges to effect these changes. Microsoft Windows COM Installations Directory or file Read Write Execute Transaction Network Services/classes (or equivalent directory) - for the Internet Guest User (for example, IUSR_MACHINE on the machine). Note: no other users require access. Transaction Network Services/PaymentClient /config for same user. Transaction Network Services/PaymentClient /log for same user. Transaction Network Services/PaymentClient /bin Page 82 of 110

83 Payment Client Deployment Guide 83 Socket and Java Installations Directory or file Read Write Execute Transaction Network Services (or equivalent directory) Transaction Network Services/PaymentClient /config Transaction Network Services/PaymentClient /log Transaction Network Services/PaymentClient /classes Transaction Network Services/PaymentClient /classes/*.* (that is, all files in the directory) Transaction Network Services/PaymentClient /bin Transaction Network Services/PaymentClient /bin/*.* (that is, all files in the directory) Secure Key Files The following are key files that must be present for Payment Client to work. They must not be deleted or altered in anyway. To prevent this, secure them at all times. PaymentClient \config\qsi.3 and PaymentClient \config\qsi.4 Page 83 of 110

84 84 Payment Client Deployment Guide Configuration Files The Payment Client installation automatically creates the configuration files and populates some fields based on information that you supplied during the installation. In most cases, you will not have to configure Payment Client. Advanced users who need to configure Payment Client for their unique environments can refer to Appendix A - Configuration Syntax on page 93. You can control the behaviour of Payment Client to suit your environment using the configuration files. Depending on the interface selected during the installation (for example, Java, sockets, etc) you may need to configure different files. You can configure these files for all interfaces. The configuration files are in ASCII format and can be edited using a standard text editor. You must have appropriate permissions to read and edit the files. For more information, see Manage Security on page 82. Payment Client must be restarted for configuration changes to take effect. Depending on your installation, you may have to restart one or more of the components as detailed in the table. COM with JNI Installation COM application. Restart COM with Sockets Java Sockets PCService. Changes to pccom.ini require you to restart the COM application as well. JVM that hosts Payment Client. PCService. Page 84 of 110

85 85 Payment Client Deployment Guide C HAPTER 9 Uninstall Payment Client The Payment Client uninstaller will remove the Payment Client and any settings or files created by the installer. If you have performed an upgrade to your earlier version of Payment Client, and also updated your application integration to use the new Payment Client, and if you now wish to uninstall your new Payment Client, you must first perform a roll back of your application integration. For more information, see Roll Back Your Application Integration on page 71. The uninstaller will only uninstall system configuration changes made by the installer. You must explicitly remove any manual changes made during the installation. See your system administrator for help. To uninstall Payment Client: 1 Stop all services and applications that use the Payment Client, for example, Internet Information Server (IIS), PCService, and so on. If you do not stop all services and applications, the uninstaller may not delete all files. If the uninstaller cannot delete the files, you must stop the service or application and manually delete the files. 2 Run Payment Client uninstaller and follow the directions on the screen. On Microsoft Windows: Go to Start menu > All Programs > Transaction Network Services > PaymentClient , and click Uninstall Payment Client; or Run the Add/Remove programs utility in the Microsoft Windows Control Panel; or Run the Uninstall PaymentClient.exe file in the \UninstallData\ directory of Payment Client installation directory. On Linux: Run the Uninstall PaymentClient.bin file in the /UninstallData/ directory of Payment Client installation directory. 3 Remove any other files added by the System Administrator or Developer when implementing Payment Client. Manually Uninstall Payment Client If you face any technical difficulties in uninstalling the Payment Client using the steps described above, you may want to uninstall it manually. 1 During installation, if you have registered PCService as a Windows Service, then: a) Stop the PCService. See Starting and Stopping Payment Client on page 77. Page 85 of 110

86 86 Payment Client Deployment Guide b) Unregister PCService using an application like sc delete <service_name>. For example, sc delete TNS_PCService sc (service control) is an application, available on some Windows operating systems, which can unregister a Windows Service. Unregister the service by entering: sc delete <service_name> If you are unsure about the service name, right-click the service and select Properties. 2 If you have not registered PCService as a Windows Service, stop it manually. 3 If you have a previous version of Payment Client that uses the COM object, you should re-register the old COM object before uninstalling your new Payment Client. To re-register: Double-click ReregisterOldCOM.cmd in the bin directory of the new Payment Client installation. For example, C:\Program Files\Transaction Network Services\PaymentClient \bin\ReregisterOldCOM.cmd 4 Delete the Payment Client installation folder and its sub-directories. Page 86 of 110

87 87 Payment Client Deployment Guide C HAPTER 10 Glossary Acquiring bank A financial institution such as a bank that verifies/acquires credit cards on behalf of a Merchant and deposits the required amount into the Merchant's bank account after settlement. API Application Programming Interface. Set of programming requests or function calls. Authentication The process of assuring that data has come from its claimed source, or of corroborating the claimed identity of a communicating party. Basic Authentication HTTP basic authentication is the standard method of access control for most major browsers. Basic authentication is supported at the HTTP level by most Web servers and requires little or no development effort to implement. HTTP basic authentication does not provide protection of the user ID and password during transmission from the user's computer to the site's Web server. Bank Financial institution where customers settle transfer funds for goods and services purchased from a merchant. See also merchant s bank and cardholder s bank. Issuing Bank A financial institution such as a bank that issues a credit card to a customer. Page 87 of 110

88 88 Payment Client Deployment Guide Merchant s bank Financial institution where the merchant maintains their business banking account. Also known as the acquiring bank. Cardholder s bank Financial institution where the cardholder maintains their account. Also known as the issuing bank. Cardholder The party that holds or owns the card. The consumer. Card not present transaction In traditional card transactions, the card is swiped in the store or keyed in a device. The card is physically present when the transaction occurs. Card not present transactions involve transaction processing over the phone, or an open Internet connection, so the transaction can be performed online, potentially even on the Web server itself. Internet transaction services typically provide an API, an HTML type input terminal for manual entry and full online reports of transactions and batches. Transaction processors are separate from the banks that provide a merchant account, although some providers provide a single transaction statement seemingly providing a single service. Payment Response Message received from the Payment Server following a Payment Request. See also Payment Request. Payment Request A signed and encrypted message containing all the transaction parameters sent from the Payment Client to the Payment Server. See also Payment Response. Page 88 of 110

89 Payment Client Deployment Guide 89 Digital Signature Information encrypted with a private key that is appended to electronic data to identify the owner of the private key and verify the integrity of the electronic data. e-commerce Electronic commerce. Buying or selling goods or services on the Internet, especially the World Wide Web. e-payment Secure online payments that transfer funds via the internet between a consumer and a merchant's financial institutions. Financial transaction A transaction from the acquirer to the issuer containing all necessary data for authorization, posting and reconciliation. Interface A shared boundary across which information is passed. A hardware or software component that connects two or more other components for the purpose of passing information from one to another. Interactive Voice Response (IVR) A software application that accepts a combination of voice telephone input and touch-tone keypad selection and provides appropriate responses in the form of voice, fax, callback, and perhaps other media. IVR is usually part of a larger application that includes database access. Page 89 of 110

90 90 Payment Client Deployment Guide IVR Application An IVR application provides pre-recorded voice responses for appropriate situations, keypad signal logic, access to relevant data, and potentially the ability to record voice input for later handling. Using computer telephony integration (CTI), IVR applications can redirect a call to a human being who can display data related to the caller. Java Virtual Machine (JVM) Interprets compiled Java binary code (called bytecode) for a computer's processor/hardware platform so it can run the Java program instructions. The java.exe file. JSSE JSSE implements a Java version of SSL (Secure Sockets Layer) and TLS (Transport Layer Security) protocols to provide secure Internet communications. Using JSSE, developers can provide for the passage of secure data between a client and a server running any application protocol (such as HTTP, Telnet, NNTP, and FTP) over TCP/IP. JSSE enables data encryption, server authentication, message integrity, and optional client authentication for a TCP/IP connection. Payment Client ID The identifier given to an instance of Payment Client running on a particular machine. Payment Server The Payment Server facilitates the processing of secure payments in real-time over the Internet between your online store and the bank. It processes a transaction request from your online store and sends back a transaction response showing whether the payment was successful or not. POS Point of sale terminal. Page 90 of 110

91 Payment Client Deployment Guide 91 Real-time A human rather than a machine sense of time. Real time is a level of computer responsiveness that a user senses as sufficiently immediate or that enables the computer to keep up with some external process (for example, to process credit card transactions as they occur) Sockets Method for communication between a client program and a server program in a network. A socket is the endpoint in a connection. Sockets are created and used via APIs. See also API. SSL SSL (Secure Sockets Layer) is a security technology that is used to secure transactions between the payment server and the Web browser. SSL protects data submitted over the Internet from being intercepted and viewed by unintended recipients. TCP/IP Basic communication language or protocol of the Internet that contains two layers. The higher layer, Transmission Control Protocol (TCP), manages the assembling of a message or file into smaller packets that are transmitted over the Internet and received by a TCP layer that reassembles the packets into the original message. The lower layer, Internet Protocol (IP), handles the address part of each packet so that it gets to the right destination. See also sockets, SSL. Transaction A DO and a DR constitute a transaction. Page 91 of 110

92

93 93 Payment Client Deployment Guide C HAPTER 11 Appendix A - Configuration Syntax This appendix contains configuration information for advanced users. You may need to customize the product behaviour to suit your environment, for example your environment may have changed since you first installed Payment Client. You may need to install a second instance of Payment Client, change the Payment Server, make changes to the network or logging. All these may necessitate configuration changes. The information in this appendix is only meant for advanced users who regularly maintain and configure complex environments. Key Files Files Purpose Attributes PaymentClient \config\qsi.3 and PaymentClient \config\qsi.4 Contain the unique cryptographic key files provided by the payment provider to allow communication between the Payment Client and the Payment Server to be securely encrypted and decrypted. These files are encrypted and cannot be edited. Note: The Payment Client cannot work without these files; you must secure them at all times to avoid deletion or alteration. Page 93 of 110

94 94 Payment Client Deployment Guide Payment Client Setup File: Purpose: PaymentClient \config\setup.properties Contains the primary Payment Client configuration information. Attributes: Attribute Description Options/Values TargetURL EncFormat ProxyType URL of the target Payment Server installation. Encryption format for communicating between the Payment Client and the Payment Server. Configures the proxy settings used by the Payment Client to communicate with the Payment Server. Pre-configured by default as the Payment Server URL. One of: RSA in codebook mode RSA envelope (default mode). Both options offer the same level of security; however RSA envelope offers faster performance. One of: http: HTTP proxy support socks4: SOCKS v4 proxy support socks5: SOCKS v5 proxy support ntlm: NTLM proxy support none - No proxy support required ProxyHost Proxy server IP address. Not required if ProxyType is 'none'. For example: ProxyHost= ProxyPort Proxy server port number. Not required if ProxyType is 'none'. For example: ProxyPort=80 ProxyUser ProxyPass Username to authenticate the Payment Client with the proxy server. Password to authenticate the Payment Client with the proxy server. Not required if ProxyType is 'none'. For example: ProxyUser=TNS PaymentClient Not required if ProxyType is 'none'. For example: ProxyPass=password Page 94 of 110

95 Payment Client Deployment Guide 95 Logging Configuration File: Purpose: PaymentClient \config\com.qsipayments.utility.logging.Logging.properties Configures the Payment Client logging output using Log4J. Attributes: Attribute Description Options/Values log4j.rootcategory 2-part value containing the logging level and file parameter for logging Payment Client messages. Logging levels (in ascending order of message logging output levels): FATAL ERROR WARN INFO DEBUG ALL File parameter: must be PC_FILE The file parameter must be PC_FILE otherwise there will be no logging output. For example, log4j.rootcategory = DEBUG, PC_FILE. Note: Only expert Log4J users should configure other properties. Test Card Numbers File Purpose Configuration PaymentClient \config\CardNumber.profile Used by the diagnostic utility to perform test transactions. The Payment Server automatically generates this file as the test cards are only valid for the specific Payment Server. You do not need to modify this file; however you can modify the card details for troubleshooting if required Page 95 of 110

96 96 Payment Client Deployment Guide Configure PCService File: PaymentClient \config\PCService.properties Purpose: Configures the PCService sockets listener application that accepts Payment Client commands for the sockets interface. You only need to configure this file if using the sockets interface. Attributes: Attribute Description Options/Values port timeout ipnumber threads rejectextraconnection messageprocessor fieldseparator Port where PCService will accept connections. Socket timeout value (in seconds) the service will keep listening to an inactive connection. This timeout need to match or be less than the timeout value specified on the application. List of IP addresses PCService will accept requests from. If you do not list IP addresses, the Payment Client will NOT accept socket connections. Number of simultaneous socket connections that PCService will make available to accept incoming requests. Determines if PCService will queue or reject connections after the maximum number of connects (as defined by the threads) has been reached. Defines the message format from the Payment Client for the Payment Server. Delimiter used by the current message processor to indicate the end of the field. If no value is set, uses the default value 9050, for example: port=9050 Default value 0 indicates no timeout. You must use a separate line for each IP address, for example: ipnumber1= ipnumber2= ipnumber3= For connections from localhost only, use If no value is set, uses the default value 10. true = reject extra connections false = queue extra connections (until thread becomes available) Do not modify the default value PaymentClient.processor.qsi. QSIMessageProcessor. Do not modify the default value comma ','. Page 96 of 110

97 Payment Client Deployment Guide 97 endofmessage Delimiter used by the current message processor to indicate the end of the message. Do not modify the default value crlf. COM DLL Configuration Only configure these files if using the COM-Java or COM-sockets interfaces. File: PaymentClient \bin\PCCOM.ini Purpose: Configures the DLL providing the COM interface to the Payment Client in Microsoft Windows COM installations. Only configure this file for COM installations. The DLL has two Payment Client interfaces: TCP sockets to communicate the COM Object and a Payment Client running PCService. JNI to create a Java Virtual Machine (JVM) and instantiate a Java Payment Client in the JVM. This file contains three configuration sections for general configuration, sockets configuration and JNI configuration. Area Attribut e Description Options/Values General config loglevel Level of detail to capture for logging information. Valid values (in order of verbosity): DISABLED (default value) ERROR WARNING INFO TRACE DETAIL DEBUG For example, loglevel=debug If no value is set, uses the default value DISABLED. logfilepat h Location and file name for system log file. If logging is enabled and no value is set, Payment Client creates the file PCCOM.log in the same directory as the DLL. For example, Logfilepath=C:\Program Files\Payment Client COM Interface\PCCOM.log Page 97 of 110

98 98 Payment Client Deployment Guide Area Attribut e Description Options/Values interfacet ype Default interface used by the default ProgID when instantiating the COM Payment Client object. Valid values are JNI to use the Java interface socket to use the sockets interface. For example, interfacetype=socket If no value is set the ProgID PaymentClient.com.COMClient uses the JNI interface. The ProgID PaymentClient.Sockets is for users wanting to use the sockets interface regardless of what the default interface (that is, PaymentClient.com.COMClient) is set to use. Page 98 of 110

99 Payment Client Deployment Guide 99 Area Attribut e Description Options/Values Socket s config socketho staddres s IP address for connecting to the Payment Client socket listener (PCService). If no value is set, uses the default localhost value For example, sockethostaddress= Value can be overridden at runtime if using the ProgID "PaymentClient. Sockets", but not if using the default ProgID (that is, "PaymentClient. com.comclient "). For more information on setting this value at runtime, see the tutorials in the Payment Client Integration Guide. Page 99 of 110

100 100 Payment Client Deployment Guide Area Attribut e Description Options/Values socketpo rt Port for connecting to the Payment Client socket listener (PCService). If no value is set, uses the default value For example, socketport=9050 Value can be overridden at runtime if using the ProgID "PaymentClient. Sockets", but not if using the default ProgID (that is, "PaymentClient. com.comclient "). For more information on setting this value at runtime, see the tutorials in the Payment Client Integration Guide. socketfiel dseparat or Character pattern for separating fields when sending data to the Payment Client socket listener (PCService). Do not modify the default value comma,. socketen dofmess agesend Character pattern indicating end of message when sending data to the Payment Client socket listener (PCService). Do not modify the default character pattern "crlf" (Carriage Return and Line Feed). Page 100 of 110

101 Payment Client Deployment Guide 101 Area Attribut e Description Options/Values socketen dofmess agerecv Character pattern indicating end of the message when receiving data from the Payment Client. Do not modify the default value "lf" (Line Feed). socketti meout DLL timeout value (in milliseconds) when communicating with the Payment Client socket listener (PCService). If no value is set, uses the default (100 seconds). For example: sockettimeout= JNI config classpat h Classpath used by the JVM using JNI. Must include the complete path to the Payment Client Java libraries and directory containing QSI.properties. For example: You MUST set this parameter correctly for the JNI interface to work correctly classpath=c:\program Files\Transaction Network Services\PaymentClient \classes\;C:\Program Files\Transaction Network Services\PaymentClient \classes\PaymentClient.jar; C:\Program Files\Transaction Network Services\PaymentClient \classes\bcprov-jdk jar;C:\Program Files\Transaction Network Services\PaymentClient \classes\jce-jdk jar;C:\Program Files\Transaction Network Services\PaymentClient \classes\log4j.jar; jvmpath Path to the DLL for creating the JVM using JNI. If no value is set, it uses the settings from the default JVM in the Microsoft Windows Registry. For example: jvmpath=c:\program Files\Java\jre1.5.0_19\bin\client\jvm.dll Note: Payment Client uses semi-colons to separate classpath entries and to indicate configuration file comments. The final semi-colon indicates the comment so you must include an additional semi-colon at the end of the comment to distinguish it from a classpath entry. Page 101 of 110

102 102 Payment Client Deployment Guide COM Installation Error Codes After installation, the Installer tests the COM Interface to ensure that the COM interface works correctly before registering the COM Interface. If the test fails, a message box displaying one of four possible errors displays. Error code 2 Error Code 4 Error code 5 Error code 6 The Payment Client COM Interface configuration test failed with error code 2 means that a Java Virtual Machine (JVM) could not be created. The JVM.DLL you selected in the COM Only installation could not be used to create a JVM. Check that the path to the JVM.DLL is correct and that the Java Runtime Environment is compatible. For the list of compatible Java Runtime Environments refer to Java Runtime Environment (JRE) Requirements on page 21. The Payment Client COM Interface configuration test failed with Error code 4 means that a test Digital Order could not be created. Ensure Payment Client supports the Java Runtime Environment you are using. For the list of compatible Java Runtime Environments refer to Java Runtime Environment (JRE) Requirements on page 21. The Payment Client COM Interface configuration test failed with error code 5 means that communications with Payment Client Service could not be established. The COM object could not connect to Payment Client PCService. Check that PCService has started and the IP address of the machine experiencing the error has been added to the PCService.properties file of PCService. If you make changes to PCService.properties, you need to restart PCService. The Payment Client COM Interface configuration test failed with error code 6 means that the COM object experienced an error when communicating with Payment Client PCService. Check that PCService is started and running correctly. The error message will be appended with more information to help define the error. Page 102 of 110

103 103 Payment Client Deployment Guide C HAPTER 12 Appendix B How Merchant-hosted Payments Work This section describes the processes behind merchant-hosted payments, the parties involved, and how the processing of e-payments occurs. Merchant-hosted payments are also called 2-party payments, direct payments, or merchant managed payments. Merchant-hosted payments involve the merchant and the merchant s payment provider. Merchanthosted payments use the direct method to send information from the merchant via the Payment Client to the Payment Server. The cardholders provide their payment details, such as card type, card number and expiry date, directly to the merchant. The customer does not leave the merchant site. Merchant-hosted payments require direct network connectivity with the Payment Server. The Payment Client sends the information as an encrypted Payment Request to the Payment Server. The Payment Client remains connected until the Payment Server processes the Payment Request and returns the encrypted Payment Response. Note: Regardless of the merchant application, the merchant is responsible for all customer facing information (for example, web pages for a cardholder, data screens for a call centre operator, or voice messages in an IVR scenario). Page 103 of 110

104 104 Payment Client Deployment Guide Merchant-hosted Information Flow The following diagram illustrates how a merchant application would make merchant-hosted payments. 1 A cardholder decides to make a purchase and provides their card details directly to your online store. 2 Your online store collects the details of the cardholders order and... 3 sends the Payment Request over the Internet to the Payment Server using the Payment Client. 4 The Payment Server passes the transaction to the merchant's acquirer bank for processing. 5 After processing, the Payment Server generates a Payment Response and passes it via the Payment Client to your online store. The Payment Response shows whether the transaction was successful or not. The results can be stored by you for future reference. 6 A receipt is generated and either immediately passed to the cardholder or included when shipping the goods. Page 104 of 110

105 105 Payment Client Deployment Guide C HAPTER 13 Appendix C How TNS-hosted Payments Work This section describes the processes behind TNS-hosted payments, the parties involved, and how the processing of e-payments occurs. TNS-hosted payments are also called 3-party payments, servermanaged payments, or re-direct method payments. TNS-hosted payments allow you to authenticate payments using Verified by Visa and MasterCard Secure Code. For more information, see the Using payment authentications section in the Payment Client Integration Guide. TNS-hosted payments involve the merchant, the merchant s payment provider, and the customer s browser as a data transport vehicle. TNS-hosted payments use the web browser to redirect information from the merchant application. The Payment Server (at the Payment Provider) returns the encrypted Payment Response, again via the cardholder s browser using a ReturnURL specified by the merchant in an encrypted and signed Payment Request. After processing the order, the cardholder s browser returns to the merchant s web site with the encrypted Payment Response as a URL encoded variable in the browser. The Payment Client decrypts the Payment Response and returns the receipt details back to the merchant s web site for display to the cardholder. Note: TNS-hosted payments sever the cardholder s session at the merchant s site. However, you can preserve merchant session information by sending session variables encrypted in the Payment Request to the Payment Server. These session variables will be returned to merchant appended to the end of the Payment Response, where they can be used to restore the cardholder s previous session. Page 105 of 110

106 106 Payment Client Deployment Guide TNS-hosted Payment Information Flow How TNS-hosted Payments are Processed TNS-hosted payments transmit information between the cardholder s web browser and the payment processor s Payment Server using the Secure Sockets Layer (SSL) protocol. The Payment Client further encrypts all information sent between the merchant application and the Payment Server to prevent data alteration in transit during re-direction of the cardholder s browser. The following diagram illustrates how a merchant application would use TNS-hosted payments. 1 A cardholder browses your online store, selects a product and enters their shipping details into the merchant's online store at the checkout page. 2 The cardholder clicks a pay button and your online store sends the payment Payment Request to the Payment Server by redirecting the cardholder's Internet browser to the Payment Server. 3 The Payment Server prompts the cardholder for the card details using a series of screens. The first screen displays the cards supported, for example MasterCard, Visa, and American Express. The cardholder chooses the card type they want to use for the transaction. The second screen accepts the details for the chosen card such as card number, card expiry, and card security number if required. 4 The Payment Server passes the details to the acquirer bank to process the transaction. After processing, the Payment Server displays the result of the transaction with a receipt number if it was successful or an appropriate information message if it was declined. It then advises the cardholder to wait while they are redirected back to the merchant's site. Page 106 of 110

107 Payment Client Deployment Guide The Payment Server then redirects the cardholder back to merchant's site with the Payment Response. The Payment Response contains the result of the Payment Request. 6 The online store interprets the Payment Response, displays the receipt, and confirms the order to the cardholder for their records. Page 107 of 110

108

109 109 Index A About e-payment Information Flows 12 About Payment Client 7 About this Document 9 Acquiring bank 83 Add PCService to the Start-up Environment in Linux 77 API 83 Appendix A - Configuration Syntax 9, 37, 80, 89 Appendix B 9, 15, 99 Appendix C 9, 15, 101 Audience 8 Authentication 83 B Bank 83 Basic Authentication 83 Before You Start 9, 21, 27, 30 C Card not present transaction 84 Cardholder 84 Cardholder s bank 84 Client Return URL information 44 COM DLL Configuration 93 COM Installation Error Codes 34, 37, 56, 98 COM Interface 52, 57, 61, 66, 69 Configuration Files 80 Configure PCService 47, 92 Configure the Diagnostic Tool (TNS hosted only) 44 Connection Details 23 Contacting Support 10 D Digital Signature 85 Disclaimer 2 E e-commerce 85 Ensure Windows Compatibility 28 e-payment 85 Example for Merchant Hosted payments 45 Example for TNS-hosted payments 46 F Financial transaction 85 Fix Communication Errors 46 G Glossary 9, 83 H How e-payments Transfer Funds 12 How Merchant-hosted Payments Work 99 How TNS-hosted Payments Work 101 How to Select an Integration Model 15 How to Select an Interface 18 I Included Software 22 Information Required for a COM JNI Interface 25 Information Required for a Java Interface 23 Information Required for a Sockets Interface 24 Install a Single Payment Client 30 Install Multiple Payment Clients 40, 41 Installing Payment Client 9, 23, 27 Integrating Payment Client 9, 15 Interactive Voice Response (IVR) 85 Interface 85 Issuing Bank 83 IVR Application 86 J Java Interface 51, 57, 58, 66, 67 Java Runtime Environment (JRE) Requirements 21, 30, 98 Java Virtual Machine (JVM) 86 JSSE 86 K Key Files 89 L Linux-related Issues on PCService 76 Logging Configuration 91 M Managing Connectivity 77 Managing Payment Client 9, 73 Managing Security 78, 80 Merchant s bank 84 Merchant-hosted Information Flow 100 Microsoft Windows COM Installations 78 Page 109 of 110

110 110 Index O Obtain the Prerequisites for the Diagnostic Tool 43 P Payment Client Documentation Set 8 Payment Client ID 86 Payment Client Overview 9, 11 Payment Client Setup 43, 90 Payment Request 84 Payment Response 84 Payment Server 86 POS 86 Preface 7 Prepare for Your Upgrade 49, 50, 54 Prerequisites 21 R Real-time 87 Related Documents 9 Roll Back Your Application Integration 66, 81 Run the Diagnostic Tool 44 Run the Example Code 43, 48 S Secure Key Files 79 Selection Guidelines for Integration Models 16 Selection Guidelines for Interfaces 18 Socket and Java Installations 79 Sockets 87 Sockets Interface 51, 57, 59, 66, 68 SSL 87 Starting and Stopping Payment Client 59, 73, 81 Step by Step COM Installation 30, 31, 32, 35, 38, 40, 41 Step by Step Installation for a Java Interface 30, 40 Step by Step Installation for a Sockets Interface 30, 40 Step by Step Installation for Multiple Payment Clients 41 Supported Platforms 21, 22 T TCP/IP 87 Test Card Numbers 43, 91 Test Connectivity 46, 77 Test PCService 47 Test the Sockets Interface 43, 46, 59 Testing Payment Client 9, 34, 37, 41, 43, 49, 56, 57, 61 The Components of an e-payment Solution 12 The Merchant Application 12 The Payment Client 13 The Payment Server 13 TNS-hosted Payment Information Flow 102 To Check the communication Path 78 Transaction 87 U Uninstall Payment Client 9, 81 Update Your Application Integration 49, 57 Upgrade Your Existing Payment Client 49, 54 Upgrading from Earlier Versions 9, 27, 31, 49 Use COM and Install a new Payment Client PCService 35, 39, 40, 41 Use COM and Install a Payment Client using Java JNI 38 Use COM With an Existing Payment Client PCService 32, 41 Use the COM interface 20 Use the Diagnostic Tool 43, 58 Use the Java interface 19 Use the PCCOM Test Tool 43, 47, 63, 65 Use the Sockets interface 19 W Welcome to TNS 7 What are e-payments? 11 When to combine 3-Party and 2-Party Payments 17 When to use 2-Party Payments 16 When to use 3-Party Payments 16 Page 110 of 110