CommWeb - Payment Client Integration Guide

CommWeb Payment Server
Payment Client Integration Guide
CommWeb Software Support Line 1800 882 888

9 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 reconciliation

of Visa and MasterCard transactions, settlement questions,
billing enquiries, chargebacks.
Operations Help Desk 1800 022 966

24hrs, 7days a week
Version 2.23
CommWeb connectivity issues (outages).
Commonwealth Bank of Australia
"
"&
$%
$$
$(
$(
$+
$+
$+
$/
$/
(4
'
#
)
!'
*&
#
)
#
+"
("
, .
&
# 0 123
# 0'
3
#
!
1
'
7 -
6
8
# !
!
&
!
#
9
(5
(5
)
,
!
&
#
,
+%
+%
+%
+$
+(
++
+4
+
4%
4%
4%
4$
4(
4+
4+
44
4@
8
:
;
'
'
>
#
!
<
#
&
!=
# ! #
.
?6
?
. -
"
;
!
#
#
!
+"
.
!
>
&
#)
&
%/%:
&
)
&
&
12
!
=
#
&
! ,
:
!&
&
'
"
6:
:
'
!
&
Version 2.23
)
, !
'
:
8 :
)
4@
4@
4@
4@
45
45
4
4

,
A3< '
#&
!
=
,#
>
>
#
.
) 8
'
&
)
+"
("
&
,# 9
.
#2)
#2)
) 8
)
'
.
.
0)')3
&
&
Version 2.23
<)
B
4
!
/%
/$
/(
/4
//
//
//
/5
/
@
@
5+
54
5/
%
%
%
$
(
(
(
+
+
4
4
/
@
5
$%%
$%$
$%$
$%$
$%(
$%/
$%/
$%/
$%@
$%
$%
$%
$$%
$$$
$$$
$$$
$$(
$$/
$$/
$$/
$$
$$

$$
$$
""
""
""
&
#
#
#
$% &
'
$
)
*
$
- )
(
'
"
$+%
$+$
$+(
&
&
Version 2.23
'
&
!
!&
!
#
, !1 8
#&
!
A ,
!
.
)
+"
!
)') &
.
)')
.
)') 9
&
.
)') 9
.
)') = #
.
)') = #
!
+@
4%
4$
4
%
(
@
&
&
&
Version 2.23
$%(
$%/
$%
$$(
$$
$$
&
&
&
&
#
!
'
#
12
!
'
+
+"
("
)')
'
$%
$$
$@
(%
($
($
((
((
(+
(+
(4
(5
+(
+5
+
+
4(
/(
//
5(
/
/
$%4
.
+"
# 0 123
&
+"
# 0 123
C> #&
!
, #
8 ;
#
!
, #
8
#
!
, #
8
#
! !
, #
8
!
C> #
!
.
("
# 0'
3
&
)
!
.
.
)
7 !'
#
&
& 8
.
.
-
# !
#+
#+
&
Version 2.23
#
.
.
D 8 *&
?6
&
?6
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 the
CommWeb Payment Server. It also contains detailed instructions
on using the Payment Client to perform payment processing, and
also details on integrated administration functions.
It outlines the differences amongst the supported interfaces (Java,
COM and Sockets) and provides Best Practice guidelines to
ensure error free integrations.
This guide is specifically aimed at business analysts and

integrators who want to effectively integrate the Payment Client
into merchant applications.
This version of the CommWeb Payment Client Integration Guide

is designed to be used with the CommWeb Payment Client
Reference Manual, which details the input and output variables for
all of the Payment Clients API methods.
Version 2.23
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. It

outlines its 3 native interfaces, Java, COM and Sockets; what
they are, when to use them, and the advantages of each
interface.
Best Practices
Describes standard usage scenarios and recommends what

the best method is to use the Payment Client.
Transaction Flows
Details the steps to perform each transaction type and the

data flows involved.
Authentication
Describes the implementation of MasterCard SecureCode and

Verified by Visa.
AMA Function
Calls
Describes the Advanced Merchant Administration functions

which allow some administration tasks to be preformed via
the Payment Client.
If you need assistance with Payment Client Integration, please contact the CommWeb
Software Support Line on 1800 882 888
Version 2.23
CommWeb enables a merchant to perform secure transactions over the

Internet. To do this they need to integrate the Host Application (Shop and
Buy application) with the CommWeb Payment Client.
The Payment Client is a back-end processing tool available to the Host
Application through an API (Application Program Interface). It interacts with
the CommWeb Payment Server, which processes secure transactions in realtime over the Internet.
Issuer
Card
CommWeb
Payment Client
Integration
Module
Host
Application
CommWeb
Payment
Server
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 of
Digital Orders from a merchants Shop and Buy application to the CommWeb
Payment Server. Digital Orders from the Payment Client provide information
to the CommWeb Payment Server to process the transaction by taking money
from the customers card account (at the issuing institution) and placing those
funds in the merchants account at the Commonwealth Bank.
After sending a transaction to the CommWeb Payment Server, the Payment
Client receives a signed and encrypted Digital Receipt. The Digital Receipt
provides a response for the transaction to the merchant to show whether the
transaction was successful or not.
The Payment Client supports a range of payment protocols using Payment
Gateways, each offering different levels of security, payment risk and cost.
Version 2.23
10
"
Issuing Bank
6.
3.
Card Holder
1.
5.
2.
4.
CommWeb
7.
Merchant
Commonwealth Bank
Real Time
Batch
How a transaction is processed
During a transaction, the funds are transferred from the cardholders account
to 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 transaction
authorisation request to the card issuer (the customers bank) (3).
3. The card issuing institution adjusts the cardholders credit limit for the
funds and returns the result to CommWeb. CommWeb passes the result
of the transaction on to the merchant.
4. Commonwealth Bank settles the transaction with the issuing bank as
part 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 bank
account.
Version 2.23
11
$!
Purchase Merchant
Purchase merchants capture funds from the customers card in a single
transaction and the funds are immediately transferred into the merchants
account when the acquiring institution processes the transaction. Each
instance of a purchase transaction will show up on the customers card
statement.
Auth /Capture Merchant (Pre Authorisation)
Note: Pre-Authorisation transactions are referenced in CommWeb as
Authorisation or Auth transactions.
Auth /Capture merchants perform at least two transactions to capture the
funds from the customers card and deposit them in the merchants account.
The Pre-Authorisation (Auth) transaction verifies that the card details
are correct and will also reserve the funds for that merchant.
The capture transaction refers back to the initial authorisation
transaction, and instructs the transfer the funds from a customers card
into the merchants account.
The merchant can perform more than one capture transaction, for example the
merchant may not have the full ordered amount of goods in stock but ships
what they do have. Later, when they ship the remaining goods the merchant
can perform another capture transaction that refers back to the initial
authorisation transaction which transfers the remaining funds to the
merchants account.
Version 2.23
12
#
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 institution
to verify that the funds are available in the customers card account. The
funds are reserved (and the credit limit adjusted) until captured by the
merchant and transferred to the merchants account.
The auth transaction reserves the funds for a predetermined period of time as
determined by the issuing bank.
Auth/Capture This is the standard Auth/Capture mode where the full
amount of the goods or service is sent through to the card issuing
institution 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 the
capture transaction to debit the card when the time comes to transfer the
funds to the merchants account.
This auth reservation of funds will reserve the funds for a predetermined
period of time, (such as 5 days), as determined by the issuing bank.
&
'
For every order there is normally one shopping transaction. Each shopping
transaction may require a number of associated financial transactions, for
example, captures and refunds. Financial transactions represent the flow of
information between the customer, the merchant and the bank when
purchasing goods and services.
Subsequent transactions can be void, capture or refund transactions.
Voided transactions cancel the settlement portion of the transaction, so the
merchant does not get paid and the cardholder never sees the transaction on
their statement. However, voided transactions on CommWeb do not readjust
the cardholders credit limit adjustment. Voids can only be done before
CommWeb 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 is
approximately 17.30 EST. Once cut-over is performed, transactions done
prior to this time cannot be voided.
Refunds are where the merchant re-credits funds back to a customers card. In
this case both transactions are listed on the cardholders statement.
The merchant can perform as many capture and refund transactions as they
want providing the total amount captured does not exceed the original auth
transaction. You must have captured the funds before you can perform a
Version 2.23
13
refund (i.e. the original transaction was a purchase or an authorised

transaction that has been captured), otherwise an error will occur.
Version 2.23
14
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 & buy
application or a call centre operation, where the merchant collects the
card details. In this mode the merchant controls the display of the
payment 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 & buy
application or e-mail, as the customer can only input their credit details
direct to CommWeb via a web page that is displayed from the
CommWeb server. The pages displayed will be branded by the
Commonwealth Bank, but will reference the merchant name.
*+,
3-Party transactions use the SSL protocol to provide secure transmission of

sensitive data between a customers web browser and the CommWeb
Payment Server. In addition to SSL channel encryption, the Payment Client
encrypts transaction data sent from the shop and buy application to the
CommWeb Payment Server to prevent alteration in transit as it is redirected
via the customers browser.
The SSL+ Gateway uses 3-Party messaging and the three parties are the
customer, 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 hackers
and misuse.
Version 2.23
15
"
Information Flow in 3-Party (SSL+)
1. A customer and decides to purchase goods and enter details into

the merchants shop and buy application software at the checkout page.
2. The customer pays for the goods and the merchant software sends an
encrypted Digital Order to the CommWeb Payment Server .
3. The CommWeb Payment Server receives the customers card details
and displays a series of screens. The first screen (see page 21) displays the
cards supported by the merchant, for example MasterCard, Visa, and
American Express. The customer chooses the card type they want to use
for the transaction. The second screen accepts the details for the chosen
card such as card number, card expiry, a card security number if required,
see page 22.
4. The CommWeb Payment Server passes the details directly to the card
issuing institution. When the payment has been processed, the
CommWeb Payment Server temporarily displays the result of the
transaction before displaying the final screen, which asks the customer to
please wait while they are redirected back to the merchants site (see page
23) and the CommWeb Payment Server passes an encrypted Digital
Receipt back to the merchants site detailing the result of the
transaction . This information is then passed back to the user for their
records (see page 23).
The CommWeb Payment Client constructs and sends an encrypted Digital
Order to the CommWeb Payment Server, and then decodes the encrypted
Digital Receipt from the CommWeb Payment Server via browser redirects.
In a 3-Party transaction, the customers browser connection is completely
Version 2.23
16
severed from the merchant application, so any session variables that are
required to identify the current session must be collected and sent to the
CommWeb Payment Server, where they are returned appended to the
encrypted Digital Receipt.
For information on the method used to send the session variables, please refer
to page 31.
Version 2.23
17
+"
3-Party transactions require two separate operations:

Creating and sending the Digital Order.
Receiving the Digital Receipt and decrypting it and returning the
individual receipt details back to the merchant software.
'
. /
0
1. Echo test to check if the shop and buy application can connect to the
Payment Client.
2. Add any additional data fields. These values are sent prior to a primary
command (getDigitalOrder) using add extra data commands (called
addDigitalOrderField). These extra data commands are detailed later
in the document.
3. Get the encrypted Digital Order and use a browser redirect to send it to
the CommWeb Payment Server via the customers browser.
. /
(
"
1. The encrypted Digital Receipt is sent by the CommWeb Payment Server
via the customers browser, and an echo test is performed to check if the
shop 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 to
your Commonwealth Bank number.
MerchTxnRef Identifies this particular transaction on the CommWeb
Payment Server. This is a unique value for each transaction. For more
information, please refer to page 30.
Amount The value of this transaction. It is an integer that expresses
the amount in the lowest currency denomination, for example cents and
pence.
Locale Identifies the language used on the CommWeb Payment
Server screens. English is the only supported language.
ReturnURL The merchant page which the CommWeb Payment

Server redirects the customers browser, at the end of the transaction.
These inputs are sent together in the one primary Payment Client command
getDigitalOrder.
Version 2.23
18
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.
Version 2.23
19
What the Customer sees in a 3-Party (SSL+) transaction.
Version 2.23
20
. %. " 2 * '. & *

The checkout page displays the line items that the customer wants to purchase
and the total amount to pay, including any delivery charges and taxes. The
customer 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 the
Payment Details page.
CommWeb Payment Servers Payment Options Page
Version 2.23
21
. '
1 +
% ) 3
/
On the Payment Details page, the customer enters their card details, including
the card number, expiry date, card security code (CVC2/CVV2), and clicks
the 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 be
displayed to the customer.
CommWeb Payment Servers Payment Pending Page
Version 2.23
22
. '
1 +
% ) 3 (
The redirection page is displayed in the customers browser and the Digital
Receipt 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 a
receipt page is displayed to the customer.
The Shop & Buy Receipt Page
Version 2.23
23
)"
2-Party transactions are purchase/auth transactions orders where the customer

provides their card details to a merchant, via mail order or by telephone on a
call 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 card
details are captured and stored by the merchant.
The MOTO Gateway uses 2-Party messaging and the two parties are the
merchant 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, mail
order or telephone order and submits the details to be processed via the
Payment Client .
9. The Payment Client generates an encrypted Digital Order and sends it
over the Internet to the CommWeb Payment Server . The Digital Order
includes 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
Version 2.23
24
the CommWeb Payment Server, which forms an encrypted Digital

Receipt. This receipt, which includes the transaction results and
payment reference details, is sent from the CommWeb Payment Server
back to the Payment Client where it is decrypted. The decrypted
results are sent back to the merchant and stored for future reference. A
receipt is also passed back to the customer for their records .
11. A 2-Party transaction is a multi command function that uses the following
commands:
12. Echo test to check if the shop and buy application has access to the
Payment Client.
13. Add additional data fields like Card Number and Card Expiry to the
transaction.
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 is
different to your Commonwealth Bank number.
MerchTxnRef Identifies this particular transaction on the CommWeb
Payment Server. This should be a unique value for each transaction
attempt, which makes it easy for the merchant to track transactions.
Amount Contains the value of this transaction. It is an integer that
expresses 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 CommWeb
Payment 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 style
transaction, as all pages are displayed by the merchants application.
Version 2.23
25
#
("
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 Internet
browser-based application implemented by the CommWeb Payment
Server. For more information, please refer to the Merchant
Administration User Guide.
2. Advanced Merchant Administration (AMA) transactions - using the
Payment Client to directly access the CommWeb Payment Server to
perform all transaction-related actions (for example, refunds, and
captures) integrated with the merchants own payment software
interfaces.
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 Reference
Manual.
The various commands available in AMA are outlined in detail later in this
guide.
Version 2.23
26
I
#
!
The Payment Client is normally installed at the merchants site, if their Web
Site is self hosted, or the merchants Internet Service Provider (ISP), which
provides encryption, security, and interface services to the merchants shop
and buy application.
The merchants shop and buy application can integrate to the Payment Client
using 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, for
example, SSL+ and MOTO, if the merchant is licensed to do so by the
Commonwealth Bank. You can install as many of these interfaces as
necessary.
Merchant Application
Perl/CGI
Sockets
Java
Java
ASP
COM
Payment
Client
Payment Client Architecture
The most common languages used for integrating the Payment Client are
Java, VBA and Perl, but any language that supports
Host Server
sockets can be used, as the Payment Client APIs are
Host
available through its sockets interface.
Application
D 8 )
Java is the native language of the Payment Client
and allows you to call the Payment Client Classes
directly from the application running on the same
Version 2.21
JVM
CommWeb
Payment
Client
27
Java Virtual Machine (JVM). Java is Operating System (OS) independent, but
the Java implementation that communicates with the Payment Client must be
located on the same host as the Payment Client. Although this architecture
provides OS independence and an object orientated interface, it does not
allow a distributed and scaleable architecture.
& ')
The COM interface is registered on the local
Payment Client machine and is available for
loading and calling Payment Client API
commands. It is operating system dependent and
the OS you use must support COM, for example
most Microsoft based operating systems. COM
allows for an object orientated interaction with the
Payment Client and the portion of the COM
implementation that communicates with the
Payment Client must be located on the same host
as the Payment Client. It also does not allow for a
distributed and scaleable architecture.
Host Server
Host
Application
Microsoft
COM
Operating
System
Microsoft
COM
CommWeb
MIGS
Payment
Client
Host Application Environment
Operating
System
Sockets API is preferred if scalability and

Host Application
flexibility are major concerns. It allows the
Integration to
CommWeb
QSI Socket
Socket
Payment Client to be located on any host
Interface
machine (as long as it is capable of supporting
Java and TCP/IP Sockets) with a listening
Payment Client Server
service attached to a port on that machine. It
Socket
allows multiple Payment Clients to be set up on
Listening
Service
one or multiple hosts as each Payment Client is
assigned to a port. To use a different Payment
Client you need to change the host name and/or
JVM
the port address you communicate to. Because
multiple hosts can be installed with multiple
CommWeb
MIGS
Payment Clients, this offers far greater flexibility
Payment
Client
and scalability to cope with future transactional
loads. This provides the sockets implementation
with a stronger operating system independence than either of the previous
two architectures, Java and COM. However as socket commands are
primarily string commands being sent to a socket, the object orientated
approach to a direct interaction with the Payment Client cannot be fully
implemented.
Version 2.23
28
E
#
MOTO requires the customers card details to be stored on the
merchants terminal, so it is not as secure as SSL+, where the merchant
does not have contact with the customers card details.
SSL+ provides added security by directly linking the customers
browser with the CommWeb Payment Server to pass the encrypted
Digital Order.
The Java interface is native to the Payment Client, so provides the
strongest communication between the merchant and customer. The
communication is between java classes, and it is very difficult for a
hacker 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 the
system. The compiled classes would require de-compilation before it
could be viewed and changed.
COM cannot be accessed remotely which means that it is secure (remote
access can be implemented using DCOM).
The sockets interface sends data as plain text to the Payment Client, so
all communications using sockets should be secured behind firewalls.
This ensures that operator names and passwords in Merchant
Administration are inaccessible from the data stream.
Version 2.23
29
.
"
0 &
MerchantTxnRef is normally used for querying an exact transaction on the

CommWeb Payment Server. In a case where the merchant requires to know
the specific result of a transaction, for example, when a Digitial Receipt is not
received by the merchant, then the MerchantTxnRef is used to locate the
details.
Although CommWeb allows any reference to be entered with a shopping
transaction, it is advised that some unique identifier is used by the merchant
to allow an easy cross-reference with the merchants host system. A example
of a MerchTxnRef would be the merchants unique order number assigned to
each sale. This allows the merchant to look up the transaction on CommWeb
with the same reference used to lookup the transaction on their own host
system. To guarantee uniqueness, different payment operations on the same
sale need also to be identified, as stated below.
#
If a transaction for a sale is declined, and a subsequent attempt is made to
process a payment for this sale, the merchant should 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. This is the
preferred way of implementing a unique MerchTxnRef. Because under a
fault condition, such as if the Digital Receipt does not arrive back at the
merchants site, you may need to check if the transaction was carried out
successfully.
Automated lookups and financial operations cannot be performed if the
merchant has not given each transaction attempt a unique MerchTxnRef
number, as there will be multiple results showing the same MerchTxnRef.
Version 2.21
30
1
In a 3-Party transaction, the customer browsers connection is completely
severed from the merchant application. Some merchant applications use
session 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 stops
hackers from spoofing transactions.
Session variables that are required to identify the current session so the
CommWeb Payment Server can return to the merchants program from where
it left, must be collected and sent to the CommWeb Payment Server. The
session variables are not used by the CommWeb Payment Server, but are
returned appended to the Encrypted Digital Receipt. There can be as many
session variables as required using any name the merchant shop and buy
application needs, providing they legally conform to HTTP/HTTPS protocols.
To make them conform to the standard, URL, you need to encode all session
variables before sending them.
To send them to the CommWeb Payment Server the merchant must append
them to the merchant ReturnURL, where they are encrypted by the Payment
Client 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*qtY
HWXzUsCm1Vh168yY6NBQkjgYuEvTaUUDvWiBWwS9rjopgPA94xoE
*RawO.stRe8bTTPCh0W0RiupP2MekWqfyAWwluag7Y9.w95y07fg
FFqQvRLYALmAz.tFEv.8*5I47yONI*fYOpHzyzRgzEFDQZ18
The ReturnURL is encrypted into the Digital Order, which is sent to the
CommWeb Payment Server using a customers browser redirect.
At the CommWeb Payment Server, the merchant session variables are
recovered and temporarily stored in the CommWeb Payment Server with the
other transaction variables. They are sent back to the Payment Client
appended to the Digital Receipt at the completion of the transaction.
When encrypted the Digital Receipt is returned via a customers browser
redirect, 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
Version 2.23
31
8wUm0W0RiupP2MekWqfyAWwluag7Y9&SessionVariable1=1234
&SessionVariable2=8901
This helps the merchant shop and buy application recover the session
variables from the encrypted Digital Receipt URL, and use them to restore the
merchant session. The session continues as though it had never been broken.
Once the encrypted Digital Receipt is decrypted, all the receipt details can be
captured from the Payment Client.
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 to
manually check using Merchant Administration on the Payment Server.
Utilise Advanced Merchant Administration (AMA) commands to search
the Payment Server database for the transaction by using the QueryDR
command if MerchTxnRef is unknown. The MerchTxnRef is used as
the transaction identifier when searching using QueryDR.
Because the Digital receipt has failed to come back, there is no transaction
number available from the Payment Server to identify the transaction in
question, and this is why you use the MerchTxnRef. It is important to have a
unique MerchTxnRef for every transaction otherwise the query could return
multiple results. Only the most recent transaction is returned in the QueryDR
command if there are multiple results, but this may not be the transaction you
are looking for.
Diagram Showing Information Flow
Version 2.23
32
When you find the required MerchTxnRef in the QueryDR, check if it is

successful by the QSIResponseCode field (equal to 0). If the
QSIResponseCode is zero, then the transaction is successful and you just
need to extract the relevant data details from the QueryDR results for your
records. If the QSIResponseCode is not 0, you need to determine the next
course of action based on what you would do if the QSIResponseCode were
not 0 in a normal digital receipt coming back from the Payment Server.
If you query the Payment Server for the MerchTxnRef using the QueryDR
call and you do not receive any results, then it is safe to repeat the transaction.
It is safe to use the same MerchTxnRef, as the existing one does not show up
in the Payment Servers database.
If the QueryDR is flagged as having multiple results (returns Y in the
MultipleResults field), the MerchTxnRef is not unique.
4
The Payment Client contains a socket listener application,
PaymentClient.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.
The related commands for the sockets interface are shown in Appendix 1.
This response consists of two fields separated by a comma, for example0,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. Failed transactions would not return any
data and the responses are 0,0. Many commands like 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 shop and buy
application to detect possible failures in the payment process. If the socket
times out it must be actioned or it will result in either a duplicate transaction.
For more information, please refer to the Best Practices section.
Version 2.23
33
Note:
In each of the socket example commands shown in this guide, the \n
New Line character at the end of each command string is used to tell Java
to input a Line Feed character to indicate the end of the command.
Failure to include this character or a Carriage Return character Java \r
at the end causes the socket command to fail.
Some programming languages such as ASP can automatically add this to
the end of the command so the programmer does not have to include it.
Warning:
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) is also prohibited from the data field.
If a data field contains any of these characters, the field data should be parsed
to remove these characters before including it in the socket command. Failure
to do so will cause the transaction to fail, as the socket listener will
prematurely see the end of that command, and not receive all the required
data.
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 socket
time-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 disable
SO_TIMEOUT with the specified timeout, (this timeout value is in
milliseconds). 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 only
the designated amount of time. A timeout of zero (0) is interpreted as an
infinite timeout so the socket will never timeout.
If the timeout expires, a java.io.InterruptedIOException is raised, though
the Socket is still valid. The option must be enabled prior to entering the
blocking operation for it to take effect and the timeout must be > 0.
The setSoTimeout value determines how long the socket waits for a response
from the Payment Client after sending a command. This allows the shop and
Version 2.23
34
buy application to detect possible failures in the payment process.

If the setSoTimeout period is reduced to a lower value, for example 10
seconds, then under times of heavy load on the CommWeb Payment Server
this short timeout period may be exceeded. The time out would normally
occur on processing messages like sending a MOTO Digital Order, which
take time for the CommWeb Payment Server to process. The message is
transmitted to the CommWeb Payment Server, where it is processed
successfully, but the successful response of 1,1 may take longer to arrive
back at the socket than the socket time out period allows. So the data remains
in the Payment Client buffer waiting for transmittal to the application. If the
time out is ignored, the next command sent will contain this old status value,
and its status will still be in the Payment Client buffer again waiting for
transmittal to the application. All responses are then displaced.
Note:
In each of the socket example commands shown in this guide, the \n
New Line character at the end of each command string is used to tell Java
to input a Line Feed character to indicate the end of the command.
Failure to include this character or a Carriage Return character Java \r
at the end causes the socket command to fail.
Some programming languages such as ASP can automatically add this to
the end of the command so the programmer does not have to include it.
You need to ensure that the timeout period is long enough not to time out
prematurely, but if the socket does time out, it needs to be detected and not
continue with the next step of the transaction. If the shop and buy application
continues and process the next command, then all future responses are
displaced.
Version 2.23
35
CommWeb Socket Information Flow

(MOTO)
Good Transaction
CommWeb Socket Information Flow

(MOTO)
Bad Transaction
Sent
Received
Sent
Received
1,Test\n
1,echo:Test
1,Test\n
1,echo:Test
translates to echo("Test") command in Payment Client
7,CardNum,5123456789012346\n
translates to echo("Test") command in Payment Client
1,1
7,CardNum,5123456789012346\n
1,1
addDigitalOrderField("CardNum") command
1,1
7,CardExp,0202\n
addDigitalOrderField("CardNum") command
7,CardExp,0202\n
1,1
addDigitalOrderField("CardExpiry") command
addDigitalOrderField("CardExpiry") command
7,ticketNo,Some data for transaction\n
addDigitalOrderField("Ticket") command
1,1
6,1234,Test2008,100,en,\n
1,1
7,ticketNo, Some data for transaction\n
1,1
addDigitalOrderField("Ticket") command
6,1234,Test2008,100,en,\n
sendMOTODigitalOrder("1234", "Test2008", "100", "en", "")
sendMOTODigitalOrder("1234", " Test2008", "100", "en", "")
5\n
5\n
1,1
1,1 (From 6,1234,Test2008, etc.)
nextResult( ) command
nextResult( ) command
4,DigitalReceipt.QSIResponseCode\n
4,DigitalReceipt.QSIResponseCode\n
1,0 *
1,1 (From 5,null,) Error Response*
objPayClient.getResultField("DigitalReceipt.QSIResponseCode")
objPayClient.getResultField("DigitalReceipt.QSIResponseCode")
4,DigitalReceipt.TransactionNo\n
4,DigitalReceipt.TransactionNo\n
1,271
1,0 (From 4, QSIRespCode,)
objPayClient.getResultField("DigitalReceipt.TransactionNo")
objPayClient.getResultField("DigitalReceipt.TransactionNo")
4,DigitalReceipt.ReceiptNo\n
4,DigitalReceipt.ReceiptNo\n
1,01102502
1,271 (From 4, TxNo,)
objPayClient.getResultField("DigitalReceipt.ReceiptNo")
objPayClient.getResultField("DigitalReceipt.ReceiptNo")
* A QSIResponse Code of 0 indicates a successful transaction.
* 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 returned
is incorrect for each of the next commands that are sent.
The result of not detecting and handling the time out is that a successful
transaction 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
sendMOTODigitalOrder command (6,1234,Test2008,100,en,\n)
The response from command 4,DigitalReceipt.QSIResponseCode\n is
1,1 which shows up as a QSIResponseCode of 1, which indicates a
failed transaction, but this response is actually from the 5\n command.
The actual QSIResponseCode is 0 because the transaction completed
successfully, but it is delayed one command so it is lost. One of the
common responses to this is to have the shop and buy application redo
the transaction, which would result in a duplicate transaction.
The response from command 4,DigitalReceipt.TransactionNo\n is
1,0 which shows up as a Transaction No of 0, which is incorrect,
but this response is actually from the
4,DigitalReceipt.QSIResponseCode\n command.
The response from command 4,DigitalReceipt.ReceiptNo\n is 1,271
which shows up as a Receipt No of 271, which is incorrect, but this
response is from the 4,DigitalReceipt.TransactionNo\n command. The
real Receipt No of 01102502 is lost from the transaction stream.
Version 2.23
36
If the transaction has been successfully processed by the CommWeb Payment

Server, and the transaction is repeated it would result in a duplicate
transaction.
If a socket time out occurs, do not ignore the time out, as it will only cause
errors.
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. You
need to determine what to send back to the cardholder while this manual
check is performed, as it could be a good transaction.
4. Close the socket and open a new socket connection and use Advanced
Merchant Administration commands to search the Payment Server
database for the transaction. The QueryDR command can be used to
search the Payment Server using the MerchTxnRef as the transaction
identifier. At this stage there is no transaction number available back
from the Payment Server to identify the transaction, so it is important
to have a unique MerchTxnRef for every transaction.
Information Flow for a Socket Timeout
When you find the required MerchTxnRef in the QueryDR, check if it is

successful by the QSIResponseCode field (equal to 0). If
QSIResponseCode is zero, then the transaction is successful and you just
Version 2.23
37
need to extract the relevant data details from the QueryDR results for your
records. If the QSIResponseCode is not 0, you need to determine the next
course of action based on what you would do if the QSIResponseCode were
not 0 in a normal digital receipt coming back from the Payment Server.
If you query the Payment Server for the MerchTxnRef using the QueryDR
call and you do not receive any results, then it is safe to repeat the transaction.
It is safe to use the same MerchTxnRef, as the existing one does not show up
in the Payment Servers database.
If the QueryDR is flagged as having multiple results (returns Y in the
MultipleResults field), the MerchTxnRef is not unique.
Completing the above process is better than repeating the transaction, and
perhaps having to do a refund. For large value transactions, double processing
becomes expensive.
While you are determining the status of the transaction, you could display an
error message to the customer, and the system is currently verifying the
transaction.
Version 2.23
38
Each Payment Client can only talk to one CommWeb Payment Server using
the merchants assigned CommWeb MerchantID. The Payment Client keys
must match the CommWeb Payment Server keys for the supplied
MerchantID, but you can run multiple Payment Clients, on separate hardware,
for redundancy. This can be easily achieved by having the merchant
application switch between the multiple Payment Clients using the sockets
interface to each Payment Client. Each Payment Client listens on its own
socket.
To CommWeb
Payment Client 1 on
Machine 1
Merchant
Application
Via the Internet
Payment Client 2 on
Machine 2
Applications and Payment Clients on

separate machines
To CommWeb
Merchant Firewall
Merchant Application Using Multiple Payment Clients
However, the Payment Client does not come standard with the ability to
operate on a remote machine or have multiple instances of the Payment Client
running, each listening on a different port. There is a patch that is available to
perform this function.
With the patch installed, the PCService.properties file in each Payment
Client config subdirectory then tells the Payment Client what port to listen
on, 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 the
Payment Client. The IP address of the machine sending the Payment Client
data must be included in this file. If it is not, the socket cannot communicate
with the Payment Client, as it will refuse the connection. This is a safeguard
to prevent unauthorised machines from communicating with the Payment
Client.
Version 2.23
39
$ %
! &
!
The port, threads and IPs are set within the file PCService.properties within
the directory \QSIPayments\PaymentClient\config\ and edit the file.
Commands
Description
port=9050
Port number of the socket when initiated,

default 9050
ipNumber1=127.0.0.1
The first IP number that is allowed to

access the socket. 127.0.0.1 is the
localhost machine.
ipNumberN=xxx.xxx.xxx.xxx
Other IP addresses that are allowed to

access the socket. N represents an
incremental number starting from 2.
threads=10
Maximum number of connections that

can connect to the socket interface. This
can be increased or decreased from the
default, but experience has shown 10
threads 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 to
the following :
QSIRoot=c:\QSIPayments
Version 2.23
40
"
5
!
Within the directory \QSIPayments\PaymentClient\config, locate your key
files qsi.3 and qsi.4. These are the critical files for the payment client and
should never be changed, unless instructed to by your bank due to a key
change on the CommWeb server, or due to a setup of a new account for the
merchant.
You do not need to modify the file setup.properties within this same
directory to point to the new CommWeb Payment Server. You can use either
the CommWeb Payment Server host name or its IP address.
Command File setup.properties
Description
for example
TargetURL=https://migs.mastercard.com.au/
Modify the TargetURL to

reflect the server name.
Setting setup.properties Data
Each Payment Client is started from a command line window from within the
Payment Client classes subdirectory by inputting java
PaymentClient.PCService, or by starting it as a service.
Version 2.23
41
'
*+
SSL+ Transaction Flow

Version 2.23
42
)*
",
The best practice flow diagram shows how to create a payment-enabled shop
and buy application.
'
1. The shopping cart is stored in a database while the transaction is being

processed, to keep a record of the data. During the transaction the
connection to the customer is unlinked [recall the redirection] so the
data needs to be stored. If the data is lost then the transaction cannot be
processed. Two boolean flags, CHECKED_OUT and WAITING_FOR_DR,
are stored on the server with the shopping cart record.
2. The flag, CHECKED_OUT, checks whether the shopping cart already has
a payment attempt in progress:
a. FALSE Payment Not Attempted
b. TRUE Payment Process Started.
If 'Payment Not Attempted' continue to the next step, otherwise go to step
17.
3. Set the CHECKED_OUT flag to TRUE to indicate the start of the payment
process.
4. Create the Digital Order.
5. Set the boolean flag WAITING_FOR_DR to TRUE to indicate that the
software is waiting for a Digital Receipt for this order.
6. Send the Digital Order to the CommWeb Payment Server using a
browser redirect.
Note:
The merchant shop and buy application transfers the connection to the
CommWeb Payment Server which sends the Digital Receipt using the
customer browser to the merchant web site static URL specified in
Merchant Administration, or by the dynamically constructed Return URL
specified in the Digital Order.
For static URLs, the MerchTxnRef identifies the customer session and
shopping cart.
For dynamic URLs, any additional session variables that are required to
allow the CommWeb Payment Server to return to the same session should
be appended to the Return URL. These are encrypted as part of the Digital
Order and returned as parameters appended to the encoded Digital Receipt.
7. Wait for the Digital Receipt to be returned via a browser redirect from
the CommWeb Payment Server. Pass the Digital Receipt to the Payment
Client and retrieve and store the results. Set WAITING_FOR_DR to
FALSE for this order.
8. The Digital Receipt is returned to the merchant software via a browser
redirect.
Version 2.23
43
9. Check the WAITING_FOR_DR flag. If FALSE the DR has already been

received. Therefore this is a retry delivery of a Digital Receipt, go to 27
and display the receipt details. If TRUE, continue.
10. Store the Digital Receipt values in the database.
11. Set the WAITING_FOR_DR flag to FALSE to indicate the Digital Receipt
has been received.
12. Check if the CANCELLED Flag set. If FALSE, continue, otherwise go to
step 28.
13. Check if the transaction was successful. This is indicated by a
QSIResponseCode value of zero.
If the QSIResponseCode is not zero then go to step 30, otherwise
continue.
14. Process the order as Paid.
15. Display the receipt details to the customer.
16. Finish.
%
If the customer attempts a second payment on one order or clicks Back button
in the browser while transaction is being processed.
If the CHECKED_OUT flag is set.
1. The customer arrives here if they attempt to enter the pay process twice
for the same order.
If the WAITING_FOR_DR flag is TRUE then go to step 20, otherwise
continue.
2. Check if the transaction was successful. This is indicated by a
QSIResponseCode value 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 if
the 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 customer
wants to keep proceeding.
If the customer wishes to proceed then continue, otherwise go to step 23.
6. Set the CANCELLED flag for this transaction and restart a new
transaction at operation 1 by storing the shopping cart in the database
with a new MerchTxnRef number according to the instruction in
operation 1.
Version 2.23
44
7. Display merchant contact details and continue waiting for the Digital
Receipt 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 permitted
for this order.
10. If the retry limit is not exceeded then increment the retry counter and
assign a new order number according to the instruction in operation 1,
and go to step 4.
Create new order from operation 4 onwards.
'
, :
11. Check if the transaction number is the same as the one previously
received for this order.
If the transaction number is the same, continue, otherwise go to step 29.
12. Cancel the duplicate successful transaction with CommWeb. The actual
cancellation can be performed through any CommWeb process, for
example MA or AMA. This operation is where an automatic
cancellation would occur or notification generated for a manual process
to begin. Only cancel the transaction if there is more than one successful
transaction for this order.
13. Display the receipt details for the current transaction based on the
original Digital Receipt.
!
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 use
another card go to step 2.
3. Check if the response is Invalid Card.
If No continue, otherwise give the customer the opportunity to use
another 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 different
card go to step 2.
If No there are no other errors we can cater for so cancel transaction
and Finish process on 16.
Version 2.23
45
'
&
*
89:93
Yes, the
...\QSIPayments\Payment Client\config\PCService.properties file can
be amended to reflect the new port number, any other IP addresses and the
maximum number of threads allocated to the new port. This can be done as
follows.
Open the ...\QSIPayments\PaymentClient\config\PCService.properties
file and add the following lines if they are not already present:
ports=XXXX (Where XXXX represents 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 machine
requiring to connect to the socket remotely)

threads=X (Maximum number of threads that may connect to the socket
interface)
Detailed instructions are included in documentation contained in the patch
release (ConfiguringExtendedSockets.txt).
"
Yes if the merchant chooses the 2-party payment method. The merchant
collects the credit card details on their own branded page and displays the
subsequent receipt. The Commonwealth Bank branded pages do not appear at
any time during this type of transaction.
With the 3-party method the payment pages are common to all merchants and
are branded in the banks style to assure customers of the security of the
transaction.
&
It is not necessary to have a shopping cart. All that is required is the relevant
information be passed to the CommWeb Payment Server within the Digital
Order.
!
*
/3
Log in as root
Navigate to /etc/rc.d directory
cd /etc/rc.d
Open rc.local file, using vi or pico, for editing

Version 2.23
46
At the end of the file add following line

<path_to_java>/java -cp <path_to_PaymentClient_classes>
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 the
background, and will not obstruct the start-up process.
Make sure that the paths are correct. You can test it by running it on the
command line prior to entering it to the file.
To test, you can do a netstat and verify that port 9050 is in use, or telnet
on localhost to port 9050 and type:
1,test (you should receive back a line with: 1,echo:test).
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 on
how to reconcile.
"
Merchant Administration is the Internet based portal, which allows merchants

to monitor and manage their on-line processing and administration of
payments through a series of easy-to-use pages.
To use Merchant Administration, you need to have access to the Internet
through a browser (such as Internet Explorer or Netscape). You also need the
CommWeb URL (or web site address).
The merchant can use one of two methods to manage their transactions:
Merchant Administration - using a browser interface to interactively
perform historical searches, captures, refunds and to perform setup
activities. For more details, please refer to the Merchant Administration
User Guide.
Advanced Merchant Administration - using the Payment Client to
directly access the CommWeb Payment Gateway to perform all
transaction-related actions (for example, captures, refunds and voids)
Version 2.23
47
integrated with merchants software interfaces.
1 3
The debug level is set within the file setup.properties, which is located within
the directory \QSIPayments\PaymentClient\config. The
administrator of the system has the ability to change the file at any time by
placing an entry in the file DebugLevel=X, where X is an integer value, (see
table below). It is recommended to have the logging set at 0, but if you
experience any problems set it to 3 for support.
The debug levels are:
Debug
Level
Description of what is logged
Print error messages only
Print error and warning

messages
Print error, warning and info

messages
>=3
Print all messages
Payment Client Debug Levels
"
If you attempt to log in with incorrect login details, Merchant Administration

will lock operators out after three (3) incorrect attempts. If an operator is
locked out, the primary operator can access Merchant Administration and
unlock 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 execute
AMA functions, please check with the helpdesk that this is enabled for
your merchant account.
Advanced admin methods privilege has to be enabled in operator set-up
in Merchant Administration. An AMA operator cannot connect to
Merchant Administration unless the AMA privilege is removed.
Check that you are not using incorrect merchantID, operatorID or
password details.
If the Payment Client is communicating with the CommWeb Payment
Server when attempting to process AMA calls, check that the firewall is
Version 2.23
48
open to communicate between the two applications.
;,< "
%
<#
%
=
The Receipt Number (RRN) is normally a unique number for a

particular MerchantId generated by the bank. This is the value that is
passed back to the customer for their records. You cannot search for this
field in Merchant Administration or using AMA, but it is displayed in
Merchant Administration on the transaction details pages as the
Reference Retrieval Number (RRN).
MerchTxnRef is generated by the merchant shop and buy application. It
should be a unique value for each transaction attempt, and the merchant
should retain this number so that transaction can be traced within the
merchants application and the CommWeb Payment Server.
TransactionID is a unique number generated by the CommWeb
Payment 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 for
transactions when using AMA transactional functions like captures and
refunds.
The AuthorizeID field in the Digital Receipt is another identifier that is
passed in the Digital Receipt and sent by the issuing bank for the
authorisation. This field cannot be searched for in Merchant
Administration or AMA but it is displayed in Merchant Administration
as the "Authorisation Code". It is one of the fields returned in an AMA
query and the AMA transaction result (captures, refunds).
Version 2.23
49
'
!
Each transaction and/or query requires data or information to be provided to
perform 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 by
the Payment Client.
Supplementary command provides the primary command with the
data required for the transaction/query to be implemented.
The combination of the primary and supplementary command allows a
particular functionality (for example, captures and refunds) to be available.
Multiple functions can be implemented on the one primary command by
using multiple supplementary commands.
For example, a ticket number is added to a 3 Party transaction, a secondary
command (addDigitalOrderField) is used multiple times to present the data
to the Payment Client. When all the required data for the functionalities has
been passed to the Payment Client, the 3 Party primary command
(getDigitalOrder) is used to generate the digital order. These extra functions
extend the underlying 3 Party transaction to include 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)
Query a transaction to retrieve its digital receipt (doQueryDR)
For more information on which primary command is relevant to the
functionality being implemented, please refer to the relevant section in this
chapter.
To find out which primary command is relevant to the functionality being
implemented, please refer to the section describing that functionality later in
this chapter.
1. 3 Party transactions use a slightly modified transaction flow. Please refer to the transaction
flow explanation later in this chapter. All other transactions use the basic transaction flows
outlined in the Results section in this chapter.
Version 2.21
50
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 the
transaction. For example, a payment request returns a digital receipt
containing a set of values that is used to process the payment request, such as
the QSIResponseCode to indicate whether the request was successful or not.
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.
Version 2.23
51
%
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 (also applicable to QueryDR).
The following process is used to perform a transaction:
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 only used after the nextResult to
retrieve an error message from the Payment
Client to explain the failure of the nextResult.
9. This step is only used to retrieve a processing
error message from the Payment Client to
explain if the QSIResponseCode = 7.
10. This step is used to perform appropriate error
handling.
handling.
Single result transaction process
!?
Version 2.23
!
52
A transaction that is not successfully processed produces errors that can be

detected 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 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 shop and buy application. Also check the networking hardware and
configuration to determine whether or not there is a hardware failure.
3. 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.
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 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 4 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 5 Executing the nextResult command
Errors that occur executing the nextResult command means the Payment
Server has detected an error in processing the Digital Order.
To determine the error in Java or COM the command
getResultField(PaymentClient.Error) is used. In sockets the command 4,
PaymentClient.Error\n is used. These commands return the error code and
description of the error.
Step 6 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.
Version 2.23
53
'
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:
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.
9. This step is only used after 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).
handling.
11. This step is used to perform appropriate error handling.
12. This step is used to perform appropriate error handling.
Version 2.23
54
Multiple result query process
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.
"
All the transactions/queries, other than 3 Party transactions, follow the
processes 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 each
transaction/query is described.
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 (3) instances of
this command are required to add the following information prior to
performing the sendMOTODigitalOrder primary command.
1. 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.
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 value
would 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. This
identifier can use text made up of any of the base US ASCII characters
in the range, hexadecimal 20 to 126. It is important to make sure this
number 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
Version 2.23
55
#&
'
This primary command requires the following information:

1. 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.
2. Merchant Identification Number (MerchantId).
The merchant ID is an alphanumeric identifier that is given to the
merchant during the banks 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.
3. Purchase Amount (PurchaseAmountInteger)
The purchase amount of the transaction expressed as an integer in the
lowest currency denominator, for example, pence, cents, lire, yen, etc. It
does not contain any decimal points, thousands separators or currency
symbols, 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 (empty
string).
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
Version 2.23
56
The 2 Party transaction returns the following fields in the Digital receipt
received by the Payment Client if the transaction was processed.
1. Merchant Transaction Reference Number (MerchTxnRef)2
This is the input value passed back in the receipt and is the reference
number 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 simple
order number or shopping basket number.
3. Merchant Identification Number (MerchantId)
This is the input value passed back in the receipt and is an alphanumeric
identifier that is given to the merchant during the banks 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.
This is the input value passed back in the receipt and is the purchase
amount of the transaction expressed as an integer in the lowest currency
denominator, for example, pence, cents, lire, yen, etc. It does not contain
any decimal points, thousands separators or currency symbols, for
example. $12.50 is expressed as 1250.
5. QSI Response Code (QSIResponseCode)
A single character response code that is generated by the CommWeb
Payment Server. A QSI Response Code 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.
6. Issuers Response Code (AcqResponseCode)
The response code that is generated by the issuing bank. It is included
for faultfinding purposes, to determine to specific reason for the decline
from the issuer. See Issuer Response Code Mapping.
7. Payment Server Transaction Number (TransactionNo)
A unique number generated by the Payment Server. It is important to
make sure the TransactionNo is stored for later retrieval if required to
perform queries or Advanced Merchant Administration commands for
example refunds.
8. Transaction Receipt Number (ReceiptNo)
The RRN is a unique number generated by CommWeb. This is the value
that is passed back to the customer for their records if the merchants
application does not provide its own receipt number.
9. Authorisation Identification Code (AuthoriseId)
A code supplied by the card issuer to approve or deny a transaction.
2 These values should reflect the values input in the Digital Order. If they are not the same as the
input values then the Digital Order or the Digital receipt has been fraudulently tampered with.
Version 2.23
57
10. 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.
11. 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.
Where a transaction is not processed successfully, errors can be detected at
various stages to indicate the reason for the error. The process is described
later in this chapter.
A payment in a 2 party transaction consists of 2 main parts. The first is to

create and send the Digital Order and the second is to 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 language, as it is the process used that is important.
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.
#
&
To instantiate the Payment Client, an example of the API call to create the
Payment Client is:
// Instantiate a Payment Client
PaymentClientImpl objPayClient = new PaymentClientImpl();
The variable objPayClient is a local variable to this shop and buy

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
Version 2.23
58
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.
To test the Payment Client, an echo command is used which returns the string
value you send with the echo command appended to the string echo: This
test ensures that the Payment Client object has been instantiated correctly and
that a communications path has been established and is functioning properly
between the Payment Client and this shop and buy application.
An example of the Java call to perform the echo test and check for a valid
response is:
// Test the Payment Client object created correctly
String result = objPayClient.echo("Test");
if (!result.equals("echo:Test")) {
// perform error handling for this command
return;
}
The contents of the if statement performs the actions for your

implementation. It may be very simple, such as, an error is displayed and
processing is terminated. For a production implementation a more
sophisticated response may be warranted.
)
Extra digital order fields must be added before the API call to send the digital
order, as the API call collects all the digital order data that the Payment Client
has been sent and it creates the complete encrypted digital order. For a
standard 2 party digital order, the minimum extra data that must be included
to create a valid digital order are Card Number, Card Expiry date and
MerchTxnRef.
An example of adding the extra fields is:
// Add card fields to Digital Order
objPayClient.addDigitalOrderField("CardNum", cardNumber);
objPayClient.addDigitalOrderField("CardExp", cardExpiry);
objPayClient.addDigitalOrderField("MerchTxnRef", MerchTxnRefValue);
&
The Payment Client collects all the data that it has been sent and encrypts it to
create the digital order.
All the 2 Party primary commands like sendMOTODigitalOrder are
synchronous calls (they block the Payment Client thread until they are able to
return a result success or failure).
An example of the code to create and send the digital order should is:
Version 2.23
59
if (!objPayClient.sendMOTODigitalOrder(SessionID, MerchantID, PurchaseAmountInteger, en, )) {

return
}
The content of the if statement should perform the actions for your
implementation. It may be very simple, such as, an error is displayed and
processing is terminated. For a production implementation a more
&
After the digital order has been processed you need to ensure that the
Payment Client has received a valid digital receipt from the Payment Server
and that there are results to process. To do this, use the nextResult API
command.
An example of checking if a valid digital receipt has been received is:
// Get the nextResult value to check there are results to process.
if (!objPayClient.nextResult()) {
// retrieve the error description from the Payment Client
String error = objPayClient.getResultField("PaymentClient.Error");
return
}
The content of the if statement perform the actions for your implementation.
It may be very simple, such as, an error is displayed and processing is
terminated. There is an extra step in this if statement as you can now receive
an error description from the Payment Client to explain why the transaction
did not return a valid digital receipt. This error description may not always
contain data, as it may be an empty string ().
8
Now that a valid digital order exists, you need to retrieve the digital receipt
details from the Payment Client. To do this you use the getResultField() API
command.
An example of retrieving each result is:
// Get the results for each of the receipt variable required.
// Start with the QSIResponseCode and check for an error condition
String qsiCode = objPayClient.getResultField("DigitalReceipt.QSIResponseCode");
if (!qsiCode.equals(0) {
// perform error handling to find out why transaction failed
return
} else {
String merchantID
= objPayClient.getResultField("DigitalReceipt.MerchantId");
String orderInfo
= objPayClient.getResultField("DigitalReceipt.OrderInfo");
String merchantRefNo= objPayClient.getResultField("DigitalReceipt.MerchTxnRef");

String txnAmount
Version 2.23
= objPayClient.getResultField("DigitalReceipt.PurchaseAmountInteger");
60
String receiptNo
= objPayClient.getResultField("DigitalReceipt.ReceiptNo");
String transNo
= objPayClient.getResultField("DigitalReceipt.TransactionNo");
String acqCode
= objPayClient.getResultField("DigitalReceipt.AcqResponseCode");
String authoriseID = objPayClient.getResultField("DigitalReceipt.AuthorizeId");

String batchNumber = objPayClient.getResultField("DigitalReceipt.BatchNo");
String cardType
= objPayClient.getResultField("DigitalReceipt.CardType");
Normally, these receipt variables would not be declared at this point of the
shop and buy application, but would have been defined earlier. You now need
to return these values to the application that called the payment process.
To check if the payment request was successful the QSIResponseCode is
checked. Any value other than 0 (zero) is a failed transaction, see list of
QSIResponseCodes in the Payment Client Reference Guide.
The following code blocks are not complete and would not compile. Java
extras like retrieving input variables and try/catch blocks have been omitted
for the sake of readability, but the principles of how the code works is correct.
An example of putting all these code extracts together, and the application
becomes:
// Step 1 - Connect to the Payment Client
// **************************************
// create a Payment Client object
objPayClient = new PaymentClientImpl();
// Step 2 - Test the Payment Client object was created successfully
// ****************************************************************
// Test the communication to the Payment Client using an "echo"
result = objPayClient.echo("Test");
// Display error as communication to the Payment Client failed
return;
}
// Step 3 - Prepare to Generate and Send Digital Order
// ***************************************************
// The extra details are not accepted by the
// sendMOTODigitalOrder() method and so we must add them
// explicitly here for inclusion in the DO creation.
// Adding the supplementary data to the DO is done using the
//"addDigitalOrderField" command
// add MerchTxnRef number
objPayClient.addDigitalOrderField("MerchTxnRef", merchTxnRef);
Version 2.23
61
// Step 4 - Generate and Send Digital Order (& receive DR)

// *******************************************************
// Create and send the Digital Order
// (This primary command also receives the Digital Receipt)
if (!objPayClient.sendMOTODigitalOrder(orderInfo, merchantID, amount, "en", "")) {
// Retrieve the Payment Client Error (There may be none to get)
result = objPayClient.getResultField("PaymentClient.Error");
if (result != null && result.length() != 0) {
exception = result;
}
return;
}
// Step 5 - Check the DR to see if there is a valid result
// *******************************************************
// Use the "nextResult" command to check if the DR contains a result
exception = result;
}
return;
}
// Step 6 - Get the result data from the Digital Receipt
// *****************************************************
// Extract the available Digital Receipt fields
// Get the QSI Response Code for the transaction
String qsiResponseCode = objPayClient.getResultField("DigitalReceipt.QSIResponseCode");
if (qsiResponseCode == null || qsiResponseCode.length() == 0) {
return;
}
// Check if the QSI Response Code is an error message
// an error message has a response code of '7'
if (qsiResponseCode.equals("7")) {
// Get the error returned from the Payment Client
result = objPayClient.getResultField("DigitalReceipt.ERROR");
exception = result;
Version 2.23
62
}
return;
}
// The example retrieves the MerchantID and CapturedAmount values,
// which should be the same as the values sent. In a production
// system the sent values and the receive values could be checked to
// make sure they are the same.
String merchanttxnRef = objPayClient.getResultField("DigitalReceipt.MerchTxnRef");
String orderinfo
String merchantId
String purchaseAmount = objPayClient.getResultField("DigitalReceipt.PurchaseAmountInteger");

String receiptNo
String acqResponseCode = objPayClient.getResultField("DigitalReceipt.AcqResponseCode");

String authorizeID
= objPayClient.getResultField("DigitalReceipt.AuthorizeId");
String batchNo
= objPayClient.getResultField("DigitalReceipt.BatchNo");
String transactionNo
String cardType
The following Sockets implementation code block is not complete and would
not compile. Java extras like importing the Java libraries, retrieving input
variables from the order form and try/catch blocks have been omitted for
readability, but the principles of how the code works is correct if these extras
were added it would be fully functional. The related commands for the
sockets interface are shown in Appendix 1.
An example of the code is:
// **************************************
// Create a socket object to the Payment Client
Socket sock = new Socket(payClientIP, payClientPort);
// The Buffered Reader data input stream from the socket
BufferedReader in = new BufferedReader( new InputStreamReader(sock.getInputStream()));
// The output stream to the socket
PrintStream out = new PrintStream(sock.getOutputStream());
// ****************************************************************
out.print("1,Test\n");
cmdResponse = in.readLine();
if (!cmdResponse.equals("1,echo:Test")) {
Version 2.23
63
sock.close();
return;
}
// ***************************************************
// sendMOTODigitalOrder() method and so we must add them
out.print("7,CardNum," + cardNumber + "\n");
// check the status to make sure the command completed OK
if (!cmdResponse.equals(1,1)) {
sock.close();
return;
}
// card expiry date data
out.print("7,CardExp," + cardExpiry + "\n");
sock.close();
return;
}
// merchant transaction reference data
out.print("7,MerchTxnRef," + MerchTxnRefValue + "\n");
sock.close();
return;
}
// *******************************************************
out.print("6, + OrderInfo + , + MerchantID + , + PurchaseAmountInteger+ ,en,\n);
out.print("4,PaymentClient.Error\n");
Version 2.23
64
// check the first status char of the return message as the second field may have data
if (cmdResponse.substring(0,1).equals(1)) {
exception = cmdResponse.substring(2);
}
sock.close();
return;
}
// *******************************************************
out.print(5\n);
out.print("4,PaymentClient.Error\n);
}
sock.close();
return;
}
String qsiResponseCode = "";
out.print(4,DigitalReceipt.QSIResponseCode);
if (!cmdResponse.substring(0,1).equals(1)) {
// Display an Error Page as the QSIResponseCode could not be retrieved
sock.close();
return;
} else {
qsiResponseCode = cmdResponse.substring(2);
}
// Check if the result is an error message
Version 2.23
65
out.print(4,DigitalReceipt.ERROR);
// The response is an error message so display an Error Page
sock.close();
return;
}
}
// *****************************************************
// Also Extract the other available Digital Receipt fields
// The example retrieves the MerchantID and Amount values,
out.print(4,DigitalReceipt.MerchTxnRef\n);
merchTxnRef = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.OrderInfo\n);
orderInfo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.MerchantId\n);
merchantID = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.PurchaseAmountInteger\n);
amount = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.TransactionNo\n);
transactionNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.ReceiptNo\n);
receiptNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.AcqResponseCode\n);
acqResponseCode = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.AuthorizeId\n);
Version 2.23
66
authorizeID = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.BatchNo\n);
batchNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.CardType\n);
cardType = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
// Step 7 - We are finished with the Payment Client so tidy up
// ***********************************************************
// Close the socket connection to the Payment Client
sock.close();
This code has been written without methods/subroutines that would reduce
the duplication of code. It demonstrates how the six steps come together.
Version 2.23
67
+
'
The transaction flow for a 3 Party transaction consists of two
sections, the Digital Order (DO) and Digital Receipt (DR).
A 3 party transaction sends a message to the Payment Server
through redirecting the customers browser using a URL that
contains an encrypted and signed digital order. When the
order has been processed, the customers browser returns to
the merchants web site with the digital receipt as a URL
encoded variable in the browser.
The two separate transaction flows for a 3 party transaction
are:
1. Creating and sending the Digital
Order.
2. Receiving and processing the Digital
receipt.
1.
Connect to the Payment Client,

