0% found this document useful (0 votes)

1K views

CommWeb - Payment Client Integration Guide

This document provides guidance on integrating a merchant application with CommWeb's Payment Client. It outlines CommWeb's payment processing system, describing how transactions are processed in real-time and funds are transferred from cardholders to merchants. It also explains the different types of transactions (purchase vs auth/capture) and interfaces available for the Payment Client (Java, COM, sockets). The guide is intended to help analysts and integrators successfully integrate the Payment Client into a merchant's application.

Uploaded by

Niño Francisco Alamo

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

1K views

CommWeb - Payment Client Integration Guide

Uploaded by

Niño Francisco Alamo

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 133

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

CommWeb Payment Server

Payment Client Integration Guide

$%
$$
$(
$(
$+
$+
$+
$/
$/
(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
!

=
#

! ,
:

!&
&

'
"

:
'
!
&

Version 2.23

)
, !
'

:
8 :
)

Commonwealth Bank of Australia

4@
4@
4@
4@
45
45
4
4

CommWeb Payment Server

Payment Client Integration Guide

A3< '

#&
!

=
,#
>

#
.

) 8

&
)
+"
("

,# 9

.
#2)
#2)

) 8
)

.
.

0)')3

Version 2.23

Commonwealth Bank of Australia

B
4
!
/%
/$
/(
/4
//
//
//
/5
/
@
@
5+
54
5/
%
%
%
$
(
(
(
+
+
4
4
/
@
5
$%%
$%$
$%$
$%$
$%(
$%/
$%/
$%/
$%@
$%
$%
$%
$$%
$$$
$$$
$$$
$$(
$$/
$$/
$$/
$$
$$

CommWeb Payment Server

Payment Client Integration Guide

$$
$$

""
""
""
&

#
#
#

$% &
'
$
)
*
$
- )

(
'

$+%
$+$
$+(

&
&

Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

!
!&
!
#

, !1 8
#&
!
A ,
!
.
)
+"
!
)') &
.
)')
.
)') 9
&
.
)') 9
.
)') = #
.
)') = #
!

