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 PDF.
Page Count: 118 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Web Service Guide
Integration Guide
Author: ML
Circulation: Public
Date: 31/03/2011
Author Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 2 5.28
Revision History
Ver. Name Date Comments
V5.28 ML May 2011 - Payer Authentication matrix updated
- ‘Resultdatetime’ string formatting corrected
- On-Hold/Release functionality documented
V5.27 ML Feb 2011 - Manual format updated
V5.26 ML Feb 2011 - 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 3 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 4 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 5 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 6 5.28
12.9. 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 7 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 8 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 which is a complex type (having multiple fields, e.g. SystemID,
SystemGUID)
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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 9 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 10 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 Expected Outcome
.00 Accepted, 789DE
.02 Voice referred
.05 Declined
.07 Communications Down
.08 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 CVCRESULT
<null> 0 – Not Provided
555 1 – Not Checked
000 2 – Matched
111 4 – Not Matched
Address Line 1 Value AD1AVSRESULT
<null> 0 – Not Provided
55 1 – Not Checked
10 2 – Matched
11 4 – Not Matched
12 8 – Partial Match
Post Code Value PCAVSRESULT
<null> 0 – Not Provided
ME555LH or 555 1 – Not Checked
ME156LH or 156 2 – Matched
ME111LH or 111 4 – Not Matched
ME122LH or 122 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 11 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 12 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 13 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 14 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 15 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 16 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 17 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 18 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 <customerspecifichash> 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 19 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 mark-
up. Here is an example, where using a reference of “Chip&PIN”:
<![CDATA[<merchantreference>Chip&PIN</merchantreference>]]>
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
<message>
MsgType String M Type of message
MsgData String M Data
ClientHeade
r
ClientHeader M ClientHeader information
</message>
4.2. ClientHeader
The clientheader is used to validate requests and direct them to the correct server:
Section/Fields Type/Format Mandatory
/ Optional
Description
<ClientHeader>
SystemID Decimal M Allocated ID
SystemGUID String M Allocated GUID
Passcode String M Allocated Passcode
ProcessingDB String M (for Confirmation Request
and Rejection Request) 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)
SendAttempt Integer M 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 20 5.28
days based on acquirer
authorisation expiries
CDATAWrapping Boolean O 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
</ClientHeader>
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 Type/Format Description
<Error>
Code Integer Code indicating error type
MsgTxt String Description of error
<
/
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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 21 5.28
5. Transactions
5.1. Transaction Process
To process a transaction using XML V4 the following procedure is used:
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
<transactionrequest>
merchantreference String O Merchant can add a reference to cross
reference responses relating to the same
transaction
accountid Decimal M Account reference number, supplied by
Commidea
accountpasscode String M Account passcode, supplied by Commidea
txntype String M 01 – Purchase
02 – Refund
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
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 22 5.28
04 – Cash Advance
05 – Purchase with cash back (PWCB)
06 – Continuous Authority
transactioncurrencycode String M This is the three digit currency code
(numeric).
terminalcountrycode String M In accordance with the numeric values
defined in ISO 3166 (see Appendix C)
apacsterminalcapabilities String M 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)
Integrators should check with
Implementations to confirm that they
have the correct capabilities.
capturemethod Integer M 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 E-
Commerce Order
processingidentifie
r
Integer M 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 23 5.28
tokenid Decimal O Token Identifier for token transaction
pan String C 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
issuenumbe
r
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.:
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)
cashback Decimal O 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.
gratuity Decimal O Additional value to add to total (e.g. service
tip)
authcode String O Only supplied for Offline transactions
transactiondatetime String O Date and time the transaction was started,
based on GMT (dd/mm/yyyy hh:mm:ss).
iccdata iccdata O Contains ICC data
vgisid String O 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 24 5.28
employeeid Decimal O Field used to add information on the
employee processing the transaction
payerauthauxiliarydata String C 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 non-
supporting card schemes. Capture
methods such as ICC will not require
Payer Auth auxiliary data to be supplied
vgistransaction Boolean C 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
</transactionrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 25 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
<iccdata>
emvterminalcapabilities String M The terminal capabilities as
defined in the EMV specifications.
emvterminaltype String M Terminal type/Currency indicator
S = Sterling
E = Euro
0 = Unspecified terminal
capabilities –
S
1 = ICC reader only – S
2 = Magnetic stripe only – S
3 = ICC/Magnetic stripe – S
4 = No card reader – S
5 = Unspecified terminal
capabilities –
E
6 = ICC reader only – E
7 = Magnetic stripe only – E
8 = ICC/Magnetic stripe – E
9 = No card reader – E
reasononlinecode String M In the provisional European
Standard (prENV 1750) the On-
line reason codes are four digits
in the form 15XX for PoS type of
environment. As all PoS codes
begin 15 there is no need to send
this fixed value and therefore only
the XX as defined in the ENV
1750 need be transmitted.
Reason On-line will be used by
the acquirer to determine if stand-
in authorisation would be an
appropriate action for this
transaction. I.e. was it the ICC or
the CAD which required an on-
line authorisation.
arqc String M 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)
apppansequenceno String M Identifies and differentiates cards
with some PAN (ICC Card passes
this information)
aip String M Application Interchange Profile
(passed by ICC terminal)
atc String M Value of the last online
transaction (passed by ICC
terminal)
unpredictableno String M (passed by ICC terminal)
tv
r
String M 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 26 5.28
by Cardholder System (passed by
ICC terminal)
cryptotxntype String M 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
iad String M Present if provided by ICC in
GENERATE AC command
response (passed by ICC
terminal)
aid String M 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)
terminalapplicationversionnumbe
r
String M 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)
cardapplicationversionnumbe
r
String M Version number assigned by the
payment system for the
application on the IC card
(extracted from the IC Card Tag
9F 08)
cvm
r
String M 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)
cryptoinfodata String M Please see EMVECO Application
Specification Book 3 Page 16 for
breakdown (passed by ICC
terminal)
</iccdata>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 27 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 non-
supporting 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
<payerauthauxiliarydata>
authenticationstatus String 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
authenticationcavv String M Contains 28-byte Base-64 encoded
Cardholder Authentication Verification Value
(CAVV)
authenticationeci String M 2 digit Electronic Commerce Indicator (ECI)
value
atsdata String M Data to populate authorisation message
transactionid String M TransactionID should be populated with the
PayerAuthRequestID provided in the
PayerAuth EnrollmentCheck Response
</payerauthauxiliarydata>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 28 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
<confirmationrequest>
transactionid Decimal M TransactionID from ProcessTransaction
request
offlineauthcode String O AuthCode if transaction was authorised offline
gratuity Decimal O Additional value to add to total (e.g. service
tip)
transactioncertificate String M for ICC Transaction certificate from 2nd generate
arc String M for ICC Auth response code
applicatonusagecontrol String M for ICC Application usage control
tv
r
String M for ICC Terminal verification results
cid String M for ICC Cryptogram information data
tsi String M for ICC Transaction status information
iad String M for ICC Issuer Application Data
</confirmationrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 29 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
<rejectionrequest>
transactionid Decimal M TransactionID from ProcessTransaction
request
tokenid Decimal O Token identifier for token transaction
capturemethod Integer M 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
pan String C Card number (when card keyed).
Conditional as not required if TokenID
provided.
track2 String C Entire Track2 contents
(including start and end sentinels and LRC).
Conditional as not required if TokenID
provided.
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
</rejectionrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 30 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 Type/Format Description
<transactionresponse>
merchantreference String Merchant can add a reference to cross reference responses relating
to the same transaction
transactionid Decimal Transaction ID (unique only to the processing database utilised)
resultdatetimestring String Extended date and time string
( YYYY-MM-DDTHH:MM:SS.sss)
processingdb String This indicates the database used to processing the request.
errormsg String Error message
merchantnumbe
r
String Unique merchant number
tid String Terminal ID
schemename String Card scheme name
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
messagenumbe
r
String Transaction message number (equivalent of EFTSN from previous
versions of the Web Service)
authcode String 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
authmessage String Authorisation message
e.g. ‘RETAIN CARD’
vrtel String Telephone number to be called by the operator to seek manual
authorisation. Only supplied for referred transactions
txnresult String 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 31 5.28
APPROVED
AUTHORISED
AUTHONLY
For further information on the transaction results please see section
5.3.
pcavsresult Integer Postcode AVS result:
0 – Not provided*
1 – Not checked
2 – Matched
4 – Not matched
8 – Partial Match
*Default result when no details are provided
ad1avsresult Integer Address line 1 AVS result:
0 – Not provided*
1 – Not checked
2 – Matched
4 – Not matched
8 – Partial Match
*Default result when no details are provided
cvcresult Integer CVC result:
0 – Not provided*
1 – Not checked
2 – Matched
4 – Not matched
*Default result when no details are provided
arc String 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.
iadarc String Authorisation response cryptogram
iadoad String Optional additional data
isd String Issuer script data
authorisingentity Integer 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
vgisreference String 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
customerspecifichash String 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
</transactionresponse>
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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 32 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
<authmessage> 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 33 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:
Commidea
Server Directory
Server
Merchant System
Merchant decides whether to
proceed and process the
transaction
Use ACS URL to send the PAReq to
issuing bank. Include TermURL for
Bank to post PARes to afterwards
Issuing bank records
authentication result from
information customer provides
(including password)
Result posted back to TermUrl in
the form of a PARes message
Extract the PARes message and
request the Commidea
Authentication Check to validate
Customer directed to ACS
page to enter their password
Yes
No
Enrollment Check Request sent
to Commidea Commidea sends check onto
Visa / MasterCard Directory
Server to check for enrollment
Directory Server contacts
issuing bank to find out if
the card is enrolled
Enrollment Check returns result,
PAReq message, and ACS URL
Directory Server informs
Commidea if the card is
enrolled or not
Call Authentication Check, populating only
the PayerAuthID and enrolled properties of
the AuthenticationCheckRequest
Enrollment Check returns ‘N’
Order and cardholder data
captured
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 34 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. The cardholder creates an order on the system, and clicks the ‘Buy’ button, which sends
a post of the final buy page
ii. Create and send an Enrollment Check request, populating it with all the details from the
webpage order
iii. This is sent onto the Directory Server, which contacts the issuing bank and finds out if
the card is enrolled or not
iv. The Check Enrollment response is sent and if the card is enrolled contains:
a. <Enrolled>Y</Enrolled>
b. The PaReq message required to send to the issuing bank
c. Access Control Server (ACS) URL
If the card is not enrolled, proceed to step x.
v. Send the PaReq message to the bank to request authentication. To do this, create a
web page that only has hidden content, including a form that meets the following
requirements:
- The forms action is the ACS URL, which displays the issuing bank’s dialog
requesting the authentication password from the cardholder
- The form includes the required hidden field PaReq, the value of which was returned
to the merchant in the Enrollment Check response. It is necessary to remove any
White Space within this PaReq field otherwise this will cause errors when it is
returned to the bank.
- The form includes the required field TermUrl, the value of which is the location where
the merchant wants the bank to post the payment authentication response (PaRes)
message.
- The form must include the hidden field MD (merchant data); however, including a
value in this field is optional. The value has no meaning to the bank, but is
guaranteed to be returned without change. This allows the merchant to tag the
redirect with a reference which will be returned during the redirect.
- This page typically include JavaScript that automatically posts the form when the
page loads (onload script)
vi. Open this page in the cardholder’s web browser. Due to popup-blocking software, it is
recommended opening this in the main browser window. The cardholder’s web browser
displays the issuing bank’s authentication dialog, and enters their secret password for
the credit card.
vii. The issuing bank records the result of the authentication dialog with the cardholder and
sends it to the merchant, along with the transaction details, in a digitally signed PaRes
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 35 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.
viii. Extract the PaRes message from the form data and request the Commidea
Authentication Check to validate the contents of the PaRes message.
ix. Depending upon the result of the Authentication Check; the merchant can now decide
whether or not to proceed.
x. If the Enrollment Check indicated that the card was not enrolled, then call the
Authentication Check populating only the PayerAuthRequestID and setting
<Enrolled>N</Enrolled>within the AuthenticationCheckRequest.
If the card was enrolled and the merchant has now received the PaRes then populate
PayerAuthRequestID, set the request to <Enrolled>Y</Enrolled> and include the PaRes
message in the AuthenticationCheckRequest.
xi. Populate a Transaction Request with all the relevant details
xii. 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:
<Enrolled>Y</Enrolled>
<AuthenticationStatus>N</AuthenticationStatus>
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
<Enrolled>U</Enrolled> or <AuthenticationStatus>U</ AuthenticationStatus> 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:
<Enrolled>N</Enrolled>
<AuthenticationStatus>N</AuthenticationStatus>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 36 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 <Enrollment> 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 37 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 38 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
<payerauthenrollmentcheckrequest>
merchantreference String O Merchant can add a reference
to cross reference responses
relating to the same
transaction
mkaccountid Decimal M Account reference number,
supplied by Commidea
mkacquirerid Decimal M 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 39 5.28
23 – JCB
24 – AIB
merchantname String
Varchar(25) M 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
merchantcountrycode String
Varchar(50) M 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)
merchanturl String
Varchar(255) M This field contains the fully
qualified URL of the merchant
site
visamerchantbankid String
Varchar(50) C
(Only for Visa checks) 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
visamerchantnumber String
Varchar(50) C
(Only for Visa checks) 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
visamerchantpassword String
Varchar(50) C
(Only for Visa checks) The alphanumeric merchant
password is provided by the
acquirer
mcmmerchantbankid String
Varchar(50) C
(Only for MasterCard
/Maestro checks)
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
mcmmerchantnumber String
Varchar(50) C
(Only for MasterCard
/Maestro checks)
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
mcmmerchantpassword String
Varchar(50) C
(Only for MasterCard
/Maestro checks)
The alphanumeric merchant
password is provided by the
acquirer
tokenid Decimal C
Token identifier for token
transaction. If none to be
passed, ‘0’ to be used.
cardnumber String
Varchar(50) C 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 40 5.28
cardexpyear String
Char(2) C Card expiry date year YY e.g.
08
(not passed if token id
supplied)
cardexpmonth String
Char(2) C Card expiry date month MM
(not passed if token id
supplied)
currencycode String
Char(3) M 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)
currencyexponent String
Char(1 M No of decimal places in
currency field ie. GBP will be
2
browseracceptheader String
Varchar(255) O 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.
browseruseragentheader String
Varchar(255) O This field contains the exact
content of the HTTP user-
agent header as sent to the
merchant from the
cardholder's user agent. This
field is only required if the
cardholder's user agent
supplied a value.
transactionamount String
Varchar(50) M Amount to be authorised with
implied decimal point ie.
£10.00 is represented as
1000 and 0.10 is represented
as 10.
transactiondisplayamount String
Varchar(50) M 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
transactiondescription String
Varchar(50) O This field contains a
description of the goods or
services being purchased,
determined by the merchant.
</payerauthenrollmentcheckrequest>
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 Type/Format Description
<payerauthenrollmentcheckresponse>
merchantreference 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 41 5.28
same transaction
processingdb String This indicates the database to use for
processing a particular request. If left
blank the default database will be
used.
payerauthrequestid Decimal Unique Identifier
enrolled String
Char(1) Indicates if card is enrolled in the 3D
secure program.
acsurl String
Varchar(4096) Fully qualified URL of an Access
Control Server.
pareq String
Varchar(1000) This field will contain the entire XML
response packet from the Directory
Server.
errorcode Integer Error code defining the error
errordescription String
Varchar(1000) Description of the error
</payerauthenrollmentcheckresponse>
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
<payerauthauthenticationcheckrequest>
merchantreference String O Merchant can add a
reference to cross reference
responses relating to the
same transaction
payerauthrequestid Decimal M Unique Identifier returned
during
EnrollmentCheckResponse.
pares String C Compressed and encoded
Payer Authentication
Response message, returned
in response from Visa /
Mastercard
(Only included if received)
enrolled String M Indicates if the card was
enrolled – Y/N
</payerauthauthenticationcheckrequest>
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 Type/Format Description
<payerauthauthenticationcheckresponse>
merchantreference 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 42 5.28
© 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.
payerauthrequestid Decimal PayerAuth transaction identifier
authenticationstatus String 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.
authenticationcertificate String The certificate that signed the Payer
Authentication Response (PARes) message.
authenticationcavv String This property contains a 28-byte Base-64
encoded Cardholder Authentication Verification
Value (CAVV).
authenticationeci String Two digit Electronic Commerce Indicator (ECI)
value.
authenticationtime String 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".
atsdata String Additional transaction security data
errorcode Integer Error code defining the error
errordescription String Description of the error
processingdb String This indicates the database used for processing a
particular request
</payerauthauthenticationcheckresponse>
Author Document name
Public
ML Web Service Guide
Date
May 2011
Phone
08444 828 200
Page number Version
43 5.28
© 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.
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
MPI Authentication
A
PACS Authorisation Streamline Settlement RAG Status
Card Type
V
ERes PARes CAVV/AVV ECI ECI CAVV/AVV Trans ID
A
TSD Trans source Liability Shift
1 Visa 3D Y Y Yes 05 05 Yes Yes D0C100 12 Yes
2 Visa 3D Y A Yes 06 06 Yes Yes D0C200 13 Yes
3 Visa 3D N None None None None None None D0C200 13 Yes
4 Mcard 3D Y Y Yes 02 02 Yes Yes D09100 12 Yes
5 Mcard 3D Y A Yes 01 01 Yes Yes D09200 13 Yes
6 Mcard 3D N None None None None None None D09200 13 Yes
7 None 3D None None None None None None None 808000 14 No
8 Visa 3D U None None None None None None D0C400 14/13 No
9 Visa 3D Y U None None None None None D0C400 14/13 No
10 Mcard 3D U None None None None None None D09400 13 Yes
11 Mcard 3D Y U None None None None None D09400 13 Yes
12 Visa 3D Y N None None None None None None None None
13 Mcard 3D Y N None None None None None None None None
Key to VERes & PARes Codes:
Y (VERes) Perform a PARes
N (VERes) Issuer/BIN not participating
U (VERes) Authentication process did not complete correctly
Y (PARes) Cardholder enrolled and authenticated
A (PARes) Cardholder not enrolled
N (PARes) Cardholder enrolled, transaction not authenticated
U (PARes) Authentication process did not complete correctly
Author Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 44 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) = Merchant & Cardholder are registered
31 (Visa ECI 6) = Merchant is registered, but Cardholder isn't.
32 (Visa ECI 7) = Standard E-Commerce message
APACS 70-2
Section B.4.2 (page 85) Electronic Commerce Data Record Sub-type 01
APACS 70-3 G = Merchant & Cardholder registered
Section A.4 (page 93) H = Merchant is registered, but Cardholder isn't.
Customer Instruction J = Standard E-Commerce message
Tests 5a & 5b Please put a line through the scenario not being used
Tests 6a & 6b Please put a line through the scenario not being used
Secure
Code
EMV Terminal Type 30 (M'Card PDS 2) = Merchant & Cardholder are registered
31 (M'Card PDS 1) = Merchant is registered, but Cardholder isn't.
32 (M'Card PDS 0) = Standard E-Commerce message
APACS 70-2
Section B.4.2 (page 85) Electronic Commerce Data Record Sub-type 01
APACS 70-3 G = Merchant & Cardholder registered
Section A.4 (page 93) H = Merchant is registered, but Cardholder isn't.
Customer Instruction J = Standard E-Commerce message
Tests 12a & 12b Please put a line through the scenario not being used
Tests 13a & 13b 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
V
ERES PARES ATSD ECI
Non supporting schemes i.e.- Creation, AMEX, JCB, Diners, Solo N/A N/A D08000 07
© 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.
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 check response is
RELEASEONHOLDREQUEST and the namespace is ONHOLD.
Section/Fields Type/Format Description
<releaseonholdrequest>
authdb String The authorisation database within the Commidea infrastructure which
processed the transaction during authorisation
mktransactionid Decimal Transaction ID (unique only to the processing database utilised)
</releaseonholdrequest>
8.1.1. Request Example
<?xml version="1.0"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ProcessMsg xmlns="https://www.commidea.webservices.com">
<Message>
<ClientHeader xmlns="https://www.commidea.webservices.com">
<SystemID>30002411</SystemID>
<SystemGUID>096d5d0f-f9dc-430a-8d9c-e102393409c4</SystemGUID>
<Passcode>17075320</Passcode>
<SendAttempt>0</SendAttempt>
</ClientHeader>
<MsgType xmlns="https://www.commidea.webservices.com">RELEASEONHOLDREQUEST</MsgType>
<MsgData xmlns="https://www.commidea.webservices.com">
<![CDATA[<releaseonholdrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="ONHOLD">
<authdb>TEST_AUTHDB2</authdb>
<mktransactionid>1969925</mktransactionid>
</releaseonholdrequest>]]></MsgData>
</Message>
</ProcessMsg>
</soap:Body>
</soap:Envelope>
Author Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 46 5.28
8.1. Release Response
The Message Type for the payer authentication enrollment check response is
RELEASEONHOLDRESPONSE and the namespace is ONHOLD.
Section/Fields Type/Format Description
<releaseonholdresponse>
result String Result of the release request. Result types are:
RELEASED
mktransactionid Decimal Transaction ID (unique only to the processing database utilised)
authdb String The authorisation database within the Commidea infrastructure
which processed the transaction during authorization
</releaseonholdresponse>
8.1.1. Response Example
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><ProcessMsgResponse
xmlns="https://www.commidea.webservices.com"><ProcessMsgResult><ClientHeader><SystemID>3000
2411</SystemID><SystemGUID>096d5d0f-f9dc-430a-8d9c-
e102393409c4</SystemGUID><Passcode/><ProcessingDB>TEST_AUTHDB2</ProcessingDB><SendAt
tempt>0</SendAttempt><CDATAWrapping>false</CDATAWrapping></ClientHeader><MsgType>RELE
ASEONHOLDRESPONSE</MsgType><MsgData>&lt;releaseonholdresponse
xmlns="ONHOLD"&gt;&lt;result&gt;RELEASED&lt;/result&gt;&lt;mktransactionid&gt;1969925&lt;/mktrans
actionid&gt;&lt;authdb&gt;TEST_AUTHDB2&lt;/authdb&gt;&lt;/releaseonholdresponse&gt;</MsgData></P
rocessMsgResult></ProcessMsgResponse></soap:Body></soap:Envelope>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 47 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
6
7
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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 48 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
<paypalsetexpresscheckoutrequest>
merchantreference String O Merchant can add a reference
to cross reference responses
relating to the same transaction
user String R Merchant PayPal API
username
pwd String R Merchant PayPal API password
version String R Version number of the NVP API
service
signature String R Merchant PayPal signature
string
subject String O 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
returnurl String R 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.
cancelurl String R 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 49 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
amt Decimal R 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 (,).
currencycode String O A three-character currency
code for one of the currencies
listed in PayPal-
maxamt Decimal O The 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 (,).
paymentaction String O 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 50 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 String O Email address of the buyer as
entered during checkout.
PayPal uses this value to pre-
fill the PayPal membership
sign-up portion of the PayPal
login page.
Character length and limit: 127
single-byte alphanumeric
characters
desc O Description of items the
customer is purchasing.
Character length and
limitations: 127 single-byte
alphanumeric characters
custom String O A free-form field for use, such
as a tracking number or other
value for PayPal to return on
GetExpressCheckoutDetails
response and
DoExpressCheckoutPayment
response.
invnum String O 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
reqconfirmshipping Integer O 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 51 5.28
Allowable values: 0, 1
Default: 0
noshipping Integer O 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
addoverride Integer O 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
token String O 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
localecode String O 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.
pagestyle String O 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 52 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.
hdrimg String O 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
hdrbordercolor String O 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
hdrbackcolor String O 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
payflowcolor String O 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
channeltype String O Type of channel:
Merchant: non-auction
seller
eBayItem: eBay auction
If the transaction does not
include a one-time purchase,
this field is ignored.
solutiontype String O 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 53 5.28
this field is ignored.
reqbillingaddress Integer O 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
description Type of billing agreement.
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 country-
specific 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
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 54 5.28
</paypalsetexpresscheckoutrequest>
9.2.2. SetExpressCheckout Response
Section/Fields Type/Format Description
<paypalsetexpresscheckoutresponse>
merchantreference String Merchant can add a reference to
cross reference responses relating
to the same transaction
paypalrequestid Decimal Unique PayPal request identifier
token String 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
errorcode String
Error identifier (Please see
Appendix E for a full list of errors)
shortmessage String
General message (Please see
Appendix E for a full list of errors)
longmessage String
Detailed message (Please see
Appendix E for a full list of errors)
serveritycode String
Severity of the error (Please see
Appendix E for a full list of errors)
</paypalsetexpresscheckoutresponse>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 55 5.28
9.2.3. GetExpressCheckoutDetails Request
Section/Fields Type/Format Optional /
Required
Description
<paypalgetexpresscheckoutrequest>
merchantreference String O Merchant can add a
reference to cross
reference responses
relating to the same
transaction
user String R Merchant PayPal API
username
pwd String R Merchant PayPal API
password
version String R Version number of the
NVP API service
signature String R Merchant PayPal
signature string
subject String O 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
token String R 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
</paypalgetexpresscheckoutrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 56 5.28
9.2.4. GetExpressCheckoutDetails Response
Section/Fields Type/Format Description
<paypalgetexpresscheckoutresponse>
merchantreference String Merchant can add a reference to cross
reference responses relating to the
same transaction
paypalrequestid Decimal Unique PayPal request identifier
token String The timestamped token value that was
returned by SetExpressCheckout
response
and passed on
GetExpressCheckoutDetails request.
Character length and limitations: 20
single-byte characters
email String Email address of payer.
Character length and limitations: 127
single-byte characters
payerid String Unique PayPal customer account
identification number.
Character length and limitations:13
single-byte alphanumeric characters.
payerstatus String Status of payer. Valid values are:
Verified
Unverified
Character length and limitations: 10
single-byte alphabetic characters.
Possible values: verified, unverified
salutation String Payer’s salutation.
Character length and limitations: 20
single-byte characters
firstname String Payer’s first name.
Character length and limitations: 25
single-byte characters
middlename String Payer’s middle name.
Character length and limitations: 25
single-byte characters
lastname String Payer’s last name.
Character length and limitations: 25
single-byte characters
suffix String Payer’s suffix.
Character length and limitations: 12
single-byte characters
countrycode String Payer’s country of residence in the form
of ISO standard 3166 two-character
country
codes.
Character length and limitations: Two
single-byte characters
business String Payer’s business name.
shiptoname String Person’s name associated with this
address.
Character length and limitations: 32
single-byte characters
shiptostreet String First street address.
Character length and limitations: 100
single-byte characters
shiptostreet2 String Second street address.
Character length and limitations: 100
single-byte characters
shiptocity String 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 57 5.28
shiptostate String State or province
Character length and limitations: 40
single-byte characters
shiptocountrycode String Country code.
Character limit: Two single-byte
characters.
shiptozip String U.S. Zip code or other country-specific
postal code.
Character length and limitations: 20
single-byte characters
addressstatus String Status of street address on file with
PayPal
custom String 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
invnum String 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
phonenum String 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)
billingaddressacceptedstatus String Whether or not the customer accepted
the billing agreement. This value always
returns ‘Yes’.
errorcode String Error identifier (Please see Appendix E
for a full list of errors)
shortmessage String General message (Please see
Appendix E for a full list of errors)
longmessage String Detailed message (Please see
Appendix E for a full list of errors)
serveritycode String Severity of the error (Please see
Appendix E for a full list of errors)
</paypalgetexpresscheckoutresponse>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 58 5.28
9.2.5. DoExpressCheckoutPayment Request
Section/Fields Type/Format Optional
/
Required
Description
<paypaldoexpresscheckoutrequest>
merchantreference String O Merchant can add a reference
to cross reference responses
relating to the same
transaction
user String R Merchant PayPal API
username
pwd String R Merchant PayPal API
password
version String R Version number of the NVP
API service
signature String R Merchant PayPal signature
string
subject String O 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
token String R The timestamped token value
that was returned by
SetExpressCheckout
response and passed on
GetExpressCheckoutDetails
request.
Character length and
limitations: 20 single-byte
characters
paymentaction String R 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 59 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..
payerid String R Unique PayPal customer
account identification number
as returned by
GetExpressCheckoutDetails
response.
Character length and
limitations: 13 single-byte
alphanumeric characters.
amt Decimal R 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 (,).
desc String O Description of items the
customer is purchasing.
Character length and
limitations: 127 single-byte
alphanumeric characters
custom String O A free-form field for use.
Character length and
limitations: 256 single-byte
alphanumeric characters
invnum String O An invoice or tracking
number.
Character length and
limitations: 127 single-byte
alphanumeric characters
notifyurl String O 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
itemamt Decimal O 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 60 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 (,).
shippingamt Decimal O 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.
handlingamt Decimal O 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.
taxamt Decimal O 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.
currencycode String O A three-character currency
code for one of the currencies
listed in PayPal-
Supported 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 61 5.28
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
country-specific postal code.
Character length and
limitations: 20 single-byte
characters
shiptostreet2 String O Second street address.
Character length and
limitations: 100 single-byte
characters
shiptophonenumber String O Phone number.
Character length and limit: 20
single-byte characters
</paypaldoexpresscheckoutrequest>
9.2.6. PayPal ExpressItem
Section/Fields Type/Format Optional / Required Description
<paypalexpressitem>
name String O Item name.
Character length and
limitations: 127 single-byte
characters
number String O Item number.
Character length and
limitations: 127 single-byte
characters
qty Integer O Item quantity.
Character length and
limitations: Any positive
integer
taxamt Decimal O 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 (,).
amt Decimal O 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 62 5.28
symbol. Must have two
decimal places, decimal
separator must be a period
(.), and the optional
thousands separator must
be a comma (,).
ebayitemnumber String O Auction item number
Character length: 765
single-byte characters
ebayitemauctiontxnid String O Auction transaction
identification number
Character length: 255
single-byte characters
ebayitemorderid String O Auction order identification
number
Character length: 64
single-byte characters
</paypalexpressitem>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 63 5.28
9.2.7. DoExpressCheckoutPayment Response
Section/Fields Type/Format Description
<paypaldoexpresscheckoutresponse>
merchantreference String Merchant can add a reference to cross
reference responses relating to the
same transaction
paypalrequestid Decimal Unique PayPal request identifier
token String The timestamped token value that was
returned by SetExpressCheckout
response and passed on
GetExpressCheckoutDetails request.
Character length and limitations:20
single-byte characters
transactionid String 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
transactiontype String The type of transaction
Character length and limitations:15
single-byte characters
Possible values:
Cart
Express-checkout
paymenttype String Indicates whether the payment is instant
or delayed.
Character length and limitations: Seven
single-byte characters
Possible values:
None
eCheck
Instant
ordertime String Time/date stamp of payment
Possible values: Transaction specific
amt Decimal 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
currencycode String A three-character currency code for one
of the currencies listed in PayPay-
Supported
Transactional Currencies.
feeamount Decimal 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 64 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
settleamount Decimal Amount deposited in the merchant’s
PayPal account after a currency
conversion.
Possible values: Transaction specific
taxamount Decimal 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
exchangerate Decimal 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
paymentstatus String 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.
pendingreason String 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 65 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.
reasoncode String 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.
redirectrequired String 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.
errorcode String Error identifier (Please see Appendix E
for a full list of errors)
shortmessage String General message (Please see
Appendix E for a full list of errors)
longmessage String Detailed message (Please see
Appendix E for a full list of errors)
serveritycode String Severity of the error (Please see
Appendix E for a full list of errors)
</paypaldoexpresscheckoutresponse>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 66 5.28
9.2.8. DoAuthorization Request
Section/Fields Type/Format Optional /
Required
Description
<paypaldoauthorizationrequest>
merchantreference String O Merchant can add a
reference to cross
reference responses
relating to the same
transaction
user String R Merchant PayPal API
username
pwd String R Merchant PayPal API
password
version String R Version number of the
NVP API service
signature String R Merchant PayPal
signature string
subject String O 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
transactionid String R The value of the order’s
transaction identification
number returned by
PayPal.
Character length and
limits: 19 single-byte
characters maximum
amt Decimal R 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 (,).
transactionentity String O 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.
currencycode String O A three-character
currency code for one of
the currencies listed in
PayPay-Supported
Transactional Currencies.
</paypaldoauthorizationrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 67 5.28
9.2.9. DoAuthorization Response
Section/Fields Type/Format Description
<paypaldoauthorizationresponse>
merchantreference String Merchant can add a reference to
cross reference responses relating to
the same transaction
paypalrequestid Decimal Unique PayPal request identifier
transactionid String An authorisation identification
number.
Character length and limits: 19 single-
byte characters
Amt Decimal The amount specified in the request.
currencycode String A three-character currency code for
one of the currencies listed in PayPal
Supported Transactional Currencies.
errorcode String
Error identifier (Please see Appendix
E for a full list of errors)
shortmessage String
General message (Please see
Appendix E for a full list of errors)
longmessage String
Detailed message (Please see
Appendix E for a full list of errors)
serveritycode String
Severity of the error (Please see
Appendix E for a full list of errors)
</paypaldoauthorizationresponse>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 68 5.28
9.2.10. DoCapture Request
Section/Fields Type/Format Optional /
Required
Description
<paypaldocapturerequest>
merchantreference String O Merchant can add a reference to
cross reference responses
relating to the same transaction
user String R Merchant PayPal API username
pwd String R Merchant PayPal API password
version String R Version number of the NVP API
service
signature String R Merchant PayPal signature string
subject String O 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
authorizationid String R 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.
amt Decimal R 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 (,).
currencycode String O A three-character currency code
for one of the currencies listed in
PayPay-Supported Transactional
Currencies.
completetype String R 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
invnum String O 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 69 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
note String O 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
softdescriptor String O 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:
<PP * | PAYPAL *><Merchant
descriptor as set in the Payment
Receiving Preferences><1
space><soft descriptor>
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(<PP * | PAYPAL *>) -
len(<Descriptor set in Payment
Receiving Preferences> + 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 70 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
</paypaldocapturerequest>
9.2.11. DoCapture Response
Section/Fields Type/Format Description
<paypaldocaptureresponse>
merchantreference String Merchant can add a reference to cross
reference responses relating to the same
transaction
paypalrequestid Decimal Unique PayPal request identifier
authorizationid String The authorisation identification number
specified in the request.
Character length and limits: 19 single-byte
characters maximum
transactionid String Unique transaction ID of the payment.
Character length and limitations: 17 single-
byte characters
parenttransactionid String 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
receipttid String Receipt identification number
Character length and limits: 16 digits in
xxxx-xxxx-xxxx-xxxx format
transactiontype String The type of transaction
Cart
Express-checkout
Character length and limitations: 15 single-
byte characters
paymenttype String Indicates whether the payment is instant or
delayed.
Character length and limitations: Seven
single-byte characters
ordertime String Time/date stamp of payment. For example:
2006-08-15T17:23:15Z.
currencycode String 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 71 5.28
the currencies listed in PayPal Supported
Transactional Currencies
amt Decimal The final amount charged, including any
shipping and taxes from the Merchant
Profile.
feeamt Decimal PayPal fee amount charged for the
transaction
settleamt Decimal Amount deposited in the merchant’s
PayPal account if there is a currency
conversion.
taxamt Decimal Tax charged on the transaction, if any
exchangerate Decimal 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
paymentstatus String 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.
errorcode String 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 72 5.28
a full list of errors)
shortmessage String General message (Please see Appendix E
for a full list of errors)
longmessage String Detailed message (Please see Appendix E
for a full list of errors)
serveritycode String Severity of the error (Please see Appendix
E for a full list of errors)
</paypaldocaptureresponse>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 73 5.28
9.2.12. DoVoid Request
Section/Fields Type/Format Optional / Required Description
<paypaldovoidrequest>
merchantreference String O Merchant can add a
reference to cross reference
responses relating to the
same transaction
user String R Merchant PayPal API
username
pwd String R Merchant PayPal API
password
version String R Version number of the NVP
API service
signature String R Merchant PayPal signature
string
subject String O 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
authorizationid String R 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
note String O 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
</paypaldovoidrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 74 5.28
9.2.13. DoVoid Response
Section/Fields Type/Format Description
<paypaldovoidresponse>
merchantreference String Merchant can add a reference to
cross reference responses relating to
the same transaction
paypalrequestid Decimal Unique PayPal request identifier
authorizationid String The authorisation identification
number specified in the request.
Character length and limits: 19 single-
byte characters
errorcode String
Error identifier (Please see Appendix
E for a full list of errors)
shortmessage String
General message (Please see
Appendix E for a full list of errors)
longmessage String
Detailed message (Please see
Appendix E for a full list of errors)
serveritycode String
Severity of the error (Please see
Appendix E for a full list of errors)
</paypaldovoidresponse>
9.2.14. RefundTransaction Request
Section/Fields Type/Format Optional / Required Description
<paypalrefundtransactionrequest>
merchantreference String O Merchant can add a
reference to cross reference
responses relating to the
same transaction
user String R Merchant PayPal API
username
pwd String R Merchant PayPal API
password
version String R Version number of the NVP
API service
signature String R Merchant PayPal signature
string
subject String O 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
transactionid String R Unique identifier of a
transaction
Character length and
limitations: 17 single-byte
alphanumeric characters
refundtype String R Type of refund being made:
Other
Full
Partial
amt Decimal O Refund amount.
Amount is required if
RefundType is Partial.
NOTE: If RefundType is Full,
do not set Amount.
currencycode String O 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 75 5.28
Currencies
note String O Custom memo about the
refund.
Character length and
limitations: 255 single-byte
alphanumeric characters
</paypalrefundtransactionrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 76 5.28
9.2.15. RefundTransaction Response
Section/Fields Type/Format Description
<paypalrefundtransactionresponse>
merchantreference String Merchant can add a reference to cross
reference responses relating to the
same transaction
paypalrequestid Decimal Unique PayPal request identifier
currencycode String A three-character currency code for one
of the currencies listed in PayPal
Supported Transactional Currencies
refundtransactionid String Unique transaction ID of the refund.
Character length and limitations:17
single-byte characters
netrefundamt Decimal Amount subtracted from PayPal
balance of original recipient of payment
to
make this refund
feerefundamt Decimal Transaction fee refunded to original
recipient of payment
grossrefundamt Decimal Amount of money refunded to original
payer
errorcode String
Error identifier (Please see Appendix E
for a full list of errors)
shortmessage String
General message (Please see
Appendix E for a full list of errors)
longmessage String
Detailed message (Please see
Appendix E for a full list of errors)
serveritycode String
Severity of the error (Please see
Appendix E for a full list of errors)
</paypalrefundtransactionresponse>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 77 5.28
9.2.16. DoReauthorization Request
Section/Fields Type/Format Optional /
Required
Description
<paypaldoreauthorizationrequest>
merchantreference String O Merchant can add a
reference to cross
reference responses
relating to the same
transaction
user String R Merchant PayPal API
username
pwd String R Merchant PayPal API
password
version String R Version number of the
NVP API service
signature String R Merchant PayPal
signature string
subject String O 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
authorizationid String R The value of a previously
authorised transaction
identification number
returned by PayPal.
Character length and
limits: 19 single-byte
characters maximum
amt Decimal R 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 (,).
currencycode String O A three-character
currency code for one of
the currencies listed in
PayPay-
Supported Transactional
Currencies.
</paypaldoreauthorizationrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 78 5.28
9.2.17. DoReauthorization Response
Section/Fields Type/Format Description
<paypaldoreauthorizationresponse>
merchantreference String Merchant can add a reference to
cross reference responses relating
to the same transaction
paypalrequestid Decimal Unique PayPal request identifier
authorizationid String A new authorisation identification
number.
Character length and limits:19
single-byte characters
errorcode String
Error identifier (Please see
Appendix E for a full list of errors)
shortmessage String
General message (Please see
Appendix E for a full list of errors)
longmessage String
Detailed message (Please see
Appendix E for a full list of errors)
serveritycode String
Severity of the error (Please see
Appendix E for a full list of errors)
</paypaldoreauthorizationresponse>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 79 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 Type/
Format
Length Optional /
Required
Description
<svsrequestmessage>
messagetype Integer M No Message Type
0Balance Enquiry
*1 Pre-Authorization Message
2Redemption Message
*3 Tip Message
4Cancellation
5Merchandise Return Message
6Card Recharge Message
*7 Pre-Authorisation Completion
Message
*8 Card Activation Message
9Issue Gift Card
*10 Issue Virtual Gift Card Message
*11 Reversal Message
*12 Network Message
13 Cash Back Message
* Reserved for future use, not currently available
stan String 6 O 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 80 5.28
original STAN must be passed in with reversals
offlineauthcode String 10 O Offline Authorisation Code
cardnumber String 19 O SVS card number
track1 String O Track 1
track2 String O Track 2
transactionamount Decimal 6 O Transaction amount, e.g. 9.99
transactioncurrency String 3 O Currency Code (ISO 4217) for transaction (e.g.
826 = Pound Sterling)
transactiondate String 8 O Transaction date: YYYYMMDD – e.g. 20110110
transactiontime String 6 O Transaction time: HHMMSS - e.g. 175732
invoicenumber String 8 O Client assigned value which may be used to
represent an order number or reference for the
transaction, e.g. INV01
merchantname String 50 O Merchant name
merchantnumber String 6 M SVS Merchant number
storenumber String 10 O Store number
divisionnumber String 5 M Division number
routingid String 19 M Routing ID
<
/
svsrequestmessage>
10.2.2. SVS Response
The SVS Response type contains all the result information from an SVS request.
Section/Fields Type/
Format
Length Description
<svsresponsemessage>
id Decimal The request ID
responsecode String 2 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 pre-
authorisation.
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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 81 5.28
32 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
responsemessage String Description e.g. “Approved”
stan String 6 Systems trace audit number. Example: 123456.
transactionamount Decimal 6 Transaction amount supplied within request: E.g. 9.99
balanceamount Decimal 6 Balance amount remaining on the SVS card
conversionrate Decimal 8 Conversion rate. E.g. 1.000000
cardcurrencycode String 3 826 (Numeric translation of GBP)
<
/
svsresponsemessage>
10.3. 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 82 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 83 5.28
11.2. 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
Description
<tokenregistrationrequest>
merchantreference String O 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
</tokenregistrationrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 84 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 Type/Format Description
<tokenregistrationresponse>
tokenid Decimal Unique identifier for registered PAN
merchantreference String Merchant can add a reference to
cross reference responses relating
to the same transaction
errorcode Integer This is an error code indicating what
type of error occurred, if any, while
processing the transaction. See
Appendix E for error codes
errormsg String This is a text field used to give as
short text description of the error
code
</tokenregistrationresponse>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 85 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
Description
<tokenregistrationrequest>
merchantreference String O 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
</tokenregistrationrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 86 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 Type/Format Description
<tokenregistrationresponse>
tokenid Decimal Unique identifier for registered PAN
merchantreference String Merchant can add a reference to
cross reference responses relating
to the same transaction
cardschemename String Returns the card scheme name for
the card registered within the
request
</tokenregistrationresponse>
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 Type/Format Description
<tokenregistrationresponse>
merchantreference String Merchant can add a reference to
cross reference responses relating
to the same transaction
errorcode Integer This is an error code indicating what
type of error occurred, if any, while
processing the transaction. See
Appendix E for error codes
errormsg String This is a text field used to give as
short text description of the error
code
</tokenregistrationresponse>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 87 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 Type/Format Description
<ukashrequest >
merchantreference String
Varchar(50) Merchant can add a reference to cross
reference responses relating to the same
transaction
requesttype String
Varchar(50) The request type;
ukashgetsettleamount
ukashlogin String
Char(20) This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
ukashpassword String
Char(20) This is the password for the Ukash login
name, which will be supplied to the
merchant by Ukash
transactionid String
Char(20) 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
brandid String
Char(20) 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
vouchernumber String
Char(19)/ Char(16) This is the number printed on the voucher
or card, the number will be 19 digits for
vouchers and 16 digits for cards.
vouchervalue decimal
This is the value of the voucher presented
in 2 decimal points
basecurr String
Char(3) 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
vouchercurrproductcode String
Char(3) 7-9 digits of voucher number
</ukashrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 88 5.28
12.2. Ukash PartSpendVoucher Request
Section/Fields Type/Format Description
<ukashrequest >
merchantreference String
Varchar(50) Merchant can add a reference to cross
reference responses relating to the same
transaction
requesttype String
Varchar(50) The request type;
ukashpartspendvoucher
ukashlogin String
Char(20) This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
ukashpassword String
Char(20) This is the password for the Ukash login
name, which will be supplied to the
merchant by Ukash
transactionid String
Char(20) 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
brandid String
Char(20) 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
vouchernumber String
Char(19)/ Char(16) This is the number printed on the voucher
or card, the number will be 19 digits for
vouchers and 16 digits for cards.
vouchervalue decimal
This is the value of the voucher presented
in 2 decimal points
ticketvalue Decimal 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.
basecurr String
Char(3) 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
merchdatetime String Char(19)
This is the Merchant’s time stamp of the
transaction. Format “yyyy-mm-dd
hh:mm:ss”
redemptiontype String Char(1)/Char(2) This indicates what the transaction is being
used for. See Section 7.9 for redemption
Types. The numeric identifier must be
supplied
vouchercurrproductcode String
Char(3) 7-9 digits of voucher number
</ukashrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 89 5.28
12.3. Ukash FullValueVoucher Request
Section/Fields Type/Format Description
<ukashrequest>
merchantreference String
Varchar(50) Merchant can add a reference to cross
reference responses relating to the same
transaction
requesttype String
Varchar(50) The request type;
ukashfullvaluevoucher
ukashlogin String
Char(20) This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
ukashpassword String
Char(20) This is the password for the Ukash login
name, which will be supplied to the
merchant by Ukash
transactionid String
Char(20) 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
brandid String
Char(20) 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
vouchernumber String
Char(19)/ Char(16) This is the number printed on the voucher
or card, the number will be 19 digits for
vouchers and 16 digits for cards.
vouchervalue decimal
This is the value of the voucher presented
in 2 decimal points
basecurr String
Char(3) 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
merchdatetime String Char(19)
This is the Merchant’s time stamp of the
transaction. Format “yyyy-mm-dd
hh:mm:ss”
redemptiontype This indicates what the transaction is being
used for. See Section 7.9 for redemption
Types. The numeric identifier must be
supplied
vouchercurrproductcode String
Char(3) 7-9 digits of voucher number
</ukashrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 90 5.28
12.4. Ukash PartSpendAccount Request
Section/Fields Type/Format Description
<ukashrequest>
merchantreference String
Varchar(50) Merchant can add a reference to cross
reference responses relating to the same
transaction
requesttype String
Varchar(50) The request type;
ukashpartspendaccount
ukashlogin String
Char(20) This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
ukashpassword String
Char(20) This is the password for the Ukash login
name, which will be supplied to the
merchant by Ukash
transactionid String
Char(20) 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
brandid String
Char(20) 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
vouchernumber String
Char(19)/ Char(16) This is the number printed on the voucher
or card, the number will be 19 digits for
vouchers and 16 digits for cards.
ukashpin String
Char(4) This is the Pin number printed on the
Ukash Card. 4 digit value, field is required
for all card based transactions
vouchervalue decimal
This is the value of the voucher presented
in 2 decimal points
ticketvalue Decimal 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.
basecurr String
Char(3) 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
merchdatetime String Char(19)
This is the Merchant’s time stamp of the
transaction. Format “yyyy-mm-dd
hh:mm:ss”
redemptiontype This indicates what the transaction is being
used for. See Section 7.9 for redemption
Types. The numeric identifier must be
supplied
vouchercurrproductcode String Char(3) 7-9 digits of voucher number
</ukashrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 91 5.28
12.5. Ukash FullSpendAccount Request
Section/Fields Type/Format Description
<ukashrequest>
merchantreference String
Varchar(50) Merchant can add a reference to cross
reference responses relating to the same
transaction
requesttype String
Varchar(50) The request type;
ukashfullspendaccount
ukashlogin String
Char(20) This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
ukashpassword String
Char(20) This is the password for the Ukash login
name, which will be supplied to the
merchant by Ukash
transactionid String
Char(20) 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
brandid String
Char(20) 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
vouchernumber String
Char(19)/ Char(16) This is the number printed on the voucher
or card, the number will be 19 digits for
vouchers and 16 digits for cards.
ukashpin String
Char(4) This is the Pin number printed on the
Ukash Card. 4 digit value, field is required
for all card based transactions
vouchervalue decimal
This is the value of the voucher presented
in 2 decimal points
basecurr String
Char(3) 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
mercdatetime String Char(19)
This is the Merchant’s time stamp of the
transaction. Format “yyyy-mm-dd
hh:mm:ss”
redemptiontype This indicates what the transaction is being
used for. See Section 7.9 for redemption
Types. The numeric identifier must be
supplied
vouchercurrproductcode String Char(3) 7-9 digits of voucher number
</ukashrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 92 5.28
12.6. TransactionEnquiry Request
Used to check if there is an issue with the Ukash server, and there is a requirement to check
with Ukash if the transaction was successful or not.
Section/Fields Type/Format Description
<ukashrequest>
merchantreference String
Varchar(50) Merchant can add a reference to cross
reference responses relating to the same
transaction
requesttype String
Varchar(50) The request type;
ukashtransactionenquiry
ukashlogin String
Char(20) This is a login name that will be supplied to
the merchant by Ukash to send with each
transaction sent to the Ukash gateway
ukashpassword String
Char(20) This is the password for the Ukash login
name, which will be supplied to the
merchant by Ukash
transactionid String
Char(20) 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
brandid String
Char(20) 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
vouchernumber String
Char(19)/ Char(16) This is the number printed on the voucher
or card, the number will be 19 digits for
vouchers and 16 digits for cards.
ukashpin String
Char(4) This is the Pin number printed on the
Ukash Card. 4 digit value, field is required
for all card based transactions
vouchervalue decimal
This is the value of the voucher presented
in 2 decimal points
basecurr String
Char(3) 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
merchdatetime String Char(19)
This is the Merchant’s time stamp of the
transaction. Format “yyyy-mm-dd
hh:mm:ss”
redemptiontype This indicates what the transaction is being
used for. See Section 7.9 for redemption
Types. The numeric identifier must be
supplied
vouchercurrproductcode String Char(3) 7-9 digits of voucher number
</ukashrequest>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 93 5.28
12.7. Ukash Response
The Message Type for the Ukash response is UKASH and the namespace is TRM.
Section/Fields Type/Format Description
<ukashresponse>
requesttype String
Varchar(50) The request type
amountreference String
Char(255) Merchants using the GetSettleAmount
method need only fill in this tag. All other
merchants should send a blank string in
this tag.
mktransactionID Decimal Unique transaction ID
txcode Integer 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
txdescription String
Char(255) This is a text field used to give a short text
description of the transaction status/return
code
transactionid String
Char(20) The transactionId is returned as reference
to link the request and response XML
settleamount Decimal This is the value of the transaction in the
base currency
accountbalance Decimal The account balance in the currency of the
account. Applicable to account based
transactions only.
accountcurrency String
Char(3) This is the currency the card account. It
will be given in the character ISO
standard.
changeissuevouchernumber String
Char(19) For ticket price redemption, this is the
voucher number for the change. For full
value redemption, this will be blank
changeissuevouchercurr String
Char(3) This is the currency of the change issue
voucher. It will be given in the character
ISO standard. Refer to Appendix B
changeissueamount Decimal This is the value of the change presented
in 2 decimal places. For full value
redemption, this will be blank
changeissueexpirydate String
Char(10) This is the expiry date for the change
issue voucher in the format yyyy-mm-dd
issuedvouchernumber String
Char(19) For issued vouchers this is the new
voucher number. This tag will only be
returned for IssueVoucher transactions.
issuedvouchercurr String
Char(3) 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.
issuedamount Decimal This is the value of the issued voucher
presented in 2 decimal places. This tag
will only be returned for IssueVoucher
transactions.
issuedexpirydate String
Char(10) This is the expiry date for the issued
voucher in the format yyyy-mm-dd. This
tag will only be returned for IssueVoucher
transactions.
ukashtransactionid String
Char(50) This is a unique reference to the
transaction
currencyconversion Boolean 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 94 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
errcode Integer 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
errdescription String
Char(255) This is a text field used to give a short text
description of the error code
</ukashresponse>
12.8. Ukash Return Code List
Type of
Message
Message
Code
Message
Description
Comments
Transaction Status 0 Accepted Redemption successful
1 Declined Redemption unsuccessful
99 Failed An error occurred during the
processing of the transaction hence
the system could not successfully
complete the redemption of the
voucher.
12.9. Ukash Transaction Type List
Code Description Comments
1 Cash Withdrawal Normal Redemption transactions. Voucher or account will be debited
with the currency and amount.
2 Account Deposit
3 Product/Service
Purchase
4 Issue Voucher Issues Voucher based on the currency and value
8 Void Transaction Voids a Transaction made in the last 60 seconds.
20 Account Add Add amount to Ukash account. Used only for Top up and Top Down
Cards.
21 Account Subtract Subtracts amount from Ukash account. Used only for Top up and
Top Down Cards.
22 Transaction Enquiry 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 95 5.28
12.10. Ukash Error Code List
Type of Erro
r
Error
Code
Error Description
Incoming XML Error 100 Invalid incoming XML
Data Validation Error 200 Non numeric Voucher Value
201 Base Currency not 3 characters in length
202 Non numeric Ticket Value
203 Invalid BrandId
204 Invalid MerchDateTime
205 Invalid transactionId: greater than 20 characters
206 Invalid Redemption Type
207 Negative Ticket Value not allowed
208 No decimal place given in Ticket Value
209 No decimal place given in Voucher Value
210 Negative Voucher Value not allowed
211 Invalid or unsupported voucher product code
212 AmountReference with TicketValue not allowed
213 No ukashNumber supplied
214 No transactionId supplied
215 No brandId supplied
216 Ticket Value cannot be greater than Voucher Value without
Currency Conversion
217 Base Currency and Voucher currency do not match.
218 Brand not configured to Issue Vouchers
219 Invalid Voucher Number
221 Multiple Transactions found
222 Unknown transaction status
223 No transaction found.
Card Validation Error 250 The transaction cannot proceed with a user supplied PIN, and
none was supplied,
251 The supplied PIN had the incorrect format, e.g. was not 4
numeric characters
252 PIN supplied with a transaction is incorrect (I.e. does not
match the required pin recorded on file)
253 PIN supplied with a transaction is incorrect and has resulted in
the failure count reaching the maximum
254 The Account has been blocked as a result of a
validation/verification check failure
Login and Password 300 Invalid Login and/or Password
Login, Password and
BrandID 301 Invalid Login and/or BrandID
Currency Conversion Not
Supported 400 Required Currency Conversion not supported
Currency Conversion
Error 500 Error In Currency Conversion
501 Converted Settle Amount greater than Voucher Value
General Error 800 Max duration between getSettleAmount and Redemption
exceeded.
801 Invalid amountReference Submitted
Technical Error 900 Technical Error. Please contact Ukash Merchant Support
999 Ukash Server Error. Please contact Commidea 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 96 5.28
12.11. Ukash Product Codes
Region Country State Currency General
Issues
(020-200)
Cash
Back
Issues
(201-400)
Gambling
Restricted
(401-600)
Reserved
(601-800)
Reserved
(801-999)
United
Kingdom United
Kingdom United
Kingdom GBP 001 201 401 601 801
Europe Europe Europe EUR 011 211 411 611 811
Europe Poland Poland PLN 151 351 551 751 951
Europe Austria Austria EUR 021 221 421 621 821
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
Europe Spain Spain EUR 011 211 411 611 811
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 Czech
Republic CZK 036 236 436 636 836
Europe Norway 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 USA USA USD 99 299 499 699 899
North
America USA Alabama USD 100 300 500 700 900
North
America USA Alaska USD 101 301 501 701 901
North
America USA Arizona USD 102 302 502 702 902
North
America USA Arkansas USD 103 303 503 703 903
North
America USA California USD 104 304 504 704 904
North
America USA Colorado USD 105 305 505 705 905
North
America USA Connecticut USD 106 306 506 706 906
North
America USA Delaware USD 107 307 507 707 907
North
America USA Florida USD 108 308 508 708 908
North
America USA Georgia USD 109 309 509 709 909
North
America USA Hawaii USD 110 310 510 710 910
North
America USA Idaho USD 111 311 511 711 911
North
America USA Illinois USD 112 312 512 712 912
North
America 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 97 5.28
North
America USA Iowa USD 114 314 514 714 914
North
America USA Kansas USD 115 315 515 715 915
North
America USA Kentucky USD 116 316 516 716 916
North
America USA Louisiana USD 117 317 517 717 917
North
America USA Maine USD 118 318 518 718 918
North
America USA Maryland USD 119 319 519 719 919
North
America USA Massachuset
ts USD 120 320 520 720 920
North
America USA Michigan USD 121 321 521 721 921
North
America USA Minnesota USD 122 322 522 722 922
North
America USA Mississippi USD 123 323 523 723 923
North
America USA Missouri USD 124 324 524 724 924
North
America USA Montana USD 125 325 525 725 925
North
America USA Nebraska USD 126 326 526 726 926
North
America USA Nevada USD 127 327 527 727 927
North
America USA New
Hampshire USD 128 328 528 728 928
North
America USA New Jersey USD 129 329 529 729 929
North
America USA New Mexico USD 130 330 530 730 930
North
America USA New York USD 131 331 531 731 931
North
America USA North
Carolina USD 132 332 532 732 932
North
America USA North Dakota USD 133 333 533 733 933
North
America USA Ohio USD 134 334 534 734 934
North
America USA Oklahoma USD 135 335 535 735 935
North
America USA Oregon USD 136 336 536 736 936
North
America USA Pennsylvania USD 137 337 537 737 937
North
America USA Rhode Island USD 138 338 538 738 938
North
America USA South
Carolina USD 139 339 539 739 939
North
America USA South
Dakota USD 140 340 540 740 940
North
America USA Tennessee USD 141 341 541 741 941
North
America USA Texas USD 142 342 542 742 942
North
America USA Utah USD 143 343 543 743 943
North
America USA Vermont USD 144 344 544 744 944
North
America USA Virginia USD 145 345 545 745 945
North
America USA Washington USD 146 346 546 746 946
North
America USA West Virginia USD 147 347 547 747 947
North
America USA Wisconsin USD 148 348 548 748 948
North
America USA Wyoming USD 149 349 549 749 949
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 98 5.28
South
America Argentina Argentina ARS 152 352 552 752 952
North
America Canada Canada CAD 153 353 553 753 953
Africa 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 99 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:
....
<PAN>CardNumber</PAN>
....
2) A deserialization error is returned within the ‘InternalError’ tag, detailing which field caused
the issue (in this case ‘PAN’):
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<CardTxnResponse xmlns="https://www.commidea.webservices.com">
<CommideaTxnResponse>
<StdResponse />
<InternalError>[16277] TransactionProcessor.DeserializeXml: Bad Format in
TRecord_Pan</InternalError>
</CommideaTxnResponse>
</CardTxnResponse>
</soap:Body>
</soap:Envelope>
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 100 5.28
13.2. Contact Information
Should there be a need to contact Commidea for help, please use the below contact details:
In a Test Environment:
Implementations
implementations@commidea.com
08444 828 273
In a Live Environment:
Merchant Helpdesk
helpdesk@commidea.com
08444 828 222
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 101 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 Description/Reasoning Test Result
Perform a normal transaction Ensure solution processes transactions correctly
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
PASS / FAIL
Perform a voice referral transaction
(value ends in 2p) Ensure voice referral transactions are rejected with a
<Command> of 2 (rejected) for websites
Check referral message does not say the transaction has
been “declined”. Use “unsuccessful, as the scenario is
different from that of declines
PASS / FAIL
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
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 102 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
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.
Author Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 103 5.28
APPENDIX B – Currency Code ISO 4217
Currency Code Num Locations using this currency
Afghani AFN 971 Afghanistan
Algerian dina
r
DZD 012 Algeria
Argentine peso ARS 032 Argentina
Armenian dram AMD 051 Armenia
Aruban guilde
r
AWG 533 Aruba
Australian dolla
r
AUD 036 Australia, Australian Antarctic Territory, Christmas Island,
Cocos (Keeling) Islands, Heard and McDonald Islands,
Kiribati, Nauru, Norfolk Island, Tuvalu
Azerbaijanian manat AZN 944 Azerbaijan
Bahamian dolla
r
BSD 044 Bahamas
Bahraini dina
r
BHD 048 Bahrain
Baht THB 764 Thailand
Balboa PAB 590 Panama
Bangladeshi taka BDT 050 Bangladesh
Barbados dolla
r
BBD 052 Barbados
Belarusian ruble BYR 974 Belarus
Belize dolla
r
BZD 084 Belize
Bermudian dollar (customarily
known as Bermuda dollar) BMD 060 Bermuda
Bolivian Mvdol (funds code) BOV 984 Bolivia
Boliviano BOB 068 Bolivia
Brazilian real BRL 986 Brazil
Brunei dolla
r
BND 096 Brunei, Singapore
Bulgarian lev BGN 975 Bulgaria
Burundian franc BIF 108 Burundi
Canadian dolla
r
CAD 124 Canada
Cape Verde escudo CVE 132 Cape Verde
Cayman Islands dolla
r
KYD 136 Cayman Islands
Cedi GHS 936 Ghana
CFA Franc BCEAO XOF 952 Benin, Burkina Faso, Côte d'Ivoire, Guinea-Bissau, Mali,
Niger, Senegal, Togo
CFA franc BEAC XAF 950 Cameroon, Central African Republic, Congo, Chad,
Equatorial Guinea, Gabon
CFP franc XPF 953 French Polynesia, New Caledonia, Wallis and Futuna
Chilean peso CLP 152 Chile
Chinese Yuan CNY 156 China (Mainland)
Code reserved for testing
purposes XTS 963
Colombian peso COP 170 Colombia
Comoro franc KMF 174 Comoros
Convertible marks BAM 977 Bosnia and Herzegovina
Cordoba oro NIO 558 Nicaragua
Costa Rican colon CRC 188 Costa Rica
Croatian kuna HRK 191 Croatia
Cuban convertible peso CUC 931 Cuba
Cuban peso CUP 192 Cuba
Czech Koruna CZK 203 Czech Republic
Dalasi GMD 270 Gambia
Danish krone DKK 208 Denmark, Faroe Islands, Greenland
Dena
r
MKD 807 Macedonia
Djibouti franc DJF 262 Djibouti
Dobra STD 678 São Tomé and Príncipe
Dominican peso DOP 214 Dominican Republic
East Caribbean dolla
r
XCD 951 Anguilla, Antigua and Barbuda, Dominica, Grenada,
Montserrat, Saint Kitts and Nevis, Saint Lucia, Saint
Vincent and the Grenadines
Egyptian pound EGP 818 Egypt
Ethiopian bir
r
ETB 230 Ethiopia
Euro EUR 978 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 104 5.28
Portugal, Slovakia, Slovenia, Spain, Andorra, Kosovo,
Monaco, Montenegro, San Marino, Vatican
European Composite Unit
(EURCO) (bond market unit) XBA 955
European Monetary Unit
(E.M.U.-6) (bond market unit) XBB 956
European Unit of Account 17
(E.U.A.-17) (bond market unit) XBD 958
European Unit of Account 9
(E.U.A.-9) (bond market unit) XBC 957
Falkland Islands pound FKP 238 Falkland Islands
Fiji dolla
r
FJD 242 Fiji
Forint HUF 348 Hungary
Franc Congolais CDF 976 Democratic Republic of Congo
Gibraltar pound GIP 292 Gibraltar
Gold (one troy ounce) XAU 959
Guarani PYG 600 Paraguay
Guinea franc GNF 324 Guinea
Guyana dolla
r
GYD 328 Guyana
Haiti gourde HTG 332 Haiti
Hong Kong dolla
r
HKD 344 Hong Kong Special Administrative Region
Hryvnia UAH 980 Ukraine
Iceland krona ISK 352 Iceland
Indian rupee INR 356 Bhutan, India
Iranian rial IRR 364 Iran
Iraqi dina
r
IQD 368 Iraq
Israeli new sheqel ILS 376 Israel
Jamaican dolla
r
JMD 388 Jamaica
Japanese yen JPY 392 Japan
Jordanian dina
r
JOD 400 Jordan
Kenyan shilling KES 404 Kenya
Kina PGK 598 Papua New Guinea
Kip LAK 418 Laos
Kroon EEK 233 Estonia
Kuwaiti dina
r
KWD 414 Kuwait
Kwacha MWK 454 Malawi
Kwacha ZMK 894 Zambia
Kwanza AOA 973 Angola
Kyat MMK 104 Myanmar
Lari GEL 981 Georgia
Latvian lats LVL 428 Latvia
Lebanese pound LBP 422 Lebanon
Lek ALL 008 Albania
Lempira HNL 340 Honduras
Leone SLL 694 Sierra Leone
Lesotho loti LSL 426 Lesotho
Liberian dolla
r
LRD 430 Liberia
Libyan dina
r
LYD 434 Libya
Lilangeni SZL 748 Swaziland
Lithuanian litas LTL 440 Lithuania
Malagasy ariary MGA 969 Madagascar
Malaysian ringgit MYR 458 Malaysia
Manat TMT 934 Turkmenistan
Mauritius rupee MUR 480 Mauritius
Metical MZN 943 Mozambique
Mexican peso MXN 484 Mexico
Mexican Unidad de Inversion
(UDI) (funds code) MXV 979 Mexico
Moldovan leu MDL 498 Moldova
Moroccan dirham MAD 504 Morocco, Western Sahara
Naira NGN 566 Nigeria
Nakfa ERN 232 Eritrea
Namibian dolla
r
NAD 516 Namibia
Nepalese rupee NPR 524 Nepal
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 105 5.28
Netherlands Antillean guilde
r
ANG 532 Netherlands Antilles
New Taiwan dolla
r
TWD 901 Taiwan and other islands that are under the effective
control of the Republic of China (ROC)
New Zealand dolla
r
NZD 554 Cook Islands, New Zealand, Niue, Pitcairn, Tokelau
Ngultrum BTN 064 Bhutan
No currency XXX 999
North Korean won KPW 408 North Korea
Norwegian krone NOK 578 Norway, Bouvet Island, Queen Maud Land, Peter I Island
Nuevo sol PEN 604 Peru
Ouguiya MRO 478 Mauritania
Pa'anga TOP 776 Tonga
Pakistan rupee PKR 586 Pakistan
Palladium (one troy ounce) XPD 964
Pataca MOP 446 Macau Special Administrative Region
Peso Uruguayo UYU 858 Uruguay
Philippine peso PHP 608 Philippines
Platinum (one troy ounce) XPT 962
Pound sterling GBP 826 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)
Pula BWP 072 Botswana
Qatari rial QAR 634 Qatar
Quetzal GTQ 320 Guatemala
Rial Omani OMR 512 Oman
Riel KHR 116 Cambodia
Romanian new leu RON 946 Romania
Rufiyaa MVR 462 Maldives
Rupiah IDR 360 Indonesia
Russian rouble RUB 643 Russia, Abkhazia, South Ossetia
Rwanda franc RWF 646 Rwanda
Saint Helena pound SHP 654 Saint Helena
Samoan tala WST 882 Samoa
Saudi riyal SAR 682 Saudi Arabia
Serbian dina
r
RSD 941 Serbia
Seychelles rupee SCR 690 Seychelles
Silver (one troy ounce) XAG 961
Singapore dolla
r
SGD 702 Singapore, Brunei
Solomon Islands dolla
r
SBD 090 Solomon Islands
Som KGS 417 Kyrgyzstan
Somali shilling SOS 706 Somalia
Somoni TJS 972 Tajikistan
South African rand ZAR 710 South Africa
South Korean won KRW 410 South Korea
Special Drawing Rights XDR 960 International Monetary Fund
Sri Lanka rupee LKR 144 Sri Lanka
Sudanese pound SDG 938 Sudan
Surinam dolla
r
SRD 968 Suriname
Swedish krona/krono
r
SEK 752 Sweden
Swiss franc CHF 756 Switzerland, Liechtenstein
Syrian pound SYP 760 Syria
Tanzanian shilling TZS 834 Tanzania
Tenge KZT 398 Kazakhstan
Trinidad and Tobago dolla
r
TTD 780 Trinidad and Tobago
Tugrik MNT 496 Mongolia
Tunisian dina
r
TND 788 Tunisia
Turkish lira TRY 949 Turkey, Northern Cyprus
Uganda shilling UGX 800 Uganda
UIC franc (special settlement
currency) XFU Nil International Union of Railways
Unidad de Fomento (funds
code) CLF 990 Chile
Unidad de Valor Real COU 970 Colombia
United Arab Emirates dirham AED 784 United Arab Emirates
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 106 5.28
United States dollar (next day)
(funds code) USN 997 United States
United States dollar (same day)
(funds code) (one source[who?]
claims it is no longer used, but
it is still on the ISO 4217-MA
list)
USS 998 United States
US dolla
r
USD 840 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 som UZS 860 Uzbekistan
V
atu VUV 548 Vanuatu
V
enezuelan bolívar fuerte VEF 937 Venezuela
V
ietnamese đồng VND 704 Vietnam
WIR euro (complementary
currency) CHE 947 Switzerland
WIR franc (complementary
currency) CHW 948 Switzerland
Yemeni rial YER 886 Yemen
Zimbabwe dolla
r
ZWL 932 Zimbabwe
Złoty PLN 985 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 107 5.28
APPENDIX C – Country Codes ISO 3166
Official country names used by the ISO 3166/MA Numeric Alpha-3 Alpha-2
Afghanistan 004 AFG AF
Åland Islands 248 ALA AX
Albania 008 ALB AL
Algeria 012 DZA DZ
American Samoa 016 ASM AS
Andorra 020 AND AD
Angola 024 AGO AO
Anguilla 660 AIA AI
Antarctica 010 ATA AQ
Antigua and Barbuda 028 ATG AG
Argentina 032 ARG AR
Armenia 051 ARM AM
Aruba 533 ABW AW
Australia 036 AUS AU
Austria 040 AUT AT
Azerbaijan 031 AZE AZ
Bahamas 044 BHS BS
Bahrain 048 BHR BH
Bangladesh 050 BGD BD
Barbados 052 BRB BB
Belarus 112 BLR BY
Belgium 056 BEL BE
Belize 084 BLZ BZ
Benin 204 BEN BJ
Bermuda 060 BMU BM
Bhutan 064 BTN BT
Bolivia 068 BOL BO
Bosnia and Herzegovina 070 BIH BA
Botswana 072 BWA BW
Bouvet Island 074 BVT BV
Brazil 076 BRA BR
British Indian Ocean Territory 086 IOT IO
Brunei Darussalam 096 BRN BN
Bulgaria 100 BGR BG
Burkina Faso 854 BFA BF
Burundi 108 BDI BI
Cambodia 116 KHM KH
Cameroon 120 CMR CM
Canada 124 CAN CA
Cape Verde 132 CPV CV
Cayman Islands 136 CYM KY
Central African Republic 140 CAF CF
Chad 148 TCD TD
Chile 152 CHL CL
China 156 CHN CN
Christmas Island 162 CXR CX
Cocos (Keeling) Islands 166 CCK CC
Colombia 170 COL CO
Comoros 174 COM KM
Congo 178 COG CG
Congo, Democratic Republic of the 180 COD CD
Cook Islands 184 COK CK
Costa Rica 188 CRI CR
Côte d'Ivoire 384 CIV CI
Croatia 191 HRV HR
Cuba 192 CUB CU
Cyprus 196 CYP CY
Czech Republic 203 CZE CZ
Denmark 208 DNK DK
Djibouti 262 DJI DJ
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 108 5.28
Dominica 212 DMA DM
Dominican Republic 214 DOM DO
Ecuado
r
218 ECU EC
Egypt 818 EGY EG
El Salvado
r
222 SLV SV
Equatorial Guinea 226 GNQ GQ
Eritrea 232 ERI ER
Estonia 233 EST EE
Ethiopia 231 ETH ET
Falkland Islands (Malvinas) 238 FLK FK
Faroe Islands 234 FRO FO
Fiji 242 FJI FJ
Finland 246 FIN FI
France 250 FRA FR
French Guiana 254 GUF GF
French Polynesia 258 PYF PF
French Southern Territories 260 ATF TF
Gabon 266 GAB GA
Gambia 270 GMB GM
Georgia 268 GEO GE
Germany 276 DEU DE
Ghana 288 GHA GH
Gibralta
r
292 GIB GI
Greece 300 GRC GR
Greenland 304 GRL GL
Grenada 308 GRD GD
Guadeloupe 312 GLP GP
Guam 316 GUM GU
Guatemala 320 GTM GT
Guernsey 831 GGY GG
Guinea 324 GIN GN
Guinea-Bissau 624 GNB GW
Guyana 328 GUY GY
Haiti 332 HTI HT
Heard Island and McDonald Islands 334 HMD HM
Holy See (Vatican City State) 336 VAT VA
Honduras 340 HND HN
Hong Kong 344 HKG HK
Hungary 348 HUN HU
Iceland 352 ISL IS
India 356 IND IN
Indonesia 360 IDN ID
Iran, Islamic Republic o
f
364 IRN IR
Iraq 368 IRQ IQ
Ireland 372 IRL IE
Isle of Man 833 IMN IM
Israel 376 ISR IL
Italy 380 ITA IT
Jamaica 388 JAM JM
Japan 392 JPN JP
Jersey 832 JEY JE
Jordan 400 JOR JO
Kazakhstan 398 KAZ KZ
Kenya 404 KEN KE
Kiribati 296 KIR KI
Korea, Democratic People's Republic o
f
408 PRK KP
Korea, Republic o
f
410 KOR KR
Kuwait 414 KWT KW
Kyrgyzstan 417 KGZ KG
Lao People's Democratic Republic 418 LAO LA
Latvia 428 LVA LV
Lebanon 422 LBN LB
Lesotho 426 LSO LS
Liberia 430 LBR LR
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 109 5.28
Libyan Arab Jamahiriya 434 LBY LY
Liechtenstein 438 LIE LI
Lithuania 440 LTU LT
Luxembourg 442 LUX LU
Macao 446 MAC MO
Macedonia, the former Yugoslav Republic o
f
807 MKD MK
Madagasca
r
450 MDG MG
Malawi 454 MWI MW
Malaysia 458 MYS MY
Maldives 462 MDV MV
Mali 466 MLI ML
Malta 470 MLT MT
Marshall Islands 584 MHL MH
Martinique 474 MTQ MQ
Mauritania 478 MRT MR
Mauritius 480 MUS MU
Mayotte 175 MYT YT
Mexico 484 MEX MX
Micronesia, Federated States o
f
583 FSM FM
Moldova, Republic o
f
498 MDA MD
Monaco 492 MCO MC
Mongolia 496 MNG MN
Montenegro 499 MNE ME
Montserrat 500 MSR MS
Morocco 504 MAR MA
Mozambique 508 MOZ MZ
Myanma
r
104 MMR MM
Namibia 516 NAM NA
Nauru 520 NRU NR
Nepal 524 NPL NP
Netherlands 528 NLD NL
Netherlands Antilles 530 ANT AN
New Caledonia 540 NCL NC
New Zealand 554 NZL NZ
Nicaragua 558 NIC NI
Nige
r
562 NER NE
Nigeria 566 NGA NG
Niue 570 NIU NU
Norfolk Island 574 NFK NF
Northern Mariana Islands 580 MNP MP
Norway 578 NOR NO
Oman 512 OMN OM
Pakistan 586 PAK PK
Palau 585 PLW PW
Palestinian Territory, Occupied 275 PSE PS
Panama 591 PAN PA
Papua New Guinea 598 PNG PG
Paraguay 600 PRY PY
Peru 604 PER PE
Philippines 608 PHL PH
Pitcairn 612 PCN PN
Poland 616 POL PL
Portugal 620 PRT PT
Puerto Rico 630 PRI PR
Qata
r
634 QAT QA
Réunion 638 REU RE
Romania 642 ROU RO
Russian Federation 643 RUS RU
Rwanda 646 RWA RW
Saint Helena 654 SHN SH
Saint Kitts and Nevis 659 KNA KN
Saint Lucia 662 LCA LC
Saint Pierre and Miquelon 666 SPM PM
Saint Vincent and the Grenadines 670 VCT VC
© 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 Document name
Public
ML Web Service Guide
Date
May 2011
Phone Page number Version
08444 828 200 110 5.28
Samoa 882 WSM WS
San Marino 674 SMR SM
São Tomé and Príncipe 678 STP ST
Saudi Arabia 682 SAU SA
Senegal 686 SEN SN
Serbia 688 SRB RS
Seychelles 690 SYC SC
Sierra Leone 694 SLE SL
Singapore 702 SGP SG
Slovakia 703 SVK SK
Slovenia 705 SVN SI
Solomon Islands 090 SLB SB
Somalia 706 SOM SO
South Africa 710 ZAF ZA
South Georgia and the South Sandwich Islands 239 SGS GS
Spain 724 ESP ES
Sri Lanka 144 LKA LK
Sudan 736 SDN SD
Suriname 740 SUR SR
Svalbard and Jan Mayen 744 SJM SJ
Swaziland 748 SWZ SZ
Sweden 752 SWE SE
Switzerland 756 CHE CH
Syrian Arab Republic 760 SYR SY
Taiwan, Province of China 158 TWN TW
Tajikistan 762 TJK TJ
Tanzania, United Republic o
f
834 TZA TZ
Thailand 764 THA TH
Timo
r
-Leste 626 TLS TL
Togo 768 TGO TG
Tokelau 772 TKL TK
Tonga 776 TON TO
Trinidad and Tobago 780 TTO TT
Tunisia 788 TUN TN
Turkey 792 TUR TR
Turkmenistan 795 TKM TM
Turks and Caicos Islands 796 TCA TC
Tuvalu 798 TUV TV
Uganda 800 UGA UG
Ukraine 804 UKR UA
United Arab Emirates 784 ARE AE
United Kingdom 826 GBR GB
United States 840 USA US
United States Minor Outlying Islands 581 UMI UM