MiGS PC Integration Guide. November 2008 Software version:

Transcription

1 MiGS PC Integration Guide November 2008 Software version:

2 Copyright MasterCard and its vendors own the intellectual property in this Manual exclusively. You acknowledge that you must not perform any act which infringes the copyright or any other intellectual property rights of MasterCard or its vendors and cannot make any copies of this Manual unless in accordance with these terms and conditions. Without our express written consent you must not: Distribute any information contained in this Manual to the public media or quote or use such information in the public media; or License Agreement Trademarks Allow access to the information in this Manual to any company, firm, partnership, association, individual, group of individuals or other legal entity other than your officers, directors and employees who require the information for purposes directly related to your business. The software described in this Manual is supplied under a license agreement and may only be used in accordance with the terms of that agreement. Trademark notices and symbols used in this manual reflect the registration status of MasterCard trademarks in the United States. Please consult with the Customer Operations Services team or the MasterCard Law Department for the registration status of particular product, program, or service names outside the United States. All third-party product and service names are trademarks or registered trademarks of their respective owners. MasterCard International Incorporated 2200 MasterCard Boulevard O Fallon MO USA MiGS PC Integration Guide November

3 Contents 1 Introduction...4 About Payment Client...4 About this Document...4 Related Documents Understanding e-payments...5 What are e-payments?...5 Payment Models Preparing for Integration...10 Integration Models and Communication Methods...10 Selection Guidelines for Integration Models...11 How to Select an Interface...13 Prerequisites Payment Client Integration Guidelines...19 Reference Fields...19 Ensuring Successful Payments...20 Securing Your Payments...21 Setting up Transactions...24 Setting up the Sockets' Interface Integrating 2-Party Payments...33 Merchant-hosted Information Flow...33 Basic 2-Party Transaction Integrating 3-Party Payments...46 Dialect-hosted Payment Information Flow...46 Steps to a 3-Party Payments Integration...52 Basic 3-Party Transaction...55 Additional 3 Party Functionality Supplementary Transactions...83 Address Verification Service (AVS)...83 Card Security Code (CSC/CVV2)...83 Card Present Transactions...84 External Payment Selection (EPS)...85 Merchant Transaction Source...85 Merchant Transaction Frequency...86 Enhanced Industry Data...86 Bank Account Type...87 ANZ Extended OrderInfo...87 Payment Authentication Advanced Merchant Administration (AMA)...96 MiGS PC Integration Guide November

4 Capture...96 Refund...97 Void Capture...97 Void Refund...98 Void Purchase...98 QueryDR...99 P2P Transactions...99 AMA Shopping Transaction History AMA Limited Shopping Transaction History AMA Financial Transaction History AMA Spanned Financial Transaction History Troubleshooting and FAQs Troubleshooting Frequently Asked Questions MiGS PC Integration Guide November

5 1 Introduction Dialect Payment Technologies Payment Client API provides a low integration effort solution for payment enabling web sites and e-commerce applications, in fact any application that needs payment functionality. This guide describes how to payment enable your e-commerce application or on-line store by using the functionality of the Payment Client API. The document describes Payment Client Version 3.1 API. 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 for installation at the merchant web site or ISP. About this Document This document is the Payment Client Integration Guide. It is part of the Payment Client documentation set. It contains information on how to integrate Payment Client with the merchant's software. Related Documents Payment Client Reference Guide This Payment Client Integration Guide is designed to be used with the Payment Client Reference Guide, which details the various types of transactions of the Payment Client's API methods, their inputs and outputs. Merchant Administration User Guide Merchant Administration allows you to view and manage your electronic transactions through a series of easy to use, secure web pages. MiGS PC Integration Guide November

6 2 Understanding e-payments This section is an overview of electronic payments or e-payments. 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. e-payments require secure communication between all components of the e-payment process. In their most simple form, e-payments are represented in the following diagram: 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/website 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. MiGS PC Integration Guide November

7 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 Digital Orders. The Payment Provider enables the merchant to accept payments online. How e-payments Transfer Funds e-payments transfer funds using the following steps: 1 The cardholder purchases goods/services from the merchant (for example, in person, using the Internet, or over the phone). 2 The merchant application sends a Payment Client Digital Order (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 at the merchant's Payment Provider. 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: Digital Order is sent by the Payment Client to the Payment Server to provide transaction information. Digital Receipt 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 Digital Order and a Digital Receipt. For each customer purchase or order, merchants may issue several transactions. Payment Client To securely communicate transaction information between the merchant application and the Payment Server, Payment Client: Receives a Payment Request from the merchant application Assembles a corresponding message, which it sends to the Payment Server Receives a Payment Response from the Payment Server MiGS PC Integration Guide November

8 Assembles a corresponding message, which it sends it to the merchant application The Payment Server To complete the transaction the Payment Server: Processes the Digital Order Transfers funds from the cardholder's account to the merchant's Payment Provider account and Returns a signed and encrypted Digital Receipt to Payment Client. Payment Models Payment Client supports the most commonly used payment models in the e- Payments process. These include the Authorisation/Capture model.. Payment Integration models are described in Preparing for Integration on page 10). Purchase Model Purchase is the most common type of payment model used by merchants to accept payments. A single transaction is used to authorise the payment and initiate the debiting of funds from a cardholder's credit card account. This is typically used when the goods will be delivered immediately following a successful transaction. Authorisation/Capture Model The authorisation/capture payment type is a two step process. The merchant uses an Authorisation transaction to reserve the funds. Authorisation in the Auth/Capture Model The Authorisation (Auth) transaction verifies that the card details are correct and may/may not also reserve the funds, depending on the merchant's Payment Provider. To find out what models are available to you, contact your Payment Provider. The authorisation is used to ensure that the cardholder has sufficient funds available against their line of credit. The full amount of the order is sent to the card Issuing Bank to verify the details against the cardholder's card account. The authorisation does not debit funds from the cardholders account, but reserves the total amount, ready for the capture transaction to debit the card and transfer the funds to your account. MiGS PC Integration Guide November

9 The cardholder's credit limit is reduced by the authorised amount. If they make another transaction, this current authorisation transaction is taken into account and comes off the cardholder's available funds as though the transaction had already taken place. This authorisation reserves the funds for a predetermined period of time, (such as 5-8 days), as determined by the card scheme and the cardholder's card issuing rules. The API does not have a method to void an Authorisation transaction so it must fade out at the end of the appropriate period. Authorisation transactions do not appear in the cardholder's account records, only the capture transactions appear. The Authorisation transaction uses the same API as the standard payment transaction used in the Purchase model where a Capture transaction is not required. The only difference is how the merchant profile is configured with the Payment Provider. Pre-Authorisation/Purchase Mode This is a variation of the Authorisation/Capture process where your Payment Provider verifies the card details with the card issuing institution, and if the transaction were carried out at this exact point in time whether the transaction would be successful. No funds are reserved on the cardholder's account. If the cardholder performed another transaction between the pre-authorisation transaction and the purchase transaction that used up all the available funds on the card, then the later purchase transaction may fail due to lack of funds (if applicable). The merchant must include the full amount in their Pre-authorisation transaction as the Payment Server uses it to ensure that later Purchase transactions do not exceed the total amount specified in the Pre-authorisation transaction. The Pre-Authorisation and Purchase transactions in this mode use exactly the same API as the Authorisation/Capture transactions outlined earlier. The only difference is how the merchant's Payment Provider actions the two transactions. Nominal Auth/Purchase Mode This is a variation of the Pre-authorisation/Purchase model where the Payment Server strips the value in the Authorisation transaction and substitutes a nominal transaction value. The acquiring bank checks the card details with the issuing card institution to ensure they are correct. No funds at all are reserved on the card. The merchant must include the full amount in their Nominal Authorisation transaction as the Payment Server uses it to ensure that later Purchase transactions do not exceed the total amount specified in the Nominal Authorisation transaction. The Nominal Auth/Purchase transactions in this mode use exactly the same API as the Authorisation/Capture transactions outlined earlier. The only difference is how the merchant's Payment Provider actions the two transactions. MiGS PC Integration Guide November

10 Capture in the Auth/Capture Model The capture transaction refers back to the initial authorisation transaction, and transfers the funds from a cardholder's card into the merchant's account. The merchant can perform any number of capture transactions on the original Authorisation transaction, however the total of all the amounts from all the captures cannot exceed the original authorised amount. For example, the merchant may not have the full ordered amount of goods in stock. Hence they ship what they do have and capture the funds from the cardholder accordingly. Later when the remaining goods are shipped the merchant performs another capture transaction that refers back to the same initial authorisation transaction. This causes the remaining funds to be transferred from the cardholder's account to the merchant's account. The capture transactions will be successful, provided: The total amount for the all captures do not exceed the original Authorisation amount, and The card issuing institution has not expired the original Authorisation transaction. MiGS PC Integration Guide November

11 3 Preparing for Integration Before you start integrating, you must determine if your Payment Provider supports the functions that you require. This will determine the transaction types you can or cannot integrate. Integration Models and Communication Methods There are two ways that you can communicate with the Payment Server to process transactions, the Redirect method and the Direct method. The method you choose is directly related to the Integration Model, either 3-Party or 2-Party, that you use. You may use both methods concurrently if necessary, for example, you may have a Web Store that uses 3-Party, and at the same time a Call Centre taking phone orders using 2-Party. Both applications could be using the Payment Client at exactly the same time. 3-Party Payments Integration Model 3-Party Payments allow the Payment Server to manage the payment pages and collect the cardholder's card details on your behalf. The Payment Server's payment pages could be Bank or Payment Provider branded to help assure the cardholder of a secure transaction. The advantage of 3-Party payments is that the complexity of securely collecting and processing card details is handled by the Payment Server, allowing you to focus on your application's part of the payment process. 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 3rd party branded pages, keeping the branding consistent throughout the whole transaction, except the 3-D Secure pages if the merchant and the cardholder are both enrolled in this antifraud initiative. To do this you would have to comply with the same obligations associated with 2-Party payments. The 3-Party Redirect method only works for web applications where a web browser is involved. This method is also required to implement 3-D Secure antifraud initiatives of Verified by Visa MasterCard SecureCode and J/Secure. The redirect method works with most network configurations and you do not need to take into account proxy servers as the information is communicated to and from the Payment Server using the cardholder's Internet browser. The cardholder's Internet browser is redirected to take the Digital Order to the Payment Server to process the transaction. After processing the transaction, the cardholder's Internet browser is returned to a web page that you nominate in the transaction together with a Digital Receipt. The Digital Receipt processing of the receipt information finalises the transaction. MiGS PC Integration Guide November

12 The 3 parties involved in a 3-Party transaction are the merchant, the payment provider and the cardholder. The cardholder's browser provides the redirect method to communicate the information between the merchant and the payment provider. This is an a-synchronous connection and the cardholder leaves your web site to go to the Payment Server, which means the transaction is broken or disrupted into 2 distinct sessions, the creation of the Digital Order and the processing of the Digital Receipt. Because of this, you may be required to capture session variables and include them in the Digital Order so they can be passed back appended to the Digital Receipt for restoring the original web session. 2-Party Payments Integration Model Merchants who want full control over the transaction and want to manage their own payment pages use the 2-Party integration model. Implementing 2-Party requires you to securely collect the cardholder's card details and then use the Payment Client to send the Digital Orders directly to the Payment Server. This is also called the merchant-managed, or direct model. This model means that you are responsible for securing the cardholders card number and details. The 2-Party does not allow you to implement the 3-D Secure anti-fraud initiatives of Verified by Visa MasterCard SecureCode and J/Secure. The 2 parties involved in a 2-Party transaction are the merchant and the payment provider. The merchant communicates directly through the Payment Client to the Payment Server and back again. This is a synchronous connection and the cardholder does not leave your site, which means the session is not broken or disrupted. The Direct method is also used for advanced Payment Server operations such as 2- Party Purchases and Auths, Captures, Refunds Voids and Queries. Your application communicates directly to the Payment Server using the Payment Client, so you need to take into account working with proxy servers. The methods used to work with these will vary slightly depending on the programming language used by your application, however the Payment Client has the ability to work with HTTP, Socks4 and Socks5 proxy servers. 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 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. MiGS PC Integration Guide November

13 You want to, either now or in the future, increase security by using 3-D Secure authentication (for example, Verified by Visa MasterCard SecureCode and J/Secure ). 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 3-Party transaction, you can collect card details and include them into the Digital Order. However the higher risk and responsibility of collecting card details remains the same as in a 2-Party transaction. 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 MasterCard SecureCode and J/Secure ). For more see Payment Authentication on page 87). 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 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. MiGS PC Integration Guide November

14 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. 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 Dialect PaymentClient). 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 Payment Client Dialect PaymentClient using TCP/IP sockets to pass socket requests and responses. The DLL communicates with a Dialect PaymentClient 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 to a Dialect PaymentClient 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 instantiate 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 MiGS PC Integration Guide November

15 the same JVM using this interface. The DLL and Payment Client must be installed in the same machine. 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. 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. MiGS PC Integration Guide November

16 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 Dialect PaymentClients. 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. Prerequisites This section lists the requirements and basic steps you need to take to build a successful integration. Support Material and Information You must have the following: Payment Client Reference Guide Example Code for your site (written in ASP, JSP, PHP and Perl) Test Card setup document MiGS PC Integration Guide November

17 Determine Your Integration Model You must choose either: 3-Party Payments Integration Model, or 2-Party Payments Integration Model. Combination of 2-Party and 3-Party Integration For more information, please refer to Integration Models and Communication Methods on page 10). Determine the Payment Model Purchase - requires a single transaction to transfer funds from the cardholder's account to your account. Authorisation/Capture - requires two transactions, the Authorisation, followed separately by a Capture. For more information, see Authorisation/Capture Model on page 7). Determine Any Advanced Functionality The available advanced functionality includes: Verified by Visa MasterCard SecureCode and J/Secure. See Securing Your Payments on page 21). Capture. Refund. Voids. QueryDR. Obtain an E-commerce Merchant facility After your E-Commerce merchant facility has been approved, your Financial Institution (FI/Bank) will provide the following information to you: Merchant Number Without this information you cannot perform any transactions. It ensures your settlement funds from successful payments are deposited to your correct account. Terminal Id/s The Payment Provider's identifier/s for the terminal/s used to process payments. MiGS PC Integration Guide November

18 Merchant Category Code (MCC) A four-digit code allocated to you by the Payment Provider based on your business type. Provide Your Financial Institution Merchant Number, Terminal Id/s and MCC to your Payment Provider This information is needed to establish your merchant profile with your Payment Provider. Your merchant profile holds your configuration data including Financial Institution account details and your access credentials to the payments service. Your Payment Provider will then issue you with a unique Payment Server Merchant Id identifying you to the Payment Server and also provide you with a User Name and Password for accessing Merchant Administration to manage your transactions. Perform a Basic Test Transaction Using the Supplied Example Code Successful completion of a transaction using the standard Dialect example code before you implement the integration with your application: Validates that your system is set-up correctly and Ensures basic functionality is available. The standard example code covers common web server scripting languages. You must select the appropriate example for your specific web environment. Note: The standard example code contains examples of how to integrate your application and may not fully correspond with the feature set that you have chosen to implement. Determine the Input and Output Fields Determine how you are going to get the Digital Order input fields and where to store the Digital Receipt output fields in your application. You need to consider: Session Variables when using 3-Party payment (with or without card details) some applications may require session variables to be collected and sent to the Payment Server in the Digital Order. The session variables are returned in the Digital Receipt allowing your application to continue with the order process using the same application session. For more information on session variables see, Handle Session Variables on page 54). Session variables are not required when using the Direct or 2-Party communication method as the session is not broken while performing a transaction. Merchant Transaction Reference (MerchTxnRef) you need to determine how you are going to produce a unique value for a transaction using the MiGS PC Integration Guide November

19 MerchTxnRef field. For more, see Merchant Transaction Reference (MerchTxnRef) on page 19). Design and Implement the Integration You are now ready to payment enable your application. This step requires a web developer familiar with both your application and the web programming language used in your web environment. This guide provides the information and best practice guidelines to assist you with this task. You should also refer to the example code and Payment Client Reference Guide for further assistance. Test Your Integration You need to test your integration by performing test transactions. The Payment Server has a test acquirer facility to test all the different response codes that you are likely to encounter in a live environment. Performing test transactions allows you to test your integration, so that you won't encounter problems when processing real transactions. For more information, please refer to the Test Card set up document supplied to you by your Payment Provider, located in the Payment Client Reference Guide - Appendix C - Test Transport Response. Conduct Final Pre-Production testing It is recommended that you follow standard IT practices and complete final preproduction testing with live credit cards to validate that end-to-end functionality works correctly, including successful settlement of funds from your financial institution. Remember you can always refund these test transactions. Go Live Once you are satisfied that your integration works correctly, please advise your Payment Provider that your testing has been successfully completed. Your Payment Provider will validate your testing results and then provide you with your production profile and instructions on how to change your website from test mode to live production mode, allowing you to process live transactions with your Financial Institution (bank). Commence Live Online Payments You should now be ready to launch your payment enabled application and start processing online payments from your cardholders. MiGS PC Integration Guide November

20 4 Payment Client Integration Guidelines This section describes certain key issues that you must take into account while writing your integration code. Reference Fields It is helpful to have an understanding of the following fields when integrating your payment application. Merchant Transaction Reference (MerchTxnRef) The MerchTxnRef field is a unique identifier that the merchant assigns to each transaction. This unique value is used by the merchant to query the Payment Server database to retrieve a copy of a lost/missing transaction receipt using a 2-Party QueryDR function. This is the only purpose of MerchTxnRef. If you are not going to use the QueryDR function then you don't need to be concerned about MerchTxnRef field. Simply copy the OrderInfo field value into the MerchTxnRef field. You can use a value like an order number or an invoice number as the foundation for the MerchTxnRef. However, if you want to allow cardholders to repeat a transaction that was declined and you want to keep the same order number (or invoice number), you must modify the MerchTxnRef for each subsequent attempt, by appending extra characters for each attempt. For example MerchTxnRef = '1234/1' on first attempt, '1234/2' on second attempt, and '1234/3' on third attempt, etc. Under a fault condition, such as if the Digital Receipt does not arrive back at the merchant's site due to a communication error, you may need to check if the transaction was carried out successfully. A unique MerchTxnRef makes crossreferencing the transactional data easier. This is achieved by performing a QueryDR command that will search the Payment Server's database for the transaction, based on the MerchTxnRef. If you have not given each transaction attempt a unique MerchTxnRef number, then there will be multiple results and the QueryDR command may not return the correct transaction attempt you are looking for as it only returns the most recent transaction information. MiGS PC Integration Guide November

21 If a MerchTxnRef field is not provided the Payment Server copies the OrderInfo field into the MerchTxnRef field so that the QueryDR function can still be used. Providing the OrderInfo is unique then this is an acceptable method of allowing the use of QueryDR. Payment Client Order Information (OrderInfo) OrderInfo is an identifier provided by you to identify the transaction on the Payment Server database. This value will be displayed in the Merchant Administration portal when manually searching transactions. It can be an order number, an invoice number, or a shopping cart number. The OrderInfo field can remain static for each transaction but you should have a unique MerchTxnRef for each transaction as outlined above for use with the QueryDR function. The OrderInfo field is used to send a merchant specified reference, for example, Merchant's Invoice No = OrderInfo and can be used to search for another in Merchant Administration. Ensuring Successful Payments It is recommended that you consult with security experts with experience in your web environment to ensure that your security implementation is suitable for your needs. An issue that merchants have to deal with when implementing payments solutions is "How to be sure that you get paid for the goods you ship?" To ensure that you will be paid means that you need to ensure the response integrity and identification/authentication of the Payment Server during the payment process. To ensure that you will be paid you can: Where possible, implement the 3-Domain Secure services of Verified by Visa MasterCard SecureCode and J/Secure. See Securing Your Payments on page 21). Manually check all transaction results at the Payment Server by logging into Merchant Administration before fulfilling each order. Automatically check transaction results at the Payment Server before fulfilling each order by using the Query DR functionality (if available). Manually Check Transaction Results Using Merchant Administration This process suits merchants with very low volume sales. It requires you to log in to your Merchant Administration and run a report to view the OrderIDs and then match them against the orders logged on your website. If they match, you can ship the product, and follow up on, or discard orders where the payment failed, or the payment does not exist. MiGS PC Integration Guide November

