CommWeb - Payment Client Integration Guide (1)

7/25/2019 CommWeb - Payment Client Integration Guide (1)

1/133


2/133

CommWeb Payment Server Payment Client Integration Guide

Version 2.23 Commonwealth Bank of Australia 2

CommWeb Software Support Line1800 882 8889 am to 6 pm (Sydney time) Monday to Friday

Merchant detail configuration on the system Installation and integration support of the technology Testing and certification of your facility Day-to-day operations including Merchant Administration

password set-up and reactivation

Product enquiries Technical issues Changes to merchant details including addition of Amex and

Diners.

Merchant Enquiries 1800 230 177

9 am to 5 pm (Sydney time) Monday to Friday

Commonwealth Bank Merchant enquiries such as reconciliationof Visa and MasterCard transactions, settlement questions,billing enquiries, chargebacks.

Operations Help Desk 1800 022 966

24hrs, 7days a week

CommWeb connectivity issues (outages).


3/133



! "# $%"& ' $$

# ! ' $( )*& $(

# $+) $+,- . $+

# & # $/

+"# 0123 $/("# 0'3 (4

# & (5 1!! ) (5

'6 +%7- 8+%#! # )+%! 9, &, # 8 +$ ! ,: +(

; ++ +4' # & " +! < ; 4%

# & ! 4%! = #4%

'#! # # & 4$> . ! +"# 12 4(

?6 > . ! 4+? . & ! 4+

44.-# ) = 4@

& # & 1 , ! #

%/%: 4@& # ! , ' 4@ ! & -: 4@

)! & " 8 16: 4@ : 45 ' ): 45! ,! 8:4& ! ' ): 4


4/133



, , 0A3< '6< )B

4 !

# # & /% /$

! /(= /4

,# # //> ( # // // /5 /

> + # @ . @ 5+ 54 5/

)8 . %% %

$( ( (

'& & 9 ,# 9 ++

) . 4+"# 2 ) . 4("# 2 ) . / @ 5

)8 ' ) 0)')3 $%%

) & $%$ $%$ $%$ $%(

) $%/ $%/ $%/ $%@

) 9 & $% $% $% $$%

) 9 $$$ $$$ $$$ $$(

. 8 $$/ $$/ $$/

=# $$ $$


5/133



$$ $$

""# $ %& ' ( ""# $ ) * '"+ ,""# $ -)

& $+% & $+$

& '! $+(


6/133



& ! , ! +@! &! & 4%! 4$# & ,! 18 4& # & ! % A, ! ( . ) # @+" !

)') & . $%()') . $%/)') 9 & . $%)') 9 .$$()') =# . $$)') =# ! $$


7/133



