Eft Pos Web Services Integration Guide 5.13 March 2009

User Manual:

Open the PDF directly: View PDF .
Page Count: 65

Download
Open PDF In Browser	View PDF

Web Services Integration Guide
V5.13
March 2009

Web Services Integration Guide V5.13 – March 2009

1. Introduction ............................................................................................................................. 4
2. ICP XML V4 Overview ............................................................................................................... 5
3. Integration ............................................................................................................................... 6
3.1 Commidea Timeouts .............................................................................................. 6
3.2 Integration Testing ................................................................................................. 7
3.3 Testing URLs .......................................................................................................... 7
3.4 Integration Methods ............................................................................................... 8
3.5 Live URLs .............................................................................................................. 9
4. Message Formats ................................................................................................................... 10
4.1 Message ............................................................................................................. 10
4.2 ClientHeader ....................................................................................................... 10
4.2.1 Processing DB Field .................................................................................. 11
4.3 Error Response .................................................................................................... 11
5. Transactions .......................................................................................................................... 12
5.1 Transaction Process ............................................................................................. 12
5.2 Transaction Message Types .................................................................................. 12
5.2.1 Transaction Request .................................................................................. 12
5.2.2 ICC Data ................................................................................................. 14
5.2.3 PayerAuth AuxiliaryData ............................................................................ 17
5.2.4 Confirmation Request ............................................................................... 17
5.2.5 Rejection Request ..................................................................................... 18
5.2.6 Transaction Response ............................................................................... 19
6. PayerAuth .............................................................................................................................. 22
6.1 PayerAuth Process ................................................................................................ 22
6.1.1 PayerAuth Expiry ....................................................................................... 24
6.1.2 Canadian Corporate Purchase Cards......................................................... 24
6.1.3 Process Transaction .................................................................................. 24
6.1.4 Payer Authentication with Token................................................................. 24
6.1.5 Chargeback Information ........................................................................... 25
6.2 Cardholder Authentication Implementation Guidelines ............................................ 25
6.3 PayerAuth Message Types ..................................................................................... 26
6.3.1 PayerAuth EnrollmentCheck Request .......................................................... 26
6.3.2 PayerAuth EnrollmentCheck Response ........................................................ 29
6.3.3 PayerAuth AuthenticationCheck Request ..................................................... 29
6.3.4 PayerAuth AuthenticationCheck Response ................................................... 30
6.4 3D Secure Matrix ................................................................................................. 31
6.4.1 3D Secure Matrix – Visa VbV Transactions .................................................. 31
6.4.2 3D Secure Matrix – MasterCard SecureCode Transactions ........................... 33
6.4.3 Non Supporting Card Schemes.................................................................. 34
7. Token Gateway ...................................................................................................................... 35
7.1 Token Registration Process.................................................................................... 35
7.2 Token Message Types .......................................................................................... 35
7.2.1 Registration Request.................................................................................. 35
7.2.2 Token Registration Response ..................................................................... 36
8. Ukash Message Types ............................................................................................................. 37
8.1 Ukash GetSettleAmount Request ........................................................................... 37
8.2 Ukash PartSpendVoucher Request ......................................................................... 38
8.3 Ukash FullValueVoucher Request .......................................................................... 39
8.4 Ukash PartSpendAccount Request ......................................................................... 40
8.5 Ukash FullSpendAccount Request .......................................................................... 41
8.6 TransactionEnquiry Request .................................................................................. 42
8.7 Ukash Response .................................................................................................. 43
8.8 Ukash Return Code List ........................................................................................ 44
8.9 Ukash Transaction Type List .................................................................................. 44
8.10 Ukash Error Code List ........................................................................................ 45
8.11 Ukash Product Codes......................................................................................... 46
9. Troubleshooting ..................................................................................................................... 49
9.1 Deserialization Errors ........................................................................................... 49
9.2 Contact Information ............................................................................................. 49
APPENDIX A – Website Testing Script ........................................................................................... 50
Commidea ICP © 2004-2009

Page 2 of 65

Web Services Integration Guide V5.13 – March 2009

APPENDIX B – Currency Code ISO 4217 ..................................................................................... 52
APPENDIX C – Country Codes ISO 3166 ..................................................................................... 55
APPENDIX D – Performing a LUHN Check .................................................................................... 60
APPENDIX E – Commidea Error Codes......................................................................................... 61

Page 3 of 65

Web Services Integration Guide V5.13 – March 2009

1. Introduction
This document is or use when integrating to the Commidea Web Service solution – XML V4. Contained
within are descriptions and examples of the record structures required, as well as a step-by-step guide to
how the process works.

Page 4 of 65

Web Services Integration Guide V5.13 – March 2009

2. ICP XML V4 Overview
The latest version of the Web Services solution provides merchants with a more resilient design and faster
service using Commidea’s next generation ICP system architecture.
It also contains support for the following:
•

Payer Authentication
this module allows MasterCard and Visa payments to be verified by entering a password, should
the card be enrolled in this service with the issuer.

•

Token Gateway
this functionality provides the ability to register a customer’s payment details with the Token
Gateway which will return a token as a reference. None of the sensitive card details therefore
need to be stored by the merchant, and can be reused in future by providing the token ID.

•

Ukash
this module will allow customers to pay for items using either a Ukash Voucher or Ukash
Account. Ukash account and vouchers enable people to pre-pay for items. The Voucher itself
contains a 19 digit code which is entered when paying for goods online. Should there be any
remaining amount from the voucher after the purchase; another code is generated for the
remaining amount.

Each of the transaction types available are listed in sections throughout the manual. For each, the process
will be explained, and then the message types themselves listed. This will provide an understanding of
how each works, and then all the messaging information required to incorporate the functionality.

Page 5 of 65

Web Services Integration Guide V5.13 – March 2009

3. Integration
To enable merchants to integrate to their systems, Commidea has a fully functional test system in place
for each version.
The process for new integrations is to develop to the test server and once the integrator is satisfied that the
solution is fully functional, contact is made with the Implementations Department to arrange for
integration testing. It is recommended that some testing is performed on the integration before booking a
testing slot. To help with this there is a list of checks that will be performed included within the manual
(please see Appendix A). Within this list there are tests performed on the ability to respond accordingly to
declines and voice referrals – to help with this there are some default values which stimulate certain
behaviour:
Value
.00
.02
.05
.08

Expected Outcome
Accepted, 789DE
Voice referred
Declined
Refund Offline

The correct address / CSC input to get a full match is: 10, ME156LH with CSC 000
Below are the different input combinations and the expected output:
CSC Value

555
000
111

CVCRESULT
0 – Not Provided
1 – Not Checked
2 – Matched
4 – Not Matched

Address Line 1 Value

55
10
11

AD1AVSRESULT
0 – Not Provided
1 – Not Checked
2 – Matched
4 – Not Matched

Post Code Value

ME555LH or 555
ME156LH or 156
ME111LH or 111

PCAVSRESULT
0 – Not Provided
1 – Not Checked
2 – Matched
4 – Not Matched

The test system is also configured to return a dummy authorisation code for every transaction; so do not
be concerned by the fact that every transaction returns the same code. This will be ‘789DE’.
To obtain a test account, please contact the Implementations Team at implementations@commidea.com,
specifying which system solution is being integrated to. They may then ask for more information before
issuing a test account, dependant on which features of XML V4 are to be utilised.
3.1 Commidea Timeouts
Transaction Authorisation Database Timeout – 45 seconds
This is the period for which ICP will wait for a transaction result until returning an authorisation error as
the transaction result.
Commidea Web Service Timeout – 60 seconds
This is the period after which ICP will timeout should it not be able to post the result back to the
merchant.
Commidea Payer Authentication Database Timeout – 30 seconds
This is the period of time that ICP will wait until it receives a response back from the Payer Authentication
application. It will return a Commidea timeout response in this instance.

Page 6 of 65

Web Services Integration Guide V5.13 – March 2009

3.2 Integration Testing
As aforementioned, vigorous testing is performed by Commidea before any solution can be used in a live
environment. To help developers ensure the application or website is ready for this testing; below are a
list of recommendations to adhere to:
•
•

•
•
•
•
•

Confirmation messages should be sent in every scenario except:
o After receiving a negative error code response
o When processing pre authorisation transactions, as these are automatically confirmed
A timeout period should be in place to ensure that, if no confirmation response is received after
a predefined period of time, the confirmation message is resent. A new transaction should not
be raised in this scenario, as this can result in duplicate orders. Should there be any issues with
recurring responses not being returned please contact Implementations during testing, or the
Helpdesk once the solution is being used in a live environment
Build timeout periods into the solution to ensure that should there be any connection errors that
these are captured and counteracted suitably
Perform validation on fields locally before posting the record to the ICP server. For example,
only allow numeric values to be entered into the relevant fields
Perform card checks locally using LUHN validation (see Appendix D)
When reporting a voice referral to the user, do not inform them that the transaction has been
“declined”, as this is not the case. Inform the users something similar to: “… your payment
attempt was unsuccessful, please use an alternative card”
Before having a Commidea Engineer perform Integration Testing, ensure the solution is as close
to the final product which will be set live as possible. For example; all on screen messages
displayed to the user will need to be checked, so the solution must be complete and in full
working order before being tested

When the solution being built is a website, the following should be considered during development:
•
•
•
•
•

Only include logos for card schemes that can be accepted by the site
Disable use of the ‘Back’ button / ensure data from previous pages is cleared and therefore
cannot be fraudulently retrieved by returning to the page
Remove the ability for duplicate orders to be raised through the system by disabling the order
button after the order has been submitted
As mentioned in the general list of recommendations, integration of the website should be the
last step of development before it is set live. In this case, it should be an exact replica of the live
site, or as close a representation as possible
Disabling the ability to copy and paste from within the web form for added security

For more information
For a table of tests to run through before releasing the solution to Commidea for testing, please see
Appendix A.
3.3 Testing URLs
Please find below the test URLs required to gain access to the XML payment service:
https://testweb.commidea.com/commideagateway/commideagateway.asmx

Page 7 of 65

Web Services Integration Guide V5.13 – March 2009

3.4 Integration Methods
Before describing the records that are required it would make sense to discuss the available methods to
invoke the Commidea Web Service. To make the solution as pliable as possible there are the following
options:
a)

SOAP

This is a standard for exchanging XML-based messages, and forms a foundation layer of the web services
stack, which provides a basic messaging framework that more abstract layers can be built on.
To enable merchants to integrate using this method there are a set of XSDs available which can be
obtained from implementations@commidea.com.
Alternatively the descriptions are available at the following URL:
https://testweb.commidea.com/commideagateway/commideagateway.asmx?op=ProcessMsg
b)

Web Service Proxy

A Web Service Proxy can be created from within Microsoft Visual Studio .Net by adding a web reference
to the URL of the web service, or by a tool called Web Service Description Language Tool (wsdl.exe). The
proxy class that is generated from the WSDL that describes the web services has the same method
signatures as the web service and hides the implementation details so that calling the web service is
transparent. This can then be used to create a new instance of the web service object as though it is a
local object instead of a remote one.
c)

Web Service Discovery Language

To access the WSDL descriptions, please visit the following URLs:
https://testweb.commidea.com/commideagateway/commideagateway.asmx?WSDL
d)

Web Referencing

XML V4 has been made simple to integrate into with the ability to add a web reference with Microsoft
Visual Studio 2005. Following are the instructions for how to do this:
i.

Right click in the project to add the reference to, and then
select “Add Web Reference”:

ii.

The address of the web service is then requested. Insert this
into the “URL:” text box and press “Go”. The service should
then be found, and “Add Reference” clicked to import it into
the project.

Page 8 of 65

Web Services Integration Guide V5.13 – March 2009

Now that the reference has been added enabling consumption of the web service, via the use of a proxy
class.
3.5 Live URLs
Once integration testing has been passed, the URLs being posted to by the solution will need to be
updated. These will be supplied after integration testing has been completed and signed off.
The other change necessary would be to the merchant account specific information; the live account
information to be used by the merchant will be required. This will entail updating the Merchant Header
and Account ID.

Page 9 of 65

Web Services Integration Guide V5.13 – March 2009

4. Message Formats
All the XML data that is submitted to a Commidea Web Service must be formatted correctly; otherwise it
will be rejected, and must be enclosed in the correct root element depending on the Web Service being
called.
If passing data that contains any XML mark-up characters (e.g. ampersand ‘&’ or less than / greater than
symbols ‘< >’) then it is recommended that the ‘CDATAWrapping’ flag within the Client Header is
enabled. This informs the XML parser that it is not to be interpreted as mark-up. Here is an example,
where using a reference of “Chip&Pin”:
<[!CDATA[…]]>
Detailed below are the formats which all messages will be wrapped in.
4.1 Message
All requests and responses will be wrapped in a message type, as defined below:

Section/Fields

Type/Format

Mandatory
/ Optional

Description

messagetype
messagedata
clientheader

String
String
ClientHeader

M
M
M

Type of message
Data
ClientHeader information

4.2 ClientHeader
The clientheader is used to validate requests and direct them to the correct server:

Section/Fields

Type/Format

Mandatory
/ Optional

Description

SystemID
SystemGUID
Passcode
ProcessingDB

Decimal
String
String
String

M
M
M
M (for Confirmation Request
and Rejection Request)

SendAttempt

Integer

CDATAWrapping

Boolean

Allocated ID
Allocated GUID
Allocated Passcode
This indicates the database to use for
processing a particular request. If left
blank the default database will be
used.
N.B. Should only be left blank for the
initial transaction request. (See 4.2.1)
If greater than 0 this indicates that this
is a resend attempt and duplicate
checking should be performed. Max
value of 5 before an automatic
declined response is returned.
Commidea will hold unconfirmed
transactions up to 10 days based on
acquirer authorisation expiries
If true then response messages will be
CDATA wrapped. If false then they will
not be wrapped. If this boolean is not
passed then by default wrapping will
be disabled. We highly recommend
that this is enabled

Page 10 of 65

Web Services Integration Guide V5.13 – March 2009

4.2.1 Processing DB Field
To further explain the use of this field within the ClientHeader, this field does not need to be populated
during the initial request, unless advised otherwise. However, when sending a Confirmation or Rejection
Request this field must be populated with the same ProcessingDB as returned in the Transaction
Response. This will ensure that the Confirmation or Rejection is sent to the same database which is
awaiting the final decision on the transaction.
The Processing DB tag needs to be set for:
•
•
•

Authentication Request (for Payer Authentication)
Transaction Confirmation
Transaction Rejection

