Web Services Integration Guide V5.28 May 2011

Web%20Services%20Integration%20Guide%20V5.28%20-%20May%202011

User Manual:

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

Download
Open PDF In Browser	View PDF

Web Service Guide
Integration Guide
Author: ML
Circulation: Public
Date: 31/03/2011

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
2

Public

Version
5.28

Revision History
Ver.

Name

Date

V5.28

ML

May 2011

V5.27

ML

Feb 2011

V5.26

ML

Feb 2011

Comments
- Payer Authentication matrix updated
- ‘Resultdatetime’ string formatting corrected
- On-Hold/Release functionality documented
- Manual format updated
- Mandatory ‘accountpasscode’ field added
to transaction request message

Element Usage
Throughout the document, element usage is described using either ‘C’ (Conditional), ‘O’
(Optional) or ‘M’ (Mandatory). Where these are used, follow the below guidance:
Conditional – element required dependent upon another
Optional – element does not have to be present
Mandatory – element must be present and be populated with a value

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
3

Public

Version
5.28

Content
Revision History ............................................................................................................................ 2
Element Usage ............................................................................................................................. 2
1. Introduction ............................................................................................................................... 7
2. ICP XML V4 .............................................................................................................................. 8
2.1.

Process Overview ......................................................................................................... 8

2.2.

Procurement Cards (VGIS) ........................................................................................... 9

3. Integration ............................................................................................................................... 10
3.1.

Integration Process ..................................................................................................... 11

3.2.

Commidea Timeouts ................................................................................................... 11

3.3.

Integration Testing....................................................................................................... 12

3.4.

Testing URLs............................................................................................................... 13

3.5.

Integration Methods..................................................................................................... 13

3.5.1. SOAP ......................................................................................................................... 13
3.5.2. Web Service Proxy .................................................................................................... 13
3.5.3. Web Service Discovery Language ............................................................................. 14
3.5.4. Web Referencing ....................................................................................................... 14
3.6.

PayPal Sandbox and Testing ...................................................................................... 15

3.7.

Grant PayPal API Permissions.................................................................................... 16

3.8.

Live URLs .................................................................................................................... 17

3.9.

Web Service XSDs ...................................................................................................... 17

3.10.

Merchant Advice to Cardholders ................................................................................. 17

3.11.

Customer Specific Hash .............................................................................................. 18

3.12.

On-Hold and Release Functionality............................................................................. 18

4. Message Formats ................................................................................................................... 19
4.1.

Message ...................................................................................................................... 19

4.2.

ClientHeader ............................................................................................................... 19

4.3.

Processing DB Field .................................................................................................... 20

4.4.

Error Response ........................................................................................................... 20

5. Transactions ........................................................................................................................... 21
5.1.

Transaction Process.................................................................................................... 21

5.2.

Transaction Message Types ....................................................................................... 21

5.2.1. Transaction Request .................................................................................................. 21
5.2.2. ICC Data .................................................................................................................... 25
© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
4

Public

Version
5.28

5.2.3. PayerAuth AuxiliaryData ............................................................................................ 27
5.2.4. Confirmation Request ................................................................................................ 28
5.2.5. Rejection Request ..................................................................................................... 29
5.2.6. Transaction Response ............................................................................................... 30
5.3.

Transaction Results..................................................................................................... 31

6. PayerAuth ............................................................................................................................... 33
6.1.

PayerAuth Process...................................................................................................... 33

6.1.1. PayerAuth Expiry ....................................................................................................... 36
6.1.2. Canadian Corporate Purchase Cards ........................................................................ 36
6.1.3. Process Transaction .................................................................................................. 36
6.1.4. Payer Authentication with Token ............................................................................... 36
6.1.5. Chargeback Information ............................................................................................ 36
6.1.6. Cardholder Authentication Implementation Guidelines .............................................. 37
6.2.

PayerAuth Message Types ......................................................................................... 38

6.2.1. PayerAuth EnrollmentCheck Request ....................................................................... 38
6.2.2. PayerAuth EnrollmentCheck Response .................................................................... 40
6.2.3. PayerAuth AuthenticationCheck Request .................................................................. 41
6.2.4. PayerAuth AuthenticationCheck Response ............................................................... 41
7. Payer Authentication Decisions .............................................................................................. 43
7.1.

Non Supporting Card Schemes................................................................................... 44

8. On-Hold & Release Functionality ............................................................................................ 45
8.1.

Release Request ......................................................................................................... 45

8.1.1. Request Example ...................................................................................................... 45
8.1.

Release Response ...................................................................................................... 46

8.1.1. Response Example.................................................................................................... 46
9. PayPal..................................................................................................................................... 47
9.1.

PayPal Express Checkout Process ............................................................................. 47

9.2.

PayPal Message Types............................................................................................... 48

9.2.1. SetExpressCheckout Request ................................................................................... 48
9.2.2. SetExpressCheckout Response ................................................................................ 54
9.2.3. GetExpressCheckoutDetails Request ....................................................................... 55
9.2.4. GetExpressCheckoutDetails Response ..................................................................... 56
9.2.5. DoExpressCheckoutPayment Request ..................................................................... 58
9.2.6. PayPal ExpressItem .................................................................................................. 61
© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
5

Public

Version
5.28

9.2.7. DoExpressCheckoutPayment Response ................................................................... 63
9.2.8. DoAuthorization Request ........................................................................................... 66
9.2.9. DoAuthorization Response ........................................................................................ 67
9.2.10. DoCapture Request ................................................................................................. 68
9.2.11. DoCapture Response .............................................................................................. 70
9.2.12. DoVoid Request....................................................................................................... 73
9.2.13. DoVoid Response .................................................................................................... 74
9.2.14. RefundTransaction Request .................................................................................... 74
9.2.15. RefundTransaction Response ................................................................................. 76
9.2.16. DoReauthorization Request ..................................................................................... 77
9.2.17. DoReauthorization Response .................................................................................. 78
10. Stored Value Solutions (SVS) ............................................................................................... 79
10.1.

SVS Functionality ........................................................................................................ 79

10.2.

SVS Message Types ................................................................................................... 79

10.2.1. SVS Request ........................................................................................................... 79
10.2.2. SVS Response ........................................................................................................ 80
10.3.

Part Payments ............................................................................................................. 81

11. Token Gateway ..................................................................................................................... 82
11.1.

Token Registration Process ........................................................................................ 82

11.2.

Token Message Types ................................................................................................ 83

11.2.1. Registration Request (TKI) ...................................................................................... 83
11.2.2. Token Registration Response (TKI) ........................................................................ 84
11.2.3. Registration Request (TKI2) .................................................................................... 85
11.2.4. Token Registration Response (TKI2) – Success ..................................................... 86
11.2.5. Token Registration Response (TKI2) – Failure ....................................................... 86
12. Ukash Message Types ......................................................................................................... 87
12.1.

Ukash GetSettleAmount Request ............................................................................... 87

12.2.

Ukash PartSpendVoucher Request ............................................................................ 88

12.3.

Ukash FullValueVoucher Request .............................................................................. 89

12.4.

Ukash PartSpendAccount Request ............................................................................. 90

12.5.

Ukash FullSpendAccount Request.............................................................................. 91

12.6.

TransactionEnquiry Request ....................................................................................... 92

12.7.

Ukash Response ......................................................................................................... 93

12.8.

Ukash Return Code List .............................................................................................. 94
© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

12.9.

Document name
Web Service Guide
Date
May 2011
Page number
6

Public

Version
5.28

Ukash Transaction Type List ....................................................................................... 94

12.10.

Ukash Error Code List ............................................................................................. 95

12.11.

Ukash Product Codes ............................................................................................. 96

13. Troubleshooting .................................................................................................................... 99
13.1.

Deserialization Errors .................................................................................................. 99

13.2.

Contact Information ................................................................................................... 100

APPENDIX A – Website Testing Script .................................................................................... 101
APPENDIX B – Currency Code ISO 4217 ................................................................................ 103
APPENDIX C – Country Codes ISO 3166 ................................................................................ 107
APPENDIX D – Performing a LUHN Check .............................................................................. 111
APPENDIX E – Commidea Error Codes ................................................................................... 112

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
7

Public

Version
5.28

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.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
8

Public

Version
5.28

2. ICP XML V4
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.

2.1. Process Overview
Commidea have a Web Service with a single function ‘processmessage’ which has an input
parameter of ‘message’ and an output parameter of ‘message’. This is defined by the WSDL
which is located at:
https://testweb.commidea.com/commideagateway/commideagateway.asmx?WSDL
A ‘message’ has the following fields:
ClientHeader
SystemGUID)

which is a complex type (having multiple fields, e.g. SystemID,

MsgType

which is a string and informing the solution how to read the MsgData

MsgData

which is a string containing the data which makes up the message

When the processmessage function is called, a message with the clientheader, msgtype and
msgdata supplied will be passed to the Web Service. Commidea, in turn, will process this
message and respond accordingly.
© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
9

Public

Version
5.28

The XSDs define the structure of the MsgData. Before a transactionrequest is sent in, the
MsgType must be set and the MsgData populated according to the XML structure of a
transactionrequest. Commidea then attempt to process the request and respond with a
corresponding message.
This does not necessarily mean a message containing a transactionresponse because if the
XML sent in is of an unreadable format or does not conform to the XSD then Commidea can
return a message containing an error detailing what has occurred. The MsgType is set to
‘ERROR’ and the MsgData contains the XML structure of an error, for which there are XSDs
available.

2.2. Procurement Cards (VGIS)
For integrators looking to process procurement cards (also known as to as ‘VGIS’) then please
ensure that the Commidea Procurement Card Specification documentation in used in
conjunction with the Web Services Guide.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
10

Public

Version
5.28

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

Expected Outcome
Accepted, 789DE
Voice referred
Declined
Communications Down
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
12

AD1AVSRESULT
0 – Not Provided
1 – Not Checked
2 – Matched
4 – Not Matched
8 – Partial Match

Post Code Value

ME555LH or 555
ME156LH or 156
ME111LH or 111
ME122LH or 122

PCAVSRESULT
0 – Not Provided
1 – Not Checked
2 – Matched
4 – Not Matched
8 – Partial Match

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.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
11

Public

Version
5.28

3.1. Integration Process
Before any testing can commence please ensure that a request for an XML test script is sent to
the implementations Department. After receiving this, the ‘Introduction’ and ‘Live Details’ tabs
must be completed and returned via email. As soon as this has been received the integration
will be added to a testing queue. This process is in place for websites only and it is
recommended that the test scripts are delivered to Commidea, at the absolute least, 2 weeks
prior to any planned go live date. If there is a go live date to met, Implementations must be
informed of this as soon as possible. Once the tests have been completed the script will be
returned along with comments on any changes that Commidea require. After these changes
have been made, and comments added to the script, please return it to Implementations to
request re-testing. This process will continue until sign off is achieved.
Should you have any questions regarding the integration process, general technical queries or
assistance then the Implementations team are available and will be happy to help.

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
12

Public

Version
5.28

3.3. 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 Declined transactions
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
Referred, Declined and ‘Comms Down’ responses should all be catered for. These can
be simulated using the test system. Please see the Website Testing Script for more
information.

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

When developing a system for use in a call centre environment (not a customer facing website
front end) it will be necessary for the system to display the merchant number, terminal ID and

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
13

Public

Version
5.28

voice referral telephone number in the case of a voice referral response. For a table of tests to
run through before releasing the solution to Commidea for testing, please see Appendix A.

3.4. Testing URLs
Please find below the test URLs required to gain access to the XML payment service:
https://testweb.commidea.com/commideagateway/commideagateway.asmx

3.5. 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:
3.5.1. 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

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
14

Public

Version
5.28

3.5.3. Web Service Discovery Language
To access the WSDL descriptions, please visit the following
URLs:
https://testweb.commidea.com/commideagateway/commideagate
way.asmx?WSDL

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

Now that the reference has been added enabling consumption of the web service, via the use of
a proxy class.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
15

Public

Version
5.28

3.6. PayPal Sandbox and Testing
When integrating to PayPal, a simulation environment is provided called the ‘PayPal Sandbox’
which is accessed by logging in to Developer Central. All test accounts, email addresses,
funding sources (bank accounts, credit cards, balances, etc), etc are fictitious. Transactions are
simulated and no real money moves. Emails sent to test accounts are simulated by appearing
on Developer Central’s ‘Email’ tab. Follow the steps below to sign up for Developer Central and
create test accounts. The process is to create a test merchant account and a test buyer account
to make purchases. Additional information about Developer Central and the PayPal Sandbox is
online in the Sandbox User Guide.
1. Create
a
Developer
Central
login
and
password
by
signing
up
at https://developer.paypal.com. It is necessary to supply a valid (real) email address
when signing up. All documentation which may be required from PayPal is available via
a link on this page.
2. Create a test merchant account and a test customer account. PayPal request that
integrators do not use real financial account information when creating test accounts.
a. Login to Developer Central
b. Go to the ‘Sandbox’ tab and click the ‘Create Account’ link. This will launch
window which explains, using simulation, the PayPal account creation flow.
•

Test customer account: It is sufficient to create a PayPal personal test account. Be sure
to confirm the email address for the account as part of the setup. Look on Developer
Central’s ‘Email’ tab for the simulated account activation email which is required to
complete the email address confirmation. Also add a credit card to the test customer
account as a funding source so the account can make purchases – the account creation
flow will pre-populate a fictitious card number for use.

•

Test merchant account: It is necessary to add and confirm a bank account and also
confirm the email address to be able to get API credentials for doing API calls with the
test merchant account. Go to the test merchant account’s Profile tab/API Access link to
get API credentials.

Be sure to login first to Developer Central when testing redirection the customer to PayPal. To
connect to the Sandbox use the following endpoint with API calls:
NVP API:

https://api.sandbox.paypal.com/nvp/

SOAP API:

https://api.sandbox.paypal.com/2.0/

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
16

Public

Version
5.28

3.7. Grant PayPal API Permissions
Permissions will need to be granted to Commidea to make API calls on a merchant’s behalf.
Step by step instructions are detailed below.
1. Log into the PayPal account and select Profile from the options under My Account.

2. Select the tab under Account Information on the far left hand side of the page called
API Access.
3. Select the option Grant API Permission in the left hand box.
4. Enter paypal.admin_api1.commidea.com in the required field; tick all of the boxes and
Click Submit.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
17

Public

Version
5.28

5. A page requesting permission will appear. Click Give Permission.
6. A page detailing your account settings will appear. Click Log Out at the top of the page.

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

3.9. Web Service XSDs
To aid integration, Implementations have a set of XSDs available to provide some form of
example code to allow developers to get started.
To acquire these XSDs please email implementations@commidea.com and with a subject title
of ‘XML V4 – XSD Request’.

3.10.

Merchant Advice to Cardholders

Commidea recommends merchants provide information to their customers regarding the
measures taken on the website to secure and protect cardholder data.
When the cardholder processes a payment on the merchant website an SSL certificate must be
employed by the merchant to shield sensitive information. A statement similar to the below to
© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
18

Public

Version
5.28

detail this to the customer may help provide peace of mind when using the website to purchase
goods:
“We use SSL (Secure Socket Layer) technology to encrypt and protect information which you
submit through our site or checkout.
‘Verified by Visa’ and ‘Mastercard SecureCode’ are schemes that have been introduced by card
issuers to help fight against online fraud. [Merchant Name] is committed to combat fraud and is
now participating in these schemes along with a growing number of participating retailers.”

3.11.

Customer Specific Hash

Some merchants require the ability to return a customer specific hashed version of the card
number via the solution when processing payments. The XML Gateway supports this
functionality via the  field within the transaction response message.
The field will be populated with the hash when the functionality is enabled on the merchant
system.
For more information on this functionality, speak to the Commidea Account Manager.

3.12.

On-Hold and Release Functionality

To cater for merchants who require the ability to review transactions prior to settlement,
Commidea can enable the On-Hold & Release functionality on a per merchant account basis.
When enabled, each transaction processed by any of Commidea’s solutions will be flagged as
‘On-Hold’ and will not be sent for settlement until the transaction is updated or “released”.
Releasing a transaction is achieved by sending a Release Request via the Web Service
gateway, transactions will be released by merchants once the transaction in question has been
reviewed and the merchant is satisfied that it can be released and therefore submitted for
settlement but Commidea. This message format for the release request is documented within
this guide.
To provide the information required by the Web Service when sending a Release Request
message for an On-Hold transaction (as discussed above), the integration version for the
transaction response message provided by Ocius Sentinel will need to be set to ‘Version 6’.
This will ensure the Server Identity/AuthID and Transaction ID are sent in fields 35 and 36.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
19

Phone
08444 828 200

Public

Version
5.28

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 markup. Here is an example, where using a reference of “Chip&PIN”:
Chip&PIN]]>
Without the use of CDATA wrapping this reference would not be valid because “&” is an illegal
character within XML elements.
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


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