22 The risk is the possible human error of matching OrderIDs with the cardholder's orders manually. Also as volumes grow, the risk may become significant as would the time and cost involved completing the task. Automatically check transaction results If you have implemented 3-Party and a Digital Receipt is not received, this method involves automatically attempting to retrieve the Digital Receipt directly from the Payment Server after each transaction where the Digital Receipt failed to come back. This is because in a 3-Party transaction the communication path via the customer's browser, which is redirected away from the merchant's web site. If the cardholder cancels the transaction, no Digital Receipt will be returned, which is not as reliable as a 2-Party connection to the Payment Server. Also, the transaction may have been successful, but you may not receive a receipt as the communication link failed at the point of redirecting the cardholder's browser back to the merchant's site. To overcome these problems QueryDR is available, but it requires some level of programming ability, and system configuration as proxies and firewalls need to be modified to allow outbound connections. Note: QueryDR cannot be used to retrieve Authentication Only transactions Securing Your Payments This section describes the security features available for the Payment Client. It is recommended that you understand this section before you start integrating your application with the Payment Client. Protecting Cardholder Information Using SSL All websites collecting sensitive or confidential information need to protect the data passed between the cardholder's Internet browser, the application and the Payment Server. SSL is a security technology that is used to secure web server to Internet browser transactions. This includes the securing of any information (such as a cardholder's credit card number) passed by an Internet browser to a web server (such as your web 'Shop & Buy' application). SSL protects data submitted over the Internet from being intercepted and viewed by unintended recipients. The Payment Server is responsible for securing the cardholder details when you implement the 3-Party Integration Model. It uses SSL, which encrypts sensitive financial data to provide a secure transmission between a cardholder and the Payment Server. MiGS PC Integration Guide November

23 When implementing the 2-Party or 3-Party Integration models you must ensure your application presents a secure form using SSL. You should also consider using a secure form in your application when collecting confidential information such as cardholder addresses. Note: SSL should also be used for 3-Party. This avoids the possible browser alert message indicating that the cardholder is being redirected to an unsecured site. This can happen when the cardholder's browser is being redirected back to the merchant's web site with the encrypted Digital Receipt for decryption. If the cardholder clicks on 'No' within the pop-up message, then neither the cardholder nor the merchant will receive any receipt details. How Do My Cardholders Know If My Site is Using SSL? When a cardholder connects to your application using SSL they will see that the changes to and also a small gold padlock will appear in their Internet browser, for example: Whenever an Internet browser connects to a web server (website) over - this signifies that the communication with the Payment Server will be encrypted and secure. You can alert your customers to this fact so they know what to look for when transacting on your web site. Security issues that apply to a payment There are three security issues that apply to a payment: Confidentiality - to protect important information such as credit card numbers. Identification/Authentication - to ensure that DOs are going to the Payment Server and that the Digital Receipt came from the Payment Server. Integrity - when you send and receive messages, you need to be sure that they are not being altered. The Payment Client uses multi-levels of encryption to ensure the Digital Orders and Digital Receipts are not being altered in transit. It encrypts the data and places a digital signature on all DOs going to the Payment Server, similarly it checks the Digital Signatures and decrypts the data on all Digital Receipt's coming from the Payment Server. This is to ensure proper confidentiality, identification/authentication and integrity. Best Practices to Ensure Transaction Integrity The following Best Practices are guidelines only. It is recommended that you consult with security experts with experience in your web environment to ensure that your security is appropriate for your needs. MiGS PC Integration Guide November

24 Use a Unique MerchTxRef for Each Transaction Attempt Each transaction attempt should be assigned a unique transaction reference Id. Most applications and web programming environments will generate a unique session for each cardholder, which can be used as the unique merchant transaction reference Id. You can alternatively create a unique reference id by combining a order/invoice number with a payments attempt counter. You may also consider appending a timestamp to the transaction reference Id to help ensure that each one is unique. Before sending a transaction to the Payment Server, you should store this unique transaction reference Id with the order details in your database. The merchant transaction reference id is returned in the Digital Receipt. The unique transaction reference Id is required for you to reliably use the QueryDR function to retrieve the transaction details you may be searching for. For example, if a transaction is reported as lost or missing, you can use QueryDR to locate it. Check that the field values in the Digital Receipt match those in the Digital Order You should ensure that important fields such as the amount in the Digital Receipt and the merchant transaction reference id match up with the values in the Digital Order. Check for a Replay of a Transaction You should check each Digital Receipt to ensure that your unique Merchant Transaction Reference Id matches that order, and that it does not correspond with any previous order that has already been processed. Check for suspect transactions Common things to look out for are: Use of free/anonymous by the cardholder Different Ship To and Bill To addresses Foreign orders or shipments from countries with reputations for high fraud activities High-priced orders Multiples of the same item. Note: It is recommended that you do not store any credit card information in your web site database. If you must store credit card numbers, they should be securely hardware encrypted, or you should store them as masked values (for example, XXXXXXX769). Use Good Password Security for Merchant Administration It is highly recommended that you choose a password that is difficult to guess and change your password regularly. A good password should be at least 8 characters and should contain a mix of capitals, numbers and special characters. MiGS PC Integration Guide November

25 Validate the SSL Certificate of the Payment Server It is highly recommended that you validate the SSL certificate of the Payment Server whenever you connect to the Payment Server. The Payment Server SSL certificate is issued by an industry standard Certificate Authority such as Verisign or Thawte whose root certificate should already be available in your web environment. Note: Please consult a web developer if you are not familiar with validating SSL certificates or exporting certificates from websites. Always ensure the server is a trusted source. Using 3-D Secure Payment Authentications 3-D Secure Payment Authentication contains Verified by Visa MasterCard SecureCode and J/Secure, which are designed to minimise credit card fraud, by attempting to authenticate cardholders when performing transactions over the Internet. Authentication ensures that a legitimate owner is using the card as the Payment Server redirects the cardholder to their card issuing institution where they must enter a password that they had previously registered with their card issuer. To use Verified by Visa MasterCard SecureCode and J/Secure, you need to request a 3-D Secure enabled merchant profile from your Payment Provider and implement the 3-Party Payment Integration Model. Note: Payment authentication is only supported for web transactions using 3-Party Payments through a browser. This is because the cardholder's web browser must be redirected to their card issuing bank. For the information flow of a 3-Party Authentication & Payment transaction please see Authentication Information Flow (see "Information Flow of a 3D-Secure Authentication/Payment transaction" on page 89). Setting up Transactions Each transaction and/or query requires data or information to be provided to perform the required action, for example, captures, refunds and QueryDR. All functionality is made up of primary and supplementary commands. Primary and Supplementary Commands Primary command triggers the transaction/query to be processed by the Payment Client and sent to the Payment Server. The only exception of information not being sent to the Payment Server is the 3-Party commands, which are sent to/from the Payment Server via browser redirect commands. Supplementary commands provides the primary command with the extra data required for the transaction/query to be implemented. These only work locally with the Payment Client. No information is transmitted between the MiGS PC Integration Guide November

26 Payment Client and the Payment Server when these supplementary commands are executed. For example, if Address Verification Service data and a ticket number is added to a 2-Party or 3-Party transaction, an adddigitalorderfield (supplementary command) is used multiple times to present the data to the Payment Client. When all this required data for the functionalities has been passed to the Payment Client, the 2-Party sendmotodigitalorder and 3-Party getdigitalorder (primary commands) is used to generate the Digital Order. These extra functions extend the underlying transaction to include Address Verification Service data and a ticket number in the same transaction. Examples of primary commands available for transactional functionality are: 2-Party Payment (sendmotodigitalorder) 3-Party Payment (getdigitalorder, decryptdigitalreceipt) 1 Capture Payment (doadmincapture) Refund Payment (doadminrefund) Void a Purchase (doadminvoidpurchase) Void a Capture (doadminvoidcapture) Void a Refund (doadminvoidrefund) Query transactional information for a purchase or authorisation (doadminfinancialtransactionhistory) 2 Query transactional history (doadminshoppingtransactionhistory) Reconcile a batch of transactions (doadminreconciliation) Query the details of a specific batch reconciliation (doadminreconciliationdetail) Query batch reconciliation history (doadminreconciliationhistory) Query a transaction to retrieve its Digital Receipt (doquerydr) For the related commands for the Sockets interface, see the PC Integration Reference Guide. For details on 3-Party transactions see Basic 3-Party Transaction on page 55. For details on 2-Party transactions see Basic 2-Party Transaction on page 34. Command Results The Payment Client supports transactions that return a single result, and queries that return multiple result sets. MiGS PC Integration Guide November

27 After a transaction is performed, a Digital Receipt is sent from the Payment Server that contains a single set of result fields for the transaction. For example, a 2-Party, 3-Party, or a Refund transaction returns a Digital Receipt containing a set of values that is used to indicate the result of the transaction. One such field is the QSIResponseCode, which indicates whether the transaction was successful or not. Another field would be the TransactionNo for the of the transaction number identity in the Payment Server. Queries may return multiple sets of result fields. For example, a query that returns all transactions within a specified period would return a result set for each transaction within that period. This query may return zero, one or more results, depending on the number of results found that match the search specified criteria. Transactions that return a single result When processing a transaction/query, the Payment Client sends a message to the Payment Server and receives a response containing a single set of values applicable to that transaction. The following process is used to perform a 2-Party transaction, plus Captures, Refunds, Voids, QueryDR. MiGS PC Integration Guide November

28 1. Connect to the Payment Client, depending on the implementation being used, Java/COM or Sockets. 2. An echo test is performed to check that communication is established correctly with the Payment Client. 3. Extra-required data for the functionality being used is sent to the Payment Client. This step may not be required for all transactions. Please refer to the functionality being used to determine the data requirements. 4. The primary command is sent to the Payment Client, which performs the specified command and communicates with the Payment Server. 5. The nextresult command is used to check if the transaction contains valid results. If there were errors go to step The data is extracted from the result set using the getresultfield command to enable the merchant to process the transaction. It is customary to first determine if any processing errors occurred by QSIResponseCode ='7'. If there were no errors returned, continue retrieving the results. 7. Disconnect from the Payment Client. 8. This step is used after the primary command and nextresult to retrieve an error message from the Payment Client to explain the failure of these commands 9. This step is only used to retrieve a processing error message from the Payment Client to explain if the QSIResponseCode = '7'. 10. This step is used to perform appropriate error handling. 11. This step is used to perform appropriate error handling when no connection was made. Determining Errors in a Transaction that Return a Single Result A transaction that is not successfully processed produces errors that can be detected at various stages to determine the reason for the error. MiGS PC Integration Guide November

29 Step 1: Connecting to the Payment Client If this step fails then you are unable to connect to the Payment Client. Errors that can cause a connection failure are: 1 The Payment Client has been incorrectly installed. In a Sockets implementation, the merchant application is unable to establish a socket connection to the Payment Client host machine and port. Check the PCService is running on the host and specified port in your merchant application. Also check the networking hardware and configuration to determine whether or not there is a hardware failure. 2 The Payment Client classes directory and/or the PaymentClient.jar file is not correctly entered into the JVM classpath for a Java implementation, so the Payment Client object cannot be instantiated. 3 A semantic error may exist when trying to invoke the Payment Client, and it cannot be found to be invoked. You may not have rebooted after installation for the COM interface. Step 2: Performing the echo test If the echo test fails, the Payment Client is not able to communicate or execute commands correctly. The errors likely to cause this are the same as those listed in Step 1 Step 3: Executing the primary command A failure is indicated by a Boolean return value of false in a Java or COM implementation, or 0,0 for Sockets. If the primary command encounters an error, it is caused by either incorrect input details being supplied to the primary command, incorrect configuration of the Payment Client (incorrect keys are installed), or the Payment Client cannot communicate with the Payment Server (usually a network configuration/firewall problem). Step 4: Executing the nextresult command A failure is indicated by a Boolean return value of false in a Java or COM implementation, or 0,0 for Sockets. Errors that occur executing the nextresult command means the Payment Server has detected an error in processing the Digital Order. To determine the error in Java or COM the command getresultfield( PaymentClient.Error ) is used. In Sockets the command 4, PaymentClient.Error\n is used. These commands return the error code and description of the error. MiGS PC Integration Guide November

30 Step 5: Checking if the QSIResponseCode = 7 If the Payment Server has detected an error processing the transaction, it will return a QSIResponseCode equal to 7. To determine the error the command: getresultfield("digitalreceipt.error") is used. In Sockets the command 4,DigitalReceipt.ERROR\n is used. This command returns a description of the error that can be found in the Payment Client Reference Guide, Appendix B. Queries that Return Multiple Results When processing a transaction/query, the Payment Client sends a message to the Payment Server and receives a response containing a single set of values for the transaction. Queries may return multiple sets of result fields. These queries may return zero, one or more results, depending on the number of results found that match your search criteria. For a function that has the ability of returning multiple results, the following steps are used for a successful query: MiGS PC Integration Guide November

31 1. Connect to the Payment Client, depending on the implementation being used, Java/COM or Sockets. 2. An echo test is performed to check that communication is established correctly with the Payment Client. 3. Any extra-required data for the functionality being used is sent to the Payment Client. This step may not be required for all transactions. Please refer to the functionality being used to determine the data requirements. 4. The primary command is sent to the Payment Client, which performs the command specified and communicates with the Payment Server. 5. The nextresult command is used to check if the transaction contains valid results. 6. Find out the number of records returned by the query, by using the getresultcount command. 7. The data is extracted using the getresultrecord command to enable the merchant to process the result through their application. Please refer to the functionality being implemented to find out what data is available. This step is performed for each result record returned in the query. The command getresultcount identifies how many results have been returned. 8. Disconnect from the Payment Client. 9. This step is only used after both the primary command and the nextresult to retrieve an error message from the Payment Client to explain the failure of the nextresult command. The getresultfield command is used to retrieve the error description (retrieved using the field name "PaymentClient.Error"). 10. This step is only used to retrieve a processing error message from the Payment Client to explain if the QSIResponseCode = '7'. 11. This step is used to perform appropriate error handling. 12. This step is used to perform appropriate error handling when no connection was made. For more information on the commands used with the Payment Client, refer to the Payment Client Reference Guide. If a transaction is not processed successfully, errors can be detected at various stages to indicate the reason for the error. These are at the same steps outlined in the previous section. MiGS PC Integration Guide November

32 Setting up the Sockets' Interface The Payment Client contains a socket listener application, PCService, which can be started and run in the background. Sockets work by the merchant sending a command message string, with each string starting with a number and followed by data. The number at the front of the string identifies the command type to be executed. Every message sent would be actioned by the Payment Client, which in turn sends back a response. This response consists of two fields separated by a comma, for example '0,0' or '1,echo:Test'. The first field will always be either a status digit of a '0' or a '1'. A first digit of '0' indicates the previous command to the Payment Client failed. A first digit of '1' indicates the previous command to the Payment Client was successful. The second field is the data field. If there is no data to be returned then the second digit is a copy of the first digit. Failed transactions never return any data and so the responses are always '0,0'. Many commands, for example, sending the card number do not return any data from the Payment Client so they have a successful response of '1,1'. Other successful responses to a socket command that do send back data, such as the echo command, will have a status response of '1,' followed by the return data, for example 'echo:test' - the full response becoming '1,echo:Test'. In most applications, the Sockets are set-up with a socket time out value, which determines how long the socket will wait for a response from the Payment Client after sending a command. This allows the merchant application to detect possible failures in the payment process. If the socket times out it must be actioned or it may result in either a duplicate transaction or a single transaction occurring but not recorded as the Payment Client could not pass the information back to the application. For more information, see Handling Socket connection Time Outs on page 106). Note1: In each of the socket example commands shown in this guide, the \n 'New Line' character at the end of each command string is used to tell Java to input a Line Feed character to indicate the end of the command. Failure to include the "\n" 'New Line' character or a Carriage Return character - Java \r at the end causes the socket command to fail. Some programming languages such as ASP can automatically add this to the end of the command so the programmer does not have to include it. Note2: The data for any socket command cannot contain either a 'New Line' (ASCII 010DEC) or a 'Carriage Return' (ASCII 013DEC) character. The comma ',' character (ASCII 044DEC) and the pip ' ' character (ASCII 124DEC) are also prohibited from the data field. The only commands excepted are commands 26 (adddigitalorderxmlfield) and 27 (addadminxmlfield) which use an extra field that defines how many characters are in the data field. If a data field, such as an XML data field contains any of these characters, you must use the adddigitalorderxmlfield or addadminxmlfield commands. Failure to do so will cause the transaction to fail, as the socket listener will prematurely see the end of that command, and not receive all the required data. MiGS PC Integration Guide November

33 For a full list of socket commands, see the Payment Client Reference Guide. MiGS PC Integration Guide November

34 5 Integrating 2-Party Payments In the 2-Party Integration Model, a cardholder places an order and provides their card details (card type, card number and expiry date) to you by Mail Order or by Telephone Order (MOTO transactions) including Interactive Voice Response (IVR) systems, or some card present application like a ticketing system. You can implement the 2-Party Integration Model if you prefer cardholders to provide their card details (card type, card number and expiry date) to you rather than to the Payment Server. 2-Party Payments carry a higher risk than 3-Party, as you are responsible for protecting the cardholder's card details. Merchant-hosted Information Flow The following diagram illustrates how a merchant application would make merchanthosted 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... MiGS PC Integration Guide November

35 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. Basic 2-Party Transaction The basic 2-Party transaction follows the process shown in Transactions that return a single result on page 26. The basic flow in a 2-Party transaction consists of two parts: Create and send the Digital Order. Extract the Digital Receipt details. Input Data - 2-Party Transaction Supplementary data, for example, the card number and card expiry date are added using the supplementary command: adddigitalorderfield. This supplementary command is in the format of a String value that represents a key, followed the data value for that key. Three instances of this command are required to add the following information prior to performing the sendmotodigitalorder primary command. Card Number (CardNum) Card Expiry Date (CardExp) Merchant Transaction Reference Value (MerchTxnRef) The number of the card to be processed for payment. It can only be a long integer value with no white space or formatting characters. The expiry date of the card to be processed for payment. The format for this is YYMM, for example, for an expiry date of May 2013, the value would be The value must be expressed as a 4-digit number (integer) with no white space or formatting characters. This field is optional and the merchant can use this field to uniquely identify the transaction for retrieving a duplicate copy of the receipt using the QueryDR function. This identifier is the primary key to the data in the Payment Server database and can use text made up of any of the base US ASCII characters in the range, hexadecimal 20 to 126. If the MerchTxnRef value is not submitted, the OrderInfo field is copied into the MerchTxnRef field in the Payment Server. Note: It is important to make sure this number is stored so that you can retrieve a copy of the Digital Receipt data of a transaction if a communications failure occurred and the Digital Receipt is not received. MiGS PC Integration Guide November

36 Java and COM Examples adddigitalorderfield( CardNum, ) adddigitalorderfield( CardExp, 1305 ) adddigitalorderfield("merchtxnref", ) Sockets Examples 7,CardNum, \n 7,CardExp,0905\n 7,MerchTxnRef,12345\n Primary Command: sendmotodigitalorder This primary command requires the following information: Order Information Number (OrderInfo) Merchant Identification Number (MerchantId) Purchase Amount (PurchaseAmountInteger) Locale (Locale) Return URL (ReturnURL) This is used to input any merchant/customer information about this transaction that may be required to be stored. Null values are not accepted. The merchant ID is an alphanumeric identifier that is given to the merchant during the Payment Provider's registration process, which is used to identify the merchant on the Payment Server. The merchant uses the merchant ID to log in to Merchant Administration. There is a unique MerchantId for each merchant account/profile on the Payment Server. The purchase amount of the transaction expressed as an integer in the lowest currency denominator, for example, Pence, Cents, Euro, Yen. It does not contain any decimal points, thousands separators or currency symbols, for example. $12.50 is expressed as Reserved for future use. Please use the default value of en. Reserved for future use. Please use the default value of (empty string). Java and COM Examples sendmotodigitalorder(orderinfo, MerchantId, PurchaseAmountInteger, en, ) Sockets Example 6, + OrderInfo +, + MerchantId +, + PurchaseAmountInteger+,en,\n Output Data - 2-Party Transaction The 2-Party transaction returns the following fields in the Digital Receipt received by the Payment Client if the transaction was processed. Merchant Transaction Reference (MerchTxnRef) Order Information Number (OrderInfo) Merchant Identification Number (MerchantId) The input value passed back in the receipt. It is the reference number allocated by the merchant's software. This code should be unique for every transaction. The merchant's information about this transaction. Can be a simple order number or shopping basket number. The input value passed back in the receipt. It is an alphanumeric identifier that is given to the merchant during the Payment Provider's registration process, which is used to identify the merchant on the Payment Server. The merchant uses the merchant ID to log in to Merchant Administration. There is a unique MerchantId for each merchant account/profile on the Payment Server. MiGS PC Integration Guide November

37 Purchase Amount (PurchaseAmountInteger) QSI Response Code (QSIResponseCode) Acquirer's Response Code (AcqResponseCode) Payment Server Transaction Number (TransactionNo) Transaction Receipt Number (ReceiptNo) Authorisation Identification Code (AuthoriseId) Transaction Batch Number (BatchNo) Card Type (CardType) The input value passed back in the receipt. It is the purchase amount of the transaction expressed as an integer in the lowest currency denominator, for example, pence, cents, Euro, yen, etc. It does not contain any decimal points, thousands separators or currency symbols, for example. $12.50 is expressed as A single character response code that is generated by the Payment Server. A QSIResponseCode of 0 (zero) indicates that the transaction was processed successfully and approved by the acquiring institution. Any other value indicates a transaction failure. Please refer to the Payment Client Reference Manual for a complete list of valid values and their descriptions. The response code that is generated by the financial institution. This can vary between institutions. It is included for faultfinding purposes. A unique number generated by the Payment Server and is the OrderID (Shopping Transaction number) for a transaction. It is important to make sure the TransactionNo is stored for later retrieval if required to perform queries or Advanced Merchant Administration commands, e.g.captures, refunds. The RRN is a unique number generated by the payment processor. This is the value that is passed back to the cardholder for their records if the merchant's application does not provide its own receipt number. A code issued by the acquiring payment processor to approve or reject a transaction. The Batch number on the Payment Server that this transaction will be added to in order to be processed by the acquiring institution. The Card Type is a code that details what type of card was used to carry out this transaction. The codes are detailed in the Payment Client Reference Guide. When a transaction is not processed successfully, errors can be detected at various stages to indicate the reason for the error. The process described in Determining Errors in a Transaction that Return a Single Result on page 27 section of this chapter is used. Payment Generic Request Functionality Fields The generic request mechanism, dorequest allows for the rapid introduction of new Payment Server facilities. Payment Provider Defined Fields A further set of optional Digital Order fields may be available, known as Payment Provider Defined Digital Order Fields. Consult the documentation from your Payment Provider for more information on the available Payment Provider Defined Digital Order Fields, their meaning, field type and length. 2-Party Tutorial A payment in a 2-Party transaction consists of two parts: MiGS PC Integration Guide November

38 To create and send the Digital Order. Extract the Digital Receipt details. This tutorial focuses on conducting a 2-Party transaction using the Java Payment Client API calls (please refer to the Payment Client Reference Manual for more details). However the steps used in this tutorial can be applied to any programming language. To process a Digital Order for a 2-Party transaction there are six main steps to follow. 1 Instantiate and test the Payment Client. 2 Perform echo test with the Payment Client 3 Add all the extra Digital Order details that are not included in the sendmotodigitalorder API command. The fields that must be added for a standard payment are: CardNum CardExp MerchTxnRef Number 4 Create and send the Digital Order to be processed. 5 Check there is a valid result 6 Retrieve the Digital Receipt details. Instantiate and test the Payment Client Instantiate the Payment Client object To instantiate the Payment Client, an example of the API call in Java to create the Payment Client is: // Instantiate a Payment Client PaymentClientImpl objpayclient = new PaymentClientImpl(); The variable objpayclient is a local variable to this merchant application and may be changed to any name that suits this implementation. However, for this tutorial, the Payment Client object continues to be called objpayclient. After execution, a Payment Client object has been instantiated and stored in the variable objpayclient. To test if the object has been successfully created in Java, use a try/catch statement to catch any errors in the creation of the object. In other languages such as Visual Basic you may use statements like the On Error statement to determine if the Object has not been created successfully. When using the COM interface there are two ways that the Payment Client object can instantiated. ' Instantiate a Payment Client set objpayclient = Server.CreateObject( PaymentClient.com.COMClient ) The VBScript above will instantiate the COM Object using the default interface that is configured for the COM Object during installation. MiGS PC Integration Guide November

39 ' Instantiate a Payment Client set objpayclient = Server.CreateObject( PaymentClient.Sockets ) ' Optionally use the TCP/IP Socket connection method. ' Host address of the Payment Client PCService objpayclient.hostaddress = ' Port that the Payment Client PCService is listening on objpayclient.portnumber = 9050 ' Socket timeout to use when communicating to the Payment Client PCService (in milliseconds) objpayclient.timeout = ' 100 seconds The VBScript above will instantiate the COM Object using the TCP/IP sockets interface. Using this method of instantiating the COM Object the user can configure the sockets settings such as the host, port and timeout to use to connect to the Payment Client PCService programmatically at runtime. If these settings are not explicitly set in the program then the COM Object will use the default settings configured during installation. The host, port and timeout cannot be set when the PaymentClient.com.COMClient ProgID is used, even if TCP/IP sockets is the default interface for the COM Object. Echo Test To test the Payment Client, an echo command is used which returns the string value you send with the echo command appended to the string echo: This test ensures that the Payment Client object has been instantiated correctly and that a communications path has been established and is functioning properly between the Payment Client and this merchant application. An example of the Java call to perform the echo test and check for a valid response is: // Test the Payment Client object created correctly String result = objpayclient.echo("test"); if (!result.equals("echo:test")) { // perform error handling for this command return; } The contents of the 'if' statement performs the actions for your implementation. It may be very simple, such as displaying an error and terminating the process. For a production implementation a more sophisticated response may be warranted. Add all the extra Digital Order fields Extra Digital Order fields must be added before the API call to send the Digital Order. This is because the API call collects all the Digital Order data that the Payment Client has been sent and it creates the complete encrypted Digital Order. For a standard 2-Party Digital Order, the minimum extra data that must be included to create a valid Digital Order are Card Number, Card Expiry date and MerchTxnRef. An example of adding the extra fields is: // Add card fields to Digital Order objpayclient.adddigitalorderfield("cardnum", cardnumber); objpayclient.adddigitalorderfield("cardexp", cardexpiry); objpayclient.adddigitalorderfield("merchtxnref", merchtxnrefvalue); MiGS PC Integration Guide November

40 Create and Send the Digital Order to be Processed The Payment Client collects all the data that it has been sent and encrypts it to create the Digital Order. All the 2-Party primary commands like sendmotodigitalorder are synchronous calls (they block the Payment Client thread until they are able to return a result - success or failure). An example of the code to create and send the Digital Order is: if (!objpayclient.sendmotodigitalorder(orderinfo, MerchantId, PurchaseAmountInteger, en, )) { // perform error handling for this command return } The content of the 'if' statement should perform the actions for your implementation. It may be very simple, such as displaying an error and terminating the process. For a production implementation a more sophisticated response may be warranted. Check there is a valid result After the Digital Order has been processed you need to ensure that the Payment Client has received a valid Digital Receipt from the Payment Server and that there are results to process. To do this, use the nextresult API command. An example of checking if a valid Digital Receipt has been received is: // Get the nextresult value to check there are results to process. if (!objpayclient.nextresult()) { // retrieve the error description from the Payment Client String error = objpayclient.getresultfield("paymentclient.error"); // perform error handling for this command return } The content of the 'if' statement perform the actions for your implementation. It may be very simple, such as displaying an error and terminating the process. There is an extra step in this 'if' statement as you can now receive an error description from the Payment Client to explain why the transaction did not return a valid Digital Receipt. This error description may not always contain data, as it may be an empty string ( ). Retrieve the Digital Receipt details Now that a valid Digital Order exists, you need to retrieve the Digital Receipt details from the Payment Client. To do this you use the getresultfield() API command. An example of retrieving each result is: // Extract the available Digital Receipt fields // Get the QSIResponseCode for the transaction // Get the results for each of the receipt variable required. String qsicode = objpayclient.getresultfield("digitalreceipt.qsiresponsecode"); // Check if the result contains an error message if (!qsiresponsecode.equals("null") &&!qsiresponsecode.equals("0")) { // check if an error returned from the Payment Client MiGS PC Integration Guide November

41 result = objpayclient.getresultfield("digitalreceipt.error"); if (result!= null && result.length()!= 0) { // The response is an error message so display an Error Page exception = result; // perform error handling to find out why transaction failed } else { // Extract the available Digital Receipt fields // The example retrieves the MerchantId and Transaction Amount values, // which should be the same as the values sent. In a production // system the sent values and the receive values could be checked to // make sure they are the same. String merchantid = objpayclient.getresultfield("digitalreceipt.merchantid"); String orderinfo = objpayclient.getresultfield("digitalreceipt.orderinfo"); String merchantrefno = objpayclient.getresultfield("digitalreceipt.merchtxnref"); String txnamount = objpayclient.getresultfield("digitalreceipt.purchaseamountinteger"); String receiptno = objpayclient.getresultfield("digitalreceipt.receiptno"); String transno = objpayclient.getresultfield("digitalreceipt.transactionno"); String acqcode = objpayclient.getresultfield("digitalreceipt.acqresponsecode"); String authoriseid = objpayclient.getresultfield("digitalreceipt.authorizeid"); String batchnumber = objpayclient.getresultfield("digitalreceipt.batchno"); } } Normally, these receipt variables would not be declared at this point of the merchant application, but would have been defined earlier. You now need to return these values to the application that called the payment process. To check if the transaction was successful the QSIResponseCode is checked. Any value other than 0 (zero) is a declined/failed transaction, see list of QSIResponseCodes in the Payment Client Reference Guide. An example of the Java code The following code blocks are not complete and would not compile. Java extras like retrieving input variables and try/catch blocks have been omitted for the sake of readability, but the principles of how the code works is correct. An example of putting all these code extracts together, and the application becomes: // Step 1 - Connect to the Payment Client // ************************************** // create a Payment Client object objpayclient = new PaymentClientImpl(); // Step 2 - Test the Payment Client object was created successfully // **************************************************************** // Test the communication to the Payment Client using an "echo" result = objpayclient.echo("test"); if (!result.equals("echo:test")) { // Display error as communication to the Payment Client failed // perform error handling for this command return; } // Step 3 - Prepare to Generate and Send Digital Order // *************************************************** // The extra details are not accepted by the MiGS PC Integration Guide November

42 // sendmotodigitalorder() method and so we must add them // explicitly here for inclusion in the DO creation. // Adding the supplementary data to the DO is done using the //"adddigitalorderfield" command // add card number and card expiry objpayclient.adddigitalorderfield("cardnum", cardnumber); objpayclient.adddigitalorderfield("cardexp", cardexpiry); // add MerchTxnRef number objpayclient.adddigitalorderfield("merchtxnref", merchtxnref); // Step 4 - Generate and Send Digital Order (& receive DR) // ******************************************************* // Create and send the Digital Order // (This primary command also receives the Digital Receipt) if (!objpayclient.sendmotodigitalorder(orderinfo, merchantid, amount, "en", "")) { // Retrieve the Payment Client Error (There may be none to get) result = objpayclient.getresultfield("paymentclient.error"); if (result!= null && result.length()!= 0) { exception = result; } // perform error handling for this command return; } // Step 5 - Check the DR to see if there is a valid result // ******************************************************* // Use the "nextresult" command to check if the DR contains a result if (!objpayclient.nextresult()) { // Retrieve the Payment Client Error (There may be none to get) result = objpayclient.getresultfield("paymentclient.error"); if (result!= null && result.length()!= 0) { exception = result; } // perform error handling for this command return; } // Step 6 - Get the result data from the Digital Receipt // ***************************************************** // Extract the available Digital Receipt fields // Get the QSIResponseCode for the transaction // Get the results for each of the receipt variable required. String qsicode = objpayclient.getresultfield("digitalreceipt.qsiresponsecode"); // Check if the result contains an error message if (!qsiresponsecode.equals("null") &&!qsiresponsecode.equals("0")) { // check if an error returned from the Payment Client result = objpayclient.getresultfield("digitalreceipt.error"); if (result!= null && result.length()!= 0) { // The response is an error message so display an Error Page exception = result; // perform error handling to find out why transaction failed } else { // Extract the available Digital Receipt fields // The example retrieves the MerchantId and Transaction Amount values, // which should be the same as the values sent. In a production // system the sent values and the receive values could be checked to // make sure they are the same. String merchantid = objpayclient.getresultfield("digitalreceipt.merchantid"); String orderinfo = objpayclient.getresultfield("digitalreceipt.orderinfo"); String merchantrefno = objpayclient.getresultfield("digitalreceipt.merchtxnref"); String txnamount = objpayclient.getresultfield("digitalreceipt.purchaseamountinteger"); String receiptno = objpayclient.getresultfield("digitalreceipt.receiptno"); MiGS PC Integration Guide November

43 String transno = objpayclient.getresultfield("digitalreceipt.transactionno"); String acqcode = objpayclient.getresultfield("digitalreceipt.acqresponsecode"); String authoriseid = objpayclient.getresultfield("digitalreceipt.authorizeid"); String batchnumber = objpayclient.getresultfield("digitalreceipt.batchno"); } } else { // Display an error as QSIResponseCode could not be retrieved // perform error handling for this command return; } // Step 7 - We are finished with the Payment Client so tidy up // *********************************************************** // nothing to be done in Java An example of the Java code in sockets The following Java Sockets implementation code block is not complete and would not compile. Java extras like importing the Java libraries, retrieving input variables from the order form and try/catch blocks have been omitted for readability, but the principles of how the code works is correct if these extras were added it would be fully functional. The related commands for the Sockets interface are shown in The Payment Client Reference Manual. The steps for sockets are exactly the same as the Java code above, only the implementation method changes. // Step 1 - Connect to the Payment Client // ************************************** // Create a socket object to the Payment Client Socket sock = new Socket(payClientIP, payclientport); // The Buffered Reader data input stream from the socket BufferedReader in = new BufferedReader( new InputStreamReader(sock.getInputStream())); // The output stream to the socket PrintStream out = new PrintStream(sock.getOutputStream()); // Step 2 - Test the Payment Client object was created successfully // **************************************************************** // Test the communication to the Payment Client using an "echo" out.print("1,test\n"); cmdresponse = in.readline(); if (!cmdresponse.equals("1,echo:test")) { // perform error handling for this command sock.close(); return; } // Step 3 - Prepare to Generate and Send Digital Order // *************************************************** // The extra details are not accepted by the // sendmotodigitalorder() method and so we must add them // explicitly here for inclusion in the DO creation. // Adding the supplementary data to the DO is done using the //"adddigitalorderfield" command // add card number out.print("7,cardnum," + cardnumber + "\n"); cmdresponse = in.readline(); // check the status to make sure the command completed OK MiGS PC Integration Guide November

44 if (!cmdresponse.equals( 1,1 )) { // perform error handling for this command sock.close(); return; } // card expiry date data out.print("7,cardexp," + cardexpiry + "\n"); cmdresponse = in.readline(); if (!cmdresponse.equals( 1,1 )) { // perform error handling for this command sock.close(); return; } // merchant transaction reference data out.print("7,merchtxnref," + merchtxnref + "\n"); cmdresponse = in.readline(); if (!cmdresponse.equals( 1,1 )) { // perform error handling for this command sock.close(); return; } // Step 4 - Generate and Send Digital Order (& receive DR) // ******************************************************* // Create and send the Digital Order // (This primary command also receives the Digital Receipt) out.print("6, + OrderInfo +, + MerchantId +, + PurchaseAmountInteger+,en,\n ); cmdresponse = in.readline(); if (!cmdresponse.equals( 1,1 )) { // Retrieve the Payment Client Error (There may be none to get) out.print("4,paymentclient.error\n"); cmdresponse = in.readline(); // check the first status char of the return message // if OK there is value to get if (cmdresponse.substring(0,1).equals( 1 )) { exception = cmdresponse.substring(2); } // perform error handling for this command sock.close(); return; } // Step 5 - Check the DR to see if there is a valid result // ******************************************************* // Use the "nextresult" command to check if the DR contains a result out.print( 5\n ); cmdresponse = in.readline(); if (!cmdresponse.equals( 1,1 )) { // retrieve the error description from the Payment Client out.print("4,paymentclient.error\n ); cmdresponse = in.readline(); // check the first status char of the return message // if OK there is value to get if (cmdresponse.substring(0,1).equals( 1 )) { exception = cmdresponse.substring(2); } // perform error handling for this command sock.close(); return; } // Step 6 - Get the result data from the Digital Receipt // ***************************************************** // Also Extract the other available Digital Receipt fields // The example retrieves the MerchantId and Amount values, MiGS PC Integration Guide November

45 // which should be the same as the values sent. In a production // system the sent values and the receive values could be checked to // make sure they are the same. String qsiresponsecode = ""; // Get the QSI Response Code for the transaction out.print( 4,DigitalReceipt.QSIResponseCode ); cmdresponse = in.readline(); if (!cmdresponse.substring(0,1).equals( 1 )) { // Display an Error Page as the QSIResponseCode could not be retrieved // perform error handling for this command sock.close(); return; } else { qsiresponsecode = cmdresponse.substring(2); } // If non-zero result, check if the result is an error message if (!qsiresponsecode.equals("0")) { out.print( 4,DigitalReceipt.ERROR ); cmdresponse = in.readline(); // check the first status char of the return message // if OK there is value to get if (!cmdresponse.substring(0,1).equals( 1 )) { exception = cmdresponse.substring(2); // The response is an error message so display an Error Page // perform error handling for this command sock.close(); return; } } out.print( 4,DigitalReceipt.MerchTxnRef\n ); cmdresponse = in.readline(); merchtxnref = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.OrderInfo\n ); cmdresponse = in.readline(); orderinfo = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.MerchantId\n ); cmdresponse = in.readline(); merchantid = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.PurchaseAmountInteger\n ); cmdresponse = in.readline(); amount = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.TransactionNo\n ); cmdresponse = in.readline(); transactionno = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.ReceiptNo\n ); cmdresponse = in.readline(); receiptno = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.AcqResponseCode\n ); cmdresponse = in.readline(); acqresponsecode = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.AuthorizeId\n ); MiGS PC Integration Guide November

46 cmdresponse = in.readline(); authorizeid = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.BatchNo\n ); cmdresponse = in.readline(); batchno = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.CardType\n ); cmdresponse = in.readline(); cardtype = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; // Step 7 - We are finished with the Payment Client so tidy up // *********************************************************** sock.close(); This code has been written without methods/subroutines that would reduce the duplication of code. It demonstrates how the six steps come together. MiGS PC Integration Guide November

47 6 Integrating 3-Party Payments This section describes the information flow and integration model for 3-Party Payments. The 3 parties involved in a 3-Party transaction are the merchant, the payment provider and the cardholder. 3-Party Payments allow the Payment Server to manage the payment pages and collect the cardholder's card details on your behalf. The cardholder's Internet browser is redirected to take the Digital Order to the Payment Server to process the transaction. After processing the transaction, the cardholder's Internet browser is returned to a web page that you nominate in the transaction together with a Digital Receipt. The Digital Receipt processing of the receipt information finalises the transaction. Dialect-hosted Payment Information Flow How Dialect-hosted Payments are Processed Dialect-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 example demonstrates how a merchant application would use Dialecthosted payments. MiGS PC Integration Guide November

48 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. 5 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. MiGS PC Integration Guide November

49 What the Cardholder Sees In 3-Party Payments, the cardholder is presented with the following pages: The merchant's application checkout page The application checkout page displays the line items that the cardholder wants to purchase and the total amount to pay, including any delivery charges and taxes. The cardholder accepts the amount and proceeds to the payment server payment pages to enter their card details. The application checkout page is created by the merchant and displayed on their website. The Payment Server's payment options page The Payment Server creates this and the following pages. MiGS PC Integration Guide November

50 The payment options page presents the cardholder with the card types the merchant accepts. The cardholder clicks a card type and proceeds to the Payment Details web page. The Payment Server's payment details page MiGS PC Integration Guide November

51 On the Payment Details page, the cardholder enters their card details including the card number, expiry date, and card security code(if applicable). Then the Payment Server processes the payment. The Payment Server's payment pending page As the bank is processing the payment, a payment pending page can be displayed to the cardholder. MiGS PC Integration Guide November

52 The Payment Server's redirection page The redirection page is displayed in the cardholder's browser and the Digital Receipt is passed to your application. A successful transaction would appear as follows: or, if declined, the following page would appear: The merchants application receipt page. MiGS PC Integration Guide November

53 The application receives the Digital Receipt and displays a receipt page. The application receipt page is created by you and displayed on your website. Steps to a 3-Party Payments Integration To process a payment your application needs to be integrated with the Payment Client in order to create and send the Digital Order and decrypt the encrypted Digital Receipt. Handle a Digital Order 1 Add any variables required by the application to re-create the session before the Digital Order has been processed. 2 Collect the minimum required information for a Digital Order. This includes your MerchTxnRef, Merchant Id, an Order Information field, the Transaction Amount, the Locale and the Return URL where the Payment Server needs to redirect the cardholder back to. You may require additional information fields when using optional features. 3 Create an encrypted Digital Order using the fields outlined above. 4 Redirect the cardholder's Internet browser using the Digital Order you just created. At this point the cardholder session with your application is interrupted while the cardholder is redirected to the Payment Server. An example of a Digital Order is: akp.ymsmt*.p9edwoobmog74evjyicwvxo5yjluigphtjt0f0urc7seuczm.wmgdingzuvtcb4rczu*.jiz du2o2p1ieertcinpzvuyyaydf6yctvg.dkioxi*qtyhwxzuscm1vh168yy6nbqkjgyuevtauudvwibwws9r jopgpa MiGS PC Integration Guide November

54 What the Payment Server does When a Digital Order arrives at the Payment Server, it: Checks to make sure the Digital Order Digital Signature is correct and if correct and Displays the card selection page for the cardholder to choose their card type. Displays the card details so the cardholder can provide the card details for the selected card type. Processes the data and notifies the acquiring bank of the status of the transaction so the funds can be settled into the merchant's account. Sends back an encrypted Digital Receipt to your website page nominated by the ReturnURL in the Digital Order indicating whether the transaction was successful or declined. The Payment Server can also send error messages back, if for example there is a communication error in the banking network and the transaction cannot proceed. If the Digital Order Digital Signature is incorrect, the Payment Server: Displays an error to the cardholder. Handle a Digital Receipt The Digital Receipt is returned to your website using an Internet browser redirect as specified in the ReturnURL field. An example of a transaction response is: t0f0urc7seuczm.wmgdingzuvtcb4rczu*fuv866ujbxvlqzr1msjeeonxlvwtsvuxxy374vnwg Cv6Q7g*ZGTjN9kJhKsFJ0ZDsHDj6IQnVt7O.YiXl0Yz*OUzfBeP.jIzdu2O2P1iEErTCinpZVuY yaydf6yctvg.dkioxi*qtyhwxzus The online store needs to process the Digital Receipt by: Decrypting the encrypted Digital Receipt Check the value of the QSIResponseCode. If this is equal to '0' then the transaction was completed successfully and you can display a receipt to the cardholder. If this is equal to '1', '2', '3', '4', or '5' the transaction has been declined and this needs to be conveyed back to the cardholder. Other values may indicate an error has occurred and further details can be gathered by performing a DigitalReceipt.ERROR command so a decision can be made as to the next step. MiGS PC Integration Guide November

55 The online store has to handle: Successful transactions Declined transactions Error Conditions All of these conditions are responses that can occur back from the Payment Client product. Handle Session Variables A session begins when a cardholder enters your website and ends when they leave your website. Some merchant applications use session variables to keep track of where the merchant application is up to and to prevent unauthorised entry without the cardholder signing in. This stops hackers from spoofing transactions. Other applications create session variables in other ways. Some applications do not create session variables at all. If there are no session variable(s) in your application then the next section will not apply. Sending Session Variables to the Payment Server In a 3-Party transaction, the cardholder browser's connection is completely severed from the merchant application when the cardholder's browser is redirected to the Payment Server. if session variables are required to identify the users in the merchant's application, they must be collected and sent to the Payment Server as part of the transaction. These session variables are not used by the Payment Server, but are returned appended to the encrypted Digital Receipt. There can be as many session variables as required using any name the merchant application needs, providing they do not conflict with any of the Dialect field names and they conform to HTTP/HTTPS protocols. You need to URL encode all session variables before sending them. However it should be noted that any URL can only be a maximum of 2047 characters long otherwise a browser will not perform a redirect operation. It the maximum limit of the URL is breached then browser redirection will fail, resulting in the Digital Order or Digital Receipt being unable to reach it's intended recipient. When the session variables are returned appended to the Digital Receipt data, the merchant application can firstly retrieve these session variables and re-create the previous user session, just as though it had never been broken. Session variables should be appended to the merchant ReturnURL, where they are encrypted by the Payment Client and sent as part of the Digital Order: ReturnURL= able1=1234&sessionvariable2=abcd&sessionvariable3=5e6g MiGS PC Integration Guide November

56 When encrypted the Digital Order becomes: TbH3akP.yMsmT*.p9edWoobMog74eVJYiCWVxo5yjluIgPHtjt0F0URC7SeucZM.WMGdiNgzUvT CB4RCZu*.jIzdu2O2P1iEErTCinpZVuYyaydF6yCTVG.DkIOXi*qtYHWXzUsCm1Vh168yY6NBQk jgyuevtauudvwibwws9rjopgpa94xoe*rawo.stre8bttpch0w0riupp2mekwqfyawwluag7y9. w95y07fgffqqvrlyalmaz.tfev.8*5i47yoni*fyophzyzrgzefdqz18 The ReturnURL is encrypted into the Digital Order, which is sent to the Payment Server using a cardholder's browser redirect. At the Payment Server, the merchant session variables are recovered and temporarily stored in the Payment Server with the other transaction variables. They are sent back to the Payment Client appended to the Digital Receipt at the completion of the transaction. When encrypted the Digital Receipt is returned via a cardholder's browser redirect, it looks something like: IgPHtjt0F0URC7SeucZM.WMGdiNgzUvTCB4RCZu*Fuv866UJbXVlqZr1MSJeeOnXlVWTsVUXxy374VNWGCv 6Q7g*ZGTjN9kJhKsFJ0ZDsHDj6IQnVt7O.YiXl0Yz*OUzfBeP.jIzdu2O2P1iEErTCinpZVuYyaydF6yCTV G.DkIOXi*qtYHWXzUsCm1Vh168yY6NBQkjgYuEvTaUUDvWiBWwS9rjopgPA94xoE*RawO.stRe8RA.KIDmi 6sVn5H1DGX.t2d8.BwJABcdSFP5gVFok8wUm0W0RiupP2MekWqfyAWwluag7Y9&SessionVariable1=1 234&SessionVariable2=ABCD&SessionVariable3=5E6G This helps the merchant application recover the session variables from the encrypted Digital Receipt, and use them to restore the merchant session. After the session is restored, the encrypted Digital Receipt is decrypted and all the transaction receipt details can be obtained from the Payment Client. Basic 3-Party Transaction 3-Party transactions follow a modified process from the one shown in Transactions that return a single result on page 26. However, the transaction flow for a 3-Party transaction consists of two separate unconnected operations, the creation of the Digital Order and the decryption of the Digital Receipt. A 3-Party transaction sends a message to the Payment Server by redirecting the cardholder's browser using a URL that contains an encrypted and digitally signed Digital Order. When the order has been processed and the result of the transaction is known, the Payment Server creates an encrypted Digital Receipt, and the cardholder's browser is redirected to the merchant's web site with the Digital Receipt as a URL variable in the browser. The two separate transaction flows for a 3-Party transaction are: Creating and sending the Digital Order. Receiving and processing the Digital Receipt. MiGS PC Integration Guide November

57 Input Data for 3-Party DO Transactions The basic inputs necessary for a 3-Party transaction are sent together in the one primary Payment Client command getdigitalorder. Supplementary Command: adddigitalorderfield The supplementary command is in the format of a command with 2 variables. The first string value represents a key, followed by the data value for that key. One instance of this command is adding the following information prior to performing the getdigitalorder() command. Merchant Transaction Reference MerchTxnRef This field is optional and the merchant can use this field to uniquely identify the transaction for retrieving a duplicate copy of the receipt using the QueryDR function. This is the only function for MerchTxnRef and will not be displayed or used in any way in the Merchant Administration web portal on the Payment Server. This identifier is the primary key to the data in the Payment Server database and can use text made up of any of the base US ASCII characters in the range, hexadecimal 20 to 126, excluding hexadecimal 124. If the MerchTxnRef value is not submitted, the Payment Server copies the OrderInfo field into the MerchTxnRef field so QueryDR can still be used, provided OrderInfo is made unique. Note: If you are going to use the QueryDR function it is important to make sure the MerchTxnRef value is stored so that you can retrieve it if required. For detailed information on supplementary commands for your locale, please refer to the Payment Client Reference Manual. In Java and COM it can be added using the supplementary command: adddigitalorderfield( MerchTxnRef, merchtxnrefvalue) In Sockets it can be added by: 7, MerchTxnRef, + merchtxnrefvalue + \n Primary Command: getdigitalorder The basic inputs necessary for creating a 3-Party Digital Order are sent together in the one primary Payment Client command - getdigitalorder(). They are: Order Information Number OrderInfo This is a merchant reference field for this transaction. It is this field (and not the MerchTxnRef field) that will be displayed for transactions displayed for search results in the Merchant Administration web portal on the Payment Server. MiGS PC Integration Guide November

58 Merchant Identification Number (MerchantId) The merchant ID is an alphanumeric identifier that is given to the merchant during the Payment Provider's registration process, which is used to identify the merchant on the Payment Server. The merchant also uses the merchant ID to log in to Merchant Administration. There is a unique MerchantId for each merchant account/profile on the Payment Server. Purchase Amount (PurchaseAmountInteger) The purchase amount of the transaction expressed as an integer in the lowest currency denominator, for example, Pence, Cents, Euro, Yen. It does not contain any decimal points, thousands separators or currency symbols, for example. $12.50 is expressed as Different currencies are represented by different MerchantIDs. Locale (Locale) Identifies the language that is used on the Payment Server pages that are displayed to the cardholder. For English, a value of "en" is used. Please contact your Payment provider to determine the languages supported on the Payment Server. Return URL (ReturnURL) This is the merchant page to which the Payment Server redirects the cardholder's browser at the end of the transaction. It should be a fully qualified URL starting with or which if entered into any browser with Internet access, would cause it to go to that URL. In Java and COM it takes the form: getdigitalorder(orderinfo, merchantid, amount, locale, returnurl) In Sockets it takes the form: "2,"+ orderinfo +","+ merchantid +","+ amount +","+ locale +","+ returnurl + "\n" MiGS PC Integration Guide November

59 Creating and Sending the Digital Order 1. Connect to the Payment Client, depending on the implementation being used, Java/COM or Sockets. 2. An echo test is performed to check that communication has been established correctly with the Payment Client. 3. Any supplementary data for the functionality being used is now sent to the Payment Client. For a base 3-Party transaction, this only includes the Merchant Transaction Reference Number. Please refer to the functionality being used to determine any other data requirements. 4. The primary command getdigitalorder is sent to the Payment Client, which then creates the Digital Order and returns it to the merchant application as the result of the getdigitalorder command. 5. Disconnect from the Payment Client. 6. The URL data string returned by the getdigitalorder command is a pre-formatted Payment Server URL that redirects the cardholder's browser and dictates which page in the Payment Server the cardholder's browser connects to. It contains an encrypted Digital Order that can only be decoded by the Payment Server. For an example of a Digital Order, see Handle a Digital Order. 7. If the getresultfield command encounters an error from the Payment Client. The getresultfield command is used to retrieve the error description (retrieved using the field name PaymentClient.Error ). Error handling is detailed in the following pages. 8. This step is used to perform all appropriate error handling. 9. Close off the connection with the Payment Client in an error condition. 10. This step is used to perform all appropriate error handling if not connection is made to the Payment Client. Errors with Digital Orders If a Digital Order is not created successfully, errors and the reasons for those errors can be detected at each of the following steps and actions taken. 1 Connect to the Payment Client. If this step fails then you are unable to connect to the Payment Client. MiGS PC Integration Guide November

60 Errors that can cause a connection failure are: The Payment Client is not installed correctly. In a Sockets implementation, the merchant application is unable to establish a socket connection to the Payment Client host machine and port. Verify that the PCService is running on the host and the port specified in your merchant application. Also check the networking hardware and configuration to determine if this is a hardware failure. The Payment Client classes directory and/or the PaymentClient.jar file is not correctly entered into the JVM classpath for a Java implementation and therefore the Payment Client object cannot be instantiated. A semantic error may exist when trying to invoke the Payment Client, and it cannot be found to be invoked. You may not have rebooted after installation for the COM interface. Please refer to the Payment Client Deployment Guide for installation procedures and trouble-shooting. 2 Performing the echo test If the echo test fails, the Payment Client is not able to communicate or execute commands correctly. The errors likely to cause this are the same as those listed in Step 1. 3 Executing the primary command A failure is indicated by a Boolean return value of false in a Java or COM implementation, or 0,0 for Sockets. If the primary command encounters an error, it is caused by either incorrect input details being supplied to the primary command, incorrect configuration of the Payment Client (incorrect keys are installed), or the Payment Client cannot communicate with the Payment Server (usually a network configuration/firewall problem). Please refer to the Payment Client Deployment Guide for detail on installation procedures. To discover the error in Java or COM the command getresultfield( PaymentClient.Error ) is used. In Sockets the command 4, PaymentClient.Error\n is used. These commands return the error code and description of the error. For full details on the error codes, please refer to the Payment Client Reference Guide. MiGS PC Integration Guide November

61 Retrieving and processing the Digital Receipt 1. Assuming you have restored the user session, extract the Digital Receipt from the incoming URL. Check if the Digital Receipt consists of a String that is greater than 0 characters in length. 2. Connect to the Payment Client, depending on the implementation being used, Java/COM or Sockets. 3. An echo test is performed to check that communication has been established correctly with the Payment Client. 4. The primary command decryptdigitalreceipt is sent to the Payment Client, which then decrypts the Digital Receipt. 5. The nextresult command is used to check if the transaction contains valid results. If there were errors go to step The data is extracted from the result set using the getresultfield command to enable the merchant to process the transaction. It is customary to first determine if any processing errors occurred by QSIResponseCode ='7' or '8'. If there were no errors returned, continue retrieving the results. 7. Disconnect from the Payment Client. 8. This step is only used after the primary command and the nextresult to retrieve an error message from the Payment Client to explain the failure of the nextresult. 9. This step is only used to retrieve a processing error message from the Payment Client to explain if the QSIResponseCode = '7'. 10. This step is used to perform appropriate error handling if a Payment Client connection has been made. 11. This step is used to perform appropriate error handling if no Payment Client connection is made. MiGS PC Integration Guide November

62 Errors with a Digital Receipt If a Digital Order is not created successfully, errors can be detected at various stages to indicate the reason for the error. At each of the following steps, actions may be taken to determine the appropriate error conditions. Extract the Digital Receipt from the incoming URL. If this step fails or the Digital Receipt is empty (the length of the Digital Receipt is zero), all you can do is terminate the transaction. All other session variables may not be in the URL so all you can do is display an error page to the cardholder. Common errors that can cause a connection failure are: The cardholder has modified the URL in their browser's address bar and removed the Digital Receipt. The web server used by the merchant may have removed the URL encoded Digital Receipt variable. The Digital Receipt has been subject to fraud and has been tampered with. You may not have rebooted after installation for the COM interface. Cannot connect to the Payment Client. Errors that can cause a Payment Client connection failure are: The Payment Client is not installed correctly. In a Sockets implementation, the merchant application is unable to establish a socket connection to the Payment Client host machine and port. Verify that the PCService is running on the host and the port specified in your merchant application. Also check the networking hardware and configuration to determine if this is a hardware failure. The Payment Client classes directory and/or the PaymentClient.jar file is not correctly entered into the JVM classpath for a Java implementation and therefore the Payment Client object cannot be instantiated. A semantic error may exist when trying to invoke the Payment Client, therefore it cannot be found to be invoked. Although the merchant cannot rectify these problems, they should perform a QueryDR command to resolve any outstanding transactions. This allows you to find the transaction and deal with it appropriately. Please refer to the Payment Client Installation Guide for detail on installation procedures. MiGS PC Integration Guide November

63 Performing the echo test If this step has been reached but the echo test fails, the Payment Client is not able to communicate or execute commands correctly. The errors likely to cause this are the same as those listed in Step 2. Executing the primary command A failure is indicated by a Boolean return value of false in a Java or COM implementation, or 0,0 for Sockets. If the primary command encounters an error, it is caused by either incorrect input details being supplied to the primary command, incorrect configuration of the Payment Client (incorrect keys are installed), or the Payment Client cannot communicate with the Payment Server (usually a network configuration/firewall problem). Please refer to the Payment Client Installation Guide for detail on installation procedure. Executing the nextresult command A failure is indicated by a Boolean return value of false in a Java or COM implementation, or 0,0 for Sockets. When an error occurs, it means the Payment Server has detected an error in processing the Digital Order. To discover the error in Java or COM the command getresultfield( PaymentClient.Error ) is used. In Sockets the command 4, PaymentClient.Error\n is used. Checking if the QSIResponseCode = 7 or 8 If the Payment Server has detected an error processing the transaction, it will return a QSIResponseCode equal to 7 or 8. To determine the error the command getresultfield("digitalreceipt.error") is used. In Sockets the command 4,DigitalReceipt.ERROR\n is used. This command returns a description of the error that can be found in the Payment Client Reference Guide, Appendix B. Output Data for 3-Party DR Transactions The 3-Party transaction returns an encrypted Digital Receipt via a cardholder's browser redirect and contains the following fields which are decrpyted by the Payment Client. MiGS PC Integration Guide November

64 Merchant Transaction Reference (MerchTxnRef) 1. The input value passed back in the receipt. It is the reference number allocated by the merchant's software. This code should be unique for every transaction. Order Information Number (OrderInfo) 2. The merchant's information about this transaction. Can be a simple order number or shopping basket number. Merchant Identification Number (MerchantId) 3. The input value passed back in the receipt. It is an alphanumeric identifier that is given to the merchant during the Payment Provider's registration process, which is used to identify the merchant on the Payment Server. The merchant uses the merchant ID to log in to Merchant Administration. There is a unique MerchantId for each merchant account/profile on the Payment Server. Purchase Amount (PurchaseAmountInteger) 4. The input value passed back in the receipt. It is the purchase amount of the transaction expressed as an integer in the lowest currency denominator, for example, pence, cents, Euro, yen, etc. It does not contain any decimal points, thousands separators or currency symbols, for example. $12.50 is expressed as QSI Response Code (QSIResponseCode) 5. A single character response code that is generated by the Payment Server. A QSIResponseCode of 0 (zero) indicates that the transaction was processed successfully and approved by the acquiring institution. Any other value indicates a transaction failure. Please refer to the Payment Client Reference Manual for a complete list of valid values and their descriptions. Acquirer's Response Code (AcqResponseCode) Payment Server Transaction Number (TransactionNo) 6. The response code that is generated by the financial institution. This can vary between institutions. It is included for faultfinding purposes. 7. A unique number generated by the Payment Server and is the OrderID (Shopping Transaction number) for a transaction. It is important to make sure the TransactionNo is stored for later retrieval if required to perform queries or Advanced Merchant Administration commands, e.g. captures, voids, refunds. Transaction Receipt Number (ReceiptNo) 8. The RRN is a unique number generated by the payment processor. This is the value that is passed back to the cardholder for their records if the merchant's application does not provide its own receipt number. Authorisation Identification Code (AuthorizeId) Transaction Batch Number (BatchNo) Card Type (CardType) Card Num (CardNum) 9. A code issued by the acquiring payment processor to approve or deny a transaction. 10. The Batch number on the Payment Server that this transaction will be added to in order to be processed by the acquiring institution. 11. The Card Type is a code that details what type of card was used to carry out this transaction. The codes are detailed in the Payment Client Reference Guide. 12. The card number in 0.4 card masking format. 13. This field is only returned if System-Captured Masked Card in Digital Receipt privilege is enabled for the merchant processing the transaction. See Merchant Manager User Guide. MiGS PC Integration Guide November

65 When a transaction is not processed successfully, errors can be detected at various stages to indicate the reason for the error. The process described in Determining Errors in a Transaction that Return a Single Result on page 27 section of this chapter is used. Tutorial A payment in a 3-Party transaction consists of two main parts: Create and send the Digital Order Retrieve and extract the Digital Receipt details. This tutorial focuses on conducting a 3-Party transaction using the Java Payment Client API calls. Please refer to the Payment Client Reference Guide for more details on commands. However the steps used in this tutorial can be applied to any language, as it is the process used that is important. To create and send the Digital Order in a 3-Party transaction there are five main steps to follow. 1 Instantiate and test the Payment Client. 2 Perform echo test with the Payment Client. 3 Add all the extra Digital Order details that are not included in the getdigitalorder API command. 4 Create the Digital Order using the getdigitalorder API command. Re-direct the cardholder's browser to the Payment Server with the Digital Order. To retrieve and extract the Digital Receipt details in a 3-Party transaction there are six steps to follow. 1 Retrieve the encrypted Digital Receipt. 2 Instantiate and test the Payment Client. 3 Perform echo test with the Payment Client 4 Decrypt the Digital Receipt to be processed using the decryptdigitalreceipt API command. 5 Check there is a valid result. 6 Retrieve the Digital Receipt details. To reduce the duplication in the tutorial, the common steps - instantiate and test the Payment Client, perform echo test with the Payment Client are described in the section describing how to create and send the Digital Order. MiGS PC Integration Guide November

66 Instantiate and test the Payment Client Instantiate the Payment Client To instantiate the Payment Client, an example of the Java API call to create the Payment Client is: // Instantiate a Payment Client PaymentClientImpl objpayclient = new PaymentClientImpl(); The variable objpayclient is a local variable to the Payment Client and may be changed to any name that suits the implementation. To test if the object has been successfully created in Java, use a try/catch statement to catch any errors in the creation of the object. In other languages such as Visual Basic, you may use statements like the On Error statement to determine if the Object hasn't been created successfully. When using the COM interface there are two ways that the Payment Client object can instantiated. ' Instantiate a Payment Client set objpayclient = Server.CreateObject( PaymentClient.com.COMClient ) The VBScript above will instantiate the COM Object using the default JNI interface that is configured for the COM Object during installation. Optionally configure the COM object to connect to Payment Client via TCP/IP Sockets. ' Instantiate a Payment Client set objpayclient = Server.CreateObject( PaymentClient.Sockets ) ' Optionally configure the TCP/IP Socket settings. ' Host address of the Payment Client PCService objpayclient.hostaddress = ' Port that the Payment Client PCService is listening on objpayclient.portnumber = 9050 ' Socket timeout to use when communicating to the Payment Client PCService (in milliseconds) objpayclient.timeout = ' 100 seconds The VBScript above will instantiate the COM Object using the TCP/IP sockets interface. Using this method of instantiating the COM Object the user can configure the sockets settings such as the host, port and timeout to use to connect to the Payment Client PCService programmatically at runtime. If these settings are not explicitly set in the program then the COM Object will use the default settings configured during installation. The host, port and timeout cannot be set when the PaymentClient.com.COMClient ProgID is used, even if TCP/IP sockets is the default interface for the COM Object. MiGS PC Integration Guide November

67 Test the Payment Client To test the Payment Client an echo command is used which returns the string value sent appended to the string echo:. This test ensures that the Payment Client object has been instantiated correctly and that a communications path has been established and is working properly between the Payment Client and the merchant application. An example of the Java call to perform the echo test and check for a valid response is: // Test the Payment Client object created correctly String result = objpayclient.echo("test"); if (!result.equals("echo:test")) { // perform error handling for this command return; } The contents of the 'if' statement should perform the actions appropriate to your implementation. It may be very simple, such as displaying an error and terminating the process. For a production implementation a more sophisticated response may be warranted. Add all the Extra Digital Order fields (for advanced functionality) Extra Digital Order fields must be added before the API call to create the Digital Order is made. This is because the API call, getdigitalorder() collects all the data that the Payment Client has been sent, and creates the complete encrypted Digital Order. If extra fields are not sent before this call then they will not be included in the Digital Order when it is created. For a standard 3-Party transaction there is no extra data that must be included to create a valid Digital Order, however when implementing advanced functionality you may be required to add extra data here. For example, for card present or corporate purchase card transactions, you may need to add extra fields. An example of adding the extra fields is: // add Merchant Transaction Reference value objpayclient.adddigitalorderfield("merchtxnref", merchtxnrefvalue); Create and Send the DO In the creation of the Digital Order, the Payment Client collects all the data that it has been sent and encrypts it to create the Digital Order. The API call must contain the following five variables in the correct order. An example of the API command to create the Digital Order is: // This shows how to add SessionIDs to the returnurl // This is so a session can be recereated on the merchant application // It is good practice to URL encode these variables // so they can be transmitted without error via HTTP protocol returnurl = returnurl + URLEncoder.encode( &SessionID1=" + session1 + "&SessionID2=" + session2); // create the Digital Order String digitalorder = objpayclient.getdigitalorder(orderinfo, merchantid, purchaseamountinteger, locale, returnurl) // check that a valid Digital Order was created if (digitalorder == null digitalorder.length( ) == 0) { // perform error handling for this command } MiGS PC Integration Guide November

68 To test if the command getdigitalorder has in fact been run successfully in Java you would use a try/catch statement to catch any errors in the creation of the object. In other languages such as Visual Basic you may use statements like the On Error statement to determine if the Object has not been created successfully. The content of the 'if' statement should perform the actions appropriate to your implementation. It may be very simple, such as displaying an error and terminating the process. For a production implementation a more sophisticated response may be warranted. Send the Digital Order to the Payment Server The last step of the process is to send the encrypted Digital Order to the Payment Server, which is done via a cardholder's browser redirect. This allows the cardholder's browser to work directly with the acquiring institution's Payment Server, so the cardholder can provide their card details directly to them. // Transmit the DO to the Payment Server via a browser redirect // In Java the code is: res.sendredirect(digitalorder); The following code blocks are not complete and would not compile. Java extras like retrieving input variables and try/catch blocks have been omitted for the sake of readability, but the principles of how the code block works is correct. Java Servlet Extract Showing how the DO is created Putting all these code extracts together the application becomes: // Step 1 - Connect to the Payment Client // ************************************** // create a Payment Client object objpayclient = new PaymentClientImpl(); // Step 2 - Test the Payment Client object was created successfully // **************************************************************** // Test the communication to the Payment Client using an "echo" result = objpayclient.echo("test"); if (!result.equals("echo:test")) { // Display error as communication to the Payment Client failed // perform error handling for this command return; } // Step 3 - Prepare to Generate and Send Digital Order // *************************************************** // The extra details are not accepted by the // getdigitalorder() method and so we must add them // explicitly here for inclusion in the DO creation. // Adding the supplementary data to the DO is done using the // "adddigitalorderfield" command // add MerchTxnRef number objpayclient.adddigitalorderfield("merchtxnref", merchtxnref); // Step 4 - Generate and Send Digital Order // **************************************** // Create and send the Digital Order digitalorder = objpayclient.getdigitalorder(orderinfo, merchantid, amount, locale, returnurl); MiGS PC Integration Guide November

69 if (digitalorder!= null && digitalorder.length() == 0) { // Retrieve the Payment Client Error (There may be none to get) result = objpayclient.getresultfield("paymentclient.error"); if (result!= null && result.length()!= 0) { exception = result; } // Display an Error Page as the Digital Order was not processed // perform error handling for this command return; } // Transmit the DO to the Payment Server via a browser redirect res.sendredirect(digitalorder); // At this point the cardholder's browser is sent to the Payment Server // using the URL at the start of the Encrypted Digital Order Java Servlet for DO using Sockets Commands The following Java Sockets implementation code block is not complete and would not compile. Java extras like importing the Java libraries, retrieving input variables from the order form and try/catch blocks have been omitted for readability, but the principles of how the code works is correct if these extras were added it would be fully functional. The related commands for the Sockets interface are shown in The Payment Client Reference Manual. The steps for sockets are exactly the same as the Java code above, only the implementation method changes. // Step 1 - Connect to the Payment Client // ************************************** // Create a socket object to the Payment Client Socket sock = new Socket(payClientIP, payclientport); // The Buffered Reader data input stream from the socket BufferedReader in = new BufferedReader( new InputStreamReader(sock.getInputStream())); // The output stream to the socket PrintStream out = new PrintStream(sock.getOutputStream()); // Step 2 - Test the Payment Client object was created successfully // **************************************************************** // Test the communication to the Payment Client using an "echo" out.print("1,test\n"); cmdresponse = in.readline(); if (!cmdresponse.equals("1,echo:test")) { // perform error handling for this command sock.close(); return; } // Step 3 - Prepare to Generate and Send Digital Order // *************************************************** // The extra details are not accepted by the // getdigitalorder() method and so we must add them // explicitly here for inclusion in the DO creation. // Adding the supplementary data to the DO is done using the //"adddigitalorderfield" command // add merchant transaction reference data out.print("7,merchtxnref," + MerchTxnRefValue + "\n"); cmdresponse = in.readline(); if (!cmdresponse.equals( 1,1 )) { // perform error handling for this command sock.close(); return; } MiGS PC Integration Guide November

70 // Step 4 - Generate and Send Digital Order // **************************************** // Create and send the Digital Order // (This primary command also receives the Digital Receipt) out.print("2, + orderinfo +, + merchantid +, + purchaseamountinteger+, + locale +, + returnurl + \n ); cmdresponse = in.readline(); if (!cmdresponse.substring(0,1).equals( 1 )) { // Retrieve the Payment Client Error (There may be none to get) out.print("4,paymentclient.error\n"); cmdresponse = in.readline(); // check the first status char of the return message as the second field may have data if (cmdresponse.substring(0,1).equals( 1 )) { exception = cmdresponse.substring(2); } // perform error handling for this command sock.close(); return; } // Get the Digital Order digitalorder = cmdresponse.substring(2); // Step 7 - We are finished with the Payment Client so tidy up // *********************************************************** // Close the socket connection to the Payment Client sock.close(); // Transmit the DO to the Payment Server via a browser redirect res.sendredirect(digitalorder); // At this point the cardholder's browser is sent to the Payment Server // using the URL at the start of the Encrypted Digital Order This code has been written without methods/subroutines that would reduce the duplication of code. It demonstrates how the six steps come together in a form that is easily followed. Digital Receipt Retrieve the Digital Receipt The Digital Receipt is returned to the merchant via the cardholder's browser as a standard HTML query string parameter with the name DR. The Digital Receipt is retrieved in the same manner as standard HTML form variable. We then perform a simple check to ensure the parameter contains data. An example of the Java code is: // Extract the encrypted Digital Receipt from the request. // Note: The default redirection from the Payment Server contains a // parameter "DR" which was sent as part of the DO in the ReturnURL field. encrypteddr = req.getparameter("dr"); if (encrypteddr == null encrypteddr.length() == 0) { // perform error handling for a bad Digital Receipt and return } Instantiate the Payment Client To instantiate the Payment Client, the Java API call to create the Payment Client should look similar to: MiGS PC Integration Guide November

71 // Instantiate a Payment Client PaymentClientImpl objpayclient = new PaymentClientImpl(); When using the COM interface there are two ways that the Payment Client object can instantiated. ' Instantiate a Payment Client set objpayclient = Server.CreateObject( PaymentClient.com.COMClient ) The VBScript above will instantiate the COM Object using the default interface that is configured for the COM Object during installation. ' Instantiate a Payment Client set objpayclient = Server.CreateObject( PaymentClient.Sockets ) ' Optionally configure the TCP/IP Socket settings. ' Host address of the Payment Client PCService objpayclient.hostaddress = ' Port that the Payment Client PCService is listening on objpayclient.portnumber = 9050 ' Socket timeout to use when communicating to the Payment Client PCService (in milliseconds) objpayclient.timeout = ' 100 seconds The VBScript above will instantiate the COM Object using the TCP/IP sockets interface. Using this method of instantiating the COM Object the user can configure the sockets settings such as the host, port and timeout to use to connect to the Payment Client PCService programmatically at runtime. If these settings are not explicitly set in the program then the COM Object will use the default settings configured during installation. The host, port and timeout cannot be set when the PaymentClient.com.COMClient ProgID is used, even if TCP/IP sockets is the default interface for the COM Object. Test the Payment Client To test the Payment Client, use an echo command to return the string value you send appended to the string echo:. An example of the Java call to perform the echo test and check for a valid response is: // Test the Payment Client object created correctly String result = objpayclient.echo("test"); if (!result.equals("echo:test")) { // perform error handling for this command and return return; } Decrypt the Digital Receipt To decrypt the Digital Receipt, the primary command decryptdigitalreceipt is used. There is only one input parameter, the encrypted Digital Receipt. An example of the code is: // Decrypt the Digital Receipt objpayclient.decryptdigitalreceipt(encrypteddr); MiGS PC Integration Guide November

72 Check there is a valid result When the Digital Order has been processed you need to ensure that the Payment Client has received a valid Digital Receipt from the Payment Server and that there are results to process. To do this, use the nextresult API command. An example of checking that a valid Digital Receipt has been received is: // Get the nextresult value to check there are results to process. if (!objpayclient.nextresult()) { // retrieve the error description from the Payment Client String error = objpayclient.getresultfield("paymentclient.error"); // perform error handling for this command return; } The content of the 'if' statement should perform the actions appropriate to your implementation. It may be very simple, such as, an error is displayed and processing is terminated. There is an extra step in this 'if' statement to others that have been shown as we are now able to receive an error description from the Payment Client to explain why the transaction did not return a valid Digital Receipt. This error description may not always contain data, as it may be an empty string ( ). Retrieve the Digital Receipt details From the valid Digital Order, you need to retrieve the Digital Receipt details from the Payment Client. To do this, use the getresultfield() API command. An example of retrieving each result is: // Extract the available Digital Receipt fields // Get the QSIResponseCode for the transaction // Get the results for each of the receipt variable required. String qsicode = objpayclient.getresultfield("digitalreceipt.qsiresponsecode"); // Check if the result contains an error message if (!qsiresponsecode.equals("null") &&!qsiresponsecode.equals("0")) { // check if an error returned from the Payment Client result = objpayclient.getresultfield("digitalreceipt.error"); if (result!= null && result.length()!= 0) { // The response is an error message so display an Error Page exception = result; // perform error handling to find out why transaction failed } else { // Extract the available Digital Receipt fields // The example retrieves the MerchantId and Transaction Amount values, // which should be the same as the values sent. In a production // system the sent values and the receive values could be checked to // make sure they are the same. String merchantid = objpayclient.getresultfield("digitalreceipt.merchantid"); String orderinfo = objpayclient.getresultfield("digitalreceipt.orderinfo"); String merchantrefno = objpayclient.getresultfield("digitalreceipt.merchtxnref"); String txnamount = objpayclient.getresultfield("digitalreceipt.purchaseamountinteger"); String receiptno = objpayclient.getresultfield("digitalreceipt.receiptno"); String transno = objpayclient.getresultfield("digitalreceipt.transactionno"); String acqcode = objpayclient.getresultfield("digitalreceipt.acqresponsecode"); String authoriseid = objpayclient.getresultfield("digitalreceipt.authorizeid"); String batchnumber = objpayclient.getresultfield("digitalreceipt.batchno"); } } MiGS PC Integration Guide November

73 Normally, these receipt variables would not be declared at this point of the merchant application, but would have been defined earlier. You now need to return these values to the application that called the payment process. To check if the payment request was successful the QSIResponseCode is checked. Any value other than 0 (zero) is a declined/failed transaction, see list of QSIResponseCodes is shown and described in the Payment Client Reference Manual. The following code blocks are not complete and would not compile. Java extras like retrieving input variables and try/catch blocks have been omitted to make it easier to read, but the principles of how the code block works is correct. Java Servlet Extract Showing how the DR is decrypted Putting the code extracts together, the application becomes: // Step 1 - retrieve the encrypted DR // ********************************** // Extract the encrypted Digital Receipt from the request. Note that // the default redirection from the Payment Server contains a // parameter "DR" which was sent as part of the DO in the ReturnURL field. if ((encrypteddr = req.getparameter("dr")) == null) { // perform error handling for this command return; } // Step 2 - Connect to the Payment Client // ************************************** // create a Payment Client object objpayclient = new PaymentClientImpl(); // Step 3 - Test the Payment Client object was created successfully // **************************************************************** // Test the communication to the Payment Client using an "echo" result = objpayclient.echo("test"); if (!result.equals("echo:test")) { // perform error handling for this command return; } // Step 4 - Decrypt Digital Receipt // ******************************** if (!objpayclient.decryptdigitalreceipt(encrypteddr)) { // Retrieve the Payment Client Error (There may be none to get) result = objpayclient.getresultfield("paymentclient.error"); if (result!= null && result.length()!= 0) { exception = result; } // perform error handling for this command return; } // Step 5 - Check the DR to see if there is a valid result // ******************************************************* // Use the "nextresult" command to check if the DR contains a result if (!objpayclient.nextresult()) { // Retrieve the Payment Client Error (There may be none to get) result = objpayclient.getresultfield("paymentclient.error"); if (result!= null && result.length()!= 0) { exception = result; } MiGS PC Integration Guide November

74 } // Display an error as the DR doesn't contain a result // perform error handling for this command return; // Step 6 - Get the result data from the Digital Receipt // ***************************************************** // Extract the available Digital Receipt fields // Get the QSIResponseCode for the transaction // Get the results for each of the receipt variable required. String qsicode = objpayclient.getresultfield("digitalreceipt.qsiresponsecode"); // Check if the result contains an error message if (!qsiresponsecode.equals("null") &&!qsiresponsecode.equals("0")) { // check if an error returned from the Payment Client result = objpayclient.getresultfield("digitalreceipt.error"); if (result!= null && result.length()!= 0) { // The response is an error message so display an Error Page exception = result; // perform error handling to find out why transaction failed } else { // Extract the available Digital Receipt fields // The example retrieves the MerchantId and Transaction Amount values, // which should be the same as the values sent. In a production // system the sent values and the receive values could be checked to // make sure they are the same. String merchantid = objpayclient.getresultfield("digitalreceipt.merchantid"); String orderinfo = objpayclient.getresultfield("digitalreceipt.orderinfo"); String merchantrefno = objpayclient.getresultfield("digitalreceipt.merchtxnref"); String txnamount = objpayclient.getresultfield("digitalreceipt.purchaseamountinteger"); String receiptno = objpayclient.getresultfield("digitalreceipt.receiptno"); String transno = objpayclient.getresultfield("digitalreceipt.transactionno"); String acqcode = objpayclient.getresultfield("digitalreceipt.acqresponsecode"); String authoriseid = objpayclient.getresultfield("digitalreceipt.authorizeid"); String batchnumber = objpayclient.getresultfield("digitalreceipt.batchno"); } } // Step 7 - We are finished with the Payment Client so tidy up // *********************************************************** // nothing to be done in Java Java Servlet for DR using TCP/IP Sockets Commands The following Java Sockets implementation code block is not complete and would not compile. Java extras like importing the Java libraries, retrieving input variables from the order form and try/catch blocks have been omitted for readability, but the principles of how the code works is correct if these extras were added it would be fully functional. The related commands for the Sockets interface are shown in The Payment Client Reference Manual. The steps for sockets are exactly the same as the Java code above, only the implementation method changes. // Step 1 - retrieve the encrypted DR // ********************************** // Extract the encrypted Digital Receipt from the request. Note that // the default redirection from the Payment Server contains a // parameter "DR" which was sent as part of the DO in the ReturnURL field. if ((encrypteddr = req.getparameter("dr")) == null) { // perform error handling for this command return; } MiGS PC Integration Guide November

75 // get Payment Client IP Address and Port number that was sent appended to the returnurl String pcmachineip = req.getparameter("pcmachineip"); String pcport = req.getparameter("pcport"); // convert to integer - required for creating socket command int payclientport = Integer.parseInt(pcPort); // Step 2 - Connect to the Payment Client // ************************************** // Create a socket object to the Payment Client Socket sock = new Socket(payClientIP, payclientport); // The Buffered Reader data input stream from the socket BufferedReader in = new BufferedReader( new InputStreamReader(sock.getInputStream())); // The output stream to the socket PrintStream out = new PrintStream(sock.getOutputStream()); // Step 3 - Test the Payment Client object was created successfully // **************************************************************** // Test the communication to the Payment Client using an "echo" out.print("1,test\n"); cmdresponse = in.readline(); if (!cmdresponse.equals("1,echo:test")) { // perform error handling for this command sock.close(); return; } // Step 4 - Decrypt Digital Receipt // ******************************** out.print( 3, + encrypteddr + \n ); cmdresponse = in.readline(); if (!cmdresponse.equals( 1,1 )) { // Retrieve the Payment Client Error (There may be none to get) out.print("4,paymentclient.error\n"); cmdresponse = in.readline(); // check the first status char of the return message as the second field may have data if (cmdresponse.substring(0,1).equals( 1 )) { exception = cmdresponse.substring(2); } // perform error handling for this command sock.close(); return; } // Step 5 - Check the DR to see if there is a valid result // ******************************************************* // Use the "nextresult" command to check if the DR contains a result out.print( 5\n ); cmdresponse = in.readline(); if (!cmdresponse.equals( 1,1 )) { // retrieve the error description from the Payment Client out.print("4,paymentclient.error\n ); cmdresponse = in.readline(); // check the first status char of the return message as the second field may have data if (cmdresponse.substring(0,1).equals( 1 )) { exception = cmdresponse.substring(2); } // perform error handling for this command sock.close(); return; MiGS PC Integration Guide November

76 } String qsiresponsecode = ""; // Get the QSI Response Code for the transaction out.print( 4,DigitalReceipt.QSIResponseCode ); cmdresponse = in.readline(); if (!cmdresponse.substring(0,1).equals( 1 )) { // Display an Error Page as the QSIResponseCode could not be retrieved // perform error handling for this command sock.close(); return; } else { qsiresponsecode = cmdresponse.substring(2); } // Check if the result is an error message if (qsiresponsecode.equals("7")) { // Get the error returned from the Payment Client out.print( 4,DigitalReceipt.ERROR ); cmdresponse = in.readline(); } if (!cmdresponse.substring(0,1).equals( 1 )) { // The response is an error message so display an Error Page // perform error handling for this command sock.close(); return; } // Step 6 - Get the result data from the Digital Receipt // ***************************************************** // Also Extract the other available Digital Receipt fields // The example retrieves the MerchantId and Amount values, // which should be the same as the values sent. In a production // system the sent values and the receive values could be checked to // make sure they are the same. String qsiresponsecode = ""; // Get the QSI Response Code for the transaction out.print( 4,DigitalReceipt.QSIResponseCode ); cmdresponse = in.readline(); if (!cmdresponse.substring(0,1).equals( 1 )) { // Display an Error Page as the QSIResponseCode could not be retrieved // perform error handling for this command sock.close(); return; } else { qsiresponsecode = cmdresponse.substring(2); } // If non-zero result, check if the result is an error message if (!qsiresponsecode.equals("0")) { out.print( 4,DigitalReceipt.ERROR ); cmdresponse = in.readline(); // check the first status char of the return message // if OK there is value to get if (!cmdresponse.substring(0,1).equals( 1 )) { exception = cmdresponse.substring(2); // The response is an error message so display an Error Page // perform error handling for this command sock.close(); return; } } out.print( 4,DigitalReceipt.MerchTxnRef\n ); cmdresponse = in.readline(); MiGS PC Integration Guide November