Essentially, any transactions that receive a Processing DB value within the response need to include this
same value within any subsequent requests.
4.3 Error Response

The error response will be returned in the event of a processing error:

Section/Fields

Type/Format

Description

Code
MsgTxt

Integer
String

Code indicating error type
Description of error

Page 11 of 65

Web Services Integration Guide V5.13 – March 2009

5. Transactions
5.1 Transaction Process
To process a transaction using XML V4 the following procedure is used:

Merchant System

Commidea Server

Order and cardholder
data captured
Transaction Request sent to
Commidea, along with any ICC,
Auxiliary or PayerAuth Data
Commidea seeks authorisation
on behalf of merchant
Transaction Response
generated and returned to host

Merchant stores response and
returns confirmation/rejection
Merchant informs customer of result
and completes/cancels order

Commidea stores transaction
ready for end of day settlement

5.2 Transaction Message Types
5.2.1 Transaction Request
The transaction request type contains all the required information to authorise the requested transaction
type.
The Message Type for the transaction request is TXN and the namespace is TXN.

Section/Fields

Type/Format

Mandatory
/ Optional

Description

merchantreference

String

accountid

Decimal

txntype

String

transactioncurrencycode
terminalcountrycode

String
String

M
M

apacsterminalcapabilities

String

Merchant can add a reference to cross reference
responses relating to the same transaction
Account reference number, supplied by
Commidea
01 – Purchase
02 – Refund
04 – Cash Advance
05 – Purchase with cash back (PWCB)
06 – Continuous Authority
This is the three digit currency code (numeric).
In accordance with the numeric values defined in
ISO 3166 (see Appendix C)
This is the functionality supported by the terminal
in the format of that defined by the APACS
standard. These are:

Page 12 of 65

Web Services Integration Guide V5.13 – March 2009

3291 – Only Swiped and Contact ICC
unattended
4290 – Mail Order/Telephone Order
4298 – CNP/ECommerce (if flagged for payer
authorisation with acquirer; no CNP transactions
are allowed with the exception of refunds)
6290 - Keyed and Swiped Customer Present
7296 – Contact (ICC) Keyed and Swiped
B291 – Swiped, Contact ICC and Contactless
unattended
C296 – Contactless and keyed transactions (a
contactless auxiliary record should be presented
for all transactions passed under this terminal
type)
F296 – Keyed, Swiped, Contact and Contactless
EMV transactions (a contactless auxiliary record
should be present for all transactions passed
under this terminal type)

capturemethod

processingidentifier

Integer

Integrators should check with Implementations to
confirm that they have the correct capabilities.
This indicates how the card details were
obtained. Acceptable values are:
1 – Keyed Cardholder Present
2 – Keyed Cardholder Not Present Mail Order
3 – Swiped
4 – ICC Fallback to Swipe
5 – ICC Fallback to Signature
6 – ICC PIN Only
7 – ICC PIN and Signature
8 – ICC – No CVM
9 – Contactless EMV
10 – Contactless Mag Stripe
11 – Keyed Cardholder Not Present Telephone
Order
12 – Keyed Cardholder Not Present ECommerce Order
This indicates the type of processing that needs
to be undertaken. Current available values are
as follows:
1 – Auth and Charge
2 – Auth Only
3 – Charge Only

tokenid
pan

Decimal
String

O
C

track2

String

csc

String

avshouse

String

avspostcode

String

All refund transactions should use the ‘Charge
Only’ option.
Token Identifier for token transaction
Card number (Conditionally required, not
needed if providing a Token ID)
Entire Track2 contents
(including start and end sentinels and LRC)
(Conditionally required, not needed if providing
a Token ID)
Amex Card – 3 or 4 digits (front of card) All
Other Cards – 3 or 4 digits (rear security strip)
Field checked by Address Verification System
(AVS) add on module, ignored if module not
enabled. AVS configuration can make this field
mandatory. Numerics from house name\number
Field checked by Address Verification System
(AVS) add on module, ignored if module not
enabled. AVS configuration can make this field
mandatory. Numerics from postcode

Page 13 of 65

Web Services Integration Guide V5.13 – March 2009
issuenumber
expirydate

startdate

txnvalue

String

1 or 2 digit card issue number. Only required by
some Switch, Solo and Laser cards, and only
required when card is keyed
String
C
Card expiry month and year (YYMM)
(Only required when card is keyed, can be
calculated from Track2)
(Conditionally required, not needed if providing
a Token ID)
String
O
Card start date month and year (MMYY)
Only required for American Express, Diners Club
International, some Switch, some Solo and some
Laser cards. Not required if Track2 data supplied
Please note the format difference between the expiry and start dates are intentional
Decimal
M
Total value of transaction including tax. Applies
to: Purchase, Refund, Cheque Guarantee, Cash
Advance, and Purchase with Cash Back.
With PWCB, field should only contain the values
of the goods or services provided.
Decimal point recommended but optional, e.g.:

cashback

Decimal

gratuity
authcode
transactiondatetime

Decimal
String
String

O
O
O

iccdata
vgisid
employeeid

iccdata
String
String

O
O
O

payerauthauxiliarydata

String

1.23 = £1.23
123 = £123
000001.23 = £1.23
Only positive values. Values will be truncated to
the correct number of decimal places required
for the transaction currency (set by the merchant
account being used)
Total Cash Back value for PWCB transactions.
Values will be truncated (without rounding) to the
number of decimal places required for the
transaction currency. Positive values only.
Additional value to add to total (e.g. service tip)
Only supplied for Offline transactions
Date and time the transaction was started, based
on GMT (dd/mm/yyyy hh:mm:ss).
Contains ICC data
VGIS XML data (Reserved for future use)
Field used to add information on the employee
processing the transaction
Payer Authentication auxiliary data

5.2.2 ICC Data
When processing an ICC transaction, this message type is used to supply the extra information required.

Section/Fields

Type/Format

Mandatory
/ Optional

Description

emvterminalcapabilities

String

emvterminaltype

String

The terminal capabilities as defined in
the EMV specifications.
Terminal type/Currency indicator
S = Sterling
E = Euro
0 = Unspecified terminal capabilities –
S
1 = ICC reader only – S
2 = Magnetic stripe only – S
3 = ICC/Magnetic stripe – S
4 = No card reader – S
5 = Unspecified terminal capabilities –
E

Page 14 of 65

Web Services Integration Guide V5.13 – March 2009

reasononlinecode

String

arqc

String

apppansequenceno

String

aip

String

atc

String

unpredictableno
tvr

String
String

M
M

cryptotxntype

String

iad

String

aid

String

terminalapplicationversionnumber

String

cardapplicationversionnumber

String

cvmr

String

6 = ICC reader only – E
7 = Magnetic stripe only – E
8 = ICC/Magnetic stripe – E
9 = No card reader – E
In the provisional European Standard
(prENV 1750) the On-line reason codes
are four digits in the form 15XX for PoS
type of environment. As all PoS codes
begin 15 there is no need to send this
fixed value and therefore only the XX as
defined in the ENV 1750 need be
transmitted. Reason On-line will be
used by the acquirer to determine if
stand-in authorisation would be an
appropriate action for this transaction.
I.e. was it the ICC or the CAD which
required an on-line authorisation.
Cryptogram generated by card at end of
offline and online declined transactions.
Can be used to validate the risk
management activities for a given
transaction (passed by ICC Terminal)
Identifies and differentiates cards with
some PAN (ICC Card passes this
information)
Application Interchange Profile (passed
by ICC terminal)
Value of the last online transaction
(passed by ICC terminal)
(passed by ICC terminal)
Terminal Verification Results. Record of
outcome of various application
functions performed by Cardholder
System (passed by ICC terminal)
Indicates transaction type used to
application usage control. One of the
following passed by ICC terminal:
00 – Purchase
09 – Purchase with Cash Back
20 – Refund
Present if provided by ICC in
GENERATE AC command response
(passed by ICC terminal)
Data label that identifies an application
on card or terminal. E.g. AID for VSDC
is 1010, Visa Electron is 2010, and Plus
is 8010. Card and Terminals use AIDs
to determine which applications are
mutually supported; both card and
terminal must support the same AID to
initiate a transaction. Both cards and
terminals may support multiple AIDs
(passed by ICC terminal)
A version number allocated by the
payment scheme used to ensure
compatibility between the IC and the
terminal. (extracted from the IC Terminal
Tag 9F 09)
Version number assigned by the
payment system for the application on
the IC card (extracted from the IC Card
Tag 9F 08)
Identifies a method of verification of the
cardholder supported by the application

Page 15 of 65

Web Services Integration Guide V5.13 – March 2009

cryptoinfodata

String

e.g. Chip and Pin but in a numeric code
(extracted from the IC Card)
Please see EMVECO Application
Specification Book 3 Page 16 for
breakdown (passed by ICC terminal)

Page 16 of 65

Web Services Integration Guide V5.13 – March 2009

5.2.3 PayerAuth AuxiliaryData
After performing the PayerAuth process to check if the card has been enrolled and then authenticated;
this message type is used to attach the PayerAuth results to the transaction.

Section/Fields

Type/Format

Mandatory
/ Optional

Description

authenticationstatus

String

authenticationcavv

String

authenticationeci

String

atsdata
transactionid

String
String

M
M

Indicates if the transaction authenticated or not:
Y – Customer was successfully authenticated
N – Customer failed authentication, and the
transaction declined
A – Attempts processing. APACS message will
show verified enrollment but cardholder not
participating
U – Enrollment could not be completed, due to
technical or other problem
Contains 28-byte Base-64 encoded Cardholder
Authentication Verification Value (CAVV)
2 digit Electronic Commerce Indicator (ECI)
value
Data to populate authorisation message
TransactionID should be populated with the
PayerAuthRequestID provided in the PayerAuth
EnrollmentCheck Response

5.2.4 Confirmation Request
This message type is used to confirm the transaction.
The Message Type for the confirmation request is CNF and the namespace is TXN.

Section/Fields

Type/Format

Mandatory
/ Optional

Description

transactionid
offlineauthcode
gratuity
transactioncertificate
arc
applicatonusagecontrol
tvr
cid
tsi
iad

Decimal
String
Decimal
String
String
String
String
String
String
String

M
O
O
M for ICC
M for ICC
M for ICC
M for ICC
M for ICC
M for ICC
M for ICC

TransactionID from ProcessTransaction request
AuthCode if transaction was authorised offline
Additional value to add to total (e.g. service tip)
Transaction certificate from 2nd generate
Auth response code
Application usage control
Terminal verification results
Cryptogram information data
Transaction status information
Issuer Application Data

Page 17 of 65

Web Services Integration Guide V5.13 – March 2009

5.2.5 Rejection Request
This message type is used to reject the transaction.
The Message Type for the transaction request is RJT and the namespace is TXN.

Section/Fields

Type/Format

Mandatory /
Optional

Description

transactionid
tokenid
capturemethod

Decimal
Decimal
Integer

M
O
M

pan
track2

String
String

M
M

csc

String

avshouse

String

avspostcode

String

TransactionID from ProcessTransaction request
Token identifier for token transaction
This indicates how the card details were
obtained. Acceptable values are:
Keyed Customer Present = 1
Keyed Customer Not Present Mail Order = 2
Swiped = 3
ICC Fallback to Swipe = 4
ICC Fallback to Signature = 5
ICC PIN Only = 6
ICC PIN and Signature = 7
ICC – No CVM = 8
Contactless EMV = 9
Contactless Mag Stripe = 10
Keyed Customer Not Present Telephone Order
= 11
Keyed Customer Not Present E-Commerce =
12
Card number (when card keyed)
Entire Track2 contents
(including start and end sentinels and LRC)
Amex Card – 3 or 4 digits (front of card) All
Other Cards – 3 or 4 digits (rear security strip)
Field checked by Address Verification System
(AVS) add on module, ignored if module not
enabled. AVS configuration can make this field
mandatory. Numerics from house
name\number
Field checked by Address Verification System
(AVS) add on module, ignored if module not
enabled. AVS configuration can make this field
mandatory. Numerics from postcode

Page 18 of 65

Web Services Integration Guide V5.13 – March 2009

5.2.6 Transaction Response
This message type which will contain the response from the transaction.
The Message Type for the transaction response is TRM (for initial transactions result message) and FT (for
the final transaction result message) and the namespace is TXN.

Section/Fields

Type/Format

Description

merchantreference

String

transactionid
resultdatetimestring

Decimal
String

processingdb

String

errormsg
merchantnumber
tid
schemename

String
String
String
String

Merchant can add a reference to cross reference responses
relating to the same transaction
Unique transaction ID
Extended date and time string
( YYYY-MM-DDTHH:MM:SS:ss)
This indicates the database to use for processing a particular
request. If left blank the default database will be used.
Error message
Unique merchant number
Terminal ID
Card scheme name

messagenumber

String

authcode

String

authmessage

String

vrtel

String

txnresult

String

1 – Amex
2 – Visa
3 – MasterCard
4 – Maestro
5 – Diners
6 – Delta
7 – JCB
8 – BT Test Host
9 – Time
10 – Solo
11 – Electron
21 – Visa CPC
23 – AllStar CPC
24 – EDC/Maestro
25 – Laser
26 – LTF
27 – CAF
28 – Creation
29 – Clydesdale
31 – BHS Gold
32 – Mothercare Card
33 – Burton Menswear
35 – BA AirPlus
36 – Amex CPC
999 – Invalid Card Range
Transaction message number (equivalent of EFTSN from previous
versions of the Web Service)
Authorisation code return by bank. Blank if the transaction
declined or if transaction value is below the floor limit
Authorisation message
e.g. ‘RETAIN CARD’
Telephone number to be called by the operator to seek manual
authorisation. Only supplied for referred transactions
Transaction result:
ERROR
REFERRAL
COMMSDOWN
DECLINED
REJECTED
CHARGED
APPROVED
AUTHORISED

Page 19 of 65

Web Services Integration Guide V5.13 – March 2009

pcavsresult

Integer

AUTHONLY
Postcode AVS result:
0 – Not provided*
1 – Not checked
2 – Matched
4 – Not matched

ad1avsresult

Integer

Default result when no details are provided.
Address line 1 AVS result:
0 – Not provided*
1 – Not checked
2 – Matched
4 – Not matched

cvcresult

Integer

Default result when no details are provided.
CVC result:
0 – Not provided*
1 – Not checked
2 – Matched
4 – Not matched

arc

String

Default result when no details are provided.
Acquirer response code

Code Message Value - Status

