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