M

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
20

Phone
08444 828 200

CDATAWrapping

Boolean

Public

Version
5.28

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

O



4.3. 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.4. Error Response
The error response will be returned in the event of a processing error:
Section/Fields

Code
MsgTxt


Type/Format

Description

Integer
String

Code indicating error type
Description of error

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
21

Phone
08444 828 200

Public

Version
5.28

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
Commidea seeks
authorisation on behalf of
Transaction Response
generated and returned to

Merchant stores response
and returns

Merchant informs customer of
result and completes/cancels

Commidea stores transaction
ready for end of day

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

O

accountid

Decimal

M

accountpasscode
txntype

String
String

M
M

Merchant can add a reference to cross
reference responses relating to the same
transaction
Account reference number, supplied by
Commidea
Account passcode, supplied by Commidea
01 – Purchase
02 – Refund

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

transactioncurrencycode

String

M

terminalcountrycode

String

M

apacsterminalcapabilities

String

M

Document name
Web Service Guide
Date
May 2011
Page number
22

Public

Version
5.28

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

Integer

processingidentifier

Integer

M

M

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
All refund transactions should use the
‘Charge Only’ option.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

tokenid
pan

Decimal
String

Document name
Web Service Guide
Date
May 2011
Page number
23

Public

Version
5.28

O
C

Token Identifier for token transaction
Card number (Conditionally required, not
needed if providing a Token ID)
track2
String
C
Entire Track2 contents
(including start and end sentinels and LRC)
(Conditionally required, not needed if
providing a Token ID)
Track2 is only to be used for Cardholder
Present transaction only.
csc
String
O
Amex Card – 3 or 4 digits (front of card) All
Other Cards – 3 or 4 digits (rear security
strip)
avshouse
String
O
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
avspostcode
Integer
O
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 only
issuenumber
String
O
1 or 2 digit card issue number. Only
required by some Switch, Solo and Laser
cards, and only required when card is
keyed
expirydate
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)
startdate
String
O
Card start date month and year (MMYY)
Only required for 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
txnvalue
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

O

gratuity

Decimal

O

authcode
transactiondatetime

String
String

O
O

iccdata
vgisid

iccdata
String

O
O

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)

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

employeeid

Decimal

O

payerauthauxiliarydata

String

C

vgistransaction

Boolean

C

Document name
Web Service Guide
Date
May 2011
Page number
24

Public

Version
5.28

Field used to add information on the
employee processing the transaction
Payer Authentication auxiliary data.
This field is conditional upon the
capture method/transaction type. If
Payer Authentication is performed this
data must be supplied, even for nonsupporting card schemes. Capture
methods such as ICC will not require
Payer Auth auxiliary data to be supplied
Denotes if the transaction is a procurement
card/VGIS transaction.
Ensure the Procurement Guide
Specification is utilised alongside the
Web Services Guide for full VGIS data
requirements



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
25

Phone
08444 828 200

Public

Version
5.28

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

M

emvterminaltype

String

M

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 –

reasononlinecode

String

M

arqc

String

M

apppansequenceno

String

M

aip

String

M

atc

String

M

unpredictableno
tvr

String
String

M
M

E
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 Online 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 standin authorisation would be an
appropriate action for this
transaction. I.e. was it the ICC or
the CAD which required an online 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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
26

Phone
08444 828 200

cryptotxntype

String

M

iad

String

M

aid

String

M

terminalapplicationversionnumber

String

M

cardapplicationversionnumber

String

M

cvmr

String

M

cryptoinfodata

String

M

Public

Version
5.28

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



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
27

Public

Version
5.28

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.
This data must be supplied whenever Payer Authentication is processed, even if a nonsupporting card scheme is presented. For the data to supply in this instance please see
section 7.4.3 or consult Implementations for further guidance.
Section/Fields

Type/Format

Mandatory
/ Optional

Description


authenticationstatus

String

M

authenticationcavv

String

M

authenticationeci

String

M

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



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
28

Phone
08444 828 200

Public

Version
5.28

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

Decimal

M

offlineauthcode
gratuity

String
Decimal

O
O

transactioncertificate
arc
applicatonusagecontrol
tvr
cid
tsi
iad


String
String
String
String
String
String
String

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
29

Public

Version
5.28

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

Decimal

M

tokenid
capturemethod

Decimal
Integer

O
M

pan

String

C

track2

String

C

csc

String

O

avshouse

String

O

avspostcode

Integer

O

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).
Conditional as not required if TokenID
provided.
Entire Track2 contents
(including start and end sentinels and LRC).
Conditional as not required if TokenID
provided.
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 only



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
30

Public

Version
5.28

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 FTR (for the final transaction result message) and the namespace is TXN.
Section/Fields

merchantreference

Type/Format

Description

String

transactionid
resultdatetimestring

Decimal
String

processingdb
errormsg
merchantnumber
tid
schemename

String
String
String
String
String

Merchant can add a reference to cross reference responses relating
to the same transaction
Transaction ID (unique only to the processing database utilised)
Extended date and time string
( YYYY-MM-DDTHH:MM:SS.sss)
This indicates the database used to processing the request.
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 – Visa Debit
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, if
transaction value is below the floor limit or if the transaction is a refund
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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
31

Public

Version
5.28

APPROVED
AUTHORISED
AUTHONLY

pcavsresult

Integer

For further information on the transaction results please see section
5.3.
Postcode AVS result:
0 – Not provided*
1 – Not checked
2 – Matched
4 – Not matched
8 – Partial Match

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
8 – Partial Match

cvcresult

Integer

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

arc

String

iadarc
iadoad
isd
authorisingentity

String
String
String
Integer

vgisreference

String

customerspecifichash

String

*Default result when no details are provided
Acquirer response code.
Should integrators wish to utilise this information to provide further
insight into the transaction result, please contact your acquirer for
further information, as this differs per acquirer.
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
VGIS Reference assigned to the transaction. Only returned when
vgistransaction is passed within the transaction request as ‘true’.
Ensure the Procurement Guide Specification is utilised alongside
the Web Services Guide for full VGIS data requirements
Hashed version of the card number, specific to the configuration of the
merchant in question.
Feature must be enabled before the field will be returned



5.3. Transaction Results
In order to provide more information surrounding the various transaction result statues which
are returned within a transaction response; the below definitions have been detailed:
© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
32

Public

Version
5.28

ERROR – There has been an error with the payment due to malformed XML, bad content or
something fundamental has been incorrect in the request.
REFERRAL – This is a voice referral message for when the bank have requested the
cardholder call their acquirer for some validation or checking reason. This is generally not
supported in an E-commerce environment.
COMMSDOWN – The communications channel to the acquirer is down on Commidea’s side
and as such no authorisation could be sought. A call with the helpdesk should be logged in this
situation.
DECLINED – The transaction has been declined. Further information can be obtained from the
 field.
REJECTED – This result is returned when a payment is rejected after an initial authorisation
due to such reasons as a not matched CV2 or AVS response. Essentially this result means the
merchant has decided not to charge the transaction after an authorisation has been successful.
CHARGED – This result will be received after a charge request has been completed in order to
settle the funds, following an authorisation-only (‘Auth-Only) request. This result will be returned
after the initial response of APPROVED is received from the charge request, with CHARGED
being returned after the confirmation of the charge.
APPROVED – This is the first transaction result received when a charge request is sent to
settle an authorisation only request. ‘CHARGED’ is received once the confirmation is sent as
the second part of this process.
AUTHORISED – This denotes the successful authorisation of a standard auth and charge
transaction (one which is not linked to an initial authorisation only transaction) and the
confirmation (or rejection – see REJECTED) is required.
AUTHONLY – This indicates that the card has been the subject of an authorisation only
transaction (see CHARGED). This is usually performed prior to a charge request being sent to
settle the funds.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
33

Phone
08444 828 200

Public

Version
5.28

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

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
34

Public

Version
5.28

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.

vi.

vii.

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)
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.
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
© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

viii.
ix.
x.

Document name
Web Service Guide
Date
May 2011
Page number
35

Public

Version
5.28

message. The result is posted to the TermUrl on the web site, and the form posted by
the issuing bank includes the PaRes.
Extract the PaRes message from the form data and request the Commidea
Authentication Check to validate the contents of the PaRes message.
Depending upon the result of the Authentication Check; the merchant can now decide
whether or not to proceed.
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
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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
36

Public

Version
5.28

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
37

Public

Version
5.28

6.1.6. 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.”
2. 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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
38

Phone
08444 828 200

Public

Version
5.28

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, merchants using inline authentication
windows with frames must populate the TERMURL field with a HTTPS address.

6.2. PayerAuth Message Types
6.2.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

O

mkaccountid

Decimal

M

mkacquirerid

Decimal

M

Merchant can add a reference
to cross reference responses
relating to the same
transaction
Account reference number,
supplied by Commidea
Acquirer reference number
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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
39

Phone
08444 828 200

merchantname

String
Varchar(25)

M

merchantcountrycode

String
Varchar(50)

M

merchanturl

String
Varchar(255)

M

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)

C

Public

Version
5.28

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
40

Phone
08444 828 200

cardexpyear

String
Char(2)

C

cardexpmonth

String
Char(2)

C

currencycode

String
Char(3)

M

currencyexponent

String
Char(1

M

browseracceptheader

String
Varchar(255)

O

browseruseragentheader

String
Varchar(255)

O

transactionamount

String
Varchar(50)

M

transactiondisplayamount

String
Varchar(50)

M

transactiondescription

String
Varchar(50)

O

Public

Version
5.28

Card expiry date year YY e.g.
08
(not passed if token id
supplied)
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
authorisation 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 useragent 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.



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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
41

Phone
08444 828 200

processingdb

String

payerauthrequestid
enrolled

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

acsurl
pareq

errorcode
errordescription

Public

Version
5.28

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

Integer
String
Varchar(1000)



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

O

payerauthrequestid

Decimal

M

pares

String

C

enrolled

String

M

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



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

merchantreference

Type/Format

Description

String

Merchant can add a reference to cross reference
responses relating to the same transaction

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

payerauthrequestid
authenticationstatus

Decimal
String

authenticationcertificate

String

authenticationcavv

String

authenticationeci

String

authenticationtime

String

atsdata
errorcode
errordescription
processingdb

String
Integer
String
String

Document name
Web Service Guide
Date
May 2011
Page number
42

Public

Version
5.28

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



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
43

Phone
08444 828 200

Public

Version
5.28

7. Payer Authentication Decisions
In order to decide upon which situations to accept or decline transaction, the below table is included and covers 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.
Case
Number
1
2
3
4
5
6
7

Card Type
Visa 3D
Visa 3D
Visa 3D
Mcard 3D
Mcard 3D
Mcard 3D
None 3D

MPI Authentication
VERes PARes CAVV/AVV
Y
Y
Yes
Y
A
Yes
N
None
None
Y
Y
Yes
Y
A
Yes
N
None
None
None
None
None

8
9
10
11

Visa 3D
Visa 3D
Mcard 3D
Mcard 3D

U
Y
U
Y

None
U
None
U

12
13

Visa 3D
Mcard 3D

Y
Y

N
N

APACS Authorisation
CAVV/AVV Trans ID
Yes
Yes
Yes
Yes
None
None
Yes
Yes
Yes
Yes
None
None
None
None

ATSD
D0C100
D0C200
D0C200
D09100
D09200
D09200
808000

Streamline Settlement
Trans source Liability Shift
12
Yes
13
Yes
13
Yes
12
Yes
13
Yes
13
Yes
14
No

ECI
05
06
None
02
01
None
None

ECI
05
06
None
02
01
None
None

None
None
None
None

None
None
None
None

None
None
None
None

None
None
None
None

None
None
None
None

D0C400
D0C400
D09400
D09400

14/13
14/13
13
13

No
No
Yes
Yes

None
None

None
None

None
None

None
None

None
None

None
None

None
None

None
None

RAG Status

Key to VERes & PARes Codes:
Y (VERes)
N (VERes)
U (VERes)
Y (PARes)

Perform a PARes
Issuer/BIN not participating
Authentication process did not complete correctly
Cardholder enrolled and authenticated

A (PARes)
N (PARes)
U (PARes)

Cardholder not enrolled
Cardholder enrolled, transaction not authenticated
Authentication process did not complete correctly

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
44

Phone
08444 828 200

Public

Version
5.28

Key to RAG Status:
Indicates a BAU (business as usual) transaction
Indicates a system failure at some point
Indicates attempted fraud or cardholder error
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

7.1. 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, Solo

VERES
N/A

PARES
N/A

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

ATSD
D08000

ECI
07

8. On-Hold & Release Functionality
As discussed earlier within this guide, the on-hold and release functionality can be enabled on a
merchant account. Once enabled, each and every transaction will require a release message to
be sent to the Commidea servers via the Web Service before the transaction is submitted for
settlement to the acquirer.
These message formats are detailed below:

8.1. Release Request
The Message Type for the payer authentication enrollment
RELEASEONHOLDREQUEST and the namespace is ONHOLD.

check

response

is

Section/Fields

authdb

Type/Format

Description

String

mktransactionid


Decimal

The authorisation database within the Commidea infrastructure which
processed the transaction during authorisation
Transaction ID (unique only to the processing database utilised)

8.1.1. Request Example






30002411
096d5d0f-f9dc-430a-8d9c-e102393409c4
17075320
0

RELEASEONHOLDREQUEST


TEST_AUTHDB2
1969925
]]>





Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
46