0 Authorised – Authorised
2 Referred – Refused
4 Hold Card – Refused
5 Refused – Refused
8 Approve After Identification – Refused
13 Invalid Amount – Refused
15 Invalid Card Issuer – Refused
17 Annulation By Client – Refused
28 Access Denied – Refused
29 Impossible Reference Number – Refused
33 Card Expired – Refused
34 Fraud Suspicion – Refused
38 Security Code Expired – Refused
41 Lost Card – Refused
43 Stolen Card, Pick Up – Refused
51 Limit Exceeded – Refused
55 Invalid Security Code – Refused
56 Unknown Card – Refused
57 Illegal Transaction – Refused
62 Restricted Card – Refused
63 Security Rules Violated – Refused
75 Security Code Invalid – Refused
76 Card Blocked – Refused
85 Rejected By Card Issuer – Refused
91 Creditcard Issuer Temporarily Not Reachable – Refused
97 Security Breach – Refused
3 –Invalid Acceptor – Error
12 Invalid Transaction – Error
14 Invalid Account – Error
19 Repeat Of Last Transaction – Error
20 Acquirer Error – Error
21 Reversal Not Processed, Missing Authorisation – Error
24 Update Of File Impossible – Error
25 Reference Number Cannot Be Found – Error
26 Duplicate Reference Number – Error
27 Error In Reference Number Field – Error
30 Format Error – Error
31 Unknown Acquirer Account Code – Error

Page 20 of 65

Web Services Integration Guide V5.13 – March 2009

iadarc
iadoad
isd
authorisingentity

String
String
String
Integer

40 Requested Function Not Supported – Error
58 Transaction Not Permitted – Error
64 Amount Higher Than Previous Transaction Amount – Error
68 Transaction Timed Out – Error
80 Amount No Longer Available, Authorisation Expired – Error
92 Creditcard Type Not Processed By Acquirer – Error
94 Duplicate Request Error – Error
Authorisation response cryptogram
Optional additional data
Issuer script data
This indicates who actually performed the authorisation
processing. Valid values are as follows:
Not Provided = 0
Merchant = 1
Acquirer = 2
Card Scheme = 4
Issuer = 8

Page 21 of 65

Web Services Integration Guide V5.13 – March 2009

6. PayerAuth
6.1 PayerAuth Process
Payer Authentication checking, this adds support for Verified by Visa and MasterCard SecureCode without
running additional software. These cardholder authentication services deter unauthorised card use.
Additionally participating merchants receive added protection from fraudulent chargeback activity. Those
who do not use these services may be liable for higher merchant fees; it is recommended to check this
with the acquirer in question. Here is an overview of the entire process:

Merchant System

Commidea
Server

Directory
Server

Order and cardholder
data captured
Enrollment Check Request sent
to Commidea

Commidea sends check onto
Visa / MasterCard Directory
Server to check for enrollment

Enrollment Check returns ‘N’

Call Authentication Check, populating only
the PayerAuthID and enrolled properties of
the AuthenticationCheckRequest

Enrollment Check returns result,
PAReq message, and ACS URL

Directory Server contacts
issuing bank to find out if
the card is enrolled

Directory Server informs
Commidea if the card is
enrolled or not
Yes

Use ACS URL to send the PAReq to
issuing bank. Include TermURL for
Bank to post PARes to afterwards

Customer directed to ACS
page to enter their password
Issuing bank records
authentication result from
information customer
provides (including password)

Extract the PARes message and
request the Commidea
Authentication Check to validate

Result posted back to TermUrl
in the form of a PARes message

Merchant decides whether to
proceed and process the
transaction

Page 22 of 65

Web Services Integration Guide V5.13 – March 2009

The process for this is as follows: as with standard transaction processing, the cardholder details and
order information is captured, but this is then passed to the Commidea Enrollment Check. This discovers
if the cardholder is enrolled by sending it onto the VISA or MasterCard Directory Server, this then contacts
the issuer to check. If the cardholder is enrolled, they are redirected to the cardholder’s web site by the
host system (the URL is provided in the enrollment response) and they then enter their password. A string
result is returned for validation, and used when calling the Commidea Authentication Check service to
ensure this is valid. A response will be received; detailing the validity and the transaction can then be
continued or aborted. This decision is up to the merchant and will take into account the outcome of the
validity check.
To ensure that the process is clear, here are the steps required in their entirety:
i.
ii.
iii.
iv.

The cardholder creates an order on the system, and clicks the ‘Buy’ button, which sends a post
of the final buy page
Create and send an Enrollment Check request, populating it with all the details from the
webpage order
This is sent onto the Directory Server, which contacts the issuing bank and finds out if the card is
enrolled or not
The Check Enrollment response is sent and if the card is enrolled contains:
a. Y
b. The PaReq message required to send to the issuing bank
c. Access Control Server (ACS) URL

If the card is not enrolled, proceed to step x.
v.
Send the PaReq message to the bank to request authentication. To do this, create a web page
that only has hidden content, including a form that meets the following requirements:
The forms action is the ACS URL, which displays the issuing bank’s dialog requesting the
authentication password from the cardholder
The form includes the required hidden field PaReq, the value of which was returned to the
merchant in the Enrollment Check response. It is necessary to remove any White Space
within this PaReq field otherwise this will cause errors when it is returned to the bank.
The form includes the required field TermUrl, the value of which is the location where the
merchant wants the bank to post the payment authentication response (PaRes) message.
The form must include the hidden field MD (merchant data); however, including a value in
this field is optional. The value has no meaning to the bank, but is guaranteed to be
returned without change. This allows the merchant to tag the redirect with a reference which
will be returned during the redirect.
This page typically include JavaScript that automatically posts the form when the page loads
(onload script)
vi.
Open this page in the cardholder’s web browser. Due to popup-blocking software, it is
recommended opening this in the main browser window. The cardholder’s web browser displays
the issuing bank’s authentication dialog, and enters their secret password for the credit card.
vii.
The issuing bank records the result of the authentication dialog with the cardholder and sends it
to the merchant, along with the transaction details, in a digitally signed PaRes message. The
result is posted to the TermUrl on the web site, and the form posted by the issuing bank includes
the PaRes.
viii.
Extract the PaRes message from the form data and request the Commidea Authentication Check
to validate the contents of the PaRes message.
ix.
Depending upon the result of the Authentication Check; the merchant can now decide whether
or not to proceed.
x.
If the Enrollment Check indicated that the card was not enrolled, then call the Authentication
Check populating only the PayerAuthRequestID and setting Nwithin the
AuthenticationCheckRequest.
If the card was enrolled and the merchant has now received the PaRes then populate
PayerAuthRequestID, set the request to Y and include the PaRes message in the
AuthenticationCheckRequest.
xi.
xii.

Populate a Transaction Request with all the relevant details
Invoke the Process Transaction method, passing the Transaction Request and wait for the
Transaction Response to be returned

Page 23 of 65

Web Services Integration Guide V5.13 – March 2009

xiii.

When the response is received, check the AuthResult to see if there was an error. If not then it is
possible to complete the transaction with a Process Confirm; again populating the required
information.
The only scenario in which a transaction should not be processed after performing Enrollment and
Authentication checks would be when the following results are received:
Y
N
This represents the card being enrolled, but when the cardholder has attempted to authenticate using
their password, this has not been matched correctly.
In the situation where these checks are unsuccessful, i.e. a response of U or
U is returned; it is recommended that the check is
resent. Due to the fact that there has been a technical problem when checking Enrollment, charge back
liability has not been shifted away from the merchant at this stage, as potentially the failure could have
occurred before the information reached the Directory Server. However, the final decision on this is down
to the merchant. If there is relatively low risk involved, due to a low transaction amount for example, the
transaction could be continued and processed regardless.
When the card is not enrolled for Payer Authentication; the following responses will be amongst those
produced:
N
N
It is important to remember that this does not mean it is not safe to proceed with the transaction; just that
the cardholder has not been enrolled in the service. Due to an enrollment check being performed by the
merchant, the liability is shifted to the issuer.
6.1.1 PayerAuth Expiry
One possible area which could create confusion is how long the Payer Authentication check lasts for once
it has been approved, and if it can be reused.
Once the Payer Authentication check has been performed it is valid for 90days with VISA, and with
MasterCard it does not expire.
One example would be that this allows use of the ID for an authorisation only transaction. If the
authorisation code provided for the authorisation expires before charging the card; a full authorisation
and charge transaction can be performed, using the PayerAuthRequestID that was provided initially.
6.1.2 Canadian Corporate Purchase Cards
Some Canadian Corporate Purchase Cards have been excluded from the Enrollment Check, and can
result in a response of ‘U’ for the field.
Unfortunately we are unable to confirm which bin ranges have been excluded and cannot therefore
provide a specific response in this scenario.
6.1.3 Process Transaction
Once the enrollment and authentication checks have been performed, the transaction can be process by
including a PayerAuth Auxiliary data record along with a Transaction Request record. Please see sections
5.2.1 and 5.2.3 for more information.
6.1.4 Payer Authentication with Token
When performing Payer Authentication in conjunction with an integration which utilises the Token
Gateway, the process is to supply the TokenID with all the Payer Authentication checking records instead
of supplying full card details.

Page 24 of 65

Web Services Integration Guide V5.13 – March 2009

Please note that each time stored card details are used to process a transaction, the Payer Authentication
process must be completed.
6.1.5 Chargeback Information
Should chargeback information be required then this can be obtained from the Merchant Helpdesk.

6.2 Cardholder Authentication Implementation Guidelines
In order to provide some guidelines for how to go about implementing the cardholder authentication
process, the following information has been collated from MasterCard and Visa.
1.

Consumer Message on Payment Page
In order to make the consumer aware of the merchant’s participation with MasterCard
SecureCode and Verified by Visa, it is recommended that a message is displayed on the
payment page, similar to: “Your card may be eligible for or enrolled in MasterCard SecureCode
or Verified by Visa. When you click ‘Pay’ below you may be prompted for further information
before your order can be completed.”

Creation of Cardholder Authentication Window
The process with this window is that it is initially created by the merchant; however, that the
actual content of the window is controlled by the cardholder’s issuing financial institution. Initially
it was possible to implement this using either a pop-up window or an inline window, but only the
inline window implementation is now supported.
Merchants utilising the pop-up window approach are expected to convert to an inline window
implementation and inline window implementations are required for all new merchant
implementations. By presenting a full-page view, it makes the SecureCode authentication
process appear to be a seamless part of the merchant checkout process. Many merchants use
frames to customise their deployments.
In a frame implementation, only part of the full window is redirected to the issuer’s access
control server. This allows the merchant to display a branded header, as well as explanation text
that can assist cardholders who are new to the cardholder authentication experience. Here are
some key points for merchants implementing this approach:
•
•
•
•

•

The use of active HTML links in the branded header frame is not allowed. Below the
header frame, however, it is recommended to include a link that directs the cardholder
back to the checkout page in case of technical difficulties.
The explanation text should be clear and concise. The text should not assume that the
cardholder is already enrolled and should not provide instructions that might conflict
with the cardholder’s issuer instructions.
The use of newer frame technologies such as iFrames and floating .Net frames is not
recommended as some cardholders set their browsers to block such elements.
The merchant should make sure that the authentication window frame is fully visible
and is not located too low in the page due to long text or large upper frame. A
minimum space of 400x400 pixels is required for the Access Control Server (ACS)
frame. It must not be necessary to scroll to see the authentication page.
Merchants must ensure that the ‘back’ button functionality works and cardholders who
click on it are routed back to the checkout page.

Inline authentication windows can also be used without frames. This will show the cardholder
that they are no longer at the merchant and are now communicating with their issuing bank
whilst also allowing them to check the SSL lock to ensure connection with the Issuer ACS. As a
result, the ‘Without frames’ approach may be preferred by some cardholders.
3.

TERMURL Field
This field is provided by the merchant to the issuer during the payer authentication request
process. It provides the issuer with the merchant URL where the payer authentication response
message is to be sent. The use of mixed HTTP and HTTPS frames typically results in a security
box being presented to the cardholder. Depending upon how the cardholder responds to this
dialog, the current and all future attempts to transmit the PAReq message may fail. As a result,

Page 25 of 65

Web Services Integration Guide V5.13 – March 2009

merchants using inline authentication windows with frames must populate the TERMURL field
with a HTTPS address.
6.3 PayerAuth Message Types
6.3.1 PayerAuth EnrollmentCheck Request
The EnrollmentCheck request is raised to check if the card is enrolled with MasterCard SecureCode or
Verified By Visa.
The Message Type for the payer authentication enrollment check is PAI and the namespace is
PAYERAUTH.

Section/Fields

Type/Format

Mandatory/
Optional/Conditional

Description

merchantreference

String

mkaccountid

Decimal

mkacquirerid

Decimal

Merchant can add a
reference to cross
reference responses
relating to the same
transaction
Account reference
number, supplied by
Commidea
Acquirer reference
number

merchantname

String
Varchar(50)

merchantcountrycode

String
Varchar(50)

1 – Barclaycard Business
(BMS) [Sterling only]
2 – NatWest Streamline
3 – HMS (HSBC)
4 – Lloyds TSB Cardnet
5 – Elavon (GiroBank)
6 – Bank Of Scotland
7 – American Express
8 – Clydesdale Bank
9 – Barclaycard Business
(BMS) MultiCurrency
10 – Bank of Ireland
11 – Northern Bank
12 – Yorkshire Bank
13 – GE Capital
14 – Ulster Bank
15 – Int'l Barclaycard
Business (BMS) [Sterling]
16 – Int'l Lloyds TSB
Cardnet
17 – Int'l HMS (HSBC)
18 – Int'l NatWest
19 – Int'l Barclaycard
Business (BMS) Multi
20 – Diners
21 – Creation
23 – JCB
24 – AIB
The MerchantName must
match the name shown
online to the cardholder
at the merchant’s site and
the name submitted by
the merchant’s acquirer in
the settlement transaction
This field contains a three
digit number assigned by

Page 26 of 65

Web Services Integration Guide V5.13 – March 2009

merchanturl

String
Varchar(255)

visamerchantbankid

String
Varchar(50)

C
(Only for Visa checks)

visamerchantnumber

String
Varchar(50)

C
(Only for Visa checks)

visamerchantpassword

String
Varchar(50)

C
(Only for Visa checks)

mcmmerchantbankid

String
Varchar(50)

C
(Only for MasterCard
/Maestro checks)

mcmmerchantnumber

String
Varchar(50)

C
(Only for MasterCard
/Maestro checks)

mcmmerchantpassword

String
Varchar(50)

tokenid

Decimal

C
(Only for MasterCard
/Maestro checks)
C