+@
4%
4$
4
%
(
@

Version 2.23

$%(
$%/
$%
$$(
$$
$$

Commonwealth Bank of Australia

CommWeb Payment Server

&
&
&
&

#
!
'
#
12
!
'
+
+"
("
)')

Payment Client Integration Guide

$%
$$
$@
(%
($
($
((
((
(+
(+
(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 *&

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

Issuing Bank

6.
3.

Card Holder

1.
5.
2.

4.
CommWeb

7.
Merchant
Commonwealth Bank
Real Time

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

. '

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

. %. " 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

Commonwealth Bank of Australia

CommWeb Payment Server

. '

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

. '

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

#
("

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

Commonwealth Bank of Australia

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

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

Commonwealth Bank of Australia

JVM

CommWeb
Payment
Client

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

$ %

! &

!
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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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.
Finish process on 16.
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.
Finish process on 16.
!

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

!
*

Open rc.local file, using vi or pico, for editing

Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

'
!
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)

The related commands for the sockets interface are shown in Appendix 1.
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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

%
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.
11. This step is used to perform appropriate error
handling.

Single result transaction process

!?
Version 2.23

!
Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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
A failure is indicated by a Boolean return value of false in a Java or COM
implementation, or 0,0 for sockets.
Errors that occur executing the nextResult command means the Payment
Server has detected an error in processing the Digital Order.
To determine the error in Java or COM the command
getResultField(PaymentClient.Error) is used. In sockets the command 4,
PaymentClient.Error\n is used. These commands return the error code and
description of the error.
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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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.
8. Disconnect from the Payment Client.
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).
10. This step is used to perform appropriate 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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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.
4. Purchase Amount (PurchaseAmountInteger)
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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

if (!objPayClient.sendMOTODigitalOrder(SessionID, MerchantID, PurchaseAmountInteger, en, )) {

// perform error handling for this command
return
}

The content of the if statement should perform the actions for your
implementation. It may be very simple, such as, an error is displayed and
processing is terminated. For a production implementation a more
sophisticated response may be warranted.
&

After the digital order has been processed you need to ensure that the
Payment Client has received a valid digital receipt from the Payment Server
and that there are results to process. To do this, use the nextResult API
command.
An example of checking if a valid digital receipt has been received is:
// Get the nextResult value to check there are results to process.
if (!objPayClient.nextResult()) {
// retrieve the error description from the Payment Client
String error = objPayClient.getResultField("PaymentClient.Error");
// perform error handling for this command
return
}

The content of the if statement perform the actions for your implementation.
It may be very simple, such as, 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");
Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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");
if (!result.equals("echo:Test")) {
// Display error as communication to the Payment Client failed
// perform error handling for this command
return;
}
// Step 3 - Prepare to Generate and Send Digital Order
// ***************************************************
// The extra details are not accepted by the
// 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
objPayClient.addDigitalOrderField("CardNum", cardNumber);
objPayClient.addDigitalOrderField("CardExp", cardExpiry);
// add MerchTxnRef number
objPayClient.addDigitalOrderField("MerchTxnRef", merchTxnRef);
Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

// Step 4 - Generate and Send Digital Order (& receive DR)

// *******************************************************
// Create and send the Digital Order
// (This primary command also receives the Digital Receipt)
if (!objPayClient.sendMOTODigitalOrder(orderInfo, merchantID, amount, "en", "")) {
// Retrieve the Payment Client Error (There may be none to get)
result = objPayClient.getResultField("PaymentClient.Error");
if (result != null && result.length() != 0) {
exception = result;
}
// perform error handling for this command
return;
}
// Step 5 - Check the DR to see if there is a valid result
// *******************************************************
// Use the "nextResult" command to check if the DR contains a result
if (!objPayClient.nextResult()) {
// Retrieve the Payment Client Error (There may be none to get)
result = objPayClient.getResultField("PaymentClient.Error");
if (result != null && result.length() != 0) {
exception = result;
}
// perform error handling for this command
return;
}
// Step 6 - Get the result data from the Digital Receipt
// *****************************************************
// Extract the available Digital Receipt fields
// Get the QSI Response Code for the transaction
String qsiResponseCode = objPayClient.getResultField("DigitalReceipt.QSIResponseCode");
if (qsiResponseCode == null || qsiResponseCode.length() == 0) {
// perform error handling for this command
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");
if (result != null && result.length() != 0) {
exception = result;
Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

}
// perform error handling for this command
return;
}
// Extract the available Digital Receipt fields
// 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

= objPayClient.getResultField("DigitalReceipt.OrderInfo");

String merchantId

= objPayClient.getResultField("DigitalReceipt.MerchantId");

String purchaseAmount = objPayClient.getResultField("DigitalReceipt.PurchaseAmountInteger");

String receiptNo

= objPayClient.getResultField("DigitalReceipt.ReceiptNo");

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

String authorizeID

= objPayClient.getResultField("DigitalReceipt.AuthorizeId");

String batchNo

= objPayClient.getResultField("DigitalReceipt.BatchNo");

String transactionNo

= objPayClient.getResultField("DigitalReceipt.TransactionNo");

String cardType

Payment Client Integration Guide

cmdResponse = in.readLine();
authorizeID = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.BatchNo\n);
cmdResponse = in.readLine();
batchNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.CardType\n);
cmdResponse = in.readLine();
cardType = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
// Step 7 - We are finished with the Payment Client so tidy up
// ***********************************************************
// 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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

+
'
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.

Connect to the Payment Client,

7.
8.

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.

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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.
4. You may not have rebooted after installation for the COM interface.
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.
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. 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.
3. The Payment Client classes directory and/or the PaymentClient.jar file is
not correctly entered into the JVM classpath for a Java implementation
and therefore the Payment Client object cannot be instantiated.
4. A semantic error may exist when trying to invoke the Payment Client,
therefore it cannot be found to be invoked.
Although the merchant cannot rectify these problems, they should perform a
QueryDR command to resolve any outstanding transactions. This allows you
to find the transaction and deal with it appropriately.
Please refer to the Payment Client Installation Guide for detail on
installation procedures.
Step 3 Performing the echo test
If this step has been reached but the echo test fails, the Payment Client is not
able to communicate or execute commands correctly. The errors likely to
cause this are the same as those listed in Step 2.
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.
Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

CommWeb Payment Server

Payment Client Integration Guide

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:
// Instantiate a Payment Client
PaymentClientImpl objPayClient = new PaymentClientImpl();

The variable objPayClient is a local variable to the Payment Client and may
be changed to any name that suits the implementation, 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.
An example of the Java call to perform the echo test and check for a valid
response is:

Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

// Test the Payment Client object created correctly

String result = objPayClient.echo("Test");
if (!result.equals("echo:Test")) {
// perform error handling for this command
return;
}

The contents of the if statement should perform the actions appropriate to

your implementation. It may be very simple, such as, 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 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) {
// perform error handling for this command
}

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

The content of the if statement should perform the actions appropriate to

your implementation. It may be very simple, such as, an error is displayed
and processing is terminated. For a production implementation a more
sophisticated response may be warranted.
!

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);

The following code blocks are not complete and would not compile. Java
extras like retrieving input variables and try/catch blocks have been omitted
for the sake of readability, but the principles of how the code block works is
correct.
Putting all these code extracts together the application becomes:
D 8

// Step 1 - Connect to the Payment Client

// ***************************************
// create a Payment Client object
objPayClient = new PaymentClientImpl();
// Step 2 - Test the Payment Client object was created successfully
// ****************************************************************
// Test the communication to the Payment Client using an "echo"
result = objPayClient.echo("Test");
if (!result.equals("echo:Test")) {
// Display error as communication to the Payment Client failed
// perform error handling for this command
return;
}
// Step 3 - Prepare to Generate and Send Digital Order
// ***************************************************
// The extra details are not accepted by the
// getDigitalOrder() method and so we must add them
// explicitly here for inclusion in the DO creation.
// Adding the supplementary data to the DO is done using the
// "addDigitalOrderField" command
// add MerchTxnRef number
objPayClient.addDigitalOrderField("MerchTxnRef", merchTxnRef);
Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

// Step 4 - Generate and Send Digital Order

// ****************************************
// Create and send the Digital Order
digitalOrder = objPayClient.getDigitalOrder(orderInfo, merchantID, amount, locale, returnURL);
if (digitalOrder != null && digitalOrder.length() == 0) {
// Retrieve the Payment Client Error (There may be none to get)
result = objPayClient.getResultField("PaymentClient.Error");
if (result != null && result.length() != 0) {
exception = result;
}
// Display an Error Page as the Digital Order was not processed
// perform error handling for this command
return;
}
// Transmit the DO to the Payment Server via a browser redirect
res.sendRedirect(digitalOrder);
// At this point the customers browser is sent to the Payment Server
// using the URL at the start of the Encrypted Digital Order

The following Sockets implementation code block is not complete and would
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.
An example of the code is:
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);
// Step 1 - Connect to the Payment Client
// **************************************
// Create a socket object to the Payment Client
Socket sock = new Socket(payClientIP, payClientPort);
// The Buffered Reader data input stream from the socket
BufferedReader in = new BufferedReader( new InputStreamReader(sock.getInputStream()));
// The output stream to the socket
PrintStream out = new PrintStream(sock.getOutputStream());
Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

// Step 2 - Test the Payment Client object was created successfully

// ****************************************************************
// Test the communication to the Payment Client using an "echo"
out.print("1,Test\n");
cmdResponse = in.readLine();
if (!cmdResponse.equals("1,echo:Test")) {
// perform error handling for this command
sock.close();
return;
}
// Step 3 - Prepare to Generate and Send Digital Order
// ***************************************************
// The extra details are not accepted by the
// getDigitalOrder() method and so we must add them
// explicitly here for inclusion in the DO creation.
// Adding the supplementary data to the DO is done using the
//"addDigitalOrderField" command
// add merchant transaction reference data
out.print("7,MerchTxnRef," + MerchTxnRefValue + "\n");
cmdResponse = in.readLine();
if (!cmdResponse.equals(1,1)) {
// perform error handling for this command
sock.close();
return;
}
// Step 4 - Generate and Send Digital Order
// ****************************************
// Create and send the Digital Order
// (This primary command also receives the Digital Receipt)
out.print("2, + orderInfo + , + merchantID + , + purchaseAmountInteger+ , + locale +
, + returnURL + \n);
cmdResponse = in.readLine();
if (!cmdResponse.substring(0,1).equals(1)) {
// Retrieve the Payment Client Error (There may be none to get)
out.print("4,PaymentClient.Error\n");
cmdResponse = in.readLine();
// check the first status char of the return message as the second field may have data
if (cmdResponse.substring(0,1).equals(1)) {
exception = cmdResponse.substring(2);
}
// perform error handling for this command
sock.close();
return;
}
// Get the Digital Order
Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

digitalOrder = cmdResponse.substring(2);
// Transmit the DO to the Payment Server via a browser redirect
res.sendRedirect(digitalOrder);
// At this point the customers browser is sent to the Payment Server
// using the URL at the start of the Encrypted Digital Order
// 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 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.
An example of the code is:
// 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:
// Instantiate a Payment Client
PaymentClientImpl objPayClient = new PaymentClientImpl();

To test the Payment Client, use an echo command to return the string value
you send appended to the string echo:.
An example of the Java call to perform the echo test and check for a valid
response is:

Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

// Test the Payment Client object created correctly

String result = objPayClient.echo("Test");
if (!result.equals("echo:Test")) {
// perform error handling for this command and return
return;
}

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.
if (!objPayClient.nextResult()) {
// retrieve the error description from the Payment Client
String error = objPayClient.getResultField("PaymentClient.Error");
// perform error handling for this command
return;
}

The content of the if statement should perform the actions appropriate to

your implementation. It may be very simple, such as, an error is displayed
and processing is terminated. There is an extra step in this if statement to
others that have been shown as we are now able to receive an error
description from the Payment Client to explain why the transaction did not
return a valid digital receipt. This error description may not always contain
data, as it may be an empty string ().
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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

// perform error handling to find out why transaction failed

} else {
String merchantID

= objPayClient.getResultField("DigitalReceipt.MerchantId");

String orderInfo

= objPayClient.getResultField("DigitalReceipt.OrderInfo");

String merchantRefNo = objPayClient.getResultField("DigitalReceipt.MerchTxnRef");

String txnAmount

= objPayClient.getResultField("DigitalReceipt.PurchaseAmountInteger");

String receiptNo

= objPayClient.getResultField("DigitalReceipt.ReceiptNo");

String transNo

= objPayClient.getResultField("DigitalReceipt.TransactionNo");

String acqCode

= objPayClient.getResultField("DigitalReceipt.AcqResponseCode");

String authoriseID

= objPayClient.getResultField("DigitalReceipt.AuthorizeId");

String batchNumber

= objPayClient.getResultField("DigitalReceipt.BatchNo");

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.
The following code blocks are not complete and would not compile. Java
extras like retrieving input variables and try/catch blocks have been omitted
to make it easier to read, but the principles of how the code block works is
correct.
Putting the code extracts together, the application becomes:
D 8

// Extract the encrypted Digital Receipt from the request. Note that
// the default redirection from the Payment Server contains a
// parameter "DR" which was sent as part of the DO in the ReturnURL field.
if ((encryptedDR = req.getParameter("DR")) == null) {
// perform error handling for this command
return;
}
// Step 1 - Connect to the Payment Client
// ***************************************
// create a Payment Client object
objPayClient = new PaymentClientImpl();
// Step 2 - Test the Payment Client object was created successfully
// ****************************************************************
// Test the communication to the Payment Client using an "echo"
result = objPayClient.echo("Test");
if (!result.equals("echo:Test")) {
// perform error handling for this command
return;
Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

}
// Step 3 - Decrypt Digital Receipt
// ********************************
if (!objPayClient.decryptDigitalReceipt(encryptedDR)) {
// Retrieve the Payment Client Error (There may be none to get)
result = objPayClient.getResultField("PaymentClient.Error");
if (result != null && result.length() != 0) {
exception = result;
}
// perform error handling for this command
return;
}
// Step 4 - Check the DR to see if there is a valid result
// *******************************************************
// Use the "nextResult" command to check if the DR contains a result
if (!objPayClient.nextResult()) {
// Retrieve the Payment Client Error (There may be none to get)
result = objPayClient.getResultField("PaymentClient.Error");
if (result != null && result.length() != 0) {
exception = result;
}
// Display an error as the DR doesn't contain a result
// perform error handling for this command
return;
}
// Step 5 - 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) {
// Display an error as QSIResponseCode could not be retrieved
// perform error handling for this command
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");
if (result != null && result.length() != 0) {
Version 2.23

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

exception = result;
}
// The response is an error message so generate an Error Page
// perform error handling for this command
return;
}
// Extract the available Digital Receipt fields
// 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 merchTxnRef = objPayClient.getResultField("DigitalReceipt.MerchTxnRef");
String orderinfo

= objPayClient.getResultField("DigitalReceipt.OrderInfo");

String merchantId

= objPayClient.getResultField("DigitalReceipt.MerchantId");

String purchaseAmount = objPayClient.getResultField("DigitalReceipt.PurchaseAmountInteger");

String receiptNo

= objPayClient.getResultField("DigitalReceipt.ReceiptNo");

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

String authorizeID

= objPayClient.getResultField("DigitalReceipt.AuthorizeId");

String batchNo

= objPayClient.getResultField("DigitalReceipt.BatchNo");

String transactionNo

= objPayClient.getResultField("DigitalReceipt.TransactionNo");

String cardType

= objPayClient.getResultField("DigitalReceipt.CardType");

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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);

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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);
objPayClient.addDigitalOrderField("CardNum", cardNumber);
objPayClient.addDigitalOrderField("CardExp", cardExpiry);

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

Commonwealth Bank of Australia

CommWeb Payment Server

Payment Client Integration Guide

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

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

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
example. $12.50 is expressed as 1250.

Username

The AMA username that can authorise the

operation of this capture transaction.

Password

The password for the AMA username.

Commonwealth Bank of Australia

101

CommWeb Payment Server

Payment Client Integration Guide

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:
// Step 1 - Connect to the Payment Client
// ***************************************
// create a Payment Client object
objPayClient = new PaymentClientImpl();
// Step 2 - Test the Payment Client object was created successfully
// ****************************************************************
// Test the communication to the Payment Client using an "echo"
result = objPayClient.echo("Test");
if (!result.equals("echo:Test")) {
// Display error as communication to the Payment Client failed
// perform error handling for this command
return;
}
// Step 3 - Prepare to Generate and Send Digital Order
// ***************************************************
// Add the Merchant Transaction Reference Number to the DO
// using the "addAdminCommandField" command
if (merchantTxnRef != null && merchantTxnRef.length() != 0) {
objPayClient.addAdminCommandField("MerchTxnRef", merchantTxnRef);
}
// 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.doAdminCapture(merchantID, transactionNo, amount, username, password)) {
// Retrieve the Payment Client Error (There may be none to get)
result = objPayClient.getResultField("PaymentClient.Error");
if (result != null && result.length() != 0) {
Version 2.23

Commonwealth Bank of Australia

102

CommWeb Payment Server

Payment Client Integration Guide

exception = result;
}
// Display an Error Page as the Digital Order was not processed
// perform error handling for this command
return;
}
// Step 5 - Check the DR to see if there is a valid result
// *******************************************************
// Use the "nextResult" command to check if the DR contains a result
if (!objPayClient.nextResult()) {
// Retrieve the Payment Client Error (There may be none to get)
result = objPayClient.getResultField("PaymentClient.Error");
if (result != null && result.length() != 0) {
exception = result;
}
// Display an error as the DR doesn't contain a result
// perform error handling for this command
return;
}
// Step 6 - Get the result data from the Digital Receipt
// *****************************************************
// Extract the available Digital Receipt fields
// Get the QSI Response Code for the transaction
String qsiResponseCode = objPayClient.getResultField("DigitalReceipt.QSIResponseCode");
if (qsiResponseCode == null || qsiResponseCode.length() == 0) {
// Display an error as QSIResponseCode could not be retrieved
// perform error handling for this command
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");
if (result != null && result.length() != 0) {
exception = result;
}
// The response is an error message so generate an Error Page
// perform error handling for this command
return;
}
// Get the result from the Digital Receipt
Version 2.23

Commonwealth Bank of Australia

103

CommWeb Payment Server

Payment Client Integration Guide

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
// perform error handling for this command
return;
}
// Extract the available Digital Receipt fields
// 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 merchantId
= objPayClient.getResultField("DigitalReceipt.MerchantId");
String transactionNo = objPayClient.getResultField("DigitalReceipt.TransactionNo");
String receiptNo
= objPayClient.getResultField("DigitalReceipt.ReceiptNo");
String acqResponseCode = objPayClient.getResultField("DigitalReceipt.AcqResponseCode");
String authorizeID
= objPayClient.getResultField("DigitalReceipt.AuthorizeId");
String batchNo
= objPayClient.getResultField("DigitalReceipt.BatchNo");
// Step 7 - We are finished with the Payment Client so tidy up
// ***********************************************************
// nothing to be done in Java
AMA Capture Java/Com Example Code Extract

Version 2.23

Commonwealth Bank of Australia

104

CommWeb Payment Server

Payment Client Integration Guide

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

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

TransactionNo

The transaction reference number of the

original Auth transaction.

PurchaseAmountInteger

The purchase amount of the transaction

Username

The AMA username that can authorise the

operation of this capture transaction.

Password

The password for the AMA username.

AMA Refund Input Fields

In Java or COM, an example of the code for adding refund data is:
Version 2.23

Commonwealth Bank of Australia

105

CommWeb Payment Server

Payment Client Integration Guide

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

// Step 3 - Add Merchant Reference Transaction number
out.print("28,MerchTxnRef," + MerchTxnRefValue + "\n");
cmdResponse = in.readLine();
// check the status to make sure the command completed OK
if (!cmdResponse.equals(1,1)) {
// perform error handling for this command
}
// check the status to make sure the command completed OK
if (!cmdResponse.equals(1,1)) {
// perform error handling for this command
}
// Step 4 - Create and send the Digital Order
out.print("15, + merchantID + , + transactionID + , + purchaseAmountInteger + , +
username + , + password + \n);
cmdResponse = in.readLine();
// check the status to make sure the command completed OK
if (!cmdResponse.equals(1,1)) {
// perform error handling for this command
}

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. Some of the more important fields are also directly accessible, (see
below), so the comma delimited string does not have to be parsed.
For more information on the output fields, please refer to the Payment Client
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

Commonwealth Bank of Australia

106

CommWeb Payment Server

Payment Client Integration Guide

adminResponse = objPayClient.getResultField("DigitalReceipt.Result");
String qsiResponseCode = objPayClient.getResultField("DigitalReceipt.QSIResponseCode");
String merchantId

= objPayClient.getResultField("DigitalReceipt.MerchantId");

String transactionNo

= objPayClient.getResultField("DigitalReceipt.TransactionNo");

String receiptNo

= objPayClient.getResultField("DigitalReceipt.ReceiptNo");

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

String authorizeID

= objPayClient.getResultField("DigitalReceipt.AuthorizeId");

String batchNo

= objPayClient.getResultField("DigitalReceipt.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
if (!cmdResponse.substring(0,1).equals(1)) {
// perform error handling for this command,
} else {
cmdResponse = cmdResponse.substring(2);
out.print(4, DigitalReceipt.QSIResponseCode \n);
cmdResponse = in.readLine();
qsiResponseCode = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.MerchantId\n);
cmdResponse = in.readLine();
merchantID = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.TransactionNo\n);
cmdResponse = in.readLine();
transactionNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.ReceiptNo\n);
cmdResponse = in.readLine();
receiptNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.AcqResponseCode\n);
cmdResponse = in.readLine();
acqResponseCode = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.AuthorizeId\n);
cmdResponse = in.readLine();
authorizeID = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.BatchNo\n);
cmdResponse = in.readLine();
batchNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
Version 2.23