Public

Version
5.28

8.1. Release Response
The Message Type for the payer authentication enrollment
RELEASEONHOLDRESPONSE and the namespace is ONHOLD.

check

response

Section/Fields

result

Type/Format

Description

String

Result of the release request. Result types are:

mktransactionid
authdb

Decimal
String

RELEASED
Transaction ID (unique only to the processing database utilised)
The authorisation database within the Commidea infrastructure
which processed the transaction during authorization

is



8.1.1. Response Example

3000
2411096d5d0f-f9dc-430a-8d9ce102393409c4TEST_AUTHDB20falseRELE
ASEONHOLDRESPONSE<releaseonholdresponse
xmlns="ONHOLD"><result>RELEASED</result><mktransactionid>1969925</mktrans
actionid><authdb>TEST_AUTHDB2</authdb></releaseonholdresponse>


© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
47

Public

Version
5.28

9. PayPal
9.1. PayPal Express Checkout Process
To provide an overview of the PayPal process, please see the flow chart shown below:

1

2

3
4

5

7

6

The steps can be summarised into the following process:
1. From the Merchant website the customer will have the option to Checkout with PayPal. If
this option is chosen a ‘SetExpressCheckout Request’ is created and sent. This will
contain the URL to which the customer’s browser is returned after choosing to pay with
PayPal.
2. PayPal returns a token, a string value used to track the customer throughout the
checkout process.
3. The website directs the customer to the PayPal site, where they log in, select a funding
source and confirm contact and shipping information.
4. The customer clicks the ‘Continue’ button and PayPal directs them to the ReturnURL
specified in the SetExpressCheckout Request, along with the token identifying the
customer appended to the URL.
5. The ‘GetExpressCheckoutDetails’ call is made to obtain the customer details from
PayPal, via ICP. The token sent from PayPal must be included to identify the customer
and allow PayPal to return the required information.
6. When the customer completes payment the ‘DoExpressCheckoutPayment’ request is
made, to which PayPal responds with the transaction result.
7. The transaction result is displayed to the customer.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
48

Phone
08444 828 200

Public

Version
5.28

From the point of view of the customer, they experience a three-click process:
1. Click to select to pay via PayPal
2. Click to confirm login details
3. Click to confirm the payment details
Should more information be required then a walkthrough document which describes in detail
how to integrate to PayPay Express Checkout (including button placement, button usage, and
button/logo image integration) can all be found within PayPal’s supporting documentation store.
Once the integration has been designed from a front-end perspective, the message types and
record sets which follow should be utilised. The integration can be tested with the PayPal test
accounts created using the instructions from section 3.5 & 3.6 of this manual.

9.2. PayPal Message Types
The Message Type for PayPal requests is PPI and the namespace is PAYPAL.

9.2.1. SetExpressCheckout Request
Section/Fields

Type/Format

Optional /
Required

Description


merchantreference

String

O

user

String

R

pwd
version

String
String

R
R

signature

String

R

subject

String

O

returnurl

String

R

cancelurl

String

R

Merchant can add a reference
to cross reference responses
relating to the same transaction
Merchant PayPal API
username
Merchant PayPal API password
Version number of the NVP API
service
Merchant PayPal signature
string
Email address of a PayPal
account that has granted
permission to make this call.
Set this parameter only if
calling an API on a different
user’s behalf
URL to which the customer’s
browser is returned after
choosing to pay with PayPal.
NOTE: PayPal recommends
that the value be the final
review page on which the
customer confirms the order
and payment or billing
agreement.
Character length and
limitations: no limit.
URL to which the customer is
returned if he does not approve
the use of PayPal to pay.
NOTE: PayPal recommends

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
49

Phone
08444 828 200

amt

Decimal

R

currencycode

String

O

maxamt

Decimal

O

paymentaction

String

O

Public

Version
5.28

that the value be the original
page on which the customer
chose to pay with PayPal or
establish a billing agreement.
Character length and
limitations: no limit
The total cost of the transaction
to the customer. If shipping cost
and tax
charges are known, include
them in this value; if not, this
value should be the current
sub-total of the order.
If the transaction includes one
or more one-time purchases,
this field must
be equal to the sum of the
purchases. If the transaction
does not include a one-time
purchase, this field can be set
to 0.
Limitations: Must not exceed
$10,000 USD in any currency.
No currency symbol. Must have
two decimal places, decimal
separator must be a period (.),
and the optional thousands
separator must be a comma (,).
A three-character currency
code for one of the currencies
listed in PayPalThe expected maximum total
amount of the complete order,
including shipping cost and tax
charges.
If the transaction does not
include a one-time purchase,
this field is ignored.
Limitations: Must not exceed
$10,000 USD in any currency.
No currency symbol. Must have
two decimal places, decimal
separator must be a period (.),
and the optional thousands
separator must be a comma (,).
How to obtain payment:
• ‘Sale’ indicates that this is
a final sale for which
payment is being
requested.
• ‘Authorization’ indicates
that this payment is a
basic authorisation
subject to settlement with
PayPal Authorisation &
Capture.
• ‘Order’ indicates that this
payment is an order
authorisation subject to
settlement with PayPal
Authorisation & Capture.
If the transaction does not
include a one-time purchase,

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
50

Phone
08444 828 200

email

String

desc

O

O

custom

String

O

invnum

String

O

reqconfirmshipping

Integer

O

Public

Version
5.28

this field is
ignored.
NOTE: This value cannot be
set to Sale in
SetExpressCheckout
request and then changed to
Authorisation or Order on the
final API
DoExpressCheckoutPayment
request. If the
value is set to Authorisation or
Order in
SetExpressCheckout, the value
may be set to Sale or the same
value (either Authorisation or
Order) in
DoExpressCheckoutPayment.
Character length and limit: Up
to 13 single-byte alphabetic
characters
Default value: Sale
Email address of the buyer as
entered during checkout.
PayPal uses this value to prefill the PayPal membership
sign-up portion of the PayPal
login page.
Character length and limit: 127
single-byte alphanumeric
characters
Description of items the
customer is purchasing.
Character length and
limitations: 127 single-byte
alphanumeric characters
A free-form field for use, such
as a tracking number or other
value for PayPal to return on
GetExpressCheckoutDetails
response and
DoExpressCheckoutPayment
response.
A unique invoice or tracking
number. PayPal returns this
value on
DoExpressCheckoutPayment
response.
If the transaction does not
include a one-time purchase,
this field is ignored.
Character length and
limitations: 127 single-byte
alphanumeric characters
The value 1 indicates that the
customer’s shipping address is
required on file with PayPal to
be a confirmed address.
NOTE: Setting this field
overrides the setting specified
in the
Merchant Account Profile.
Character length and
limitations: One single-byte
numeric character.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
51

Phone
08444 828 200

noshipping

Integer

O

addoverride

Integer

O

token

String

O

localecode

String

O

pagestyle

String

O

Public

Version
5.28

Allowable values: 0, 1
Default: 0
The value 1 indicates that on
the PayPal pages, no shipping
address fields should be
displayed whatsoever.
Character length and
limitations: One single-byte
numeric character.
Allowable values: 0, 1
Default: 0
The value 1 indicates that the
PayPal pages should display
the shipping address set in this
SetExpressCheckout request,
not the shipping address on file
with PayPal for this customer.
Displaying the PayPal street
address on file does not allow
the customer to edit that
address.
Character length and
limitations: One single-byte
numeric character.
Allowable values: 0, 1
Default: 0
A timestamped token by which
to identify to PayPal that the
merchant is processing this
payment with Express
Checkout.
NOTE: The token expires after
three hours.
If the token is set in the
SetExpressCheckout request,
the value of the token in the
response is identical to the
value in the request.
Character length and
limitations: 20 single-byte
characters
Locale of pages displayed by
PayPal during Express
Checkout.
Character length and
limitations: Any two-character
country code.
The following two-character
country codes are supported by
PayPal:
• AU
• DE
• FR
• IT
• GB
• ES
• US
Any other value will default to
US.
This value corresponds to the
HTML variable page_style for
customising payment pages.
The value is the same as the

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
52

Phone
08444 828 200

hdrimg

String

O

hdrbordercolor

String

O

hdrbackcolor

String

O

payflowcolor

String

O

channeltype

String

O

solutiontype

String

O

Public

Version
5.28

Page Style Name chosen when
adding or editing the page style
from the Profile subtab of the
My Account tab of the merchant
PayPal account.
Character length and
limitations: 30 single-byte
alphabetic characters.
URL for the image to appear at
the top left of the payment
page.
The image has a maximum size
of 750 pixels wide by 90 pixels
high.
PayPal recommends providing
an image that is stored on a
secure (https) server. If an
image is not specified, the
business name is displayed.
Character length and limit: 127
single-byte alphanumeric
characters
Sets the border color around
the header of the payment
page. The border
is a 2-pixel perimeter around
the header space, which is 750
pixels wide
by 90 pixels high. By default,
the color is black.
Character length and
limitations: Six character HTML
hexadecimal color
code in ASCII
Sets the background color for
the header of the payment
page. By default, the color is
white.
Character length and limitation:
Six character HTML
hexadecimal color
code in ASCII
Sets the background color for
the payment page. By default,
the color is white.
Character length and limitation:
Six character HTML
hexadecimal color code in
ASCII
Type of channel:
• Merchant: non-auction
seller
• eBayItem: eBay auction
If the transaction does not
include a one-time purchase,
this field is ignored.
Type of checkout flow:
• Sole: Express Checkout
for auctions
• Mark: normal Express
Checkout
If the transaction does not
include a one-time purchase,

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
53

Phone
08444 828 200

Public

Version
5.28

this field is ignored.
A value of 1 indicates that the
customer billing address should
be returned in subsequent API
calls. If the value is 0, the billing
address is not returned.
billingtype
String
See
Type of billing agreement.
description
For recurring payments, this
field is required and must be
set to RecurringPayments.
billingagreementdescription
String
O
Description of goods or
services associated with the
billing agreement.
PayPal recommends that
providing a brief summary of
the terms & conditions of the
billing agreement.
billingagreementcustom
String
O
Custom annotation field for use.
NOTE: This field is ignored for
recurring payments.
paymenttype
String
O
Specifies type of PayPal
payment required for the billing
agreement, which is one of the
following values.
• ‘Any’
• ‘InstantOnly’
NOTE: This field is ignored for
recurring payments.
Passing the shipping information is optional, however the optional/required settings here refer to if
the merchant decides that this information is to be provided. If not providing shipping information,
none of the below fields are included.
shiptoname
String
R
Person’s name associated with
this shipping address.
Character length and
limitations: 32 single-byte
characters
shiptostreet
String
R
First street address.
Character length and
limitations: 100 single-byte
characters
shiptocity
String
R
Name of city.
Character length and
limitations: 40 single-byte
characters
shiptostate
String
O
State or province.
Character length and
limitations: 40 single-byte
characters Required for US
addresses only.
shiptocountrycode
String
R
Country code.
Character limit: Two single-byte
characters.
shiptozip
String
R
U.S. Zip code or other countryspecific postal code.
Character length and
limitations: 20 single-byte
characters
shiptostreet2
String
O
Second street address.
Character length and
limitations: 100 single-byte
characters
phonenum
String
O
Phone number.
Character length and limit: 20
single-byte characters
reqbillingaddress

Integer

O

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
54

Public

Version
5.28



9.2.2. SetExpressCheckout Response
Section/Fields

merchantreference

Type/Format

Description

String

paypalrequestid
token

Decimal
String

errorcode

String

shortmessage

String

longmessage

String

serveritycode

String

Merchant can add a reference to
cross reference responses relating
to the same transaction
Unique PayPal request identifier
A timestamped token by which to
identify to PayPal that the
merchant is processing this
payment with Express Checkout.
NOTE: The token expires after
three hours.
If the token is set in the
SetExpressCheckout request, the
value of the token in the response
is identical to the value in the
request.
Character length and limitations:
20 single-byte characters
Error identifier (Please see
Appendix E for a full list of errors)
General message (Please see
Appendix E for a full list of errors)
Detailed message (Please see
Appendix E for a full list of errors)
Severity of the error (Please see
Appendix E for a full list of errors)



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
55

Phone
08444 828 200

Public

Version
5.28

9.2.3. GetExpressCheckoutDetails Request
Section/Fields

Type/Format

Optional /
Required

Description


merchantreference

String

O

user

String

R

pwd

String

R

version

String

R

signature

String

R

subject

String

O

token

String

R

Merchant can add a
reference to cross
reference responses
relating to the same
transaction
Merchant PayPal API
username
Merchant PayPal API
password
Version number of the
NVP API service
Merchant PayPal
signature string
Email address of a
PayPal account that has
granted the merchant
permission to make this
call. Set this parameter
only if calling an API on a
different user’s behalf
A timestamped token, the
value of which was
returned by
SetExpressCheckout
response.
Character length and
limitations: 20 single-byte
characters
Allowable values: An
unexpired token



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
56

Public

Version
5.28

9.2.4. GetExpressCheckoutDetails Response
Section/Fields

merchantreference

Type/Format

Description

String

paypalrequestid
token

Decimal
String

email

String

payerid

String

payerstatus

String

salutation

String

firstname

String

middlename

String

lastname

String

suffix

String

countrycode

String

business
shiptoname

String
String

shiptostreet

String

shiptostreet2

String

shiptocity

String

Merchant can add a reference to cross
reference responses relating to the
same transaction
Unique PayPal request identifier
The timestamped token value that was
returned by SetExpressCheckout
response
and passed on
GetExpressCheckoutDetails request.
Character length and limitations: 20
single-byte characters
Email address of payer.
Character length and limitations: 127
single-byte characters
Unique PayPal customer account
identification number.
Character length and limitations:13
single-byte alphanumeric characters.
Status of payer. Valid values are:
• Verified
• Unverified
Character length and limitations: 10
single-byte alphabetic characters.
Possible values: verified, unverified
Payer’s salutation.
Character length and limitations: 20
single-byte characters
Payer’s first name.
Character length and limitations: 25
single-byte characters
Payer’s middle name.
Character length and limitations: 25
single-byte characters
Payer’s last name.
Character length and limitations: 25
single-byte characters
Payer’s suffix.
Character length and limitations: 12
single-byte characters
Payer’s country of residence in the form
of ISO standard 3166 two-character
country
codes.
Character length and limitations: Two
single-byte characters
Payer’s business name.
Person’s name associated with this
address.
Character length and limitations: 32
single-byte characters
First street address.
Character length and limitations: 100
single-byte characters
Second street address.
Character length and limitations: 100
single-byte characters
Name of city.
Character length and limitations: 40
single-byte characters

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