cardnumber

String
Varchar(50)

cardexpyear

String
Char(4)

the signing member or
processor to identify the
merchant’s location
country. Based on ISO
Country Codes – 3166.
(See Appendix C)
This field contains the fully
qualified URL of the
merchant site
This field contains a six
digit assigned Bank
Identification Number
issued by the merchant’s
member bank or
processor. The acquirer
Bank Identification
Number (BIN) identifies
the member bank that
signed the merchant
using the Point of Sale
application
This field contains a
unique ID number which
is assigned by the signing
merchant’s acquirer, bank
or processor. This field is
used to identify the
merchant within the
VisaNet system
The alphanumeric
merchant password is
provided by the acquirer
This field contains a six
digit assigned Bank
Identification Number
issued by the merchant’s
member bank or
processor. The acquirer
Bank Identification
Number (BIN) identifies
the member bank that
signed the merchant
using the Point of Sale
application
This field contains a
unique ID number which
is assigned by the signing
merchant’s acquirer, bank
or processor. This field is
used to identify the
merchant within the
SecureCode system
The alphanumeric
merchant password is
provided by the acquirer
Token identifier for token
transaction. If none to be
passed, ‘0’ to be used.
Card PAN
Card expiry date year YY
e.g. 08
(not passed if token id
supplied)

Page 27 of 65

Web Services Integration Guide V5.13 – March 2009
cardexpmonth

String
Char(2)

currencycode

String
Char(3)

currencyexponent