depending on the implementation
being used, Java/COM or sockets.
2. An echo test is performed to check that communication
has been established correctly with the Payment Client.
3. Any supplementary data for the functionality being used
is now sent to the Payment Client. For a base 3 party
transaction, this only includes the Merchant Transaction
Reference Number. Please refer to the functionality being
used to determine the data requirements.
4. The primary command getDigitalOrder is sent to the
Payment Client, which then creates the Digital Order and
returns it to the shop and buy application as the result of
the getDigitalOrder command.
6. The URL data string returned by the getDigitalOrder
command is a pre-formatted Payment Server URL that
redirects the customers browser and dictates which page
in the Payment Server the customers browser connects to.
It contains an encrypted Digital Order that can only be
decoded by the Payment Server. For an example of a
Digital Order, refer to page 31.
7. If the getDigitalOrder command retrieves an error
message from the Payment Client. The getResultField
command is used to retrieve the error description
(retrieved using the field name PaymentClient.Error). Error handling is detailed in the
Version 2.23
68
following pages.
8. This step is used to perform all appropriate error handling.
For details on the commands used with the Payment Client, please refer to the
Payment Client Reference Manual.
Version 2.23
69
If a digital order is not created successfully, errors and reasons for errors can
be detected at each of the following steps and actions taken.
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 is not installed correctly.
port. Verify that the PCService is running on the host and the port
specified in your shop and buy application. Also check the networking
hardware and configuration to determine if this is a hardware failure.
not correctly entered into the JVM classpath for a Java implementation
and therefore the Payment Client object cannot be instantiated.
and it cannot be found to be invoked.
Please refer to the Payment Client Installation Guide for detail on
installation procedures and trouble-shooting.
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.
To discover the error in Java or COM the command
getResultField(PaymentClient.Error) is used. In sockets the command 4,
PaymentClient.Error\n is used. These commands return the error code and
description of the error.
For full details on the error codes, please refer to the Payment Client
Reference Manual.
Version 2.23
70
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
Version 2.23
1. Extract the Digital Receipt from

