MiGS PC Integration Guide. November 2008 Software version:

(1)

MiGS PC

Integration Guide

November 2008

Software version: 3.1.21.0

(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 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.

License

Agreement

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.

Trademarks

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 63366-7263 USA

1-636-722-6100

(3)

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.

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.

(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

(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,

(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.

(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.

(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

(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

(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.

(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.

(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:

(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

(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.

(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.

(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 pre-production 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

(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 cross-referencing 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

(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

(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.

(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 http:// changes to https:// 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 https:// - 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.

(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 E-mail 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, 498765XXXXXXX769).

(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

(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.

(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.

(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 8.

6. 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.

(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

(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:

(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.

(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.

(33)

(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 merchant-hosted payments.

1 A cardholder decides to make a purchase and provides their card details directly to your online store.

(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) 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. Card Expiry Date (CardExp) 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 1305. The value must be expressed as a 4-digit number (integer) with no white space or formatting characters.

Merchant Transaction Reference

Value (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 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

(36)

Java and COM Examples addDigitalOrderField(”CardNum”,”5123456789012346”) addDigitalOrderField(”CardExp”,”1305”) addDigitalOrderField("MerchTxnRef", ”12345”) Sockets Examples “7,CardNum,5123456789012346\n” “7,CardExp,0905\n” “7,MerchTxnRef,12345\n”

Primary Command: sendMOTODigitalOrder This primary command requires the following information:

Order Information Number

(OrderInfo) This is used to input any merchant/customer information about this transaction that may be required to be stored. Null values are not accepted.

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 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 1250.

Locale (Locale) Reserved for future use. Please use the default value of “en”. Return URL (ReturnURL) 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) 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) The merchant's information about this transaction. Can be a simple order number or shopping basket number. Merchant Identification Number

(MerchantId) 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

(37)

Purchase Amount

(PurchaseAmountInteger) 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 1250.

QSI Response Code

(QSIResponseCode) 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) The response code that is generated by the financial institution. This can vary between institutions. It is included for faultfinding purposes. Payment Server Transaction

Number (TransactionNo) 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.

Transaction Receipt Number

(ReceiptNo) 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

(AuthoriseId) A code issued by the acquiring payment processor to approve or reject a transaction. Transaction Batch Number

(BatchNo) The Batch number on the Payment Server that this transaction will be added to in order to be processed by the acquiring institution. Card Type (CardType) 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.

(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.