String
Char(1

browseracceptheader

String
Varchar(255)

browseruseragentheader

String
Varchar(255)

transactionamount

String
Varchar(50)

transactiondisplayamount

String
Varchar(50)

transactiondescription

String
Varchar(50)

Card expiry date month
MM
(not passed if token id
supplied)
This field contains a three
digit number assigned by
the signing member or
processor to identify the
merchant's authorization
currency. Based on ISO
Country Code – 3166
(See Appendix C)
No of decimal places in
currency field ie. GBP will
be 2
This field contains the
exact content of the HTTP
accept header as sent to
the merchant from the
cardholder's user agent.
This field is required only
if the cardholder's user
agent supplied a value.
This field contains the
exact content of the HTTP
user-agent header as sent
to the merchant from the
cardholder's user agent.
This field is only required
if the cardholder's user
agent supplied a value.
Amount to be authorised
with implied decimal
point ie. £10.00 is
represented as 1000 and
0.10 is represented as
10.
The transaction amount is
to be presented with all
currency-specific
punctuation, as this will
be the number displayed
to the customer. E.g.
10.00
This field contains a
description of the goods
or services being
purchased, determined by
the merchant.

Page 28 of 65

Web Services Integration Guide V5.13 – March 2009

6.3.2 PayerAuth EnrollmentCheck Response
The response from the check will be contained within the EnrollmentCheck response.
The Message Type for the payer authentication enrollment check response is PAER and the namespace is
PAYERAUTH.

Section/Fields

merchantreference

Type/Format

Description

String
Varchar(50)

Merchant can add a reference to cross
reference responses relating to the same
transaction
This indicates the database to use for
processing a particular request. If left
blank the default database will be used.
Unique Identifier
Indicates if card is enrolled in the 3D
secure program.
Fully qualified URL of an Access Control
Server.
This field will contain the entire XML
response packet from the Directory
Server.
Error code defining the error
Description of the error

processingdb

String

payerauthrequestid
enrolled

Decimal
String
Char(1)
String
Varchar(255)
String
Varchar(1000)

acsurl
pareq
errorcode
errordescription

Integer
String
Varchar(1000)

6.3.3 PayerAuth AuthenticationCheck Request
After the enrollment check has been performed, authentication can be sought using this message type.
The Message Type for the payer authentication check request is PAI and the namespace is PAYERAUTH.

Section/Fields

Type/Format

Mandatory/
Optional/
Conditional

Description

merchantreference

String

payerauthrequestid

Decimal

pares

String

enrolled

String

Merchant can add a reference
to cross reference responses
relating to the same transaction
Unique Identifier returned
during
EnrollmentCheckResponse.
Compressed and encoded
Payer Authentication Response
message, returned in response
from Visa / Mastercard
(Only included if received)
Indicates if the card was
enrolled – Y/N

Page 29 of 65

Web Services Integration Guide V5.13 – March 2009

6.3.4 PayerAuth AuthenticationCheck Response
The authentication check response will contain the result of the authentication check.
The Message Type for the payer authentication response is PAAR and the namespace is PAYERAUTH.

Section/Fields

Type/Format

Description

merchantreference

String

payerauthrequestid
authenticationstatus

Decimal
String

Merchant can add a reference to cross
reference responses relating to the same
transaction
PayerAuth transaction identifier
This property indicates whether the transaction
has been authenticated or not.
• Y – The customer was successfully
authenticated. All data needed for
clearing is included.
N – The customer failed
authentication, and the transaction is
denied.
• A – Attempted processing. The APACS
message will show verified enrolment
but cardholder is not participating at
this time.
• U – Authentication could not be
performed due to technical or other
problems.
The certificate that signed the Payer
Authentication Response (PARes) message.
This property contains a 28-byte Base-64
encoded Cardholder Authentication
Verification Value (CAVV).
Two digit Electronic Commerce Indicator (ECI)
value.
The date and time in which the Payer
Authentication Response (PARes) message was
signed by the Access Control Server (ACS).
The value is expressed in GMT and uses the
format "YYYYMMDD HH:MM:SS".
Additional transaction security data
Error code defining the error
Description of the error
This indicates the database used for
processing a particular request
•

authenticationcertificate

String

authenticationcavv

String

authenticationeci

String

authenticationtime

String

atsdata
errorcode
errordescription
processingdb

String
Integer
String
String

Page 30 of 65

Web Services Integration Guide V5.13 – March 2009

6.4 3D Secure Matrix
Below is a 3D Secure Matrix for both Visa VbV Transactions, and MasterCard SecureCode Transactions.
This matrix provides a description of the Authentication Results and Merchant to Acquirer values presented
during each scenario.
6.4.1 3D Secure Matrix – Visa VbV Transactions
Payer auth can be carried out on all Visa card ranges.
Authentication results
Scenario

VERes
(enrolmen
t status)

Confirmation
Participating Issuer,
participating cardholder.
Cardholder enrolment
verified, authentication
successful
Attempt
Participating Issuer,
participating cardholder.
Cardholder enrolment
verified. Visa have an
Attempts ACS to act on
behalf of nonparticipating Issuers / or
non-enrolled
cardholders.
Denial
Participating Issuer,
participating cardholder.
Cardholder enrolment
verified; Issuer declines
authentication
cardholder. I.e.
cardholder unable to
provide correct password.
Authentication could not
be performed
Participating Issuer,
participating cardholder.
Cardholder enrolment
verified. Authentication
could not be completed
due to technical or other
reasons.
Non-participation
• Non-participating Issuer
• Participating Issuer,
card range of
cardholder not
registered in directory
• Participating Issuer,
cardholder not enrolled
in ACS

Merchant to Acquirer

Liability Shift

PARes
(Txn
status)

PARes
ECI
value

PARes
CAVV
Present

ATSD

CAVV
Present

Yes

D0C100

Yes

D0C200

Yes

N/A - Visa state
that the
transaction must
not be sent for
authorisation.

None

No auth

None

D0C400

None

N/A

D0C200

Yes

Page 31 of 65

Web Services Integration Guide V5.13 – March 2009
Authentication results
Scenario

Merchant to Acquirer

Liability Shift

VERes
(enrolmen
t status)

PARes
(Txn
status)

PARes
ECI
value

PARes
CAVV
Present

ATSD

CAVV
Present

None

N/A

D0C400

Yes

N/A

808000

Unable to authenticate
(2)
• Participating Issuer,
ACS is not able to verify
enrolment status of
cardholder because
card type or channel is
not supported, or
technical difficulties.
• Non-participating
Issuer, ineligible
product
Non Supporting Card
Schemes

Page 32 of 65

Web Services Integration Guide V5.13 – March 2009

6.4.2 3D Secure Matrix – MasterCard SecureCode Transactions
Payer auth can be carried out on the following SecureCode schemes - MasterCard, Maestro
International, Maestro Domestic and Solo.
Authentication results
Scenario

VERes
(enrolment
status)

MasterCard do not
support attempts and the
AAV must not be sent in
the Auth.
3.

Denial
Participating Issuer,
participating cardholder.
Cardholder enrolment
verified; Issuer declines
authentication cardholder.
I.e. cardholder unable to
provide correct password.
Authentication could not
be performed
Participating Issuer,
participating cardholder.
Cardholder enrolment
verified. Authentication
could not be completed
due to technical or other
reasons.
Non-participation
• Non-participating Issuer
• Participating Issuer, card
range of cardholder not
registered in directory
• Participating Issuer,
cardholder not enrolled
in ACS.
Unable to authenticate (2)
• Participating Issuer, ACS
is not able to verify
enrolment status of
cardholder because
card type or channel is
not supported, or
technical difficulties.
• Non-participating Issuer,
ineligible product

Merchant to Acquirer
Chargeback
right

PARes
(Transaction
status)

PARes
ECI
value

PARes
CAVV/
AAV
Present

ATSD

CAVV/AAV
Present

Yes

D09100

Yes

D09200

Yes

Y
Acquirer
advises that
the
transaction is
not sent for
authorisation.

None

No auth

None

D09400

Yes

None

N/A

D09200

Yes

None

N/A

D09400

Yes

Page 33 of 65

Web Services Integration Guide V5.13 – March 2009
VbV
EMV Terminal Type

30 (Visa ECI 5) =
31 (Visa ECI 6) =
32 (Visa ECI 7) =

Merchant & Cardholder are registered
Merchant is registered, but Cardholder isn't.
Standard E-Commerce message

APACS 70-2
Section B.4.2 (page 85)

Electronic Commerce Data Record Sub-type 01

APACS 70-3
Section A.4 (page 93)
Customer Instruction

G = Merchant & Cardholder registered
H = Merchant is registered, but Cardholder isn't.
J = Standard E-Commerce message

Tests 5a & 5b
Tests 6a & 6b

Please put a line through the scenario not being used
Please put a line through the scenario not being used

EMV Terminal Type

30 (M'Card PDS 2) =
31 (M'Card PDS 1) =
32 (M'Card PDS 0) =

Secure
Code
Merchant & Cardholder are registered
Merchant is registered, but Cardholder isn't.
Standard E-Commerce message

APACS 70-2
Section B.4.2 (page 85)

Electronic Commerce Data Record Sub-type 01

APACS 70-3
Section A.4 (page 93)
Customer Instruction

G = Merchant & Cardholder registered
H = Merchant is registered, but Cardholder isn't.
J = Standard E-Commerce message

Tests 12a & 12b
Tests 13a & 13b

Please put a line through the scenario not being used
Please put a line through the scenario not being used

6.4.3 Non Supporting Card Schemes
Payer Auth is not performed on non supporting schemes i.e.- Creation, AMEX, JCB, Diners. However,
Additional Transaction Security Data is required to show that SSL encryption was used for the transaction.
SCHEME
Non supporting schemes i.e.- Creation, AMEX, JCB, Diners

VERES
N/A

PARES
N/A

ATSD
D08000

ECI
07

Page 34 of 65

Web Services Integration Guide V5.13 – March 2009

7. Token Gateway
7.1 Token Registration Process
To register a token a request should be created containing all the information required, which will include
the card number, expiry date as well as boolean values to control the transaction types allowed for the
token. A response will then be returned containing a TokenID. This should be stored, and can be
provided in a transaction request (see section 5.2.1) to request for the stored details to be sourced and
utilized to provide payment details for the transaction.
Merchant System

Commidea Server

Order and cardholder
data captured
Token Registration request sent
to Commidea, including token
expiration date
Commidea securely stores
sensitive data and assigns a token
on behalf of merchant
Token Registration response
returned to merchant, including
token ID

Merchant stores token ID

7.2 Token Message Types
7.2.1 Registration Request
The Token Registration Request type contains all the information required to register a token.
The Message Type is TKI and the namespace is TOKEN.

Section/Fields

Type/Format

Mandatory/
Optional/
Conditional

Description

merchantreference

String

pan
expirydate

String
String

M
M

startdate

String

Merchant can add a
reference to cross
reference responses
relating to the same
transaction
Card number
Card expiry month and
year (YYMM)
(Only required when card
is keyed, can be
calculated from Track2)
Card start date month
and year (MMYY)
Only required for
American Express, Diners
Club International, some
Maestro, some Solo and

Page 35 of 65

Web Services Integration Guide V5.13 – March 2009

some Laser cards. Not
required if Track2 data
supplied
Please note the format difference between the expiry and start dates are intentional

issuenumber

String

purchase
refund
cashback
tokenexpirationdate

Boolean
Boolean
Boolean
String

M
M
M
M

1 or 2 digit card issue
number as shown on the
front of the card.
Only required by some
Switch, Solo and Laser
cards. Required only
when card is keyed
Allow purchase txn type
Allow refund txn type
Allow cashback txn type
Last date on which the
token can be utilized.
Format of date to be:
DDMMCCYY

7.2.2 Token Registration Response
The Token Registration Response type contains all the result information from a token registration request.

Section/Fields

Type/Format

Description

merchantreference

String

tokenid
errorcode

Decimal
Integer

errormsg

String

Merchant can add a reference to
cross reference responses relating to
the same transaction
Unique identifier for registered PAN
This is an error code indicating what
type of error occurred, if any, while
processing the transaction. See
Appendix E for error codes
This is a text field used to give as
short text description of the error
code

Page 36 of 65

Web Services Integration Guide V5.13 – March 2009

8. Ukash Message Types
The Message Type for Ukash requests is UKASH and the namespace is UKASH.
8.1 Ukash GetSettleAmount Request

Section/Fields

merchantreference
requesttype
ukashlogin

Type/Format

Description

String
Varchar(50)

Merchant can add a reference to cross
reference responses relating to the same
transaction
The request type;
ukashgetsettleamount
This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
This is the password for the Ukash login
name, which will be supplied to the merchant
by Ukash
This is a unique reference to the transaction,
which must be supplied by the merchant. It
must be unique across the merchant’s
ukashLogin. E.g. for gaming clients, the
format of the transactionId must be
casinoId_TransNo
Ukash will supply a brand id to the merchant
for each of the brands he wishes to
differentiate between. The appropriate brand
id must then be sent through on each
transaction request
This is the number printed on the voucher or
card, the number will be 19 digits for
vouchers and 16 digits for cards.
This is the value of the voucher presented in 2
decimal points
This is the currency in which the
product/service is being sold. It is the
merchant base currency for the transaction. It
must be given in the character ISO standard.
Refer to Appendix B to verify
7-9 digits of voucher number

String
Varchar(50)
String
Char(20)

ukashpassword

String
Char(20)

transactionid

String
Char(20)

brandid

String
Char(20)

vouchernumber

String
Char(19)/ Char(16)

vouchervalue

decimal

basecurr

String
Char(3)

vouchercurrproductcode

String
Char(3)

Page 37 of 65

Web Services Integration Guide V5.13 – March 2009

8.2 Ukash PartSpendVoucher Request

Section/Fields

merchantreference
requesttype
ukashlogin

Type/Format

Description

String
Varchar(50)

Merchant can add a reference to cross
reference responses relating to the same
transaction
The request type;
ukashpartspendvoucher
This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
This is the password for the Ukash login
name, which will be supplied to the merchant
by Ukash
This is a unique reference to the transaction,
which must be supplied by the merchant. It
must be unique across the merchant’s
ukashLogin. E.g. for gaming clients, the
format of the transactionId must be
casinoId_TransNo
Ukash will supply a brand id to the merchant
for each of the brands he wishes to
differentiate between. The appropriate brand
id must then be sent through on each
transaction request
This is the number printed on the voucher or
card, the number will be 19 digits for
vouchers and 16 digits for cards.
This is the value of the voucher presented in 2
decimal points
This is the value, which the merchant wishes
to charge from the voucher or account. It is
presented in 2 decimal points in the merchant
base currency.
This is the currency in which the
product/service is being sold. It is the
merchant base currency for the transaction. It
must be given in the character ISO standard.
Refer to Appendix B to verify
This is the Merchant’s time stamp of the
transaction. Format “yyyy-mm-dd hh:mm:ss”
This indicates what the transaction is being
used for. See Section 7.9 for redemption
Types. The numeric identifier must be
supplied
7-9 digits of voucher number

String
Varchar(50)
String
Char(20)

ukashpassword

String
Char(20)

transactionid

String
Char(20)

brandid

String
Char(20)

vouchernumber

String
Char(19)/ Char(16)

vouchervalue

decimal

ticketvalue

Decimal

basecurr

String
Char(3)

merchantdatetime

String Char(19)

redemptiontype

String Char(1)/Char(2)

vouchercurrproductcode

String
Char(3)

Page 38 of 65

Web Services Integration Guide V5.13 – March 2009

8.3 Ukash FullValueVoucher Request

Section/Fields

merchantreference
requesttype
ukashlogin

Type/Format

Description

String
Varchar(50)

Merchant can add a reference to cross
reference responses relating to the same
transaction
The request type;
ukashfullvaluevoucher
This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
This is the password for the Ukash login
name, which will be supplied to the merchant
by Ukash
This is a unique reference to the transaction,
which must be supplied by the merchant. It
must be unique across the merchant’s
ukashLogin. E.g. for gaming clients, the
format of the transactionId must be
casinoId_TransNo
Ukash will supply a brand id to the merchant
for each of the brands he wishes to
differentiate between. The appropriate brand
id must then be sent through on each
transaction request
This is the number printed on the voucher or
card, the number will be 19 digits for
vouchers and 16 digits for cards.
This is the value of the voucher presented in 2
decimal points
This is the currency in which the
product/service is being sold. It is the
merchant base currency for the transaction. It
must be given in the character ISO standard.
Refer to Appendix B to verify
This is the Merchant’s time stamp of the
transaction. Format “yyyy-mm-dd hh:mm:ss”
This indicates what the transaction is being
used for. See Section 7.9 for redemption
Types. The numeric identifier must be
supplied
7-9 digits of voucher number

String
Varchar(50)
String
Char(20)

ukashpassword

String
Char(20)

transactionid

String
Char(20)

brandid

String
Char(20)

vouchernumber

String
Char(19)/ Char(16)

vouchervalue

decimal

basecurr

String
Char(3)

merchantdatetime

String Char(19)

redemptiontype

vouchercurrproductcode

String
Char(3)

Page 39 of 65

Web Services Integration Guide V5.13 – March 2009

8.4 Ukash PartSpendAccount Request

Section/Fields

merchantreference
requesttype
ukashlogin

Type/Format

Description

String
Varchar(50)

Merchant can add a reference to cross
reference responses relating to the same
transaction
The request type;
ukashpartspendaccount
This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
This is the password for the Ukash login
name, which will be supplied to the merchant
by Ukash
This is a unique reference to the transaction,
which must be supplied by the merchant. It
must be unique across the merchant’s
ukashLogin. E.g. for gaming clients, the
format of the transactionId must be
casinoId_TransNo
Ukash will supply a brand id to the merchant
for each of the brands he wishes to
differentiate between. The appropriate brand
id must then be sent through on each
transaction request
This is the number printed on the voucher or
card, the number will be 19 digits for
vouchers and 16 digits for cards.
This is the Pin number printed on the Ukash
Card. 4 digit value, field is required for all
card based transactions
This is the value of the voucher presented in 2
decimal points
This is the value, which the merchant wishes
to charge from the voucher or account. It is
presented in 2 decimal points in the merchant
base currency.
This is the currency in which the
product/service is being sold. It is the
merchant base currency for the transaction. It
must be given in the character ISO standard.
Refer to Appendix B to verify
This is the Merchant’s time stamp of the
transaction. Format “yyyy-mm-dd hh:mm:ss”
This indicates what the transaction is being
used for. See Section 7.9 for redemption
Types. The numeric identifier must be
supplied
7-9 digits of voucher number

String
Varchar(50)
String
Char(20)

ukashpassword

String
Char(20)

transactionid

String
Char(20)

brandid

String
Char(20)

vouchernumber

String
Char(19)/ Char(16)

ukashpin

String
Char(4)

vouchervalue

decimal

ticketvalue

Decimal

basecurr

String
Char(3)

merchantdatetime

String Char(19)

redemptiontype

vouchercurrproductcode

String Char(3)

Page 40 of 65

Web Services Integration Guide V5.13 – March 2009

8.5 Ukash FullSpendAccount Request

Section/Fields

merchantreference
requesttype
ukashlogin

Type/Format

Description

String
Varchar(50)

Merchant can add a reference to cross
reference responses relating to the same
transaction
The request type;
ukashfullspendaccount
This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
This is the password for the Ukash login
name, which will be supplied to the merchant
by Ukash
This is a unique reference to the transaction,
which must be supplied by the merchant. It
must be unique across the merchant’s
ukashLogin. E.g. for gaming clients, the
format of the transactionId must be
casinoId_TransNo
Ukash will supply a brand id to the merchant
for each of the brands he wishes to
differentiate between. The appropriate brand
id must then be sent through on each
transaction request
This is the number printed on the voucher or
card, the number will be 19 digits for
vouchers and 16 digits for cards.
This is the Pin number printed on the Ukash
Card. 4 digit value, field is required for all
card based transactions
This is the value of the voucher presented in 2
decimal points
This is the currency in which the
product/service is being sold. It is the
merchant base currency for the transaction. It
must be given in the character ISO standard.
Refer to Appendix B to verify
This is the Merchant’s time stamp of the
transaction. Format “yyyy-mm-dd hh:mm:ss”
This indicates what the transaction is being
used for. See Section 7.9 for redemption
Types. The numeric identifier must be
supplied
7-9 digits of voucher number

String
Varchar(50)
String
Char(20)

ukashpassword

String
Char(20)

transactionid

String
Char(20)

brandid

String
Char(20)

vouchernumber

String
Char(19)/ Char(16)

ukashpin

String
Char(4)

vouchervalue

decimal

basecurr

String
Char(3)

merchantdatetime

String Char(19)

redemptiontype

vouchercurrproductcode

String Char(3)

Page 41 of 65

Web Services Integration Guide V5.13 – March 2009

8.6 TransactionEnquiry Request
Used to check if there is an issue with the Ukash server, and there is a requirement to check with Ukash if
the transaction was successful or not.

Section/Fields

merchantreference
requesttype
ukashlogin

Type/Format

Description

String
Varchar(50)

Merchant can add a reference to cross
reference responses relating to the same
transaction
The request type;
ukashtransactionenquiry
This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
This is the password for the Ukash login
name, which will be supplied to the merchant
by Ukash
This is a unique reference to the transaction,
which must be supplied by the merchant. It
must be unique across the merchant’s
ukashLogin. E.g. for gaming clients, the
format of the transactionId must be
casinoId_TransNo
Ukash will supply a brand id to the merchant
for each of the brands he wishes to
differentiate between. The appropriate brand
id must then be sent through on each
transaction request
This is the number printed on the voucher or
card, the number will be 19 digits for
vouchers and 16 digits for cards.
This is the Pin number printed on the Ukash
Card. 4 digit value, field is required for all
card based transactions
This is the value of the voucher presented in 2
decimal points
This is the currency in which the
product/service is being sold. It is the
merchant base currency for the transaction. It
must be given in the character ISO standard.
Refer to Appendix B to verify
This is the Merchant’s time stamp of the
transaction. Format “yyyy-mm-dd hh:mm:ss”
This indicates what the transaction is being
used for. See Section 7.9 for redemption
Types. The numeric identifier must be
supplied
7-9 digits of voucher number

String
Varchar(50)
String
Char(20)

ukashpassword

String
Char(20)

transactionid

String
Char(20)

brandid

String
Char(20)

vouchernumber

String
Char(19)/ Char(16)

ukashpin

String
Char(4)

vouchervalue

decimal

basecurr

String
Char(3)

merchantdatetime

String Char(19)

redemptiontype

vouchercurrproductcode

String Char(3)

Page 42 of 65

Web Services Integration Guide V5.13 – March 2009

8.7 Ukash Response
The Message Type for the Ukash response is UKASH and the namespace is TRM.

Section/Fields

requesttype
amountreference

Type/Format

Description

String
Varchar(50)
String
Char(255)

The request type

mktransactionID
txcode

Decimal
Integer

txdescription

String
Char(255)

transactionid
settleamount

String
Char(20)
Decimal

accountbalance

Decimal

accountcurrency

String
Char(3)
String
Char(19)

changeissuevouchernumber
changeissuevouchercurr

String
Char(3)

changeissueamount

Decimal

changeissueexpirydate

String
Char(10)
String
Char(19)

issuedvouchernumber
issuedvouchercurr

String
Char(3)

issuedamount

Decimal

issuedexpirydate

String
Char(10)

ukashtransactionid

String
Char(50)
Boolean

currencyconversion

Merchants using the GetSettleAmount
method need only fill in this tag. All other
merchants should send a blank string in this
tag.
Unique transaction ID
This is a transaction status/return code. It
determines whether the voucher was
successfully redeemed or not. A “0” means
that the voucher was successfully redeemed.
Any other code will reflect an unsuccessful
redemption due to an invalid voucher or an
error. See Section 7.8 for possible return
codes
This is a text field used to give a short text
description of the transaction status/return
code
The transactionId is returned as reference to
link the request and response XML
This is the value of the transaction in the
base currency
The account balance in the currency of the
account. Applicable to account based
transactions only.
This is the currency the card account. It will
be given in the character ISO standard.
For ticket price redemption, this is the
voucher number for the change. For full
value redemption, this will be blank
This is the currency of the change issue
voucher. It will be given in the character ISO
standard. Refer to Appendix B
This is the value of the change presented in 2
decimal places. For full value redemption,
this will be blank
This is the expiry date for the change issue
voucher in the format yyyy-mm-dd
For issued vouchers this is the new voucher
number. This tag will only be returned for
IssueVoucher transactions.
The currency of the issued voucher. It will be
given in the character ISO standard. Refer to
Appendix B. This tag will only be returned for
IssueVoucher transactions.
This is the value of the issued voucher
presented in 2 decimal places. This tag will
only be returned for IssueVoucher
transactions.
This is the expiry date for the issued voucher
in the format yyyy-mm-dd. This tag will only
be returned for IssueVoucher transactions.
This is a unique reference to the transaction
This flag indicates whether currency
conversion took place. For full value
redemption, currency conversion may occur
to determine the settleAmount in the base
currency. For ticket price redemption,

Page 43 of 65

Web Services Integration Guide V5.13 – March 2009

errcode

Integer

errdescription

String
Char(255)

currency conversion may occur to determine
the ticket price in the currency of the voucher
This is an error code indicating what type of
error occurred, if any, while processing the
transaction. See Section 7.10 for possible
error codes
This is a text field used to give a short text
description of the error code

8.8 Ukash Return Code List
Type of Message
Transaction Status

Message Code
0
1
99

Message Description
Accepted
Declined
Failed

Comments
Redemption successful
Redemption unsuccessful
An error occurred during the processing
of the transaction hence the system
could not successfully complete the
redemption of the voucher.

8.9 Ukash Transaction Type List
Code
1
2
3
4
8
20

Description
Cash Withdrawal
Account Deposit
Product/Service
Purchase
Issue Voucher
Void Transaction
Account Add

Account Subtract

Transaction Enquiry

Comments
Normal Redemption transactions. Voucher or account will be debited
with the currency and amount.

Issues Voucher based on the currency and value
Voids a Transaction made in the last 60 seconds.
Add amount to Ukash account. Used only for Top up and Top Down
Cards.
Subtracts amount from Ukash account. Used only for Top up and Top
Down Cards.
Returns the state of a transaction that was executed in the last 48 hours.

Page 44 of 65

Web Services Integration Guide V5.13 – March 2009

8.10 Ukash Error Code List
Type of Error
Incoming XML Error
Data Validation Error

Card Validation Error

Error Code
100
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216

300
301

Error Description
Invalid incoming XML
Non numeric Voucher Value
Base Currency not 3 characters in length
Non numeric Ticket Value
Invalid BrandId
Invalid MerchDateTime
Invalid transactionId: greater than 20 characters
Invalid Redemption Type
Negative Ticket Value not allowed
No decimal place given in Ticket Value
No decimal place given in Voucher Value
Negative Voucher Value not allowed
Invalid or unsupported voucher product code
AmountReference with TicketValue not allowed
No ukashNumber supplied
No transactionId supplied
No brandId supplied
Ticket Value cannot be greater than Voucher Value without
Currency Conversion
Base Currency and Voucher currency do not match.
Brand not configured to Issue Vouchers
Invalid Voucher Number
Multiple Transactions found
Unknown transaction status
No transaction found.
The transaction cannot proceed with a user supplied PIN, and
none was supplied,
The supplied PIN had the incorrect format, e.g. was not 4 numeric
characters
PIN supplied with a transaction is incorrect (I.e. does not match
the required pin recorded on file)
PIN supplied with a transaction is incorrect and has resulted in the
failure count reaching the maximum
The Account has been blocked as a result of a
validation/verification check failure
Invalid Login and/or Password
Invalid Login and/or BrandID

400

Required Currency Conversion not supported

500
501
800

Error In Currency Conversion
Converted Settle Amount greater than Voucher Value
Max duration between getSettleAmount and Redemption
exceeded.
Invalid amountReference Submitted
Technical Error. Please contact Ukash Merchant Support
Ukash Server Error. Please contact Commidea Merchant Helpdesk

217
218
219
221
222
223
250
251
252
253
254

Technical Error

801
900
999

Page 45 of 65

Web Services Integration Guide V5.13 – March 2009

8.11 Ukash Product Codes
General
Issues
(020-200)

Cash Back
Issues
(201-400)

Gambling
Restricted
(401-600)

Reserved
(601-800)

Reserved
(801-999)

Region
United
Kingdom

Country
United
Kingdom

State
United
Kingdom

Currency
GBP

001

201

401

601

801

Europe

EUR

011

211

411

611

811

Europe

Poland

PLN

151

351

551

751

951

Europe

Austria

EUR

021

221

421

621

821

Europe

Belgium

EUR

022

222

422

622

822

Europe

Finland

EUR

023

223

423

623

823

Europe

France

EUR

024

224

424

624

824

Europe

Germany

EUR

025

225

425

625

825

Europe

Greece

EUR

026

226

426

626

826

Europe

Ireland

EUR

027

227

427

627

827

Europe

Italy

EUR

028

228

428

628

828

Europe

Luxembourg

EUR

029

229

429

629

829

Europe

Netherlands

EUR

030

230

430

630

830

Europe

Portugal

EUR

031

231

431

631

831

Europe

Spain

EUR

011

211

411

611

811

Europe

Switzerland

CHF

033

233

433

633

833

Europe

Denmark

DKK

034

234

434

634

834

Europe

Sweden

SEK

035

235

435

635

835

Europe

Czech Republic

Sweden
Czech
Republic

CZK

036

236

436

636

836

Europe

Norway

NOK

037

237

437

637

837

Europe

Romania

RON

038

238

438

638

838

Europe

Hungary

HUF

039

239

439

639

839

Europe

Bulgaria

BGL

040

240

440

640

840

Europe
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America

Estonia

EEK

041

241

441

641

841

USA

USD

299

499

699

899

USA

Alabama

USD

100

300

500

700

900

USA

Alaska

USD

101

301

501

701

901

USA

Arizona

USD

102

302

502

702

902

USA

Arkansas

USD

103

303

503

703

903

USA

California

USD

104

304

504

704

904

USA

Colorado

USD

105

305

505

705

905

USA

Connecticut

USD

106

306

506

706

906

USA

Delaware

USD

107

307

507

707

907

USA

Florida

USD

108

308

508

708

908

USA

Georgia

USD

109

309

509

709

909

USA

Hawaii

USD

110

310

510

710

910

USA

Idaho

USD

111

311

511

711

911

USA

Illinois

USD

112

312

512

712

912

USA

Indiana

USD

113

313

513

713

913

USA

Iowa

USD

114

314

514

714

914

Page 46 of 65

Web Services Integration Guide V5.13 – March 2009
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
North
America
South
America

USA

Kansas

USD

115

315

515

715

915

USA

Kentucky

USD

116

316

516

716

916

USA

Louisiana

USD

117

317

517

717

917

USA

Maine

USD

118

318

518

718

918

USA

USD

119

319

519

719

919

USA

Maryland
Massachusett
s

USD

120

320

520

720

920

USA

Michigan

USD

121

321

521

721

921

USA

Minnesota

USD

122

322

522

722

922

USA

Mississippi

USD

123

323

523

723

923

USA

Missouri

USD

124

324

524

724

924

USA

Montana

USD

125

325

525

725

925

USA

Nebraska

USD

126

326

526

726

926

USA

USD

127

327

527

727

927

USA

Nevada
New
Hampshire

USD

128

328

528

728

928

USA

New Jersey

USD

129

329

529

729

929

USA

New Mexico

USD

130

330

530

730

930

USA

USD

131

331

531

731

931

USD

132

332

532

732

932

USA

New York
North
Carolina
North
Dakota

USD

133

333

533

733

933

USA

Ohio

USD

134

334

534

734

934

USA

Oklahoma

USD

135

335

535

735

935

USA

Oregon

USD

136

336

536

736

936

USA

Pennsylvania

USD

137

337

537

737

937

USA

USD

138

338

538

738

938

USD

139

339

539

739

939

USA

Rhode Island
South
Carolina
South
Dakota

USD

140

340

540

740

940

USA

Tennessee

USD

141

341

541

741

941

USA

Texas

USD

142

342

542

742

942

USA

Utah

USD

143

343

543

743

943

USA

Vermont

USD

144

344

544

744

944

USA

Virginia

USD

145

345

545

745

945

USA

Washington

USD

146

346

546

746

946

USA

West Virginia

USD

147

347

547

747

947

USA

Wisconsin

USD

148

348

548

748

948

USA

Wyoming

USD

149

349

549

749

949

Argentina

ARS

152

352

552

752

952

USA

Page 47 of 65

Web Services Integration Guide V5.13 – March 2009
North
America

Canada

CAD

153

353

553

753

953

Africa

South Africa

ZAR

150

350

550

750

950

Page 48 of 65

Web Services Integration Guide V5.13 – March 2009

9. Troubleshooting
This section has been included in the manual to provide integrators with information to help resolve any
issues.
9.1 Deserialization Errors
When the elements which make up the XML document are populated with the necessary data, if the
‘Type’ of each is not adhered to then deserialization errors can occur.
Essentially, the information provided does not meet the format requirements and, when the XML
document has been programmatically checked, it could not be parsed correctly.
An example of this would be:
If the ‘Track2’ element were to be populated with data that does not match the predefined type, (in this
case, the track2 data should consist of a numeric value), then a deserialization error will be produced.
The error will detail which element(s) contained the mismatch, which enables the problem to be resolved
by checking what information was passed and comparing this to the required type.
1) The XML document ‘TRecord’ contains PAN information that doesn’t satisfy the type requirements:
....
CardNumber
....
2) A deserialization error is returned within the ‘InternalError’ tag, detailing which field caused the issue
(in this case ‘PAN’):

[16277] TransactionProcessor.DeserializeXml: Bad Format in
TRecord_Pan

9.2 Contact Information
Should there be a need to contact Commidea for help, please use the below contact details:
In a Test Environment:
Implementations
implementations@commidea.com
08444 828 273
In a Live Environment:
Merchant Helpdesk
helpdesk@commidea.com
08444 828 222

Page 49 of 65

Web Services Integration Guide V5.13 – March 2009

APPENDIX A – Website Testing Script
To aid developers before Commidea integration testing is performed; please follow the table below to
ensure that all recommendations and requirements have been met:

Test/Scenario

Description/Reasoning

Test Result

Perform a normal transaction

Ensure solution processes transactions correctly

PASS / FAIL

Check the modifiers used to mark the transaction are
correct, e.g. ‘Purchase’ (1) and ‘Keyed Customer Not
Present E-Commerce’ (12). These may differ for different
scenarios. A transaction can be marked with more than
one modifier

PASS / FAIL

Ensure voice referral transactions are rejected with a
of 2 (rejected) for websites

PASS / FAIL

Check referral message does not say the transaction has
been “declined”. Use “unsuccessful, as the scenario is
different from that of declines

PASS / FAIL

Process a declined transaction
(value ends in 5p)

Ensure solution reacts correctly to declined transactions,
including supplying an appropriate a message

PASS / FAIL

Check for SSL certificate

Must be installed on the site to ensure credit card
information is handled securely

PASS / FAIL

Navigating between payment forms
disabled

Secure information from website pages should be
cleared once the page is left, or returning using the
‘Back’ button should be disabled

PASS / FAIL

Process a transactions with various
issue numbers

The issue number field should allowing processing of
cards with issue numbers ranging from 1-99, including
01. Ensure leading 0’s are not removed after submission

PASS / FAIL

Process a transaction using a card
number with 13 digits

This is the least amount of digits a card number can
consist of (13)

PASS / FAIL

Process a transaction with a
Maestro card

This is the greatest amount of digits a card number can
consist of (19)

PASS / FAIL

Process a transaction with 20 alpha
characters as a card number

The card number field should validate locally and reject
any attempts to enter more than 19 characters. Entry of
alpha characters in this field should be disabled

PASS / FAIL

Process a transaction using invalid
start date, expiry date and issue
number

All fields should be validated locally, ensure that invalid
start date, expiry date and issue number entry is disabled
(formatting the field accordingly)

PASS / FAIL

In the event of a transaction
confirmation response not being
received, resend the confirmation

Confirmation should be resent rather than creating a
new transaction if no confirmation response is received.
This avoids duplicating orders

PASS / FAIL

Process a transaction using a CV2
value of ‘000’ (if applicable)

This test will check leading 0’s are not being removed
from the record before it is sent to Commidea. On the
test system, ‘000’ is the only CV2 value accepted

PASS / FAIL

Process a transaction using an
AMEX card (if applicable)

This will ensure that the CV2 field allows entry of up to 4
digits, which is a requirement for processing AMEX
cards. Please note that AMEX cards do now support 3
digit CSC values

PASS / FAIL

Process a transaction using AVS
information (if applicable)

Test scenarios whereby different AVS data is used. Here
are three tests to perform with the relevant test data
listed:

Perform a voice referral transaction
(value ends in 2p)

Page 50 of 65

Web Services Integration Guide V5.13 – March 2009

‘Matched’ – 10;ME156LH

PASS / FAIL

ii)

‘Partial Match’ – 11;ME156LH

PASS / FAIL

iii)