! ' $% $$ . +"# 0123 $@ & +"# 0123 (% C ># & ! ($&, # 8; # ! ($&, # 8 # ! ((&, # 8 # ! ! ((&, # 8 ! (+ C ># ! (+ . ("# 0'3 (4# & ) (5! ! . +( . +5' ) 7! ' # & +# &8 . +12 . 4(

! /(' -# //+ # ! 5(+"# + . /("# + . /

)') & D8*& ?6 & ?6 $%4


8/133



This guide provides the details required to successfully integrate a

merchant application with the CommWeb Payment Client.It outlines the business logic around payment processing on theCommWeb Payment Server. It also contains detailed instructionson using the Payment Client to perform payment processing, andalso details on integrated administration functions.

It outlines the differences amongst the supported interfaces (Java,COM and Sockets) and provides Best Practice guidelines toensure error free integrations.

This guide is specifically aimed at business analysts andintegrators who want to effectively integrate the Payment Clientinto merchant applications.

This version of the CommWeb Payment Client Integration Guideis designed to be used with the CommWeb Payment ClientReference Manual, which details the input and output variables forall of the Payment Clients API methods.


9/133



This guide consists of the following sections:

Preface An introduction to CommWeb, and this guide.

e-Payments An overview of the different transaction types, 3-Party(SSL+) and 2-Party (MOTO) and when they should be used.

Payment Client

Interfaces

Describes the different interfaces of the Payment Client. Itoutlines its 3 native interfaces, Java, COM and Sockets; whatthey are, when to use them, and the advantages of eachinterface.

Best Practices Describes standard usage scenarios and recommends whatthe best method is to use the Payment Client.

Transaction Flows Details the steps to perform each transaction type and thedata flows involved.

Authentication Describes the implementation of MasterCard SecureCode and

Verified by Visa.

AMA Function

Calls

Describes the Advanced Merchant Administration functionswhich allow some administration tasks to be preformed viathe Payment Client.

If you need assistance with Payment Client Integration, please contact the CommWebSoftware Support Line on 1800 882 888


10/133



CommWeb enables a merchant to perform secure transactions over theInternet. To do this they need to integrate the Host Application (Shop andBuy application) with the CommWeb Payment Client.

The Payment Client is a back-end processing tool available to the HostApplication through an API (Application Program Interface). It interacts withthe CommWeb Payment Server, which processes secure transactions in real-time over the Internet.

Figure 1 demonstrates a view of a successful integration module:

Successful Integration Module

The Payment Client is a remote interface to the CommWeb Payment Server,which processes the secure transactions sent by the Payment Client.

The Payment Client provides formatting, encryption and digital signing ofDigital Orders from a merchants Shop and Buy application to the CommWebPayment Server. Digital Orders from the Payment Client provide informationto the CommWeb Payment Server to process the transaction by taking moneyfrom the customers card account (at the issuing institution) and placing thosefunds in the merchants account at the Commonwealth Bank.

After sending a transaction to the CommWeb Payment Server, the PaymentClient receives a signed and encrypted Digital Receipt. The Digital Receipt

provides a response for the transaction to the merchant to show whether thetransaction was successful or not.

The Payment Client supports a range of payment protocols using PaymentGateways, each offering different levels of security, payment risk and cost.

Host

Application

Integration

Module

CommWeb

PaymentClient

Card

Issuer

CommWeb

Payment

ServerH

ost

Application

Integration

Module

CommWeb

PaymentClient

Host

Application

Integration

Module

CommWeb

PaymentClient

Card

Issuer

CommWeb

Payment

Server

Card

Issuer

CommWeb

Payment

Server


11/133



! "

Merchant

Card Holder

Issuing Bank

Commonwealth Bank

1.

2.

3.

5.

4.

7.

6.

Real Time Batch

CommWeb

How a transaction is processed

During a transaction, the funds are transferred from the cardholders accountto the merchants account in the following steps:

1. The cardholder purchases goods or services from a merchant via the

internet, over the phone, etc.2. The merchant uses the Payment Client to connect with CommWeb,

which processes the transaction by switching the transactionauthorisation request to the card issuer (the customers bank) (3).

3. The card issuing institution adjusts the cardholders credit limit for thefunds and returns the result to CommWeb. CommWeb passes the resultof the transaction on to the merchant.

4. Commonwealth Bank settles the transaction with the issuing bank aspart of normal credit card processing.

5. The issuing bank adds an entry to the cardholders statement.

6. Commonwealth Bank deposits the funds into the merchants bankaccount.


12/133



#$!

Purchase Merchant

Purchase merchants capture funds from the customers card in a singletransaction and the funds are immediately transferred into the merchantsaccount when the acquiring institution processes the transaction. Eachinstance of a purchase transaction will show up on the customers cardstatement.

Auth /Capture Merchant (Pre Authorisation)

Note: Pre-Authorisation transactions are referenced in CommWeb asAuthorisation or Auth transactions.

Auth /Capture merchants perform at least two transactions to capture thefunds from the customers card and deposit them in the merchants account.

The Pre-Authorisation (Auth) transaction verifies that the card detailsare correct and will also reserve the funds for that merchant.

The capture transaction refers back to the initial authorisationtransaction, and instructs the transfer the funds from a customers cardinto the merchants account.

The merchant can perform more than one capture transaction, for example themerchant may not have the full ordered amount of goods in stock but shipswhat they do have. Later, when they ship the remaining goods the merchantcan perform another capture transaction that refers back to the initial

authorisation transaction which transfers the remaining funds to themerchants account.


13/133



#

Note: Pre-Authorisation transactions are referenced in CommWeb as

Authorisation or Auth transactions.

The full amount of the goods or service is sent to the card issuing institutionto verify that the funds are available in the customers card account. Thefunds are reserved (and the credit limit adjusted) until captured by themerchant and transferred to the merchants account.The auth transaction reserves the funds for a predetermined period of time asdetermined by the issuing bank.

Auth/Capture This is the standard Auth/Capture mode where the fullamount of the goods or service is sent through to the card issuinginstitution to verify the details against the customers card account.Funds are not debited against the card with this auth transaction;

however they are reserved against the customers account, ready for thecapture transaction to debit the card when the time comes to transfer thefunds to the merchants account.

This auth reservation of funds will reserve the funds for a predeterminedperiod of time, (such as 5 days), as determined by the issuing bank.

%& '

For every order there is normally one shopping transaction. Each shoppingtransaction may require a number of associated financial transactions, for

example, capturesand refunds. Financial transactions represent the flow ofinformation between the customer, the merchant and the bank whenpurchasing goods and services.

Subsequent transactions can be void, capture or refund transactions.

Voidedtransactions cancel the settlement portion of the transaction, so themerchant does not get paid and the cardholder never sees the transaction ontheir statement. However, voided transactions on CommWeb do not readjustthe cardholders credit limit adjustment. Voids can only be done beforeCommWeb sends the transaction to the issuing bank at end-of-day settlement.If the transaction has already been sent, the merchant will need to perform a

refund. The cut-off time for the days transactions in CommWeb isapproximately 17.30 EST. Once cut-over is performed, transactions doneprior to this time cannot be voided.

Refunds are where the merchant re-credits funds back to a customers card. Inthis case both transactions are listed on the cardholders statement.

The merchant can perform as many capture and refund transactions as theywant providing the total amount captured does not exceed the original authtransaction. You must have captured the funds before you can perform a


14/133



refund (i.e. the original transaction was a purchase or an authorisedtransaction that has been captured), otherwise an error will occur.


15/133



There are two transaction styles used by the Payment Client:

2-Party Mail Order Telephone Order (MOTO)Used for any merchant application, such as a merchant web shop & buyapplication or a call centre operation, where the merchant collects thecard details. In this mode the merchant controls the display of thepayment pages and can brand the pages with their own style.

3-Party Secure Socket Layer (SSL+)Only possible from a web application, such as a merchant shop & buyapplication or e-mail, as the customer can only input their credit detailsdirect to CommWeb via a web page that is displayed from theCommWeb server. The pages displayed will be branded by theCommonwealth Bank, but will reference the merchant name.

( )*+,

3-Party transactions use the SSL protocol to provide secure transmission ofsensitive data between a customers web browser and the CommWebPayment Server. In addition to SSL channel encryption, the Payment Clientencrypts transaction data sent from the shop and buy application to theCommWeb Payment Server to prevent alteration in transit as it is redirectedvia the customers browser.

The SSL+ Gateway uses 3-Party messaging and the three parties are thecustomer, merchant and CommWeb.

One of the benefits of a 3-Party (SSL+) transaction is that the merchant does

not carry the legal responsibility of having to secure card details from hackersand misuse.


16/133



! "

Information Flow in 3-Party (SSL+)

1. A customer anddecides to purchase goods and enter details intothe merchants shop and buy application software at the checkout page.

2. The customer pays for the goods and the merchant software sends anencrypted Digital Order to the CommWeb Payment Server.

3. The CommWeb Payment Server receives the customers card detailsand displays a series of screens. The first screen (see page 21) displays the

cards supported by the merchant, for example MasterCard, Visa, andAmerican Express. The customer chooses the card type they want to usefor the transaction. The second screen accepts the details for the chosencard such as card number, card expiry, a card security number if required,see page 22.

4. The CommWeb Payment Server passes the details directlyto the cardissuing institution. When the payment has been processed, theCommWeb Payment Server temporarily displays the result of thetransaction before displaying the final screen, which asks the customer toplease wait while they are redirected back to the merchants site (see page23) and the CommWeb Payment Server passes an encrypted Digital

Receipt back to the merchants site detailing the result of thetransaction. This information is then passed back to the user for theirrecords(see page 23).

The CommWeb Payment Client constructs and sends an encrypted DigitalOrder to the CommWeb Payment Server, and then decodes the encryptedDigital Receipt from the CommWeb Payment Server via browser redirects.

In a 3-Party transaction, the customers browser connection is completely


17/133



severed from the merchant application, so any session variables that arerequired to identify the current session must be collected and sent to theCommWeb Payment Server, where they are returned appended to theencrypted Digital Receipt.

For information on the method used to send the session variables, please referto page 31.


18/133



+"# !

3-Party transactions require two separate operations:

Creating and sending the Digital Order.

Receiving the Digital Receipt and decrypting it and returning theindividual receipt details back to the merchant software.

' % . / 0

1. Echo test to check if the shop and buy application can connect to thePayment Client.

2. Add any additional data fields. These values are sent prior to a primarycommand (getDigitalOrder) using add extra data commands (calledaddDigitalOrderField). These extra data commands are detailed laterin the document.

3. Get the encrypted Digital Order and use a browser redirect to send it tothe CommWeb Payment Server via the customers browser.

() . / ("

1. The encrypted Digital Receipt is sent by the CommWeb Payment Servervia the customers browser, and an echo test is performed to check if theshop and buy application can connect to the Payment Client.

1. Decrypt the Digital Receipt using the Payment Client.

2. Check if there is a valid receipt result.

3. Get the individual receipt results.

The basic inputs necessary for a 3-Party transaction are:

MerchantId The merchant account at CommWeb. This is different toyour Commonwealth Bank number.

MerchTxnRef Identifies this particular transaction on the CommWebPayment Server. This is a unique value for each transaction. For moreinformation, please refer to page 30.

Amount The value of this transaction. It is an integer that expressesthe amount in the lowest currency denomination, for example cents andpence.

Locale Identifies the language used on the CommWeb PaymentServer screens. English is the only supported language.

ReturnURL The merchant page which the CommWeb PaymentServer redirects the customers browser, at the end of the transaction.

These inputs are sent together in the one primary Payment Client commandgetDigitalOrder.


19/133



1. . '. %

In a 3-Party (SSL+) transaction the cardholder is presented with six pages:

1. The shop and buys checkout page

2. The CommWeb Payment Servers Payment Options page

3. The CommWeb Payment Servers Payment Details page

4. The CommWeb Payment Servers Payment Pending page

5. The CommWeb Payment Servers Redirection page

6. The shop and buys receipt page.

Examples of these pages are shown in the following pages.


20/133



What the Customer sees in a 3-Party (SSL+) transaction.


21/133



. %." 2 * '.&*

The checkout page displays the line items that the customer wants to purchaseand the total amount to pay, including any delivery charges and taxes. Thecustomer accepts the amount and proceeds to the CommWeb payment pages

to enter their card details.

The Shop & Buy Check Out Page

'1+ %)3 0"

The payment options page presents the customer with the card types the

merchant accepts. The customer clicks a card type and proceeds to thePayment Details page.

CommWeb Payment Servers Payment Options Page


22/133



. '1+ %)3 /

On the Payment Details page, the customer enters their card details, includingthe card number, expiry date, card security code (CVC2/CVV2), and clicksthe pay button. CommWeb then processes the payment.

CommWeb Payment Servers Payment Details Page

. '1+ %)

As CommWeb is processing the payment, a payment pending page can bedisplayed to the customer.

CommWeb Payment Servers Payment Pending Page


23/133



. '1+ %)3 (

The redirection page is displayed in the customers browser and the DigitalReceipt is passed to the merchants shop and buy application

CommWeb Payment Servers Receipt Page

. . %." 2 *3 ("

The shop and buy receives the Digital Order and creates a Digital Receipt as areceipt page is displayed to the customer.

The Shop & Buy Receipt Page


24/133



- )",

2-Party transactions are purchase/auth transactions orders where the customerprovides their card details to a merchant, via mail order or by telephone on acall centre or financial application.

The customer provides their payment details (card type, card number and

expiry date) directly to the merchant.

MOTO transactions carry a higher risk than SSL+, as the customers carddetails are captured and stored by the merchant.

The MOTO Gateway uses 2-Party messaging and the two parties are themerchant and CommWeb.

Information Flow in 2-Party (MOTO)

("# 0'3 .

7. A customer ,purchases goods or services.

8. The merchant collects the card details using the Internet, IVR, mailorder or telephone order and submits the details to be processed via thePayment Client.

9. The Payment Client generates an encrypted Digital Order and sends itover the Internet to the CommWeb Payment Server. The Digital Orderincludes the purchase amount, card details (submitted to the merchant),and a merchant-specified transaction reference.

10.The issuing bank processes the information and passes the result back to


25/133



the CommWeb Payment Server, which forms an encrypted DigitalReceipt. This receipt, which includes the transaction results andpayment reference details, is sent from the CommWeb Payment Serverback to the Payment Clientwhere it is decrypted. The decryptedresults are sent back to the merchantand stored for future reference. Areceipt is also passed back to the customer for their records.

11. A 2-Party transaction is a multi command function that uses the followingcommands:

12.Echo test to check if the shop and buy application has access to thePayment Client.

13.Add additional data fields like Card Number and Card Expiry to thetransaction.

14.Send the Digital Order.

15.Check if there is a receipt result.

16.Get the individual receipt results

The basic inputs used for a 2-Party transaction are:

CardNumber The card number or the customer. CardExpiry The expiry date of the card.

MerchantId The merchant identifier allocated by CommWeb. This isdifferent to your Commonwealth Bank number.

MerchTxnRef Identifies this particular transaction on the CommWebPayment Server. This should be a unique value for each transactionattempt, which makes it easy for the merchant to track transactions.

Amount Contains the value of this transaction. It is an integer thatexpresses the value in the lowest currency denomination, for example,cents, pence and yen.

In a 2-Party transaction, session variables are not sent to the CommWebPayment Server because the merchants session is always maintained.

&

In a 2-Party transaction the cardholder is presented with two pages:

1. The merchants shop and buy checkout page.

2. The merchants shop and buy receipt page.

The CommWeb Payment Server does not display any pages in a 2-Party styletransaction, as all pages are displayed by the merchants application.


26/133



#

("# #

Other 2-Party transactions are:

Captures

Refunds.

2-Party transaction types can be performed in two ways:

1. Manually through Merchant Administration, which is an Internetbrowser-based application implemented by the CommWeb Payment

Server. For more information, please refer to the MerchantAdministration User Guide.

2. Advanced Merchant Administration (AMA) transactions - using thePayment Client to directly access the CommWeb Payment Servertoperform all transaction-related actions (for example, refunds, andcaptures) integrated with the merchants own payment softwareinterfaces.

Advanced Merchant Administration is used with your merchant application.

Administration methods typically return a single result that contains one or

more fields. These fields are detailed in the Payment Client ReferenceManual.

The various commands available in AMA are outlined in detail later in thisguide.


27/133


I #

!

The Payment Client is normally installed at the merchants site, if their WebSite is self hosted, or the merchants Internet Service Provider (ISP), whichprovides encryption, security, and interface services to the merchants shopand buy application.

The merchants shop and buy application can integrate to the Payment Clientusing one or more of the following interfaces:

Java- running under Windows NT, 2000 or UNIX.

TCP/IP Sockets- running under Windows NT, 2000 or UNIX.

COM- running under Windows NT or 2000.

Each interface can process payments to each different Payment Gateway, forexample, SSL+ and MOTO, if the merchant is licensed to do so by theCommonwealth Bank. You can install as many of these interfaces asnecessary.

Payment Client Architecture

* #

The most common languages used for integrating the Payment Client areJava, VBA and Perl, but any language that supportssockets can be used, as the Payment Client APIs areavailable through its sockets interface.

D8 )

Java is the native language of the Payment Clientand allows you to call the Payment Client Classesdirectly from the application running on the same

SocketsPerl/CGI

PaymentClient

Java

COM

Java

ASP

MerchantApp

lication

Host Server

HostApplication

JVM

CommWeb

PaymentClient

Host Server

HostApplication

JVM

CommWeb

PaymentClient


28/133



Java Virtual Machine (JVM). Java is Operating System (OS) independent, butthe Java implementation that communicates with the Payment Client must belocated on the same host as the Payment Client. Although this architectureprovides OS independence and an object orientated interface, it does notallow a distributed and scaleable architecture.

&' )The COM interface is registered on the localPayment Client machine and is available forloading and calling Payment Client APIcommands. It is operating system dependent andthe OS you use must support COM, for examplemost Microsoft based operating systems. COMallows for an object orientated interaction with thePayment Client and the portion of the COMimplementation that communicates with thePayment Client must be located on the same host

as the Payment Client. It also does not allow for adistributed and scaleable architecture.

)

Sockets API is preferred if scalability andflexibility are major concerns. It allows thePayment Client to be located on any hostmachine (as long as it is capable of supportingJava and TCP/IP Sockets) with a listeningservice attached to a port on that machine. Itallows multiple Payment Clients to be set up onone or multiple hosts as each Payment Client isassigned to a port. To use a different PaymentClient you need to change the host name and/orthe port address you communicate to. Becausemultiple hosts can be installed with multiplePayment Clients, this offers far greater flexibilityand scalability to cope with future transactionalloads. This provides the sockets implementationwith a stronger operating system independence than either of the previoustwo architectures, Java and COM. However as socket commands areprimarily string commands being sent to a socket, the object orientatedapproach to a direct interaction with the Payment Client cannot be fully

implemented.

Host Server

HostApplication

MicrosoftCOM

MIGSPayment

Client

OperatingSystem

MicrosoftCOM

Host Server

HostApplication

MicrosoftCOM

CommWeb

PaymentClient

OperatingSystem

MicrosoftCOM

Host Server

HostApplication

MicrosoftCOM

MIGSPayment

Client

OperatingSystem

MicrosoftCOM

Host Server

HostApplication

MicrosoftCOM

CommWeb

PaymentClient

OperatingSystem

MicrosoftCOM

Host Application Environment

Payment Client Server

SocketListeningService

JVM

MIGSPayment

Client

Host ApplicationIntegration toQSI SocketInterface

OperatingSystem




JVM

CommWeb

PaymentClient

Host ApplicationIntegration to

CommWeb SocketInterface

OperatingSystem




JVM

MIGSPayment

Client

Host ApplicationIntegration toQSI SocketInterface

OperatingSystem




JVM

CommWeb

PaymentClient

Host ApplicationIntegration to

CommWeb SocketInterface

OperatingSystem


29/133



E

#

MOTO requires the customers card details to be stored on themerchants terminal, so it is not as secure as SSL+, where the merchantdoes not have contact with the customers card details.

SSL+ provides added security by directly linking the customersbrowser with the CommWeb Payment Server to pass the encryptedDigital Order.

The Java interface is native to the Payment Client, so provides thestrongest communication between the merchant and customer. Thecommunication is between java classes, and it is very difficult for ahacker to get between the classes.

Security is strongest in Java, as the code is compiled. Only the classes

are available after implementation as the code is removed from thesystem. The compiled classes would require de-compilation before itcould be viewed and changed.

COM cannot be accessed remotely which means that it is secure (remoteaccess can be implemented using DCOM).

The sockets interface sends data as plain text to the Payment Client, soall communications using sockets should be secured behind firewalls.This ensures that operator names and passwords in MerchantAdministration are inaccessible from the data stream.


30/133


.

"/

0& 1

MerchantTxnRef is normally used for querying an exact transaction on theCommWeb Payment Server. In a case where the merchant requires to knowthe specific result of a transaction, for example, when a Digitial Receipt is notreceived by the merchant, then the MerchantTxnRef is used to locate thedetails.

Although CommWeb allows any reference to be entered with a shopping

transaction, it is advised that some unique identifier is used by the merchantto allow an easy cross-reference with the merchants host system. A exampleof a MerchTxnRef would be the merchants unique order number assigned toeach sale. This allows the merchant to look up the transaction on CommWebwith the same reference used to lookup the transaction on their own hostsystem. To guarantee uniqueness, different payment operations on the samesale need also to be identified, as stated below.

#

If a transaction for a sale is declined, and a subsequent attempt is made toprocess a payment for this sale, the merchant should modify the

MerchTxnRef for each subsequent attempt, by appending extra characters foreach attempt. For exampleMerchTxnRef= 1234/1 on first attempt,1234/2 on second attempt, and 1234/3 on third attempt, etc. This is thepreferred way of implementing a uniqueMerchTxnRef. Because under afault condition, such as if the Digital Receipt does not arrive back at themerchants site, you may need to check if the transaction was carried outsuccessfully.

Automated lookups and financial operations cannot be performed if themerchant has not given each transaction attempt a uniqueMerchTxnRefnumber, as there will be multiple results showing the sameMerchTxnRef.


31/133



2% !% 1

In a 3-Party transaction, the customer browsers connection is completelysevered from the merchant application. Some merchant applications usesession variables to keep track of where the shop and buy application is up to

and to prevent unauthorised entry without the customer signing in. This stopshackers from spoofing transactions.

Session variables that are required to identify the current session so theCommWeb Payment Server can return to the merchants program from whereit left, must be collected and sent to the CommWeb Payment Server. Thesession variables are not used by the CommWeb Payment Server, but arereturned appended to the Encrypted Digital Receipt. There can be as manysession variables as required using any name the merchant shop and buyapplication needs, providing they legally conform to HTTP/HTTPS protocols.To make them conform to the standard, URL, you need to encode all sessionvariables before sending them.

To send them to the CommWeb Payment Server the merchant must appendthem to the merchant ReturnURL, where they are encrypted by the PaymentClient and sent as part of the Digital Order:

ReturnURL=http://

migs.mastercard.com.au/servlet/ReceiptServlet?DR=${D

R}&SessionVariable1=1234&SessionVariable2=8901

When encrypted the Digital Order becomes:

https://migs.mastercard.com.au/pay?DO=OItlAg06jzyWcE

z*N5gdjPK7Ds9lpbYpOU84413tiTbH3akP.yMsmT*.p9edWoobMo

g74eVJYiCWVxo5yjluIgPHtjt0F0URC7SeucZM.WMGdiNgzUvTCB

4RCZu*.jIzdu2O2P1iEErTCinpZVuYyaydF6yCTVG.DkIOXi*qtYHWXzUsCm1Vh168yY6NBQkjgYuEvTaUUDvWiBWwS9rjopgPA94xoE

*RawO.stRe8bTTPCh0W0RiupP2MekWqfyAWwluag7Y9.w95y07fg

FFqQvRLYALmAz.tFEv.8*5I47yONI*fYOpHzyzRgzEFDQZ18

The ReturnURL is encrypted into the Digital Order, which is sent to theCommWeb Payment Server using a customers browser redirect.

At the CommWeb Payment Server, the merchant session variables arerecovered and temporarily stored in the CommWeb Payment Server with theother transaction variables. They are sent back to the Payment Clientappended to the Digital Receipt at the completion of the transaction.

When encrypted the Digital Receipt is returned via a customers browserredirect, it looks something like:

DR=http://demo.payments.com/servlet/ReceiptServlet?D

R=p9edWoobMog74eVJYiCWVxo5yjluKIgPHtjt0F0URC7SeucZM.

WMGdiNgzUvTCB4RCZu*Fuv866UJbXVlqZr1MSJeeOnXlVWTsVUXx

y374VNWGCv6Q7g*ZGTjN9kJhKsFJ0ZDsHDj6IQnVt7O.YiXl0Yz*

OUzfBeP.jIzdu2O2P1iEErTCinpZVuYyaydF6yCTVG.DkIOXi*qt

YHWXzUsCm1Vh168yY6NBQkjgYuEvTaUUDvWiBWwS9rjopgPA94xo

E*RawO.stRe8RA.KIDmi6sVn5H1DGX.t2d8.BwJABcdSFP5gVFok


32/133



8wUm0W0RiupP2MekWqfyAWwluag7Y9&SessionVariable1=1234

&SessionVariable2=8901

This helps the merchant shop and buy application recover the sessionvariables from the encrypted Digital Receipt URL, and use them to restore themerchant session. The session continues as though it had never been broken.Once the encrypted Digital Receipt is decrypted, all the receipt details can becaptured from the Payment Client.

%3

The two ways of dealing with a digital receipt that fails to come back are:

Flag the transaction as having an error that the merchant needs tomanually check using Merchant Administration on the Payment Server.

Utilise Advanced Merchant Administration (AMA) commands to searchthe Payment Server database for the transaction by using the QueryDRcommand ifMerchTxnRefis unknown. TheMerchTxnRefis used as

the transaction identifier when searching using QueryDR.Because the Digital receipt has failed to come back, there is no transactionnumber available from the Payment Server to identify the transaction inquestion, and this is why you use theMerchTxnRef. It is important to have auniqueMerchTxnReffor every transaction otherwise the query could returnmultiple results. Only the most recent transaction is returned in the QueryDRcommand if there are multiple results, but this may not be the transaction youare looking for.

Diagram Showing Information Flow


33/133



When you find the requiredMerchTxnRefin the QueryDR, check if it issuccessful by the QSIResponseCodefield (equal to 0). If theQSIResponseCodeis zero, then the transaction is successful and you justneed to extract the relevant data details from the QueryDRresults for yourrecords. If the QSIResponseCodeis not 0, you need to determine the nextcourse of action based on what you would do if the QSIResponseCodewere

not 0 in a normal digital receipt coming back from the Payment Server.

If you query the Payment Server for theMerchTxnRefusing the QueryDRcall and you do not receive any results, then it is safe to repeat the transaction.It is safe to use the sameMerchTxnRef, as the existing one does not show upin the Payment Servers database.

If the QueryDR is flagged as having multiple results (returns Y in theMultipleResults field), the MerchTxnRef is not unique.

4

The Payment Client contains a socket listener application,PaymentClient.PCService, which can be started and run in thebackground. Sockets work by the merchant sending a command messagestring, with each string starting with a number and followed by data. Thenumber 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 turnsends back a response.

The related commands for the sockets interface are shown in Appendix 1.

This response consists of two fields separated by a comma, for example0,0or 1,echo:Test. The first field will always be either a status digit of a0 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 tothe Payment Client was successful.

The second field is the data field. Failed transactions would not return anydata and the responses are 0,0. Many commands like sending the cardnumber do not return any data from the Payment Client so they have asuccessful response of 1,1.

Other successful responses to a socket command that do send back data, suchas the echo command, will have a status response of 1, followed by thereturn data, for example echo:Test the full response becoming1,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 thePayment Client after sending a command. This allows the shop and buyapplication to detect possible failures in the payment process. If the sockettimes out it must be actioned or it will result in either a duplicate transaction.For more information, please refer to the Best Practices section.


34/133



Note:

In each of the socket example commands shown in this guide, the \nNew 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 \rat the end causes the socket command to fail.

Some programming languages such as ASP can automatically add this tothe end of the command so the programmer does not have to include it.

Warning:

Thedatafor any socket command cannot contain either a New Line (ASCII010DEC) or a Carriage Return (ASCII 013DEC) character. The comma ,character (ASCII 044DEC) is also prohibited from the data field.

If a data field contains any of these characters, the field data should be parsedto remove these characters before including it in the socket command. Failureto do so will cause the transaction to fail, as the socket listener willprematurely see the end of that command, and not receive all the requireddata.

For a full list of socket commands, see the Payment Client Reference Manual.

In most applications like ASP and Java, the sockets are set-up with a sockettime-out value, for example:' Open a socket connection to the Payment Client

socketPayClient.TimeOut = 200000 ' 200 seconds

socketPayClient.Host = payClientIP & ":" & payClientPort

Java uses a setSoTimeout(int timeout)command to enable or disableSO_TIMEOUT with the specified timeout, (this timeout value is inmilliseconds). If the setSoTimeout option is set to a non-zero timeout, a

read() call on the Input Stream associated with this socket will block for onlythe designated amount of time. A timeout of zero (0) is interpreted as aninfinite timeout so the socket will never timeout.

If the timeout expires, a java.io.InterruptedIOExceptionis raised, thoughthe Socket is still valid. The option must be enabled prior to entering theblocking operation for it to take effect and the timeout must be > 0.

The setSoTimeout value determines how long the socket waits for a responsefrom the Payment Client after sending a command. This allows the shop and


35/133



buy application to detect possible failures in the payment process.

If the setSoTimeout period is reduced to a lower value, for example 10seconds, then under times of heavy load on the CommWeb Payment Serverthis short timeout period may be exceeded. The time out would normallyoccur on processing messages like sending a MOTO Digital Order, whichtake time for the CommWeb Payment Server to process. The message istransmitted to the CommWeb Payment Server, where it is processedsuccessfully, but the successful response of 1,1 may take longer to arriveback at the socket than the socket time out period allows. So the data remainsin the Payment Client buffer waiting for transmittal to the application. If thetime 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 fortransmittal 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 Javato input a Line Feed character to indicate the end of the command.

Failure to include this character or a Carriage Return character Java \rat the end causes the socket command to fail.

Some programming languages such as ASP can automatically add this tothe 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 outprematurely, but if the socket does time out, it needs to be detected and notcontinue with the next step of the transaction. If the shop and buy application

continues and process the next command, then all future responses aredisplaced.


36/133



CommWeb Socket Information Flow(MOTO)

Good Transaction

CommWeb Socket Information Flow(MOTO)

Bad TransactionSent Received

1,Test\n 1,echo:Test

translates toecho("Test") command in Payment Client

7,CardNum,5123456789012346\n 1,1addDigitalOrderField("CardNum")command

7,CardExp,0202\n 1,1addDigitalOrderField("CardExpiry")command

7,ticketNo,Some data for transaction\n 1,1addDigitalOrderField("Ticket")command

6,1234,Test2008,100,en,\n 1,1sendMOTODigitalOrder("1234", "Test2008", "100", "en", "")

5\n 1,1nextResult()command

4,DigitalReceipt.QSIResponseCode\n 1,0 *objPayClient.getResultField("DigitalReceipt.QSIResponseCode")

4,DigitalReceipt.TransactionNo\n 1,271objPayClient.getResultField("DigitalReceipt.TransactionNo")

4,DigitalReceipt.ReceiptNo\n 1,01102502objPayClient.getResultField("DigitalReceipt.ReceiptNo")

* A QSIResponse Code of 0 indicates a successful transaction.

Sent Received

1,Test\n 1,echo:Test

translates toecho("Test") command in Payment Client7,CardNum,5123456789012346\n 1,1addDigitalOrderField("CardNum")command

7,CardExp,0202\n 1,1addDigitalOrderField("CardExpiry")command

7,ticketNo, Some data for transaction\n 1,1addDigitalOrderField("Ticket")command

6,1234,Test2008,100,en,\n # $ sendMOTODigitalOrder("1234", " Test2008", "100", "en", "")

5\n 1,1(From 6,1234,Test2008, etc.)nextResult()command

4,DigitalReceipt.QSIResponseCode\n 1,1 (From 5,null,) Error Response*objPayClient.getResultField("DigitalReceipt.QSIResponseCode")

4,DigitalReceipt.TransactionNo\n 1,0 (From 4, QSIRespCode,)objPayClient.getResultField("DigitalReceipt.TransactionNo")

4,DigitalReceipt.ReceiptNo\n 1,271 (From 4, TxNo,)objPayClient.getResultField("DigitalReceipt.ReceiptNo")

* A QSIResponse Code of 1 indicates transaction failed

Comparison of a good transaction and a bad transaction where the timeout is ignored.

The commands for the sockets interface are shown in Appendix 1.

If the time out is not detected and the transaction continues, the data returnedis incorrect for each of the next commands that are sent.

The result of not detecting and handling the time out is that a successfultransaction has been conducted but the shop and buy application will interpret

the transaction as a failure.

The response from the command 5\n is 1,1,which is a good response but it is actually from the

sendMOTODigitalOrdercommand (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 completedsuccessfully, but it is delayed one command so it is lost. One of thecommon responses to this is to have the shop and buy application redothe 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,271which shows up as a Receipt No of 271, which is incorrect, but thisresponse is from the 4,DigitalReceipt.TransactionNo\n command. Thereal Receipt No of 01102502 is lost from the transaction stream.


37/133



If the transaction has been successfully processed by the CommWeb PaymentServer, and the transaction is repeated it would result in a duplicatetransaction.

If a socket time out occurs, do not ignore the time out, as it will only causeerrors.

There are two ways of dealing with a time out:3. Flag the transaction as having an error that needs to be manually

checked using Merchant Administration on the Payment Server. Youneed to determine what to send back to the cardholder while this manualcheck is performed, as it could be a good transaction.

4. Close the socket and open a new socket connection and use AdvancedMerchant Administration commands to search the Payment Serverdatabase for the transaction. The QueryDRcommand can be used tosearch the Payment Server using theMerchTxnRefas the transactionidentifier. At this stage there is no transaction number available backfrom the Payment Server to identify the transaction, so it is important

to have a uniqueMerchTxnReffor every transaction.

Information Flow for a Socket Timeout

When you find the requiredMerchTxnRefin the QueryDR, check if it issuccessful by the QSIResponseCodefield (equal to 0). IfQSIResponseCodeis zero, then the transaction is successful and you just


38/133



need to extract the relevant data details from the QueryDRresults for yourrecords. If the QSIResponseCodeis not 0, you need to determine the nextcourse of action based on what you would do if the QSIResponseCodewerenot 0 in a normal digital receipt coming back from the Payment Server.

If you query the Payment Server for theMerchTxnRefusing the QueryDRcall and you do not receive any results, then it is safe to repeat the transaction.It is safe to use the sameMerchTxnRef, as the existing one does not show upin the Payment Servers database.

If the QueryDR is flagged as having multiple results (returns Y in theMultipleResults field), the MerchTxnRef is not unique.

Completing the above process is better than repeating the transaction, andperhaps having to do a refund. For large value transactions, double processingbecomes expensive.

While you are determining the status of the transaction, you could display anerror message to the customer, and the system is currently verifying thetransaction.


39/133



Each Payment Client can only talk to one CommWeb Payment Server usingthe merchants assigned CommWeb MerchantID. The Payment Client keys

must match the CommWeb Payment Server keys for the suppliedMerchantID, but you can run multiple Payment Clients, on separate hardware,for redundancy. This can be easily achieved by having the merchantapplication switch between the multiple Payment Clients using the socketsinterface to each Payment Client. Each Payment Client listens on its ownsocket.

Merchant Application Using Multiple Payment Clients

However, the Payment Client does not come standard with the ability tooperate on a remote machine or have multiple instances of the Payment Clientrunning, each listening on a different port. There is a patch that is available toperform this function.

With the patch installed, thePCService.propertiesfile in each PaymentClientconfigsubdirectory then tells the Payment Client what port to listenon, for example

[CommWeb]

port=9051

ipNumber1=127.0.0.1

ipNumber2=192.168.20.10

ipNumber3=192.168.20.11

threads=10

Typical PCService.properties File

The properties file determines which machines can communicate with thePayment Client. The IP address of the machine sending the Payment Clientdata must be included in this file. If it is not, the socket cannot communicatewith the Payment Client, as it will refuse the connection. This is a safeguardto prevent unauthorised machines from communicating with the PaymentClient.

MerchantApplication

Payment Client 1 onMachine 1

Payment Client 2 on

Machine 2

To CommWeb

To CommWeb

Via the Internet

Merchant Firewall

Applications and Payment Clients on

separate machines


40/133



$ % !&

!

The port, threads and IPs are set within the file PCService.properties withinthe directory \QSIPayments\PaymentClient\config\ and edit the file.

Commands Description

port=9050Port number of the socket when initiated,default 9050

ipNumber1=127.0.0.1The first IP number that is allowed toaccess the socket. 127.0.0.1 is thelocalhost machine.

ipNumberN=xxx.xxx.xxx.xxxOther IP addresses that are allowed toaccess the socket. N represents an

incremental number starting from 2.

threads=10

Maximum number of connections thatcan connect to the socket interface. Thiscan be increased or decreased from thedefault, but experience has shown 10threads will cover nearly all applications.

Setting Configuration Data Initial PC

'! (

The QSI.properties file can be found in the\QSIPayments\PaymentClient\classes\ directory. Edit the QSIRoot value tothe following :

QSIRoot=c:\QSIPayments


41/133



" 5 !

Within the directory \QSIPayments\PaymentClient\config, locate your keyfiles qsi.3 and qsi.4. These are the critical files for the payment client andshould never be changed, unless instructed to by your bank due to a keychange on the CommWeb server, or due to a setup of a new account for themerchant.

You do not need to modify the file setup.propertieswithin this samedirectory to point to the new CommWeb Payment Server. You can use eitherthe CommWeb Payment Server host name or its IP address.

Command File setup.properties Description

for exampleTargetURL=https://migs.mastercard.com.au/

Modify the TargetURL toreflect the server name.

Setting setup.properties Data

Each Payment Client is started from a command line window from within thePayment Client classes subdirectory by inputting javaPaymentClient.PCService,orby starting it as a service.


42/133



. ' ( *+

SSL+ Transaction Flow


43/133



)* + " ,

The best practice flow diagram shows how to create a payment-enabled shopand buy application.

6 ' !

1. The shopping cart is stored in a database while the transaction is beingprocessed, to keep a record of the data. During the transaction theconnection to the customer is unlinked [recall the redirection] so thedata needs to be stored. If the data is lost then the transaction cannot beprocessed. Two boolean flags, CHECKED_OUT andWAITING_FOR_DR,are stored on the server with the shopping cart record.

2. The flag, CHECKED_OUT, checks whether the shopping cart already hasa payment attempt in progress:a. FALSE Payment Not Attemptedb. TRUE Payment Process Started.

If 'Payment Not Attempted'continue to the next step, otherwise go to step

17.

3. Set the CHECKED_OUTflag to TRUE to indicate the start of the paymentprocess.

4. Create the Digital Order.

5. Set the boolean flag WAITING_FOR_DRto TRUE to indicate that the

software is waiting for a Digital Receipt for this order.

6. Send the Digital Order to the CommWeb Payment Server using a

browser redirect.

Note:

The merchant shop and buy application transfers the connection to theCommWeb Payment Server which sends the Digital Receipt using thecustomer browser to the merchant web site static URL specified inMerchant Administration, or by the dynamically constructed Return URLspecified in the Digital Order.

For static URLs, the MerchTxnRef identifies the customer session andshopping cart.

For dynamic URLs, any additional session variables that are required toallow the CommWeb Payment Server to return to the same session should

be appended to the Return URL. These are encrypted as part of the DigitalOrder and returned as parameters appended to the encoded Digital Receipt.

7. Wait for the Digital Receipt to be returned via a browser redirect fromthe CommWeb Payment Server. Pass the Digital Receipt to the PaymentClient and retrieve and store the results. Set WAITING_FOR_DRtoFALSE for this order.

8. The Digital Receipt is returned to the merchant software via a browserredirect.


44/133



9. Check the WAITING_FOR_DRflag. If FALSE the DR has already beenreceived. Therefore this is a retry delivery of a Digital Receipt, go to 27and display the receipt details. If TRUE, continue.

10.Store the Digital Receipt values in the database.

11.Set the WAITING_FOR_DRflag to FALSE to indicate the Digital Receipthas been received.

12.Check if the CANCELLEDFlag set. If FALSE, continue, otherwise go tostep 28.

13.Check if the transaction was successful. This is indicated by aQSIResponseCode value of zero.

If the QSIResponseCodeis not zero then go to step 30, otherwisecontinue.

14.Process the order as Paid.

15.Display the receipt details to the customer.

16.Finish.

%

If the customer attempts a second payment on one order or clicks Back buttonin the browser while transaction is being processed.

If the CHECKED_OUTflag is set.

1. The customer arrives here if they attempt to enter the pay process twicefor the same order.

If the WAITING_FOR_DRflag is TRUE then go to step 20, otherwisecontinue.

2. Check if the transaction was successful. This is indicated by aQSIResponseCodevalue of zero.

If QSIResponseCode is not zero then go to step 24, otherwise continue.

3. Re-display the receipt details.

Finish process on 16.

4. Display a warning message about the risk of a duplicate transaction ifthe customer keeps proceeding.

5. The customer has already checked out a transaction but the merchant

system has not received a Digital Receipt. Determine if the customerwants to keep proceeding.

If the customer wishes to proceed then continue, otherwise go to step 23.

6. Set the CANCELLEDflag for this transaction and restart a newtransaction at operation 1 by storing the shopping cart in the databasewith a newMerchTxnRefnumber according to the instruction inoperation 1.


45/133



7. Display merchant contact details and continue waiting for the DigitalReceipt at 17.

Waiting for Digital Receipt

8. If the number of retries for the payment are exceeded then continue,otherwise go to 26.

9. Display a message indicating that no further attempts will be permittedfor this order.


10. If the retry limit is not exceeded then increment the retry counter andassign a new order number according to the instruction in operation 1,and go to step 4.

Create new order from operation 4 onwards.

' ! 8 ,:

11.Check if the transaction number is the same as the one previouslyreceived for this order.

If the transaction number is the same, continue, otherwise go to step 29.

12.Cancel the duplicate successful transaction with CommWeb. The actualcancellation can be performed through any CommWeb process, forexample MA or AMA. This operation is where an automaticcancellation would occur or notification generated for a manual processto begin. Only cancel the transaction if there is more than one successfultransaction for this order.

13.Display the receipt details for the current transaction based on the

original Digital Receipt.


! 8 :

1. Display the appropriate response for this transaction.

2. Check if the response is Insufficient Funds.

If No continue, otherwise give the customer the opportunity to useanother card go to step 2.

3. Check if the response is Invalid Card.

If No continue, otherwise give the customer the opportunity to useanother card go to step 2.

4. Check if the transaction was Declined By The Issuing Bank.

If Yes Give the customer the opportunity to try again with a differentcard go to step 2.If No there are no other errors we can cater for so cancel transactionand Finish process on 16.


46/133



'& # 7

! ! * % 89:93

Yes, the...\QSIPayments\Payment Client\config\PCService.propertiesfile canbe amended to reflect the new port number, any other IP addresses and themaximum number of threads allocated to the new port. This can be done asfollows.

Open the ...\QSIPayments\PaymentClient\config\PCService.propertiesfile and add the following lines if they are not already present:

ports=XXXX(Where XXXXrepresents the socket port number to be used.)

ipNumber1=127.0.0.1(127.0.0.1 is the localhost machine)

ipNumberX=xxx.xxx.xxx.xxx(xxx.xxx.xxx.xxx is the IP number of a machinerequiring to connect to the socket remotely)

threads=X(Maximum number of threads that may connect to the socketinterface)

Detailed instructions are included in documentation contained in the patchrelease (ConfiguringExtendedSockets.txt).

! % "

Yes if the merchant chooses the 2-party payment method. The merchantcollects the credit card details on their own branded page and displays the

subsequent receipt. The Commonwealth Bank branded pages do not appear atany time during this type of transaction.

With the 3-party method the payment pages are common to all merchants andare branded in the banks style to assure customers of the security of thetransaction.

! &3

It is not necessary to have a shopping cart. All that is required is the relevantinformation be passed to the CommWeb Payment Server within the DigitalOrder.

# !5 1 */3

Log in as root

Navigate to /etc/rc.ddirectory

cd /etc/rc.d

Open rc.localfile, using viorpico, for editing


47/133



At the end of the file add following line

/java -cp

PaymentClient.PCService &

For example on our system that is:/usr/local/apps/jdk1.3.1/jre/bin/java -cp

/usr/local/QSIPayments/PaymentClient/classes

PaymentClient.PCService &

save the file and re-boot the machine

Note

Make sure the line ends with '&', as that will run the process in thebackground, and will not obstruct the start-up process.

Make sure that the paths are correct. You can test it by running it on thecommand line prior to entering it to the file.

To test, you can do a netstatand verify that port 9050 is in use, or telneton localhost to port 9050 and type:

1,test (you should receive back a line with: 1,echo:test).

3

Reconciliation is performed automatically by the CommWeb Payment Server.It is always done around the same time each day, approximately 17.30 EST

each day. Please refer to the Merchant Administration guide for details onhow to reconcile.

" #3

Merchant Administration is the Internet based portal, which allows merchantsto monitor and manage their on-line processing and administration ofpayments through a series of easy-to-use pages.

To use Merchant Administration, you need to have access to the Internetthrough a browser (such as Internet Explorer or Netscape). You also need theCommWeb URL (or web site address).

The merchant can use one of two methods to manage their transactions:

Merchant Administration- using a browser interface to interactivelyperform historical searches, captures, refunds and to perform setupactivities. For more details, please refer to the Merchant AdministrationUser Guide.

Advanced Merchant Administration- using the Payment Client todirectly access the CommWeb Payment Gateway to perform alltransaction-related actions (for example, captures, refunds and voids)


48/133



integrated with merchants software interfaces.

% 13

The debug level is set within the file setup.properties, which is located withinthe directory \QSIPayments\PaymentClient\config. The

administrator of the system has the ability to change the file at any time byplacing an entry in the file DebugLevel=X,where Xis an integer value, (seetable below). It is recommended to have the logging set at 0, but if youexperience any problems set it to 3 for support.

The debug levels are:

Debug

Level

Description of what is logged

0 Print error messages only

1 Print error and warningmessages

2 Print error, warning and infomessages

>=3 Print all messages

Payment Client Debug Levels

! " #3

If you attempt to log in with incorrect login details, Merchant Administrationwill lock operators out after three (3) incorrect attempts. If an operator is

locked out, the primary operator can access Merchant Administration andunlock the operator. If the primary operator (Administrator) is locked out,they will have to be unlocked by the CommWeb helpdesk.

% -. % --- . % /

The following reasons may cause AMA functionality to not work:

A separate operator needs to be created for AMA API calls

Your merchant account is required to have the privileges to executeAMA 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-upin Merchant Administration. An AMA operator cannot connect toMerchant Administration unless the AMA privilege is removed.

Check that you are not using incorrect merchantID, operatorID orpassword details.

If the Payment Client is communicating with the CommWeb PaymentServer when attempting to process AMA calls, check that the firewall is


49/133



open to communicate between the two applications.

% %

);,< "/< #=