shiptostate

String

shiptocountrycode

String

shiptozip

String

addressstatus

String

custom

String

invnum

String

phonenum

String

billingaddressacceptedstatus

String

errorcode

String

shortmessage

String

longmessage

String

serveritycode

String

Document name
Web Service Guide
Date
May 2011
Page number
57

Public

Version
5.28

State or province
Character length and limitations: 40
single-byte characters
Country code.
Character limit: Two single-byte
characters.
U.S. Zip code or other country-specific
postal code.
Character length and limitations: 20
single-byte characters
Status of street address on file with
PayPal
A free-form field for own use, as set in
the Custom element of
SetExpressCheckout request.
Character length and limitations: 256
single-byte alphanumeric characters
An invoice or tracking number, as set in
the element of the same name in
SetExpressCheckout request .
Character length and limitations: 127
single-byte alphanumeric characters
Payer’s contact telephone number.
NOTE: PayPal returns a contact
telephone number only if the Merchant
account profile settings require that the
buyer enter one.
Character length and limitations: Field
mask is XXX-XXX-XXXX (for US
numbers) or
+XXX XXXXXXXX (for international
numbers)
Whether or not the customer accepted
the billing agreement. This value always
returns ‘Yes’.
Error identifier (Please see Appendix E
for a full list of errors)
General message (Please see
Appendix E for a full list of errors)
Detailed message (Please see
Appendix E for a full list of errors)
Severity of the error (Please see
Appendix E for a full list of errors)



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
58

Phone
08444 828 200

Public

Version
5.28

9.2.5. DoExpressCheckoutPayment Request
Section/Fields

Type/Format

Optional
/
Required

Description


merchantreference

String

O

user

String

R

pwd

String

R

version

String

R

signature

String

R

subject

String

O

token

String

R

paymentaction

String

R

Merchant can add a reference
to cross reference responses
relating to the same
transaction
Merchant PayPal API
username
Merchant PayPal API
password
Version number of the NVP
API service
Merchant PayPal signature
string
Email address of a PayPal
account that has granted
permission to make this call.
Set this parameter only if
calling an API on a different
user’s behalf
The timestamped token value
that was returned by
SetExpressCheckout
response and passed on
GetExpressCheckoutDetails
request.
Character length and
limitations: 20 single-byte
characters
How to obtain payment:
• ‘Sale’ indicates that this
is a final sale for which
payment is being
requested.
• ‘Authorization’ indicates
that this payment is a
basic authorisation
subject to settlement
with PayPal
Authorisation &
Capture.
• ‘Order’ indicates that
this payment is an order
authorisation subject to
settlement with PayPal
Authorisation &
Capture.
If the transaction does not
include a one-time purchase,
this field is ignored.
NOTE: This value cannot be
set to Sale in
SetExpressCheckout request
and then change this value to
Authorisation or Order on the
final API
DoExpressCheckoutPayment
request. If the value is set to
Authorisation or Order in

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
59

Phone
08444 828 200

payerid

String

R

amt

Decimal

R

desc

String

O

custom

String

O

invnum

String

O

notifyurl

String

O

itemamt

Decimal

O

Public

Version
5.28

SetExpressCheckout, the
value may be set to Sale or
the same value (either
Authorisation or Order) in
DoExpressCheckoutPayment.
Character length and limit: Up
to 13 single-byte alphabetic
characters
Default value: Sale
Allowable Values:
• Authorization
• Order
• Sale
Default: The transaction
resulting from
DoExpressCheckoutPayment
request will be a final sale..
Unique PayPal customer
account identification number
as returned by
GetExpressCheckoutDetails
response.
Character length and
limitations: 13 single-byte
alphanumeric characters.
Total of order, including
shipping, handling, and tax.
NOTE: Limitations: Must not
exceed $10,000 USD in any
currency.
No currency symbol. Must
have two decimal places,
decimal separator must be a
period (.), and the optional
thousands separator must be
a comma (,).
Description of items the
customer is purchasing.
Character length and
limitations: 127 single-byte
alphanumeric characters
A free-form field for use.
Character length and
limitations: 256 single-byte
alphanumeric characters
An invoice or tracking
number.
Character length and
limitations: 127 single-byte
alphanumeric characters
The merchant’s URL for
receiving Instant Payment
Notification (IPN) about this
transaction.
NOTE: If not specified in the
request, the notification URL
from the Merchant Profile is
used, if one exists.
Character length and
limitations: 2,048 single-byte
alphanumeric characters
Sum of cost of all items in this
order.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
60

Phone
08444 828 200

shippingamt

Decimal

O

handlingamt

Decimal

O

taxamt

Decimal

O

currencycode

String

O

Public

Version
5.28

Limitations: Must not exceed
$10,000 USD in any currency.
No currency symbol. Must
have two decimal places,
decimal separator must be a
period
(.), and the optional
thousands separator must be
a comma (,).
Total shipping costs for this
order.
NOTE: Character length and
limitations: Must not exceed
$10,000 USD in any currency.
No currency symbol.
Regardless of currency,
decimal separator must be a
period (.), and the optional
thousands separator must be
a comma (,). Equivalent to
nine characters maximum for
USD.
Total handling costs for this
order.
NOTE: Character length and
limitations: Must not exceed
$10,000 USD in any currency.
No currency symbol.
Regardless of currency,
decimal separator must be a
period (.), and the optional
thousands separator must be
a comma (,). Equivalent to
nine characters maximum for
USD.
Sum of tax for all items in this
order.
NOTE: Character length and
limitations: Must not exceed
$10,000 USD in any currency.
No currency symbol.
Regardless of currency,
decimal separator must be a
period (.), and the optional
thousands separator must be
a comma (,). Equivalent to
nine characters maximum for
USD.
A three-character currency
code for one of the currencies
listed in PayPalSupported Transactional
Currencies.

paypalexpressitems
paypalexpressitems O
Passing the shipping information is optional, however the optional/required settings here refer to if
the merchant decides that this information is to be provided. If not providing shipping information,
none of the below fields are included
shiptoname
String
R
Person’s name associated
with this address.
Character length and
limitations: 32 single-byte
characters
shiptostreet
String
R
First street address.
Character length and
© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
61

Phone
08444 828 200

shiptocity

String

R

shiptostate

String

O

shiptocountrycode

String

R

shiptozip

String

R

shiptostreet2

String

O

shiptophonenumber

String

O

Public

Version
5.28

limitations: 100 single-byte
characters
Name of city.
Character length and
limitations: 40 single-byte
characters
State or province.
Character length and
limitations: 40 single-byte
characters
Required for US addresses
only.
Country code.
Character limit: Two singlebyte characters
U.S. ZIP code or other
country-specific postal code.
Character length and
limitations: 20 single-byte
characters
Second street address.
Character length and
limitations: 100 single-byte
characters
Phone number.
Character length and limit: 20
single-byte characters



9.2.6. PayPal ExpressItem
Section/Fields

name

Type/Format

Optional / Required

Description

String

O

number

String

O

qty

Integer

O

taxamt

Decimal

O

amt

Decimal

O

Item name.
Character length and
limitations: 127 single-byte
characters
Item number.
Character length and
limitations: 127 single-byte
characters
Item quantity.
Character length and
limitations: Any positive
integer
Item sales tax.
Limitations: Must not
exceed $10,000 USD in
any currency. No currency
symbol. Must have two
decimal places, decimal
separator must be a period
(.), and the optional
thousands separator must
be a comma (,).
Cost of item
Limitations: Value can be
positive, negative or zero
and must not exceed
$10,000 USD in any
currency. No currency

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
62

Phone
08444 828 200

ebayitemnumber

String

O

ebayitemauctiontxnid

String

O

ebayitemorderid

String

O

Public

Version
5.28

symbol. Must have two
decimal places, decimal
separator must be a period
(.), and the optional
thousands separator must
be a comma (,).
Auction item number
Character length: 765
single-byte characters
Auction transaction
identification number
Character length: 255
single-byte characters
Auction order identification
number
Character length: 64
single-byte characters



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
63

Public

Version
5.28

9.2.7. DoExpressCheckoutPayment Response
Section/Fields

merchantreference

Type/Format

Description

String

paypalrequestid
token

Decimal
String

transactionid

String

transactiontype

String

paymenttype

String

ordertime

String

amt

Decimal

currencycode

String

feeamount

Decimal

Merchant can add a reference to cross
reference responses relating to the
same transaction
Unique PayPal request identifier
The timestamped token value that was
returned by SetExpressCheckout
response and passed on
GetExpressCheckoutDetails request.
Character length and limitations:20
single-byte characters
Unique transaction ID of the payment.
NOTE: If the PaymentAction of the
request was Authorisation or Order, this
value
is the merchant’s AuthorizationID for
use with the Authorization & Capture
APIs.
Character length and limitations:19
single-byte characters
Possible values: Transaction specific
The type of transaction
Character length and limitations:15
single-byte characters
Possible values:
• Cart
• Express-checkout
Indicates whether the payment is instant
or delayed.
Character length and limitations: Seven
single-byte characters
Possible values:
• None
• eCheck
• Instant
Time/date stamp of payment
Possible values: Transaction specific
The final amount charged, including any
shipping and taxes from the Merchant
Profile.
Character length and limitations: Does
not exceed $10,000 USD in any
currency. No
currency symbol. Regardless of
currency, decimal separator is a period
(.), and the
optional thousands separator is a
comma (,). Equivalent to nine
characters maximum for USD.
Possible Values: Transaction specific
A three-character currency code for one
of the currencies listed in PayPaySupported
Transactional Currencies.
PayPal fee amount charged for the
transaction.
Character length and limitations: Does
not exceed $10,000 USD in any
currency. No
currency symbol. Regardless of

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

settleamount

Decimal

taxamount

Decimal

exchangerate

Decimal

paymentstatus

String

pendingreason

String

Document name
Web Service Guide
Date
May 2011
Page number
64

Public

Version
5.28

currency, decimal separator is a period
(.), and the
optional thousands separator is a
comma (,). Equivalent to nine
characters maximum for USD.
Possible values: Transaction specific
Amount deposited in the merchant’s
PayPal account after a currency
conversion.
Possible values: Transaction specific
Tax charged on the transaction.
Character length and limitations: Does
not exceed $10,000 USD in any
currency. No
currency symbol. Regardless of
currency, decimal separator is a period
(.), and the
optional thousands separator is a
comma (,). Equivalent to nine
characters maximum for USD.
Possible values: Transaction specific
Exchange rate if a currency conversion
occurred. Relevant only if billing in their
non-primary currency. If the customer
chooses to pay with a currency other
than the nonprimary currency, the
conversion occurs in the customer’s
account.
Character length and limitations: a
decimal that does not exceed 17
characters, including decimal point
Possible values: Transaction specific
Status of the payment:
• Completed: The payment has
been completed, and the funds
have been added successfully to
the merchant’s account balance.
• Pending: The payment is
pending. See the PendingReason
element for more information.
The reason the payment is pending:
• None: No pending reason
• Address: The payment is pending
because the customer did not
include a confirmed shipping
address and the Payment
Receiving Preferences is set
such that the merchants wants to
manually accept or deny each of
these payments. To change
these preference, go to the
Preferences section of the
Profile.
• eCheck: The payment is pending
because it was made by an
eCheck that has not yet cleared.
• Intl: The payment is pending
because the merchant holds a
non-U.S. account and does not
have a withdrawal mechanism.
This payment must be manually
accepted or denied from the
Account Overview.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
65

•

reasoncode

String

redirectrequired

String

errorcode

String

shortmessage

String

longmessage

String

serveritycode

String

Public

Version
5.28

Multi-currency: There is no
balance in the currency sent, and
the Payment Receiving
Preferences are not set to
automatically convert and accept
this payment. This payment must
be manually accepted or denied.
• Verify: The payment is pending
because the merchant is not yet
verified. It is necessary to verify
the merchant account before
accepting this payment.
• Other: The payment is pending
for a reason other than those
listed above. For more
information, contact PayPal
customer service.
The reason for a reversal if
TransactionType is reversal:
• None: No reason code
• Chargeback: A reversal has
occurred on this transaction due
to a chargeback by the customer.
• Guarantee: A reversal has
occurred on this transaction due
to the customer triggering a
money-back guarantee.
• Buyer-complaint: A reversal has
occurred on this transaction due
to a complaint about the
transaction from the customer.
• Refund: A reversal has occurred
on this transaction because the
customer has been given a
refund.
• Other: A reversal has occurred
on this transaction due to a
reason not listed above.
Flag to indicate whether to redirect the
customer to back to PayPal after
completing the transaction.
NOTE: Use this field only if using
giropay or bank transfer payment
methods in Germany.
Error identifier (Please see Appendix E
for a full list of errors)
General message (Please see
Appendix E for a full list of errors)
Detailed message (Please see
Appendix E for a full list of errors)
Severity of the error (Please see
Appendix E for a full list of errors)



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
66

Phone
08444 828 200

Public

Version
5.28

9.2.8. DoAuthorization Request
Section/Fields

Type/Format

Optional /
Required

Description


merchantreference

String

O

user

String

R

pwd

String

R

version

String

R

signature

String

R

subject

String

O

transactionid

String

R

amt

Decimal

R

transactionentity

String

O

currencycode

String

O

Merchant can add a
reference to cross
reference responses
relating to the same
transaction
Merchant PayPal API
username
Merchant PayPal API
password
Version number of the
NVP API service
Merchant PayPal
signature string
Email address of a
PayPal account that has
granted permission to
make this call. Set this
parameter only if calling
an API on a different
user’s behalf
The value of the order’s
transaction identification
number returned by
PayPal.
Character length and
limits: 19 single-byte
characters maximum
Amount to authorize.
Limitations: Value is a
positive number which
cannot exceed $10,000
USD in any currency. No
currency symbol. Must
have two decimal places,
decimal separator must
be a period (.), and the
optional thousands
separator must be a
comma (,).
Type of transaction to
authorize. The only
allowable value is Order,
which means that the
transaction represents a
customer order that can
be fulfilled over 29 days.
A three-character
currency code for one of
the currencies listed in
PayPay-Supported
Transactional Currencies.



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
67

Public

Version
5.28

9.2.9. DoAuthorization Response
Section/Fields

merchantreference

Type/Format

Description

String

paypalrequestid
transactionid

Decimal
String

Amt
currencycode

Decimal
String

errorcode

String

shortmessage

String

longmessage

String

serveritycode

String

Merchant can add a reference to
cross reference responses relating to
the same transaction
Unique PayPal request identifier
An authorisation identification
number.
Character length and limits: 19 singlebyte characters
The amount specified in the request.
A three-character currency code for
one of the currencies listed in PayPal
Supported Transactional Currencies.
Error identifier (Please see Appendix
E for a full list of errors)
General message (Please see
Appendix E for a full list of errors)
Detailed message (Please see
Appendix E for a full list of errors)
Severity of the error (Please see
Appendix E for a full list of errors)



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
68