‘Not Matched’ – 11;ME167LH (or any
other address)

PASS / FAIL

Page 51 of 65

Web Services Integration Guide V5.13 – March 2009

APPENDIX B – Currency Code ISO 4217
Alpha code
AED
AFA
ALL
ANG
AOK
ARS
ATS
AUD
BBD
BDT
BEF
BGL
BHD
BIF
BMD
BND
BOP
BRC
BSD
BUK
BWP
BZD
CAD
CHF
CLP
CNY
COP
CRC
CSK
CUP
CVE
CYP
DDM
DEM
DJF
DKK
DOP
DZD
ECS
EGP
ESP
ETB
EUR
FIM
FJD
FKP
FRF
GBP
GHC
GIP
GMD
GNS
GQE
GRD
GTQ
GWP
GYD
HKD
HNL
HTG
HUF
IDR
IEP
ILS
INR
IQD

Numeric code
784
4
8
532
24
32
40
36
52
50
56
100
48
108
60
96
68
76
44
104
72
84
124
756
152
156
170
188
200
192
132
196
278
280
262
208
214
12
218
818
724
230
978
246
242
238
250
826
288
292
270
324
226
300
320
624
328
344
340
332
348
360
372
376
356
368

Currency
UAE Dirham
Afghani
Lek
Antillian Guilder
Kwanza
Argentine Peso
Schilling
Australian Dollar
Barbados Dollar
Taka
Belgian Franc
Lev
Bahraini Dinar
Burundi Franc
Bermudan Dollar
Brunei Dollar
Bolivian Peso
Cruzeiro
Bahamian Dollar
Kyat
Pula
Belize Dollar
Canadian Dollar
Swiss Franc
Chilean Peso
Yuan Renminbi
Colombian Peso
Costa Rican Colon
Koruna
Cuban Peso
Cape Verde Escudo
Cyprus Pound
Mark der DDR
Deutsche Mark
Djibouti Franc
Danish Krone
Dominican Peso
Algerian Dinar
Sucre
Egyptian Pound
Spanish Peseta
Ethiopian Birr
Euro
Markka
Fiji Dollar
Falkland Islands Pound
French Franc
Pound Sterling
Cedi
Gibraltar Pound
Dalasi
Syli
Ekwele
Drachma
Quetzal
Guinea-Bissau Peso
Guyana Dollar
Hong Kong Dollar
Lempira
Gourde
Forint
Rupiah
Irish Pound
Shekel
Indian Rupee
Iraqi Dinar

Entity
United Arab Emirates
Afghanistan
Albania
Netherlands Antilles
Angola
Argentina
Austria
Australia
Barbados
Bangladesh
Belgium
Bulgaria
Bahrain
Burundi
Bermuda
Brunei
Bolivia
Brazil
Bahamas
Burma
Botswana
Belize
Canada
Switzerland
Chile
China
Colombia
Costa Rica
Czechoslovakia
Cuba
Cape Verde
Cyprus
German Democratic Republic
Germany, Federal Republic of
Djibouti
Denmark
Dominican Republic
Algeria
Ecuador
Egypt
Spain
Ethiopia
European Union
Finland
Fiji
Falkland Islands (Malvinas)
France
United Kingdom
Ghana
Gibraltar
Gambia
Guinea
Equatorial Guinea
Greece
Guatemala
Guinea-Bissau
Guyana
Hong Kong
Honduras
Haiti
Hungary
Indonesia
Ireland
Israel
India
Iraq

Page 52 of 65

Web Services Integration Guide V5.13 – March 2009
IRR
ISK
ITL
JMD
JOD
JPY
KES
KHR
KMF
KPW
KRW
KWD
KYD
LAK
LBP
LKR
LRD
LSM
LUF
LYD
MAD
MGF
MLF
MNT
MOP
MRO
MTP
MUR
MVR
MWK
MXP
MYR
MZM
NGN
NIC
NLG
NOK
NPR
NZD
OMR
PAB
PES
PGK
PHP
PKR
PLZ
PTE
PYG
QAR
ROL
RWF
SAR
SBD
SCR
SDP
SEK
SGD
SHP
SLL
SOS
SRG
STD
SUR
SVC
SYP
SZL
THB
TND
TOP

364
352
380
388
400
392
404
116
174
408
410
414
136
418
422
144
430
426
442
434
504
450
466
496
446
478
470
480
462
454
484
458
508
566
558
528
578
524
554
512
590
604
598
608
586
616
620
600
634
642
646
682
90
690
736
752
702
654
694
706
740
678
810
222
760
748
764
788
776