the incoming URL. Check if the
DR consists of a String that is
greater than 0 characters in
length.
Connect to the Payment Client, depending on the
implementation being used, Java/COM or sockets.
An echo test is performed to check that
communication has been established correctly with
the Payment Client.
The primary command decryptDigitalReceipt is sent
to the Payment Client, which then decrypts the
digital receipt.
The nextResult command is used to check if the
transaction contains valid results. If there were errors
go to step 8.
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.
Disconnect from the Payment Client.
This step is only used after the nextResult to retrieve
an error message from the Payment Client to explain
the failure of the nextResult.
This step is only used to retrieve a processing error
message from the Payment Client to explain if the
QSIResponseCode = 7.
This step is used to perform appropriate error
handling.
This step is used to perform appropriate error
handling.
71
3 Party Digital receipts Process
If a digital order is not created successfully, errors can be detected at various

stages to indicate the reason for the error. At each of the following steps,
actions may be taken to determine the appropriate error conditions.
Step 1 Extract the digital receipt from the incoming URL.
If this step fails or the digital receipt is empty (the length of the digital receipt
is zero), all you can do is terminate the transaction. All other session variables
may not be in the URL so all you can do is display an error page to the
customer.
Common errors that can cause a connection failure are:
1. The customer has modified the URL in their browsers address bar and
removed the digital receipt.
2. The web server used by the merchant may have removed the URL
encoded digital receipt variable.
3. The digital receipt has been subject to fraud and has been tampered
with.
Step 2 Cannot connect to the Payment Client.
Errors that can cause a Payment Client connection failure are:
1. The Payment Client is not installed correctly.
port. Verify that the PCService is running on the host and the port
specified in your shop and buy application. Also check the networking
hardware and configuration to determine if this is a hardware failure.
not correctly entered into the JVM classpath for a Java implementation
and therefore the Payment Client object cannot be instantiated.
therefore it cannot be found to be invoked.
Although the merchant cannot rectify these problems, they should perform a
QueryDR command to resolve any outstanding transactions. This allows you
to find the transaction and deal with it appropriately.
installation procedures.
If this step has been reached but the echo test fails, the Payment Client is not
able to communicate or execute commands correctly. The errors likely to
cause this are the same as those listed in Step 2.
Version 2.23
72