Commonwealth Bank of Australia

107

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

108

CommWeb Payment Server

Payment Client Integration Guide

The Admin Void Capture inputs that are required are:

Fieldname

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

The transaction reference number of the

original Auth transaction.

Username

The AMA username that can authorise the

operation of this capture transaction.

Password

The password for the AMA username.

AMA Void Capture Input Fields

In Java or COM, an example of the code for adding void capture data is:
// Step 3 - Add Merchant Reference Transaction number
objPayClient.addAdminCommandField("MerchTxnRef", MerchTxnRefValue);
// Step 4 - Create and send the Digital Order
objPayClient.doAdminVoidCapture(merchantID, transactionID, user, password);

In sockets, an example of the code for adding void capture data is:
// Step 3 - Add Merchant Reference Transaction number
out.print("28,MerchTxnRef," + MerchTxnRefValue + "\n");
// Step 4 - Create and send the Digital Order
out.print("16, + merchantID + , + transactionID + , + username + , + password + \n);

Version 2.23

Commonwealth Bank of Australia

109

CommWeb Payment Server

Payment Client Integration Guide

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. Some of the more important fields are also directly accessible, (see
below), so the comma delimited string does not have to be parsed.
For more information on the output fields, please refer to the Payment Client
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.
adminResponse = objPayClient.getResultField("DigitalReceipt.Result");
String qsiResponseCode = objPayClient.getResultField("DigitalReceipt.QSIResponseCode");
String merchantId

= objPayClient.getResultField("DigitalReceipt.MerchantId");

String transactionNo

= objPayClient.getResultField("DigitalReceipt.TransactionNo");

String receiptNo

= objPayClient.getResultField("DigitalReceipt.ReceiptNo");

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

String authorizeID

= objPayClient.getResultField("DigitalReceipt.AuthorizeId");

String batchNo

= objPayClient.getResultField("DigitalReceipt.BatchNo");

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

Commonwealth Bank of Australia

110

CommWeb Payment Server

Payment Client Integration Guide

receiptNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";

out.print(4,DigitalReceipt.AcqResponseCode\n);
cmdResponse = in.readLine();
acqResponseCode = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.AuthorizeId\n);
cmdResponse = in.readLine();
authorizeID = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.BatchNo\n);
cmdResponse = in.readLine();
batchNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";

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