77 merchtxnref = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.OrderInfo\n ); cmdresponse = in.readline(); orderinfo = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.MerchantId\n ); cmdresponse = in.readline(); merchantid = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.PurchaseAmountInteger\n ); cmdresponse = in.readline(); amount = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.TransactionNo\n ); cmdresponse = in.readline(); transactionno = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.ReceiptNo\n ); cmdresponse = in.readline(); receiptno = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.AcqResponseCode\n ); cmdresponse = in.readline(); acqresponsecode = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.AuthorizeId\n ); cmdresponse = in.readline(); authorizeid = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.BatchNo\n ); cmdresponse = in.readline(); batchno = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; out.print( 4,DigitalReceipt.CardType\n ); cmdresponse = in.readline(); cardtype = cmdresponse.substring(0,1).equals( 1 )? cmdresponse.substring(2) : "Unknown"; // Step 7 - We are finished with the Payment Client so tidy up // *********************************************************** sock.close(); This code has been written without methods/subroutines that would reduce the duplication of code. It demonstrates how the six steps come together in a form that is easily followed. MiGS PC Integration Guide November

78 Additional 3 Party Functionality The Payment Server provides you with additional ways to process payments, for example: 3-Party, where the merchant collects the cardholder's card type 3-Party, where the merchant collects all the cardholder's card details 3-Party, where the merchant is enabled for Verified by Visa MasterCard SecureCode and J/Secure. For more information, see Using 3-D Secure Payment Authentications on page 24). 3-Party Payments Where the Merchant Collects the Cardholder's Card Type In 3-Party Payments you can choose to bypass the Payment Server payments page that displays the logos of all the cards the Payment Provider will accept. This can be helpful if your application already allows the cardholder to select the card they want to pay with. This stops the cardholder having to do a double selection, once at your application and once on the Payment Server. You can achieve this by providing the following extra fields in the Digital Order - Gateway and Card Type. This type of 3-Party transaction is called External Payment Selection (EPS). 3-Party Payments Where the Merchant Collects All the Cardholder's Card Details In 3-Party Payments you can choose to bypass all the Payment Server payment pages displayed. This can be helpful if you want to keep merchant branding consistent throughout a 3-Party transaction. The same security measure must be observed, such as installing an SSL certificate to protect the card details being sent from the cardholder's browser to the merchant's site as in a 2-Party transaction. You can achieve this by providing the following card details in extra fields in the Digital Order. These fields are: Card Number, Card Expiry, Gateway and Card Type. You can also submit Card Security Code and any other optional data at this point. 3-Party Payments using Verified-by-Visa and/or MasterCard Secure Code In 3-Party Payments you can have your Payment Provider enable you to use Verified by Visa MasterCard SecureCode and J/Secure, which provides additional security to all your payments. This type of transaction requires the 3-Party model, and works by redirecting the cardholder to their card issuer to enter a password. For more information, please see Using Verified-by-Visa and MasterCard SecureCode Payment Authentications to secure your payments (see Using 3-D Secure Payment Authentications on page 24). MiGS PC Integration Guide November