Phone
08444 828 200

Public

Version
5.28

9.2.10. DoCapture Request
Section/Fields

Type/Format

Optional /
Required

Description


merchantreference

String

O

user
pwd
version

String
String
String

R
R
R

signature
subject

String
String

R
O

authorizationid

String

R

amt

Decimal

R

currencycode

String

O

completetype

String

R

invnum

String

O

Merchant can add a reference to
cross reference responses
relating to the same transaction
Merchant PayPal API username
Merchant PayPal API password
Version number of the NVP API
service
Merchant PayPal signature string
Email address of a PayPal
account that has granted
permission to make this call. Set
this parameter only if calling an
API on a different user’s behalf
The authorisation identification
number of the payment to
capture. This is the transaction id
returned from
DoExpressCheckoutPayment or
DoDirectPayment.
Character length and limits: 19
single-byte characters maximum.
Amount to capture.
Limitations: Value is a positive
number which cannot exceed
$10,000 USD in any currency.
No currency symbol. Must have
two decimal places, decimal
separator must be a period (.),
and the optional thousands
separator must be a comma (,).
A three-character currency code
for one of the currencies listed in
PayPay-Supported Transactional
Currencies.
The value Complete indicates
that this the last capture intended
to be made.
The value NotComplete indicates
an intention to make additional
captures.
NOTE: If Complete, any
remaining amount of the original
authorised transaction is
automatically voided and all
remaining open authorisations
are voided.
Character length and limits: 12
single-byte alphanumeric
characters
An invoice number or other
identification number that is
displayed to the merchant and
customer in his transaction
history.
NOTE: This value on DoCapture
will overwrite a value previously
set on
DoAuthorization.
NOTE: The value is recorded

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
69

Phone
08444 828 200

note

String

O

softdescriptor

String

O

Public

Version
5.28

only if the authorisation being
captured is an order
authorisation, not a basic
authorisation.
Character length and limits: 127
single-byte alphanumeric
characters
An informational note about this
settlement that is displayed to
the payer in email and in his
transaction history.
Character length and limits: 255
single-byte characters
The soft descriptor is a per
transaction description of the
payment that is passed to the
consumer’s credit card
statement.
If a value for the soft descriptor
field is provided, the full
descriptor
displayed on the customer’s
statement has the following
format:
<1
space>
The soft descriptor can contain
only the following characters:
• Alphanumeric characters
• - (dash)
• * (asterisk)
• . (period)
•
(space)
If using any other characters
(such as “,”), an error code is
returned.
The soft descriptor does not
include the phone number, which
can be toggled between the
merchant’s customer service
number and PayPal’s customer
service number.
The maximum length of the total
soft descriptor is 22 characters.
Of this, either 4 or 8 characters
are used by the PayPal prefix
shown in the data format. Thus,
the maximum length of the soft
descriptor passed in the API
request is:
22 - len() len( + 1)
For example, assume the
following conditions:
• The PayPal prefix toggle is
set to PAYPAL * in
PayPal’s admin tools
• The merchant descriptor
set in the Payment

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
70

•
•

Public

Version
5.28

Receiving Preferences is
set to EBAY.
The soft descriptor is
passed in as
JanesFlowerGifts LLC
The resulting descriptor
string on the credit card
would be:
PAYPAL *EBAY
JanesFlow



9.2.11. DoCapture Response
Section/Fields

merchantreference

Type/Format

Description

String

paypalrequestid
authorizationid

Decimal
String

transactionid

String

parenttransactionid

String

receipttid

String

transactiontype

String

paymenttype

String

ordertime

String

currencycode

String

Merchant can add a reference to cross
reference responses relating to the same
transaction
Unique PayPal request identifier
The authorisation identification number
specified in the request.
Character length and limits: 19 single-byte
characters maximum
Unique transaction ID of the payment.
Character length and limitations: 17 singlebyte characters
Parent or related transaction identification
number. This field is populated for
the following transaction types:
• Reversal. Capture of an authorised
transaction.
• Reversal. Reauthorisation of a
transaction.
• Capture of an order. The value of
ParentTransactionID is the original
OrderID.
• Authorisation of an order. The value
of ParentTransactionID is the original
OrderID.
• Capture of an order authorisation.
• Void of an order. The value of
ParentTransactionID is the original
OrderID.
Character length and limits: 16 digits in
xxxx-xxxx-xxxx-xxxx format
Receipt identification number
Character length and limits: 16 digits in
xxxx-xxxx-xxxx-xxxx format
The type of transaction
• Cart
• Express-checkout
Character length and limitations: 15 singlebyte characters
Indicates whether the payment is instant or
delayed.
Character length and limitations: Seven
single-byte characters
Time/date stamp of payment. For example:
2006-08-15T17:23:15Z.
A three-character currency code for one of

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

amt

Decimal

feeamt

Decimal

settleamt

Decimal

taxamt
exchangerate

Decimal
Decimal

paymentstatus

String

errorcode

String

Document name
Web Service Guide
Date
May 2011
Page number
71

Public

Version
5.28

the currencies listed in PayPal Supported
Transactional Currencies
The final amount charged, including any
shipping and taxes from the Merchant
Profile.
PayPal fee amount charged for the
transaction
Amount deposited in the merchant’s
PayPal account if there is a currency
conversion.
Tax charged on the transaction, if any
Exchange rate if a currency conversion
occurred. Relevant only if billing in the
customer’s non-primary currency. If the
customer chooses to pay with a currency
other than the non-primary currency, the
conversion occurs in the customer’s
account.
Character length and limitations: a decimal
multiplier
Status of the payment.
The status of the payment:
• None: No status
• Canceled-Reversal: This means a
reversal has been canceled. For
example, if a dispute was won with
the customer, and the funds for the
transaction that was reversed have
been returned to the merchant.
• Completed: The payment has been
completed, and the funds have been
added successfully to the merchant’s
account balance.
• Denied: The payment was denied.
This happens only if the payment
was
previously pending because of
possible reasons described for the
PendingReason element.
• Expired: the authorisation period for
this payment has been reached.
• Failed: The payment has failed. This
happens only if the payment was
made from the customer’s bank
account.
• Pending: The payment is pending.
See the PendingReason field for
more information.
• Refunded: The payment was
refunded.
• Reversed: A payment was reversed
due to a chargeback or other type of
reversal. The funds have been
removed from the merchant’s
account balance and returned to the
buyer. The reason for the reversal is
specified in the
ReasonCode element.
• Processed: A payment has been
accepted.
• Voided: An authorisation for this
transaction has been voided.
Error identifier (Please see Appendix E for

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

shortmessage

String

longmessage

String

serveritycode

String

Document name
Web Service Guide
Date
May 2011
Page number
72

Public

Version
5.28

a full list of errors)
General message (Please see Appendix E
for a full list of errors)
Detailed message (Please see Appendix E
for a full list of errors)
Severity of the error (Please see Appendix
E for a full list of errors)



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
73

Phone
08444 828 200

Public

Version
5.28

9.2.12. DoVoid Request
Section/Fields

merchantreference

Type/Format

Optional / Required

Description

String

O

user

String

R

pwd

String

R

version

String

R

signature

String

R

subject

String

O

authorizationid

String

R

note

String

O

Merchant can add a
reference to cross reference
responses relating to the
same transaction
Merchant PayPal API
username
Merchant PayPal API
password
Version number of the NVP
API service
Merchant PayPal signature
string
Email address of a PayPal
account that has granted
permission to make this call.
Set this parameter only if
calling an API on a different
user’s behalf
The value of the original
authorisation identification
number returned by a
PayPal product.
IMPORTANT: If voiding a
transaction that has been
reauthorised,
use the ID from the original
authorisation, and not the
reauthorisation.
Character length and limits:
19 single-byte characters
An informational note about
this void that is displayed to
the payer in
email and in his transaction
history.
Character length and limits:
255 single-byte characters



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
74

Phone
08444 828 200

Public

Version
5.28

9.2.13. DoVoid Response
Section/Fields

merchantreference

Type/Format

Description

String

paypalrequestid
authorizationid

Decimal
String

errorcode

String

shortmessage

String

longmessage

String

serveritycode

String

Merchant can add a reference to
cross reference responses relating to
the same transaction
Unique PayPal request identifier
The authorisation identification
number specified in the request.
Character length and limits: 19 singlebyte characters
Error identifier (Please see Appendix
E for a full list of errors)
General message (Please see
Appendix E for a full list of errors)
Detailed message (Please see
Appendix E for a full list of errors)
Severity of the error (Please see
Appendix E for a full list of errors)



9.2.14. RefundTransaction Request
Section/Fields

merchantreference

Type/Format

Optional / Required

Description

String

O

user

String

R

pwd

String

R

version

String

R

signature

String

R

subject

String

O

transactionid

String

R

refundtype

String

R

amt

Decimal

O

currencycode

String

O

Merchant can add a
reference to cross reference
responses relating to the
same transaction
Merchant PayPal API
username
Merchant PayPal API
password
Version number of the NVP
API service
Merchant PayPal signature
string
Email address of a PayPal
account that has granted
permission to make this call.
Set this parameter only if
calling an API on a different
user’s behalf
Unique identifier of a
transaction
Character length and
limitations: 17 single-byte
alphanumeric characters
Type of refund being made:
• Other
• Full
• Partial
Refund amount.
Amount is required if
RefundType is Partial.
NOTE: If RefundType is Full,
do not set Amount.
A three-character currency
code for one of the
currencies listed in PayPal
Supported Transactional

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
75

Phone
08444 828 200

note

String

O

Public

Version
5.28

Currencies
Custom memo about the
refund.
Character length and
limitations: 255 single-byte
alphanumeric characters



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
76

Public

Version
5.28

9.2.15. RefundTransaction Response
Section/Fields

merchantreference

Type/Format

Description

String

paypalrequestid
currencycode

Decimal
String

refundtransactionid

String

netrefundamt

Decimal

feerefundamt

Decimal

grossrefundamt

Decimal

errorcode

String

shortmessage

String

longmessage

String

serveritycode

String

Merchant can add a reference to cross
reference responses relating to the
same transaction
Unique PayPal request identifier
A three-character currency code for one
of the currencies listed in PayPal
Supported Transactional Currencies
Unique transaction ID of the refund.
Character length and limitations:17
single-byte characters
Amount subtracted from PayPal
balance of original recipient of payment
to
make this refund
Transaction fee refunded to original
recipient of payment
Amount of money refunded to original
payer
Error identifier (Please see Appendix E
for a full list of errors)
General message (Please see
Appendix E for a full list of errors)
Detailed message (Please see
Appendix E for a full list of errors)
Severity of the error (Please see
Appendix E for a full list of errors)



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
77

Phone
08444 828 200

Public

Version
5.28

9.2.16. DoReauthorization Request
Section/Fields

Type/Format

Optional /
Required

Description


merchantreference

String

O

user

String

R

pwd

String

R

version

String

R

signature

String

R

subject

String

O

authorizationid

String

R

amt

Decimal

R

currencycode

String

O

Merchant can add a
reference to cross
reference responses
relating to the same
transaction
Merchant PayPal API
username
Merchant PayPal API
password
Version number of the
NVP API service
Merchant PayPal
signature string
Email address of a
PayPal account that has
granted permission to
make this call. Set this
parameter only if calling
an API on a different
user’s behalf
The value of a previously
authorised transaction
identification number
returned by PayPal.
Character length and
limits: 19 single-byte
characters maximum
Amount to reauthorise.
Limitations: Value is a
positive number which
cannot exceed $10,000
USD in any currency. No
currency symbol. Must
have two decimal places,
decimal separator must
be a period (.), and the
optional thousands
separator must be a
comma (,).
A three-character
currency code for one of
the currencies listed in
PayPaySupported Transactional
Currencies.



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
78

Public

Version
5.28

9.2.17. DoReauthorization Response
Section/Fields

merchantreference

Type/Format

Description

String

paypalrequestid
authorizationid

Decimal
String

errorcode

String

shortmessage

String

longmessage

String

serveritycode

String

Merchant can add a reference to
cross reference responses relating
to the same transaction
Unique PayPal request identifier
A new authorisation identification
number.
Character length and limits:19
single-byte characters
Error identifier (Please see
Appendix E for a full list of errors)
General message (Please see
Appendix E for a full list of errors)
Detailed message (Please see
Appendix E for a full list of errors)
Severity of the error (Please see
Appendix E for a full list of errors)



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
79

Phone
08444 828 200

Public

Version
5.28

10. Stored Value Solutions (SVS)
10.1.

SVS Functionality

Stored Value Solutions provide prepaid services to merchants. Commidea support SVS’
branded prepaid cards which are used to:
•
•
•
•
•

Reward and incentivise employees, customers, and partners
Improve foot traffic to your locations
Increase brand awareness
Facilitate new promotional and co-branding opportunities
Allow easy gift card acceptance across multiple point-of-sale systems

Prepaid cards are accepted the same way as any standard electronic funds transfer card
through Commidea’s XML Gateway.

10.2.

SVS Message Types

10.2.1. SVS Request
The Stored Value Solutions (SVS) Request type contains all the information required to process
a transaction using an SVS card.
Section/Fields

messagetype

Type/
Format

Length

Integer

Optional /
Required
M

Description

No
0
*1
2
*3
4
5
6
*7
*8
9
*10
*11
*12
13

stan

String

6

O

Message Type
Balance Enquiry
Pre-Authorization Message
Redemption Message
Tip Message
Cancellation
Merchandise Return Message
Card Recharge Message
Pre-Authorisation Completion
Message
Card Activation Message
Issue Gift Card
Issue Virtual Gift Card Message
Reversal Message
Network Message
Cash Back Message

* Reserved for future use, not currently available
Systems trace audit number. Example: 123456.
For the original transaction this should be left
blank and will be generated automatically. The

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
80

Phone
08444 828 200

offlineauthcode
cardnumber
track1
track2
transactionamount
transactioncurrency

String
String
String
String
Decimal
String

10
19

6
3

O
O
O
O
O
O

transactiondate
transactiontime
invoicenumber

String
String
String

8
6
8

O
O
O

merchantname
merchantnumber
storenumber
divisionnumber
routingid


String
String
String
String
String

50
6
10
5
19

O
M
O
M
M

Public

Version
5.28

original STAN must be passed in with reversals
Offline Authorisation Code
SVS card number
Track 1
Track 2
Transaction amount, e.g. 9.99
Currency Code (ISO 4217) for transaction (e.g.
826 = Pound Sterling)
Transaction date: YYYYMMDD – e.g. 20110110
Transaction time: HHMMSS - e.g. 175732
Client assigned value which may be used to
represent an order number or reference for the
transaction, e.g. INV01
Merchant name
SVS Merchant number
Store number
Division number
Routing ID