TheReceipt Number(RRN)is normally a unique number for a

particular MerchantId generated by the bank. This is the value that ispassed back to the customer for their records. You cannot search for thisfield in Merchant Administration or using AMA, but it is displayed inMerchant Administration on the transaction details pages as theReference Retrieval Number (RRN).

MerchTxnRefis generated by the merchant shop and buy application. Itshould be a unique value for each transaction attempt, and the merchantshould retain this number so that transaction can be traced within themerchants application and the CommWeb Payment Server.

TransactionIDis a unique number generated by the CommWebPayment Server that matches the shopping transaction number. The

shopping transaction number is only relevant to a shopping transaction,for example Auth transactions. It is the key reference value fortransactions when using AMA transactional functions like captures andrefunds.

TheAuthorizeIDfield in the Digital Receipt is another identifier that ispassed in the Digital Receipt and sent by the issuing bank for theauthorisation. This field cannot be searched for in MerchantAdministration or AMA but it is displayed in Merchant Administrationas the "Authorisation Code". It is one of the fields returned in an AMAquery and the AMA transaction result (captures, refunds).


50/133


'

!

Each transaction and/or query requires data or information to be provided toperform the required action, for example, captures and refunds.

Transactions are made up of primary and supplementary commands:

Primary command- triggers the transaction/query to be processed bythe Payment Client.