installation procedure.
Step 5 Executing the nextResult command
When an error occurs, it means the Payment Server has detected an error in
processing the digital Order. To discover the error in Java or COM the
command getResultField(PaymentClient.Error) is used.
In sockets the command 4, PaymentClient.Error\n is used.
Step 6 Checking if the QSIResponseCode = 7
If the Payment Server has detected a 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.
0
The supplementary command is in the format of a String value that
represents a key, followed the data value for that key. One (1) instance of this
command is required to add the following information prior to performing the
getDigitalOrder command.
For detailed information on supplementary command for your locale, please
refer to the Payment Client Reference Manual.
5. Merchant Reference transaction Number (MerchTxnRef).
The merchant can use this field to uniquely identify the transaction. This
identifier can use text made up of any of the base US ASCII characters
in the range, hexadecimal 20 to 126. It is important to make sure this
number 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(MerchTxnRef, merchTxnRefValue)
In Sockets they take the form:

Version 2.23
73
7, MerchTxnRef, + merchTxnRefValue + \n
0
This primary command only requires one data field the encrypted Digital
receipt being returned from the Payment Server to the Payment Client to be
decrypted to allow the merchant to retrieve the information contained within
it.
In Java and COM it takes the form:
decryptDigitalReceipt(encryptedDigitalReceipt)
In Sockets it takes the form:

3, + encryptedDigitalReceipt + \n
3 Party transaction returns the following fields in the Digital receipt received
by the merchant and passed to the Payment Client when the customers
browser is re-directed back to their site:
1. Merchant Transaction Reference Number (MerchTxnRef)3
This is the input value passed back in the receipt and is merchants
reference number allocated by the merchants software. This code
should be unique for every transaction.
2. Order Information Number (OrderInfo)
This is the input value passed back in the receipt and is the merchants
information about this transaction. Can be a simple order number or
shopping basket number.
3. Merchant Identification Number (MerchantId)
This is the input value passed back in the receipt and is an alphanumeric
identifier that is given to the merchant during the banks 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
This is the input value passed back in the receipt and is amount of the
transaction expressed as an integer in the lowest currency denominator,
for example, pence, cents, lire, yen, etc. It does not contain any decimal
points, thousands separators or currency symbols, for example. $12.50 is
expressed as 1250.
5. Locale (Locale)
This is the input value passed back in the receipt and it specifies the
3 These values should reflect the values input in the Digital Order. If they are not the same as the
input values then the Digital Order or the Digital receipt has been fraudulently tampered with.
Version 2.23
74
language that is used on the Payment Server pages that are displayed to
the customer. For English, a value of en is used. CommWeb only
supports English.
6. QSI Response Code (QSIResponseCode)
A single character response code that is generated by the Payment
Server. A QSI Response Code of 0 (zero) indicates that the transaction
was processed successfully and approved by the issuing 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.
7. Issuers Response Code (AcqResponseCode)
The response code that is generated by the issuing bank. It is included
for faultfinding purposes, to determine to specific reason for the decline
from the issuer. See Issuer Response Code Mapping
8. Payment Server Transaction Number (TransactionNo)
A unique number generated by the Payment Server. It is important to
make sure the TransactionNo is stored for later retrieval if required to
perform queries or Advanced Merchant Administration commands for
example refunds.
9. Transaction Receipt Number (ReceiptNo)
The RRN is a unique number generated by CommWeb. This is the value
that is passed back to the customer for their records if the merchants
application does not provide its own receipt number.
10. Authorisation Identification Code (AuthoriseId)
A code issued by the card issuer to approve or deny a transaction.
11. Transaction Batch Number (BatchNo)
The Batch number on the Payment Server that this transaction will be
added to in order to be processed by CommWeb.
12. Card Type (CardType)
This is the input value passed back in the receipt and 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.
If a transaction is not processed successfully, errors can be detected at various
stages to indicate the reason for the error.
A payment in a 3 party transaction consists of 2 main parts. The first is to

create and send the digital Order and the second is to retrieve and extract the
Digital receipt details. This tutorial focuses on conducting a 3 party
transaction using the Java Payment Client API calls. Please refer to the
Payment Client Reference Manual for more details on commands. However
the steps used in this tutorial can be applied to any language as it is the
process used that is important.
To create and send the digital order in a 3 party transaction there are five
main steps to follow.
1. Instantiate and test the Payment Client.
Version 2.23
75
2. Perform echo test with the Payment Client.

3. Add all the extra Digital Order details that are not included in the
getDigitalOrder API command.
4. Create the Digital Order using the getDigitalOrder API command.
5. Re-direct the customers browser to the Payment Server with the Digital
Order.
To retrieve and extract the digital receipt details in a 3 party transaction there
are six main steps to follow.
6.
7.
8.
9.
Retrieve the encrypted digital receipt.

Instantiate and test the Payment Client.
Perform echo test with the Payment Client
Decrypt the digital receipt to be processed using the
decryptDigitalReceipt API command.
10. Check there is a valid result.
11. Retrieve the digital receipt details.
To reduce the duplication in the tutorial, the common steps - instantiate and
test the Payment Client, perform echo test with the Payment Client are
described in the section describing how to create and send the digital order.
%
,
#
&
To instantiate the Payment Client, an example of the API call to create the
Payment Client is:
The variable objPayClient is a local variable to the Payment Client and may
be changed to any name that suits the implementation, but for this tutorial, the
Payment Client object will continue to be called 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 hasnt been created successfully.
#
&
To test the Payment Client an echo command is used which will return the
string value you send with the echo command appended to the string echo:.
This test ensures that the Payment Client object has been instantiated
correctly and that a communications path has been established and is working
properly between the Payment Client and the shop and buy application.
response is:
Version 2.23
76

return;
}
The contents of the if statement should perform the actions appropriate to

your implementation. It may be very simple, such as, an error is displayed
and processing is terminated. For a production implementation a more
)
Extra digital order fields must be added before the API call to create the
digital order is made. This is because the API call, getDigitalOrder collects
all the data that the Payment Client has been sent, and it creates the complete
encrypted digital order. If extra fields are not sent before this call then they
will not be included in the digital order when it is created. For a standard 3
party transaction there is no extra data that must be included to create a valid
digital order, however when implementing some advanced functionality you
may be required to add extra data here.
An example of adding the extra fields is:
// add Merchant Transaction Reference value
objPayClient.addDigitalOrderField("MerchTxnRef", merchTxnRefValue);
&
In the creation of the digital order, the Payment Client collects all the data
that it has been sent and encrypts it to create the digital order. The API call
must contain 5 variables in the correct order.
An example of the API command to create the digital order is:
// create the Digital Order
String digitalOrder = objPayClient.getDigitalOrder(orderInfo, merchantID,
purchaseAmountInteger, locale, returnURL)
// check that a valid Digital Order was created
if (digitalOrder == null || digitalOrder.length() == 0) {
}
To test if the command getDigitalOrder has in fact been run successfully in

Java you would use a try/catch statement to catch any errors in the creation of
the object. In other languages such as Visual Basic you may use statements
like the On Error statement to determine if the Object has not been created
successfully.
Version 2.23
77
The content of the if statement should perform the actions appropriate to

and processing is terminated. For a production implementation a more
!
The last step of the process is to send the encrypted digital order to the
Payment Server, which is done via a customers browser redirect. This allows
the customers browser to work directly with the acquiring institutions
Payment Server, so the customer can provide their card details directly to
them.
// Transmit the DO to the Payment Server via a browser redirect
res.sendRedirect(digitalOrder);
for the sake of readability, but the principles of how the code block works is
correct.
Putting all these code extracts together the application becomes:
D 8
?6

// ***************************************
// ****************************************************************
return;
}
// ***************************************************
// getDigitalOrder() method and so we must add them
// "addDigitalOrderField" command
// add MerchTxnRef number
objPayClient.addDigitalOrderField("MerchTxnRef", merchTxnRef);
Version 2.23
78
// Step 4 - Generate and Send Digital Order

// ****************************************
digitalOrder = objPayClient.getDigitalOrder(orderInfo, merchantID, amount, locale, returnURL);
if (digitalOrder != null && digitalOrder.length() == 0) {
exception = result;
}
// Display an Error Page as the Digital Order was not processed
return;
}
// At this point the customers browser is sent to the Payment Server
// using the URL at the start of the Encrypted Digital Order
not compile. Java extras like importing the Java libraries, and try/catch blocks
have been omitted to make the code block example easier to read, but if these
extras were added it would be fully functional. The related commands for the
sockets interface are shown in Appendix 1.
D 8
&
// This shows how to add sessionIDs to the returnURL

// In this case we have added the Payment Client IP address and Port to the returnURL
// so the Digital Receipt Servlet knows where the Payment Client is, and its port.
// However, session variables to identify the customer session can be added this same way.
// It is good practice to URL encode these variables
// so they can be transmitted without error via HTTP protocol
returnURL = returnURL + URLEncoder.encode(&PCMachineIP =" + pcMachineIP + "& PCPort =" + pcPort);
// **************************************
Version 2.23
79

// ****************************************************************
sock.close();
return;
}
// ***************************************************
// getDigitalOrder() method and so we must add them
// add merchant transaction reference data
sock.close();
return;
}
// Step 4 - Generate and Send Digital Order
// ****************************************
out.print("2, + orderInfo + , + merchantID + , + purchaseAmountInteger+ , + locale +
, + returnURL + \n);
}
sock.close();
return;
}
// Get the Digital Order
Version 2.23
80
digitalOrder = cmdResponse.substring(2);
// At this point the customers browser is sent to the Payment Server
// using the URL at the start of the Encrypted Digital Order
// ***********************************************************
// Close the socket connection to the Payment Client
sock.close();
the duplication of code. It demonstrates how the six steps come together in a
form that is easily followed.
,
8
The Digital receipt is returned to the merchant via the customers browser as
a standard HTML query string parameter with the name DR. The digital
receipt is retrieved in the same manner as standard HTML form variable. We
then perform a simple check to ensure the parameter contains data.
// Extract the encrypted Digital receipt from the request. Note that
// the default redirection from the Payment Server contains a
// parameter "DR" which was sent as part of the DO in the ReturnURL field.
encryptedDR = req.getParameter("DR");
if (encryptedDR == null || encryptedDR.length() == 0) {
/ perform error handling for a bad Digital receipt and return
}
&
To instantiate the Payment Client, the API call to create the Payment Client
should look similar to:
&
To test the Payment Client, use an echo command to return the string value
you send appended to the string echo:.
response is:
Version 2.23
81

// perform error handling for this command and return
return;
}
To decrypt the digital receipt, the primary command decryptDigitalReceipt is

used. There is only one input parameter, the encrypted digital receipt. An
example of the code is:
// Decrypt the Digital receipt
objPayClient.decryptDigitalReceipt(encryptedDR);
&
When the digital order has been processed you need to ensure that the
Payment Client has received a valid digital receipt from the Payment Server
and that there are results to process. To do this, use the nextResult API
command.
An example of checking that a valid digital receipt has been received is:
// Get the nextResult value to check there are results to process.
String error = objPayClient.getResultField("PaymentClient.Error");
return;
}
The content of the if statement should perform the actions appropriate to