Iranian Rial
Iceland Krona
Lira
Jamaican Dollar
Jordanian dinar
Yen
Kenyan Shilling
Riel
Comoros Franc
North Korean Won
Won
Kuwaiti Dinar
Cayman Islands Dollar
Kip
Lebanese Pound
Sri Lanka Rupee
Liberian Dollar
Maloti
Luxembourg Franc
Libyan Dinar
Moroccan Dirham
Malagasy Franc
Mali Franc
Tugrik
Pataca
Ouguiya
Maltese Pound
Mauritius Rupee
Maldive Rupee
Kwacha
Mexican Peso
Malaysian Ringgit
Metical
Naira
Cordoba
Netherlands Guilder
Norwegian Krone
Nepalese Rupee
New Zealand Dollar
Rial Omani
Balboa
Sol
Kina
Philippine Peso
Pakistan Rupee
Zloty
Portugese Escudo
Guarani
Qatari Rial
Leu
Rwanda Franc
Saudi Riyal
Solomon Islands Dollar
Seychelles Rupee
Sudanese Pound
Swedish Krona
Singapore Dollar
St. Helena Pound
Leone
Somali Shilling
Suriname Guilder
Dobra
Rouble
El Salvador Colon
Syrian Pound
Lilangeni
Baht
Tunisian Dinar
Pa’anga

Iran
Iceland
Italy
Jamaica
Jordan
Japan
Kenya
Kampuchea, Democratic
Comoros
Korea, Democratic People’s of
Korea, Republic of
Kuwait
Cayman Islands
Lao People’s Democratic Republic
Lebanon
Sri Lanka
Liberia
Lesotho
Luxembourg
Libyan Arab Jamahiriya
Morocco
Madagascar
Mali
Mongolia
Macau
Mauritania
Malta
Mauritius
Maldives
Malawi
Mexico
Malaysia
Mozambique
Nigeria
Nicaragua
Netherlands
Norway
Nepal
New Zealand
Oman
Panama
Peru
Papau New Guinea
Philippines
Pakistan
Poland
Portugal
Paraguay
Qatar
Romania
Rwanda
Saudi Arabia
Solomon Islands
Seychelles
Sudan
Sweden
Singapore
St. Helena
Sierra Leone
Somalia
Suriname
Sao Tome and Principe
Union of Soviet Socialist Republics
El Salvador
Syrian Arab Republic
Swaziland
Thailand
Tunisia
Tonga

Page 53 of 65

Web Services Integration Guide V5.13 – March 2009
TPE
TRL
TTD
TWD
TZS
UGS
USD
USN
USS
UYP
VND
VEB
VUV
WST
XAF
XCD
XDR
XEU
XOF
XPF
YDD
YER
YUD
ZAR
ZMK
ZRZ
ZWD

626
792
780
901
834
800
840
997
998
858
704
862
548
882
950
951
960
954
952
953
720
886
890
710
894
180
716

Timor Escudo
Turkish Lira
Trinidad&Tobago Dollar
New Taiwan Dollar
Tanzanian Shilling
Uganda Shilling
US Dollar
US Dollar (Next day)
US Dollar (same day)
Uruguayan Peso
Dong
Bolivar
Vatu
Tala
CFA Franc BEAC
East Caribbean Dollar
Special Drawing Rights
European Currency Unit
CFA Franc BCEAO
CFP Franc
Yemeni Dinar
Yemeni Rial
New Yugoslavian Dinar
Rand
Kwacha
Zaire
Zimbabwe Dollar

East Timor
Turkey
Trinidad and Tobago
Taiwan, Province of China
Tanzania, United Republic of
Uganda
United States
United States
United States
Uruguay
Viet Nam
Venezuela
Vanuatu
Samoa
Cameroon, Central African Republic, Chad, Congo ,Gabon
Antiqua
International Monetary Fund
Euro. Monetary Cooperation Fund (EMCF)
Benin, Ivory coast, Niger, Senegal, Togo, Upper Volta
French polynesia
Yemen, Democratic
Yemen
Yugoslavia
South Africa
Zambia
Zaire
Zimbabwe

Page 54 of 65

Web Services Integration Guide V5.13 – March 2009

APPENDIX C – Country Codes ISO 3166
Country Name

Country Code

Country Number

AFGHANISTAN
ALBANIA
ALGERIA
AMERICAN SAMOA
ANDORRA
ANGOLA
ANGUILLA
ANTARCTICA
ANTIGUA AND BARBUDA
ARGENTINA
ARMENIA
ARUBA
AUSTRALIA
AUSTRIA
AZERBAIJAN
BAHAMAS
BAHRAIN
BANGLADESH
BARBADOS
BELARUS
BELGIUM
BELIZE
BENIN
BERMUDA
BHUTAN
BOLIVIA
BOSNIA AND HERZEGOWINA
BOTSWANA
BOUVET ISLAND
BRAZIL
BRITISH INDIAN OCEAN TERRITORY
BRUNEI DARUSSALAM
BULGARIA
BURKINA FASO
BURUNDI
CAMBODIA
CAMEROON
CANADA
CAPE VERDE
CAYMAN ISLANDS
CENTRAL AFRICAN REPUBLIC
CHAD
CHILE
CHINA
CHRISTMAS ISLAND
COCOS (KEELING) ISLANDS
COLOMBIA
COMOROS
CONGO
CONGO, THE DEMOCRATIC REPUBLIC OF THE
COOK ISLANDS
COSTA RICA
COTE D'IVOIRE

AF
AL
DZ
AS
AD
AO
AI
AQ
AG
AR
AM
AW
AU
AT
AZ
BS
BH
BD
BB
BY
BE
BZ
BJ
BM
BT
BO
BA
BW
BV
BR
IO
BN
BG
BF
BI
KH
CM
CA
CV
KY
CF
TD
CL
CN
CX
CC
CO
KM
CG
CD
CK
CR
CI

4
8
12
16
20
24
660
10
28
32
51
533
36
40
31
44
48
50
52
112
56
84
204
60
64
68
70
72
74
76
86
96
100
854
108
116
120
124
132
136
140
148
152
156
162
166
170
174
178
180
184
188
384

Page 55 of 65

Web Services Integration Guide V5.13 – March 2009
CROATIA (local name: Hrvatska)
CUBA
CYPRUS
CZECH REPUBLIC
DENMARK
DJIBOUTI
DOMINICA
DOMINICAN REPUBLIC
EAST TIMOR
ECUADOR
EGYPT
EL SALVADOR
EQUATORIAL GUINEA
ERITREA
ESTONIA
ETHIOPIA
FALKLAND ISLANDS (MALVINAS)
FAROE ISLANDS
FIJI
FINLAND
FRANCE
FRANCE, METROPOLITAN
FRENCH GUIANA
FRENCH POLYNESIA
FRENCH SOUTHERN TERRITORIES
GABON
GAMBIA
GEORGIA
GERMANY
GHANA
GIBRALTAR
GREECE
GREENLAND
GRENADA
GUADELOUPE
GUAM
GUATEMALA
GUINEA
GUINEA-BISSAU
GUYANA
HAITI
HEARD AND MC DONALD ISLANDS
HOLY SEE (VATICAN CITY STATE)
HONDURAS
HONG KONG
HUNGARY
ICELAND
INDIA
INDONESIA
IRAN (ISLAMIC REPUBLIC OF)
IRAQ
IRELAND
ISRAEL
ITALY
JAMAICA
JAPAN

HR
CU
CY
CZ
DK
DJ
DM
DO
TP
EC
EG
SV
GQ
ER
EE
ET
FK
FO
FJ
FI
FR
FX
GF
PF
TF
GA
GM
GE
DE
GH
GI
GR
GL
GD
GP
GU
GT
GN
GW
GY
HT
HM
VA
HN
HK
HU
IS
IN
ID
IR
IQ
IE
IL
IT
JM
JP

191
192
196
203
208
262
212
214
626
218
818
222
226
232
233
231
238
234
242
246
250
249
254
258
260
266
270
268
276
288
292
300
304
308
312
316
320
324
624
328
332
334
336
340
344
348
352
356
360
364
368
372
376
380
388
392

Page 56 of 65

Web Services Integration Guide V5.13 – March 2009
JORDAN
KAZAKHSTAN
KENYA
KIRIBATI
KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF
KOREA, REPUBLIC OF
KUWAIT
KYRGYZSTAN
LAO PEOPLE'S DEMOCRATIC REPUBLIC
LATVIA
LEBANON
LESOTHO
LIBERIA
LIBYAN ARAB JAMAHIRIYA
LIECHTENSTEIN
LITHUANIA
LUXEMBOURG
MACAU
MACEDONIA, THE FORMER YUGOSLAV REPUBLIC
MADAGASCAR
MALAWI
MALAYSIA
MALDIVES
MALI
MALTA
MARSHALL ISLANDS
MARTINIQUE
MAURITANIA
MAURITIUS
MAYOTTE
MEXICO
MICRONESIA, FEDERATED STATES OF
MOLDOVA, REPUBLIC OF
MONACO
MONGOLIA
MONTSERRAT
MOROCCO
MOZAMBIQUE
MYANMAR
NAMIBIA
NAURU
NEPAL
NETHERLANDS
NETHERLANDS ANTILLES
NEW CALEDONIA
NEW ZEALAND
NICARAGUA
NIGER
NIGERIA
NIUE
NORFOLK ISLAND
NORTHERN MARIANA ISLANDS
NORWAY
OMAN
PAKISTAN
PALAU

JO
KZ
KE
KI
KP
KR
KW
KG
LA
LV
LB
LS
LR
LY
LI
LT
LU
MO
MK
MG
MW
MY
MV
ML
MT
MH
MQ
MR
MU
YT
MX
FM
MD
MC
MN
MS
MA
MZ
MM
NA
NR
NP
NL
AN
NC
NZ
NI
NE
NG
NU
NF
MP
NO
OM
PK
PW

400
398
404
296
408
410
414
417
418
428
422
426
430
434
438
440
442
446
807
450
454
458
462
466
470
584
474
478
480
175
484
583
498
492
496
500
504
508
104
516
520
524
528
530
540
554
558
562
566
570
574
580
578
512
586
585

Page 57 of 65

Web Services Integration Guide V5.13 – March 2009
PANAMA
PAPUA NEW GUINEA
PARAGUAY
PERU
PHILIPPINES
PITCAIRN
POLAND
PORTUGAL
PUERTO RICO
QATAR
REUNION
ROMANIA
RUSSIAN FEDERATION
RWANDA
SAINT KITTS AND NEVIS
SAINT LUCIA
SAINT VINCENT AND THE GRENADINES
SAMOA
SAN MARINO
SAO TOME AND PRINCIPE
SAUDI ARABIA
SENEGAL
SEYCHELLES
SIERRA LEONE
SINGAPORE
SLOVAKIA (Slovak Republic)
SLOVENIA
SOLOMON ISLANDS
SOMALIA
SOUTH AFRICA
SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS
SPAIN
SRI LANKA
ST. HELENA
ST. PIERRE AND MIQUELON
SUDAN
SURINAME
SVALBARD AND JAN MAYEN ISLANDS
SWAZILAND
SWEDEN
SWITZERLAND
SYRIAN ARAB REPUBLIC
TAIWAN, PROVINCE OF CHINA
TAJIKISTAN
TANZANIA, UNITED REPUBLIC OF
THAILAND
TOGO
TOKELAU
TONGA
TRINIDAD AND TOBAGO
TUNISIA
TURKEY
TURKMENISTAN
TURKS AND CAICOS ISLANDS
TUVALU
UGANDA

PA
PG
PY
PE
PH
PN
PL
PT
PR
QA
RE
RO
RU
RW
KN
LC
VC
WS
SM
ST
SA
SN
SC
SL
SG
SK
SI
SB
SO
ZA
GS
ES
LK
SH
PM
SD
SR
SJ
SZ
SE
CH
SY
TW
TJ
TZ
TH
TG
TK
TO
TT
TN
TR
TM
TC
TV
UG

591
598
600
604
608
612
616
620
630
634
638
642
643
646
659
662
670
882
674
678
682
686
690
694
702
703
705
90
706
710
239
724
144
654
666
736
740
744
748
752
756
760
158
762
834
764
768
772
776
780
788
792
795
796
798
800

Page 58 of 65

Web Services Integration Guide V5.13 – March 2009
UKRAINE
UNITED ARAB EMIRATES
UNITED KINGDOM
UNITED STATES
UNITED STATES MINOR OUTLYING ISLANDS
URUGUAY
UZBEKISTAN
VANUATU
VENEZUELA
VIET NAM
VIRGIN ISLANDS (BRITISH)
VIRGIN ISLANDS (U.S.)
WALLIS AND FUTUNA ISLANDS
WESTERN SAHARA
YEMEN
YUGOSLAVIA
ZAMBIA
ZIMBABWE

UA
AE
GB
US
UM
UY
UZ
VU
VE
VN
VG
VI
WF
EH
YE
YU
ZM
ZW

804
784
826
840
581
858
860
548
862
704
92
850
876
732
887
891
894
716

Page 59 of 65

Web Services Integration Guide V5.13 – March 2009

APPENDIX D – Performing a LUHN Check
The following steps are involved in this calculation:
Step 1

Double the value of alternate digits beginning with the first right hand digit (low order).

Step 2
Add the individual digit comprising the products obtained in Step 1 to each of the
unaffected digits in the original number.
Step 3
Subtract the total obtained in Step 2 from the next higher number ending in 0 (this is the
equivalent of calculating the “ten complement” of the low order digit (unit digit) of the total). If the total
obtained in Step 2 is a number ending in zero (30, 40, etc.), the check digit is 0.
Example:
Account Number without check digit 4929 123 123 12
Step 1

4
4

9
X2
18

2
2

9
X2
18

1
1

2
X2
4

3
3

1
X2
2

2
2

3
X2
6

1
1

2
X2
4

Step 2
4+1+8+2+1+8+1+4+3+2+2+6+1+4= 47
Step 3
50 – 47 = 3
Therefore check digit is 3 and complete card number is 4929 123 123 123

Page 60 of 65

Web Services Integration Guide V5.13 – March 2009

APPENDIX E – Commidea Error Codes
Error Code

General Description

0001
0002

Unspecified error
Invalid transaction type

0003

Invalid card / invalid Track2

0004

Card scheme not recognised

0005

Card scheme not accepted

0006

Invalid card number (lcd)

0007

Invalid card number length

0008

Invalid card number (pcd)

0009
0010
0011
0012
0013

Expired card
Card not yet valid
Invalid card service code
File or XML missing or wrong
format
File permanently locked

0014

Out of memory

0015

Account number does not exist

0016