Supplementary command provides the primary command with thedata required for the transaction/query to be implemented.

The combination of the primary and supplementary command allows aparticular functionality (for example, captures and refunds) to be available.Multiple functions can be implemented on the one primary command byusing multiple supplementary commands.

For example, a ticket number is added to a 3 Party transaction, a secondarycommand (addDigitalOrderField) is used multiple times to present the data

to the Payment Client. When all the required data for the functionalities hasbeen passed to the Payment Client, the 3 Party primary command(getDigitalOrder) is used to generate the digital order. These extra functionsextend the underlying 3 Party transaction to include ticket number in the sametransaction.

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)

Query a transaction to retrieve its digital receipt (doQueryDR)

The related commands for the sockets interface are shown in Appendix 1.

For more information on which primary command is relevant to thefunctionality being implemented, please refer to the relevant section in thischapter.

To find out which primary command is relevant to the functionality beingimplemented, please refer to the section describing that functionality later inthis chapter.

1. 3 Party transactions use a slightly modified transaction flow. Please refer to the transactionflow explanation later in this chapter. All other transactions use the basic transaction flowsoutlined in the Results section in this chapter.


51/133



The Payment Client supports transactions that return a single set of results,and queries that return multiple result sets.

After a transaction is performed, a message is sent to the Payment Server,which responds to the message with a single set of result fields for thetransaction. For example, a payment request returns a digital receiptcontaining a set of values that is used to process the payment request, such asthe QSIResponseCodeto indicate whether the request was successful or not.