79 You can also choose with this transaction type to bypass all the Payment Server payment pages displayed. This can be helpful if you want to keep merchant branding consistent throughout a 3-Party Verified by Visa or MasterCard SecureCode transaction, except for the one page where the cardholder types in their password. The same security measure must be observed, such as installing an SSL certificate to protect the card details being sent from the cardholder's browser to the merchant's site as in a 2-Party transaction. You can achieve this by providing the following card details in extra fields in the Digital Order. These fields are: Card Number, Card Expiry, Gateway and Card Type. You can also submit Card Security Code and any other optional data at this point. MiGS PC Integration Guide November

80 3-Party Payments - A Best Practice Flow Sample The best practice flow diagram shows how to create a payment-enabled merchant application. MiGS PC Integration Guide November

81 1 The shopping cart is stored in a database while the transaction is being processed, to keep a record of the data. During the transaction the connection to the cardholder is unlinked [recall the redirection] so the data needs to be stored. If the data is lost then the transaction cannot be processed. Two boolean flags, checked_out and waiting_for_dr, are stored on the server with the shopping cart record. 2 The flag, checked_out, checks whether the shopping cart already has a payment attempt in progress for that cardholder: a. FALSE - Payment Not Attempted b. TRUE - Payment Process Started. If the Payment Not Attempted continue to the next step, otherwise go to step Set the checked_out flag to TRUE to indicate the start of the payment process. 4 Create the Digital Order. 5 Set the Boolean flag waiting_for_dr to TRUE to indicate that the software is waiting for a Digital Receipt for this order. 6 Send the Digital Order to the Payment Server using a browser redirect. Note: The merchant application transfers the connection to the Payment Server which sends the Digital Receipt using the cardholder browser to the merchant web site by the ReturnURL specified in the Digital Order. Any additional session variables that are required to allow the Payment Server to return to the same session should be appended to the ReturnURL. These are encrypted as part of the Digital Order and returned as parameters appended to the encoded Digital Receipt. 7 Wait for the Digital Receipt to be returned via a browser redirect from the Payment Server. Pass the Digital Receipt to the Payment Client and retrieve and store the results. Set waiting_for_dr to FALSE for this order. 8 The Digital Receipt is returned to the merchant software via a browser redirect. 9 Check the waiting_for_dr flag. If FALSE the Digital Receipt has already been received. Therefore this is a retry delivery of a Digital Receipt, go to 27 and display the receipt details. If TRUE, continue. 10 Store the Digital Receipt values in the database. 11 Set the waiting_for_dr flag to FALSE to indicate the Digital Receipt has been received. 12 Check if the cancelled Flag set. If FALSE continue, otherwise go to step Check if the transaction was successful. This is indicated by a QSIResponseCode value of zero. If the QSIResponseCode is not zero then go to step 30, otherwise continue. 14 Process the order as Paid. 15 Display the receipt details to the cardholder. 16 Finish. MiGS PC Integration Guide November