10.2.2. SVS Response
The SVS Response type contains all the result information from an SVS request.
Section/Fields

Type/
Format


id
responsecode

Decimal
String

Length

2

Description

The request ID
Code Return Description
01
Approval
02
Inactive Card
03
Invalid Card Number
04
Invalid Transaction Code
05
Insufficient Funds
06
No Previous Authorisations
07
Invalid Message
08
No Card Found
09
Insufficient Funds due to Outstanding preauthorisation.
10
Denial – No previous authorisation
11
No Authorization number
12
Invalid Authorization number
13
Maximum single recharge exceeded
14
Maximum working balance exceeded
15
Host Unavailable
16
Invalid Card Status
17
Unknown dealer/Store Code - Special edit
18
Maximum number of recharges exceeded
19
Invalid card verification value
20
Invalid PIN number / PIN Locked
21
Card already issued
22
Card not issued
23
Card already used
24
Manual Transaction not allowed
25
Mag Stripe read not valid
26
Transaction type unknown
27
Invalid tender type
28
Invalid customer type
29
n/a
30
Max number of redemption exceeded
31
Invalid currency code

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
81

Phone
08444 828 200

Public

Version
5.28

32

responsemessage
stan
transactionamount
balanceamount
conversionrate
cardcurrencycode


10.3.

String
String
Decimal
Decimal
Decimal
String

6
6
6
8
3

Invalid server id (restaurant only – server ID
code is invalid)
33
Frozen card or Unknown
34
Invalid amount (transaction amount does not
match the pre-valued card dollar amount)
99
Route does not exist for the routingID supplied
Description e.g. “Approved”
Systems trace audit number. Example: 123456.
Transaction amount supplied within request: E.g. 9.99
Balance amount remaining on the SVS card
Conversion rate. E.g. 1.000000
826 (Numeric translation of GBP)

Part Payments

Commidea supports SVS’ “Part Payment” functionality on both Terminal and XML solutions.
However, please note that this functionality will require additional logic to be put in place within
the merchant’s integration. Should an SVS transaction be initiated using an SVS card which
does not contain enough funds to pay off the entire balance, a separate transaction will be
required to clear the remaining balance.
In order to monitor for such an occurrence within the XML solution, the integration should take
note of the ‘TransactionAmount’ within the ‘ProcessMsgResponse’. This value should be
compared to the original ‘TransactionAmount’ from the ‘SVSRequestMessage’, with the
difference equating to the remaining balance in a scenario where there are insufficient funds on
the SVS card to pay the balance off in full. When a balance remains as per the above, the
merchant’s system should return the customer to a checkout page which details the remaining
amount to be paid and provides the option to input additional payment details, which could be
either a different SVS card number or a credit/debit card number for a standard EFT
transaction.
Commidea Best Practice: it is recommended that a balance enquiry is processed after the
transaction amount has been finalised. This will ensure that the SVS card provided by the
cardholder has sufficient funds before processing the transaction. In a scenario where the card
does not contain sufficient funds, the merchant can make the cardholder aware of this prior to
processing the transaction, and inform the cardholder that a further payment will be required.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
82

Phone
08444 828 200

Public

Version
5.28

11. Token Gateway
11.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 utilised to provide payment details for the transaction.
There are two versions of the Token Registration process:
•

TKI
card scheme name not returned from token registration, legacy message type

•

TKI2
message type added which returns a different response depending upon success or
failure of the registration process, including returning the card scheme name of the
registered details should the process be successful

Both message formats are detailed below. An overview of the registration process is shown in
the below diagram:
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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
83

Phone
08444 828 200

11.2.

Public

Version
5.28

Token Message Types

11.2.1. Registration Request (TKI)
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


merchantreference

String

O

Description

Merchant can add a
reference to cross
reference responses
relating to the same
transaction
pan
String
M
Card number
expirydate
String
M
Card expiry month and
year (YYMM)
(Only required when card
is keyed, can be
calculated from Track2)
startdate
String
C
Card start date month
and year (MMYY)
Only required for Diners
Club International, some
Maestro, 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
issuenumber
String
C
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
purchase
Boolean
M
Allow purchase txn type
refund
Boolean
M
Allow refund txn type
cashback
Boolean
M
Allow cashback txn type
tokenexpirationdate
String
M
Last date on which the
token can be utilised.
Format of date to be:
DDMMCCYY


© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
84

Public

Version
5.28

11.2.2. Token Registration Response (TKI)
The Token Registration Response type contains all the result information from a token
registration request.
The Message Type is TOKENRESPONSE and the namespace is TOKEN.
Section/Fields

tokenid
merchantreference

Type/Format

Description

Decimal
String

errorcode

Integer

errormsg

String

Unique identifier for registered PAN
Merchant can add a reference to
cross reference responses relating
to the same transaction
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



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
85

Phone
08444 828 200

Public

Version
5.28

11.2.3. Registration Request (TKI2)
The Token Registration Request type contains all the information required to register a token,
and ensures that the card scheme name is returned within the response message.
The Message Type is TKI2 and the namespace is TOKEN.
Section/Fields

Type/Format

Mandatory/
Optional/
Conditional


merchantreference

String

O

Description

Merchant can add a
reference to cross
reference responses
relating to the same
transaction
pan
String
M
Card number
expirydate
String
M
Card expiry month and
year (YYMM)
(Only required when card
is keyed, can be
calculated from Track2)
startdate
String
C
Card start date month
and year (MMYY)
Only required for Diners
Club International, some
Maestro, 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
issuenumber
String
C
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
purchase
Boolean
M
Allow purchase txn type
refund
Boolean
M
Allow refund txn type
cashback
Boolean
M
Allow cashback txn type
tokenexpirationdate
String
M
Last date on which the
token can be utilised.
Format of date to be:
DDMMCCYY


© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
86

Public

Version
5.28

11.2.4. Token Registration Response (TKI2) – Success
When the TKI2 token registration request is successful, the following message is returned.
The Message Type is TOKENRESPONSE and the namespace is TOKEN.
Section/Fields

tokenid
merchantreference

Type/Format

Description

Decimal
String

cardschemename

String

Unique identifier for registered PAN
Merchant can add a reference to
cross reference responses relating
to the same transaction
Returns the card scheme name for
the card registered within the
request



11.2.5. Token Registration Response (TKI2) – Failure
Should the TKI2 token registration request fail, the following message is returned.
The Message Type is TOKENRESPONSE and the namespace is TOKEN.
Section/Fields

merchantreference

Type/Format

Description

String

errorcode

Integer

errormsg

String

Merchant can add a reference to
cross reference responses relating
to the same transaction
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



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
87

Public

Version
5.28

12. Ukash Message Types
The Message Type for Ukash requests is UKASH and the namespace is UKASH.

12.1.

Ukash GetSettleAmount Request

Section/Fields

merchantreference

Type/Format

Description

String
Varchar(50)

requesttype

String
Varchar(50)
String
Char(20)

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

ukashlogin

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)



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

12.2.

Document name
Web Service Guide
Date
May 2011
Page number
88

Public

Version
5.28

Ukash PartSpendVoucher Request

Section/Fields

merchantreference

Type/Format

Description

String
Varchar(50)

requesttype

String
Varchar(50)
String
Char(20)

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

ukashlogin

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)

merchdatetime

String Char(19)

redemptiontype

String Char(1)/Char(2)

vouchercurrproductcode

String
Char(3)



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

12.3.

Document name
Web Service Guide
Date
May 2011
Page number
89

Public

Version
5.28

Ukash FullValueVoucher Request

Section/Fields

merchantreference

Type/Format

Description

String
Varchar(50)

requesttype

String
Varchar(50)
String
Char(20)

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

ukashlogin

ukashpassword

String
Char(20)

transactionid

String
Char(20)

brandid

String
Char(20)

vouchernumber

String
Char(19)/ Char(16)

vouchervalue

decimal

basecurr

String
Char(3)

merchdatetime

String Char(19)

redemptiontype

vouchercurrproductcode

String
Char(3)



© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

12.4.

Document name
Web Service Guide
Date
May 2011
Page number
90

Public

Version
5.28

Ukash PartSpendAccount Request

Section/Fields

merchantreference

Type/Format

Description

String
Varchar(50)

requesttype

String
Varchar(50)
String
Char(20)

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

ukashlogin

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)

merchdatetime

String Char(19)

redemptiontype

vouchercurrproductcode


String Char(3)

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

12.5.

Document name
Web Service Guide
Date
May 2011
Page number
91

Public

Version
5.28

Ukash FullSpendAccount Request

Section/Fields

merchantreference

Type/Format

Description

String
Varchar(50)

requesttype

String
Varchar(50)
String
Char(20)

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

ukashlogin

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)

mercdatetime

String Char(19)

redemptiontype

vouchercurrproductcode


String Char(3)

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

12.6.

Document name
Web Service Guide
Date
May 2011
Page number
92

Public

Version
5.28

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

Type/Format

Description

String
Varchar(50)

requesttype

String
Varchar(50)
String
Char(20)

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

ukashlogin

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)

merchdatetime

String Char(19)

redemptiontype

vouchercurrproductcode


String Char(3)

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

12.7.

Document name
Web Service Guide
Date
May 2011
Page number
93

Public

Version
5.28

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)

changeissuevouchernumber

String
Char(19)

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

errcode

Integer

errdescription

String
Char(255)

Document name
Web Service Guide
Date
May 2011
Page number
94

Public

Version
5.28

conversion took place. For full value
redemption, currency conversion may
occur to determine the settleAmount in the
base currency. For ticket price
redemption, 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



12.8.

Ukash Return Code List

Type of
Message
Transaction Status

12.9.
Code
1
2
3

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.

Ukash Transaction Type List

4
8
20

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

21

Account Subtract

22

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.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

12.10.

Document name
Web Service Guide
Date
May 2011
Page number
95

Public

Version
5.28

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

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

Login and Password
Login, Password and
BrandID
Currency Conversion Not
Supported
Currency Conversion
Error
General Error

Technical Error

Error Description

801
900
999

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
96

Phone
08444 828 200

12.11.

Public

Version
5.28

Ukash Product Codes

Region

Country

State

Currency

General
Issues
(020-200)

United
Kingdom
Europe

United
Kingdom
Europe

United
Kingdom
Europe

GBP
EUR

011

211

411

611

811

Europe

Poland

Poland

PLN

151

351

551

751

951

Europe

Austria

Austria

EUR

021

221

421

621

821

001

Cash
Back
Issues
(201-400)
201

Gambling
Restricted
(401-600)
401

Reserved
(601-800)

601

Reserved
(801-999)

801

Europe

Belgium

Belgium

EUR

022

222

422

622

822

Europe

Finland

Finland

EUR

023

223

423

623

823

Europe

France

France

EUR

024

224

424

624

824

Europe

Germany

Germany

EUR

025

225

425

625

825

Europe

Greece

Greece

EUR

026

226

426

626

826

Europe

Ireland

Ireland

EUR

027

227

427

627

827

Europe

Italy

Italy

EUR

028

228

428

628

828

Europe

Luxembourg

Luxembourg

EUR

029

229

429

629

829

Europe

Netherlands

Netherlands

EUR

030

230

430

630

830

Europe

Portugal

Portugal

EUR

031

231

431

631

831
811

Europe

Spain

Spain

EUR

011

211

411

611

Europe

Switzerland

Switzerland

CHF

033

233

433

633

833

Europe

Denmark

Denmark

DKK

034

234

434

634

834

Europe

Sweden

Sweden

SEK

035

235

435

635

835

Europe

Czech Republic

CZK

036

236

436

636

836

Europe

Norway

Czech
Republic
Norway

NOK

037

237

437

637

837

Europe

Romania

Romania

RON

038

238

438

638

838

Europe

Hungary

Hungary

HUF

039

239

439

639

839

Europe

Bulgaria

Bulgaria

BGL

040

240

440

640

840

Europe

Estonia

Estonia

EEK

041

241

441

641

841

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

USA

USA

USD

99

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
97

Phone
08444 828 200
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
North
America

Public

Version
5.28

USA

Iowa

USD

114

314

514

714

914

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

Maryland

USD

119

319

519

719

919

USA

USD

120

320

520

720

920

USA

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

Nevada

USD

127

327

527

727

927

USA

USD

128

328

528

728

928

USA

New
Hampshire
New Jersey

USD

129

329

529

729

929

USA

New Mexico

USD

130

330

530

730

930

USA

New York

USD

131

331

531

731

931

USA

USD

132

332

532

732

932

USA

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

Rhode Island

USD

138

338

538

738

938

USA

USD

139

339

539

739

939

USD

140

340

540

740

940

USA

South
Carolina
South
Dakota
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

USA

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
98

Phone
08444 828 200
South
America
North
America
Africa

Public

Version
5.28

Argentina

Argentina

ARS

152

352

552

752

952

Canada

Canada

CAD

153

353

553

753

953

South Africa

South Africa

ZAR

150

350

550

750

950

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
99

Public

Version
5.28

13. Troubleshooting
This section has been included in the manual to provide integrators with information to help
resolve any issues.

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





© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

13.2.

Document name
Web Service Guide
Date
May 2011
Page number
100

Public

Version
5.28

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
101

Public

Version
5.28

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
Perform a normal transaction

Description/Reasoning
Ensure solution processes transactions correctly

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

Process a transaction where the
response is comms down
(value ends in 7p)

A situation may arise whereby a response of ‘Comms
Down’ maybe returned by the service. This must be catered
for by the integration.

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

This will ensure that the CV2 field allows entry of up to 4

PASS / FAIL

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
102

Public

Version
5.28

card (if applicable)

digits, which is a requirement for processing AMEX cards.
Please note that AMEX cards do now support 3 digit CSC
values

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:
i)

‘Matched’ – 10;ME156LH

ii)

‘Partial Match’ – 11;ME156LH

iii)

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

PASS / FAIL
PASS / FAIL

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

PASS / FAIL

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
103

Phone
08444 828 200

Public

Version
5.28

APPENDIX B – Currency Code ISO 4217
Currency
Afghani
Algerian dinar
Argentine peso
Armenian dram
Aruban guilder
Australian dollar

Code
AFN
DZD
ARS
AMD
AWG
AUD

Num
971
012
032
051
533
036

Azerbaijanian manat
Bahamian dollar
Bahraini dinar
Baht
Balboa
Bangladeshi taka
Barbados dollar
Belarusian ruble
Belize dollar
Bermudian dollar (customarily
known as Bermuda dollar)
Bolivian Mvdol (funds code)
Boliviano
Brazilian real
Brunei dollar
Bulgarian lev
Burundian franc
Canadian dollar
Cape Verde escudo
Cayman Islands dollar
Cedi
CFA Franc BCEAO

AZN
BSD
BHD
THB
PAB
BDT
BBD
BYR
BZD
BMD

944
044
048
764
590
050
052
974
084
060