Queries may return multiple sets of result fields. For example, a query thatreturns all transactions within a specified period would return a result set foreach transaction within that period. This query may return zero, one or moreresults, depending on the number of results found that match the searchspecified criteria.


52/133



%

When processing a transaction/query, the Payment Client sends a message to thePayment Server and receives a response containing a single set of valuesapplicable to that transaction (also applicable to QueryDR).

The following process is used to perform a transaction:

1. Connect to the Payment Client, depending on theimplementation being used, Java/COM orsockets.

2. An echo test is performed to check thatcommunication is established correctly withthe Payment Client.

3. Extra-required data for the functionality beingused is sent to the Payment Client. This stepmay not be required for all transactions. Pleaserefer to the functionality being used todetermine the data requirements.

4. The primary command is sent to the PaymentClient, which performs the specified commandand communicates with the Payment Server.

5. The nextResult command is used to check ifthe transaction contains valid results. If therewere errors go to step 8.

6. The data is extracted from the result set usingthe getResultField command to enable themerchant to process the transaction. It iscustomary to first determine if any processingerrors occurred by QSIResponseCode=7. Ifthere were no errors returned, continue

retrieving the results.

7. Disconnect from the Payment Client.

8. This step is only used after the nextResult toretrieve an error message from the PaymentClient to explain the failure of the nextResult.