and processing is terminated. There is an extra step in this if statement to
others that have been shown as we are now able to receive an error
description from the Payment Client to explain why the transaction did not
return a valid digital receipt. This error description may not always contain
data, as it may be an empty string ().
8
From the valid digital order, you need to retrieve the digital receipt details
from the Payment Client. To do this, use the getResultField() API command.
An example of retrieving each result is:
// Get the results for each of the receipt variable required.
String qsiCode = objPayClient.getResultField("DigitalReceipt.QSIResponseCode");
if (!qsiCode.equals(0) {
Version 2.23
82
// perform error handling to find out why transaction failed

} else {
String merchantID
String orderInfo
String merchantRefNo = objPayClient.getResultField("DigitalReceipt.MerchTxnRef");

String txnAmount
String receiptNo
String transNo
String acqCode
= objPayClient.getResultField("DigitalReceipt.AcqResponseCode");
String authoriseID
String batchNumber
The integrator must now return these values to the application that called the
payment process.
To check if the payment request was successful, you need to check the
QSIResponseCode. Any value other than 0 (zero) means the transaction has
failed. A complete list of QSIResponseCodes is shown and described in the
Payment Client Reference Manual.
to make it easier to read, but the principles of how the code block works is
correct.
Putting the code extracts together, the application becomes:
D 8
?6
// Extract the encrypted Digital Receipt from the request. Note that
if ((encryptedDR = req.getParameter("DR")) == null) {
return;
}
// ***************************************
// ****************************************************************
return;
Version 2.23
83
}
// Step 3 - Decrypt Digital Receipt
// ********************************
if (!objPayClient.decryptDigitalReceipt(encryptedDR)) {
exception = result;
}
return;
}
// *******************************************************
exception = result;
}
// Display an error as the DR doesn't contain a result
return;
}
// *****************************************************
// Display an error as QSIResponseCode could not be retrieved
return;
}
Version 2.23
84
exception = result;
}
// The response is an error message so generate an Error Page
return;
}
String merchTxnRef = objPayClient.getResultField("DigitalReceipt.MerchTxnRef");
String orderinfo
String merchantId
String purchaseAmount = objPayClient.getResultField("DigitalReceipt.PurchaseAmountInteger");

String receiptNo

String authorizeID
String batchNo
String cardType

// ***********************************************************
// nothing to be done in Java
not compile. Java extras like importing the Java libraries, retrieving input
variables from the order form and try/catch blocks have been omitted to make
it easier to read, but if these extras were added it would be fully functional.
D 8
&
// Extract the encrypted Digital Receipt from the request. Note that
if ((encryptedDR = req.getParameter("DR")) == null) {
return;
}
// get Payment Client IP Address and Port number that was sent appended to the returnURL
String pcMachineIP = req.getParameter("PCMachineIP");
Version 2.23
85
String pcPort = req.getParameter("PCPort");

// convert to integer required for creating socket command
int payClientPort = Integer.parseInt(pcPort);
// **************************************
// ****************************************************************
sock.close();
return;
}
// Step 3 - Decrypt Digital Receipt
// ********************************
out.print(3, + encryptedDR + \n);
}
sock.close();
return;
}
// *******************************************************
Version 2.23
86

out.print(5\n);
}
sock.close();
return;
}
out.print(4,DigitalReceipt.QSIResponseCode);
sock.close();
return;
} else {
}
out.print(4,DigitalReceipt.ERROR);
// The response is an error message so display an Error Page
sock.close();
return;
}
}
// *****************************************************
Version 2.23
87
// Also Extract the other available Digital Receipt fields

// The example retrieves the MerchantID and Amount values,
out.print(4,DigitalReceipt.MerchTxnRef\n);
merchTxnRef = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.OrderInfo\n);
orderInfo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
amount = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.CardType\n);
cardType = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
Version 2.23
88
// ***********************************************************
sock.close();
the duplication of code. It demonstrates how the six steps come together in a
form that is easily followed.
Version 2.23
89
- .
To implement the advanced features available on the Payment Server, you
need to add additional data to the digital order.
Additional fields are added using the addDigitalOrderField supplementary
command.
Multiple advanced features may be combined in the one digital order, but you
need to refer to page 129 to ensure that the functionality being implemented
can be combined together.
It is possible with some additional data returned in the digital receipt can be
accessed using the getResultField supplementary command.
1 23 112
The Card Security Code (CSC) is a security feature used for card not present
transactions that compares the Card Security Code on the card with the
records held in the card issuers database. On Visa (CVV2) and MasterCard
(CVC2) credit cards, it is the three-digit value printed on the signature panel
on the back following the credit card account number.
In a 2 party transaction, the card security code is sent with the digital order. In
a 3 party transaction the Payment Server requests this information from the
cardholder via the card details screen. In 3 party transactions, no extra
integration effort is required from the merchant as it is an integrated
part of the solution on the Payment Server side. From the Payment Server,
the CSC is sent along with the card details and transaction details for
authorisation. The issuer will approve or decline the transaction based on
whether there is sufficient funds etc, and also whether the CSC is correct, and
whether the transaction has gone through authentication.
NOTE: not all issuers support the CVC2/CVV2 feature. Issuers that do not
support CVC2/CVV2 will process the transaction as normal, ignoring any
CVC2/CVV2 value that is entered.
The CSC value can be added to 2 party digital orders via the
addDigitalOrderField supplementary command at the appropriate point in
their transaction flow. The field that needs to be added to the digital order is:
Fieldname
CardSecurityCode
Description
The Card Security Code entered by the cardholder. On
Visa and MasterCard credit cards, it is the three-digit
value printed on the signature panel on the back
following the credit card account number.
Card Security Code Digital Order field

Version 2.23
90
In Java or COM, an example of the additional code for implementing CSC is:
objPayClient.addDigitalOrderField("CardSecurityCode", cscValue);
In Sockets, an example of the additional code for implementing CSC is:

out.print("7,CardSecurityCode," + cscValue + "\n");
In 3 party transactions, the CSC value can be entered into the Card Details
screen at the Payment Server as illustrated below:
The CSC functionality does not return any extra fields in the digital receipt.
The end result of the authorisation is a decision to be made by the issuer.
Version 2.23
91
Ticket Number functionality allows the merchant to enter a ticket number in

the digital order to be stored for that transaction. Although the ticket number
was originally designed for the travel industry, it can be any alpha data about
the transaction up to the maximum length of the field (see Payment Client
Reference Manual).
It is available for both 2 Party and 3 Party transactions and the details are
provided in the digital order and stored in the Payment Server database. The
ticket number is not returned in the digital receipt.
The ticket number is added to 2 transactions using the addDigitalOrderField

supplementary command at the appropriate point (Step 3) as indicated in their
transaction flows.
The fields that need to be added to the digital order for ticket number
functionality are:
Fieldname
Ticket
Description
An alphanumeric field originally designed for airline
ticket numbers, but can be used by merchants for any
reference information in addition to the Order Info field.
Ticket Number Digital Order fields
In Java or COM, an example of the additional code for adding ticket number
is:
objPayClient.addDigitalOrderField("Ticket", ticketNumber);
In sockets, an example of the additional code for adding ticket number is:
out.print("7,Ticket," + ticketNumber + "\n");
Ticket number functionality does not return any extra fields in the digital
receipt, but the merchant can access this field through the Merchant
Administration interface on the CommWeb Server.
Version 2.23
92
MasterCard and Visa have introduced new authentication methods for

internet payments, which involves validating the presence of the cardholder in
a traditional internet card-not-present environment.
Essentially, this involves the cardholder entering a password known only to
themselves and their issuing bank during the course of the payment, similar to
the use of a PIN during an ATM transaction. This reduces the likelihood of
fraud and customer chargeback.
CommWeb supports the MasterCard initiative, SecureCode and the Visa
initiative, Verified by Visa, which authenticates the cardholder by
redirecting their internet browser to their card issuers authentication server,
which is accessible via the internet. Both SecureCode and Verified by Visa
implement an authentication process called 3D Secure, and CommWeb
supports the consolidation of both card scheme implementations of 3D
Secure. This consolidation makes the whole authentication process easier for
the merchant. CommWeb allows authentication to be performed without any
changes to the merchant request for payment process.
Authentication is performed as an integral part of an Authorization or
Purchase transaction.
From a cardholders experience, there is simply a new step added, where the
cardholder is redirected to the issuers 3DSecure Access Control Server (ACS)
and a password is inputted by the cardholder. If the password matches the
password selected by the cardholder at the point of enrolment in their Issuers
authentication program, then the transaction is considered authenticated and
payment can proceed.
If the cardholder does not enter the correct password, and therefore cannot
authenticate themselves, CommWeb will not proceed with the payment.
Other failures (for example, communication errors) may result in the
authentication attempt failing, but the payment going ahead. The general rule
is that if authentication is possible it will be performed, but if it is performed
it must succeed otherwise the payment will not be processed.
Note It is beyond the scope of this document to explain the full details
of the MasterCard SecureCode and Verified by Visa initiatives, the
processes involved in becoming registered in these programs, and under
what circumstances the liability for the transaction is shifted from the
merchant. Please contact your bank representative for more information.
Version 2.23
93
'
The CommWeb interaction with any other entity apart from the cardholder or
merchant is described for information only, as the merchant will only witness
passing of control to CommWeb and the return of authentication data if
authentication was attempted.
It is important to note than the merchant has no control over an authenication
attempt if he is configured for 3D Secure.
CommWeb will detect the submission of a MasterCard or Visa Card by the
cardholder and, if the merchant has been enabled for 3D Secure, CommWeb
will interigate the MasterCard or Visa Directory Service to check if the
cardholder is enroled in his issuer 3D secure program.
If the cardholder is not enroled, or the issuer does not support 3D Secure,
authorisation is performed as normal.
It the cardholder is enroled, the MasterCard or Visa directory service will
return the URL of the issuers ACS, and CommWeb will redirect the
cardholders browser to this ACS to allow the issuer to authenticate. The ACS
then returns the cardholders browser to CommWeb, along with the result of
the authentication attempt.
CommWeb will continue with the authorization of the transaction if the
authentication was sucessful.
Version 2.23
+#
'
94
3-Party 3D Secure Process Flow
For a 3-party transaction the merchant has no extra considerations on the

submission of the payment request, but needs to accept and record the new
3D Secure result fields, described later in this section and detailed in the
Payment Client Reference Guide.
+#
'
2-Party 3D Secure Process Flow
A 2-Party 3D Secure transaction is performed by using the standard 3-Party