82 Other Processes If the cardholder attempts second payment on one order or clicks Back button in the browser while transaction is being processed. If the checked_out flag is set. The cardholder arrives here if they attempt to enter the pay process twice for the same order. 17 If the waiting_for_dr flag is TRUE then go to step 20, otherwise continue. 18 Check if the transaction was successful. This is indicated by a QSIResponseCode value of '0' (zero). If QSIResponseCode is not '0' then go to step 24, otherwise continue. 19 Re-display the Shopping Receipt details. Finish process on Display a warning message about the risk of a duplicate transaction if the cardholder keeps proceeding. 21 The cardholder has already checked out a transaction but the merchant system has not received a Digital Receipt. Determine if the cardholder wants to keep proceeding. If the cardholder wishes to proceed then continue, otherwise go to step Set the cancelled flag for this transaction and restart a new transaction at operation 1 by storing the shopping cart in the database with a new MerchTxnRef number according to the instruction in operation Display merchant contact details and continue waiting for the Digital Receipt at If the number of retries for the payment are exceeded then continue, otherwise go to Display a message indicating that no further attempts will be permitted for this order. Finish process on If the retry limit is not exceeded then increment the retry counter and assign a new order number according to the instruction in operation 1, and go to step 4. Create new order from operation 4 onwards. Multiple Digital Receipts received for an order number? 27 Check if the transaction number is the same as the one previously received for this order. If the transaction number is the same - continue, otherwise go to step Cancel the duplicate successful transaction with the payment processor. The actual cancellation can be performed through any payment processor process, for example MA, AMA, or through a manual help desk process. This operation is where an automatic cancellation would occur or notification generated for a manual process to begin. Only cancel the transaction if there is more than one successful transaction for this order. MiGS PC Integration Guide November