9. This step is only used to retrieve a processingerror message from the Payment Client toexplain if the QSIResponseCode= 7.

10.This step is used to perform appropriate errorhandling.


Single result transaction process

! ? !


53/133



A transaction that is not successfully processed produces errors that can bedetected at various stages to determine the reason for the error.

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.

2. In a sockets implementation, the shop and buy application is unable toestablish a socket connection to the Payment Client host machine andport. Check the PCService is running on the host and specified port inyour shop and buy application. Also check the networking hardware andconfiguration to determine whether or not there is a hardware failure.

3. The Payment Client classes directory and/or the PaymentClient.jar file isnot correctly entered into the JVM classpath for a Java implementation,so the Payment Client object cannot be instantiated.

4. A semantic error may exist when trying to invoke the Payment Client,and it cannot be found to be invoked.

5. You may not have rebooted after installation for the COM interface.

Step 2 Performing the echo testIf the echo test fails, the Payment Client is not able to communicate orexecute commands correctly. The errors likely to cause this are the same asthose listed in Step 1.

Step 4 Executing the primary commandA failure is indicated by a Boolean return value of false in a Java or COMimplementation, or 0,0 for sockets.If the primary command encounters an error, it is caused by either incorrectinput details being supplied to the primary command, incorrect configurationof the Payment Client (incorrect keys are installed), or the Payment Clientcannot communicate with the Payment Server (usually a networkconfiguration/firewall problem).

