Web Services Integration Guide V5.28 May 2011

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

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

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

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

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

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.

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.

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.

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.

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.

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

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.

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.

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/

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.

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

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.

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

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

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

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>

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

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

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.

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)

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>

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

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

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>

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

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>

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

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>

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

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>

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

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

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:

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.

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

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

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:

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:

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.

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

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

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

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

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

merchantreference String

Varchar(50) Merchant can add a reference to cross

reference responses relating to the

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

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

merchantreference String Merchant can add a reference to cross reference

responses relating to the same transaction

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

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

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

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

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>

</ClientHeader>

<MsgType xmlns="https://www.commidea.webservices.com">RELEASEONHOLDREQUEST</MsgType>

<![CDATA[<releaseonholdrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="ONHOLD">

<authdb>TEST_AUTHDB2</authdb>

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

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

xmlns="ONHOLD"><result>RELEASED</result><mktransactionid>1969925</mktrans

actionid><authdb>TEST_AUTHDB2</authdb></releaseonholdresponse></MsgData></P

rocessMsgResult></ProcessMsgResponse></soap:Body></soap:Envelope>

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.

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

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

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,

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.

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

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,

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

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

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>

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

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>

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

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

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>

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

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

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.

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

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

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

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>

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

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

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.

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>

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

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>

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

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>

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

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

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

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

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

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

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>

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

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>

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

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

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

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>

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

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>

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

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>

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

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>

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

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

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

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

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.

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

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

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>

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

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>

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

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>

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

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

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>

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

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>

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

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>

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

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>

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

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>

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

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>

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

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>

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

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

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

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.

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

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

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

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

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>

<InternalError>[16277] TransactionProcessor.DeserializeXml: Bad Format in

TRecord_Pan</InternalError>

</CommideaTxnResponse>

</CardTxnResponse>

</soap:Body>

</soap:Envelope>

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

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

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

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

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

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,

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

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

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

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

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

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

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

Uruguay 858 URY UY

Uzbekistan 860 UZB UZ

V

anuatu 548 VUT VU

V

enezuela 862 VEN VE

V

iet Nam 704 VNM VN

V

irgin Islands, British 092 VGB VG

V

irgin Islands, U.S. 850 VIR VI

Wallis and Futuna 876 WLF WF

Western Sahara 732 ESH EH

Yemen 887 YEM YE

Zambia 894 ZMB ZM

Zimbabwe 716 ZWE ZW

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

APPENDIX D – Performing a LUHN Check

The following steps are involved in this calculation:

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

order).

Step 2 Add the individual digit comprising the products obtained in Step 1 to each of the

unaffected digits in the original number.

Step 3 Subtract the total obtained in Step 2 from the next higher number ending in 0 (this

is the equivalent of calculating the “ten complement” of the low order digit (unit digit) of the

total). If the total obtained in Step 2 is a number ending in zero (30, 40, etc.), the check digit is

0.

Example:

Account Number without check digit 4929 123 123 12

Step 1

4 9 2 9 1 2 3 1 2 3 1 2

X2 X2 X2 X2 X2 X2

4 18 2 18 1 4 3 2 2 6 1 4

Step 2

4+1+8+2+1+8+1+4+3+2+2+6+1+4= 47

Step 3

50 – 47 = 3

Therefore check digit is 3 and complete card number is 4929 123 123 123

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

APPENDIX E – Commidea Error Codes

Error

Code General Description Additional Technical Description

(if required) Recommended Action

0001 Unspecified error Contact Commidea

0002 Invalid transaction type An example of this could be a

Refund being passed when the site

are not set up to do so. A trace of

what was passed will be in the

system log.

Use alternative method for transaction

type.

0003 Invalid card / invalid Track2 General card error. Track2 must

either be ;PAN=YYMMsss……?x or

just the PAN.

Re-enter card number or re-swipe card

0004 Card scheme not recognised The card Issuer Identification

Number (IIN) has not been located

in the IIN table. The IIN is typically

the first 4 to 6 digits of the card

number.

Prompt for alternate method of

payment

0005 Card scheme not accepted The card has been identified, but

the card scheme is not accepted at

the given site.

Reject Transaction

0006 Invalid card number (lcd) The LUHN check digit is incorrect

(the card has been mis-keyed or

mis-swiped).

Re-enter card number or re-swipe card

0007 Invalid card number length The length of the PAN is incorrect

for the given card scheme. Re-enter card number or re-swipe card

0008 Invalid card number (pcd) The pen-ultimate check digit is

invalid. Re-enter card number or re-swipe card

0009 Expired card Prompt for alternate method of

payment

0010 Card not yet valid Prompt for alternate method of

payment

0011 Invalid card service code The Track2 service code is invalid. Prompt for alternate method of

payment

0012 File or XML missing or wrong

format A required file or XML is missing or

has wrong format. Contact Commidea

0013 File permanently locked A file required by the EFT library

was still locked after EFT FIO

TRIES attempts.

Contact Commidea

0014 Out of memory The library has failed to allocate

sufficient heap. Contact Commidea

0015 Account number does not

exist The requested account number

does not exist. Check the account number

configuration of the system, ensuring it

matches that configured within WinTI

0016 Value exceeds ceiling limit Purchase value exceeds card

scheme ceiling limit Prompt for alternative method of

payment.

Arrange to increase ceiling limits

0017 Cashback exceeds ceiling limit Cashback value exceeds card

scheme ceiling limit Revise transaction cash-back value

0018 Transaction currency is invalid The transaction currency code is

invalid or incorrect for the given

site.

0019 Lay aways are not allowed Attempt to lay away invalid / lay

aways are not allowed

0020 Lay away already stored Attempt to lay away a transaction

where there is already a

transaction laid away on that card

Prompt for alternate method of

payment

0021 EFT system not configured The EFT system has not been

configured

0022 Internal error, buffer too small A buffer is too small

0023 Unknown comms device type Invalid / unknown communications

device type Check communications configuration

0024 Configuration file is invalid Configuration file is invalid / bad

format Check system configuration

0025 No valid accounts There are no valid accounts

specified in the TillInfo.cfg Check system configuration

0026 Invalid channel Invalid channel Check>

· 2 transactions aren’t being passed

down the same channel.

· 2 tills aren’t using the same channel

number.

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

· WinTI EFTChans within the registry

has enough available channels set

(Socket mode only).

0027 System error –module not

loaded System error (Track2 check

module has not been loaded)

0028 General transaction error Re-enter transaction

0029 Transaction store unavailable Transaction store unavailable Check Live Store.

Check hard disk space.

0030 Unspecified error Unspecified error Check system log for indication of

error.

0031 Unspecified error:2 Transaction cancelled Channel available for next transaction

0032 Library not open EFT library is unavailable

0033 Possible text for error:

<fieldname> (<fieldno>)

should be X to Y characters in

length.

<fieldname> out of range,

should be X to Y.

<fieldname> out of tolerance,

is X, should be X +/- Z.

Line discount not available for

Cendant cards.

Line count (X) doesn’t match

header -> CPC lines (Y).

Separate post and packing

only on Amex cards.

Where <fieldname> = part

number, part description,

commodity code, unit of

measure, quantity, net value,

VAT amount, gross value,

PAN, PO number, customer

number, customer name,

customer VAT no, destination

zip, destination country code,

order date, original invoice

number, cost centre, invoice

net amount, invoice VAT

amount, post and packing

VAT, invoice gross or

transaction total.

Invalid CPC data

The error message is made up of a

combination of text (1 to 6) with the

applicable field name inserted, as

applicable.

For example:

Net value out of tolerance, is

123.45, should be 123.00 +/- 1

0034 Modifier field invalid/missing As the modifier is passed within the

T record the host software is likely

to be the cause of this

0035 Invalid card / invalid Track 1 Track 1 is invalid Re-swipe card

0036 Invalid card / invalid Track 3 Track 3 is invalid Re-swipe card

0037 Invalid / missing expiry date The expiry date is either invalid or

missing. If key entered, the format

should be MMYY

Re-enter expiry date or re-swipe card

0038 Invalid / missing issue number The issue number is either invalid

(value or length) or missing Re-enter issue number or re-swipe

card

0039 Invalid / missing start date The start date is either invalid or

missing. If key entered, the format

should be MMYY.

Re-enter start date or re-swipe card

0040 Purchase/refund value bad or

missing The transaction value is either

invalid or missing Re-enter transaction

0041 Cash-back value bad or

missing The cash-back value is either

invalid or missing Re-enter transaction

0042 Auth code value bad or

missing The authorisation code is either

invalid or missing

0043 Cheque account number value

bad or missing The cheque account number is

either invalid or missing Re-enter cheque account number

0044 Invalid cheque sort code The cheque sort code is either

invalid or missing Re-enter sort code

0045 Invalid / missing cheque

number Re-enter cheque number

0046 Invalid / missing cheque type Re-enter cheque type

0047 Invalid EFT serial number The EFT serial number is either

invalid or missing in the .Cnf file Re create *.cnf

0048 Unexpected CPC data Purchasing card invoice data has

been presented for a non- Re-enter transaction without invoice

data or prompt for a valid Purchasing

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

Purchasing Card (where invoice

data is not valid/required) Card

0049 Transaction already confirmed

or rejected Attempt to confirm or reject a

transaction, which has already

been confirmed or rejected

0050 Copy protection failure Could be a permission problem on

the PC

0051 Post confirm reversal not

allowed for PWCB or Cash

Advance (reserved for future

use)

Attempt to perform a post confirm

reversal on a PWCB or Cash

Advance has been dis-allowed (as

post confirm reversals are not

supported when cash is involved)

Reverse transaction manually (as cash

is involved)

0052 Transaction data supplied in

post conf rev not consistent

with store (reserved for future

use)

The details supplied in the post

confirm reversal message is not

consistent with the data stored for

the transaction to be reversed

0053 Transaction already void Attempt to perform a post

transaction reversal has failed

because the transaction has

already been voided/reversed

0054 Card on hot list The card number is on the locally

stored host list (received from the

acquirer and/or entered by the

customer). The card must be

rejected

Prompt for alternate method of

payment

0055 Attempt to confirm a declined

transaction The format of the confirmation

message is invalid (confirming a

declining transaction). The

confirmation message should

contain a command value of 2

(reverse/reject) and not a value of 1

(confirm).

0056 EFT_ERR_BAD_CV2 CV2 is invalid Check CV2 and re-enter

0057 EFT_ERR_BAD_AVS AVS is invalid Check AVS and re-enter

0058 Invalid Merchant Details Merchant Details passed in XML

Gateway are Invalid. Check both the GUID and Passcode

information that being passed to the

XML Gateway

0059 Invalid Mobile Number Format The Mobile Number format passed

is incorrect Please check and re-enter the mobile

number supplied.

0060 Invalid/missing bank account

number The bank account number within

the supplied T-Record is incorrect. Check the bank number being passed

and re-enter as necessary.

0062 Token does not exist or invalid

token for this merchant system The Token ID supplied is incorrect

or invalid for the merchant system Check the Token ID is correct and for

use with the current merchant system

0064 Unexpected / Invalid

Authorisation Response Unexpected / Invalid Authorisation

Response from M-Voucher Host Please contact Commidea Support

0065 Invalid voucher target type The Target Voucher Type is invalid

(M-Voucher) Please contact Commidea Support

0066 Invalid Refund Pin The refund pin entered is invalid Please enter the correct refund pin if

continues to fail, please contact

Commidea Support

0067 Report Not Supported The Report ID supplied is either

invalid or does not correspond to a

report that is supported

Check the Report ID that is being

passed

0068 Report Failed Integrated report failed Contact Commidea

0069 Gratuity value exceeded Check Gratuity Value Check Gratuity Value

0070 Invalid Capture Not

Supported Check Ocius settings Capture Method Not Set correctly

0071 Cashback not allowed by card Card does not allow cashback Use a different card or proceed without

cashback

0072 Cash advance not allowed by

card Card does not allow cash advance Use a different card

0073 Max refund value exceeded Refund transaction value is greater

than the maximum refund value set

on the account

Reduce transaction value

0074 Bill Already Complete The bill being cancelled is already

completed and therefore cannot be

cancelled.

N\A

0075 No ETU accounts Attempt to process ETU transaction

without ETU accounts being

present on terminal

Contact Commidea

0076 Card is online only Attempt to process an online only

card whilst offline Check network or use another card

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

0077 Cancel Failed - In Payment on

xxx.xxx.xxx.xxx Attempt to cancel a lodged Bill

failed, usually locked on a specific

terminal

Leave for configured amount of time

before retrying cancel routine.

0078 Login failed User ID or PIN is incorrect Check login details and try again

0079 Confirmation Status Unknown An invalid confirmation response

has been received or the

confirmation message to be sent

was not saved

0080 Bill Reference Already Exists Attempt to lodge a Bill into I-Link

that already exists Clear the original Bill, or re-send this

one using an alternative reference.

0081 Print Report Failed The request report failed to

generate or print Check printer settings, network

connection and try again.

0082 Network Error Error in Network Check network.

0083 Invalid Record Invalid Record The record received is invalid.

0084 PED User already logged in A Login command has been

received, but a user is already

logged in

Log the terminal off first, or simply

pass a transaction.

0085 PED User not logged in The terminal needs to be logged in Send a login command to the terminal,

or manually login using the on-screen

prompts, then re-send the transaction.

0086 Submission of offline

transactions failed The submission of the offline stored

transactions have failed. The transactions will still be stored on

the terminal. Re-try, and if still having

problems contact The Merchant

Helpdesk.

0087 Problem in network There has been a problem in the

network.

0088 Voice Referral Timeout The voice referral transaction has

taken too long. Re-try or cancel.

0089 Invalid Account ID Invalid Account ID

0090 Service Not Allowed Service code not supported Use another card, or cancel the

transaction

0091 Card Not Accepted Card type not accepted Use another card, or cancel the

transaction

0092 Unknown Card Unknown card type Use another card, or cancel the

transaction

0093 Not In IIN Range Unknown card type Use another card, or cancel the

transaction

0094 Application Blocked The terminal cannot accept this

card type Use another card, or cancel the

transaction

0095 Card Blocked The card has been blocked. Use another card, or cancel the

transaction.

0096 Card Error There is a problem with the Card Re-try or use another card.

0097 Authorisation Error The authorisation process has

been interrupted or is not

responding.

Check ILink & WinTI are running – or

when using ICP, contact Commidea

Merchant Helpdesk.

0098 Unknown Client

Unknown Transaction Source

Unknown Message

When using transaction

processing, if no POS Routing has

been configured for the IP Address

or File Name where the transaction

originates from, ILink does not

know where to send the

transaction. It therefore rejects it

with this message.

Configure POS routing for that Point Of

Sale.

0099 Transaction/Bill Cancelled When a transaction has been

cancelled by the user, the system

or an ICC card, this error message

will be sent.

0100 Pin Bypass Failed ICC Card does not allow Pin

Bypass. Use another card.

0101 Invalid Terminal Country Code' The Terminal Country Code

passed is invalid Please check the ISO Country Codes

table and make sure the code being

passed is correct.

0102 User has no permissions on

specified account Check account permissions in

WebCom. Please contact Commidea Support

0103 Invalid Currency Code' The Currency Code passed is

invalid. Please check the ISO Currency Codes

table and make sure the code being

passed is correct.

0104 Invalid EMV Terminal Type' The EMV Terminal Type passed is

invalid Please check the EMV Terminal Type

that is being passed is valid.

0105 Unknown Message Type The message type received by

server side is not recognised Please contact Commidea Support

0106 General Enqueue Error General Commidea Enqueueing Please contact Commidea Support

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

Error

0107 Transaction Confirmation Error The transaction confirmation has

errored. Please retry the confirmation and if

continues to fail please contact

Commidea Support

0108 Payer Auth Error The Payer Auth has encountered

an error. Please check the error message

response and contact Commidea

support.

0109 Ukash Auth Error The Ukash transaction has

encountered an error. Please check the error message

response and Contact Commidea

Support.

0110 Encryption Failure An error has occurred in the data

encryption. Please contact Commidea Support

0111 Unable to build Auxillary Data

Record The auxillary data record failed to

build correctly Please contact Commidea Support

0112 Transaction rejection error The attempt to reject the

transaction has errored Please retry the rejection and if

continues to fail please contact

Commidea support

0113 Unknown Terminal The terminal\PTID is not

recognised Please contact Commidea Support

0114 Invalid Download Type The download type is invalid Please contact Commidea Support

0115 Terminal Registration Failed The attempt to register the terminal

has failed Please retry the registration if it

continues to fail, please contact

Commidea Support

0116 Terminal has been deactivated The terminal has been marked as

deactivated. Please contact Commidea Support

0117 Comms down Acquirer has been blocked in the

database as acquirer is not

processing any authorisations

(comms down)

Please contact Commidea Support

0118 M-Voucher Service

Unavailable This is when the terminal is in

offline mode at the start of a

transaction, and cannot connect to

the hosted server to allow M-

Voucher

Please contact Commidea Support

0119 Barclays Bonus Service

Unavailable Error response when Comms

failure between server application

and XLS Host experienced.

Please contact Commidea Support

0120 Token Server Error The Token Server has encountered

an error Please contact Commidea Support

0121 Purchase transaction type not

allowed on token The token provided does not allow

purchase transactions Please supply another token that

allows purchase transactions

0122 Refund transaction type not

allowed on token The token provided does not allow

refund transactions Please supply another token that

allows refund transactions

0123 Cashback transaction type not

allowed on token The token provided does not allow

cashback transactions Please supply another token that

allows cashback transactions

0124 Token expired The token provided has passed its

expiry date Please register a new token

0125 Invalid TokenID The token provided is invalid Please supply another token or contact

Commidea Support

0126 Token has no Txn Type

Permissions The Token Registration has no

transaction permissions Please resubmit the token request with

transaction permissions enabled

0127 Invalid Token expiration date The token expiration date provided

is invalid Please resubmit the token request with

a valid token expiration date

0128 ProcessingDB Missing or

Invalid The processing database that is

passed in the client header is either

missing or invalid.

Please check that the message you

are sending has the processing

database set in the client header and

that it is valid (as per the

transaction\payer auth request)

0129 Invalid Original Barclays Gift

Transaction ID The Original Gift Transaction ID

provided is invalid Please check the Original Transaction

ID and try again.

0130 Invalid Barclays Gift

Configuration Your Barclays Gift Configuration is

invalid Please check the configuration and

download to the terminal. If the

problem continues please contact

support.

0131 Barclays Gift Service

Unavailable The Barclays Gift Service is

temporarily unavailable Please contact Commidea Support

0132 Merchant Reference Required Your current configuration requires

a Merchant Reference to be

passed.

Please re-submit the transaction with

the Merchant Reference populated.

0133 Account On File Not Allowed Terminal is operating in offline

mode

Please check that the terminal is online

Please check the configuration of the

account

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

Account does not allow Account

On file CNP transactions

EFT transaction capture method

does not support registration of

details for Account On File

processing

Check the transaction details that you

have passed.

0134 Card not allowed to be keyed The card scheme doesn't allow

processing of keyed card numbers Use another card, or cancel the

transaction

0135 Timeout Waiting for Card A timeout has occurred whilst

waiting for the card and

Transactions has been cancelled

Reprocess Transaction.

0137 Present Cash Advance

Transaction As Purchase The card presented does not

support cash advance and needs

to be represented as a purchase

txn.

Reprocess Transaction as a purchase

0138 Gratuity Value Incorrect Check Gratuity Value Check Gratuity Value

0139 Transaction Timeout The application has timed out

waiting for a Barclays Gift response Please check whether the gift request

has gone through and if necessary

please try again.

0140 Schedule Payment registration

failed. The scheduled payment

registration has failed. Please attempt to re-register the

scheduled payment or contact

Commidea Support

0141 Ocius migration failed The Ocius migration failed on the

database because the migration

has not been setup / enabled

Contact Commidea to arrange for

migration

0150 Invalid PayPoint Configuration The PayPoint configuration that

you have setup is invalid. Please contact Commidea Support

0151 No PayPoint Accounts There are no PayPoint accounts

available. Please contact Commidea Support

0152 PayPoint Service Unavailable The PayPoint service is currently

unavailable Please retry the payment or contact

Commidea support

0153 PayPoint Download Required A PayPoint download is required Please perform a configuration file

update to your terminal

0154 PayPoint Account Extraction

Failed PayPoint account file extraction

has failed. Please retry the download if it

continues to fail please contact

Commidea Support

0155 PayPoint Transaction Type

Not Allowed The PayPoint transaction type

provide is not allowed Please check the Transaction Type

supplied and correct

0156 Invalid PayPoint TopUp Type The PayPoint TopUp type provided

is invalid Please check the TopUp Type

supplied and correct

0157 Invalid PayPoint Service

Provider The PayPoint Service Provider

provided is invalid Please check the Service Provider

supplied and correct

0158 Invalid PayPoint Scheme The PayPoint Scheme provided is

invalid Please check the Scheme supplied

and correct

0159 Invalid PayPoint Scheme

Option The PayPoint Scheme Option

provided is invalid Please check the Scheme Option

supplied and correct

0160 Invalid PayPoint Amount The PayPoint Amount provided is

invalid Please check the Amount supplied and

correct

0161 No PinPad Available The PinPad is currently unavailable Please check the PinPad is available

for use, please contact Commidea

Support if the problem persists.

0189 Invalid refund password An invalid refund password has

been supplied during the

transaction, and was rejected by

the database

Please contact Commidea Support

0999 Token Server Error Start date or issue data supplied is

incorrect or missing Please check you are passing the

appropriate required fields

1000 Generic Error Generic Capture Error Please contact Commidea Support

1001 Merchant Supplied Bad Data The information supplied in the

post is incorrect Please check the data that you are

sending and retry.

1002 Bad Source URL The source URL is unrecognised Please contact Commidea Support

1003 Attempting to use a TokenID

and a PAN at the same time A TokenID and PAN were received

for the same transaction Please check the data that is being

passed

1004 Curl Error Communication Error Please contact Commidea Support

1005 Couldn't Extract Error Code

from Response The error code returned could not

be extracted Please contact Commidea Support

1006 Failed to Retrieve System

Config PayPage has failed to retrieve your

System Configuration Please contact Commidea Support

1007 Unusual Data Supplied

(Possible Attack) The data that has been supplied is

suspicious Please check the data that you are

sending and contact Commidea

support

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

or in part without the express permission of Point International prohibited.

1008 Failed to Retrieve Session

Data PayPage has failed to retrieve your

session data Please retry the payment or contact

Commidea support

1009 Failed to Create New Session PayPage has failed to create a new

session Please retry the payment or contact

Commidea support

1010 Bad SessionID received from

end user The sessionID provided by the front

end is incorrect. Please check the data that you are

sending and retry.

1011 Bad PIN received from end

user The PIN provided by the front end

is incorrect. Please check the data that you are

sending and retry.

1012 Session Finished The session that you are trying to

use has already finished. Please retry the payment or contact

Commidea support

1013 Failed to extract PA Data An error has occurred trying to

decrypt\extract the Payer Auth data Please retry the payment or contact

Commidea support

1014 Session Expired The session that you are trying to

use has expired. Please retry the payment or contact

Commidea support

Web Services Integration Guide V5.28 May 2011

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

Navigation menu

Versions of this User Manual:

Views

Navigation