83 29 Display the receipt details for the current transaction based on the original Digital Receipt. 30 Finish process on 16. Digital Receipt received for unsuccessful transaction? 31 Display the appropriate response for this transaction. 32 Check if the response is Insufficient Funds. If No - continue, otherwise give the cardholder the opportunity to use another card - go to step Check if the response is Invalid Card. If No - continue, otherwise give the cardholder the opportunity to use another card - go to step Check if the transaction was Declined by the Payment Processor. If Yes - Give the cardholder the opportunity to try again with a different card - go to step 2. If No - there are no other errors we can cater for so cancel transaction and Finish process on 16. MiGS PC Integration Guide November

84 7 Supplementary Transactions To implement the advanced features available on the Payment Server, you need to add additional data to the Digital Order. Additional fields are added using the adddigitalorderfield supplementary command according to the processes outlined in the transaction flow sections. Multiple supplementary features may be combined in the one Digital Order, but you need to ensure that the functionality being implemented can be combined. see Advanced Function Compatibility on page 113). Some additional data returned in the Digital Receipt can be accessed using the getresultfield supplementary command. Address Verification Service (AVS) Address Verification Service (AVS) is a security feature used for card not present transactions that compares the billing address entered by the cardholder with the records held in the card issuer's database. An AVS result code is returned in the transaction response message indicating the extent to which the addresses match (or fail to match). The merchant application is responsible for deciding how to handle the payment transaction on the basis of the AVS result code. Note: AVS is only supported for the S2I Acquirer. Furthermore, not all banks support AVS, so even though AVS data is passed in the transaction data, if the issuing bank does not support AVS, it will be ignored. Card Security Code (CSC/CVV2) The Card Security Code (CSC) is a security feature used for card not present transactions that compares the Card Security Code on the card with the records held in the card issuer's database. For example, on Visa and MasterCard credit cards, it is the three-digit value printed on the signature panel on the back. MiGS PC Integration Guide November

85 For American Express, the number is the 4-digit value printed on the front above the credit card account number. In a 2-Party transaction and a 3-Party with card details the card security code is sent, but in a standard 3-Party transaction the Payment Server requests this information from the cardholder. Depending on the level of the match between what the cardholder issuing institution has on file and what the cardholder has provided in the transaction, determines if the transaction will complete successfully or fail. In most cases if the transaction fails due to the CSC not being accepted, it results in a declined transaction with DigitalReceipt.QSIResponseCode = 2 Bank Declined Transaction For some Payment Providers, the CSC result code (CSCResultCode) is returned, which indicates the level that the CSC code matches the data held by the cardholder issuing institution. However this is not always provided and may show up as 'Unsupported'. Note: If CSC is collected by the merchant, this data is never to be stored or retained. This includes storing it in a logfile. CSC is mandatory in some countries and regions. Please check with your Payment Provider to determine the legal requirements of your region. However, not all banks support CSC so even though the data is passed in the transaction data, if the issuing bank does not support CSC, it will be ignored. Card Present Transactions This feature allows merchants to add Card Present information and track data to a transaction. This feature applies where the merchant integration collects card track data from POS terminals. Card present functionality can only be performed as a 2- Party Authorisation/Purchase transaction. The card track data needs to contain the correct start and end sentinel characters and trailing longitudinal redundancy check (LRC) characters. For all card present transactions, the Merchant Transaction Source, must be set to the value 'CARDPRESENT'. MiGS PC Integration Guide November

86 Regarding card track data, If both are available, both CardTrack1 and CardTrack2 must be added to the Digital Order or If only one is available, either CardTrack1 or CardTrack2 must be added to the Digital Order. If the magnetic stripe data is not available, for example, if the card is defective, or the POS terminal was malfunctioning at the time, it is sufficient to set the merchant transaction source to 'CARDPRESENT' and change the 'PAN Entry Mode' and 'PIN Entry Capability' values in POSEntryMode field to indicate that the card was sighted, but manually entered. Note: Card Track 3 data is not supported. For EMV transactions, 'CARDPRESENT' is used. The other mandatory fields are: EMCVICCData, CardSeqNum, POSEntryMode, and CardTrack2. Card types must be MasterCard or Visa. External Payment Selection (EPS) EPS is only used in a 3-Party transaction for bypassing the Payment Server page that displays the logos of all the cards the payment processor will accept. This can be helpful if the merchant's application already allows the cardholder to select the card they want to pay with. This stops the cardholder having to do a double selection, once at the merchant's application and once on the Payment Server. Merchant Transaction Source Merchant transaction source functionality allows a merchant to indicate the source of a 2-Party transaction. These can be INTERNET indicates an Internet transaction MOTOCC indicates a call centre transaction MOTO indicates a mail order or telephone order MAILORDER indicates a mail order transaction TELORDER indicates a telephone order transaction CARDPRESENT indicates that the merchant has sighted the card. This can only be used if the merchant has their privilege set to use this functionality, otherwise the transaction will be set to the merchant's default transaction source as defined by the Payment Provider. VOICERESPONSE - indicates that the merchant has captured the transaction from an IVR system. MiGS PC Integration Guide November

87 Merchants and acquirers can optionally set the merchant transaction source so the Payment Provider can calculate correct fees and charges for each transaction. Merchant Transaction Frequency Merchant transaction frequency functionality allows a merchant to set the frequency of the transactions for the cardholder's order. This can only be used if the merchant has their privilege set to use this functionality, otherwise the transaction will be set to the merchant's default transaction source as defined by the Payment Provider. The frequencies are: SINGLE indicates a single transaction where a single payment is used to complete the cardholder's order INSTALLMENT indicates an installment transaction where the cardholder authorises the merchant to deduct multiple payments over an agreed period of time for a single purchase RECURRING indicates a recurring transaction where the cardholder authorises the merchant to automatically debit their accounts for bill or invoice payments. This value only indicates to the acquirer that this is a recurring type payment; it does not mean that the merchant can use the Payment Server's Recurring Payment functionality. Note: The Payment Server does not contain a recurring payment facility to automatically trigger a recurring payment. This is up to the merchant to implement. Enhanced Industry Data Although Enhanced Industry Data functionality was originally designed for the travel industry, this functionality allows the merchant to enter any industry related data to be stored on the Payment Server for that transaction. It includes fields: Ticket Number allows the merchant to submit airline ticket number in the Digital Order, including Capture transactions. The previous ticket number is overwritten when a new ticket number is submitted. The Payment Server does not maintain an audit record of these changes. You can view the latest Ticket Number in the search results of a Transaction Search using the Merchant Administration portal on the Payment Server. Addendum Data allows the merchant to include industry specific data in the Digital Order. The data can include passenger names, ticket numbers, hotel bookings, etc. The addendum data is stored in the database, which may be used in creating reports external to the Payment Server. MiGS PC Integration Guide November