Payment Client call, but providing the credit card type, number, and expiry
date as extended fields, allowing the credit card entry screens to be bypassed.
The cardholder experiences the process above, where control appears to be
passed straight from the merchant website to the issuer ACS, where in fact
control has been passed to CommWeb, who silently detects the card details in
the digital order, interigates the MasterCard or Visa Directory Service and
redirects the cardholder to the issuer ACS.
Version 2.23
95
The 3-Party and 2-Party Authentication and Payment combination uses the
basic 3-Party style of transaction.
If the merchant collects the card details (2-Party), the merchant can also add
an optional Description field to the Digital Order for an authentication
transaction.
This optional field is added using addDigitalOrderField(Fieldname, <field
value>) command.
If CommWeb is used to collect the card details, the merchant cannot use the
Description field as they do not collect the card details so they cannot add it to
the Digital Order.
The Input Fields for Authentication and Payment are:
FieldName
gateway
card
Description
Always set to ssl.
The value is either Visa or MasterCard.
CardNum
2-Party only. The number of the MasterCard or Visa Card collected by the
merchant.
It must not contain white space or formatting characters.
CardExp
The expiry date of the card in the format YYMM. The value must be expressed
as a 4-digit number (integer) with no white space or formatting characters, for
example, an expiry date of May 2009 is 0905.
An optional field that the merchant may supply in the Digital Order as a
description of the transaction.
Desc
Note: This is only used for Visa transactions and cannot be used for
MasterCard Secure Code. The field can only be used if the merchant collects the
card details (2-Party). If the CommWeb is used to collect the card details (3Party), the merchant cannot use the Description field as they do not collect the
card details so they cannot add it to the Digital Order.
Secure Input Fields for Authentication and Payment Transactions
Version 2.23
96
In Java or COM, an example of the additional code for adding Authentication and Payment
transactions is:
// Optional Authentication and Payment transaction field for Verified by Visa transactions
// Not used for MasterCard Secure Code
objPayClient.addDigitalOrderField("Desc", description);
// Modes 1 & 2 where Merchant collects card details for Mode 1 operation
objPayClient.addDigitalOrderField("gateway", "ssl");
objPayClient.addDigitalOrderField("card", cardValue);
In Sockets, an example of the additional code for adding Authentication and Payment
transactions is:
// Optional Authentication and Payment transaction field for Verified by Visa transactions
// Not used for MasterCard Secure Code
out.print("7,Desc," + description + "\n");
// Modes 1 & 2 where Merchant collects card details for Mode 1 operation
out.print("7,gateway,ssl\n");
out.print("7,card, + cardValue);
out.print("7,CardNum," + cardNumber + "\n");
out.print("7,CardExp," + cardExpiry + "\n");
If an authentication has failed, the QSI Response code, Authorisation Failed (F), is returned in
the Digital Receipt (DR).
If a 3-D Secure authentication has been successful, extra fields are returned in the Digital
Receipt. The fields below are not used by the merchant but are returned for the merchant to allow
them to store them as a record of authentication for the transaction and they can be used for
repudiation disputes. They cannot be used again for any future transactions.
Version 2.23
97
All Fieldnames are case sensitive.

The fields are returned using the getResultField("DigitalReceipt.Fieldname):
Fieldname
Description
VerType
Always 3DS.
Y =The cardholder was successfully authenticated.
E = The cardholder is not enrolled.
N = The cardholder was not verified.
U = The cardholders Issuer was unable to authenticate due to a
system error at the Issuer.
F = An error exists in the format of the request from the CommWeb.
A = Authentication of your Merchant ID and Password to the ACS
Directory Failed.
VerStatus
D = Error communicating with the Directory Server.

C = The card type is not supported for authentication.
S = The response received from the Issuer was not consider authentic..
P = Invalid format message from Issuer.
I = Internal CommWeb system error.
This field contains the security level to be used in the payment
message.
Visa 05 Fully authenticated
VerSecurityLevel
Visa 06 -
Not authenticated, (cardholder not participating),
Visa 07 -
Not authenticated
MasterCard 0 - Merchant not participating (A merchant should never

see this if they are configured for SecureCode)
MasterCard 1- Cardholder not participating
MasterCard 2- Cardholder authenticated
VerToken
The Accountholder Authentication Value (AVV MasterCard) or

Cardholder Authentication Verification Value (CAVV - Visa) generated
by the issuers Access Control Server as a token to prove that the
cardholder authenticated OK.
3DSXID
It is a unique transaction identifier that is generated by the merchant to

identify the transaction.
3DSECI
The 3D Secure Electronic Commerence Indicatort.
3DSenrolled
This field is only included if the card is within an enrolled range. This is
the value of the VERes.enrolled field. It will take values (Y - Yes, N - No,
U Unavailable for Checking).
3DSstatus
This field is only included if 3-D Secure authentication was used and a
PARes was received by the MPI. It will take values (Y Yes, N No,
A Attempted Authentication, U Unavailable for Checking).
3-D Secure Digital Receipt fields
Version 2.23
98
The ResponseCode is used to determine if the authentication passed or a failed.

If the ResponseCode is 0 (zero), the authentication transaction completed satisfactorily.
If the ResponseCode is F, the Authentication process failed.
In Java or COM, an example of the code for retrieving the 3-D Secure output fields from the
Digital Receipt is:
String cavv = objPayClient.getResultField("DigitalReceipt.VerToken");
String acqECI = objPayClient.getResultField("DigitalReceipt.3DSECI");
String xid = objPayClient.getResultField("DigitalReceipt.3DSXID");
String verType= objPayClient.getResultField("DigitalReceipt.VerType");
String verStatus = objPayClient.getResultField("DigitalReceipt.VerStatus");
String level = objPayClient.getResultField("DigitalReceipt.VerSecurityLevel");
String enrolled = objPayClient.getResultField("DigitalReceipt.3DSenrolled");
String status = objPayClient.getResultField("DigitalReceipt.3DSstatus");
In Sockets, an example of the code for retrieving the 3-D Secure output fields from the Digital
Receipt is:
out.print("4,DigitalReceipt.VerToken\n");
String cavv = in.readLine().substring(2);
out.print("4,DigitalReceipt.ACQECI\n");
String acqECI = in.readLine().substring(2);
out.print("4,DigitalReceipt.3DSXID\n");
String xid = in.readLine().substring(2);
out.print("4,DigitalReceipt.VerType\n");
String verType = in.readLine().substring(2);
out.print("4,DigitalReceipt.VerStatus\n");
String verStatus = in.readLine().substring(2);
out.print("4,DigitalReceipt.VerSecurityLevel\n");
String level = in.readLine().substring(2);
out.print("4,DigitalReceipt.3DSenrolled\n");
String enrolled = in.readLine().substring(2);
out.print("4,DigitalReceipt.3DSstatus\n");
String status = in.readLine().substring(2);
Version 2.23
99
- .
- -
The following section describes the flows for each AMA transaction/query,
and the data requirements for each stage of the transaction/query.
Most AMA transactions and some AMA query transactions, follow the base 2
Party transaction. This includes the AMA QueryDR transaction that only
returns a single result.
Some commands follow the transaction processes outlined in the Queries
that return multiple results.
AMA privilege for a user is set in the Operator Detail page in Merchant
Administration. AMA transactions must have a username, password and be
set up with AMA privileges to run an AMA transaction.
Tips for Advanced Merchant Administration:
1. All AMA transactions contain username and Password. This AMA
username cannot be used to perform normal Merchant Administration
functions.
2. In the privileges section of the Merchant Administration Operator Setup menu, select the "Enable advanced MerchantAdmin features"
checkbox.
Also check required transaction types the AMA user is required to use,
otherwise that transaction type will fail.
In AMA transactions the MerchTxnRef number should only be added to
transaction commands like capture, refunds, and voids, and not query
commands. It is added by an addAdminCommandField supplementary
command at the appropriate point (Step 3) as indicated in the transaction
flows. A merchant would add the MerchTxnRef number to enable them to
use the AMA QueryDR transaction (doQueryDR) to find lost digital receipts,
if required.
Version 2.23
100
The Admin Capture command allows an Auth/Capture mode merchant to

capture the funds from a previous run Auth transaction. This command is
not necessary or accepted if the merchant is operating in Purchase mode.
Most payment providers allow merchants to perform as many capture
transactions on the original Auth transaction, but the total amount captured
cannot be more than the amount specified in the original Auth transaction.
The Admin Capture inputs that are required are:

Fieldname
Description
The merchant should use a unique value for this
field to identify the transaction. This identifier
can use text made up of any of the base US
ASCII characters in the range, hexadecimal 20
to 126. This field is added using the
addAdminCommandField
MerchTxnRef
It is important to make sure this number is

stored safely for later retrieval if required as it
is used to track the progress of a transaction in
the event of a communications failure where
no Digital receipt is received.
Version 2.23
MerchantId
The merchant ID is an alphanumeric identifier

that is given to the merchant during the banks
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.
TransactionNo
The transaction reference number of the

original Auth transaction.
PurchaseAmountInteger
The purchase amount of the transaction

expressed as an integer in the lowest currency
denominator, for example, pence, cents, lire,
yen, etc. It does not contain any decimal points,
thousands separators or currency symbols, for
Username
The AMA username that can authorise the

operation of this capture transaction.
Password
The password for the AMA username.

101
AMA Capture Input Fields
The Admin Capture command returns a string of comma-delimited fields.

The number of fields returned may vary according the Payment Server being
used. Please refer to your payment provider for a complete list of the returned
fields. The fields are retrieved using the getResultField supplementary
command.
For more information on the output fields, please refer to the Payment Client
Reference Manual.
The following Java or COM implementation code block is not complete and
would not compile, but if these extras were added it would be fully
functional.
An example of the code extract for running a capture transaction is:
// ***************************************
// ****************************************************************
return;
}
// ***************************************************
// Add the Merchant Transaction Reference Number to the DO
// using the "addAdminCommandField" command
if (merchantTxnRef != null && merchantTxnRef.length() != 0) {
objPayClient.addAdminCommandField("MerchTxnRef", merchantTxnRef);
}
// *******************************************************
if (!objPayClient.doAdminCapture(merchantID, transactionNo, amount, username, password)) {
Version 2.23
102
exception = result;
}
// Display an Error Page as the Digital Order was not processed
return;
}
// *******************************************************
exception = result;
}
return;
}
// *****************************************************
return;
}
exception = result;
}
return;
}
// Get the result from the Digital Receipt
Version 2.23
103
result = objPayClient.getResultField("DigitalReceipt.Result");
// Check for an empty result
if (result == null || result.equals("")) {
// Display an Error Page as the DR contained an empty result
return;
}
String merchantId
String transactionNo = objPayClient.getResultField("DigitalReceipt.TransactionNo");
String receiptNo
String authorizeID
String batchNo
// ***********************************************************
AMA Capture Java/Com Example Code Extract
Version 2.23
104
The Admin Refund command allows a merchant to refund any funds from a
previous run capture transaction or purchase transaction.
The merchant can run any number of refund transactions on the original
transaction, however generally the total amount refunded cannot be more than
the amount specified in that original transaction.
The Admin Refund inputs that are required are:

Fieldname
Description
field to identify the transaction. This identifier
can use text made up of any of the base US
ASCII characters in the range, hexadecimal 20
to 126. This field is added using the
MerchTxnRef
It is important to make sure this number is

stored safely for later retrieval if required as it
is used to track the progress of a transaction in
the event of a communications failure where
no Digital receipt is received.
MerchantId
The merchant ID is an alphanumeric identifier

that is given to the merchant during the banks
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.
TransactionNo

PurchaseAmountInteger
The purchase amount of the transaction

expressed as an integer in the lowest currency
denominator, for example, pence, cents, lire,
yen, etc. It does not contain any decimal points,
thousands separators or currency symbols, for
Username

Password
AMA Refund Input Fields
In Java or COM, an example of the code for adding refund data is:
Version 2.23
105
// Step 3 - Add Merchant Reference Transaction number

objPayClient.addAdminCommandField("MerchTxnRef", MerchTxnRefValue);
// Step 4 - Create and send the Digital Order
objPayClient.doAdminRefund(merchantID, transactionID, refundAmount, user, password);
In sockets, an example of the code for adding refund data is:

}
}
out.print("15, + merchantID + , + transactionID + , + purchaseAmountInteger + , +
username + , + password + \n);
}

command. Some of the more important fields are also directly accessible, (see
below), so the comma delimited string does not have to be parsed.
Reference Manual.
In Java or COM, an example of the code for retrieving the results is:
// Step 6 - Get the results for each of the receipt variable required.
Version 2.23
106
adminResponse = objPayClient.getResultField("DigitalReceipt.Result");
String merchantId
String receiptNo

String authorizeID
String batchNo
In sockets, an example of the code for retrieving the results is:

out.print("4,DigitalReceipt.Result\n");
String adminResponse = in.readLine;
// only check the first status character of the return message as the second field has data
// perform error handling for this command,
} else {
cmdResponse = cmdResponse.substring(2);
out.print(4, DigitalReceipt.QSIResponseCode \n);
qsiResponseCode = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
Version 2.23
107
The Admin Void Capture command allows a merchant to void the funds from
a previous run capture transaction in Auth/Capture mode. This command
cannot be used if the merchant is operating in Purchase mode.
The merchant can only run one void capture transaction on the original
capture transaction, as it completely removes the capture transaction as
though it never occurred. A void capture must be run before the batch
containing the original capture transaction is processed by the acquiring
institution.
Version 2.23
108
The Admin Void Capture inputs that are required are:

Fieldname
Description
The merchant should use a unique value
for this field to identify the transaction.
This identifier can use text made up of any
of the base US ASCII characters in the
range, hexadecimal 20 to 126. This field is
added using the addAdminCommandField
MerchTxnRef
It is important to make sure this number
is stored safely for later retrieval if
required as it is used to track the progress
of a transaction in the event of a
communications failure where no Digital
receipt is received.
MerchantId
The merchant ID is an alphanumeric

identifier that is given to the merchant
during the banks 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
TransactionNo

Username

Password
AMA Void Capture Input Fields
In Java or COM, an example of the code for adding void capture data is:
objPayClient.doAdminVoidCapture(merchantID, transactionID, user, password);
In sockets, an example of the code for adding void capture data is:
out.print("16, + merchantID + , + transactionID + , + username + , + password + \n);
Version 2.23
109

Reference Manual.
String merchantId
String receiptNo

String authorizeID
String batchNo

String cmdResponse = in.readLine;
} else {
adminResponse = cmdResponse.substring(2);
Version 2.23
110

The Admin Void Purchase command allows a purchase merchant to void a

purchase transaction. It is not available for Auth/Capture mode merchants.
The merchant can only run one Void Purchase transaction on the original
Purchase transaction as it completely removes the purchase transaction as
though it never occurred.
The Admin Void Purchase must be run before the acquiring institution
processes the batch containing the original purchase transaction.
The Admin Void Purchase inputs that are required are:

Fieldname
MerchTxnRef
Description
field to identify the transaction. This identifier can
use text made up of any of the base US ASCII
characters in the range, hexadecimal 20 to 126.
This field is added using the
It is important to make sure this number is stored
safely for later retrieval if required as it is used to
track the progress of a transaction in the event of
a communications failure where no Digital
receipt is received.
Version 2.23
111
Fieldname
Description
MerchantId
The merchant ID is an alphanumeric identifier that

is given to the merchant during the banks
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.
TransactionNo
This is the transaction reference number of the

Username
This is the AMA username that can authorise the

Password
This is the password for the AMA username.
AMA Void Purchase Input Fields
In Java or COM, an example of the code for adding void purchase data is:
objPayClient.doAdminVoidPurchase(merchantID, transactionID, user, password);
In sockets, an example of the code for adding void purchase data is:
out.print("25, + merchantID + , + transactionID + , + username + , + password + \n);

Reference Manual.
Version 2.23
112
String merchantId
String receiptNo

String authorizeID
String batchNo
Version 2.23
113
String cmdResponse = in.readLine;
} else {
adminResponse = cmdResponse.substring(2);
Version 2.23
114
Financial transactions represent the flow of information between the customer, the merchant and
the bank when purchasing goods and services. They include transactions for purchasing goods
immediately, authorizing and capturing goods on order, and performing voids and refunds when
necessary.
The number of financial transactions generated from an initial shopping transaction depends on
the type of transaction and the actions performed.
In Purchase mode this only includes the original purchase transaction, plus any refunds that have
been performed. In Auth/Capture mode this is the original Auth transaction plus any captures
and refunds.
Input the reference transaction number and the output displays all the results about the
transaction.
The Admin Financial Transaction History inputs that are required are:
Fieldname
Description
MerchantId
The merchant ID is an alphanumeric identifier that is given to the

merchant during the CommWebs registration process, which is used to
identify the merchant on CommWeb.
TransactionNo
The transaction reference number of the original Authorisation or

Purchase transaction.
Username
The AMA username that can authorise the operation of this capture
transaction.
Password
"*
In Java or COM, an example of the code for performing a Financial Transaction History query is:
objPayClient.doAdminShoppingTransactionHistory(merchantID, transactionNo, user, password);
In sockets, an example of the code for performing a Financial Transaction History query is:
out.print("18, + merchantID + , + transactionNo + , + username + , + password + \n);
The Admin Financial Transaction History command returns a string of comma-delimited fields.
The fields are retrieved using the getResultField supplementary command.
For more information on the output fields, please refer to the Payment Client Reference
Manual.
In Java or COM, an example of the code extract for retrieving the results is:
return;
Version 2.23
115
}
exception = result;
}
return;
}
// Get the number of records in the result set
int recordCount = objPayClient.getResultCount();
if (recordCount = = 0) {
// Display a message to indicate there are no records to display for this period.
} else {
// Retrieve each output record String
for (int i=0; i< recordCount; i++) {
// retrieve the details for this record
String receiptDetails = objPayClient.getResultRecord(i);
// output the required details from this record
}
}
In sockets, an example of the code extract for retrieving the results is:
out.print("4,DigitalReceipt.QSIResponseCode\n);
sock.close();
return;
} else {
}
Version 2.23
116
out.print("4,DigitalReceipt.ERROR\n);
// Display an Error Page as the record count could not be retrieved
sock.close();
return;
}
}
// Get the number of records in the result set
out.print("23\n");
// Display an Error Page as the record count could not be retrieved
sock.close();
return;
}
int recordCount = Integer.parseInt(cmdResponse.substring(2));
if (recordCount = = 0) {
// Display message to indicate there are no records to display for this period.
} else {
// Retrieve each output record String
for (int i=0; i< recordCount; i++) {
out.print(24, + i + \n);
String receiptDetails = in.readLine().substring(2);
// retrieve the required details from this record
}
}
Version 2.23
117
'
,(
The QueryDR command allows a merchant to search for a Digital Receipt for
a transaction where the original receipt has been lost. The search is performed
on the key MerchTxnRef, so you should keep the MerchTxnRef field a
unique value.
If transactions exist with duplicate MerchTxnRef numbers, the query will only
return the most recent transactions encrypted digital receipt, but a flag is
raised to indicate there is more than one transaction that meets the criteria.
If the query result returned is not the correct one, the merchant would need to
visually check the transactions via the Merchant Administration portal. But it
is easier to search for a unique MerchTxnRef number.
The encrypted digital receipt is then decrypted in the Payment Client by the
decryptDigitalReceipt command, depending on the command type the digital
receipt refers to. A transaction receipt will contain the same fields as the
original receipt and an AMA receipt will return a multi field comma
delimited string.
The Admin QueryDR inputs that are required are:

Fieldname
Description
MerchantId
The merchant ID is an alphanumeric

identifier that is given to the merchant
during the banks 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
MerchTxnRef
The search-identifier field for this

command to search on. It should return an
encrypted DR result that would have been
returned from the original lost transaction
receipt.
Username

Password
AMA QueryDR Input Fields
In Java or COM, an example of the code for QueryDR data is:

Version 2.23
118
objPayClient.doQueryDR(merchantID, MerchTxnRef, user, password);
In sockets, an example of the code for QueryDR data is:

out.print("29, + merchantID + , + merchTxnRef + , + username + , + password + \n);
The result for an Admin QueryDR command will return a transaction receipt
for a standard 2 Party or 3 Party transaction, or a comma delimited string for
an AMA transaction. You must know what type of receipt to enable you to
generate the appropriate output.
There are also a few extra keys values used in getResultField supplementary
command for QueryDR, that are not used elsewhere.
These fields are:
Fieldname
Description
QueryDR.DRExists
This key is used to determine if the

QueryDR command returned any search
results. If the value is Y, then there is at
least one MerchTxnRef number result
matching the search criteria.
QueryDR.FoundMultipleDRs
This is used after the previous command to

determine if there are multiple results. If
the value is Y, then there are multiple
MerchTxnRef numbers matching the search
criteria.
DigitalReceipt.ReceiptNo"
This is used to return the encrypted Digital

receipt.
AMA QueryDR Digital receipt fields
In Java or COM, an example of the code extract for retrieving the results is:
// *******************************************************
exception = result;
}
Version 2.23
119

return;
}
// *****************************************************
// Get the QSI Response Code, DRExists and MultipleDRs fields
String drExists
= objPayClient.getResultField("QueryDR.DRExists");
String multipleDRs
= objPayClient.getResultField("QueryDR.FoundMultipleDRs");