Value exceeds ceiling limit

Purchase value exceeds card scheme
ceiling limit

0017

Cashback exceeds ceiling limit

0018

Transaction currency is invalid

0019

Lay aways are not allowed

0020

Lay away already stored

0021

EFT system not configured

0022
0023

Internal error, buffer too small
Unknown comms device type

0024

Configuration file is invalid

0025

No valid accounts

0026

Invalid channel

Cashback value exceeds card scheme
ceiling limit
The transaction currency code is
invalid or incorrect for the given site.
Attempt to lay away invalid / lay
aways are not allowed
Attempt to lay away a transaction
where there is already a transaction
laid away on that card
The EFT system has not been
configured
A buffer is too small
Invalid / unknown communications
device type
Configuration file is invalid / bad
format
There are no valid accounts specified
in the TillInfo.cfg
Invalid channel

0027

System error –module not
loaded
General transaction error
Transaction store unavailable

0028
0029

Additional Technical Description
(if required)
An example of this could be a Refund
being passed when the site are not
set up to do so. A trace of what was
passed will be in the system log.
General card error. Track2 must
either be ;PAN=YYMMsss……?x or
just the PAN.
The card Issuer Identification Number
(IIN) has not been located in the IIN
table. The IIN is typically the first 4 to
6 digits of the card number.
The card has been identified, but the
card scheme is not accepted at the
given site.
The LUHN check digit is incorrect (the
card has been mis-keyed or misswiped).
The length of the PAN is incorrect for
the given card scheme.
The pen-ultimate check digit is
invalid.

The Track2 service code is invalid.
A required file or XML is missing or
has wrong format.
A file required by the EFT library was
still locked after EFT FIO TRIES
attempts.
The library has failed to allocate
sufficient heap.
The requested account number does
not exist.

Recommended Action
Contact Commidea
Use alternative method for transaction
type.

Re-enter card number or re-swipe card

Prompt for alternate method of payment

Reject Transaction

Re-enter card number or re-swipe card

Re-enter card number or re-swipe card
Re-enter card number or re-swipe card
Prompt for alternate method of payment
Prompt for alternate method of payment
Prompt for alternate method of payment
Contact Commidea
Contact Commidea

Contact Commidea
Check the account number configuration
of the system, ensuring it matches that
configured within WinTI
Prompt for alternative method of
payment.
Arrange to increase ceiling limits
Revise transaction cash-back value

Prompt for alternate method of payment

Check communications configuration
Check system configuration
Check system configuration
Check>
· 2 transactions aren’t being passed
down the same channel.
· 2 tills aren’t using the same channel
number.
· WinTI EFTChans within the registry has
enough available channels set (Socket
mode only).

System error (Track2 check module
has not been loaded)
Transaction store unavailable

Re-enter transaction
Check Live Store.

Page 61 of 65

Web Services Integration Guide V5.13 – March 2009

0030
0031
0032
0033

0034

Unspecified error
Unspecified error:2
Library not open
Possible text for error:
()
should be X to Y characters in
length.
out of range,
should be X to Y.
out of tolerance,
is X, should be X +/- Z.
Line discount not available for
Cendant cards.
Line count (X) doesn’t match
header -> CPC lines (Y).
Separate post and packing only
on Amex cards.
Where = part
number, part description,
commodity code, unit of
measure, quantity, net value,
VAT amount, gross value, PAN,
PO number, customer number,
customer name, customer VAT
no, destination zip, destination
country code, order date,
original invoice number, cost
centre, invoice net amount,
invoice VAT amount, post and
packing VAT, invoice gross or
transaction total.
Invalid CPC data
Modifier field invalid/missing

0035
0036
0037

Invalid card / invalid Track 1
Invalid card / invalid Track 3
Invalid / missing expiry date

0038

Invalid / missing issue number

0039

Invalid / missing start date

0040
0041

Purchase/refund value bad or
missing
Cash-back value bad or missing

0042

Auth code value bad or missing

0043
0044

Cheque account number value
bad or missing
Invalid cheque sort code

0045
0046
0047

Invalid / missing cheque number
Invalid / missing cheque type
Invalid EFT serial number

0048

Unexpected CPC data

0049

Transaction already confirmed
or rejected

0050

Copy protection failure

0051

Post confirm reversal not
allowed for PWCB or Cash
Advance (reserved for future use)

Unspecified error
Transaction cancelled
EFT library is unavailable
The error message is made up of a
combination of text (1 to 6) with the
applicable field name inserted, as
applicable.
For example:
Net value out of tolerance, is 123.45,
should be 123.00 +/- 1

As the modifier is passed within the T
record the host software is likely to be
the cause of this
Track 1 is invalid
Track 3 is invalid
The expiry date is either invalid or
missing. If key entered, the format
should be MMYY
The issue number is either invalid
(value or length) or missing
The start date is either invalid or
missing. If key entered, the format
should be MMYY.
The transaction value is either invalid
or missing
The cash-back value is either invalid
or missing
The authorisation code is either
invalid or missing
The cheque account number is either
invalid or missing
The cheque sort code is either invalid
or missing

The EFT serial number is either invalid
or missing in the .Cnf file
Purchasing card invoice data has
been presented for a non-Purchasing
Card (where invoice data is not
valid/required)
Attempt to confirm or reject a
transaction, which has already been
confirmed or rejected
Could be a permission problem on
the PC
Attempt to perform a post confirm
reversal on a PWCB or Cash Advance
has been dis-allowed (as post confirm
reversals are not supported when

Check hard disk space.
Check system log for indication of error.
Channel available for next transaction

Re-swipe card
Re-swipe card
Re-enter expiry date or re-swipe card

Re-enter issue number or re-swipe card
Re-enter start date or re-swipe card

Re-enter transaction
Re-enter transaction

Re-enter cheque account number
Re-enter sort code
Re-enter cheque number
Re-enter cheque type
Re create *.cnf
Re-enter transaction without invoice data
or prompt for a valid Purchasing Card

Reverse transaction manually (as cash is
involved)

Page 62 of 65

Web Services Integration Guide V5.13 – March 2009
cash is involved)
The details supplied in the post
confirm reversal message is not
consistent with the data stored for the
transaction to be reversed
Attempt to perform a post transaction
reversal has failed because the
transaction has already been
voided/reversed
The card number is on the locally
stored host list (received from the
acquirer and/or entered by the
customer). The card must be rejected
The format of the confirmation
message is invalid (confirming a
declining transaction). The
confirmation message should contain
a command value of 2
(reverse/reject) and not a value of 1
(confirm).
CV2 is invalid
AVS is invalid
Mechant Details passed in XML
Gateway are Invalid.

0052

Transaction data supplied in
post conf rev not consistent with
store (reserved for future use)

0053

Transaction already void

0054

Card on hot list

0055

Attempt to confirm a declined
transaction

0056
0057
0058

EFT_ERR_BAD_CV2
EFT_ERR_BAD_AVS
Invalid Merchant Details

0059

Invalid Mobile Number Format

0060

0067

Invalid/missing bank account
number
Unexpected / Invalid
Authorisation Response
Report Not Supported

0068
0069
0070
0071

Report Failed
Gratuity value exceeded
Invalid Capture Not Supported
Cashback not allowed by card

0072
0073

Cash advance not allowed by
card
Max refund value exceeded

0074

Bill Already Complete

0075

No ETU accounts

0076

Card is online only

0077
0078
0079

Cancel Failed - In Payment on
xxx.xxx.xxx.xxx
Login failed
Confirmation Status Unknown

0080

Bill Reference Already Exists

0081

Print Report Failed

0082
0083
0084

Network Error
Invalid Record
PED User already logged in

0085

PED User not logged in

Refund transaction value is greater
than the maximum refund value set
on the account
The bill being cancelled is already
completed and therefore cannot be
cancelled.
Attempt to process ETU transaction
without ETU accounts being present
on terminal
Attempt to process an online only
card whilst offline
Attempt to cancel a lodged Bill failed,
usually locked on a specific terminal
User ID or PIN is incorrect
An invalid confirmation response has
been received or the confirmation
message to be sent was not saved
Attempt to lodge a Bill into I-Link that
already exists
The request report failed to generate
or print
Error in Network
Invalid Record
A Login command has been received,
but a user is already logged in
The terminal needs to be logged in

0086

Submission of offline
transactions failed

The submission of the offline stored
transactions have failed.

0064

The Mobile Number format passed is
incorrect
The bank account number within the
supplied T-Record is incorrect.
Unexpected / Invalid Authorisation
Response from M-Voucher Host
The Report ID supplied is either
invalid or does not correspond to a
report that is supported
Integrated report failed
Check Gratuity Value
Check Ocius settings
Card does not allow cashback
Card does not allow cash advance

Prompt for alternate method of payment

Check CV2 and re-enter
Check AVS and re-enter
Check both the GUID and Passcode
information that being passed to the XML
Gateway
Please check and re-enter the
mobilenumber supplied.
Check the bank number being passed
and re-enter as necessary.
Please contact Commidea Support
Check the Report ID that is being passed

Contact Commidea
Check Gratuity Value
Capture Method Not Set correctly
Use a different card or proceed without
cashback
Use a different card
Reduce transaction value

N\A

Contact Commidea

Check network or use another card
Leave for configured amount of time
before retrying cancel routine.
Check login details and try again

Clear the original Bill, or re-send this one
using an alternative reference.
Check printer settings, network
connection and try again.
Check network.
The record received is invalid.
Log the terminal off first, or simply pass a
transaction.
Send a login command to the terminal,
or manually login using the on-screen
prompts, then re-send the transaction.
The transactions will still be stored on the
terminal. Re-try, and if still having
problems contact The Merchant

Page 63 of 65

Web Services Integration Guide V5.13 – March 2009
Helpdesk.
0087

Problem in network

0088

Voice Referral Timeout

0089
0090

Invalid Account ID
Service Not Allowed

There has been a problem in the
network.
The voice referral transaction has
taken too long.
Invalid Account ID
Service code not supported

0091

Card Not Accepted

Card type not accepted

0092

Unknown Card

Unknown card type

0093

Not In IIN Range

Unknown card type

0094

Application Blocked

0095

Card Blocked

The terminal cannot accept this card
type
The card has been blocked.

0096
0097

Card Error
Authorisation Error

There is a problem with the Card
The authorisation process has been
interrupted or is not responding.

0098

Unknown Client
Unknown Transaction Source
Unknown Message

0099

Transaction/Bill Cancelled

0100
0101

Pin Bypass Failed
Invalid Terminal Country Code'

When using transaction processing, if
no POS Routing has been configured
for the IP Address or File Name where
the transaction originates from, ILink
does not know where to send the
transaction. It therefore rejects it with
this message.
When a transaction has been
cancelled by the user, the system or
an ICC card, this error message will
be sent.
ICC Card does not allow Pin Bypass.
The Terminal Country Code passed is
invalid

0102
0103

User has no permissions on
specified account
Invalid Currency Code'

Check account permissions in
WebCom.
The Currency Code passed is invalid.

0104

Invalid EMV Terminal Type'

0105

Unknown Message Type

0106

General Enqueue Error

0107

Transaction Confirmation Error

The EMV Terminal Type passed is
invalid
The message type received by server
side is not recognised
General Commidea Enqueueing
Error
The transaction confirmation has
errored.

0108

Payer Auth Error

0109

Ukash Auth Error

0110

Encryption Failure

0111
0112

Unable to build Auxillary Data
Record
Transaction rejection error

0120

Token Server Error

0121

0124

Purchase transaction type not
allowed on token
Refund transaction type not
allowed on token
Cashback transaction type not
allowed on token
Token expired

0125

Invalid TokenID

0122
0123

The Payer Auth has encountered an
error.
The Ukash transaction has
encountered an error.
An error has occurred in the data
encryption.
The auxillary data record failed to
build correctly
The attempt to reject the transaction
has errored
The Token Server has encountered an
error
The token provided does not allow
purchase transactions
The token provided does not allow
refund transactions
The token provided does not allow
cashback transactions
The token provided has passed its
expiry date
The token provided is invalid

Re-try or cancel.

Use another card, or cancel the
transaction
Use another card, or cancel the
transaction
Use another card, or cancel the
transaction
Use another card, or cancel the
transaction
Use another card, or cancel the
transaction
Use another card, or cancel the
transaction.
Re-try or use another card.
Check ILink & WinTI are running – or
when using ICP, contact Commidea
Merchant Helpdesk.
Configure POS routing for that Point Of
Sale.

Use another card.
Please check the ISO Country Codes
table and make sure the code being
passed is correct.
Please contact Commidea Support
Please check the ISO Currency Codes
table and make sure the code being
passed is correct.
Please check the EMV Terminal Type that
is being passed is valid.
Please contact Commidea Support
Please contact Commidea Support
Please retry the confirmation and if
continues to fail please contact
Commidea Support
Please check the error message response
and contact Commidea support.
Please check the error message response
and Contact Commidea Support.
Please contact Commidea Support
Please contact Commidea Support
Please retry the rejection and if continues
to fail please contact Commidea support
Please contact Commidea Support
Please supply another token that allows
purchase transactions
Please supply another token that allows
refund transactions
Please supply another token that allows
cashback transactions
Please register a new token
Please supply another token or contact

Page 64 of 65

Web Services Integration Guide V5.13 – March 2009

0126
0127

Token has no Txn Type
Permissions
Invalid Token expiration date

0189

Invalid refund password

The Token Registration has no
transaction permissions
The token expiration date provided is
invalid
An invalid refund password has been
supplied during the transaction, and
was rejected by the database

Commidea Support
Please resubmit the token request with
transaction permissions enabled
Please resubmit the token request with a
valid token expiration date
Please contact Commidea Support

Page 65 of 65

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
XMP Toolkit                     : Adobe XMP Core 4.0-c316 44.253921, Sun Oct 01 2006 17:14:39
Creator Tool                    : PScript5.dll Version 5.2.2
Modify Date                     : 2009:03:31 12:14:03+01:00
Create Date                     : 2009:03:31 12:14:03+01:00
Producer                        : Acrobat Distiller 8.1.0 (Windows)
Format                          : application/pdf
Creator                         : 
Title                           : 
Document ID                     : uuid:5a3625c9-9760-4e04-8a39-2a46da5a80a5
Instance ID                     : uuid:bd9ba9d0-4ed5-4854-8f4a-eca8778749f8
Page Count                      : 65
Author                          :

EXIF Metadata provided by EXIF.tools

Eft Pos Web Services Integration Guide 5.13 March 2009

Navigation menu

Versions of this User Manual:

Views

Navigation