88 Both Ticket number and Addendum Data are passed with the Digital Order and stored on the Payment Server. The ticket number is passed to the financial institution as part of certain transactions. Note: Applies to 2-Party and 3-Party transactions. Bank Account Type The Bank Account Type card field is applicable to card types such as Maestro. The Bank Account Type functionality allows the merchant to enter the type of account, Savings or Cheque, to be stored on the Payment Server for that transaction. Bank Account Type is passed with the Digital Order and stored on the Payment Server. This identifier is mandatory if the card type is Maestro, and will be displayed in the Order Search results in the Merchant Administration portal on the Payment Server. Note: Applies to 2-Party transactions and 3-Party with card details transactions. ANZ Extended OrderInfo This is an extended OrderInfo field for the ANZ bank only. Some ANZ merchants require extra customer data for their records. It is for display purposes only in Merchant Administration and is not to be passed in any messages to the acquirer. Merchant Administration users are able to view this extended OrderInfo data in the Shopping Transaction History Detail Page. Payment Authentication Payment Authentications are designed to stop credit card fraud by authenticating cardholders when performing transactions over the Internet by using the 3-Domain Secure (3-D Secure or 3DS) protocol developed by Visa. A 3-D Secure transaction is performed immediately before a merchant performs a payment transaction, that is, an Authorisation transaction in the Auth/Capture mode, or a Purchase transaction in the Purchase mode. Authentication ensures that the card is being used by its legitimate owner. During a transaction, 3DS authentication allows the merchant to authenticate the cardholder by redirecting them to their card issuer where they enter a previously registered password. MiGS PC Integration Guide November

89 Merchants using 3DS can be configured to block any transaction that fails 3DS authentication. A transaction is considered to fail 3DS authentication if it results in a Verification Security Level of '07'. A blocked transaction results in a Dialect Response Code of 'B', which is included in the DR and displayed in the Financial Transaction Details page. Note: 3DS Authentication can only take place if the merchant is using a 3-Party model of transaction as the cardholder's browser has to be redirected to their card issuing bank where they enter their secret password. This is performed by the Payment Server if the cardholder is enrolled in the 3DS schemes of Verified by Visa MasterCard SecureCode and J/Secure Payment Authentication 3-D Secure transaction modes The following diagram shows an overview of the Payment Authentication 3-D Secure transaction modes. 1 Mode 1 - Combined 3-Party Authentication and Payment transaction - the merchant uses the Payment Server to perform the authentication and payment in the one transaction. The Payment Server collects the cardholder's card details and not the merchant's application. The Payment Server redirects the cardholder to the cardissuing bank to enter their 3-D Secure password. If the Authentication is performed correctly the Payment Server uses the Authentication information to perform the payment transaction. 2 Mode 2 - Combined 3-Party Authentication and Payment transaction, (merchant collects card details) the merchant uses the Payment Server to perform the authentication and payment in the one transaction. MiGS PC Integration Guide November

90 The merchant's application collects the cardholder's card details and sends them to the Payment Server, which redirects the cardholder to the card-issuing bank to enter their 3-D Secure password. If the Authentication is performed correctly the Payment Server uses the Authentication information to perform the payment transaction. 3 Mode 3a - 3-Party - Authentication Only transaction - the merchant uses the Payment Server to perform an authentication transaction and the payment transaction is processed as a separate transaction. This gives the merchant complete control as to when and if a payment transaction should proceed. The merchant's application collects the cardholder's card details and sends them to the Payment Server, which redirects the cardholder to the card-issuing bank to enter their 3-D Secure password. The Authentication operation outputs become the inputs for a 3-Party with card details transaction. Mode 3b - 2-Party Style Pre-Authenticated Payment transaction - the merchant may use the 3-Party - Authentication only transaction through the Payment Server or an external authentication provider to perform the 3-D Secure Authentication, and use the outputs from this operation to perform a 2- Party payment transaction through the Payment Server. Information Flow of a 3D-Secure Authentication/Payment transaction If you have been enabled to use Verified by Visa MasterCard SecureCode and J/Secure, the information flow for Verified by Visa MasterCard SecureCode and J/Secure where the Payment Server collects the card details (Mode1) is as follows: MiGS PC Integration Guide November

91 1 A cardholder browses the application, selects a product and enters their shipping details into the merchant's application at the checkout page. 2 The cardholder clicks a pay button and your application sends the payment Digital Order 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. 4 If the card is a Visa or MasterCard, the Payment Server then checks with the VBV or SecureCode Directory Server to determine if the card is enrolled in either the Verified by Visa (Visa 3-Domain Secure) or MasterCard SecureCode (MasterCard 3-Domain Secure) scheme. If the card is not enrolled in payment authentication scheme then the Payment Server continues processing the transaction as a normal 3-Party transaction without payment authentication. If the cardholder's card is registered in the payment authentication scheme, the Payment Server redirects the cardholder's browser to the card issuing bank site for authentication. 5 If the cardholder's card is registered in the payment authentication scheme, the Payment Server redirects the cardholder's browser to the card issuer's site for authentication. The card issuer's server displays the cardholder's secret message and the cardholder enters their response (password), which is checked against the Issuing bank's database. 6 At the completion of the authentication stage, the cardholder is redirected back to the Payment Server indicating whether or not the cardholder's password matched the password in the database. If the cardholder was not authenticated correctly, then the payment does not take place and the cardholder is redirected back to the merchant's site with an encrypted Digital Receipt containing details to indicate the authentication failed - see step 8. 7 If the cardholder was authenticated correctly, the Payment Server continues with processing the transaction with the details of the successful authentication operation. 8 The Payment Server then redirects the cardholder back to merchant's site with the Digital Receipt. The Digital Receipt contains the result of the transaction. 9 The application decrypts the Digital Receipt and displays the receipt and confirms the order to the cardholder for their records. Note: If the cardholder is enrolled in the 3D Secure scheme but is not authenticated correctly, for example, because the cardholder may have entered their password incorrectly 3 times, then the merchant's application is sent a response code of 'F' to indicate the cardholder failed the authentication process and the transaction does not proceed. Mode 2 and Mode 3a are slight variations on the above information flow. In mode 2 and mode 3a the merchant collects the card details and passes them through, which means step 3 is eliminated. For Mode 3a step 7 is also eliminated, the payment being performed through a separate 2-Party transaction after this Authentication. MiGS PC Integration Guide November

92 Advantages and Disadvantages of the 3-D Secure modes of transaction Mode Advantages Disadvantages Mode 1 3 Party Authentication and Payment transaction mode Mode 2 3 Party Authentication and Payment transaction (Merchant collects card details) Mode 3a 3 Party Authentication Only transaction mode Mode 3b 2 Party Pre-Authenticated transaction mode Simple to implement. The Payment Provider collects the cardholder's card details and not the merchant, which provides highest level of security for the cardholder's card details. Suits a merchant that normally collects all the card details. Branding of the payment pages on the website remains consistent throughout the whole transaction, except the screen where the cardholder enters their password for 3-D secure. Suits a merchant that normally collects all the card details. Branding of the payment pages on the website remains consistent throughout the whole transaction, except the screen where the cardholder enters their password for 3-D secure. Gives the merchant maximum control of the transaction. If the cardholder is not enrolled in 3-D Secure, then the merchant's application can stop the transaction from progressing to the Payment stage providing full control over the transaction risk. Branding remains consistent throughout the whole transaction, except for the one screen where the cardholder enters their 3-D Secure password. The merchant is not able to use their own branding throughout the whole transaction, as the Payment Provider displays their own branding while the card details are being captured. If the cardholder is not enrolled in 3-D Secure, or the authentication could not be performed, the authentication will not take place and the transaction will automatically move into the payment stage. If the cardholder is not enrolled in 3-D Secure the authentication will not take place and the transaction will automatically move into the payment stage. It consists of two separate transactions, the Authentication and the Payment, which can be more difficult for a merchant to integrate. Can only be performed if the merchant collects all the card details. It consists of two separate transactions, the Authentication and the Payment, which can be more difficult for a merchant to integrate. MiGS PC Integration Guide November

93 Mode 1 - Implementing a 3 Party Authentication and Payment transaction (Payment Server collects card details) The information flow for a successful 3 Party Authentication and Payment transaction mode is very similar to a standard 3-Party transaction. The cardholder submits the order. 1 The browser is redirected to the Payment Server. 2 The Payment Server collects the cardholder's card details and determines if the cardholder is enrolled in 3-D Secure. If the card is not enrolled in 3-D Secure then steps 4, 5 and 6 are skipped. 3 The Payment Server redirects the cardholder's browser to the Access Control Server (ACS) site for authentication. 4 The ACS displays the cardholder's secret message and the cardholder enters their password, which is checked with the Card Issuer system. 5 The cardholder is redirected back to the Payment Server and the card issuer returns an authentication message showing whether or not the cardholder's password matched the password in the card issuer system. If the Authentication failed, step 7 is bypassed and the cardholder is redirected back to the merchant (see step 8) with a DigitalReceipt.QSIResponseCode of 'F'. No payment takes place in this scenario. 6 If the cardholder is authenticated correctly, the Payment Server continues with processing the payment part of the transaction. The cardholder is redirected back to the merchant, where the receipt is passed back to the merchant and: 7 The receipt displayed to the cardholder. MiGS PC Integration Guide November

94 Mode 2 - Implementing a 3 Party Authentication and Payment transaction (Merchant collects card details) The information flow for Mode 2 transaction where the merchant collect the card details uses the basic 3-Party style of transaction with some additional input fields. For more information, please refer Basic 3-Party Transaction on page 55) The information flow for a 3 Party Style Authentication & Payment mode 2 transaction is: 1 The cardholder enters their card details into the merchant's application, clicks the merchant's Pay button. 2 Their browser is redirected to the Payment Server. The Payment Server determines if the card is enrolled in the 3-D Secure scheme by checking the Verified by Visa MasterCard SecureCode and J/Secure system. If the card is not enrolled in 3-D Secure then steps 3, 4 and 5 are skipped. 3 If the cardholder's card is registered, the Payment Server redirects the cardholder's browser to the Access Control Server (ACS) site for authentication. 4 The ACS displays the cardholder's secret message, the cardholder enters their secret password, which is checked with the Card Issuer system. 5 The cardholder is redirected back to the Payment Server and the card issuer returns an authentication message showing whether or not the cardholder's password matched the password in the card issuer system. If the Authentication failed, step 6 is bypassed and the cardholder is redirected back to the merchant MiGS PC Integration Guide November

95 (see step 7) with a DigitalReceipt.QSIResponseCode of 'F'. No payment takes place in this scenario. 6 If the cardholder is authenticated correctly, the Payment Server continues with processing the payment part of the transaction. 7 The cardholder is redirected back to the merchant, where the receipt is passed back to the merchant and: 8 The receipt displayed to the cardholder. Mode 3a - Implementing a 3 Party Style Authentication Only transaction In a 3 Party Style Authentication Only transaction mode, the merchant's application can stop the transaction from progressing to the Payment stage and return an error message back to the cardholder if the cardholder is not enrolled in 3-D Secure. The other scenario is a merchant may want to perform an immediate Authentication operation, but delay the payment transaction. The information flow for a 3 Party Style Authentication Only transaction mode uses the 3-Party style of transaction with additional card details. For more information, please refer to Basic 3-Party Transaction on page 55). The information flow for a 3 Party Style Authentication Only mode transaction is: 1 The cardholder enters their card details into the merchant's application. 2 Their browser is redirected to the Payment Server and the Payment Server determines if the card is enrolled in the 3-D Secure scheme by checking the Verified by Visa MasterCard SecureCode and J/Secure system. MiGS PC Integration Guide November

96 3 If the cardholder's card is registered, the Payment Server redirects the cardholder's browser to the Access Control Server (ACS) site for authentication. If the card is not enrolled in 3-D Secure then steps 3, 4 and 5 are skipped. 4 The ACS displays the cardholder's secret message, the cardholder enters their secret password, which is checked with the Card Issuer system. 5 The cardholder is redirected back to the Payment Server and the card issuer sends an authentication message showing whether or not the cardholder's password matched the password in the Card Issuer system 6 The cardholder is redirected back to the merchant's site. 7 The merchant examines the DigitalReceipt.QSIResponseCode to determine if the cardholder was enrolled, and if they were successfully authenticated. The merchant can now determine whether or not to proceed with the Payment. The Authentication outputs from this transaction would then be used for the Pre-Authenticated transaction along with the card details. Mode 3b - Implementing a 2-Party Style Pre-Authenticated Payment Transaction The information flow for a 2-Party Style Pre-Authenticated Payment transaction uses the 2 Party style of transaction. For more information on 2 Party transactions, see Integrating 2-Party Payments on page 33). The information flow for a 2-Party Style Pre-Authenticated Payment transaction is: 1 The authentication outputs from the Authentication Only transaction or external MPI provider are used in the Standard 2-Party transaction with additional input fields. 2 The Payment Server then performs the payment part of the Pre-Authenticated Payment transaction. 3 The Result of the payment is sent back to the merchant. 4 The merchant displays a receipt page to the cardholder, which indicates whether the transaction was successful or not. MiGS PC Integration Guide November

97 8 Advanced Merchant Administration (AMA) There are a number of additional transactional options that you can implement, depending on your implementation of Payment Client. All of these transactions operate using the 2-Party model. Merchants and users who need AMA transactions must have a username, password and be set up with the appropriate AMA privileges to run a particular AMA transaction. Capture The AMA Capture command allows a merchant to capture the funds from a previous authorisation transaction. A merchant that operates using Authorisation/Capture mode performs two transactions to transfer the funds into their account. 1 The first transaction (Authorisation) reserves the funds on the cardholder's credit card. 2 The second transaction (Capture) transfers the funds from the cardholder's account to the merchant's account. Capture allows a merchant to complete a transaction performed using the Authorisation/Capture Payment Model. The capture transaction initiates the transfer of funds from the cardholder's account to the merchant's account. Note: In Purchase mode, the authorisation and capture operations are completed at the same time in the one purchase transaction, so you do not need to perform a separate capture is not needed, that is this capture command is not necessary if the merchant is operating in Purchase mode. There are two ways you can capture the funds from an authorisation transaction: Manually using Merchant Administration. This is the simplest method if you do not have many transactions. For more information, refer to your Merchant Administration User Guide. Using the Capture command using the Payment Client to directly perform the capture transaction from your application. Payment Providers allow merchants to perform as many capture transactions on the original Authorisation transaction as required, but the total amount captured cannot be more than the amount specified in the original Authorisation transaction, unless the excessive capture privilege is enabled. MiGS PC Integration Guide November

98 Refund AMA Refund allows you to refund funds for a previous purchase or capture transaction from the merchant's account back to the cardholder's account. Refunds can only be performed for a previously completed a purchase or capture transaction for the particular order. The merchant can run any number of refund transactions on the original transaction, but cannot refund more than has been obtained via a purchase or capture transaction. There are two ways to refund the funds: Manually using Merchant Administration. This is the simplest method if the merchant does not have many refund transactions. For more information, refer to your Merchant Administration User Guide. Using the AMA Refund command using the Payment Client to directly perform refunds from the merchant's application. Void Capture AMA Void Capture allows a merchant to void the funds from a previous capture transaction in Auth/Capture mode, that has not been processed by the acquiring institution. This command cannot be used if the merchant is operating in Purchase mode. The merchant can only run one void capture transaction on the original capture transaction, as it completely removes the capture transaction as though it never occurred. A void capture must be run before the batch containing the original capture transaction is processed by the acquiring institution. There are two ways you can Void Capture the funds: Manually using Merchant Administration. This is the simplest method if you do not have many Void Capture transactions. For more information, refer to your Merchant Administration User Guide. Using the Void Capture command using the Payment Client to directly perform Void Captures from your application. The merchant must have a user enabled with AMA and Void privileges to use this functionality. Note: Not all financial institutions support void transactions, only those that operate in switch to issuer mode. Please consult with your financial institution if they support voids. Only the most recent transaction in an order can be voided. MiGS PC Integration Guide November

99 Void Refund AMA Void Refund allows a merchant to void a previous refund transaction that has not been processed by the acquiring institution. The merchant can only run one Void Refund transaction on the original refund transaction as it completely removes the refund transaction as though it never occurred. The Void Refund must be run before the acquiring institution processes the batch containing the original refund transaction. There are two ways you can Void Refund the funds. Your Payment Provider must enable this function on your Merchant Profile for you to use either of these methods: Manually using Merchant Administration. This is the simplest method if you do not have many Void Refund transactions. For more information, refer to your Merchant Administration User Guide. Using the Void Refund command using the Payment Client to directly perform Void Refund from your application. The merchant must have a user enabled with AMA and Void privileges to use this functionality. Note: Not all financial institutions support void transactions. Please consult with your financial institution if they support voids. Only the most recent transaction in an order can be voided. Void Purchase AMA Void Purchase allows a purchase merchant to void a purchase transaction that has not been processed by the acquiring institution. It is not available for Auth/Capture mode merchants. This transaction is not possible for Debit and EBT transactions. The merchant can only run one 'Void Purchase' transaction on the original 'Purchase' transaction as it completely removes the purchase transaction as though it never occurred. The Admin Void Purchase must be run before the acquiring institution processes the batch containing the original purchase transaction. There are two ways you can Void Purchase the funds. Your Payment Provider must enable this function on your Merchant Profile for you to use either of these methods: Manually using Merchant Administration. This is the simplest method if you don't have many Void Purchase transactions. For more information please refer to your Merchant Administration User Guide. Using the Void Purchase command using the Payment Client to directly perform Void Purchase from your application. The merchant must have a user enabled with AMA and Void privileges to use this functionality. MiGS PC Integration Guide November

100 Note: Not all banks support void transactions, only those that operate in switch to issuer mode. Consult with your financial institution if they support voids. Only the most recent transaction in an order can be voided. QueryDR The AMA QueryDR command allows a merchant to search for a duplicate transaction receipt. The search is performed on the key - MerchTxnRef, so the MerchTxnRef field must be a unique value. If you want to use QueryDR to return duplicate receipts, it must be done in under 3 days or no results matching the criteria will be returned. This is because the database only contains data up to 3 days old. If a transaction receipt is found, the results will contain the same fields as the original receipt plus the 2 flags described below. QueryDR always returns these 2 flags: QueryDR.DRExists: If no transactions are found that match the MerchTxnRef number, this value will be set to 'N' for No. If any transactions are found that match the MerchTxnRef number, this value will be set to 'Y' for Yes. QueryDR.FoundMultipleDRs: This is used to determine if there are multiple results. If the value is N, then only one MerchTxnRef matches the search criteria. If the value is Y, then there are multiple MerchTxnRef matching the search criteria, but it will return the most recent transaction. If the query result returned is not the correct one, the merchant must manually search through Merchant Administration on the Payment Server. Note: QueryDR does not return receipt data for 3-D Secure (Verified by Visa MasterCard SecureCode and J/Secure ) Authentication Only transactions. P2P Transactions The Person-to-Person (P2P) feature allows the merchant to perform a funds transfer between two credit cards. Note: It is not possible to void or refund either the funding component or the payment component of a P2P transaction. MiGS PC Integration Guide November

101 AMA Shopping Transaction History A shopping transaction history returns all of the OrderID reference transactions (shopping transactions) between a start date and an end date where the cardholder entered their card details for a 2-Party or 3-Party transaction. In Purchase mode it would be the Purchase transaction; or the Auth transaction in Auth/Capture mode. It also contains summary information for the entire shopping experience, including captures and refunds. The Shopping Transaction History command allows a merchant to view the details of shopping transactions for the MerchantId in the Payment Server over a specified period. The period is specified by the use of a Start Date/Time value and an End Date/Time value. The Start Date/Time format and an End Date/Time format depends on the database being used in the Payment Server. Please refer to your Payment Provider for the correct format used by the Payment Server. Note: The capacity in Payment Client 3.1 to handle large results has been upgraded. However, there is a limitation in the Active Server Pages (ASP) environment on the length of a field that can be handled. Therefore when you receive an especially large result from a Reconciliation Query, the ASP environment will truncate the DR when it hits the length limitation. So although the COM interface supports large results, you will not get them if you are using ASP web pages on IIS. However other programming environments that interface to COM (for example VBA and C++) will be able to utilise the large results capacity. AMA Limited Shopping Transaction History A limited shopping transaction history returns some of the OrderIDs reference transactions (shopping transactions) between a start date and an end date where the cardholder entered their card details for a 2-Party or 3-Party transaction. In Purchase mode it would be the Purchase transaction or the Auth transaction in Auth/Capture mode. It also contains some summary information for the entire shopping experience (i.e. including captures, refunds). The Limited Shopping Transaction History command allows a merchant to limit the number of shopping transactions for the MerchantId in the Payment Server over a specified period. The period is specified by the use of a Start Date/Time value and an End Date/Time value. The limit is specified by the field 'MaxTrans' and: The starting point to start returning transactions from is specified by the field: 'LastTxnReturned'. MiGS PC Integration Guide November