Step 5 Executing the nextResultcommandA failure is indicated by a Boolean return value of false in a Java or COMimplementation, or 0,0 for sockets.Errors that occur executing the nextResultcommand means the PaymentServer has detected an error in processing the Digital Order.

To determine the error in Java or COM the commandgetResultField(PaymentClient.Error)is used. In sockets the command 4,PaymentClient.Error\nis used. These commands return the error code anddescription of the error.

Step 6 Checking if the QSIResponseCode = 7If 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\nis used. Thiscommand returns a description of the error that can be found in the PaymentClient Reference Guide,Appendix B.


54/133



' %

When processing a transaction/query, the Payment Client sends a message to the PaymentServer and receives a response containing a single set of values for the transaction. Queriesmay 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, thefollowing steps are used for a successful query:

1. Connect to the Payment Client,depending on the implementationbeing used, Java/COM orsockets.

2. An echo test is performed to check thatcommunication is established correctly with thePayment Client.

3. Any extra-required data for the functionality beingused is sent to the Payment Client. This step may notbe required for all transactions. Please refer to the

functionality being used to determine the datarequirements.

4. The primary command is sent to the Payment Client,which performs the command specified andcommunicates with the Payment Server.

5. The nextResult command is used to check if thetransaction 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 getResultRecordcommand to enable the merchant to process the result