Commonwealth Bank of Australia

111

CommWeb Payment Server

Payment Client Integration Guide

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

original Auth transaction.

Username

This is the AMA username that can authorise the

operation of this capture transaction.

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:
// Step 3 - Add Merchant Reference Transaction number
objPayClient.addAdminCommandField("MerchTxnRef", MerchTxnRefValue);
// Step 4 - Create and send the Digital Order
objPayClient.doAdminVoidPurchase(merchantID, transactionID, user, password);

In sockets, an example of the code for adding void purchase data is:
// Step 3 - Add Merchant Reference Transaction number
out.print("28,MerchTxnRef," + MerchTxnRefValue + "\n");
// Step 4 - Create and send the Digital Order
out.print("25, + merchantID + , + transactionID + , + username + , + password + \n);

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. Some of the more important fields are also directly accessible, (see
below), so the comma delimited string does not have to be parsed.
For more information on the output fields, please refer to the Payment Client
Reference Manual.
In Java or COM, an example of the code for retrieving the results is:
Version 2.23

Commonwealth Bank of Australia

112

CommWeb Payment Server

Payment Client Integration Guide

// Step 6 - Get the results for each of the receipt variable required.
adminResponse = objPayClient.getResultField("DigitalReceipt.Result");
String qsiResponseCode = objPayClient.getResultField("DigitalReceipt.QSIResponseCode");
String merchantId

= objPayClient.getResultField("DigitalReceipt.MerchantId");

String transactionNo

= objPayClient.getResultField("DigitalReceipt.TransactionNo");

String receiptNo

= objPayClient.getResultField("DigitalReceipt.ReceiptNo");

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

String authorizeID

= objPayClient.getResultField("DigitalReceipt.AuthorizeId");

String batchNo

= objPayClient.getResultField("DigitalReceipt.BatchNo");

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

Version 2.23

Commonwealth Bank of Australia

113

CommWeb Payment Server

Payment Client Integration Guide

out.print("4,DigitalReceipt.Result\n");
String cmdResponse = in.readLine;
// only check the first status character of the return message as the second field has data
if (!cmdResponse.substring(0,1).equals(1)) {
// perform error handling for this command,
} else {
adminResponse = cmdResponse.substring(2);
out.print(4, DigitalReceipt.QSIResponseCode \n);
cmdResponse = in.readLine();
qsiResponseCode = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.MerchantId\n);
cmdResponse = in.readLine();
merchantID = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.TransactionNo\n);
cmdResponse = in.readLine();
transactionNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.ReceiptNo\n);
cmdResponse = in.readLine();
receiptNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.AcqResponseCode\n);
cmdResponse = in.readLine();
acqResponseCode = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.AuthorizeId\n);
cmdResponse = in.readLine();
authorizeID = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.BatchNo\n);
cmdResponse = in.readLine();
batchNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";