return;
}
exception = result;
}
// Check if the error relates to the original DR queried by the
// QueryDR command or if it is for the QueryDR command itself
if (drExists != null && drExists.equalsIgnoreCase("Y")) {
// This error relates to the original transaction that was
// queried by the QueryDR command
} else {
// This error relates to the QueryDR command and not the
// transaction that was queried
}
return;
}
// Define Output variables inside 'if' statement
String transAmount
= "";
String receiptNo
= "";
String acqResponseCode = "";

String authorizeID
Version 2.23
= "";
120
String batchNo
= "";
= "";
String orderinfo
= "";
String cardType
= "";

// The example retrieves the MerchantID and Transaction Amount
// values, which should be the same as the values sent. In a
// production system the sent values and the receive values
// could be checked to make sure they are the same.
merchantID
transAmount
receiptNo
acqResponseCode = objPayClient.getResultField("DigitalReceipt.AcqResponseCode");
authorizeID
batchNo
transactionNo
// The program needs to know if it is expecting a standard purchase type transaction, or

// an AMA type transaction. This field is passed in from the input.
if (receiptType.equals("Standard")) {
// extra fields returned for a standard input
merchantTxnRef = objPayClient.getResultField("DigitalReceipt.MerchTxnRef");
orderinfo
cardType
} else {
result = objPayClient.getResultField("DigitalReceipt.Result");
// Check for an empty result
if (result == null || result.equals("")) {
// Display an Error Page as DR contained an empty result
return;
}
}
}
// ***********************************************************
Version 2.23
121
In sockets, an example of the QueryDR code extract is:

// *******************************************************
out.print("5,", res, req);
if (!cmdResponse.substring(0,1).equals(OK)) {
if (cmdResponse.substring(0,1).equals(OK)) {
}
// Display an Error as the DR doesn't contain a valid result
sock.close();
return;
}
// *****************************************************
// Get the QSI Response Code, DRExists and MultipleDRs fields
String qsiResponseCode = ;
String drExists = ;
String multipleDRs = ;
out.print("4,DigitalReceipt.QSIResponseCode\n);
sock.close();
return;
} else {
}
out.print("4,QueryDR.DRExists\n);
sock.close();
return;
} else {
Version 2.23
122
drExists = cmdResponse.substring(2);
}
out.print("4,QueryDR.FoundMultipleDRs\n);
sock.close();
return;
} else {
drExists = cmdResponse.substring(2);
}
out.print("4,DigitalReceipt.ERROR\n);
}
// Check if the error relates to the original DR queried by the
// QueryDR command or if it is for the QueryDR command itself
if (drExists.equalsIgnoreCase("Y")) {
// This error relates to the original transaction that was
// queried by the QueryDR command
} else {
// This error relates to the QueryDR command and not the
// transaction that was queried
}
sock.close();
return;
}
// Define Output variables inside 'if' statement
String transAmount
= "";
String receiptNo
= "";
String acqResponseCode = "";

String authorizeID
= "";
String batchNo
= "";
= "";
String orderinfo
= "";
Version 2.23
123

String cardType

= "";

// The example retrieves the MerchantID and Transaction Amount
// values, which should be the same as the values sent. In a
// production system the sent values and the receive values
// could be checked to make sure they are the same.
transAmount = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
// The program needs to know if it is expecting a standard purchase type transaction, or
// an AMA type transaction. This field is passed in from the input.
if (receiptType.equals("Standard")) {
// the extra fields returned for a standard input
merchantTxnRef = ... // as above for the standard outputs
orderinfo
= ...
cardType
= ...
} else {
out.print("4,DigitalReceipt.Result\n);
Version 2.23
124
// Display an error as the DigitalReceipt.Result could not be retrieved
sock.close();
return;
} else {
result = cmdResponse.substring(2);
}
}
// ***********************************************************
sock.close();
Version 2.23
125
/>?
Function Name
Parameters
Message
Type
echo
getDigitalOrder1
decryptDigitalReceipt
getResultField
nextResult
sendMOTODigitalOrder4
addDigitalOrderField
13
doGetVersion
MessageID=1
EchoString
MessageID=2
OrderInfof2
MerchantID
Amount
Locale
ReturnURL
MessageID=3
DigitalReceipt
MessageID=4
Argument Field3
MessageID=5
MessageID=6
OrderInfof2
MerchantID
Amount
Locale5
ReturnURL(null)6
MessageID=7
FieldName
FieldValue
MessageID=13
Data Type
Return Value
String
String
Success:1,echo:{Echo
String}
Failure: 0,0
String
String
String
String (Integer)
String
String
Success:
1,{DigitalOrder}
Failure: 0,0
String
String
String
String
String
String
String(Integer)
String
String
String
String
String
String
MessageID=14
String
MerchantID
String
TransactionNumb
String(Long)
er7
String(Integer)
Amount(cents)
String
User
String
Password
MessageID=15
String
MerchantID
String
TransactionNumb
String(Long)
7
er
String(Integer)
Amount(cents)
String
User
String
Password
MessageID=16
String
MerchantID
String
TransactionNumb
String(Long)
7
er
String
User
String
Password
14
doAdminCapture
15
doAdminRefund
16
doAdminVoidCapture
23
getResultCount
MessageID=2310
String
24
getResultRecord
MessageID=24
RecordNumber11
String
String(Integer)
Version 2.21
Success: 1,1
Failure: 0,0
Success: 1,{fieldvalue}
Failure: 0,0
Success: 1,1
Failure: 0,0
Success: 1,1
Failure: 0,0
Success: 1,1
Failure: 0,0
Success:
1,{PCversion}
Failure: 0,0
Success: 1,1
Failure: 0,0
Success: 1,1
Failure: 0,0
Success: 1,1
Failure: 0,0
Success:
1,{resultCount}
Failure: 0,0
Success:
1,{resultRecord}
Failure: 0,0
127
Message
Type
Function Name
25
doAdminVoidPurchase
28
29
doQueryDR
Parameters
Data Type
MessageID=25
String
MerchantID
String
TransactionNumb
String (Long)
er7
String
User
String
Password
13
MessageID=28
String
FieldName
String
FieldValue
String
MessageID=29
String
MerchTxnRef
String
User
String
Password
String
Return Value
Success: 1,1
Failure: 0,0
Success: 1,1
Failure: 0,0
Success: 1,1
Failure: 0,0
Before sending an SSL+ Digital Order, you must have set all additional data fields using the
AddDigitalOrderField command.
2
CommWeb accepts no more than 34 characters
3
The argument field is a predefined String value that triggers the appropriate response. These values can
only be those shown in Standard Digital receipt Codes in Appendix A.
4
Before sending a MOTO order, you must have set the CardNum and CardExp fields using the
addDigitalOrderField command.
CardNum is the card number as a string with no white spaces.
CardExp is the expiry date in the form YYMM where YY is the last two digits of the year and MM is
the two digit numeric month.
5
Although not used for a MOTO transaction, this field must have a value inserted. The default value to
use is en
6
The use of this field is deprecated. It may be left blank.
7
A Number (definite positive integer), no more than 21 digits long, that is generated by the Server and
provided in the SSL & MOTO receipts, and is the primary transaction number, i.e. the reference
transaction number that subsequent transactions refer back to, for example If a transaction is carried out
and is assigned a value of say 1243, then a refund transaction must refer back to 1243.
8
This is the start date & time of the batch being examined and is usually used in the format
DD/MM/YYYY. The date format actually depends on the Payment Server locale in use, but please be
aware that some databases could cause the format to change to MM/DD/YYYY or even
YYYY/MM/DD.
If you know the correct database format, you can even include time frames to check between particular
times
for example 24/09/2001 09:00:00 & 24/09/2001 17:00:00.
9
This is the end & time date of the batch being examined. It is the same format as start date & time
format. If you use Date/Time format in 8, then you must use the same format here. Likewise if you use
Date only format in 8, then you must use the same format here. The EndDate must be equal to or greater
than the StartDate
10
This is used for finding how many records are to be returned in a function.
11
This is used to select the appropriate record in one of the history functions. It would normally be used
in a for loop, starting from record 0 (the first record) up to the number of records minus 1, as
determined in 10.
12
These commands are similar to addDigitalOrderField and addAdminCommandField that are used for
adding additional data to requests.
13
This is an equivalent to addDigitalOrderField that is used for adding additional data to
sendMOTODigitalOrder. The addAdminCommandField command is used to add additional data to any
Advanced Merchant Administration command for example doAdminCapture and doAdminRefund.
Version 2.23
128
#
!
/-?# 1
%
'
The following table lists the functions available on CommWeb and the compatibility of each
function that the merchant can use to determine the functionality that can be included in a digital
order.
MasterCard SecureCode
Visa 3-D Secure Transaction
Version 2.23
Ticket Number
Basic 3 party
Basic 2 Party
Card Security Code
Ticket Number
Visa 3-D Secure Transaction X
MasterCard SecureCode X
Card Security Code
Functionality
X
X
129
/(?
6 1
!
The following table shows the test card numbers and associated expiry dates configured for each card
scheme on the CommWeb Payment Server.
These Cards are for authorization and purchase transactions only. Cards for authentication testing will be
supplied at a later time.
Card Type
MasterCard
MasterCard
Visa
Visa
Amex
Bankcard (Australian Domestic)
Diners Club
Version 2.23
PAN
5123456789012346
5313581000123430
4005550000000001
4557012345678902
345678901234564
5678901234567898
30123456789019
Expiry Date
04/05
04/05
04/05
04/05
04/05
04/05
04/05
130
!
The test bank simulator is configured to allow the user to change the response received against the above
test card numbers by varying the amount after the decimal point for the transaction.
The following table shows how the various response codes can be triggered varying the amount after the
decimal point.
QSI
Name
Resp.
.
QSI
Amount
Transaction approved
XXX.00
Transaction could not

be processed
XXX.10
Transaction declined contact issuing bank
XXX.05
No reply from
Processing Host
XXX.68
Card has expired
XXX.33
Insufficient credit
XXX.51
Error Communicating
with Bank
Name
Not Mapped
Caused by
Resp.
.
7
Message Detail Error
Transaction declined
transaction type not
supported
Not Mapped
Bank Declined
Transaction Do Not
Contact Bank
Not Mapped
Invalid PAN, Invalid Expiry Date
For example, to obtain a response of 1 on a MasterCard, simply send a transaction for $xxx.10 against
one of the above MasterCard numbers.
Developers should use these response codes in exception handling. For further detail on the reason for
decline, the issuer response code should be checked. See Issuer Response Code Mapping.
Version 2.23
131
"
The Payment Server returns both a summary result code generated by the Payment Server as well as the
raw issuer response code as received from the bank.
Digital Receipt Field
Description
DigitalReceipt.QSIResponseCo
de
Summary result code as returned from the

Payment Server.
DigitalReceipt.AcqResponseCo
de
Issuer response code as returned from the

bank.
The following table is a list of relevant issuer response codes. These response codes may vary by issuer
and may vary from time to time.
Issuer
Resp.
00
01
02
03
04
05
07
12
14
15
33
34
36
39
41
43
51
54
57
59
62
65
91
Version 2.23
Description
Approved
Refer to Card Issuer
Refer to Card Issuer
Invalid Merchant
Pick Up Card
Do Not Honor
Pick Up Card
Invalid Transaction
Invalid Card Number (No such Number)
No Such Issuer
Expired Card
Suspected Fraud
Restricted Card
No Credit Account
Card Reported Lost
Stolen Card
Insufficient Funds
Expired Card
Transaction Not Permitted
Suspected Fraud
Restricted Card
Exceeds withdrawal frequency limit
Cannot Contact Issuer
132
The following table shows how the bank simulator maps the issuer response code to response codes.
Issuer
Resp.
00
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
Version 2.23
CommWeb
Resp.
0
2
2
2
2
2
2
2
0
1
1
1
1
1
2
2
0
1
1
2
1
1
1
1
1
2
1
1
1
1
1
2
1
4
Issuer
Resp.
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
CommWeb
Resp.
2
1
2
1
1
2
1
2
1
2
1
1
1
1
1
1
1
5
1
1
4
1
1
1
1
2
1
2
1
1
1
2
1
1
Issuer
Resp.
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
CommWeb
Resp.
3
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
2
2
2
1
1
1
1
1
2
2
133

CommWeb - Payment Client Integration Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

CommWeb - Payment Client Integration Guide

Uploaded by

Copyright:

Available Formats

CommWeb Payment Server

Payment Client Integration Guide

CommWeb Software Support Line 1800 882 888

Merchant detail configuration on the system

Merchant Enquiries 1800 230 177

Commonwealth Bank Merchant enquiries such as reconciliation

Operations Help Desk 1800 022 966

CommWeb connectivity issues (outages).

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

This guide provides the details required to successfully integrate a

This guide is specifically aimed at business analysts and

This version of the CommWeb Payment Client Integration Guide

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

This guide consists of the following sections:

An introduction to CommWeb, and this guide.

An overview of the different transaction types, 3-Party

Describes the different interfaces of the Payment Client. It

Describes standard usage scenarios and recommends what

Details the steps to perform each transaction type and the

Describes the implementation of MasterCard SecureCode and

Describes the Advanced Merchant Administration functions

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

CommWeb enables a merchant to perform secure transactions over the

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,

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

How a transaction is processed

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

refund (i.e. the original transaction was a purchase or an authorised

Commonwealth Bank of Australia

CommWeb Payment Server