through their application. Please refer to thefunctionality being implemented to find out what datais available. This step is performed for each resultrecord returned in the query. The commandgetResultCount identifies how many results havebeen returned.

8. Disconnect from the Payment Client.

9. This step is only used after the nextResult to retrievean error message from the Payment Client to explainthe failure of the nextResult command. ThegetResultField command is used to retrieve the errordescription (retrieved using the field namePaymentClient.Error).


11. This step is used to perform appropriate error handling.

12.This step is used to perform appropriate error handling.


55/133



Multiple result query process

If a transaction is not processed successfully, errors can be detected at variousstages to indicate the reason for the error. These are at the same steps outlinedin the previous section.

"

All the transactions/queries, other than 3 Party transactions, follow theprocesses outlined in the pages just described.

The following section describes the query flows for each type of transaction.The descriptions include the data requirements for each stage of eachtransaction/query is described.

. -

Supplementary data, for example, the card number and card expiry date areadded using the supplementary command: addDigitalOrderField.

This supplementary command is in the format of a String value thatrepresents a key, followed the data value for that key. Three (3) instances ofthis command are required to add the following information prior toperforming the sendMOTODigitalOrderprimary command.

1. Card Number (CardNum)The number of the card to be processed for payment. It can only be along integer value with no white space or formatting characters.

2. 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 2009, the valuewould be 0905. The value must be expressed as a 4-digit number(integer) with no white space or formatting characters.

3. Merchant Reference Transaction Number(MerchTxnRef).The merchant can use this field to uniquely identify the transaction. Thisidentifier can use text made up of any of the base US ASCII charactersin the range, hexadecimal 20 to 126.It is important to make sure thisnumber is stored so that you can retrieve it if required. It is used to

track the progress of a transaction if a communications failure

occurred and the Digital receipt is not received.

In Java and COM they take the form:

addDigitalOrderField(CardNum,5123456789012346)

addDigitalOrderField(CardExp,0905)

In Sockets they take the form:

7,CardNum,5123456789012346\n

7,CardExp,0905\n


56/133



# &F '!

This primary command requires the following information:

1. Order Information Number(OrderInfo).This is used to input any merchant/customer information about thistransaction that may be required to be stored. Null values are notaccepted.

2. Merchant Identification Number(MerchantId).The merchant ID is an alphanumeric identifier that is given to themerchant during the banks registration process, which is used to identifythe merchant on the Payment Server. The merchant uses the merchantID to log in to Merchant Administration. There is a uniqueMerchantIdfor each merchant account/profile on the Payment Server.

3. Purchase Amount(PurchaseAmountInteger)The purchase amount of the transaction expressed as an integer in thelowest currency denominator, for example, pence, cents, lire, yen, etc. It

does not contain any decimal points, thousands separators or currencysymbols, for example. $12.50 is expressed as 1250.

4. Locale(Locale)Reserved for future use. Please use the default value of en.

5. Return URL(ReturnURL)Reserved for future use. Please use the default value of (emptystring).

In Java and COM it takes the form:

sendMOTODigitalOrder(OrderInfo, MerchantId, PurchaseAmountInteger, en, )

In Sockets it takes the form:

6, + OrderInfo + , + MerchantId + , + PurchaseAmountInteger+ ,en,\n


57/133



The 2 Party transaction returns the following fields in the Digital receiptreceived by the Payment Client if the transaction was processed.

1. Merchant Transaction Reference Number (MerchTxnRef)2This is the input value passed back in the receipt and is the referencenumber allocated by the merchants software. This code should be

unique for every transaction.

2. Order Information Number (OrderInfo)The merchants information about this transaction. Can be a simpleorder number or shopping basket number.

3. Merchant Identification Number (MerchantId)This is the input value passed back in the receipt and is an alphanumericidentifier that is given to the merchant during the banks registrationprocess, which is used to identify the merchant on the Payment Server.The merchant uses the merchant ID to log in to MerchantAdministration. There is a uniqueMerchantIdfor each merchantaccount/profile on the Payment Server.

4. Purchase Amount(PurchaseAmountInteger)This is the input value passed back in the receipt and is the purchaseamount of the transaction expressed as an integer in the lowest currencydenominator, for example, pence, cents, lire, yen, etc. It does not containany decimal points, thousands separators or currency symbols, forexample. $12.50 is expressed as 1250.

5. QSI Response Code(QSIResponseCode)A single character response cod

Documents

CommWeb - Payment Client Integration Guide (1)