Version 2.23

Commonwealth Bank of Australia

114

CommWeb Payment Server

Payment Client Integration Guide

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.

117

CommWeb Payment Server

Payment Client Integration Guide

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

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

The AMA username that can authorise the

operation of this capture transaction.

Password

The password for the AMA username.

AMA QueryDR Input Fields

In Java or COM, an example of the code for QueryDR data is:

// Step 4 - Create and send the Digital Order
Version 2.23

Commonwealth Bank of Australia

118

CommWeb Payment Server

Payment Client Integration Guide

objPayClient.doQueryDR(merchantID, MerchTxnRef, user, password);

In sockets, an example of the code for QueryDR data is:

// Step 4 - Create and send the Digital Order
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:
// Step 5 - Check the DR to see if there is a valid result
// *******************************************************
// Use the "nextResult" command to check if the DR contains a result
if (!objPayClient.nextResult()) {
// Retrieve the Payment Client Error (There may be none to get)
result = objPayClient.getResultField("PaymentClient.Error");
if (result != null && result.length() != 0) {
exception = result;
}
Version 2.23

Commonwealth Bank of Australia

119

CommWeb Payment Server

Payment Client Integration Guide

// Display an error as the DR doesn't contain a result

// perform error handling for this command,
return;
}
// Step 6 - Get the result data from the Digital Receipt
// *****************************************************
// Get the QSI Response Code, DRExists and MultipleDRs fields
String qsiResponseCode = objPayClient.getResultField("DigitalReceipt.QSIResponseCode");
String drExists

= objPayClient.getResultField("QueryDR.DRExists");

String multipleDRs

= objPayClient.getResultField("QueryDR.FoundMultipleDRs");

if (qsiResponseCode == null || qsiResponseCode.length() == 0) {

// Display an error as QSIResponseCode could not be retrieved
// perform error handling for this command,
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");
if (result != null && result.length() != 0) {
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
// perform error handling for this command,
} else {
// This error relates to the QueryDR command and not the
// transaction that was queried
// perform error handling for this command,
}
return;
}
// Define Output variables inside 'if' statement
String transAmount

= "";

String receiptNo

= "";

String acqResponseCode = "";

String authorizeID
Version 2.23

= "";
Commonwealth Bank of Australia

120

CommWeb Payment Server

Payment Client Integration Guide

String batchNo

= "";

String transactionNo

= "";

String orderinfo

= "";

String cardType

= "";

if (drExists != null && drExists.equalsIgnoreCase("Y")) {

= objPayClient.getResultField("DigitalReceipt.MerchantId");

transAmount

= objPayClient.getResultField("DigitalReceipt.PurchaseAmountInteger");

receiptNo

= objPayClient.getResultField("DigitalReceipt.ReceiptNo");

acqResponseCode = objPayClient.getResultField("DigitalReceipt.AcqResponseCode");
authorizeID

= objPayClient.getResultField("DigitalReceipt.AuthorizeId");

batchNo

= objPayClient.getResultField("DigitalReceipt.BatchNo");

transactionNo

= objPayClient.getResultField("DigitalReceipt.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

= objPayClient.getResultField("DigitalReceipt.OrderInfo");

cardType

= objPayClient.getResultField("DigitalReceipt.CardType");

} else {
// Get the result from the Digital Receipt
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
// perform error handling for this command,
return;
}
}
}
// Step 7 - We are finished with the Payment Client so tidy up
// ***********************************************************
// nothing to be done in Java