102 The Start Date/Time format and an End Date/Time format depends on the database being used in the Payment Server. Please refer to your Payment Provider for the correct format being used by the Payment Server. Note: The capacity in Payment Client 3.1 to handle large results has been upgraded. However, there is a limitation in the Active Server Pages (ASP) environment on the length of a field that can be handled. Therefore when you receive an especially large result from a Reconciliation Query, the ASP environment will truncate the DR when it hits the length limitation. So although the COM interface supports large results, you will not get them if you are using ASP web pages on IIS. However other programming environments that interface to COM (for example VBA and C++) will be able to utilise the large results capacity. AMA Financial Transaction History A financial transaction history refers to the series of transactions that have been performed over a time period relating back to a specified Payment Server OrderID (shopping transaction) number. Input the reference transaction number and the output displays all the results about the transaction and other transactions linked to it. The number of financial transactions generated from a Payment Server OrderID depends on the type of transaction and the actions performed. In Purchase mode this only includes the original purchase transaction, plus any refunds and voids that have been performed. In Auth/Capture mode this is the original Auth transaction plus any captures, refunds and voids. AMA Spanned Financial Transaction History A spanned financial transaction history refers to the series of transactions that have been performed over the time period specified by a start date and end date. Input a Start Date/Time value and an End Date/Time value and it returns all the details about all the transactions that have occurred in that period for this MerchantId. In Purchase mode this only includes the original purchase transaction plus any related refunds and voids that have been performed. In Auth/Capture mode this includes the original Auth transactions plus any related captures, and refunds and voids for those Auth transactions. The Start Date/Time format and an End Date/Time format depends on the database being used in the Payment Server. Please refer to your Payment Provider for the correct format being used by the Payment Server. MiGS PC Integration Guide November

103 Note: The capacity in Payment Client 3.1 to handle large results has been upgraded. However, there is a limitation in the Active Server Pages (ASP) environment on the length of a field that can be handled. Therefore when you receive an especially large result from a Reconciliation Query, the ASP environment will truncate the DR when it hits the length limitation. So although the COM interface supports large results, you will not get them if you are using ASP web pages on IIS. However other programming environments that interface to COM (for example VBA and C++) will be able to utilise the large results capacity. MiGS PC Integration Guide November

104 9 Troubleshooting and FAQs Troubleshooting This section contains suggestions and solutions to problems that may occur with your integration. What Do We Do if a Session Timeout Occurs? It is possible that while a cardholder is entering their card details at the Payment Server, the session is broken (say a communication failure due to a modem connection dropping off). If this occurs, a cardholder will lose their session. Even if they come back to your site, they will have a new session, and their old session will never be completed. To determine the status of the lost transaction, you will need to perform a QueryDR transaction based on the original MerchTxnRef. Does the Cardholder's Internet Browser Need to Support Cookies? The Payment Client interface requires a cardholder's browser to support cookies for all 3-Party. What Happens if a Digital Receipt Fails to Come Back? To deal with a Digital Receipt that fails to come back: 1 Flag the transaction as having an error, so that it needs to be manually checked using Merchant Administration on the Payment Server. Or, 2 Use the Advanced Merchant Administration (AMA), QueryDR command to search the Payment Server database for the transaction. The MerchTxnRef is used as the transaction identifier when searching using QueryDR command. MiGS PC Integration Guide November

105 Since the Digital Receipt has failed to come back, there is no transaction number available from the Payment Server to identify the transaction in question, and this is why you use the MerchTxnRef. It is important to have a unique MerchTxnRef for every transaction otherwise the query could return multiple results. Only the most recent transaction is returned in the QueryDR command if there are multiple results, but this may not be the transaction you are concerned with. If the DigitalReceipt.QSIResponseCode was successful When you find the required MerchTxnRef in the QueryDR, check the DigitalReceipt.QSIResponseCode field to see if it is successful (should be equal to '0'). If the DigitalReceipt.QSIResponseCode is 0, then the transaction is successful and you just need to extract the relevant data details from the QueryDR results for your records. If the DigitalReceipt.QSIResponseCode code was not successful. If the DigitalReceipt.QSIResponseCode is not 0, you need to determine the next course of action based on what you would do if the DigitalReceipt.QSIResponseCode were not 0 in a normal Digital Receipt coming back from the Payment Server. MiGS PC Integration Guide November

106 If you did not find a QueryDR result. If you query the Payment Server for the MerchTxnRef using the QueryDR call and you do not receive any results, that is QueryDR.DRExists = 'N', then it is safe to repeat the transaction. It is safe to use the same MerchTxnRef, as the existing one does not show up in the Payment Server's database and therefore it was never processed. If you find multiple QueryDR results. If the QueryDR is flagged as having multiple results (returns 'Y' in the QueryDR.FoundMultipleDRs field), then the MerchTxnRef is not unique. This is the primary reason for implementing a unique MerchTxnRef for every transaction. QueryDR returns the latest transaction but this may not be the one you require. This solution requires more data capture and processing, but it is only necessary when you do not have a unique MerchTxnRef number. How Do I Add the PCThread.sh in the Start-up Environment in Linux? 1 Log in as root. 2 Navigate to /etc/rc.d directory. cd /etc/rc.d 3 Open rc.local file, using vi or pico, for editing. 4 At the end of the file add following line <path_to_java>/java -cp <path_to_paymentclient_classes> PaymentClient.PCService & 5 For example on our system that is: /usr/local/apps/jdk1.3.1/jre/bin/java -cp /usr/local/dialect/paymentclient/classes PaymentClient.PCService & 6 Save the file and re-boot the machine. Notes Make sure the line ends with '&', as that will run the process in the background, and will not obstruct the start-up process. Make sure that the paths are correct. You can test it by running it on the command line prior to entering it to the file. To test, you can do a netstat and verify that port 9050 is in use, or telnet on localhost to port 9050 and type: 1,test (you should receive back a line with: 1,echo:test). MiGS PC Integration Guide November

107 Handling Socket connection Time Outs In most applications like ASP and Java, the Sockets are set-up with a socket time-out value, for example in ASP: ' Open a socket connection to the Payment Client socketpayclient.timeout = ' 200 seconds socketpayclient.host = payclientip & ":" & payclientport If the socket times out you need to handle the situation and determine the status of the transaction that timed out. The easiest way to do this is to perform a QueryDR transaction based on the original MerchTxnRef. It is much better to have the sockets timeout value set to a longer value than a shorter value. If the socket timeout period is reduced to a value too low, for example 10 seconds, then under times of heavy load on the Payment Server this short timeout period may be exceeded. The time out would normally occur on processing messages like sending a Digital Order, which take time for the Payment Server to process. The message is transmitted to the Payment Server, where it is processed successfully, but the successful response of '1,1' may take longer to arrive back at the socket than the socket time out period allows. So the data remains in the Payment Client buffer waiting for transmittal to the application. If the time out is ignored, the next command sent will contain this old status value, and its status will still be in the Payment Client buffer again waiting for transmittal to the application. All responses are then displaced. Note: In each of the socket example commands shown in this guide, the \n 'New Line' character at the end of each command string is used to tell Java to input a Line Feed character to indicate the end of the command. Failure to include this character or a Carriage Return character - Java \r at the end causes the socket command to fail. Some programming languages such as ASP can automatically add this to the end of the command so the programmer does not have to include it. You need to ensure that the timeout period is long enough not to time out prematurely, but if the socket does time out, it needs to be detected and not continue with the next step of the transaction. If the merchant application continues and process the next command, then all future responses are displaced. MiGS PC Integration Guide November

108 Comparison of a good and bad transaction when the timeout is ignored Socket Information Flow 2-Party Good Transaction Bad Transaction Sent Received Sent Received 1,Test\n 1,echo:Test 1,Test\n 1,echo:Test translates to echo("test") command in Payment Client 7,CardNum, \n 1,1 7,CardNum, \n 1,1 adddigitalorderfield("cardnum") command 7,CardExp,0202\n 1,1 7,CardExp,0202\n 1,1 adddigitalorderfield("cardexpiry") command 7,ticketNo,data for transaction\n 1,1 7,ticketNo,data for transaction\n 1,1 adddigitalorderfield("ticketno") command 6,1234,Test2008,100,en,\n 1,1 6,1234,Test2008,100,en,\n Socket times out, no response. Merchant continues with the next command. sendmotodigitalorder("1234", "Test2008", "100", "en", "") 5\n 1,1 5,\n 1,1 (From 6,1234,Test2008, etc.) nextresult( ) command 4,DigitalReceipt.QSIResponseCode \n 1,0 * 4,DigitalReceipt.QSIResponse Code\n 1,1 (From 5,) Error Response* objpayclient.getresultfield("digitalreceipt.qsiresponsecode") 4,DigitalReceipt.TransactionNo\n 1,271 4,DigitalReceipt.TransactionN o\n objpayclient.getresultfield("digitalreceipt.transactionno") 1,0 (From 4, QSIRespCode,) 4,DigitalReceipt.ReceiptNo\n 1, ,DigitalReceipt.ReceiptNo\n 1,271 (From 4, TxNo,) objpayclient.getresultfield("digitalreceipt.receiptno") * A QSIResponse Code of '0' indicates a successful transaction. * A QSIResponse Code of '1' indicates a declined transaction The commands for the Sockets interface are shown in The Payment Client Reference Manual. If the time out is not detected and the transaction continues, the data returned is incorrect for each of the following commands that are sent after the socket timeout. The result of not detecting and handling the time out is that a successful transaction has been conducted but the merchant application will interpret the transaction as a failure. MiGS PC Integration Guide November

109 The response from the command '5\n' is '1,1', which is a good response but it is actually from the sendmotodigitalorder command (6,1234,Test2008,100,en,\n) The response from command '4,DigitalReceipt.QSIResponseCode\n' is '1,1' which shows up as a QSIResponseCode of '1', which indicates a failed transaction, but this response is actually from the '5\n' command. The actual QSIResponseCode is '0' because the transaction completed successfully, but it is delayed one command so it is lost. One of the common responses to this is to have the merchant application redo the transaction, which would result in a duplicate transaction. The response from command '4,DigitalReceipt.TransactionNo\n' is '1,0' which shows up as a Transaction No of '0', which is incorrect, but this response is actually from the '4,DigitalReceipt.QSIResponseCode\n' command. The response from command '4,DigitalReceipt.ReceiptNo\n' is '1,271' which shows up as a Receipt No of '271', which is incorrect, but this response is from the 4,DigitalReceipt.TransactionNo\n command. The real Receipt No of ' ' is lost from the transaction stream. If the Payment Server has successfully processed the transaction and the transaction is repeated it would result in a duplicate transaction. If a socket time out occurs, do not ignore the time out, as it will only cause errors. Detection can be as simple as looking for an empty receive value from the socket. There are two ways of dealing with a Payment Client sockets timeout: 1 Flag the transaction as having an error that needs to be manually checked using Merchant Administration on the Payment Server. You need to determine what to send back to the cardholder while this manual check is performed, as it could be a good transaction. 2 Close the socket and open a new socket connection and use Advanced Merchant Administration commands to search the Payment Server database for the transaction. The QueryDR command can be used to search the Payment Server using the MerchTxnRef as the transaction identifier. At this stage there is no transaction number available back from the Payment Server to identify the transaction, so it is important to have a unique MerchTxnRef for every transaction. If you are using QueryDR then: If the QSIResponseCode code in the QueryDR function was successful When you find the required MerchTxnRef in the QueryDR, check the QSIResponseCode field to see if it is successful (should be equal to '0'). If the QSIResponseCode is 0, then the transaction is successful and you just need to extract the relevant data details from the QueryDR results for your records. If the QSIResponseCode code the QueryDR function was not successful If the QSIResponseCode is not 0, you need to determine the next course of action based on what you would do if the QSIResponseCode were not 0 in a normal Digital Receipt coming back from the Payment Server. MiGS PC Integration Guide November

110 If you did not find any results using QueryDR function If you query the Payment Server for the MerchTxnRef using the QueryDR function and you do not receive any results, (i.e. QueryDR.DRExists = N) then it is safe to repeat the transaction. It is safe to use the same MerchTxnRef, as the existing one does not show up in the Payment Server's database and was therefore never processed. If the QueryDR is flagged as having multiple results If the QueryDR is flagged as having multiple results (returns 'Y' in the QueryDR.FoundMultipleDRs field), the MerchTxnRef is not unique and you will have to manually check all the results for the same time when the MerchTxnRef number was created. This solution requires more data capture and processing, but it is only necessary when you don't have a unique MerchTxnRef number. Frequently Asked Questions What is an Outage? An outage is considered a production fault as it means that the Payment Server is temporarily offline; for example for maintenance and upgrades, and so forth. During an outage, all transactions are declined with an error message indicating that the service is currently unavailable. Can the Payment Server's Payment Pages be Modified for a Merchant? No. The Payment Server's payment pages are branded using either the Payment Provider's or Bank's branding to assure cardholders of the security of the transaction. If you do not wish to display the Payment Provider's branded pages you need to implement either the 3-Party with card details, or the 2-Party integration models. Note: Using the 2-Party Integration model prohibits the use of 3-D Secure Verified by Visa MasterCard SecureCode and J/Secure functionality. How Do I know If a Transaction Has Been Approved? All approved transactions are represented with a DigitalReceipt.QSIResponseCode of '0' (zero) from the Payment Server. Any other code represents a declined or failed transaction. MiGS PC Integration Guide November

111 Can the Payment Client Listen on Any Port Other than 9050? Yes, the...\dialect\paymentclient\config\pcservice.properties file can be amended to reflect the new port number, any other IP addresses and the maximum number of threads allocated to the new port. This can be done as follows. Open the...\dialect\paymentclient\config\pcservice.properties file in a text file editor and amend the following lines: ports=xxxx (Where XXXX represents the socket port number to be used.) ipnumber1= ( is the localhost machine) ipnumberx=xxx.xxx.xxx.xxx (xxx.xxx.xxx.xxx is the IP number of a machine requiring to connect to the socket remotely) threads=x (Maximum number of threads that may connect to the socket interface) Detailed instructions are included in the Payment Client Installation Guide. Longevity - How Long Will the Technology be Useful? Additional functionality can be added to the Payment Server, which requires the merchant to perform small additional integration work to utilise any new functions. Typically, existing Payment Clients and their methods are not affected by new functionality and remain backward compatible. Handling Large Peaks in Transaction Volumes? The Payment Server queues pending transactions so transactions are not lost, although the cardholder may at times notice a slight delay when transactional loads are very high. How Often Can I Reconcile? Reconciliation can be completed using either Merchant Administration or Advanced Merchant Administration. In either case the Payment Client does not limit the frequency of the function, but the payment processor may have a settlement frequency - generally daily - which is useful if any problems with transactions occur as all the days transaction are in the same batch. Is a Shopping Cart required? It is not necessary to have a shopping cart. All that is required is that the transaction information is within the Digital Order passed to the Payment Server. MiGS PC Integration Guide November

112 What is Merchant Administration? Merchant Administration is the merchants internet based administration portal, which allows merchants to monitor and manage their on-line processing and administration of payments through a series of easy to use pages. To use Merchant Administration, you need to have access to the internet through a browser (such as Internet Explorer). You also need the Acquiring Institutions URL (or web site address). The merchant can use one of two methods to manage their transactions: Merchant Administration using a browser interface to interactively perform historical searches, captures, refunds settlements and to perform setup activities. These functions are described in this guide. For more details, please refer to the Merchant Administration User Guide. Advanced Merchant Administration using the Payment Client to directly access the Payment Gateway to perform all transaction-related actions (for example, captures, refunds and purchases) integrated with merchants' software interfaces. Why Can't I Utilise the Advanced Merchant Administration (AMA) Functionality Via the Payment Client? The following reasons may cause AMA functionality not to work: A separate operator needs to be created for AMA API calls Your merchant account is required to have the privileges to execute AMA functions, please check with the helpdesk that this is enabled for your merchant account. Advanced Admin methods privilege has to be enabled in operator set-up in Merchant Administration. An AMA operator cannot connect to Merchant Administration unless the AMA privilege is removed. Check that you are not using incorrect MerchantId, OperatorID or Password details. If the Payment Client is communicating with the Payment Server when attempting to process AMA calls, check that the firewall is open to communicate between the two applications. How Much Will it Cost to Keep the Payment Site Running? The Payment Client is very stable, is not difficult to keep running and requires no more maintenance than the web server itself. MiGS PC Integration Guide November

113 Does the Payment Server Handle Large Peaks in Transaction Volumes? The Payment Server queues pending transactions so transactions are not lost, although the cardholder may at times notice a slight delay when transactional loads are extremely high. How Long Will an Authorisation be Valid on a Cardholder Account? This depends on the Financial Institution who issued the card to the cardholder. Each card Issuer defines the authorisation expiry period in which they hold the funds on the cardholder's account, while they wait for the arrival of the capture transaction. Generally it is 5-8 processing days, before the authorisation purges from the cardholder account and access to the funds are released back to the cardholder. What is the RRN and How Do I Use It? RRN (Reference Retrieval Number) is a unique number for a particular MerchantId. This is the value that is passed back to the cardholder for their records. You cannot search for this field in Merchant Administration, but it is displayed in Merchant Administration on the transaction details pages as the Reference Retrieval Number (RRN). It is one of the fields returned in a QueryDR and the transaction result (captures, refunds). The RRN is useful when your application does not provide a receipt number. The RRN can be viewed in Merchant Administration. What is the Difference Between RRN, MerchTxnRef, OrderInfo, AuthorizeId and TransNo? RRN (Reference Retrieval Number) is a unique number assigned to each transaction for a particular MerchantId. This is the value that is passed back to the cardholder for their records. You cannot search on this field in Merchant Administration, but it is displayed in Merchant Administration on the transaction details pages as the Reference Retrieval Number (RRN). It is one of the fields returned in a querydr and the transaction result (captures, refunds). MerchTxnRef is generated by your merchant application. Ideally it should be a unique value for each transaction and you should retain this number so that transactions can be searched for in your application and the Payment Server. See Merchant Transaction Reference (MerchTxnRef) on page 19) OrderInfo is also generated by your application. It should also be a unique value for each order, which you should retain so that you can search for the transaction in your application and the Payment Server. AuthorizeId is an identifier from the Acquiring Bank, which is in the Digital Receipt for the authorisation. This field cannot be searched for in Merchant Administration, but it is displayed in Merchant Administration as the Authorisation Code. It is one of the fields returned in a transaction result and an AMA QueryDR. MiGS PC Integration Guide November

114 TransNo or TransactionNo is a unique number for each MerchantId generated by the Payment Server that is called the OrderID or shopping transaction number. The OrderID is the key reference value for transactions when using AMA transactional functions like captures and refunds. Advanced Function Compatibility The following table lists the common functions available on the Payment Server and the compatibility of functions the merchant can use. To determine the functionality that can be included in a Digital Order choose a function in a column and follow it down to the appropriate row. Enabled for this transaction type or compatible with this feature. Not enabled for this transaction type or not compatible with this feature Supplementary Feature Compatibility Address Verification Card Security Code Ticket Number External Payment Selection Card Details in 3-Party 3-D Secure Authentication & Payment Card Present CPC 2 2-Party Transaction 3-Party Transaction Address Verification Card Security Code Ticket Number External Payment Selection Card Details in 3-Party 3-D Secure Authentication & Payment Card Present MiGS PC Integration Guide November

115 Suggested Merchant Actions Acq Resp Code Recur Resp Code Merchant Advice Description Examples of reason for decline Suggested Merchant Action DE39 DE48 SE New account information available Expired card Account upgrade Portfolio sale Conversion Try again later Over credit limit Insufficient funds Do not try again Account closed Fraudulent Obtain new account information before next billing cycle. Recycle transaction 72 hours later. Obtain another type of payment from customer. MiGS PC Integration Guide November