BOV
BOB
BRL
BND
BGN
BIF
CAD
CVE
KYD
GHS
XOF

984
068
986
096
975
108
124
132
136
936
952

CFA franc BEAC

XAF

950

CFP franc
Chilean peso
Chinese Yuan
Code reserved for testing
purposes
Colombian peso
Comoro franc
Convertible marks
Cordoba oro
Costa Rican colon
Croatian kuna
Cuban convertible peso
Cuban peso
Czech Koruna
Dalasi
Danish krone
Denar
Djibouti franc
Dobra
Dominican peso
East Caribbean dollar

XPF
CLP
CNY
XTS

953
152
156
963

COP
KMF
BAM
NIO
CRC
HRK
CUC
CUP
CZK
GMD
DKK
MKD
DJF
STD
DOP
XCD

170
174
977
558
188
191
931
192
203
270
208
807
262
678
214
951

Egyptian pound
Ethiopian birr
Euro

EGP
ETB
EUR

818
230
978

Locations using this currency
Afghanistan
Algeria
Argentina
Armenia
Aruba
Australia, Australian Antarctic Territory, Christmas Island,
Cocos (Keeling) Islands, Heard and McDonald Islands,
Kiribati, Nauru, Norfolk Island, Tuvalu
Azerbaijan
Bahamas
Bahrain
Thailand
Panama
Bangladesh
Barbados
Belarus
Belize
Bermuda
Bolivia
Bolivia
Brazil
Brunei, Singapore
Bulgaria
Burundi
Canada
Cape Verde
Cayman Islands
Ghana
Benin, Burkina Faso, Côte d'Ivoire, Guinea-Bissau, Mali,
Niger, Senegal, Togo
Cameroon, Central African Republic, Congo, Chad,
Equatorial Guinea, Gabon
French Polynesia, New Caledonia, Wallis and Futuna
Chile
China (Mainland)

Colombia
Comoros
Bosnia and Herzegovina
Nicaragua
Costa Rica
Croatia
Cuba
Cuba
Czech Republic
Gambia
Denmark, Faroe Islands, Greenland
Macedonia
Djibouti
São Tomé and Príncipe
Dominican Republic
Anguilla, Antigua and Barbuda, Dominica, Grenada,
Montserrat, Saint Kitts and Nevis, Saint Lucia, Saint
Vincent and the Grenadines
Egypt
Ethiopia
Austria, Belgium, Cyprus, Finland, France, Germany,
Greece, Ireland, Italy, Luxembourg, Malta, Netherlands,

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
104

Public

Version
5.28

Portugal, Slovakia, Slovenia, Spain, Andorra, Kosovo,
Monaco, Montenegro, San Marino, Vatican
European Composite Unit
(EURCO) (bond market unit)
European Monetary Unit
(E.M.U.-6) (bond market unit)
European Unit of Account 17
(E.U.A.-17) (bond market unit)
European Unit of Account 9
(E.U.A.-9) (bond market unit)
Falkland Islands pound
Fiji dollar
Forint
Franc Congolais
Gibraltar pound
Gold (one troy ounce)
Guarani
Guinea franc
Guyana dollar
Haiti gourde
Hong Kong dollar
Hryvnia
Iceland krona
Indian rupee
Iranian rial
Iraqi dinar
Israeli new sheqel
Jamaican dollar
Japanese yen
Jordanian dinar
Kenyan shilling
Kina
Kip
Kroon
Kuwaiti dinar
Kwacha
Kwacha
Kwanza
Kyat
Lari
Latvian lats
Lebanese pound
Lek
Lempira
Leone
Lesotho loti
Liberian dollar
Libyan dinar
Lilangeni
Lithuanian litas
Malagasy ariary
Malaysian ringgit
Manat
Mauritius rupee
Metical
Mexican peso
Mexican Unidad de Inversion
(UDI) (funds code)
Moldovan leu
Moroccan dirham
Naira
Nakfa
Namibian dollar
Nepalese rupee

XBA

955

XBB

956

XBD

958

XBC

957

FKP
FJD
HUF
CDF
GIP
XAU
PYG
GNF
GYD
HTG
HKD
UAH
ISK
INR
IRR
IQD
ILS
JMD
JPY
JOD
KES
PGK
LAK
EEK
KWD
MWK
ZMK
AOA
MMK
GEL
LVL
LBP
ALL
HNL
SLL
LSL
LRD
LYD
SZL
LTL
MGA
MYR
TMT
MUR
MZN
MXN
MXV

238
242
348
976
292
959
600
324
328
332
344
980
352
356
364
368
376
388
392
400
404
598
418
233
414
454
894
973
104
981
428
422
008
340
694
426
430
434
748
440
969
458
934
480
943
484
979

Paraguay
Guinea
Guyana
Haiti
Hong Kong Special Administrative Region
Ukraine
Iceland
Bhutan, India
Iran
Iraq
Israel
Jamaica
Japan
Jordan
Kenya
Papua New Guinea
Laos
Estonia
Kuwait
Malawi
Zambia
Angola
Myanmar
Georgia
Latvia
Lebanon
Albania
Honduras
Sierra Leone
Lesotho
Liberia
Libya
Swaziland
Lithuania
Madagascar
Malaysia
Turkmenistan
Mauritius
Mozambique
Mexico
Mexico

MDL
MAD
NGN
ERN
NAD
NPR

498
504
566
232
516
524

Moldova
Morocco, Western Sahara
Nigeria
Eritrea
Namibia
Nepal

Falkland Islands
Fiji
Hungary
Democratic Republic of Congo
Gibraltar

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
105

Phone
08444 828 200

Netherlands Antillean guilder
New Taiwan dollar

ANG
TWD

532
901

New Zealand dollar
Ngultrum
No currency
North Korean won
Norwegian krone
Nuevo sol
Ouguiya
Pa'anga
Pakistan rupee
Palladium (one troy ounce)
Pataca
Peso Uruguayo
Philippine peso
Platinum (one troy ounce)
Pound sterling

NZD
BTN
XXX
KPW
NOK
PEN
MRO
TOP
PKR
XPD
MOP
UYU
PHP
XPT
GBP

554
064
999
408
578
604
478
776
586
964
446
858
608
962
826

Pula
Qatari rial
Quetzal
Rial Omani
Riel
Romanian new leu
Rufiyaa
Rupiah
Russian rouble
Rwanda franc
Saint Helena pound
Samoan tala
Saudi riyal
Serbian dinar
Seychelles rupee
Silver (one troy ounce)
Singapore dollar
Solomon Islands dollar
Som
Somali shilling
Somoni
South African rand
South Korean won
Special Drawing Rights
Sri Lanka rupee
Sudanese pound
Surinam dollar
Swedish krona/kronor
Swiss franc
Syrian pound
Tanzanian shilling
Tenge
Trinidad and Tobago dollar
Tugrik
Tunisian dinar
Turkish lira
Uganda shilling
UIC franc (special settlement
currency)
Unidad de Fomento (funds
code)
Unidad de Valor Real
United Arab Emirates dirham

BWP
QAR
GTQ
OMR
KHR
RON
MVR
IDR
RUB
RWF
SHP
WST
SAR
RSD
SCR
XAG
SGD
SBD
KGS
SOS
TJS
ZAR
KRW
XDR
LKR
SDG
SRD
SEK
CHF
SYP
TZS
KZT
TTD
MNT
TND
TRY
UGX
XFU

072
634
320
512
116
946
462
360
643
646
654
882
682
941
690
961
702
090
417
706
972
710
410
960
144
938
968
752
756
760
834
398
780
496
788
949
800
Nil

Singapore, Brunei
Solomon Islands
Kyrgyzstan
Somalia
Tajikistan
South Africa
South Korea
International Monetary Fund
Sri Lanka
Sudan
Suriname
Sweden
Switzerland, Liechtenstein
Syria
Tanzania
Kazakhstan
Trinidad and Tobago
Mongolia
Tunisia
Turkey, Northern Cyprus
Uganda
International Union of Railways

CLF

990

Chile

COU
AED

970
784

Colombia
United Arab Emirates

Public

Version
5.28

Netherlands Antilles
Taiwan and other islands that are under the effective
control of the Republic of China (ROC)
Cook Islands, New Zealand, Niue, Pitcairn, Tokelau
Bhutan
North Korea
Norway, Bouvet Island, Queen Maud Land, Peter I Island
Peru
Mauritania
Tonga
Pakistan
Macau Special Administrative Region
Uruguay
Philippines
United Kingdom, Crown Dependencies (the Isle of Man and
the Channel Islands), certain British Overseas Territories
(South Georgia and the South Sandwich Islands, British
Antarctic Territory and British Indian Ocean Territory)
Botswana
Qatar
Guatemala
Oman
Cambodia
Romania
Maldives
Indonesia
Russia, Abkhazia, South Ossetia
Rwanda
Saint Helena
Samoa
Saudi Arabia
Serbia
Seychelles

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
106

Phone
08444 828 200

United States dollar (next day)
(funds code)
United States dollar (same day)
[who?]
(funds code) (one source
claims it is no longer used, but
it is still on the ISO 4217-MA
list)
US dollar

Uzbekistan som
Vatu
Venezuelan bolívar fuerte
Vietnamese đồng
WIR euro (complementary
currency)
WIR franc (complementary
currency)
Yemeni rial
Zimbabwe dollar
Złoty

Public

Version
5.28

USN

997

United States

USS

998

United States

USD

840

UZS
VUV
VEF
VND
CHE

860
548
937
704
947

American Samoa, British Indian Ocean Territory, Ecuador,
El Salvador, Guam, Haiti, Marshall Islands, Micronesia,
Northern Mariana Islands, Palau, Panama, Puerto Rico,
Timor-Leste, Turks and Caicos Islands, United States,
Virgin Islands, Bermuda (as well as Bermudian Dollar)
Uzbekistan
Vanuatu
Venezuela
Vietnam
Switzerland

CHW

948

Switzerland

YER
ZWL
PLN

886
932
985

Yemen
Zimbabwe
Poland

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
107

Public

Version
5.28

APPENDIX C – Country Codes ISO 3166
Official country names used by the ISO 3166/MA
Afghanistan
Åland Islands
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 Herzegovina
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, Democratic Republic of the
Cook Islands
Costa Rica
Côte d'Ivoire
Croatia
Cuba
Cyprus
Czech Republic
Denmark
Djibouti

Numeric
004
248
008
012
016
020
024
660
010
028
032
051
533
036
040
031
044
048
050
052
112
056
084
204
060
064
068
070
072
074
076
086
096
100
854
108
116
120
124
132
136
140
148
152
156
162
166
170
174
178
180
184
188
384
191
192
196
203
208
262

Alpha-3
AFG
ALA
ALB
DZA
ASM
AND
AGO
AIA
ATA
ATG
ARG
ARM
ABW
AUS
AUT
AZE
BHS
BHR
BGD
BRB
BLR
BEL
BLZ
BEN
BMU
BTN
BOL
BIH
BWA
BVT
BRA
IOT
BRN
BGR
BFA
BDI
KHM
CMR
CAN
CPV
CYM
CAF
TCD
CHL
CHN
CXR
CCK
COL
COM
COG
COD
COK
CRI
CIV
HRV
CUB
CYP
CZE
DNK
DJI

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Alpha-2
AF
AX
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
HR
CU
CY
CZ
DK
DJ

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
108

Phone
08444 828 200

Dominica
Dominican Republic
Ecuador
Egypt
El Salvador
Equatorial Guinea
Eritrea
Estonia
Ethiopia
Falkland Islands (Malvinas)
Faroe Islands
Fiji
Finland
France
French Guiana
French Polynesia
French Southern Territories
Gabon
Gambia
Georgia
Germany
Ghana
Gibraltar
Greece
Greenland
Grenada
Guadeloupe
Guam
Guatemala
Guernsey
Guinea
Guinea-Bissau
Guyana
Haiti
Heard Island and McDonald Islands
Holy See (Vatican City State)
Honduras
Hong Kong
Hungary
Iceland
India
Indonesia
Iran, Islamic Republic of
Iraq
Ireland
Isle of Man
Israel
Italy
Jamaica
Japan
Jersey
Jordan
Kazakhstan
Kenya
Kiribati
Korea, Democratic People's Republic of
Korea, Republic of
Kuwait
Kyrgyzstan
Lao People's Democratic Republic
Latvia
Lebanon
Lesotho
Liberia

212
214
218
818
222
226
232
233
231
238
234
242
246
250
254
258
260
266
270
268
276
288
292
300
304
308
312
316
320
831
324
624
328
332
334
336
340
344
348
352
356
360
364
368
372
833
376
380
388
392
832
400
398
404
296
408
410
414
417
418
428
422
426
430

DMA
DOM
ECU
EGY
SLV
GNQ
ERI
EST
ETH
FLK
FRO
FJI
FIN
FRA
GUF
PYF
ATF
GAB
GMB
GEO
DEU
GHA
GIB
GRC
GRL
GRD
GLP
GUM
GTM
GGY
GIN
GNB
GUY
HTI
HMD
VAT
HND
HKG
HUN
ISL
IND
IDN
IRN
IRQ
IRL
IMN
ISR
ITA
JAM
JPN
JEY
JOR
KAZ
KEN
KIR
PRK
KOR
KWT
KGZ
LAO
LVA
LBN
LSO
LBR

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Public

Version
5.28

DM
DO
EC
EG
SV
GQ
ER
EE
ET
FK
FO
FJ
FI
FR
GF
PF
TF
GA
GM
GE
DE
GH
GI
GR
GL
GD
GP
GU
GT
GG
GN
GW
GY
HT
HM
VA
HN
HK
HU
IS
IN
ID
IR
IQ
IE
IM
IL
IT
JM
JP
JE
JO
KZ
KE
KI
KP
KR
KW
KG
LA
LV
LB
LS
LR

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
109

Phone
08444 828 200

Libyan Arab Jamahiriya
Liechtenstein
Lithuania
Luxembourg
Macao
Macedonia, the former Yugoslav Republic of
Madagascar
Malawi
Malaysia
Maldives
Mali
Malta
Marshall Islands
Martinique
Mauritania
Mauritius
Mayotte
Mexico
Micronesia, Federated States of
Moldova, Republic of
Monaco
Mongolia
Montenegro
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
Palestinian Territory, Occupied
Panama
Papua New Guinea
Paraguay
Peru
Philippines
Pitcairn
Poland
Portugal
Puerto Rico
Qatar
Réunion
Romania
Russian Federation
Rwanda
Saint Helena
Saint Kitts and Nevis
Saint Lucia
Saint Pierre and Miquelon
Saint Vincent and the Grenadines

434
438
440
442
446
807
450
454
458
462
466
470
584
474
478
480
175
484
583
498
492
496
499
500
504
508
104
516
520
524
528
530
540
554
558
562
566
570
574
580
578
512
586
585
275
591
598
600
604
608
612
616
620
630
634
638
642
643
646
654
659
662
666
670