Version 2.23

Commonwealth Bank of Australia

121

CommWeb Payment Server

Payment Client Integration Guide

In sockets, an example of the QueryDR code extract is:

// Step 5 - Check the DR to see if there is a valid result
// *******************************************************
// Use the "nextResult" command to check if the DR contains a result
out.print("5,", res, req);
cmdResponse = in.readLine();
if (!cmdResponse.substring(0,1).equals(OK)) {
// Retrieve the Payment Client Error (There may be none to get)
out.print("4,PaymentClient.Error\n);
cmdResponse = in.readLine();
if (cmdResponse.substring(0,1).equals(OK)) {
exception = cmdResponse.substring(2);
}
// Display an Error as the DR doesn't contain a valid result
// perform error handling for this command
sock.close();
return;
}
// Step 6 - Get the result data from the Digital Receipt
// *****************************************************
// Get the QSI Response Code, DRExists and MultipleDRs fields
String qsiResponseCode = ;
String drExists = ;
String multipleDRs = ;
out.print("4,DigitalReceipt.QSIResponseCode\n);
cmdResponse = in.readLine();
if (!cmdResponse.substring(0,1).equals(1)) {
// Display an Error Page as the QSIResponseCode could not be retrieved
// perform error handling for this command
sock.close();
return;
} else {
qsiResponseCode = cmdResponse.substring(2);
}
out.print("4,QueryDR.DRExists\n);
cmdResponse = in.readLine();
if (!cmdResponse.substring(0,1).equals(1)) {
// Display an Error Page as the QSIResponseCode could not be retrieved
// perform error handling for this command
sock.close();
return;
} else {
Version 2.23

Commonwealth Bank of Australia

122

CommWeb Payment Server

Payment Client Integration Guide

drExists = cmdResponse.substring(2);
}
out.print("4,QueryDR.FoundMultipleDRs\n);
cmdResponse = in.readLine();
if (!cmdResponse.substring(0,1).equals(1)) {
// Display an Error Page as the QSIResponseCode could not be retrieved
// perform error handling for this command
sock.close();
return;
} else {
drExists = cmdResponse.substring(2);
}
// 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
out.print("4,DigitalReceipt.ERROR\n);
cmdResponse = in.readLine();
if (cmdResponse.substring(0,1).equals(1)) {
exception = cmdResponse.substring(2);
}
// 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
// perform error handling for this command,
} else {
// This error relates to the QueryDR command and not the
// transaction that was queried
// perform error handling for this command,
}
sock.close();
return;
}
// Define Output variables inside 'if' statement
String transAmount

= "";

String receiptNo

= "";

String acqResponseCode = "";

String authorizeID

= "";

String batchNo

= "";

String transactionNo

= "";

String orderinfo

= "";

Version 2.23

Commonwealth Bank of Australia

123

CommWeb Payment Server

String cardType

Payment Client Integration Guide

= "";

if (drExists != null && drExists.equalsIgnoreCase("Y")) {

// Extract the available Digital Receipt fields
// The example retrieves the MerchantID and Transaction Amount
// values, which should be the same as the values sent. In a
// production system the sent values and the receive values
// could be checked to make sure they are the same.
out.print(4,DigitalReceipt.MerchantId\n);
cmdResponse = in.readLine();
merchantID = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.PurchaseAmountInteger\n);
cmdResponse = in.readLine();
transAmount = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.TransactionNo\n);
cmdResponse = in.readLine();
transactionNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.ReceiptNo\n);
cmdResponse = in.readLine();
receiptNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.AcqResponseCode\n);
cmdResponse = in.readLine();
acqResponseCode = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.AuthorizeId\n);
cmdResponse = in.readLine();
authorizeID = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
out.print(4,DigitalReceipt.BatchNo\n);
cmdResponse = in.readLine();
batchNo = cmdResponse.substring(0,1).equals(1) ? cmdResponse.substring(2) : "Unknown";
// 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 {
// Get the result from the Digital Receipt
out.print("4,DigitalReceipt.Result\n);
Version 2.23

Commonwealth Bank of Australia

124

CommWeb Payment Server

Payment Client Integration Guide

cmdResponse = in.readLine();
if (!cmdResponse.substring(0,1).equals(1)) {
// Display an error as the DigitalReceipt.Result could not be retrieved
// perform error handling for this command
sock.close();
return;
} else {
result = cmdResponse.substring(2);
}
}
// Step 7 - We are finished with the Payment Client so tidy up
// ***********************************************************
sock.close();

Version 2.23

Commonwealth Bank of Australia

125

/>?

Function Name

Parameters

Message
Type

echo

getDigitalOrder1

decryptDigitalReceipt

getResultField

nextResult

sendMOTODigitalOrder4

addDigitalOrderField

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

doAdminCapture

doAdminRefund

doAdminVoidCapture

getResultCount

MessageID=2310

String

getResultRecord

MessageID=24
RecordNumber11

String
String(Integer)

Version 2.21

Commonwealth Bank of Australia

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,{resultCount}
Failure: 0,0
Success:
1,{resultRecord}
Failure: 0,0

127

CommWeb Payment Server

Message
Type

Function Name

doAdminVoidPurchase

addAdminCommandField

doQueryDR

Payment Client Integration Guide

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

Commonwealth Bank of Australia

128

CommWeb Payment Server

#
!

Payment Client Integration Guide

/-?# 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

Commonwealth Bank of Australia

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

CommWeb Payment Server

/(?

Payment Client Integration Guide

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

Commonwealth Bank of Australia

Expiry Date
04/05
04/05
04/05
04/05
04/05
04/05
04/05

130

CommWeb Payment Server

Payment Client Integration Guide

!
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

Commonwealth Bank of Australia

131

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

132

CommWeb Payment Server

Payment Client Integration Guide

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

Commonwealth Bank of Australia

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

Lettings Valuation Letter
No ratings yet
Lettings Valuation Letter
4 pages
The Future of Online Banking Amidst Crises
No ratings yet
The Future of Online Banking Amidst Crises
7 pages
Robinson, Mark. UNDP. From Old Public Administration To The New Public Service
No ratings yet
Robinson, Mark. UNDP. From Old Public Administration To The New Public Service
6 pages
History of ERP
No ratings yet
History of ERP
8 pages
PayWay Net Developers Guide
No ratings yet
PayWay Net Developers Guide
38 pages
Documentation: Flutter V1.0 Savings & Multipurpose Investment Software
No ratings yet
Documentation: Flutter V1.0 Savings & Multipurpose Investment Software
20 pages
Api For Ecpay Channel Documentation: Release 0.2.0-Alpha
No ratings yet
Api For Ecpay Channel Documentation: Release 0.2.0-Alpha
9 pages
Basic Wallet Rollout - Paper
No ratings yet
Basic Wallet Rollout - Paper
12 pages
Takadimi
No ratings yet
Takadimi
4 pages
In The Name of Jesus Israel Houghton Chords
75% (4)
In The Name of Jesus Israel Houghton Chords
2 pages
Commweb Virtual Payment Client Integration Guide PDF
No ratings yet
Commweb Virtual Payment Client Integration Guide PDF
2 pages
Mobile Banking
No ratings yet
Mobile Banking
14 pages
E Money PDF
No ratings yet
E Money PDF
41 pages
Compensation Plan: Global
No ratings yet
Compensation Plan: Global
24 pages
Risk of Late Payment in The Malaysian Construction Industry
No ratings yet
Risk of Late Payment in The Malaysian Construction Industry
9 pages
Invictus Wallet Service Termination Letter
No ratings yet
Invictus Wallet Service Termination Letter
21 pages
Tamilnadu Govt Pongal Bonus G.O No 1 Date 03.01.2011 English Version
100% (1)
Tamilnadu Govt Pongal Bonus G.O No 1 Date 03.01.2011 English Version
4 pages
PayHere+eWallet Form PDF
100% (1)
PayHere+eWallet Form PDF
3 pages
Daily Credit Alert
No ratings yet
Daily Credit Alert
22 pages
Hackcelerator Problem Statements
100% (1)
Hackcelerator Problem Statements
72 pages
IMF - The Functions and Impact of Fiscal Councils
No ratings yet
IMF - The Functions and Impact of Fiscal Councils
62 pages
E-Wallet: Paper Presentation On
100% (1)
E-Wallet: Paper Presentation On
7 pages
PayPal Integration Guide
No ratings yet
PayPal Integration Guide
82 pages
Supermarket Billing Project
50% (2)
Supermarket Billing Project
27 pages
E-Commerce Electronic Payments PDF
No ratings yet
E-Commerce Electronic Payments PDF
6 pages
Sealed Complaint
No ratings yet
Sealed Complaint
28 pages
United Nations
No ratings yet
United Nations
1 page
Issues in b2b e Business
No ratings yet
Issues in b2b e Business
24 pages
A Different Kind of Voyage: Development and Dependence in The Pacific Islands
No ratings yet
A Different Kind of Voyage: Development and Dependence in The Pacific Islands
156 pages
Whatsapp Banking Cecec
No ratings yet
Whatsapp Banking Cecec
6 pages
Mas Aml-Cft Guidelines
100% (1)
Mas Aml-Cft Guidelines
54 pages
Exinity LTD ALPARI Client Agreement V8 PDF
No ratings yet
Exinity LTD ALPARI Client Agreement V8 PDF
43 pages
Let's Talk Bitcoin - Ep 78
No ratings yet
Let's Talk Bitcoin - Ep 78
22 pages
E-Book - Earn Second Salary
No ratings yet
E-Book - Earn Second Salary
24 pages
SequelPay API Manual
No ratings yet
SequelPay API Manual
121 pages
The Coin of Asian Standard Payment Guaranteed: White Paper
No ratings yet
The Coin of Asian Standard Payment Guaranteed: White Paper
25 pages
Blank Expense Form
100% (1)
Blank Expense Form
3 pages
Jurnal Teknologi: Payment Issue in Malaysian Construction Industry: Contractors' Perspective
No ratings yet
Jurnal Teknologi: Payment Issue in Malaysian Construction Industry: Contractors' Perspective
7 pages
Smart Banking
No ratings yet
Smart Banking
4 pages
2branch Cashier Training Manual 1.6
No ratings yet
2branch Cashier Training Manual 1.6
21 pages
Software Requirements Specification: Splitpay
No ratings yet
Software Requirements Specification: Splitpay
13 pages
Payment Gateway Integration
No ratings yet
Payment Gateway Integration
3 pages
A N T A M L D A SQL S: Jerzy Korczak Wojciech Merchelski Błaŝej Oleszkiewicz
No ratings yet
A N T A M L D A SQL S: Jerzy Korczak Wojciech Merchelski Błaŝej Oleszkiewicz
22 pages
PHP Payment Gateway Integration
No ratings yet
PHP Payment Gateway Integration
5 pages
NIA Online Payment Terms & Conditions
No ratings yet
NIA Online Payment Terms & Conditions
1 page
Electronic Payment Systems 2017
No ratings yet
Electronic Payment Systems 2017
49 pages
API-GatewayTokenService - v6.4 - BAC - Translated
No ratings yet
API-GatewayTokenService - v6.4 - BAC - Translated
26 pages
Simple Bank Agreement
No ratings yet
Simple Bank Agreement
30 pages
Payment Response
No ratings yet
Payment Response
34 pages
Dimensions of E-Commerce Security - Integrity
No ratings yet
Dimensions of E-Commerce Security - Integrity
17 pages
C-AP - Cash and Bank Balances
No ratings yet
C-AP - Cash and Bank Balances
7 pages
Cyclos Reference
100% (1)
Cyclos Reference
126 pages
Charging Accounting and Billing Manageme
No ratings yet
Charging Accounting and Billing Manageme
9 pages
Use Cases: Applying UML and Patterns
100% (1)
Use Cases: Applying UML and Patterns
29 pages
Integrating Instamojo
No ratings yet
Integrating Instamojo
20 pages
Registry Functional Specification v22 24
No ratings yet
Registry Functional Specification v22 24
524 pages
Network Merchants (NMI) Integration Resources: Direct Post API Documentation
No ratings yet
Network Merchants (NMI) Integration Resources: Direct Post API Documentation
11 pages
Freelance - Salary PDF 2023
No ratings yet
Freelance - Salary PDF 2023
1 page
Merchant Integration Guide
No ratings yet
Merchant Integration Guide
28 pages
Proposal For Whatsapp Banking
No ratings yet
Proposal For Whatsapp Banking
7 pages
Review of Some Online Banks and Visa/Master Cards Issuers
From Everand
Review of Some Online Banks and Visa/Master Cards Issuers
Dr. Hedaya Mahmood Alasooly
No ratings yet
Evaluation of Some Online Payment Providers Services: Best Online Banks and Visa/Master Cards Issuers
From Everand
Evaluation of Some Online Payment Providers Services: Best Online Banks and Visa/Master Cards Issuers
Dr. Hidaia Mahmood Alassouli
No ratings yet
Business + Bitcoin
From Everand
Business + Bitcoin
LaTrell Lewis
No ratings yet
Evaluation of Some Online Banks, E-Wallets and Visa/Master Card Issuers
From Everand
Evaluation of Some Online Banks, E-Wallets and Visa/Master Card Issuers
Dr. Hidaia Mahmood Alassouli
No ratings yet
Declare Array in Stored Procedure
No ratings yet
Declare Array in Stored Procedure
11 pages
It's Not Over (Israel Houghton)
No ratings yet
It's Not Over (Israel Houghton)
2 pages
MRT - Fare - Matrix Customers - Epic: Niño Francisco Alamol, V 1.0 - January 11, 2021
No ratings yet
MRT - Fare - Matrix Customers - Epic: Niño Francisco Alamol, V 1.0 - January 11, 2021
6 pages
Assign Seat (S) - PNR - Addmultielements (Option Code 0)
No ratings yet
Assign Seat (S) - PNR - Addmultielements (Option Code 0)
1 page
Here Again
No ratings yet
Here Again
4 pages
Book
No ratings yet
Book
15 pages
Approval Sheet
No ratings yet
Approval Sheet
1 page
Approval-Sheet 1
No ratings yet
Approval-Sheet 1
1 page
Learning Cocoa With Objective-C PDF
100% (2)
Learning Cocoa With Objective-C PDF
461 pages
911 Tabs
No ratings yet
911 Tabs
1 page
Tigerair Web API, This Enables User To Query Flight Itineraries, Get Pricing, Add Service Requests and Confirm Booking. Frequently Asked Questions
No ratings yet
Tigerair Web API, This Enables User To Query Flight Itineraries, Get Pricing, Add Service Requests and Confirm Booking. Frequently Asked Questions
1 page
1 Fare Basis Codes 20140224
No ratings yet
1 Fare Basis Codes 20140224
9 pages
UML - Class Diagram
No ratings yet
UML - Class Diagram
2 pages
S2I Test Cards 1 2
No ratings yet
S2I Test Cards 1 2
4 pages
WHO Is LIKE The LORD Chords - Israel Houghton - E-Chords
No ratings yet
WHO Is LIKE The LORD Chords - Israel Houghton - E-Chords
2 pages
XNA Tutorial 1 - Merged
No ratings yet
XNA Tutorial 1 - Merged
478 pages
Ignite Travel Group Scorecard - Nino Francisco Alamo
No ratings yet
Ignite Travel Group Scorecard - Nino Francisco Alamo
1 page
Amadeus Web Service Integration - in Progress
No ratings yet
Amadeus Web Service Integration - in Progress
11 pages
Taize Prayer 2016
No ratings yet
Taize Prayer 2016
6 pages
UG WBS Ticket DisplayTST 15.1
No ratings yet
UG WBS Ticket DisplayTST 15.1
69 pages
Chapter 3
No ratings yet
Chapter 3
27 pages
Quiz 10 - Performance Measurement - 2020SP-07 - MANAGERIAL ACCOUNTING
No ratings yet
Quiz 10 - Performance Measurement - 2020SP-07 - MANAGERIAL ACCOUNTING
9 pages
ANALYSING PERFORMANCE MANAGEMENT SYSTEM AT TCS TATA Consultancy Service
100% (1)
ANALYSING PERFORMANCE MANAGEMENT SYSTEM AT TCS TATA Consultancy Service
57 pages
Chapter 1 Construction Industry
No ratings yet
Chapter 1 Construction Industry
7 pages
Baker Adhesive Case Study V2
No ratings yet
Baker Adhesive Case Study V2
15 pages
Stock Control, Net Realisable Value, Mark-Up & Margin
No ratings yet
Stock Control, Net Realisable Value, Mark-Up & Margin
15 pages
Employment Issues To Consider: Asean'S Response To Covid-19
No ratings yet
Employment Issues To Consider: Asean'S Response To Covid-19
34 pages
Astm B302 (1998)
No ratings yet
Astm B302 (1998)
5 pages
Cust Copy 2
No ratings yet
Cust Copy 2
1 page
Far1 Artt Ias 8 & 33 Test Sol
No ratings yet
Far1 Artt Ias 8 & 33 Test Sol
2 pages
Macro - I Chapter One
No ratings yet
Macro - I Chapter One
25 pages
Lecture Notes: Auditing Theory L. R. Cabarles AT.1807-Preliminary Engagement Activities OCTOBER 2013
No ratings yet
Lecture Notes: Auditing Theory L. R. Cabarles AT.1807-Preliminary Engagement Activities OCTOBER 2013
7 pages
Accounting task 1 presentation answers
No ratings yet
Accounting task 1 presentation answers
3 pages
Business Matters
No ratings yet
Business Matters
3 pages
Estimation and Planning Tool For Industrial Construction Scaffolding
No ratings yet
Estimation and Planning Tool For Industrial Construction Scaffolding
9 pages
060 Sms Self-Reading - Advert 2019 - Newspapers (00000002)
No ratings yet
060 Sms Self-Reading - Advert 2019 - Newspapers (00000002)
1 page
03 Power BI Governance - SureshChanges Autosaved
No ratings yet
03 Power BI Governance - SureshChanges Autosaved
22 pages
Narayana-Aditi-Premium-Illustration
No ratings yet
Narayana-Aditi-Premium-Illustration
2 pages
Educ 207 - FINANCIAL ASPECTS IN EDUCATIONAL PLANNING v2
100% (2)
Educ 207 - FINANCIAL ASPECTS IN EDUCATIONAL PLANNING v2
7 pages
Order Fulfillment in SAP SD
No ratings yet
Order Fulfillment in SAP SD
1 page
CHAPTER 2 (Introduction To The Construction Industry)
No ratings yet
CHAPTER 2 (Introduction To The Construction Industry)
16 pages
internship report of decor
No ratings yet
internship report of decor
1 page
ISTQB Foundation Level Quick Guide
No ratings yet
ISTQB Foundation Level Quick Guide
57 pages
Accounting Chapter 1
No ratings yet
Accounting Chapter 1
17 pages
Cost and Management Accounting II Assign
No ratings yet
Cost and Management Accounting II Assign
6 pages
Steel Bridge Erection Guide Specification: American Association of State Highway and Transportation Officials
No ratings yet
Steel Bridge Erection Guide Specification: American Association of State Highway and Transportation Officials
5 pages
Hedging Example - Sheet1
No ratings yet
Hedging Example - Sheet1
1 page
Literature Review Tourism Development
100% (3)
Literature Review Tourism Development
5 pages