LBY
LIE
LTU
LUX
MAC
MKD
MDG
MWI
MYS
MDV
MLI
MLT
MHL
MTQ
MRT
MUS
MYT
MEX
FSM
MDA
MCO
MNG
MNE
MSR
MAR
MOZ
MMR
NAM
NRU
NPL
NLD
ANT
NCL
NZL
NIC
NER
NGA
NIU
NFK
MNP
NOR
OMN
PAK
PLW
PSE
PAN
PNG
PRY
PER
PHL
PCN
POL
PRT
PRI
QAT
REU
ROU
RUS
RWA
SHN
KNA
LCA
SPM
VCT

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Public

Version
5.28

LY
LI
LT
LU
MO
MK
MG
MW
MY
MV
ML
MT
MH
MQ
MR
MU
YT
MX
FM
MD
MC
MN
ME
MS
MA
MZ
MM
NA
NR
NP
NL
AN
NC
NZ
NI
NE
NG
NU
NF
MP
NO
OM
PK
PW
PS
PA
PG
PY
PE
PH
PN
PL
PT
PR
QA
RE
RO
RU
RW
SH
KN
LC
PM
VC

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
110

Phone
08444 828 200

Samoa
San Marino
São Tomé and Príncipe
Saudi Arabia
Senegal
Serbia
Seychelles
Sierra Leone
Singapore
Slovakia
Slovenia
Solomon Islands
Somalia
South Africa
South Georgia and the South Sandwich Islands
Spain
Sri Lanka
Sudan
Suriname
Svalbard and Jan Mayen
Swaziland
Sweden
Switzerland
Syrian Arab Republic
Taiwan, Province of China
Tajikistan
Tanzania, United Republic of
Thailand
Timor-Leste
Togo
Tokelau
Tonga
Trinidad and Tobago
Tunisia
Turkey
Turkmenistan
Turks and Caicos Islands
Tuvalu
Uganda
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
Western Sahara
Yemen
Zambia
Zimbabwe

882
674
678
682
686
688
690
694
702
703
705
090
706
710
239
724
144
736
740
744
748
752
756
760
158
762
834
764
626
768
772
776
780
788
792
795
796
798
800
804
784
826
840
581
858
860
548
862
704
092
850
876
732
887
894
716

WSM
SMR
STP
SAU
SEN
SRB
SYC
SLE
SGP
SVK
SVN
SLB
SOM
ZAF
SGS
ESP
LKA
SDN
SUR
SJM
SWZ
SWE
CHE
SYR
TWN
TJK
TZA
THA
TLS
TGO
TKL
TON
TTO
TUN
TUR
TKM
TCA
TUV
UGA
UKR
ARE
GBR
USA
UMI
URY
UZB
VUT
VEN
VNM
VGB
VIR
WLF
ESH
YEM
ZMB
ZWE

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

WS
SM
ST
SA
SN
RS
SC
SL
SG
SK
SI
SB
SO
ZA
GS
ES
LK
SD
SR
SJ
SZ
SE
CH
SY
TW
TJ
TZ
TH
TL
TG
TK
TO
TT
TN
TR
TM
TC
TV
UG
UA
AE
GB
US
UM
UY
UZ
VU
VE
VN
VG
VI
WF
EH
YE
ZM
ZW

Public

Version
5.28

Author
ML

Document name
Web Service Guide
Date
May 2011
Page number
111

Phone
08444 828 200

Public

Version
5.28

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

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

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

9

2

X2
4

18

9

1

X2
2

18

2

3

X2
1

4

1

2

X2
3

2

3

1

X2
2

6

2
X2

1

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
112

Public

Version
5.28

APPENDIX E – Commidea Error Codes
Error
Code
0001
0002

General Description

Additional Technical Description
(if required)

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

Expired card

0010

Card not yet valid

0011

Invalid card service code

The Track2 service code is invalid.

0012
0013

File or XML missing or wrong
format
File permanently locked

0014

Out of memory

0015

Account number does not
exist

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.

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

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
mis-swiped).
The length of the PAN is incorrect
for the given card scheme.
The pen-ultimate check digit is
invalid.

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.

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
113

Public

Version
5.28

· WinTI EFTChans within the registry
has enough available channels set
(Socket mode only).
0027

System error (Track2 check
module has not been loaded)

0028
0029

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

0030

Unspecified error

Unspecified error

0031
0032
0033

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

0034

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

Purchase/refund value bad or
missing
Cash-back value bad or
missing
Auth code value bad or
missing
Cheque account number value
bad or missing
Invalid cheque sort code

0041
0042
0043
0044
0045
0046
0047

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

0048

Unexpected CPC data

Transaction store unavailable

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

Re-enter transaction
Check Live Store.
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

The EFT serial number is either
invalid or missing in the .Cnf file
Purchasing card invoice data has
been presented for a non-

Re-enter cheque type
Re create *.cnf
Re-enter transaction without invoice
data or prompt for a valid Purchasing

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

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)

0052

0053

Transaction data supplied in
post conf rev not consistent
with store (reserved for future
use)
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

0065

Invalid/missing bank account
number
Token does not exist or invalid
token for this merchant system
Unexpected / Invalid
Authorisation Response
Invalid voucher target type

0066

Invalid Refund Pin

0067

Report Not Supported

0068
0069
0070

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

0062
0064

0071
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

Document name
Web Service Guide
Date
May 2011
Page number
114

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 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
Merchant Details passed in XML
Gateway are Invalid.
The Mobile Number format passed
is incorrect
The bank account number within
the supplied T-Record is incorrect.
The Token ID supplied is incorrect
or invalid for the merchant system
Unexpected / Invalid Authorisation
Response from M-Voucher Host
The Target Voucher Type is invalid
(M-Voucher)
The refund pin entered is invalid

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

Public

Version
5.28

Card

Reverse transaction manually (as cash
is involved)

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 mobile
number supplied.
Check the bank number being passed
and re-enter as necessary.
Check the Token ID is correct and for
use with the current merchant system
Please contact Commidea Support
Please contact Commidea Support
Please enter the correct refund pin if
continues to fail, 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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
115

0077

Cancel Failed - In Payment on
xxx.xxx.xxx.xxx

0078
0079

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

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.

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

0098

Unknown Client
Unknown Transaction Source
Unknown Message

0099

Transaction/Bill Cancelled

0100

Pin Bypass Failed

0101

Invalid Terminal Country Code'

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

The EMV Terminal Type passed is
invalid
The message type received by
server side is not recognised
General Commidea Enqueueing

There is a problem with the Card
The authorisation process has
been interrupted or is not
responding.
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

Public

Version
5.28

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

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

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200
Error
The transaction confirmation has
errored.

0107

Transaction Confirmation Error

0108

Payer Auth Error

The Payer Auth has encountered
an error.

0109

Ukash Auth Error

The Ukash transaction has
encountered an error.

0110

Encryption Failure

0111
0112

Unable to build Auxillary Data
Record
Transaction rejection 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

0113

Unknown Terminal

0114
0115

Invalid Download Type
Terminal Registration Failed

0116

Terminal has been deactivated

0117

Comms down

0118

M-Voucher Service
Unavailable

0119

Barclays Bonus Service
Unavailable

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

0126

Token has no Txn Type
Permissions
Invalid Token expiration date

0122
0123

0127

Document name
Web Service Guide
Date
May 2011
Page number
116

The terminal\PTID is not
recognised
The download type is invalid
The attempt to register the terminal
has failed
The terminal has been marked as
deactivated.
Acquirer has been blocked in the
database as acquirer is not
processing any authorisations
(comms down)
This is when the terminal is in
offline mode at the start of a
transaction, and cannot connect to
the hosted server to allow MVoucher
Error response when Comms
failure between server application
and XLS Host experienced.
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
The Token Registration has no
transaction permissions
The token expiration date provided
is invalid
The processing database that is
passed in the client header is either
missing or invalid.

0128

ProcessingDB Missing or
Invalid

0129

Invalid Original Barclays Gift
Transaction ID
Invalid Barclays Gift
Configuration

The Original Gift Transaction ID
provided is invalid
Your Barclays Gift Configuration is
invalid

0132

Barclays Gift Service
Unavailable
Merchant Reference Required

0133

Account On File Not Allowed

The Barclays Gift Service is
temporarily unavailable
Your current configuration requires
a Merchant Reference to be
passed.
Terminal is operating in offline
mode

0130

0131

Public

Version
5.28

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 contact Commidea Support
Please retry the registration if it
continues to fail, please contact
Commidea Support
Please contact Commidea Support
Please contact Commidea Support

Please contact Commidea Support

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
Commidea Support
Please resubmit the token request with
transaction permissions enabled
Please resubmit the token request with
a valid token expiration date
Please check that the message you
are sending has the processing
database set in the client header and
that it is valid (as per the
transaction\payer auth request)
Please check the Original Transaction
ID and try again.
Please check the configuration and
download to the terminal. If the
problem continues please contact
support.
Please contact Commidea Support
Please re-submit the transaction with
the Merchant Reference populated.
Please check that the terminal is online
Please check the configuration of the
account

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200

Document name
Web Service Guide
Date
May 2011
Page number
117

Account does not allow Account
On file CNP transactions
EFT transaction capture method
does not support registration of
details for Account On File
processing
The card scheme doesn't allow
processing of keyed card numbers
A timeout has occurred whilst
waiting for the card and
Transactions has been cancelled
The card presented does not
support cash advance and needs
to be represented as a purchase
txn.
Check Gratuity Value
The application has timed out
waiting for a Barclays Gift response

0134

Card not allowed to be keyed

0135

Timeout Waiting for Card

0137

Present Cash Advance
Transaction As Purchase

0138
0139

Gratuity Value Incorrect
Transaction Timeout

0140

Schedule Payment registration
failed.

The scheduled payment
registration has failed.

0141

Ocius migration failed

0150

Invalid PayPoint Configuration

0151

No PayPoint Accounts

0152

PayPoint Service Unavailable

0153

PayPoint Download Required

The Ocius migration failed on the
database because the migration
has not been setup / enabled
The PayPoint configuration that
you have setup is invalid.
There are no PayPoint accounts
available.
The PayPoint service is currently
unavailable
A PayPoint download is required

0154

PayPoint Account Extraction
Failed

PayPoint account file extraction
has failed.

0155

PayPoint Transaction Type
Not Allowed
Invalid PayPoint TopUp Type

The PayPoint transaction type
provide is not allowed
The PayPoint TopUp type provided
is invalid
The PayPoint Service Provider
provided is invalid
The PayPoint Scheme provided is
invalid
The PayPoint Scheme Option
provided is invalid
The PayPoint Amount provided is
invalid
The PinPad is currently unavailable

0156
0157
0158
0159

Invalid PayPoint Service
Provider
Invalid PayPoint Scheme

0160

Invalid PayPoint Scheme
Option
Invalid PayPoint Amount

0161

No PinPad Available

0189

Invalid refund password

0999

Token Server Error

1000
1001

Generic Error
Merchant Supplied Bad Data

1002
1003

Bad Source URL
Attempting to use a TokenID
and a PAN at the same time
Curl Error
Couldn't Extract Error Code
from Response
Failed to Retrieve System
Config
Unusual Data Supplied
(Possible Attack)

1004
1005
1006
1007

An invalid refund password has
been supplied during the
transaction, and was rejected by
the database
Start date or issue data supplied is
incorrect or missing
Generic Capture Error
The information supplied in the
post is incorrect
The source URL is unrecognised
A TokenID and PAN were received
for the same transaction
Communication Error
The error code returned could not
be extracted
PayPage has failed to retrieve your
System Configuration
The data that has been supplied is
suspicious

Public

Version
5.28

Check the transaction details that you
have passed.

Use another card, or cancel the
transaction
Reprocess Transaction.

Reprocess Transaction as a purchase

Check Gratuity Value
Please check whether the gift request
has gone through and if necessary
please try again.
Please attempt to re-register the
scheduled payment or contact
Commidea Support
Contact Commidea to arrange for
migration
Please contact Commidea Support
Please contact Commidea Support
Please retry the payment or contact
Commidea support
Please perform a configuration file
update to your terminal
Please retry the download if it
continues to fail please contact
Commidea Support
Please check the Transaction Type
supplied and correct
Please check the TopUp Type
supplied and correct
Please check the Service Provider
supplied and correct
Please check the Scheme supplied
and correct
Please check the Scheme Option
supplied and correct
Please check the Amount supplied and
correct
Please check the PinPad is available
for use, please contact Commidea
Support if the problem persists.
Please contact Commidea Support

Please check you are passing the
appropriate required fields
Please contact Commidea Support
Please check the data that you are
sending and retry.
Please contact Commidea Support
Please check the data that is being
passed
Please contact Commidea Support
Please contact Commidea Support
Please contact Commidea Support
Please check the data that you are
sending and contact Commidea
support

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.

Author
ML

Phone
08444 828 200
1008
1009
1010

Failed to Retrieve Session
Data
Failed to Create New Session

1012

Bad SessionID received from
end user
Bad PIN received from end
user
Session Finished

1013

Failed to extract PA Data

1014

Session Expired

1011

Document name
Web Service Guide
Date
May 2011
Page number
118

PayPage has failed to retrieve your
session data
PayPage has failed to create a new
session
The sessionID provided by the front
end is incorrect.
The PIN provided by the front end
is incorrect.
The session that you are trying to
use has already finished.
An error has occurred trying to
decrypt\extract the Payer Auth data
The session that you are trying to
use has expired.

Public

Version
5.28

Please retry the payment or contact
Commidea support
Please retry the payment or contact
Commidea support
Please check the data that you are
sending and retry.
Please check the data that you are
sending and retry.
Please retry the payment or contact
Commidea support
Please retry the payment or contact
Commidea support
Please retry the payment or contact
Commidea support

© 2011 COMMIDEA LTD
All rights reserved. Copying and/or redistribution of this information in whole
or in part without the express permission of Point International prohibited.



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
Tagged PDF                      : Yes
XMP Toolkit                     : Adobe XMP Core 4.0-c321 44.398116, Tue Aug 04 2009 14:24:39
Producer                        : Acrobat Distiller 8.2.6 (Windows)
Company                         : PresentationSupport
Source Modified                 : D:20110531082540
Create Date                     : 2011:05:31 09:26:51+01:00
Creator Tool                    : Acrobat PDFMaker 8.1 for Word
Modify Date                     : 2011:05:31 09:31:47+01:00
Metadata Date                   : 2011:05:31 09:31:47+01:00
Document ID                     : uuid:917e09f8-cea9-422e-b820-ce8a6d3ceb03
Instance ID                     : uuid:fd485994-c812-4ebc-9a40-e825a0943c90
Subject                         : 6
Format                          : application/pdf
Creator                         : michael.lovelock
Title                           : 
Page Count                      : 118
Page Layout                     : OneColumn
Author                          : michael.lovelock

EXIF Metadata provided by EXIF.tools