web services integration guide -...
TRANSCRIPT
Web Services Integration Guide - V1.9 – 20th February 2014 1
Web Services Integration Guide
Web Services Integration Guide – V2.0 – 30th July 2014 2
Revision History The following table summarises the main changes made to this document:
Ver. Author Date Comments
V2.0 ND Jul 2014 - Added details on VAAD changes - Updated descriptions of tokenID and processingdb fields - Updated description of auth code field
V1.9 ND Feb 2014 - Added further details on Account Check Transaction Type - Updated document with new naming conventions; Sentinel to POS Client
and PayPage to Payment Page. - Updated Chargeback Information - IIN Lookup Service updated - Amended On-Hold & Release and PAN Hash examples
V1.8 ND Dec 2013 - PAN Hash Service request example corrected - Updated field descriptions of On-Hold and Release request - Updated description On-Hold & Release Functionality
V1.7 JS Nov 2013 - Document rebrand - Amendments to offline transaction response, token and PAN Hash
messages - On-Hold and Release functionality description amended - Token Error code included
V1.6 ND Mar 2013 - Updated document in-line with solution branding - Dynamic Currency Conversion (DCC) detailed - IIN Lookup service detailed - Offline to Online Token detailed - Updated ReD Fraud Request with new field (‘orderid’) & other validation
fields - Description on ‘processingdb’ field added under Session-Based section - Removed fields ‘mcmmerchantpassword’ & ‘visamerchantpassword’ as
now obsolete
Web Services Integration Guide – V2.0 – 30th July 2014 3
Table of Contents Revision History ......................................................................................................................... 2
Introduction .............................................................................................................................. 10
Element Usage ........................................................................................................................ 10
Integration ................................................................................................................................ 11
Integration Process .................................................................................................................. 12
Message Formats .................................................................................................................... 12
Account Check Transaction Type ......................................................................................... 13
VeriFone Timeouts ................................................................................................................... 15
Integration Testing ................................................................................................................... 16
Testing URLs ........................................................................................................................... 17
Live URLs ................................................................................................................................ 17
Merchant Advice to Cardholders .............................................................................................. 18
Security Methods ..................................................................................................................... 19
Token Registration ................................................................................................................... 19
Offline to Online Token ............................................................................................................ 19
Token Payments ...................................................................................................................... 19
Payer Authentication (PayerAuth) ............................................................................................ 21
PayerAuth Expiry .................................................................................................................. 24
Excluded Card Types ........................................................................................................... 24
Process Transaction ............................................................................................................. 24
Payer Authentication with Token .......................................................................................... 24
Chargeback Information ....................................................................................................... 25
Cardholder Authentication Implementation Guidelines ......................................................... 25
PayerAuth Decisions ............................................................................................................ 26
Visa Additional Authorisation Data (VAAD) .............................................................................. 27
Data Required ...................................................................................................................... 27
Encryption ............................................................................................................................ 28
Account on File (Tokenisation) ............................................................................................. 28
Non-supported Card Schemes ............................................................................................. 28
Integration Changes ............................................................................................................. 28
Auxiliary Record ................................................................................................................... 29
Web Services Integration Guide – V2.0 – 30th July 2014 4
Validation ............................................................................................................................. 31
Error Codes .......................................................................................................................... 31
Optional Functionalities ............................................................................................................ 35
Customer Specific Hash ........................................................................................................... 35
On-Hold and Release Functionality .......................................................................................... 35
PAN Hash Service ................................................................................................................... 35
Procurement Cards (VGIS) ...................................................................................................... 36
IIN Lookup Service ................................................................................................................... 36
Session-Based ......................................................................................................................... 37
Overview .................................................................................................................................. 37
Sessions .................................................................................................................................. 37
Card Capture Process .......................................................................................................... 38
Full & Partial Capture Options .............................................................................................. 39
Transaction Process ................................................................................................................ 40
Session-Based Message Formats ........................................................................................... 41
Message............................................................................................................................... 41
Client Header ....................................................................................................................... 41
Processing DB Field ............................................................................................................. 41
Generate Session .................................................................................................................... 41
Generate Session Request................................................................................................... 42
Generate Session Response ................................................................................................ 42
Generate Session Example .................................................................................................. 42
Card Capture Page .................................................................................................................. 43
Post Fields ........................................................................................................................... 43
HTML Example..................................................................................................................... 44
Get Card Details ...................................................................................................................... 45
Get Card Details Request ..................................................................................................... 45
Get Card Details Response .................................................................................................. 45
Get Card Details Example .................................................................................................... 46
PayerAuth Message Types ...................................................................................................... 47
Enrollment Check Request ................................................................................................... 47
Enrollment Check Response ................................................................................................ 48
Enrollment Example ............................................................................................................. 49
Web Services Integration Guide – V2.0 – 30th July 2014 5
Authentication Check Request ............................................................................................. 50
Authentication Check Response ........................................................................................... 50
Authentication Example ........................................................................................................ 51
Token Registration ................................................................................................................... 52
Token Registration Request ................................................................................................. 52
Token Registration Response .............................................................................................. 53
Token Registration Example................................................................................................. 53
EFT Transaction ...................................................................................................................... 54
Transaction Request ............................................................................................................ 54
Transaction Response .......................................................................................................... 56
Transaction Request Example .............................................................................................. 58
Transaction Response Example ........................................................................................... 58
Confirmation Request .............................................................................................................. 59
Rejection Request .................................................................................................................... 59
Confirmation Example .......................................................................................................... 60
Non-Session-Based ................................................................................................................. 61
Overview .................................................................................................................................. 61
Process Flow ........................................................................................................................ 62
Non-Session-Based Message Formats .................................................................................... 63
Message............................................................................................................................... 63
ClientHeader ........................................................................................................................ 63
Processing DB Field ............................................................................................................. 65
Error Response .................................................................................................................... 65
EFT Transaction ...................................................................................................................... 66
Transaction Request ............................................................................................................ 66
ICC Data .............................................................................................................................. 69
PayerAuth AuxiliaryData ....................................................................................................... 71
Confirmation Request ........................................................................................................... 72
Rejection Request ................................................................................................................ 73
Transaction Response .......................................................................................................... 74
Transaction Results .............................................................................................................. 76
PayerAuth ................................................................................................................................ 77
PayerAuth EnrollmentCheck Request .................................................................................. 77
Web Services Integration Guide – V2.0 – 30th July 2014 6
PayerAuth EnrollmentCheck Response ................................................................................ 79
PayerAuth AuthenticationCheck Request ............................................................................. 80
PayerAuth AuthenticationCheck Response .......................................................................... 81
Token Gateway ........................................................................................................................ 82
Registration Request (TKI) ................................................................................................... 82
Token Registration Response (TKI) ...................................................................................... 83
Registration Request (TKI2) ................................................................................................. 83
Token Registration Response (TKI2) – Success .................................................................. 84
Token Registration Response (TKI2) – Failure ..................................................................... 84
Offline to Online Token ............................................................................................................ 85
Offline to Online Request ..................................................................................................... 85
Offline to Online Response ................................................................................................... 85
On-Hold & Release Message Types ........................................................................................ 86
Release Request .................................................................................................................. 86
Request Example ................................................................................................................. 87
Release Response ............................................................................................................... 88
Response Example .............................................................................................................. 88
PAN Hash Service ................................................................................................................... 89
Hash Request ...................................................................................................................... 89
Request Example ................................................................................................................. 89
Hash Response .................................................................................................................... 90
Response Example .............................................................................................................. 90
IIN Lookup Service ................................................................................................................... 91
IIN Request .......................................................................................................................... 91
IIN Response ....................................................................................................................... 91
Value Added Services .............................................................................................................. 96
PayPal ..................................................................................................................................... 96
Express Checkout Process .................................................................................................. 96
PayPal Sandbox and Testing ............................................................................................... 97
Grant PayPal API Permissions ............................................................................................. 98
SVS (Stored Value Solutions) .................................................................................................100
Part Payments .....................................................................................................................100
Transax SV (Stored Value) .....................................................................................................101
Web Services Integration Guide – V2.0 – 30th July 2014 7
Duplication Checking ...........................................................................................................101
Ukash .....................................................................................................................................102
Fraud Screening .....................................................................................................................103
Card Types ..........................................................................................................................103
DCC (Dynamic Currency Conversion) .....................................................................................104
Card Schemes Supported ...................................................................................................104
Currencies Supported..........................................................................................................104
E-Receipts ...........................................................................................................................104
Transaction Flow.....................................................................................................................105
Value-added Services Message Formats ................................................................................106
Message..............................................................................................................................106
ClientHeader .......................................................................................................................106
Processing DB Field ............................................................................................................107
Error Response ...................................................................................................................107
PayPal Message Formats .......................................................................................................108
SetExpressCheckout Request .............................................................................................108
SetExpressCheckout Response ..........................................................................................113
GetExpressCheckoutDetails Request ..................................................................................114
GetExpressCheckoutDetails Response ...............................................................................115
DoExpressCheckoutPayment Request ................................................................................117
PayPal ExpressItem ............................................................................................................120
DoExpressCheckoutPayment Response .............................................................................121
DoAuthorization Request .....................................................................................................123
DoAuthorization Response ..................................................................................................124
DoCapture Request .............................................................................................................125
DoCapture Response ..........................................................................................................127
DoVoid Request ..................................................................................................................129
DoVoid Response ...............................................................................................................130
RefundTransaction Request ................................................................................................130
RefundTransaction Response .............................................................................................131
DoReauthorization Request.................................................................................................131
DoReauthorization Response ..............................................................................................132
Stored Value Solutions (SVS) Message Formats ....................................................................133
Web Services Integration Guide – V2.0 – 30th July 2014 8
SVS Request .......................................................................................................................133
SVS Confirmation ................................................................................................................134
SVS Response ....................................................................................................................135
Transax SV Message Formats ................................................................................................136
Transax SV Request ...........................................................................................................136
Card Details ........................................................................................................................137
Transax SV Response .........................................................................................................138
Transax SV Request Example .............................................................................................139
Transax SV Confirmation ....................................................................................................140
Transax SV Final Result ......................................................................................................141
Transax SV Confirmation Example ......................................................................................141
Ukash Message Formats ........................................................................................................142
Ukash GetSettleAmount Request ........................................................................................142
Ukash PartSpendVoucher Request .....................................................................................143
Ukash FullValueVoucher Request .......................................................................................144
Ukash PartSpendAccount Request .....................................................................................145
Ukash FullSpendAccount Request ......................................................................................146
TransactionEnquiry Request ...............................................................................................147
Ukash Response .................................................................................................................148
Ukash Return Code List ......................................................................................................149
Ukash Transaction Type List ...............................................................................................149
Ukash Error Code List .........................................................................................................150
Ukash Product Codes..........................................................................................................151
Fraud Screening Message Formats ........................................................................................153
Accepted Characters ...........................................................................................................153
ReD Fraud Request ............................................................................................................154
Customer Details .................................................................................................................155
Shipping Details ..................................................................................................................156
Custom Data .......................................................................................................................156
192 Data..............................................................................................................................157
Recipient Data .....................................................................................................................159
Product Data .......................................................................................................................159
Repeated Data Header ........................................................................................................160
Web Services Integration Guide – V2.0 – 30th July 2014 9
Request Examples ..................................................................................................................160
Session-Based Example .....................................................................................................160
Non-Session-Based Example ..............................................................................................162
ReD Fraud Response ..........................................................................................................163
Response Example .............................................................................................................164
Dynamic Currency Conversion (DCC) Message Formats .......................................................165
DCC Request ......................................................................................................................165
DCC Request Example .......................................................................................................166
DCC Response ...................................................................................................................167
DCC Response Example .....................................................................................................168
Troubleshooting ......................................................................................................................169
Deserialization Errors ..........................................................................................................169
APPENDIX A VeriFone Error Codes .......................................................................................170
APPENDIX B Currency Code ISO 4217 ..................................................................................177
APPENDIX C Country Codes ISO 3166 .................................................................................181
APPENDIX D ..........................................................................................................................186
Performing a LUHN Check ..................................................................................................186
APPENDIX E Payer Authentication Decisions ...................................................................187
Non Supporting Card Schemes ...........................................................................................189
APPENDIX F ..........................................................................................................................190
DCC Online Screen Examples ................................................................................................190
DCC Payment Choice .........................................................................................................190
DCC Disclaimer ...................................................................................................................191
Contact Details .......................................................................................................................192
Web Services Integration Guide – V2.0 – 30th July 2014 10
Introduction The Web Services Integration Guide has been produced to provide full details on the integration requirements of VeriFone’s Web Service components: Session-Based and Non-Session-Based.
The Session-Based component ensures no sensitive cardholder data traverses the merchant’s network; this is achieved by capturing the card details on the cardholder’s browser and posting it directly to the VeriFone servers.
With the Non-Session-Based process, the merchant captures the card details on their own website; this information is posted from the cardholder browser to the merchant’s web server, which generates a request to post the information to VeriFone’s web servers.
Session-Based is built around VeriFone’s existing Web Service gateway service, utilising similar message structure to Non-Session-Based, as existing merchants will be familiar with. For certain transaction types, such as Token Payments (also known as Account on File transactions) it will be necessary to utilise a Non-Session-Based format of the transaction request.
This document will furnish integrators with all the information required to integrate to the Web Services solution.
In addition, the document consists of additional functionalities and Value-added Services available for both components.
Element Usage
The following element usage is used throughout the document:
• ‘O’ (Optional) – element does not have to be present. • ‘M’ (Mandatory) – element must be present and populated with a value. • ‘C’ (Conditional) – element is dependent upon the usage of one or more elements
and/or their results.
Please note: There are no changes to message formats for merchants who do not wish to move to a Session-Based solution from their previous Web Service gateway service integration.
Web Services Integration Guide – V2.0 – 30th July 2014 11
Integration To enable merchants to integrate to their systems, VeriFone 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 Technical Services 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’.
Web Services Integration Guide – V2.0 – 30th July 2014 12
To obtain a test account, please contact the Technical Services Team at the following email address: [email protected], specifying which system solution is being integrated to.
Integration Process Before any testing can commence please ensure that a request for a Session-Based or Non-Session-Based test script is sent to the Technical Services 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 VeriFone, at the absolute least, 2 weeks prior to any planned go live date. If there is a go live date to met, Technical Services 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 VeriFone require. After these changes have been made, and comments added to the script, please return it to Technical Services 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 Technical Services team are available and will be happy to help.
Message Formats VeriFone 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://txn-test.cxmlpg.com/XML4/commideagateway.asmx?WSDL
A ‘message’ has the following fields:
• ClientHeader - 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. VeriFone will process this message and respond accordingly.
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. VeriFone 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 VeriFone can return a message containing an error detailing what has occurred. The MsgType is set to
Web Services Integration Guide – V2.0 – 30th July 2014 13
‘ERROR’ and the MsgData contains the XML structure of an error, for which there are XSDs available.
Account Check Transaction Type
Within the transaction request message, field 4 txntype is used to define the transaction type. The following transaction types are available:
• 01 – Purchase • 02 – Refund • 04 – Cash Advance • 05 – Purchase with cash back (PWCB) • 06 – Continuous Authority • 07 – Account Check
The Account Check transaction type service is used in conjunction with Card Verification Code (CSC) and Address Verification Service (AVS), allowing merchants to validate a card account for debit and prepaid services without impacting the cardholder’s funds.
Account check is mandated by Visa and MasterCard to supersede VeriFone’s existing Authorisation Only (Auth Only) process, which uses a nominal value to validate an account. The transaction type does not indicate whether funds are available on the account. It is primarily used to confirm that the account exists and is not blocked or invalid.
The Account Check service is supported with both Session-Based and Non-Session-Based Web Service components.
To process an Account Check transaction via integration, the txntype field needs to be configured to ‘07’ and the processingidentifier flagged to ‘2’ for Auth Only. The value must be presented with a ‘0.00’ value.
The Account Check authorisation result will be confirmed as either “Account Valid” or “Cannot Validate” within the authmessage field depending on the transaction result returned within the transaction response message:
• If the txnresult returns “Declined” – the authmessage will return “CANNOT VALIDATE”. • If the txnresult returns “AuthOnly” – the authmessage will return “ACCOUNT VALID”.
Please note: Due to the nature of the service, the transaction does not require confirmation.
Web Services Integration Guide – V2.0 – 30th July 2014 14
Account Check Request Example:
<?xml version="1.0"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ProcessMsg xmlns="https://www.commidea.webservices.com"> <Message> <ClientHeader xmlns="https://www.commidea.webservices.com"> <SystemID>30004294</SystemID> <SystemGUID>d81841b0-40ff-4730-90c1-8b426a49335a</SystemGUID> <Passcode>12345678</Passcode> <ProcessingDB></ProcessingDB> <SendAttempt>0</SendAttempt> </ClientHeader> <MsgType xmlns="https://www.commidea.webservices.com">TXN</MsgType> <MsgData xmlns="https://www.commidea.webservices.com"> <![CDATA[<transactionrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="TXN"> <merchantreference></merchantreference> <accountid>123456789</accountid> <txntype>07</txntype> <transactioncurrencycode>826</transactioncurrencycode> <apacsterminalcapabilities>4298</apacsterminalcapabilities> <capturemethod>12</capturemethod> <processingidentifier>2</processingidentifier> <tokenid>0</tokenid> <pan></pan> <track2></track2> <csc></csc> <avshouse></avshouse> <avspostcode></avspostcode> <expirydate></expirydate> <issuenumber></issuenumber> <startdate></startdate> <txnvalue>0.00</txnvalue> <cashback>0.00</cashback> <gratuity>0.00</gratuity> <authcode></authcode> <transactiondatetime></transactiondatetime> </transactionrequest>]]></MsgData> </Message> </ProcessMsg> </soap:Body> </soap:Envelope>
Web Services Integration Guide – V2.0 – 30th July 2014 15
Acount Check 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>30004294</SystemID>
<SystemGUID>d81841b0-40ff-4730-90c1-8b426a49335a</SystemGUID> <Passcode/> <ProcessingDB>QA-DB-TOKEN-1</ProcessingDB> <SendAttempt>0</SendAttempt> <CDATAWrapping>false</CDATAWrapping>
</ClientHeader> <MsgType>TRM</MsgType> <MsgData> <transactionresponse xmlns="TXN"><merchantreference></merchantreference><transactionid>4814091</transactionid><resultdatetimestring>2013-04-16T09:16:52.947</resultdatetimestring><processingdb>QA-DB-TOKEN-1</processingdb><errormsg></errormsg><merchantnumber>6819023</merchantnumber><tid>22270003</tid><schemename>MasterCard</schemename><messagenumber>1007</messagenumber><authcode>000000</authcode><authmessage>ACCOUNTVALID</authmessage><vrtel></vrtel><txnresult>AUTHONLY</txnresult><pcavsresult>2</pcavsresult><ad1avsresult>2</ad1avsresult><cvcresult>1</cvcresult><arc>00</arc><iadarc></iadarc><iadoad></iadoad><isd></isd><authorisingentity>8</authorisingentity></transactionresponse> </MsgData> </ProcessMsgResult> </ProcessMsgResponse> </soap:Body> </soap:Envelope>
VeriFone Timeouts Transaction Authorisation Database Timeout – 45 seconds
This is the period for which VeriFone’s Servers will wait for a transaction result until returning an authorisation error as the transaction result.
Web Service Timeout – 60 seconds
This is the period after which Web Services will timeout should it not be able to post the result back to the merchant.
VeriFone Payer Authentication Database Timeout – 30 seconds
This is the period of time that VeriFone’s Servers will wait until it receives a response back from the Payer Authentication application. It will return a VeriFone timeout response in this instance.
Web Services Integration Guide – V2.0 – 30th July 2014 16
Integration Testing As aforementioned, vigorous testing is performed by VeriFone 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: - After receiving a negative error code response - Declined transactions - 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 Technical Services 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 gateway 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 VeriFone 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
Web Services Integration Guide – V2.0 – 30th July 2014 17
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 VeriFone for testing, please see Appendix A.
Testing URLs All messages should be posted to the below URL with the exception of the Card Entry page when utilising the Session-Based message formats:
https://txn-test.cxmlpg.com/XML4/commideagateway.asmx
Merchants should configure the Card Entry page to post the card details to:
https://vg-test.cxmlpg.com/vanguard.aspx
Please refer to the table below for further guidance on which URL to utilise for the relevant message type:
Transaction Type Message Type: URL Session Based VGGENERATESESSIONREQUEST
VGPAYERAUTHENROLLMENTCHECKREQUEST VGPAYERAUTHAUTHENTICATIONCHECKREQUEST VGTOKENREGISTRATIONREQUEST VGTRANSACTIONREQUEST VGCONFIRMATIONREQUEST VGREJECTIONREQUEST VGGETCARDDETAILSREQUEST
https://txn-test.cxmlpg.com/XML4/commideagateway.asmx
Non-Session Based TXN (Transaction Request) CNF (Confirmation Request) RJT (Rejection Request) PAI (PayerAuth EnrollmentCheck Request) TKI & TKI2 (Token Registration Request) PPI (PayPal Request) RELEASEONHOLDREQUEST HASHPANREQUEST SVSREQUESTMESSAGE TRANSAXSV UKASH
https://txn-test.cxmlpg.com/XML4/commideagateway.asmx
Card Entry Page
https://vg-test.cxmlpg.com/vanguard.aspx
Live URLs Once VeriFone has completed integration testing, Live URLs will be provided by VeriFone’s Technical Services department.
Web Services Integration Guide – V2.0 – 30th July 2014 18
Merchant Advice to Cardholders VeriFone 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 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.”
Web Services Integration Guide – V2.0 – 30th July 2014 19
Security Methods
Token Registration Session-Based provides merchants the ability to ‘tokenise’ the cardholder’s sensitive payment data. This process securely stores the payment card details within VeriFone’s PCI-DSS Level 1 certified managed service, returning a Token Identifier (Token ID) which can be passed as part of a transaction in future instead of the cardholder having to re-present their card details.
This enables merchants to maintain a customer database which matches any registered Token IDs to each customer record; allowing, for example, the merchant’s website to require customers to login before processing an order and displaying a list of previously used card details (displaying the card number in a masked format or a customised payment type name on the page) instead of requiring the cardholder to supply card details each time they wish to purchase from the merchant.
Card Scheme rules dictate that the Card Security Code (CSC) and Payer Authentication details cannot be stored alongside the card payment details as part of the tokenisation process. As a result, this information should be requested, where applicable, when the Token ID is utilised in future by merchants.
Tokens can be registered as part of a transaction or via an independent process utilised by the merchant with the aim of just storing the card details without processing an associated payment.
Offline to Online Token In the event of Token Registration performed offline; when the merchant is unable to connect to VeriFone’s host system, an offline Token ID is generated and returned within the integration response.
An offline Token ID is based on the time and date of the transaction. Once connection is re-established, the offline Token ID can be used to retrieve the online Token ID using the ‘OfflineToOnline Request’ message.
Please refer to ‘Non-Session-Based Message Formats’ section of this guide for Offline to Online Token message formats.
Token Payments After the registration of a token has been completed via Session-Based, or using existing tokens generated using another VeriFone product or service, the Token ID can be provided in
Please note: Merchants wishing to process Token Payment (also known as “Account On File”) transactions using pre-registered Token IDs will need to utilise a different Transaction Request message format. Please see ‘Token Payments’ section of this guide for more details.
Web Services Integration Guide – V2.0 – 30th July 2014 20
place of the payment card details for transactions from returning customers wishing to use the same card from previous transactions.
In this instance, a different transaction request message format is required. Instead of using the ‘VGTRANSACTIONREQUEST’ message type, the ‘TXN’ message type should be utilised.
As aforementioned, Card Scheme rules dictate that the Card Security Code (CSC) and Payer Authentication details cannot be stored alongside the card payment details as part of the tokenisation process. As a result; this information should be requested, where applicable, when the Token ID is utilised for future payments by merchants. This will require use of a different format of the Payer Authentication enrolment and authentication check messages.
The ‘TXN’ message type has no concept of sessions as with the Session-Based transaction request version; therefore, the process for token payments will be to populate the ‘TXN’ transaction request with the Token ID and required payment parameters (e.g. transaction value), submit the request, process the transaction response received and confirm or reject the transaction.
There is no requirement to generate a session or send the customer to a card details capture screen when utilising pre-existing Token IDs.
Web Services Integration Guide – V2.0 – 30th July 2014 21
Payer Authentication (PayerAuth) Depending upon the transaction type, Payer Authentication will be required in order to verify the cardholder and ensure the merchant is protected from fraudulent transactions resulting in a chargeback.
In order to authenticate a cardholder, VeriFone connects to the relevant Directory Server, depending upon the card type, to utilise the Verified by Visa (VbV) and MasterCard SecureCode services.
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
Yes
No
Enrollment Check Request sent to VeriFone VeriFone 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 ‘N’
Enrollment Check returns result, PAReq message, and ACS URL
Call Authentication Check, populating only the PayerAuthID and enrolled properties of
the AuthenticationCheckRequest
Issuing bank records authentication result from
information customer provides (including password)
Customer directed to ACS page to enter their password
Extract the PARes message and request the VeriFone Authentication
Check to validate Result posted back to TermUrl in the form of a PARes message
Directory Server informs VeriFone if the card is
enrolled or not
Order and cardholder data captured
Merchant System VeriFone Server Directory Server
Web Services Integration Guide – V2.0 – 30th July 2014 22
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 VeriFone Enrollment Check. This process identifies the cardholder’s enrolment status by communicating with the VISA or MasterCard Directory Server, which in turn 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 VeriFone 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 includes 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
Web Services Integration Guide – V2.0 – 30th July 2014 23
displays the issuing bank’s authentication dialog, and enters their secret password for the credit card.
vii. The issuing bank records the result of the authentication dialog with the cardholder and sends it to the merchant, along with the transaction details, in a digitally signed PARes message. The result is posted to the TermUrl on the web site, and the form posted by the issuing bank includes the PARes.
viii. Extract the PARes message from the form data and request the VeriFone Authentication Check to validate the contents of the PARes message.
ix. Depending upon the result of the Authentication Check; the merchant can now decide whether or not to proceed.
x. If the Enrollment Check indicated that the card was not enrolled, then call the Authentication Check populating only the PayerAuthRequestID and setting <Enrolled>N</Enrolled>within the AuthenticationCheckRequest.
If the card was enrolled and the merchant has now received the PARes then populate PayerAuthRequestID, set the request to <Enrolled>Y</Enrolled> and include the PARes message in the AuthenticationCheckRequest.
xi. Populate a Transaction Request with all the relevant details xii. Invoke the Process Transaction method, passing the Transaction Request and wait for
the Transaction Response to be returned xiii. When the response is received, check the AuthResult to see if there was an error. If not
then it is possible to complete the transaction with a Process Confirm; again populating the required information.
The only scenario in which a transaction should not be processed after performing Enrollment and Authentication checks would be when the following results are received:
<Enrolled>Y</Enrolled>
<AuthenticationStatus>N</AuthenticationStatus>
This represents the card being enrolled, but when the cardholder has attempted to authenticate using their password, this has not been matched correctly.
In the situation where these checks are unsuccessful, i.e. a response of <Enrolled>U</Enrolled> or <AuthenticationStatus>U</ AuthenticationStatus> is returned; it is recommended that the check is resent. Due to the fact that there has been a technical problem when checking Enrollment, charge back liability has not been shifted away from the merchant at this stage, as potentially the failure could have occurred before the information reached the Directory Server. However, the final decision on this is down to the merchant. If there is relatively low risk involved, due to a low transaction amount for example, the transaction could be continued and processed regardless.
When the card is not enrolled for Payer Authentication; the following responses will be amongst those produced:
<Enrolled>N</Enrolled>
Web Services Integration Guide – V2.0 – 30th July 2014 24
<AuthenticationStatus>N</AuthenticationStatus>
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.
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.
Excluded Card Types Verified by Visa currently excludes Visa Commercial (Non European Card), and MasterCard SecureCode currently excludes MasterCard Commercial (International cards).
These card types are excluded from any form of chargeback liability shift and an ‘Unable to Authenticate’ response will be returned. The merchant may proceed with the transaction but should be aware about the chargeback liability shift for these card types.
Process Transaction Once the enrollment and authentication checks have been performed, the transaction can be processed 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.
Payer Authentication with Token
When performing Payer Authentication in conjunction with an integration which utilises tokenisation, the process is to supply the TokenID with all the Payer Authentication checking records instead of linking to the card details stored within a session.
As a result of the above, different Payer Authentication message formats will be required dependent upon if the merchant is performing a Token Payment or a standard transaction (whereby the card details have been captured within a session).
Please note: Each time stored card details are used to process a transaction, the Payer Authentication process must be completed.
Web Services Integration Guide – V2.0 – 30th July 2014 25
Chargeback Information Merchants must ensure the Payer Authentication check details (e.g. VeReq, VaRes, PaReq and PaRes) are stored and available, when requesting any chargebacks from the acquirer. For more details, please contact VeriFone Merchant Helpdesk team.
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.
Please note: If the Payer Authentication check details are not provided to the acquirer within their set timeframe, then this could result to loss of funds.
Web Services Integration Guide – V2.0 – 30th July 2014 26
• The merchant should make sure that the authentication window frame is fully visible and is not located too low in the page due to long text or large upper frame. A minimum space of 400x400 pixels is required for the Access Control Server (ACS) frame. It must not be necessary to scroll to see the authentication page.
• Merchants must ensure that the ‘back’ button functionality works and cardholders who click on it are routed back to the checkout page.
Inline authentication windows can also be used without frames. This will show the cardholder that they are no longer at the merchant and are now communicating with their issuing bank whilst also allowing them to check the SSL lock to ensure connection with the Issuer ACS. As a result, the ‘Without frames’ approach may be preferred by some cardholders.
3. TERMURL Field This field is provided by the merchant to the issuer during the payer authentication request process. It provides the issuer with the merchant URL where the payer authentication response message is to be sent. The use of mixed HTTP and HTTPS frames typically results in a security box being presented to the cardholder. Depending upon how the cardholder responds to this dialog, the current and all future attempts to transmit the PAReq message may fail. As a result, merchants using inline authentication windows with frames must populate the TERMURL field with a HTTPS address.
PayerAuth Decisions
For guidance on which situations to accept or decline transactions based upon the Payer Authentication results, please see the table included within the Appendix of this document.
Web Services Integration Guide – V2.0 – 30th July 2014 27
Visa Additional Authorisation Data (VAAD) Visa has mandated that additional authorisation elements must be provided during domestic transactions in order to reduce the number of fraud transactions in the financial sector. The extra security information is intended to prevent fraud with all Visa debit and credit cards being used to pay off debts owed to merchants. The changes will apply to merchants falling under the category of financial institutions which have Merchant Category Code 6012. These include; banks, payday loan lenders, securities brokers or dealers, insurance sales, insurance premiums and insurance carriers.
Data Required
The additional authorisation data (AAD) will be required for transactions where cardholders use a Visa card to pay off outstanding debts. Examples of this type of transaction include paying off all, or part of, a balance on a credit card, payday loans, or mortgage repayments. The data will be required at only the auth stage of the following types of transactions: Auth and Charge and Auth only for the purchase transactions. The data will belong to the ‘primary recipient’; the person whose debt is being paid-off, but who is not necessarily the cardholder. For example; if person ‘A’ owes debt to a loan lender and the debt is paid off by person ‘B’, then additional authorisation data for person ‘A’ will be required. Merchants falling under the MCC 6012 category will be required to provide acquirers with the following AAD details when processing transactions using Visa cards:
Field Input Type Recipient date of birth Year/Month/ Day, e.g. 2014/12/01 String Recipient surname Up to 6 characters - if the surname is more than 6
characters long, then only the first 6 characters should be entered, e.g. for JOHNSON enter only JOHNSO
String
Recipient account number or partial PAN
Up to 10 alphanumeric characters of the account number (if the account number is less than 10 characters long, then the full account number should be provided). If entering a PAN – enter the first 6 and last 4 digits only, e.g. if PAN is 9999887766551234, then enter 9999881234
String
Recipient partial postcode Up to 4 characters - The first part of the postcode (the district) e.g. if the postcode is TN24 8XW, enter only “TN24”, or for the postcode B4 7DA only “B4” will be required.
String
Please note: All merchants within the MCC 6012 category will be required to ask for additional authorisation data when processing Visa transactions.
Please note: There are no case sensitive requirements for any of the VAAD fields.
Please note: The AAD details will not be logged at any point during processing, even once encrypted.
Web Services Integration Guide – V2.0 – 30th July 2014 28
Encryption
Encryption will not be used for Web Services, therefore merchants can choose to discard only the key field of the record or populate with an empty string.
At point of interaction, the VAAD information must be base 64 encoded prior to being passed to the Web Service.
Account on File (Tokenisation)
Merchants processing tokens with VAAD will be able to pass the AAD details within the transactions, provided the card scheme is Visa, which will then get passed onto the acquirer for authorisation. However, if the card scheme is not Visa, then the AAD details will be removed from the authorisation request prior to being sent to the acquirer.
Non-supported Card Schemes In the instance, when a non-supported card scheme is used when processing AAD details, the Web Service will remove the AAD details from the request and send it to the acquirer for authorisation, rather than rejecting the transaction.
Integration Changes Non-Session-Based
When processing the VAAD information within the Non-Session-Based transactions, merchants must provide all the VAAD details within the auxiliary record via the extended transaction integration record: TXN.
For more details, please refer to the Auxiliary Record section.
Session-Based For Session-Based transactions, the VAAD details can be passed in a web post page along with the card details, or later on in the VGTRANSACTIONREQUEST message. When passing the VAAD information in a web post page to Session-Based, then the AAD field will contain the concatenated details of the <data> field and should be base 64 encoded.
If the VAAD details are sent via the VGTRANSACTIONREQUEST then it needs to be formatted as shown below (non-HTML encoded):
<aadarec> <data>MDAxMTk4NjAxMDEdMDAySk9ITlNPHTAwMzAxMjM0NTY3ODkdMDA0VE4yNQ==</data> <key></key> </aadarec>
This data then needs to be HTML encoded to avoid browser warnings, an example of this is shown below:
Web Services Integration Guide – V2.0 – 30th July 2014 29
<?xml version="1.0"?><aadarec xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><data>MDAxMTk4NjAxMDEdMDAySk9ITlNPHTAwMzAxMjM0NTY3ODkdMDA0VE4yNQ==</data><key></key></aadarec>
Auxiliary Record
As part of the VAAD changes for Web Services, a new auxiliary record is appended to the XML transaction request. This auxiliary record is known as aadarec:
Record Name Type Description aadarec XML Segment This XML element contains the data required for VAAD. Should no data
be populated for VAAD then the XML element will not be included in the authorisation request
The VAAD auxiliary record will be added to the EFT authorisation request in the event that data has been set. If the VAAD information is not obtained, then the auxiliary record will not be included within the EFT authorisation request.
The VAAD auxiliary record will be an XML segment within the EFT authorisation request. The request will be comprised of 2 fields as defined below:
Field Name Type Usage Description data String M This element will contain the concatenated VAAD
information as detailed and formatted as below. key String O Please leave blank Example:
<aadarec> <data>(base 64 encoded additional authorisation data)</data> <key></key> </aadarec> The data field will be comprised of up to 4 fields utilising a tag and value format, with each field being separated by a group separator. Each field will only be present in the data field should it be populated with data. If the entry has been bypassed, then the field will not be added.
The data field elements are as follows:
Tag Value Usage Description 001 DOB O This field contains the DOB in the format of YYYYMMDD,
e.g. 20140101. 002 Surname O This field contains the Surname truncated to 6 characters
and capitalised e.g. DEYORE. 003 Account Number O This is the Account Number up to 10 digits e.g.
0123456789. 004 Post Code O This is the Partial Postcode entered e.g. TN25.
Web Services Integration Guide – V2.0 – 30th July 2014 30
Examples:
Each data element should be built like this – tag + value. For example: 002JOHNSO Each data element should be delimited by ASCII char 29 – group separator. DOB = 19990101, Surname = DEYORE, Post Code = TN25 4AZ *<data>00119990101<GS>002DEYORE<GS>004TN25</data> Surname = DEYORE, Account Number = 0123456789 *<data>002DEYORE>GS>0030123456789</data> If all the elements are provided, the data should be similar to the below: <aadarec> *<data>00119860101<GS>002JOHNSO<GS>003BLSD126502<GS>004TN25</data> <key></key> </aadarec> If only a few elements are provided, the data should be similar to the below: <aadarec> *<data>002JOHNSO<GS>004TN25</data> <key></key> </aadarec>
If there are no values to populate, then the following fields can be omitted, however VeriFone recommends the data to be left blank similar to the below: <aadarec> *<data></data> <key></key> </aadarec>
* The data field will be base 64 encoded.
Please note: <GS> should be replaced with ‘ASCII char 29 - group separator’. The elements can appear in any order.
Web Services Integration Guide – V2.0 – 30th July 2014 31
Validation All VAAD fields are optional allowing the user to bypass the prompts when requested to provide any of the details.
Merchants should ensure they conform to the following validation for each field. Web Services will perform validation as per below for each field when the VAAD fields are populated, prior to being included within the auxiliary record:
Name Type Usage Description surname String (Alpha) O This field must be truncated to 6 characters. Alpha
characters only. Must not include numeric or special characters.
dob String (Numeric) O This field must be populated in the following format: YYYYMMDD. Does not support alpha or special characters.
postcode String (Alphanumeric)
O This field must be populated with alphanumeric characters between 2 and 4 and must not include any spaces. Must only contain the first half of the postcode, i.e. TN24 5AZ would be truncated as TN25.
accountnumber String (Alphanumeric)
O Populated with account number or partial PAN (6, 4). Must be truncated to 10 alphanumeric characters. Must not include special characters.
The acquirer will perform minimal format validation on the VAAD details. If the validation fails, then the transaction will be declined and a generic error message of “Bad Format” will be returned by the acquirer.
Error Codes There are VAAD specific error messages that will be returned in the authmessage field within the transaction response messages. Please refer to the table below for more details:
Error Code Error Message Description 0200 Invalid AAD VAAD incorrectly constructed or not base 64 encoded.
Please refer guidelines. 0201 Invalid Date of birth in AAD Date of birth is of either incorrect format (should be
YYYYMMDD) or is not in the past. 0202 Invalid Surname in AAD Surname has special characters or numbers. Should be
only alpha characters. 0203 Invalid PAN/Account in AAD PAN/Account has special characters. Should be only
alphanumeric. 0204 Invalid Postcode in AAD Postcode has special characters. Should be only
alphanumeric.
Please note: The error codes will NOT be returned within the transaction response message, along with the error messages.
Please note: The response from the acquirer will not specify the reason of the VAAD validation failure other than “Bad Format”.
Web Services Integration Guide – V2.0 – 30th July 2014 32
Session-Based Transaction Request Example:
The following example shows the VGTRANSACTIONREQUEST message including the VAAD fields populated within the aadarec record:
<?xml version="1.0"?> <vgtransactionrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <merchantreference>Vanguard Test Merchant</merchantreference> <accountid>140008423</accountid> <txntype>01</txntype> <transactioncurrencycode>826</transactioncurrencycode> <apacsterminalcapabilities>4298</apacsterminalcapabilities> <capturemethod>12</capturemethod> <processingidentifier>1</processingidentifier> <avshouse>1</avshouse> <avspostcode>254</avspostcode> <expirydate>1212</expirydate> <issuenumber /> <startdate /> <txnvalue>2.34</txnvalue> <transactiondatetime>15/08/2011 16:15:25</transactiondatetime> <terminalcountrycode>826</terminalcountrycode> <payerauthauxiliarydata> <authenticationstatus>Y</authenticationstatus> <authenticationcavv>jOJxBg52QGg3ABEAAABkKW//KuI=</authenticationcavv> <authenticationeci>02</authenticationeci> <atsdata>D09100</atsdata> <transactionid>160777</transactionid> </payerauthauxiliarydata> <accountpasscode>98218859</accountpasscode> <aadarec> <data>MDAxMTk4ODEyMjEdMDAyV0lMQ09P</data> <key></key> </aadarec>
</vgtransactionrequest>
Non-Session-Based Transaction Request Example:
The following example shows the TXN message including the VAAD fields populated within the aadarec record:
<transactionrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="TXN"> <merchantreference></merchantreference> <accountid>140008154</accountid> <txntype>01</txntype> <transactioncurrencycode>826</transactioncurrencycode>
Web Services Integration Guide – V2.0 – 30th July 2014 33
<apacsterminalcapabilities>4298</apacsterminalcapabilities> <capturemethod>11</capturemethod> <processingidentifier>1</processingidentifier> <tokenid>0</tokenid> <pan>4929123123123127</pan> <track2></track2> <csc></csc> <avshouse></avshouse> <avspostcode></avspostcode> <expirydate>1412</expirydate> <issuenumber></issuenumber> <startdate></startdate> <txnvalue>10.00</txnvalue> <cashback>0.00</cashback> <gratuity>0.00</gratuity> <authcode></authcode> <transactiondatetime></transactiondatetime> <aadarec> <data>MDAxMTk4ODEyMjEdMDAyV0lMQ09P</data> <key></key> </aadarec> </transactionrequest>
The following examples illustrate invalid data entered within the surname field, i.e. special characters were entered (O’Neill):
Transaction request example with invalid data:
<transactionrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="TXN"> <merchantreference></merchantreference> <accountid>140008154</accountid> <txntype>01</txntype> <transactioncurrencycode>826</transactioncurrencycode> <apacsterminalcapabilities>4298</apacsterminalcapabilities> <capturemethod>11</capturemethod> <processingidentifier>1</processingidentifier> <tokenid>0</tokenid> <pan>4929123123123127</pan> <track2></track2> <csc></csc> <avshouse></avshouse> <avspostcode></avspostcode> <expirydate>1412</expirydate> <issuenumber></issuenumber> <startdate></startdate> <txnvalue>10.00</txnvalue> <cashback>0.00</cashback> <gratuity>0.00</gratuity>
Web Services Integration Guide – V2.0 – 30th July 2014 34
<authcode></authcode> <transactiondatetime></transactiondatetime> <aadarec> <data>MDAyTydOZWlsbA==</data> <key></key> </aadarec> </transactionrequest>
Transaction response example with invalid data:
<transactionresponse xmlns="TXN"> <merchantreference></merchantreference> <transactionid>4953957</transactionid> <resultdatetimestring>2014-05-02T16:41:45.680</resultdatetimestring> <processingdb>QA-DB-TOKEN-1</processingdb> <errormsg></errormsg> <merchantnumber></merchantnumber> <tid>00000000</tid> <schemename>Visa</schemename> <messagenumber>0000</messagenumber> <authcode></authcode> <authmessage>Invalid Surname in AAD</authmessage> <vrtel></vrtel> <txnresult>ERROR</txnresult> <pcavsresult>0</pcavsresult> <ad1avsresult>0</ad1avsresult> <cvcresult>0</cvcresult> <arc></arc> <iadarc></iadarc> <iadoad></iadoad> <isd></isd> <authorisingentity>0</authorisingentity> </transactionresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 35
Optional Functionalities
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. Web Services 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, please speak to your VeriFone Sales Account Manager.
On-Hold and Release Functionality To cater for merchants that require the ability to review transactions prior to settlement, VeriFone can enable the On-Hold and Release functionality on a merchant system. If enabled on a merchant system, the On-Hold and Release functionality can also be configured on or off at both an account and card scheme level.
When enabled, transactions at either level that are processed by any of VeriFone’s solutions will be automatically flagged as ‘On-Hold’ and will not be sent for settlement until the transaction is updated or “released” by the merchant.
Releasing a transaction is achieved by sending a Release request via Web Services 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 by VeriFone. This message format for the release request is documented within this guide.
For more information on this functionality, speak to the VeriFone Sales Account Manager.
PAN Hash Service In order for merchants to simply provide a Primary Account Number (PAN/card number) and retrieve the hash representation from VeriFone without processing a transaction, the PAN Hash Service has been provided.
To utilise this service, simply generate a non-session-based XML message conforming to the message formats supplied within this guide, and the response from the web service will contain the hash representation of the card number provided within the request.
Please note: A hash algorithm cannot be decrypted; merchants are advised to utilise sessions to remove the card details from their systems instead.
Web Services Integration Guide – V2.0 – 30th July 2014 36
Procurement Cards (VGIS) For integrators looking to process procurement cards (also known as ‘VGIS’ although this technically only refers to the Visa Global Invoice Specification) then please ensure that the VeriFone Procurement Card Specification documentation is used in conjunction with this guide.
IIN Lookup Service When a card is presented, merchants can use the IIN (Issuer Identification Number) lookup service to determine if the key information about a card range is valid, prior to processing the transaction. For example, the merchant could use the cardholder’s AVS details to verify the legality of the billing address. If it is a foreign issued card, then the response will be returned as either a ‘Not Checked’ or ‘Not Matched’ response, where the transaction may call for extra scrutiny.
VeriFone performs IIN range validation against the card ranges provided by the acquirers, in order to determine the card scheme type, prior to transaction processing. The validation is only performed on the first 6-8 digits of a card number (IIN), which identifies the institution that issued the card to the card holder and other relevant details (please see IIN Response for more details).
This functionality enables merchants to perform thorough local validation reducing erroneous transactions being sent in for processing. To utilise this functionality, merchants are required to send in an ‘IIN Request’ and will receive an ‘IIN Response’ containing all the details relevant to that card type (e.g. scheme name, allow refund, allow purchase etc).
For message formats, please refer to Non-Session-Based message formats of this guide.
PAYware Ocius applies predefined IIN sets relevant to the merchant’s solution(s) to ensure transactions are processed according to the permissions in the specific sets. A merchant can utilise more than one IIN set depending on the type of transaction. The following table provides details on these sets:
Item Description IIN Set 1 Standard GBP IIN set for UK merchants IIN Set 2 Multicurrency IIN set IIN Set 3 Visa Electron and Maestro CNP disabled IIN Set 4 ROI (Republic of Ireland) Barclays merchants IIN Set 5 Standard Euro IIN set for ROI merchants IIN Set 6 Web Services IIN set
Web Services Integration Guide – V2.0 – 30th July 2014 37
Session-Based
Overview Session-Based is the latest cardholder not present solution developed by VeriFone, hosted on VeriFone’s PCI-DSS Level 1 certified data centres.
It has been designed as a middle ground between VeriFone’s existing Web Service and Payment Page solutions, providing the merchant with the key advantages from both, whilst also reducing the scope of PCI for the merchant.
This is achieved by ensuring that no sensitive cardholder data traverses the merchant’s network as the card details are captured on the cardholder’s browser and posted directly from the cardholder’s browser to VeriFone’s servers.
Sessions Session-Based provides the ability to generate a unique session identifier prior to processing a transaction. This allows the merchant to issue the cardholder with a card entry page, the details from which are posted directly to VeriFone, but linked to the session identifier requested by the merchant and generated by VeriFone. The merchant can then retrieve a masked version of the card details sent to VeriFone by the customer using the session identifier, as well as the outcome of the transaction.
This ensures that the merchant is not exposed to the sensitive cardholder data as it is sent directly to VeriFone and referenced by the merchant by supplying VeriFone with the session identifier.
The merchant can subsequently use the session identifier to make use of the card details captured previously in order to process a complete payment transaction. If a partial capture was performed during the initial card capture (for example only the PAN was recorded), then some additional details will need to be supplied within the subsequent transaction request, which the merchant will have obtained from the customer separately.
Once a transaction has been processed and linked to the session identifier then the session is configured to expire and will not be re-usable. Should the merchant need to reference the card details captured (e.g. for a refund), this is not possible by re-using the session identifier but can be catered for using the token registration process.
Please note: Sessions do not need to be generated for capturing card types which are not governed by card scheme rules relating to PCI, e.g. Transax SV cards. All Value Add cards can be captured on the merchant website and sent directly to VeriFone using the relevant Value-add message formats. Sessions are only required for card types such as Visa which are to be used for an EFT (electronic funds transfer) transaction.
Web Services Integration Guide – V2.0 – 30th July 2014 38
Session-Based splits the transaction process into two sections: Card Capture and Transaction Processing.
Card Capture Process
The card capture process is used to collect all the required card information in order to process the transaction, and is summarised within the flow diagram below:
1. Cardholder informs the merchant that they wish to pay by card 2. Merchant sends a Generate Session request 3. VeriFone generates a ‘Session ID’ and returns this to the merchant with Generate
Session response 4. Merchant provides a card details entry page to the customer with button configured to
post the parameters directly to VeriFone’s servers 5. Cardholder enters their card details and posts them to VeriFone 6. VeriFone performs IIN range validation (to deduce the card scheme type) and redirects
customer back to merchants’ site using the page specified in the ‘ReturnURL’ field supplied within the initial Generate Session request message
7. Merchant sends Get Card Details request to retrieve the card details sent to VeriFone during step 5. If any additional details are required as only a partial capture was initially performed, then the merchant will obtain these at this stage
8. The merchant starts the transaction process, by beginning a Payer Authentication Enrolment check or a Transaction Request depending upon the merchant’s requirements.
Web Services Integration Guide – V2.0 – 30th July 2014 39
Full & Partial Capture Options To provide flexibility, VeriFone has provided the option to capture the card details as a single or two stage process. A Boolean is supplied within the generate session request to define this option.
If performing a full capture, all card details are captured when the customer is served with a card details entry page.
If performing a partial capture, only the PAN will be captured from the cardholder when the merchant serves a card details entry page. The remaining card details (expiry date, issue number, start date...) can be captured within a second stage of card details entry by the merchant and included within the transaction request message generated by the merchant.
Partial capture gives the merchant the option to check the card type being presented by the customer before deciding upon how to progress the transaction, or before generating an updated card capture page which displays required elements such as the start date, using the information returned by the Get Card Details Response.
Web Services Integration Guide – V2.0 – 30th July 2014 40
Transaction Process After capturing the card details via a session, the merchant will progress by beginning the transaction process. The card details captured within the session are referenced during this process by passing the Session GUID.
1. If Payer Authentication is required then the merchant sends a Payer Authentication Enrolment Check request. If not required, the process begins from step 5
2. VeriFone performs the enrolment check and returns the result to the merchant via the Payer Authentication Enrolment Check response. If the cardholder is enrolled then the merchant displays the Payer Authentication iframe (inline frame containing another document) for the customer to enter their details. If the card holder is not enrolled then the merchant moves on to step 4
3. The cardholder enters their Payer Authentication details and the result is returned to the merchant via the Payer Authentication Enrolment Check response which includes the response from the card scheme’s Directory Server
4. The merchant then sends a Payer Authentication Check request to VeriFone to verify the Payer Authentication details and the result is returned to the merchant to define if the transaction was successfully authenticated
5. The merchant sends the transaction request to VeriFone, including the Payer Authentication Auxiliary Data if Payer Authentication has been performed
6. VeriFone processes the transaction and returns the result to the merchant via the Transaction Response message
7. The merchant processes the transaction response and displays the result to cardholder.
Web Services Integration Guide – V2.0 – 30th July 2014 41
Session-Based Message Formats All messages built will need to conform to the message formats defined within the following sections:
Message All requests and responses will be wrapped in a message type.
Fieldname Type Usage Description MsgType String M Type of message MsgData String M Data ClientHeader ClientHeader M Client header information
Client Header The client header from within ‘Message’ will need to contain the following elements:
Fieldname Type Usage Description SystemID Decimal M System ID allocated by VeriFone, merchant specific SystemGUID String M System GUID allocated by VeriFone, merchant specific Passcode String M System Passcode allocated by VeriFone, merchant specific ProcessingDB String M This indicates the database to use for processing a request. The
maximum size limit for this field is 15. Special characters are allowed. This will be left blank for the initial generate session request
SendAttempt Integer M This field should be populated with ‘0’. Functionality will be added in future to support Send Attempt verification
CDATAWrapping Boolean M 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. VeriFone highly recommend that this is enabled
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, once a session is generated, the Processing DB field should be used for all requests.
Essentially, any transactions that receive a Processing DB value within the response need to include this same value within any subsequent requests.
Generate Session The Generate Session message is used to request a session identifier from VeriFone which will be used to reference the card details captured by the merchant.
Web Services Integration Guide – V2.0 – 30th July 2014 42
Generate Session Request MsgType: VGGENERATESESSIONREQUEST
Fieldname Type Usage Description returnurl String M URL to redirect the customers browser to after receiving the post fullcapture Boolean M Specifies if the customer will be posting all the required card details or
just partial card details Note: if only capturing partial card details, it will be necessary for the merchant to collect the remaining details and supply within the transaction request
Generate Session Response
MsgType: VGGENERATESESSIONRESPONSE
Fieldname Type Usage Description sessionguid String M Session identifier. 32 character hexadecimal string sessionpasscode String M Session passcode. 32 character hexadecimal string errorcode Integer M Error code errormessage String O Description of error
Generate Session Example An example of the Generate Session message formats is provided below:
<?xml version="1.0"?> <vggeneratesessionrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="VANGUARD"> <returnurl>https://www.company.com/returnurl.aspx</returnurl> <fullcapture>true</fullcapture> </vggeneratesessionrequest> <?xml version="1.0"?> <vggeneratesessionresponse xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <sessionpasscode>B2720217-9BE7-4891-B468-4763313EB45A</sessionpasscode> <errorcode>0</errorcode> <errordescription></errordescription> </vggeneratesessionresponse>
Please note: When generating a message a fully qualified XML name space should be included into the message (as illustrated in the example below).
Web Services Integration Guide – V2.0 – 30th July 2014 43
Card Capture Page After the merchant has generated a session ID, the customer should be served with a card capture page to enable them to provide their card details.
This information will be posted to VeriFone directly to ensure that the card details do not traverse the merchant’s network.
In a test environment, this information should be posted to:
https://vg-test.cxmlpg.com/vanguard.aspx
A webpage will receive the post from the customer’s browser. The webpage will not have any display and will just capture the post fields and redirect the customer back to the merchants’ ‘ReturnURL’ as passed in the initial generate session request.
Post Fields The following post fields will be required by the webpage receiving the post from the customer’s browser:
Fieldname Type Usage Description sessionguid String M Session identifier sessionpasscode String M Session passcode processingdb String M This indicates the database used to process the request (this needs to
be the same throughout the transaction). The maximum size limit for this field is 15. Special characters are allowed. This value can be taken from the Client Header on the Generate Session response message
pan String M Card number expirymonth String O 2 character expiry date month in the format of 01 - 12 expiryyear String O 2 character expiry date year in the format of 00 - 99 csc Decimal C Card Security Code on the card. The amount of digits required will
depend on the card type: Amex Card – 3 or 4 digits (front of card) All Other Cards – 3 or 4 digits (rear security strip)
expirydate Decimal C Card expiry month and year (MMYY) issuenumber Decimal C 1 or 2 digit card issue number.
This is only required by some Switch and Laser cards, and only required when card is keyed
startmonth String O 2 character start date month in the format of 01 – 12 startyear String O 2 character start date year in the format of 00 – 99 startdate Decimal C Card start date month and year (MMYY)
Only required for Diners Club International, some Switch, and some Laser cards.
cardholdername String O Cardholder’s name address1 String C Cardholder’s billing address first line.
This is mandatory for full capture
address2 String O Cardholder’s billing address second line.
Web Services Integration Guide – V2.0 – 30th July 2014 44
town String O Cardholder’s billing address town county String O Cardholder’s billing address county postcode String C Cardholder’s billing address postcode.
This is mandatory for full capture
country String O Cardholder’s billing address country
HTML Example
The below example shows, the post fields received from a card capture page to the VeriFone servers in HTML format:
<html> <head> <title>Vanguard Post Page Example</title> </head> <body> <form method="post" action="verifonepostpage.aspx"> <input type="text" name="cardholdername" id="cardholdername" value="A Person"/> <br> <input type="text" name="pan" id="pan" value="123456789012"/> <br> <input type="text" name="startdate" id="startdate" value="1402"/> <br> <input type="text" name="expirydate" id="expirydate" value=""/> <br> <input type="text" name="issueno" id="issueno" value=""/> <br> <input type="text" name="csc" id="csc" value="123"/> <br> <input type="text" name="address1" id="address1" value="A House"/> <br> <input type="text" name="address2" id="address2" value="A Street"> <br> <input type="text" name="town" id="town" value="A Town"/> <br> <input type="text" name="county" id="county" value="A County"/> <br> <input type="text" name="postcode" id="postcode" value="AA11 1AA"/> <br> <input type="text" name="country" id="country" value="A Country"/> <br> <input type="hidden" name="sessionguid" id="sessionguid" value="session_guid"/> <input type="hidden" name="sessionpasscode" id="sessionpasscode" value="sessoin_passcode"/> <input type="hidden" name="processingdb" id="processingdb" value="some_database"/> <input type="submit" value="Submit"> </form> </body> </html>
Web Services Integration Guide – V2.0 – 30th July 2014 45
Get Card Details The Get Card Details request is utilised by the merchant to request the card details which the customer has submitted using the Card Entry page served by the merchant in the previous step.
Get Card Details Request MsgType: VGGETCARDDETAILSREQUEST
Fieldname Type Usage Description sessionguid String M Session identifier
Get Card Details Response MsgType: VGGETCARDDETAILSRESPONSE
Fieldname Type Usage Description sessionguid String M Session identifier fullcapture Boolean M Echo from request mkcardschemeid Decimal M Card scheme identifier schemename String O Card scheme name issuenolength Integer M Length of issue number, if required startdaterequired Boolean M Indicates if start date required csclength String M Length of Card Security Code, if required allowpayerauth Boolean M Indicates if Payer Authentication is supported cpcoption Integer M Available Values:
0 = Not CPC Card 1 = CPC Card 2 = Mask Identification Required
cpcidentificationmask String O Mask used to identify if the PAN matches the format of a CPC card or not. Valid characters are: _ = A single numeric digit 0-9 = Specific numeric digit % = Any combination of numeric digits
panstar String O Starred PAN cardnumberhash String O SHA-256 hashed representation of the PAN expirydate String O Expiry date from customer’s post
Only returned if capture method was ‘full capture’
startdate String O Start date from customer’s post Only returned if capture method was ‘full capture’
issueno String O Issue no from customer’s post Only returned if capture method was ‘full capture’
address1 String O Cardholder’s billing address first line from customer’s post address2 String O Cardholder’s billing address second line from customer’s post town String O Cardholder’s billing address town from customer’s post county String O Cardholder’s billing address county from customer’s post postcode String O Cardholder’s billing address postcode from customer’s post country String O Cardholder’s billing address country from customer’s post cardholdername String O Cardholder’s name errorcode Integer M Error identifier errormessage String O Error description
Web Services Integration Guide – V2.0 – 30th July 2014 46
Get Card Details Example
An example of the Get Card Details message formats is provided below:
<?xml version="1.0"?> <vggetcarddetailsrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> </vggetcarddetailsrequest> <?xml version="1.0"?> <vggetcarddetailsresponse xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <fullcapture>1</fullcapture> <mkcardschemeid>3</mkcardschemeid> <schemename>Mastercard</schemename> <issuenolength>0</issuenolength> <startdaterequired>0</startdaterequired> <csclength>3</csclength> <allowpayerauth>1</allowpayerauth> <cpcoption>0</cpcoption> <cpcidentificationmask>%</cpcidentificationmask> <panstar>545301******0789</panstar> <cardnumberhash>t7jo9jiV5n/El/MMSLw0jAlDiJ8rxTzGJwmhoRbR73g=</cardnumberhash> <expirydate>1212</expirydate> <startdate></startdate> <issueno></issueno> <address1>Address1</address1> <address2>Address2</address2> <town>Town/Village</town> <county>County</county> <postcode>TN25 4AZ</postcode> <country>Country</country> <cardholdername>MR M LOVELOCK</cardholdername> <errorcode>0</errorcode> <errordescription></errordescription> </vggetcarddetailsresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 47
PayerAuth Message Types This section details the message types required in order to perform Payer Authentication with Session-Based.
• Enrollment Check – used to check if the cardholder is enrolled with the Payer Authentication service
• Authentication Check – used to retrieve the Payer Authentication result from the Directory Server
The result of the Payer Authentication check can then be used to decide how the merchant wishes to proceed with the transaction.
Enrollment Check Request MsgType: VGPAYERAUTHENROLLMENTCHECKREQUEST
Fieldname Type Usage Description sessionguid String M Session identifier
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 VeriFone 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 23 – JCB 24 – AIB
merchantname String 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 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.
merchanturl String M This field contains the fully qualified URL of the merchant site visamerchantbankid String C This field contains a six digit assigned Bank Identification
Number issued by the merchant’s member bank or processor.
Web Services Integration Guide – V2.0 – 30th July 2014 48
The acquirer Bank Identification Number (BIN) identifies the member bank that signed the merchant using the Point of Sale application
visamerchantnumber String C 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 C (Field is obsolete)
mcmmerchantbankid String C 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 C 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 C (Field is obsolete)
expirydate String C Expiry date. Mandatory for partial capture but not required for full capture
currencycode String 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
currencyexponent String M No of decimal places in currency field ie. GBP will be 2 browseracceptheader String M 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 M This field contains the exact content of the HTTP useragent header as sent to the merchant from the cardholder's user agent. This field is only required if the cardholder's user agent supplied a value.
transactionamount String 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 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 O This field contains a description of the goods or services being purchased, determined by the merchant.
Enrollment Check Response
MsgType: VGPAYERAUTHENROLLMENTCHECKRESPONSE
Fieldname Type Usage Description sessionguid String M Session identifier merchantreference String O Merchant can add a reference to cross reference responses
relating to the same transaction payerauthrequestid Decimal M Unique Identifier enrolled String O Indicates if card is enrolled in the 3D secure program. acsurl String O Fully qualified URL of an Access Control Server. pareq String O This field will contain the entire XML response packet from the
Directory Server. errorcode Integer M Error identifier errordescription String O Error description
Web Services Integration Guide – V2.0 – 30th July 2014 49
Enrollment Example <?xml version="1.0"?> <vgpayerauthenrollmentcheckrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <merchantreference>Vanguard Test Merchant</merchantreference> <mkaccountid>140008423</mkaccountid> <mkacquirerid>2</mkacquirerid> <merchantname>A Merchant Ltd</merchantname> <merchantcountrycode>826</merchantcountrycode> <merchanturl>https://www.company.com/merchantsite</merchanturl> <visamerchantbankid>123456</visamerchantbankid> <visamerchantnumber>22270438</visamerchantnumber> <mcmmerchantbankid>542515</mcmmerchantbankid> <mcmmerchantnumber>83589362</mcmmerchantnumber> <currencycode>826</currencycode> <currencyexponent>2</currencyexponent> <browseracceptheader>image/gif, image/jpeg, image/pjpeg, application/x-ms-application, application/vnd.ms-xpsdocument, application/xaml+xml, application/x-ms-xbap, application/vnd.ms-excel, application/vnd.ms-powerpoint, application/msword, application/x-shockwave-flash, */*</browseracceptheader> <browseruseragentheader>Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0; Trident/4.0; SLCC1; .NET CLR 2.0.50727; .NET CLR 3.0.30729; .NET CLR 1.1.4322; .NET CLR 3.5.30729; InfoPath.2; SERVERS; .NET4.0C; .NET4.0E; SERVERS)</browseruseragentheader> <transactionamount>234</transactionamount> <transactiondisplayamount>2.34</transactiondisplayamount> <transactiondescription>A Merchant Ltd product purchase</transactiondescription> </vgpayerauthenrollmentcheckrequest>
<?xml version="1.0"?> <vgpayerauthenrollmentcheckresponse xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <merchantreference>Vanguard Test Merchant</merchantreference> <payerauthrequestid>160777</payerauthrequestid> <enrolled>Y</enrolled> <acsurl>https://test.cap.securecode.com/acspage/cap?RID=28&VAA=B</acsurl> <pareq>[Removed from documentation]</pareq> <errorcode>0</errorcode> <errordescription></errordescription> </vgpayerauthenrollmentcheckresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 50
Authentication Check Request MsgType: VGPAYERAUTHAUTHENTICATIONCHECKREQUEST
Fieldname Type Usage Description sessionguid String M Session identifier 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
Authentication Check Response
MsgType: VGPAYERAUTHAUTHENTICATIONCHECKRESPONSE
Fieldname Type Usage Description sessionguid String M Session identifier merchantreference String O Merchant can add a reference to cross reference responses
relating to the same transaction payerauthrequestid Decimal M PayerAuth transaction identifier atsdata String O Additional transaction security data authenticationstatus String O 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 O The certificate that signed the Payer Authentication Response (PARes) message
authenticationcavv String O This property contains a 28-byte Base-64 encoded Cardholder Authentication Verification Value (CAVV)
authenticationeci String O Two digit Electronic Commerce Indicator (ECI) value authenticationtime String O 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"
errorcode Integer M Error identifier errordescription String O Error description
Web Services Integration Guide – V2.0 – 30th July 2014 51
Authentication Example <?xml version="1.0"?> <vgpayerauthauthenticationcheckrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <merchantreference>Vanguard Test Merchant</merchantreference> <payerauthrequestid>160777</payerauthrequestid> <pares>[Removed from documentation]</pares> <enrolled>Y</enrolled> </vgpayerauthauthenticationcheckrequest> <?xml version="1.0"?> <vgpayerauthauthenticationcheckresponse xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <merchantreference>Vanguard Test Merchant</merchantreference> <payerauthrequestid>160777</payerauthrequestid> <atsdata>D09100</atsdata> <authenticationstatus>Y</authenticationstatus> <authenticationcertificate>MIIEgDCCA2igAwIBAgICUPMwDQYJKoZIhvcNAQEFBQAwgawxCz</authenticationcertificate> <authenticationcavv>jOJxBg52QGg3ABEAAABkKW//KuI=</authenticationcavv> <authenticationeci>02</authenticationeci> <authenticationtime>20110815 15:16:28</authenticationtime> <errorcode>0</errorcode> <errordescription></errordescription> </vgpayerauthauthenticationcheckresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 52
Token Registration As part of a transaction, or without processing an associated transaction (i.e. token registration only), Session-Based can be used to store the payment card details within VeriFone’s PCI DSS Level 1 certified data centres.
After the registration has been completed, a ‘token ID’ will be returned within the response which should store for future use alongside some form of customer record which is held and maintained by the merchant.
When Token Registration is required, it should be requested prior to processing the transaction request.
Token Registration Request
MsgType: VGTOKENREGISTRATIONREQUEST
Fieldname Type Usage Description
sessionguid String M Session identifier merchantreference String O Merchant can add a reference to cross reference responses relating
to the same transaction expirydate String O Card expiry month and year (YYMM) issuenumber String O 1 or 2 digit card issue number.
Only required by some Switch, and Laser cards, and only required when card is keyed
startdate String O Card start date month and year (MMYY). Only required for Diners Club International, some Switch, and some Laser cards. Please note the format difference between the expiry and start dates are intentional
purchase Boolean M Allow purchase transaction type refund Boolean M Allow refund transaction type cashback Boolean M Allow cashback transaction type tokenexpirationdate String M Last date on which the token can be utilised.
Format of date to be: DDMMCCYY
Please note: Should there be an error with the token registration; the token ID field will still be populated. The token ID field should only be stored when the ‘ErrorCode’ field contains a value of ‘0’.
Web Services Integration Guide – V2.0 – 30th July 2014 53
Token Registration Response MsgType: VGTOKENREGISTRATIONRESPONSE
Fieldname Type Usage Description sessionguid String M Session identifier merchantreference String O Merchant can add a reference to cross reference responses relating to
the same transaction tokenid Decimal M Unique identifier for registered PAN. The maximum size limit for this
field is 18. This value should only be stored when the error code field contains a ‘0’. For all other error conditions, the tokenID should not be stored.
cardschemename String O Name of card scheme errorcode Integer M Error identifier errordescription String O Error description
Token Registration Example <?xml version="1.0"?> <vgtokenregistrationrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <merchantreference>Vanguard Test Merchant</merchantreference> <expirydate>1212</expirydate> <startdate /> <issueno /> <purchase>true</purchase> <refund>false</refund> <cashback>false</cashback> <tokenexpirationdate>14092011</tokenexpirationdate> </vgtokenregistrationrequest> <?xml version="1.0"?> <vgtokenregistrationresponse xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <merchantreference>Vanguard Test Merchant</merchantreference> <tokenid>35337801</tokenid> <cardschemename>Mastercard</cardschemename> <errorcode>0</errorcode> <errordescription></errordescription> </vgtokenregistrationresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 54
EFT Transaction In order to process a transaction using the card details captured, a transaction request is required. The transaction request includes the session identifier against which the card details provided by the cardholder have been linked and instructs VeriFone on all other aspects of the transaction such as value, type and currency.
A response is returned to the merchant, this will require either a confirmation or rejection request to be sent. The Web Service will then return an updated transaction response message to confirm the final result of the transaction after the confirmation or rejection has been processed.
Transaction Request
MsgType: VGTRANSACTIONREQUEST
Fieldname Type Usage Description sessionguid String M Session identifier 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 VeriFone txntype String M 01 – Purchase
02 – Refund 04 – Cash Advance 05 – Purchase with cash back (PWCB) 06 – Continuous Authority 07 – Account Check (for more details, please refer to the section within this guide)
transactioncurrencycode String M This is the three digit currency code (numeric). 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 Technical Services 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
Web Services Integration Guide – V2.0 – 30th July 2014 55
6 – ICC PIN Only 7 – ICC PIN and Signature 8 – ICC – No CVM 9 – Contactless EMV 10 – Contactless Mag Stripe 11 – Keyed Cardholder Not Present Telephone Order 12 – Keyed Cardholder Not Present Ecommerce Order
processingidentifier 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.
csc1 String O Amex Card – 3 or 4 digits (front of card) All Other Cards – 3 or 4 digits (rear security strip)
avshouse1 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
avspostcode1 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
expirydate String O Card expiry month and year (YYMM) issuenumber String O 1 or 2 digit card issue number. Only
required by some Switch, and Laser cards, and only required when card is keyed
startdate String O Card start date month and year (MMYY) Only required for Diners Club International, some Switch, and some Laser cards. 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) Please note: For Account Check transaction, the value must be in the following format: “0.00”.
cashbackvalue 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). terminalcountrycode String M In accordance with the numeric values defined in ISO 3166 employeeid String O Employee identifier 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
Web Services Integration Guide – V2.0 – 30th July 2014 56
Payer Auth auxiliary data to be supplied vgistransaction Boolean C Denotes if the transaction is a procurement card/VGIS
transaction. accountpasscode String M Account passcode, supplied by VeriFone returnhash Boolean M Specifies whether to return the ‘gdethash’ and ‘panstar’ fields
within the transaction response message. Valid values are: 0 = False 1 = True
1 All three fields are required when processing Amex transactions, if not provided then result of ‘0’ is returned in the response message.
Transaction Response MsgType: VGTRANSACTIONRESPONSE
Fieldname Type Description sessionguid String session identifier 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:ss) errormsg String Error message merchantnumber String Unique merchant number tid String Terminal ID schemename String Card scheme name
1 – Amex 2 – Visa 3 – MasterCard/MasterCard One 4 – Maestro 5 – Diners 6 – Visa Debit 7 – JCB 8 – BT Test Host 9 – Time / TradeUK Account card 10 – Solo (ceased) 11 – Electron 21 – Visa CPC 23 – AllStar CPC 24 – EDC/Maestro (INT) / Laser 26 – LTF 27 – CAF (Charity Aids Foundation) 28 – Creation 29 – Clydesdale 31 – BHS Gold 32 – Mothercare Card 33 – Arcadia Group card 35 – BA AirPlus 36 – Amex CPC 41 – FCUK card (Style) 48 – Premier Inn Business Account card 49 – MasterCard Debit 51 – IKEA Home card (IKANO)
Web Services Integration Guide – V2.0 – 30th July 2014 57
53 – HFC Store card 999 – Invalid Card Range
messagenumber String Transaction message number (equivalent of EFTSN from previous versions of the Web Service)
authcode String The Authorisation code that is returned by the bank. This will be blank if the transaction is declined and if the transaction value is below the floor limit.
authmessage String The authmessage wil depend on the txnresult received, e.g. if ‘AuthOnly’ is received then the authmessage will return “ACCOUNT VALID” for Account Check transaction.
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 APPROVED AUTHORISED AUTHONLY VERIFIED NOT VERIFIED
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.
authorisingentity String 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’.
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
panstar String Starred version of the PAN.
Web Services Integration Guide – V2.0 – 30th July 2014 58
Only returned if ‘returnhash’ set to true within the transaction request message
gdethash String SHA-256 representation of the PAN provided within the transaction request. Only returned if ‘returnhash’ set to true within the transaction request message
Transaction Request Example <?xml version="1.0"?> <vgtransactionrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <merchantreference>Vanguard Test Merchant</merchantreference> <accountid>140008423</accountid> <txntype>01</txntype> <transactioncurrencycode>826</transactioncurrencycode> <apacsterminalcapabilities>4298</apacsterminalcapabilities> <capturemethod>12</capturemethod> <processingidentifier>1</processingidentifier> <avshouse>1</avshouse> <avspostcode>254</avspostcode> <expirydate>1212</expirydate> <issuenumber /> <startdate /> <txnvalue>2.34</txnvalue> <transactiondatetime>15/08/2011 16:15:25</transactiondatetime> <terminalcountrycode>826</terminalcountrycode> <payerauthauxiliarydata> <authenticationstatus>Y</authenticationstatus> <authenticationcavv>jOJxBg52QGg3ABEAAABkKW//KuI=</authenticationcavv> <authenticationeci>02</authenticationeci> <atsdata>D09100</atsdata> <transactionid>160777</transactionid> </payerauthauxiliarydata> <accountpasscode>98218859</accountpasscode> </vgtransactionrequest>
Transaction Response Example <?xml version="1.0"?> <vgtransactionresponse xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <merchantreference>Vanguard Test Merchant</merchantreference> <transactionid>3505976</transactionid> <resultdatetimestring>2011-08-15T16:16:33.447</resultdatetimestring> <errormsg></errormsg> <merchantnumber>22048042</merchantnumber> <tid>28200005</tid> <schemename>MasterCard</schemename> <messagenumber>1535</messagenumber> <authcode>612866</authcode> <authmessage>AUTH CODE:612866</authmessage> <vrtel></vrtel>
Web Services Integration Guide – V2.0 – 30th July 2014 59
<txnresult>AUTHORISED</txnresult> <pcavsresult>4</pcavsresult> <ad1avsresult>4</ad1avsresult> <cvcresult>4</cvcresult> <arc>00</arc> <authorisingentity>8</authorisingentity> <customerspecifichash>20AED17A240DB326530AF05491074E9688B41549</customerspecifichash> </vgtransactionresponse>
Confirmation Request
MsgType: VGCONFIRMATIONREQUEST
Fieldname Type Usage Description sessionguid String M Session identifier transactionid Decimal M TransactionID from Transaction request offlineauthcode String O AuthCode if transaction was authorised offline gratuity Decimal O Additional value to add to total (e.g. service tip)
Rejection Request MsgType: VGREJECTIONREQUEST
Fieldname Type Usage Description sessionguid String M Session identifier transactionid Decimal M TransactionID from Transaction request 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
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
Web Services Integration Guide – V2.0 – 30th July 2014 60
Confirmation Example <?xml version="1.0"?> <vgconfirmationrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <transactionid>3505976</transactionid> </vgconfirmationrequest> <?xml version="1.0"?> <vgtransactionresponse xmlns="VANGUARD"> <sessionguid>24D65BEC-03B1-4C51-B0B5-EBD9E9EAEB58</sessionguid> <merchantreference>Vanguard Test Merchant</merchantreference> <transactionid>3505976</transactionid> <resultdatetimestring>2011-08-15T16:16:33.447</resultdatetimestring> <errormsg></errormsg> <merchantnumber>22048042</merchantnumber> <tid>28200005</tid> <schemename>3</schemename> <messagenumber>1535</messagenumber> <authcode>612866</authcode> <authmessage>AUTH CODE:612866</authmessage> <vrtel></vrtel> <txnresult>CHARGED</txnresult> <pcavsresult>4</pcavsresult> <ad1avsresult>4</ad1avsresult> <cvcresult>4</cvcresult> <arc>00</arc> <authorisingentity>8</authorisingentity> <customerspecifichash>20AED17A240DB326530AF05491074E9688B41549</customerspecifichash> </vgtransactionresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 61
Non-Session-Based
Overview Non-Session-Based provides merchants with a resilient design and faster service using VeriFone’s next generation gateway 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 listed. This will provide an understanding of how each works, and then all the messaging information required to incorporate the functionality.
Web Services Integration Guide – V2.0 – 30th July 2014 62
Process Flow Non-Session-Based transaction process is as per the below process:
Merchant System VeriFone Server
Transaction Response generated and returned to host
Merchant informs customer of result and completes/cancels
order
VeriFone stores transaction ready for end of day
settlement
Order and cardholder data captured
Transaction Request sent to VeriFone, along with any ICC, Auxiliary or PayerAuth Data
VeriFone seeks authorisation on behalf of
merchant
Merchant stores response and returns confirmation/rejection
Web Services Integration Guide – V2.0 – 30th July 2014 63
Non-Session-Based Message Formats For those merchants who do not require the use of sessions to capture the card details from the customer, the message formats previously supplied by VeriFone using the Web Service gateway service can be utilised.
These formats are required when processing transactions using Token IDs for merchants who are using Session-Based to capture the card details and then using token registration to store them for future use.
All the XML data that is submitted to a VeriFone 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.
Message
All requests and responses will be wrapped in a message type, as defined below:
Section/Fields Type/Format Mandatory/Optional Description <message> MsgType String M Type of message MsgData String M Data ClientHeader ClientHeader M ClientHeader information </message>
ClientHeader The clientheader is used to validate requests and direct them to the correct server:
Section/Fields Type/Format Mandatory / Optional Description <ClientHeader> SystemID Decimal M Allocated ID SystemGUID String M Allocated GUID
Please note: There are no changes to message formats for merchants who do not wish to move to a session-based solution from their previous Web Service gateway service integration.
Web Services Integration Guide – V2.0 – 30th July 2014 64
Passcode String M Allocated Passcode ProcessingDB String M (for Confirmation Request,
Rejection Request and Authentication Request for Payer Authentication)
This indicates the database to use for processing a particular request. If left blank the default database will be used. The maximum size limit for this field is 15. Special characters are allowed. N.B. Should only be left blank for the initial transaction request
SendAttempt Integer M This field should be populated with ‘0’. Functionality will be added in future to support Send Attempt verification.
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>
Web Services Integration Guide – V2.0 – 30th July 2014 65
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.
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>
Web Services Integration Guide – V2.0 – 30th July 2014 66
EFT Transaction
Transaction Request
The transaction request type contains all the required information to authorise the requested transaction type. The Message Type for the transaction request is TXN and the namespace is TXN.
Section/Fields Type/Format Mandatory / Optional
Description
<transactionrequest> merchantreference String O Merchant can add a reference to cross reference
responses relating to the same transaction accountid Decimal M Account reference number, supplied by VeriFone accountpasscode String M Account passcode, supplied by VeriFone txntype String M 01 – Purchase
02 – Refund* 04 – Cash Advance 05 – Purchase with cash back (PWCB) 06 – Continuous Authority 07 - Account Check * When processing a refund, set ‘apacsterminalcapabilities’ to 4290 and ‘capturemethod’ to 11 (for MOTO)
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 Technical Services 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
Web Services Integration Guide – V2.0 – 30th July 2014 67
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
processingidentifier 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.
tokenid Decimal O Token Identifier for token transaction. The maximum size limit for this field is 18.
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.
csc1 String O Amex Card – 3 or 4 digits (front of card) All Other Cards – 3 or 4 digits (rear security strip)
avshouse1 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
avspostcode1 Integer O Field checked by Address Verification System (AVS) add on module, ignored if module not enabled. AVS configuration can make this field mandatory. Numerics from postcode only
issuenumber String O 1 or 2 digit card issue number. Only required by some Switch, 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, 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:
Web Services Integration Guide – V2.0 – 30th July 2014 68
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) 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 Integration Guide for full VGIS data requirements
</transactionrequest> 1 All three fields are required when processing Amex transactions, if not provided then result of ‘0’ is returned in the response message.
Web Services Integration Guide – V2.0 – 30th July 2014 69
ICC Data When processing an ICC transaction, this message type is used to supply the extra information required.
Section/Fields Type/Format Mandatory / Optional
Description
<iccdata> emvterminalcapabilities String M The terminal capabilities as defined in the
EMV specifications. emvterminaltype String M Terminal type/Currency indicator
S = Sterling E = Euro 0 = Unspecified terminal capabilities – S 1 = ICC reader only – S 2 = Magnetic stripe only – S 3 = ICC/Magnetic stripe – S 4 = No card reader – S 5 = Unspecified terminal capabilities – E 6 = ICC reader only – E 7 = Magnetic stripe only – E 8 = ICC/Magnetic stripe – E 9 = No card reader – E
reasononlinecode String M In the provisional European Standard (prENV 1750) the On-line reason codes are four digits in the form 15XX for PoS type of environment. As all PoS codes begin 15 there is no need to send this fixed value and therefore only the XX as defined in the ENV 1750 need be transmitted. Reason On-line will be used by the acquirer to determine if stand-in authorisation would be an appropriate action for this transaction. I.e. was it the ICC or the CAD which required an on-line authorisation.
arqc String M Cryptogram generated by card at end of offline and online declined transactions. Can be used to validate the risk management activities for a given transaction (passed by ICC Terminal)
apppansequenceno String M Identifies and differentiates cards with some PAN (ICC Card passes this information)
aip String M Application Interchange Profile (passed by ICC terminal)
atc String M Value of the last online transaction (passed by ICC terminal)
unpredictableno String M (passed by ICC terminal) tvr String M Terminal Verification Results. Record of
outcome of various application functions performed by Cardholder System (passed by ICC terminal)
cryptotxntype String M Indicates transaction type used to application usage control. One of the
Web Services Integration Guide – V2.0 – 30th July 2014 70
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)
terminalapplicationversionnumber 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)
cardapplicationversionnumber String M Version number assigned by the payment system for the application on the IC card (extracted from the IC Card Tag 9F 08)
cvmr 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>
Web Services Integration Guide – V2.0 – 30th July 2014 71
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. Please see the PayerAuth section for instructions on how to perform the enrolment and authentication checks.
Section/Fields Type/Format Mandatory / Optional
Description
<payerauthauxiliarydata> authenticationstatus String M Indicates if the transaction authenticated or not:
Y – Customer was successfully authenticated N – Customer failed authentication, and the transaction declined A – Attempts processing. APACS message will show verified enrollment but cardholder not participating U – Enrollment could not be completed, due to technical or other problem
authenticationcavv String M Contains 28-byte Base-64 encoded Cardholder Authentication Verification Value (CAVV)
authenticationeci String M 2 digit Electronic Commerce Indicator (ECI) value atsdata String M Data to populate authorisation message transactionid String M TransactionID should be populated with the
PayerAuthRequestID provided in the PayerAuth EnrollmentCheck Response
</payerauthauxiliarydata>
Web Services Integration Guide – V2.0 – 30th July 2014 72
Confirmation Request This message type is used to confirm the transaction.
The Message Type for the confirmation request is CNF and the namespace is TXN.
Section/Fields Type/Format Mandatory / Optional
Description
<confirmationrequest> transactionid Decimal M TransactionID from ProcessTransaction request offlineauthcode String O AuthCode if transaction was authorised offline gratuity Decimal O Additional value to add to total (e.g. service tip) transactioncertificate String M for ICC Transaction certificate from 2nd generate arc String M for ICC Auth response code applicatonusagecontrol String M for ICC Application usage control tvr 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>
Web Services Integration Guide – V2.0 – 30th July 2014 73
Rejection Request This message type is used to reject the transaction.
The Message Type for the transaction request is RJT and the namespace is TXN.
Section/Fields Type/Format Mandatory / Optional
Description
<rejectionrequest> transactionid Decimal M TransactionID from ProcessTransaction request tokenid Decimal O Token identifier for token transaction. The
maximum size limit for this field is 18. 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>
Web Services Integration Guide – V2.0 – 30th July 2014 74
Transaction Response This message type will contain the response from the transaction.
The Message Type for the transaction response is TRM (for initial transactions result message) and FTR (for the final transaction result message) and the namespace is TXN.
Section/Fields Type/Format Description <transactionresponse> merchantreference String Merchant can add a reference to cross reference responses relating
to the same transaction transactionid Decimal Transaction ID (unique only to the processing database utilised) resultdatetimestring String Extended date and time string
( YYYY-MM-DDTHH:MM:SS.sss) processingdb String This indicates the database used to processing the request. The
maximum size limit for this field is 15. Special characters are allowed. errormsg String Error message merchantnumber 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 (ceased)
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
messagenumber String Transaction message number (equivalent of EFTSN from previous versions of the Web Service)
authcode String The Authorisation code that is returned by the bank. This will be blank if the transaction is declined and if the transaction value is below the floor limit.
authmessage String Authorisation message
Web Services Integration Guide – V2.0 – 30th July 2014 75
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 APPROVED AUTHORISED AUTHONLY For further information on the transaction results please see below
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’.
Web Services Integration Guide – V2.0 – 30th July 2014 76
Ensure the Procurement Guide Specification is utilised alongside the Web Services Integration 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>
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:
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 VeriFone’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.
Web Services Integration Guide – V2.0 – 30th July 2014 77
PayerAuth Non-Session-Based Payer Authentication is required for token payments, and is also available for merchants not using a non-session-based integration for transaction processing.
PayerAuth EnrollmentCheck Request The EnrollmentCheck request is raised to check if the card is enrolled with MasterCard SecureCode or Verified By Visa.
The Message Type for the payer authentication enrollment check is PAI and the namespace is PAYERAUTH.
Section/Fields Type/Format Mandatory/ Optional/ Conditional
Description
<payerauthenrollmentcheckrequest> merchantreference String O Merchant can add a reference to cross
reference responses relating to the same transaction
mkaccountid Decimal M Account reference number, supplied by VeriFone
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 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 M This field contains a three digit number
Web Services Integration Guide – V2.0 – 30th July 2014 78
Varchar(50) 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)
(Field is obsolete)
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)
(Field is obsolete)
tokenid Decimal C
Token identifier for token transaction. If none to be passed, ‘0’ to be used. The maximum size limit for this field is 18.
cardnumber String Varchar(50)
C Card PAN
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
Web Services Integration Guide – V2.0 – 30th July 2014 79
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>
PayerAuth EnrollmentCheck Response
The response from the check will be contained within the EnrollmentCheck response.
The Message Type for the payer authentication enrollment check response is PAER and the namespace is PAYERAUTH.
Section/Fields Type/Format Description <payerauthenrollmentcheckresponse> merchantreference String
Varchar(50) Merchant can add a reference to cross reference responses relating to the same transaction
processingdb String This indicates the database to use for processing a particular request. The maximum size limit for this field is 15. Special characters are allowed. 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>
Web Services Integration Guide – V2.0 – 30th July 2014 80
PayerAuth AuthenticationCheck Request After the enrollment check has been performed, authentication can be sought using this message type.
The Message Type for the payer authentication check request is PAI and the namespace is PAYERAUTH.
Section/Fields Type/Format Mandatory/ Optional/ Conditional
Description
<payerauthauthenticationcheckrequest> merchantreference String O Merchant can add a reference to
cross reference responses relating to the same transaction
payerauthrequestid Decimal M Unique Identifier returned during EnrollmentCheckResponse.
pares String C Compressed and encoded Payer Authentication Response message, returned in response from Visa / Mastercard (Only included if received)
enrolled String M Indicates if the card was enrolled – Y/N
</payerauthauthenticationcheckrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 81
PayerAuth AuthenticationCheck Response The authentication check response will contain the result of the authentication check.
The Message Type for the payer authentication response is PAAR and the namespace is PAYERAUTH.
Section/Fields Type/Format Description <payerauthauthenticationcheckresponse> merchantreference String Merchant can add a reference to cross reference
responses relating to the same transaction 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. The maximum size limit for this field is 15. Special characters are allowed.
</payerauthauthenticationcheckresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 82
Token Gateway The token gateway is available for merchants not requiring a session-based token registration process.
Registration Request (TKI) The Token Registration Request type contains all the information required to register a token.
The Message Type is TKI and the namespace is TOKEN.
Section/Fields Type/Format Mandatory/ Optional/ Conditional
Description
<tokenregistrationrequest> merchantreference String O Merchant can add a reference to
cross reference responses relating to the same transaction
pan String M Card number expirydate String M Card expiry month and year
(YYMM) (Only required when card is keyed, can be calculated from Track2)
startdate String C Card start date month and year (MMYY) Only required for Diners Club International, some Maestro, 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, 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>
Web Services Integration Guide – V2.0 – 30th July 2014 83
Token Registration Response (TKI) The Token Registration Response type contains all the result information from a token registration request.
The Message Type is TOKENRESPONSE and the namespace is TOKEN.
Section/Fields Type/Format Description <tokenregistrationresponse> tokenid Decimal Unique identifier for registered PAN. The maximum size limit for
this field is 18. 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>
Registration Request (TKI2)
The Token Registration Request type contains all the information required to register a token, and ensures that the card scheme name is returned within the response message.
The Message Type is TKI2 and the namespace is TOKEN.
Section/Fields Type/Format Mandatory/ Optional/ Conditional
Description
<tokenregistrationrequest> merchantreference String O Merchant can add a reference to
cross reference responses relating to the same transaction
pan String M Card number expirydate String M Card expiry month and year
(YYMM) (Only required when card is keyed, can be calculated from Track2)
startdate String C Card start date month and year (MMYY) Only required for Diners Club International, some Maestro, 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, 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
Web Services Integration Guide – V2.0 – 30th July 2014 84
</tokenregistrationrequest>
Token Registration Response (TKI2) – Success When the TKI2 token registration request is successful, the following message is returned.
The Message Type is TOKENRESPONSE and the namespace is TOKEN.
Section/Fields Type/Format Description <tokenregistrationresponse> tokenid Decimal Unique identifier for registered PAN. The maximum size limit for
this field is 18. 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>
Token Registration Response (TKI2) – Failure
Should the TKI2 token registration request fail, the following message is returned.
The Message Type is TOKENRESPONSE and the namespace is TOKEN.
Section/Fields Type/Format Description <tokenregistrationresponse> merchantreference String Merchant can add a reference to cross reference responses
relating to the same transaction errorcode Integer This is an error code indicating what type of error occurred, if
any, while processing the transaction. See Appendix E for error codes
errormsg String This is a text field used to give as short text description of the error code
</tokenregistrationresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 85
Offline to Online Token In order to obtain an online Token ID from an offline Token ID, the following integration message request is required.
Offline to Online Request The Message Type for the Offline to Online request is OFFLINETOONLINEREQUEST and the namespace is OFFLINETOONLINE.
Section/Fields Type/Format Usage Description <offlinetoonlinerequest> mkofflineid Decimal M Offline Token ID </ offlinetoonlinerequest>
Offline to Online Response
The Message Type for the Offline to Online response is OFFLINETOONLINERESPONSE and the namespace is OFFLINETOONLINE.
Section/Fields Type/Format Usage Description <offlinetoonlineresponse>
mkofflinetoonlineid Decimal M The response provided by VeriFone mtokenid Decimal O The ID of the online token. The maximum size limit for
this field is 18. errorcode String O The error code errormessage String O The error message
</offlinetoonlineresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 86
On-Hold & Release Message Types As discussed earlier within this guide, the On-Hold and Release functionality can be enabled on a merchant system. If enabled on a merchant system, the On-Hold and Release functionality can also be configured on or off at both an account and card scheme level. Once enabled, each and every transaction within an enabled card scheme and/or account will require a release message to be sent to the VeriFone servers via the Web Services solution before the transaction is submitted for settlement to the acquirer.
Release Request The Message Type for the payer authentication enrolment check response is RELEASEONHOLDREQUEST and the namespace is ONHOLD.
Section/Fields Type/Format Usage Description <releaseonholdrequest> authdb String C The authorisation database within the VeriFone
infrastructure which processed the transaction during authorisation. Mandatory for all online transactions. The data with which to populate this field is obtained from: Field 35, ServerID in Transaction Response 6 (Payware Ocius VX820RS Integration Guide) Field 39, ServerID in Transaction Response 7 (VX 810 and VX 820 POS Client Integration Guide). For an online transaction, the ServerID will contain the name of the authorisation server which processed the transaction. For an offline transaction, this will contain "OFFLINE".
mktransactionid Decimal C Transaction ID (unique only to the processing database utilised). Mandatory for all online transactions. The data with which to populate this field is obtained from: Field 36, TransactionID in Transaction Response 6 (Payware Ocius VX820RS Integration Guide) Field 38, TransactionID in Transaction Response 7 (VX 810 and VX 820 POS Client Integration Guide). For an online transaction, the field TransactionID will contain the transaction ID assigned by the authorisation server.
uniquestring String C Unique string provided by the merchant, in order for offline transactions without an associated transaction ID can be released by matching this string within the database. Mandatory for all offline transactions. The data with which to populate this field is obtained from: Field 36, TransactionID in Transaction Response 6 (Payware Ocius VX 820RS Integration Guide) Field 38, TransactionID in Transaction Response 7 (VX 810 and VX820 POS Client Integration Guide). For an offline transaction, the field TransactionID will contain a unique string based on the time of day and the hardware PTID.
</releaseonholdrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 87
Request Example <?xml version="1.0"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ProcessMsg xmlns="https://www.commidea.webservices.com"> <Message> <ClientHeader xmlns="https://www. commidea.webservices.com"> <SystemID>00000000</SystemID> <SystemGUID>000d0d0f-f0dc-000a-0d0c-e1234567890c4</SystemGUID> <Passcode>00000000</Passcode> <SendAttempt>0</SendAttempt> </ClientHeader> <MsgType xmlns="https://www. commidea.webservices.com">RELEASEONHOLDREQUEST</MsgType> <MsgData xmlns="https://www. commidea.webservices.com"> <![CDATA[<releaseonholdrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="ONHOLD"> <authdb>TEST_AUTHDB2</authdb> <mktransactionid>1969925</mktransactionid> </releaseonholdrequest>]]></MsgData> </Message> </ProcessMsg> </soap:Body> </soap:Envelope>
Web Services Integration Guide – V2.0 – 30th July 2014 88
Release Response The Message Type for the payer authentication enrolment check response is RELEASEONHOLDRESPONSE and the namespace is ONHOLD.
Section/Fields Type/Format Description <releaseonholdresponse> result String Result of the release request. Result types are:
RELEASED
mktransactionid Decimal Transaction ID (unique only to the processing database utilised)
authdb String The authorisation database within the VeriFone infrastructure which processed the transaction during authorization
</releaseonholdresponse>
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>00000000</SystemID><SystemGUID>000d0d0f-f0dc-000a-0d0c-e1234567890c4</SystemGUID><Passcode/><ProcessingDB>TEST_AUTHDB2</ProcessingDB><SendAttempt>0</SendAttempt><CDATAWrapping>false</CDATAWrapping></ClientHeader><MsgType>RELEASEONHOLDRESPONSE</MsgType><MsgData><releaseonholdresponse xmlns="ONHOLD"><result>RELEASED</result><mktransactionid>1969925</mktransactionid><authdb>TEST_AUTHDB2</authdb></releaseonholdresponse></MsgData></ProcessMsgResult></ProcessMsgResponse></soap:Body></soap:Envelope>
Web Services Integration Guide – V2.0 – 30th July 2014 89
PAN Hash Service As part of the Web Service offered by VeriFone, a merchant may submit a PAN to be hashed. In order to allow future hash developments, the type of hash requested is also part of the request.
Hash Request The Message Type is HASHPANREQUEST and the namespace is HASH.
This request contains the PAN and the type of hash to be performed from the available list of types.
Fieldname Type Usage Description <hashrequest> pan Decimal M PAN hashtype Decimal M Hash type
Acceptable values are: 1 – GDET (SHA-256)
</hashrequest>
Request Example <?xml version="1.0"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ProcessMsg xmlns="https://www.commidea.webservices.com"> <Message> <ClientHeader xmlns="https://www. commidea.webservices.com"> <SystemID>00000000</SystemID> <SystemGUID>000d0d0f-f0dc-000a-0d0c-e1234567890c4</SystemGUID> <Passcode>00000000</Passcode> <SendAttempt>0</SendAttempt> </ClientHeader> <MsgType xmlns="https://www. commidea.webservices.com">HASHPANREQUEST</MsgType> <MsgData xmlns="https://www. commidea.webservices.com"> <![CDATA[<hashrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="HASH"> <pan>4929123123123</pan> <hashtype>1</hashtype> </hashrequest>]]> </MsgData> </Message> </ProcessMsg> </soap:Body> </soap:Envelope>
Web Services Integration Guide – V2.0 – 30th July 2014 90
Hash Response
The Message Type is HASHRESPONSE and the namespace is HASH.
This message will contain the PAN, hashed according to the requested hash type submitted.
Fieldname Type Usage Description <hashresponse> Hash String M Hashed PAN </hashresponse>
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>00000000</SystemID> <SystemGUID>000d0d0f-f0dc-000a-0d0c-e1234567890c4</SystemGUID> <Passcode/> <ProcessingDB>TEST_AUTHDB2</ProcessingDB> <SendAttempt>0</SendAttempt> <CDATAWrapping>false</CDATAWrapping> </ClientHeader> <MsgType>HASHRESPONSE</MsgType> <MsgData><hashresponse xmlns="HASH"><hash> VUEARmiUf10aJ70CtI7f9Uozlk7B9draSR/CNvBn7Fc=</hash></hash esponse></MsgData> </ProcessMsgResult> </ProcessMsgResponse> </soap:Body> </soap:Envelope>
Web Services Integration Guide – V2.0 – 30th July 2014 91
IIN Lookup Service To perform IIN range validation prior to transaction processing, please use the following message format:
IIN Request The Message Type is IINREQUEST.
Fieldname Type Usage Description binrange Varchar(8) M First 6-8 digits of the card number
iinset tinyint M IIN set to be used
Example:
<iinrequest> <binrange>492912</binrange> <iinset>2</iinset> </iinrequest> Please refer to the IIN Lookup Service section for more details. IIN Response
The Message Type is IINRESPONSE.
Fieldname Type Usage Description mkiintableid decimal(18,0) O Unique entry ID within the database mkcardschemeid decimal(18,0) O Unique Card Scheme ID mkiinsetid decimal(18,0) O This is the IIN set ID that the entry relates to that will
account for differences in acquirer and currency differences.
sortorder int O This is the order within the set to organise the IIN entries. Note: There are no possible orders; it is a running starting ‘1’ till ‘n’ within each IIN set.
fromrange varchar(10) O The starting range for the IIN entry torange varchar(10) O The ending for range for the IIN entry valid bit O Indicates whether the card scheme range is valid schemename varchar(300) O The card scheme name the IIN entry belongs to issuenorequired bit O Indicates whether an issue number is required issuenolength int O If an issue number is required, indicates the length of the
issue number track2issuenoposition int O Location within track2 to find the issue number position.
This position is one-based, and includes the start sentinel.
startdaterequired bit O Indicates if a start date is required track2startdateformat int O Available Values:
0 = Full Validation 1 = Format Validation 2 = No Validation
track2startdatepos int O Location within track2 to find the start date startdatevalidation int O Start Date Validation that is required whilst operating in
Online Mode.
Web Services Integration Guide – V2.0 – 30th July 2014 92
Available Values: 0 = Full Validation 1 = Format Validation 2 = No Validation
expirydatevalidation int O Expiry Date Validation that is required whilst operating in Online Mode. Available Values: 0 = Full Validation 1 = Format Validation 2 = No Validation
refundstartdatevalidation int O Start Date Validation for refund transactions that is required whilst operating in Online Mode. Available Values: 0 = Full Validation 1 = Format Validation 2 = No Validation
refundexpirydatevalidation int O Expiry Date Validation that is required for refund transactions whilst operating in Online Mode. Available Values: 0 = Full Validation 1 = Format Validation 2 = No Validation
allowedpanlengths varchar(50) O This is a comma separated list of allowed PAN lengths cpcoption int O Available Values:
0 = Full Validation 1 = Format Validation 2 = No Validation
cpcidentificationmask varchar(50) O Mask used to identify if the PAN matches the format of a CPC card or not. Valid characters are: _ = A single numeric digit 0-9 = Specific numeric digit % = Any combination of numeric digits
noncpccardschemeid decimal(18,0) O Required to treat CPC cards as standard card types (e.g. Visa CPC as Visa)
allowpurchase bit O Purchase transactions are allowed. Valid Values would be ‘0’ or ‘1’.
allowrefund bit O Refund transactions are allowed. Valid Values would be ‘0’ or ‘1’.
allowpwcb bit O Purchase with Cashback transactions are allowed. Valid Values would be ‘0’ or ‘1’.
allowcashadv bit O Cash Advance transactions are allowed. Valid Values would be ‘0’ or ‘1’.
allowauthonly bit O Auth Only / Pre-Auth transactions are allowed. Valid Values would be ‘0’ or ‘1’.
allowchargeonly bit O Charge Only transactions are allowed. Valid Values would be ‘0’ or ‘1’.
allowrecurringtxn bit O Recurring Purchase transactions are allowed. Valid Values would be ‘0’ or ‘1’.
allowecompurchase bit O E-Commerce Purchase transactions are allowed. Valid Values would be ‘0’ or ‘1’.
allowecomrefund bit O E-Commerce Refund transactions are allowed. Valid Values would be ‘0’ or ‘1’.
allowpayerauth bit O Payer Authentication is allowed (e.g. Secure Code / VBV). Valid Values would be ‘0’ or ‘1’.
allowofflinetxns bit O Offline Txns are allowed. Valid Values would be ‘0’ or ‘1’.
Web Services Integration Guide – V2.0 – 30th July 2014 93
allowkeyedpan bit O Keyed PAN allowed for Customer Present purchase transactions. Valid Values would be ‘0’ or ‘1’. Original implementation was for this to do all keyed PAN Customer present transactions, however we need to differentiate so a refund column has been added
allowkeyedpanrefund bit O Keyed PAN allowed for Customer Present refund transactions. Valid Values would be ‘0’ or ‘1’.
allowmailorderpurchase bit O Mail Order (Customer Not Present) purchase transactions are allowed (Allow keyed PAN for CNP). Valid Values would be ‘0’ or ‘1’.
allowmailorderrefund bit O Mail Order (Customer Not Present) refund transactions are allowed (Allow keyed PAN for CNP). Valid Values would be ‘0’ or ‘1’.
allowtelorderpurchase bit O Telephone Order (Customer Not Present) purchase transactions are allowed (Allow keyed PAN for CNP). Valid Values would be ‘0’ or ‘1’.
allowtelorderrefund bit O Telephone Order (Customer Not Present) refund transactions are allowed (Allow keyed PAN for CNP). Valid Values would be ‘0’ or ‘1’.
allowunattended bit O Allow use on unattended terminals. Obsolete. Use AllowUnattended2 instead. Valid Values would be ‘0’ or ‘1’.
allowunattended2 int O Allow use on unattended terminals. Valid values are: 0 = Not Allowed 1 = ICC & Swipe & Contactless Equivalent 2 = Swipe & Contactless Equivalent 3 = ICC & Contactless Equivalent The terminal must validate this against the transaction capture method. This replaces the Allow Unattended Field
allowvr bit O Allow transactions to be voice referred. Valid Values would be ‘0’ or ‘1’.
allowzeropreauth bit O If Auth Only transactions are allowed, Zero value Auth only transactions are allowed. Valid Values would be ‘0’ or ‘1’.
allowmerchforceonline bit O Merchant is allowed to force the transaction online. Valid Values would be ‘0’ or ‘1’.
allowrecnoexpiry bit O If recurring transactions are allowed, a blank expiry date is allowed for recurring transactions. Valid Values would be ‘0’ or ‘1’.
allowavs bit O AVS supported by acquirer. Valid Values would be ‘0’ or ‘1’.
allowcsc bit O CSC supported by acquirer. Valid Values would be ‘0’ or ‘1’.
csclength int O Required length of the CSC value. csclength2 varchar(50) O This is a comma separated list of all supported lengths
of the CSC value. This is a restrictive list, so for this field to be optional, an entry of value ‘0’ must be entered. At time of writing, current acquirer mandates now deem that for customer not present transactions, CSC is mandatory. This replaces the CSC Length field
cpconly bit O Only CPC transactions are allowed (i.e. transactions where an invoice record is also provided)
supportansitrack2 bit O Card Scheme range supports ANSI and ISO format
Web Services Integration Guide – V2.0 – 30th July 2014 94
cards allowedansitrack2lengths varchar(50) O This is a comma separated list of all track2 lengths that
conform to the ANSI track2 format ansitrack2startdatepos int O Location within ANSI formatted track 2 to find either the
start date or the validity period. This position is one-based, and includes the start sentinel.
disableservicecodecheck bit O Determines whether Service Code Checking is to be performed in Online Mode Available values: True = Do not perform Service Code Checking False = Perform Service Code Checking
disableluhncheck bit O Determines whether LUHN Checking is to be performed in Online Mode Available values: True = Do not perform LUHN Checking False = Perform LUHN Checking
disablepancheck bit O Determines whether PAN Checking is to be performed in Online Mode Available values: True = Do not perform PAN Checking False = Perform PAN Checking
convertcashadvtopurch bit O If Cash Advance is not supported, in order to perform a cash advance transaction, represent as a purchase transaction
icconly bit O Card scheme range is ICC only. This field is used in conjunction with the ‘valid’ field. If the card scheme is marked as not being valid, and the transaction is an ICC transaction, if this flag is set, the terminal must allow the transaction provided it is an acceptable card scheme according to the merchant’s allowed card schemes list.
disableiccintcashback varchar(250) O This is a comma separated list of all of the terminal country codes that do not support international cashback for that card scheme
authcodelength int O This is the length of the auth code than needs to be generated. This value must include the LUHN check digit. Default value is 5
olstartdatevalidation int O Start Date Validation that is required whilst operating in Offline Mode. Available Values: 0 = Full Validation 1 = Format Validation 2 = No Validation Default Value: 0
olexpirydatevalidation int O Expiry Date Validation that is required whilst operating in Offline Mode.
olrefundstartdatevalidation int O Expiry Date Validation that is required whilst operating in Offline Mode. Available Values: 0 = Full Validation 1 = Format Validation 2 = No Validation Default Value: 0
olrefundexpirydatevalidation int O Expiry Date Validation that is required for refund
Web Services Integration Guide – V2.0 – 30th July 2014 95
transactions whilst operating in Online Mode. Available Values: 0 = Full Validation 1 = Format Validation 2 = No Validation Default Value: 0
oldisableservicecodecheck bit O Determines whether Service Code Checking is to be performed in Offline Mode Available values: True = Do not perform Service Code Checking False = Perform Service Code Checking Default Value: False
oldisableluhncheck bit O Determines whether LUHN Checking is to be performed in Offline Mode Available values: True = Do not perform LUHN Checking False = Perform LUHN Checking Default Value: False
oldisablepancheck bit O Determines whether PAN Checking is to be performed in Offline Mode Available values: True = Do not perform PAN Checking False = Perform PAN Checking Default Value: False
exdtchk bit O Indicates if an expiry date is required. If set to true, the terminal will extract the expiry date from the track2 for swipe transactions and prompt for expiry date entry for keyed transactions. ICC transactions are not affected by this setting. Default value: True
error_code varchar(4) O Error code if an error occurs. Otherwise '0000' error_message varchar(500) O Error message if an error occurs
Web Services Integration Guide – V2.0 – 30th July 2014 96
Value Added Services Web Services supports Value Added Services in order to; for example, enable merchants to offer their customers the ability to pay for goods and services using gift cards rather than EFT cards.
Value Added transactions do not require a session identifier to be generated in order to reference captured card details from the customer and sent directly to VeriFone. As these card types are not governed by card scheme rules relating PCI certification, they can be captured by the merchant directly and the details sent to VeriFone via the merchant’s web server without affecting compliancy.
As a result, to transact with value-added cards there is no requirement to utilise the card capture process or have a separate card capture webpage to have these posted directly to VeriFone.
For more information on this functionality, speak to the VeriFone Sales Account Manager.
PayPal
Express Checkout Process
To provide an overview of the PayPal process, please see the flow chart shown below:
4 3
5
6 7
2
1
Web Services Integration Guide – V2.0 – 30th July 2014 97
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 the VeriFone gateway. 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.
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.
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
Web Services Integration Guide – V2.0 – 30th July 2014 98
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/
Grant PayPal API Permissions Permissions will need to be granted to VeriFone 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.
Web Services Integration Guide – V2.0 – 30th July 2014 99
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.
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.
Web Services Integration Guide – V2.0 – 30th July 2014 100
SVS (Stored Value Solutions) Stored Value Solutions provide prepaid services to merchants. VeriFone 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
SVS integration messages are provided within the Value Added Services message formats section of this guide.
Part Payments VeriFone supports SVS’ “Part Payment” functionality on both Terminal and Web Service 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 Web Service 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.
VeriFone 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.
Web Services Integration Guide – V2.0 – 30th July 2014 101
Transax SV (Stored Value) Transax SV is a Value-added Service provided by Fidelity National Information Services (FIS). It can be integrated into merchant’s existing retail payment systems to provide a Gift Card programme.
The following functionality is supported:
• Balance Enquiry • Load/Activate • Refund • Sale • Top-Up
Gift Cards can be used for a range of retail sales and marketing applications including savings schemes, insurance claim schemes, promotions and staff incentives.
Duplication Checking As potential communication and technical issues could cause duplicate transactions to be requested, the Transax SV Host comprises a Duplicate Checking Mechanism to ensure that cards are only debited or credited once for each genuine transaction performed at the Point of Sale.
When the host receives a new transaction for a card, it retrieves the previous (last) transaction to carry out a comparison check between the two (current and previous) transactions, to ensure they are not duplicates.
There are two flavours of duplicate handling provided by Transax SV:
• If the merchant is supplying a Unique Merchant Reference (UMR) for every transaction, where this reference matches the reference for the previous transaction on the same card and the transaction amount, transaction type and merchant number all match then the latest transaction will be considered a duplicate and the result of the previous transaction will be returned.
• If no UMR is provided for each transaction; where the transaction amount, transaction type and merchant number all match then if the two transactions are within X minutes (where X is the duplicate window in minutes set on the Transax SV host on a card scheme level) of each other then the latest transaction will be considered a duplicate and the result of the previous transaction will be returned.
If merchants do not wish for this duplication checking to be in place, then the duplication window should be configured with Transax SV to be ‘0’ and no UMR should be supplied with each transaction.
Web Services Integration Guide – V2.0 – 30th July 2014 102
Ukash Ukash provide the ability for consumers to purchases good online without the need to access a bank account or use a bank or credit card. Some consumers also choose to use Ukash to retain control over the amount they spend.
Consumers will purchase a Ukash voucher from the nearest store where epay, PayPoint or PayZone terminals are available. This provides them with a Ukash voucher containing a 19 digit code which can be used to pay for goods with merchants who support this payment method, up to the value of the voucher.
For further information, visit www.ukash.com
Web Services Integration Guide – V2.0 – 30th July 2014 103
Fraud Screening Fraud screening is a Value Added Service which enables merchants to protect themselves against fraudulent transactions. The fraud screening functionality, provided by Retail Decisions (ReD), provides merchants with the ability to check the cardholder’s data against positive and negative cardholder history. As an example, this would enable a merchant to send through information such as delivery address, customer name and billing address, and card details, in order for ReD fraud screening to perform a check on the details provided.
Fraud screening is implemented independent of EFT processing. The following approach has been implemented when fraud screening is requested alongside EFT processing;
1. Transaction with Payer Authentication requested, will be performed with VBV (Verified By Visa) and MSC (MasterCard Secure Code), if successful will go onto fraud screening check.
2. ReD fraud screening check will be performed and result returned to the merchant (at this stage merchant will be able to make a decision whether to continue with the transaction or cancel).
3. If continue, the transaction authorisation request will be sent to the relevant acquirer for approval on the transaction value.
4. Finally, if transaction value is approved then a charge against the initial authorisation will be applied.
The ReD fraud screening request record is sent to the VeriFone servers and forwarded onto ReD for processing. The result returned is forwarded onto the merchant via the VeriFone servers. This enables the merchant to make an informed decision (accept/challenge/deny) on whether the transaction should be continued or cancelled.
The ReD request utilises the standard conversation handle timeout, which is 45 seconds.
The Value Added Service is supported with both Session-Based and Non-Session-Based transactions. The merchant also has the ability to utilise token IDs in place of card details.
Card Types ReD Fraud Screening supports all card types, irrespective of card brand in line with VeriFone’s IIN BIN range.
Please note: In order to utilise this service; merchants are required to have an agreement in place with ReD, prior to VeriFone setting up the merchant’s system. For more details, please contact your VeriFone Sales Account Manager.
Web Services Integration Guide – V2.0 – 30th July 2014 104
DCC (Dynamic Currency Conversion) Dynamic Currency Conversion (DCC), provided by Fexco enables retailers the functionality of allowing foreign customers using Visa and MasterCard, the choice to pay for their goods and services in their home billing currency or the local (base) currency.
In accordance with Visa and MasterCard compliancy, the cardholder will be provided with a choice on whether to accept or decline DCC, and that the terms and conditions associated with the service are disclosed to the customer at the point of sale.
Visa and MasterCard have separate rules and regulations governing the provision of DCC in the card present and card not present environments, however the principles of choice and disclosure are common to both card schemes.
Card Schemes Supported Fexco DCC service is only supported on Visa, MasterCard and Maestro cards.
Currencies Supported
The functionality currently only supports either British Pound Sterling or Euros as a base currency value.
E-Receipts
E-receipts provide cardholders with an email confirmation of their online purchase. VeriFone currently do not produce e-receipts for DCC. Should the cardholder require this service, then it is the responsibility of the merchant to provide to their customers.
The following details should be included from the DCC Response, as part of the accreditation for all DCC e-receipts:
Field Description OriginalTransactionValue The local (base) currency amount OriginalGratuityValue The local (base) currency gratuity amount OriginalCashBackValue The local (base) currency cashback amount OriginalTotalValue The local (base) currency total amount DCCConversionRateApplied Rate of conversion ForeignTransactionValue Foreign currency transaction amount ForeignTotalValue Foreign currency total amount including ‘ForeignCurrencySymbol’ Receipt Disclaimer Receipt Disclaimer Foreign MID Foreign Merchant Identification number Foreign TID Foreign Terminal Identification number
Please note: Maestro cards are only available if supported by the merchant’s acquirer. For more details, please contact your VeriFone Sales Account Manager.
Web Services Integration Guide – V2.0 – 30th July 2014 105
Transaction Flow Fexco DCC uses a real-time Dynamic Host Service (DHS) when identifying if a card is eligible for DCC and to obtain an accurate exchange rate.
The general flow of a DCC transaction is as follows:
1. Merchant’s website presents a card entry page to cardholder to take payment details
2. Cardholder enters Visa/MasterCard details for payment
3. Payment details are passed onto VeriFone’s DCC server (DHS) which performs an eligibility check and returns a response back to the merchant via the VeriFone hosted payment page:
a. True – provides cardholder with a choice to pay in the local trading currency amount (base currency) or the foreign (home) currency amount with the DCC exchange rate.
b. False – provides cardholder with the amount to pay in the original currency only.
4. Depending on the cardholder’s selection, the following will be executed:
a. Foreign currency – if the cardholder chooses to pay in the foreign currency, the applicable (Visa/MasterCard) DCC disclaimer page will be displayed allowing the cardholder to print the payment information and continue with the transaction in the home currency amount.
b. Local currency - If local currency is selected, the transaction will continue without conversion.
5. The payment details will be sent to the cardholder’s acquirer and/or issuer for authorisation of the selected currency amount.
6. Once the payment details have been authorised the applicable (Visa/MasterCard) transaction confirmation page will be displayed to the cardholder.
7. Lastly, VeriFone send the settlement files to the Fexco Host system at 11pm every day for submission.
Fexco act as a middle entity for all transactions processed by merchants utilising the Fexco DCC service. When Fexco receive the settlement files from VeriFone, the files will be sent to the applicable acquirer for submission.
Web Services Integration Guide – V2.0 – 30th July 2014 106
Value-added Services Message Formats This section contains all the message formats required for Value Added functionality. These transactions do not require sessions to be generated prior to processing the transaction request as the card details can be captured by the merchant without affecting PCI compliancy.
All Value Added Services should be wrapped using the same Message and ClientHeader messages as the Non-Session-Based process.
All the XML data that is submitted to a VeriFone 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.
Message All requests and responses will be wrapped in a message type, as defined below:
Section/Fields Type/Format Mandatory / Optional
Description
<message> MsgType String M Type of message MsgData String M Data ClientHeader ClientHeader M ClientHeader information </message>
ClientHeader The clientheader is used to validate requests and direct them to the correct server:
Section/Fields Type/Format Mandatory / Optional
Description
<ClientHeader> SystemID Decimal M Allocated ID SystemGUID String M Allocated GUID Passcode String M Allocated Passcode ProcessingDB String M (for Confirmation Request and
Rejection Request) This indicates the database to use for processing a particular request. The maximum size limit for this field is 15. Special characters are allowed.
Web Services Integration Guide – V2.0 – 30th July 2014 107
If left blank the default database will be used. N.B. Should only be left blank for the initial transaction request
SendAttempt Integer M This field should be populated with ‘0’. Functionality will be added in future to support Send Attempt verification.
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>
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.
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>
Web Services Integration Guide – V2.0 – 30th July 2014 108
PayPal Message Formats VeriFone supports the ability for merchants to integrate the PayPal Express Checkout process into the payment solution at the same time as integrating VeriFone’s transaction processing functionality.
The formats to be adhered to for this process are detailed within this section.
The Message Type for PayPal requests is PPI and the namespace is PAYPAL.
SetExpressCheckout Request Section/Fields Type/Format Optional /
Required Description
<paypalsetexpresscheckoutrequest> merchantreference String O Merchant can add a reference to
cross reference responses relating to the same transaction
user String R Merchant PayPal API username pwd String R Merchant PayPal API password version String R Version number of the NVP API
service signature String R Merchant PayPal signature string subject String O Email address of a PayPal account
that has granted permission to make this call. Set this parameter only if calling an API on a different user’s behalf
returnurl String R URL to which the customer’s browser is returned after choosing to pay with PayPal. NOTE: PayPal recommends that the value be the final review page on which the customer confirms the order and payment or billing agreement. Character length and limitations: no limit.
cancelurl String R URL to which the customer is returned if he does not approve the use of PayPal to pay. NOTE: PayPal recommends 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
Web Services Integration Guide – V2.0 – 30th July 2014 109
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, 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.
Web Services Integration Guide – V2.0 – 30th July 2014 110
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. 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.
Web Services Integration Guide – V2.0 – 30th July 2014 111
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 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
Web Services Integration Guide – V2.0 – 30th July 2014 112
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, 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
Web Services Integration Guide – V2.0 – 30th July 2014 113
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
</paypalsetexpresscheckoutrequest>
SetExpressCheckout Response Section/Fields Type/Format Description <paypalsetexpresscheckoutresponse> merchantreference String Merchant can add a reference to cross reference
responses relating to the same transaction paypalrequestid Decimal Unique PayPal request identifier token String A timestamped token by which to identify to PayPal
that the merchant is processing this payment with Express Checkout. NOTE: The token expires after three hours. If the token is set in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. Character length and limitations: 20 single-byte characters
errorcode String Error identifier (Please see Appendix E for a full list of errors)
shortmessage String General message (Please see Appendix E for a full list of errors)
longmessage String Detailed message (Please see Appendix E for a full list of errors)
serveritycode String Severity of the error (Please see Appendix E for a full list of errors)
</paypalsetexpresscheckoutresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 114
GetExpressCheckoutDetails Request Section/Fields Type/Format Optional /
Required Description
<paypalgetexpresscheckoutrequest> merchantreference String O Merchant can add a reference to
cross reference responses relating to the same transaction
user String R Merchant PayPal API username pwd String R Merchant PayPal API password version String R Version number of the NVP API
service signature String R Merchant PayPal signature
string subject String O Email address of a PayPal
account that has granted the merchant permission to make this call. Set this parameter only if calling an API on a different user’s behalf
token String R A timestamped token, the value of which was returned by SetExpressCheckout response. Character length and limitations: 20 single-byte characters Allowable values: An unexpired token
</paypalgetexpresscheckoutrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 115
GetExpressCheckoutDetails Response Section/Fields Type/Format Description <paypalgetexpresscheckoutresponse> merchantreference String Merchant can add a reference to cross reference
responses relating to the same transaction paypalrequestid Decimal Unique PayPal request identifier token String The timestamped token value that was returned by
SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations: 20 single-byte characters
email String Email address of payer. Character length and limitations: 127 single-byte characters
payerid String Unique PayPal customer account identification number. Character length and limitations:13 single-byte alphanumeric characters.
payerstatus String Status of payer. Valid values are: • Verified • Unverified
Character length and limitations: 10 single-byte alphabetic characters. Possible values: verified, unverified
salutation String Payer’s salutation. Character length and limitations: 20 single-byte characters
firstname String Payer’s first name. Character length and limitations: 25 single-byte characters
middlename String Payer’s middle name. Character length and limitations: 25 single-byte characters
lastname String Payer’s last name. Character length and limitations: 25 single-byte characters
suffix String Payer’s suffix. Character length and limitations: 12 single-byte characters
countrycode String Payer’s country of residence in the form of ISO standard 3166 two-character country codes. Character length and limitations: Two single-byte characters
business String Payer’s business name. shiptoname String Person’s name associated with this address.
Character length and limitations: 32 single-byte characters
shiptostreet String First street address. Character length and limitations: 100 single-byte characters
shiptostreet2 String Second street address. Character length and limitations: 100 single-byte characters
shiptocity String Name of city. Character length and limitations: 40 single-byte characters
shiptostate String State or province
Web Services Integration Guide – V2.0 – 30th July 2014 116
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>
Web Services Integration Guide – V2.0 – 30th July 2014 117
DoExpressCheckoutPayment Request Section/Fields Type/Format Optional /
Required Description
<paypaldoexpresscheckoutrequest> merchantreference String O Merchant can add a reference to
cross reference responses relating to the same transaction
user String R Merchant PayPal API username pwd String R Merchant PayPal API password version String R Version number of the NVP API
service signature String R Merchant PayPal signature string subject String O Email address of a PayPal account
that has granted permission to make this call. Set this parameter only if calling an API on a different user’s behalf
token String R The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations: 20 single-byte characters
paymentaction String R How to obtain payment: • ‘Sale’ indicates that this is a
final sale for which payment is being requested.
• ‘Authorization’ indicates that this payment is a basic authorisation subject to settlement with PayPal Authorisation & Capture.
• ‘Order’ indicates that this payment is an order authorisation subject to settlement with PayPal Authorisation & Capture.
If the transaction does not include a one-time purchase, this field is ignored. NOTE: This value cannot be set to Sale in SetExpressCheckout request and then change this value to Authorisation or Order on the final API DoExpressCheckoutPayment request. If the value is set to Authorisation or Order in 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
Web Services Integration Guide – V2.0 – 30th July 2014 118
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. 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
Web Services Integration Guide – V2.0 – 30th July 2014 119
$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 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.
Web Services Integration Guide – V2.0 – 30th July 2014 120
Character length and limitations: 100 single-byte characters
shiptophonenumber String O Phone number. Character length and limit: 20 single-byte characters
</paypaldoexpresscheckoutrequest>
PayPal ExpressItem Section/Fields Type/Format Optional / Required Description <paypalexpressitem> name String O Item name.
Character length and limitations: 127 single-byte characters
number String O Item number. Character length and limitations: 127 single-byte characters
qty Integer O Item quantity. Character length and limitations: Any positive integer
taxamt Decimal O Item sales tax. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
amt Decimal O Cost of item Limitations: Value can be positive, negative or zero and must not exceed $10,000 USD in any currency. No currency 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>
Web Services Integration Guide – V2.0 – 30th July 2014 121
DoExpressCheckoutPayment Response Section/Fields Type/Format Description <paypaldoexpresscheckoutresponse> merchantreference String Merchant can add a reference to cross reference
responses relating to the same transaction paypalrequestid Decimal Unique PayPal request identifier token String The timestamped token value that was returned by
SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations:20 single-byte characters
transactionid String Unique transaction ID of the payment. NOTE: If the PaymentAction of the request was Authorisation or Order, this value is the merchant’s AuthorizationID for use with the Authorization & Capture APIs. Character length and limitations:19 single-byte characters Possible values: Transaction specific
transactiontype String The type of transaction Character length and limitations:15 single-byte characters Possible values:
• Cart • Express-checkout
paymenttype String Indicates whether the payment is instant or delayed. Character length and limitations: Seven single-byte characters Possible values:
• None • eCheck • Instant
ordertime String Time/date stamp of payment Possible values: Transaction specific
amt Decimal The final amount charged, including any shipping and taxes from the Merchant Profile. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. Possible Values: Transaction specific
currencycode String A three-character currency code for one of the currencies listed in PayPay-Supported Transactional Currencies.
feeamount Decimal PayPal fee amount charged for the transaction. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of 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.
Web Services Integration Guide – V2.0 – 30th July 2014 122
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.
• 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
Web Services Integration Guide – V2.0 – 30th July 2014 123
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>
DoAuthorization Request Section/Fields Type/Format Optional / Required Description <paypaldoauthorizationrequest> merchantreference String O Merchant can add a reference to
cross reference responses relating to the same transaction
user String R Merchant PayPal API username pwd String R Merchant PayPal API password version String R Version number of the NVP API
service signature String R Merchant PayPal signature string subject String O Email address of a PayPal account
that has granted permission to make this call. Set this parameter only if calling an API on a different user’s behalf
transactionid String R The value of the order’s transaction identification number returned by PayPal. Character length and limits: 19 single-byte characters maximum
amt Decimal R Amount to authorize. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
transactionentity String O Type of transaction to authorize. The only allowable value is Order,
Web Services Integration Guide – V2.0 – 30th July 2014 124
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>
DoAuthorization Response Section/Fields Type/Format Description <paypaldoauthorizationresponse> merchantreference String Merchant can add a reference to cross reference
responses relating to the same transaction paypalrequestid Decimal Unique PayPal request identifier transactionid String An authorisation identification number.
Character length and limits: 19 single-byte characters Amt Decimal The amount specified in the request. currencycode String A three-character currency code for one of the currencies
listed in PayPal Supported Transactional Currencies. errorcode String Error identifier (Please see Appendix E for a full list of
errors) shortmessage String General message (Please see Appendix E for a full list of
errors) longmessage String Detailed message (Please see Appendix E for a full list of
errors) serveritycode String Severity of the error (Please see Appendix E for a full list
of errors) </paypaldoauthorizationresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 125
DoCapture Request Section/Fields Type/Format Optional / Required Description <paypaldocapturerequest> merchantreference String O Merchant can add a reference to cross
reference responses relating to the same transaction
user String R Merchant PayPal API username pwd String R Merchant PayPal API password version String R Version number of the NVP API service signature String R Merchant PayPal signature string subject String O Email address of a PayPal account that
has granted permission to make this call. Set this parameter only if calling an API on a different user’s behalf
authorizationid String R The authorisation identification number of the payment to capture. This is the transaction id returned from DoExpressCheckoutPayment or DoDirectPayment. Character length and limits: 19 single-byte characters maximum.
amt Decimal R Amount to capture. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
currencycode String O A three-character currency code for one of the currencies listed in PayPay-Supported Transactional Currencies.
completetype String R The value Complete indicates that this the last capture intended to be made. The value NotComplete indicates an intention to make additional captures. NOTE: If Complete, any remaining amount of the original authorised transaction is automatically voided and all remaining open authorisations are voided. Character length and limits: 12 single-byte alphanumeric characters
invnum String O An invoice number or other identification number that is displayed to the merchant and customer in his transaction history. NOTE: This value on DoCapture will overwrite a value previously set on DoAuthorization. NOTE: The value is recorded 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-
Web Services Integration Guide – V2.0 – 30th July 2014 126
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 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>
Web Services Integration Guide – V2.0 – 30th July 2014 127
DoCapture Response Section/Fields Type/Format Description <paypaldocaptureresponse> merchantreference String Merchant can add a reference to cross reference responses
relating to the same transaction paypalrequestid Decimal Unique PayPal request identifier authorizationid String The authorisation identification number specified in the request.
Character length and limits: 19 single-byte characters maximum transactionid String Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters parenttransactionid String Parent or related transaction identification number. This field is
populated for the following transaction types:
• Reversal. Capture of an authorised transaction. • Reversal. Reauthorisation of a transaction. • Capture of an order. The value of
ParentTransactionID is the original • OrderID. • Authorisation of an order. The value of
ParentTransactionID is the original • OrderID. • Capture of an order authorisation. • Void of an order. The value of ParentTransactionID
is the original OrderID. Character length and limits: 16 digits in xxxx-xxxx-xxxx-xxxx format
receipttid String Receipt identification number Character length and limits: 16 digits in xxxx-xxxx-xxxx-xxxx format
transactiontype String The type of transaction • Cart • Express-checkout
Character length and limitations: 15 single-byte characters paymenttype String Indicates whether the payment is instant or delayed.
Character length and limitations: Seven single-byte characters ordertime String Time/date stamp of payment. For example: 2006-08-
15T17:23:15Z. currencycode String A three-character currency code for one of 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
Web Services Integration Guide – V2.0 – 30th July 2014 128
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 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>
Web Services Integration Guide – V2.0 – 30th July 2014 129
DoVoid Request Section/Fields Type/Format Optional / Required Description <paypaldovoidrequest> merchantreference String O Merchant can add a reference to cross
reference responses relating to the same transaction
user String R Merchant PayPal API username pwd String R Merchant PayPal API password version String R Version number of the NVP API service signature String R Merchant PayPal signature string subject String O Email address of a PayPal account that has
granted permission to make this call. Set this parameter only if calling an API on a different user’s behalf
authorizationid String R The value of the original authorisation identification number returned by a PayPal product. IMPORTANT: If voiding a transaction that has been reauthorised, use the ID from the original authorisation, and not the reauthorisation. Character length and limits: 19 single-byte characters
note String O An informational note about this void that is displayed to the payer in email and in his transaction history. Character length and limits: 255 single-byte characters
</paypaldovoidrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 130
DoVoid Response Section/Fields Type/Format Description <paypaldovoidresponse> merchantreference String Merchant can add a reference to cross reference responses relating
to the same transaction paypalrequestid Decimal Unique PayPal request identifier authorizationid String The authorisation identification number specified in the request.
Character length and limits: 19 single-byte characters errorcode String Error identifier (Please see Appendix E for a full list of errors) shortmessage String General message (Please see Appendix E for a full list of errors) longmessage String Detailed message (Please see Appendix E for a full list of errors) serveritycode String Severity of the error (Please see Appendix E for a full list of errors) </paypaldovoidresponse>
RefundTransaction Request Section/Fields Type/Format Optional / Required Description <paypalrefundtransactionrequest> merchantreference String O Merchant can add a reference to
cross reference responses relating to the same transaction
user String R Merchant PayPal API username pwd String R Merchant PayPal API password version String R Version number of the NVP API
service signature String R Merchant PayPal signature string subject String O Email address of a PayPal
account that has granted permission to make this call. Set this parameter only if calling an API on a different user’s behalf
transactionid String R Unique identifier of a transaction Character length and limitations: 17 single-byte alphanumeric characters
refundtype String R Type of refund being made: • Other • Full • Partial
amt Decimal O Refund amount. Amount is required if RefundType is Partial. NOTE: If RefundType is Full, do not set Amount.
currencycode String O A three-character currency code for one of the currencies listed in PayPal Supported Transactional Currencies
note String O Custom memo about the refund. Character length and limitations: 255 single-byte alphanumeric characters
</paypalrefundtransactionrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 131
RefundTransaction Response Section/Fields Type/Format Description <paypalrefundtransactionresponse> merchantreference String Merchant can add a reference to cross reference
responses relating to the same transaction paypalrequestid Decimal Unique PayPal request identifier currencycode String A three-character currency code for one of the
currencies listed in PayPal Supported Transactional Currencies
refundtransactionid String Unique transaction ID of the refund. Character length and limitations:17 single-byte characters
netrefundamt Decimal Amount subtracted from PayPal balance of original recipient of payment to make this refund
feerefundamt Decimal Transaction fee refunded to original recipient of payment
grossrefundamt Decimal Amount of money refunded to original payer errorcode String Error identifier (Please see Appendix E for a full list of
errors) shortmessage String General message (Please see Appendix E for a full list
of errors) longmessage String Detailed message (Please see Appendix E for a full list
of errors) serveritycode String Severity of the error (Please see Appendix E for a full
list of errors) </paypalrefundtransactionresponse>
DoReauthorization Request Section/Fields Type/Format Optional / Required Description <paypaldoreauthorizationrequest> merchantreference String O Merchant can add a reference to
cross reference responses relating to the same transaction
user String R Merchant PayPal API username pwd String R Merchant PayPal API password version String R Version number of the NVP API
service signature String R Merchant PayPal signature string subject String O Email address of a PayPal
account that has granted permission to make this call. Set this parameter only if calling an API on a different user’s behalf
authorizationid String R The value of a previously authorised transaction identification number returned by PayPal. Character length and limits: 19 single-byte characters maximum
amt Decimal R Amount to reauthorise. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have
Web Services Integration Guide – V2.0 – 30th July 2014 132
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>
DoReauthorization Response Section/Fields Type/Format Description <paypaldoreauthorizationresponse> merchantreference String Merchant can add a reference to cross reference
responses relating to the same transaction paypalrequestid Decimal Unique PayPal request identifier authorizationid String A new authorisation identification number.
Character length and limits:19 single-byte characters errorcode String Error identifier (Please see Appendix E for a full list of
errors) shortmessage String General message (Please see Appendix E for a full list
of errors) longmessage String Detailed message (Please see Appendix E for a full list
of errors) serveritycode String Severity of the error (Please see Appendix E for a full
list of errors) </paypaldoreauthorizationresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 133
Stored Value Solutions (SVS) Message Formats Merchants choosing to accept Stored Value Solutions (SVS) cards online will need to adopt the below message formats in order to send transaction requests for SVS cards through to the Web Services Gateway.
When an SVS Request message is sent; the transaction will be processed and a response message returned. The response message will contain a status message of either:
• ‘Approved’ • ‘Rejected’ • ‘Error’
Transactions with a status of ‘Approved’ will need to be confirmed or reversed using the SVS Confirmation request. The transaction is completed and the result returned within an updated SVS response message.
SVS Request The Stored Value Solutions (SVS) Request type contains all the information required to process a transaction using an SVS card.
The Namespace is ‘SVS’ and the Message Type is ‘SVSREQUESTMESSAGE’
Section/Fields Type/ Format
Length Optional / Required
Description
<svsrequestmessage> messagetype Integer M No Message Type
0 Balance Enquiry *1 Pre-Authorization Message 2 Redemption Message
*3 Tip Message 4 Cancellation 5 Merchandise Return Message 6 Card Recharge Message
*7 Pre-Authorisation Completion Message *8 Card Activation Message 9 Issue 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 original STAN must be passed in with reversals
offlineauthcode String 10 O Offline Authorisation Code cardnumber String 19 O SVS card number
Web Services Integration Guide – V2.0 – 30th July 2014 134
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>
SVS Confirmation
The SVS Confirm type contains all the information required to confirm or reverse a transaction. This confirmation must be received less than 45 seconds after sending an SVS Request otherwise the transaction will be automatically reversed.
The Namespace is ‘SVS’ and the Message Type is ‘svscnf’. The ‘id’ value to pass in the confirmation message is the ‘id’ value received in the SVSRESPONSEMESSAGE message.
Section/Fields Type/ Format
Optional / Required
Description
<svscnf> id Decimal M ID received in SVSRESPONSEMESSAGE message confirmationtype Integer M 01 – Confirm
02 – Reverse </svscnf>
Web Services Integration Guide – V2.0 – 30th July 2014 135
SVS Response The SVS Response type contains all the result information from an SVS request.
Section/Fields Type/ Format
Length Description
<svsresponsemessage> id Decimal The request ID responsecode String 2 Code Return Description
01 Approval 02 Inactive Card 03 Invalid Card Number 04 Invalid Transaction Code 05 Insufficient Funds 06 No Previous Authorisations 07 Invalid Message 08 No Card Found 09 Insufficient Funds due to Outstanding pre-
authorisation. 10 Denial – No previous authorisation 11 No Authorization number 12 Invalid Authorization number 13 Maximum single recharge exceeded 14 Maximum working balance exceeded 15 Host Unavailable 16 Invalid Card Status 17 Unknown dealer/Store Code - Special edit 18 Maximum number of recharges exceeded 19 Invalid card verification value 20 Invalid PIN number / PIN Locked 21 Card already issued 22 Card not issued 23 Card already used 24 Manual Transaction not allowed 25 Mag Stripe read not valid 26 Transaction type unknown 27 Invalid tender type 28 Invalid customer type 29 n/a 30 Max number of redemption exceeded 31 Invalid currency code 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) status String This is the status of the transaction. Response options are:
CONFIRMED REVERSED APPROVED REJECTED ERROR
Web Services Integration Guide – V2.0 – 30th July 2014 136
authcode String Authorisation code </svsresponsemessage>
Transax SV Message Formats In order to process Transax SV transactions it is necessary to submit a Transax SV Request, process the response received before sending a confirmation message.
Transax SV does not require a session to be generated via Session-Based, prior to processing, as the card number is not mandated by card scheme rules and its presence within the merchant network does not cause any issues with PCI compliance from a merchant perspective.
Transax SV Request MsgType: TRANSAXSV
Fieldname Type Usage Description transactiontype String M This is the Transax SV transaction type:
Valid values are: 1 = Load / Activate 2 = TopUp 3 = Sale (Debit) 4 = Balance Enquiry 5 = Refund
transactiondatetime String O Date and time the transaction was started, based on GMT (DD/MM/YYYY HH:MM:SS)
apacsterminalcapabilities String M This indicates the type of terminal/EPOS system and its capabilities. 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 Technical Services to confirm that they have the correct capabilities
merchantnumber String M This is the card acceptor number allocated by Fidelity National Information Services
capturemethod Integer M This indicates how the card details were obtained. Acceptable values are: Swipe = 1 Keyed Cardholder Present = 2 Keyed Cardholder Not Present = 3
Web Services Integration Guide – V2.0 – 30th July 2014 137
Keyed E-Commerce = 4 carddetails Composite
Object M Card Details Class, as described below
transactionamount String M Amount to be authorised with implied decimal point ie. £10.00 is represented as 1000 and 0.10 is represented as 10
isocurrencycode String M This is the numeric ISO currency code (3 numeric digits) currencyid Decimal M This is the VeriFone allocated currency identifier currencyexponent String M No of decimal places in currency field i.e. GBP will be 2 uniquemerchantreference String O Merchant can add a reference to cross reference
responses relating to the same transaction transaxsvaccountid Decimal M This is the identifier of the Transax SV account used to
process the transaction
Card Details Fieldname Type Usage Description
track2 String C Entire Track2 contents (including start and end sentinels and LRC)
Mandatory for swiped transaction. Not required for keyed transaction
primaryaccountnumber String M Primary account number of the card. This must be either the value entered manually or extracted from the track2
starredprimaryaccountnumber String M This is the starred representation of the primary account number (PAN/card number). This must be all starred bar the last four digits of the card number
expirydate String (4 numeric digits)
O Card expiry month and year (YYMM). Optional for keyed transactions, not required for swipe transactions
issuenumber String (Up to 2 digits)
O Issue number of the card that has been entered as part of the transaction. Optional for keyed transactions, not required for swipe transactions
securitycode String (Up to 4 digits)
O Card security code of the card
Web Services Integration Guide – V2.0 – 30th July 2014 138
Transax SV Response MsgType: TRANSAXSVAUTHORISATIONRESULT
Fieldname Type Description transactionid Decimal This is the ID allocated to the transaction status String This is the status of the transaction. Response options are:
CONFIRMED APPROVED REJECTED REVERSING PENDING REVERSAL FAILED REVERSED ERROR DECLINED
errorcode Integer This is the code representing an error condition generated by VeriFone messagenumber String Terminal specific transaction count between 0000-9999 acquirerresponsecode String This indicates if the transaction was authorised or declined by FIS host.
00 = Authorised 05 = Declined
message String This is the message returned from the FIS host for printing and on screen display
balance Decimal This is the amount represented from the FIS host in response to the balance enquiry request. This will be formatted in accordance with the currency details provided as part of the original transaction request
authorisationcode String This is the authorisation code allocated to the transaction if the transaction was authorised by the FIS host
Web Services Integration Guide – V2.0 – 30th July 2014 139
Transax SV Request Example <?xml version="1.0"?> <Message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <ClientHeader xmlns="https://www. commidea.webservices.com"> <SystemID>30003361</SystemID> <SystemGUID>855AEB5F-7E23-44AE-8AEF-3A7E7E6AD5AA</SystemGUID> <Passcode>89375589</Passcode> <SendAttempt>0</SendAttempt> <NoCDATAWrapping>true</NoCDATAWrapping> </ClientHeader> <MsgType xmlns="https://www. commidea.webservices.com">TRANSAXSV</MsgType> <MsgData xmlns="https://www. commidea.webservices.com"><![CDATA[<?xml version="1.0"?> <transaxsv xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="TRANSAXSV"> <transactiontype>4</transactiontype> <transactiondatetime>2011-08-16 09:30:05.000</transactiondatetime> <apacsterminalcapabilities>4298</apacsterminalcapabilities> <merchantnumber>96222222</merchantnumber> <capturemethod>4</capturemethod> <carddetails> <primaryaccountnumber>9826150920108228</primaryaccountnumber> <starredprimaryaccountnumber>************8228</starredprimaryaccountnumber> <expirydate>1112</expirydate> <securitycode>944</securitycode> </carddetails> <transactionamount>0.01</transactionamount> <isocurrencycode>826</isocurrencycode> <currencyid>1</currencyid> <currencyexponent>2</currencyexponent> <transaxsvaccountid>2</transaxsvaccountid> </transaxsv>]]></MsgData> </Message> <?xml version="1.0"?> <Message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <ClientHeader xmlns="https://www. commidea.webservices.com"> <SystemID>30003361</SystemID> <SystemGUID>855AEB5F-7E23-44AE-8AEF-3A7E7E6AD5AA</SystemGUID> <Passcode /> <ProcessingDB>TEST_AUTHDB2</ProcessingDB> <SendAttempt>0</SendAttempt> <CDATAWrapping>false</CDATAWrapping> </ClientHeader> <MsgType xmlns="https://www. commidea.webservices.com">TRANSAXSVAUTHORISATIONRESULT</MsgType> <MsgData xmlns="https://www. commidea.webservices.com"><transaxsvauthorisationresult xmlns="TRANSAXSV"><transactionid>140</transactionid><status>DECLINED</status><messagenumber>145</messagenumber><acquirerresponsecode>05</acquirerresponsecode><message>BAL=0.00 Decline Inactive</message><balance>0.00000</balance><authorisationcode></authorisationcode><terminalnumber>22</terminalnumber></transaxsvauthorisationresult></MsgData></Message>
Web Services Integration Guide – V2.0 – 30th July 2014 140
Transax SV Confirmation
MsgType: TRANSAXSVCONFIRMATION
Fieldname Type Usage Description transactionid Decimal M This is the ID allocated to the transaction by VeriFone confirmationtype Integer M This indicates whether to confirm or reverse the authorisation. Valid values
are: 1 = Confirm 2 = Reverse
Web Services Integration Guide – V2.0 – 30th July 2014 141
Transax SV Final Result MsgType: TRANSAXSVFINALRESULT
Fieldname Type Description transactionid Decimal This is the ID allocated to the transaction status String This is the result of the transaction:
CONFIRMED REJECTED
errorcode Integer This is the code representing the error condition generated by VeriFone
Transax SV Confirmation Example <transaxsvconfirmation xmlns=”TRANSAXSV”> <transactionid>...</transactionid> <confirmationtype>...</confirmationtype> </transaxsvconfirmation> <transaxsvfinalresult xmlns=”TRANSAXSV”> <transactionid>...</transactionid> <status>...</status> </transaxsvfinalresult>
Web Services Integration Guide – V2.0 – 30th July 2014 142
Ukash Message Formats In order for merchants to accept Ukash voucher as a payment method, the below message formats should be integrated to.
The Message Type for Ukash requests is UKASH and the namespace is UKASH.
Ukash GetSettleAmount Request Section/Fields Type/Format Description <ukashrequest > merchantreference String
Varchar(50) Merchant can add a reference to cross reference responses relating to the same transaction
requesttype String Varchar(50)
The request type; ukashgetsettleamount
ukashlogin String Char(20)
This is a login name that will be supplied to the merchant by Ukash to send with each transaction sent to the Ukash gateway
ukashpassword String Char(20)
This is the password for the Ukash login name, which will be supplied to the merchant by Ukash
transactionid String Char(20)
This is a unique reference to the transaction, which must be supplied by the merchant. It must be unique across the merchant’s ukashLogin. E.g. for gaming clients, the format of the transactionId must be casinoId_TransNo
brandid String Char(20)
Ukash will supply a brand id to the merchant for each of the brands he wishes to differentiate between. The appropriate brand id must then be sent through on each transaction request
vouchernumber String Char(19)/ Char(16)
This is the number printed on the voucher or card, the number will be 19 digits for vouchers and 16 digits for cards.
vouchervalue decimal
This is the value of the voucher presented in 2 decimal points
basecurr String Char(3)
This is the currency in which the product/service is being sold. It is the merchant base currency for the transaction. It must be given in the character ISO standard. Refer to Appendix B to verify
vouchercurrproductcode String Char(3)
7-9 digits of voucher number
</ukashrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 143
Ukash PartSpendVoucher Request Section/Fields Type/Format Description <ukashrequest > merchantreference String
Varchar(50) Merchant can add a reference to cross reference responses relating to the same transaction
requesttype String Varchar(50)
The request type; ukashpartspendvoucher
ukashlogin String Char(20)
This is a login name that will be supplied to the merchant by Ukash to send with each transaction sent to the Ukash gateway
ukashpassword String Char(20)
This is the password for the Ukash login name, which will be supplied to the merchant by Ukash
transactionid String Char(20)
This is a unique reference to the transaction, which must be supplied by the merchant. It must be unique across the merchant’s ukashLogin. E.g. for gaming clients, the format of the transactionId must be casinoId_TransNo
brandid String Char(20)
Ukash will supply a brand id to the merchant for each of the brands he wishes to differentiate between. The appropriate brand id must then be sent through on each transaction request
vouchernumber String Char(19)/ Char(16)
This is the number printed on the voucher or card, the number will be 19 digits for vouchers and 16 digits for cards.
vouchervalue decimal
This is the value of the voucher presented in 2 decimal points
ticketvalue Decimal This is the value, which the merchant wishes to charge from the voucher or account. It is presented in 2 decimal points in the merchant base currency.
basecurr String Char(3)
This is the currency in which the product/service is being sold. It is the merchant base currency for the transaction. It must be given in the character ISO standard. Refer to Appendix B to verify
merchdatetime String Char(19)
This is the Merchant’s time stamp of the transaction. Format “yyyy-mm-dd hh:mm:ss”
redemptiontype String Char(1)/Char(2) This indicates what the transaction is being used for. See Section 7.9 for redemption Types. The numeric identifier must be supplied
vouchercurrproductcode String Char(3)
7-9 digits of voucher number
</ukashrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 144
Ukash FullValueVoucher Request Section/Fields Type/Format Description <ukashrequest> merchantreference String
Varchar(50) Merchant can add a reference to cross reference responses relating to the same transaction
requesttype String Varchar(50)
The request type; ukashfullvaluevoucher
ukashlogin String Char(20)
This is a login name that will be supplied to the merchant by Ukash to send with each transaction sent to the Ukash gateway
ukashpassword String Char(20)
This is the password for the Ukash login name, which will be supplied to the merchant by Ukash
transactionid String Char(20)
This is a unique reference to the transaction, which must be supplied by the merchant. It must be unique across the merchant’s ukashLogin. E.g. for gaming clients, the format of the transactionId must be casinoId_TransNo
brandid String Char(20)
Ukash will supply a brand id to the merchant for each of the brands he wishes to differentiate between. The appropriate brand id must then be sent through on each transaction request
vouchernumber String Char(19)/ Char(16)
This is the number printed on the voucher or card, the number will be 19 digits for vouchers and 16 digits for cards.
vouchervalue decimal
This is the value of the voucher presented in 2 decimal points
basecurr String Char(3)
This is the currency in which the product/service is being sold. It is the merchant base currency for the transaction. It must be given in the character ISO standard. Refer to Appendix B to verify
merchdatetime String Char(19)
This is the Merchant’s time stamp of the transaction. Format “yyyy-mm-dd hh:mm:ss”
redemptiontype This indicates what the transaction is being used for. See Section 7.9 for redemption Types. The numeric identifier must be supplied
vouchercurrproductcode String Char(3)
7-9 digits of voucher number
</ukashrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 145
Ukash PartSpendAccount Request Section/Fields Type/Format Description <ukashrequest> merchantreference String
Varchar(50) Merchant can add a reference to cross reference responses relating to the same transaction
requesttype String Varchar(50)
The request type; ukashpartspendaccount
ukashlogin String Char(20)
This is a login name that will be supplied to the merchant by Ukash to send with each transaction sent to the Ukash gateway
ukashpassword String Char(20)
This is the password for the Ukash login name, which will be supplied to the merchant by Ukash
transactionid String Char(20)
This is a unique reference to the transaction, which must be supplied by the merchant. It must be unique across the merchant’s ukashLogin. E.g. for gaming clients, the format of the transactionId must be casinoId_TransNo
brandid String Char(20)
Ukash will supply a brand id to the merchant for each of the brands he wishes to differentiate between. The appropriate brand id must then be sent through on each transaction request
vouchernumber String Char(19)/ Char(16)
This is the number printed on the voucher or card, the number will be 19 digits for vouchers and 16 digits for cards.
ukashpin String Char(4)
This is the Pin number printed on the Ukash Card. 4 digit value, field is required for all card based transactions
vouchervalue decimal
This is the value of the voucher presented in 2 decimal points
ticketvalue Decimal This is the value, which the merchant wishes to charge from the voucher or account. It is presented in 2 decimal points in the merchant base currency.
basecurr String Char(3)
This is the currency in which the product/service is being sold. It is the merchant base currency for the transaction. It must be given in the character ISO standard. Refer to Appendix B to verify
merchdatetime String Char(19)
This is the Merchant’s time stamp of the transaction. Format “yyyy-mm-dd hh:mm:ss”
redemptiontype This indicates what the transaction is being used for. See Section 7.9 for redemption Types. The numeric identifier must be supplied
vouchercurrproductcode String Char(3) 7-9 digits of voucher number </ukashrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 146
Ukash FullSpendAccount Request Section/Fields Type/Format Description <ukashrequest> merchantreference String
Varchar(50) Merchant can add a reference to cross reference responses relating to the same transaction
requesttype String Varchar(50)
The request type; ukashfullspendaccount
ukashlogin String Char(20)
This is a login name that will be supplied to the merchant by Ukash to send with each transaction sent to the Ukash gateway
ukashpassword String Char(20)
This is the password for the Ukash login name, which will be supplied to the merchant by Ukash
transactionid String Char(20)
This is a unique reference to the transaction, which must be supplied by the merchant. It must be unique across the merchant’s ukashLogin. E.g. for gaming clients, the format of the transactionId must be casinoId_TransNo
brandid String Char(20)
Ukash will supply a brand id to the merchant for each of the brands he wishes to differentiate between. The appropriate brand id must then be sent through on each transaction request
vouchernumber String Char(19)/ Char(16)
This is the number printed on the voucher or card, the number will be 19 digits for vouchers and 16 digits for cards.
ukashpin String Char(4)
This is the Pin number printed on the Ukash Card. 4 digit value, field is required for all card based transactions
vouchervalue decimal
This is the value of the voucher presented in 2 decimal points
basecurr String Char(3)
This is the currency in which the product/service is being sold. It is the merchant base currency for the transaction. It must be given in the character ISO standard. Refer to Appendix B to verify
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>
Web Services Integration Guide – V2.0 – 30th July 2014 147
TransactionEnquiry Request Used to check if there is an issue with the Ukash server, and there is a requirement to check with Ukash if the transaction was successful or not.
Section/Fields Type/Format Description <ukashrequest> merchantreference String
Varchar(50) Merchant can add a reference to cross reference responses relating to the same transaction
requesttype String Varchar(50)
The request type; ukashtransactionenquiry
ukashlogin String Char(20)
This is a login name that will be supplied to the merchant by Ukash to send with each transaction sent to the Ukash gateway
ukashpassword String Char(20)
This is the password for the Ukash login name, which will be supplied to the merchant by Ukash
transactionid String Char(20)
This is a unique reference to the transaction, which must be supplied by the merchant. It must be unique across the merchant’s ukashLogin. E.g. for gaming clients, the format of the transactionId must be casinoId_TransNo
brandid String Char(20)
Ukash will supply a brand id to the merchant for each of the brands he wishes to differentiate between. The appropriate brand id must then be sent through on each transaction request
vouchernumber String Char(19)/ Char(16)
This is the number printed on the voucher or card, the number will be 19 digits for vouchers and 16 digits for cards.
ukashpin String Char(4)
This is the Pin number printed on the Ukash Card. 4 digit value, field is required for all card based transactions
vouchervalue decimal
This is the value of the voucher presented in 2 decimal points
basecurr String Char(3)
This is the currency in which the product/service is being sold. It is the merchant base currency for the transaction. It must be given in the character ISO standard. Refer to Appendix B to verify
merchdatetime String Char(19)
This is the Merchant’s time stamp of the transaction. Format “yyyy-mm-dd hh:mm:ss”
redemptiontype This indicates what the transaction is being used for. See Section 7.9 for redemption Types. The numeric identifier must be supplied
vouchercurrproductcode String Char(3) 7-9 digits of voucher number </ukashrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 148
Ukash Response The Message Type for the Ukash response is UKASH and the namespace is TRM.
Section/Fields Type/Format Description <ukashresponse> requesttype String
Varchar(50) The request type
amountreference String Char(255)
Merchants using the GetSettleAmount method need only fill in this tag. All other merchants should send a blank string in this tag.
mktransactionID Decimal Unique transaction ID txcode Integer This is a transaction status/return code. It determines whether the
voucher was successfully redeemed or not. A “0” means that the voucher was successfully redeemed. Any other code will reflect an unsuccessful redemption due to an invalid voucher or an error. See Section 7.8 for possible return codes
txdescription String Char(255)
This is a text field used to give a short text description of the transaction status/return code
transactionid String Char(20)
The transactionId is returned as reference to link the request and response XML
settleamount Decimal This is the value of the transaction in the base currency accountbalance Decimal The account balance in the currency of the account. Applicable to
account based transactions only. accountcurrency String
Char(3) This is the currency the card account. It will be given in the character ISO standard.
changeissuevouchernumber String Char(19)
For ticket price redemption, this is the voucher number for the change. For full value redemption, this will be blank
changeissuevouchercurr String Char(3)
This is the currency of the change issue voucher. It will be given in the character ISO standard. Refer to Appendix B
changeissueamount Decimal This is the value of the change presented in 2 decimal places. For full value redemption, this will be blank
changeissueexpirydate String Char(10)
This is the expiry date for the change issue voucher in the format yyyy-mm-dd
issuedvouchernumber String Char(19)
For issued vouchers this is the new voucher number. This tag will only be returned for IssueVoucher transactions.
issuedvouchercurr String Char(3)
The currency of the issued voucher. It will be given in the character ISO standard. Refer to Appendix B. This tag will only be returned for IssueVoucher transactions.
issuedamount Decimal This is the value of the issued voucher presented in 2 decimal places. This tag will only be returned for IssueVoucher transactions.
issuedexpirydate String Char(10)
This is the expiry date for the issued voucher in the format yyyy-mm-dd. This tag will only be returned for IssueVoucher transactions.
ukashtransactionid String Char(50)
This is a unique reference to the transaction
currencyconversion Boolean This flag indicates whether currency 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>
Web Services Integration Guide – V2.0 – 30th July 2014 149
Ukash Return Code List Type of Message Message Code Message Description Comments Transaction Status 0 Accepted Redemption successful 1 Declined Redemption unsuccessful 99 Failed An error occurred during the processing of
the transaction hence the system could not successfully complete the redemption of the voucher.
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.
Web Services Integration Guide – V2.0 – 30th July 2014 150
Ukash Error Code List Type of Error 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 VeriFone Merchant Helpdesk
Web Services Integration Guide – V2.0 – 30th July 2014 151
Ukash Product Codes Region Country State Currency General
Issues (020-200)
Cash Back
Issues (201-400)
Gambling Restricted (401-600)
Reserved (601-800)
Reserved (801-999)
United Kingdom
United Kingdom
United Kingdom
GBP 001 201 401 601 801
Europe Europe Europe EUR 011 211 411 611 811
Europe Poland Poland PLN 151 351 551 751 951
Europe Austria Austria EUR 021 221 421 621 821
Europe Belgium Belgium EUR 022 222 422 622 822
Europe Finland Finland EUR 023 223 423 623 823
Europe France France EUR 024 224 424 624 824
Europe Germany Germany EUR 025 225 425 625 825
Europe Greece Greece EUR 026 226 426 626 826
Europe Ireland Ireland EUR 027 227 427 627 827
Europe Italy Italy EUR 028 228 428 628 828
Europe Luxembourg Luxembourg EUR 029 229 429 629 829
Europe Netherlands Netherlands EUR 030 230 430 630 830
Europe Portugal Portugal EUR 031 231 431 631 831
Europe Spain Spain EUR 011 211 411 611 811
Europe Switzerland Switzerland CHF 033 233 433 633 833
Europe Denmark Denmark DKK 034 234 434 634 834
Europe Sweden Sweden SEK 035 235 435 635 835
Europe Czech Republic Czech Republic
CZK 036 236 436 636 836
Europe Norway Norway NOK 037 237 437 637 837
Europe Romania Romania RON 038 238 438 638 838
Europe Hungary Hungary HUF 039 239 439 639 839
Europe Bulgaria Bulgaria BGL 040 240 440 640 840
Europe Estonia Estonia EEK 041 241 441 641 841
North America
USA USA USD 99 299 499 699 899
North America
USA Alabama USD 100 300 500 700 900
North America
USA Alaska USD 101 301 501 701 901
North America
USA Arizona USD 102 302 502 702 902
North America
USA Arkansas USD 103 303 503 703 903
North America
USA California USD 104 304 504 704 904
North America
USA Colorado USD 105 305 505 705 905
North America
USA Connecticut USD 106 306 506 706 906
North America
USA Delaware USD 107 307 507 707 907
North America
USA Florida USD 108 308 508 708 908
North America
USA Georgia USD 109 309 509 709 909
North America
USA Hawaii USD 110 310 510 710 910
Web Services Integration Guide – V2.0 – 30th July 2014 152
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
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 Massachusetts
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 USA Utah USD 143 343 543 743 943
Web Services Integration Guide – V2.0 – 30th July 2014 153
America
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
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
Fraud Screening Message Formats This section details all the messages which need to be constructed and sent, and received as a response. Fraud screening is supported with both Session-Based and Non-Session-Based transactions.
Accepted Characters Please refer to the tables below for character requirements utilised during the integration process.
String fields support the following alphanumeric characters:
A B C D E F G H I J K L M N O P Q R S T
U V W X Y Z a b c d e f g h i j k l m n
o p q r s t u v w x y z 0 1 2 3 4 5 6 7
8 9
Number fields only support the following characters:
0 1 2 3 4 5 6 7 8 9 .
Special Character fields (e.g. email) supports the String characters as well as the following characters:
- _ ‘ , . @ ?
Web Services Integration Guide – V2.0 – 30th July 2014 154
One nine two fields support all the string characters as well as the following characters:
+ / <
Key:
Please refer to the below keys for indication of the ‘Size’ fields within the message formats:
Key Meaning No Size Specified X X no. Characters (Fixed Size) X-Y X to Y number of characters (variable size) W-X/Y-Za Either W to X or Y to Z. (Some fields are conditional based on their position. This is
specified in point a.)
This Value-added Service also has the ability to send token IDs in place of card details within the request message, which is referred to as ‘TKN’ within the ReD Request table.
The table illustrates message formats for the relevant transaction type as, i.e. ‘SB’ (Session-Based), ‘TKN’ (Tokenisation) and ‘NSB’ (Non-Session-Based). There are certain message formats which are only specific to the relevant transaction type. Fields containing ‘N/A’ (non-applicable) indicates that the specific message format is not required for the relevant transaction type, e.g. ‘sessionguid’ message format is only required for Session-Based transactions.
The Message Type for ReD Fraud request is REDFRAUDREQUEST.
ReD Fraud Request Name Type Size SB TKN NSB Description orderid String 12 O O O A unique identification for the order orderdatetime String 19 M M M The date and the time of the order authorizationamount String 2-10 M M M The amount of money that the
transaction is for paymentmethod String 1 M M M Code Meaning
R Retail request M Mail Order/Telephone
order request S Secure EC Transaction N Non-authenticated SET E Non-SET Transaction
Channel Encrypted T Telephone Order A Attempted Authentication
cardtype String 2 N/A O O The type of card currencycode String 3 M M M The country code in the ISO format –
e.g. 826 actioncode String 2 M M M Code Action to be performed
OA Online authorization only OC Online authorization and
auto-deposit OD Online Unconditional
Web Services Integration Guide – V2.0 – 30th July 2014 155
Deposit - submit the deposit to the payment processor host
BD GCX batch deposit
reddivnum String 1-15 M M M The RED division number (supplied by RED)
mksystemid Decimal 18 M M M The system id (only mandatory for tokens)
sessionguid String 32 M N/A N/A The Session GUID for Session-Based mktokenid Decimal 18 O O O A token ID
startdate String 4 N/A N/A O The start date for the card cardnumber String 10-19 N/A N/A O The number of the card expirationdate String 4 N/A N/A O The expiration date of the card issuenumber String 1-2 N/A N/A O The issue number of the card customerdetails customerdetails C1 C1 C1 The details of the customer shippingdetails shippingdetails O O O The details of where to ship the
products to customdata customdata O O O Any customer specific data oneninetwo oneninetwo O O O One nine two service data recipientdetails recipientdetails() O O O The details of the recipients productdetails productdetails() O O O The details of the products being sent repeateddataheader repeatedheader
data C2 C2 C2 A header required if there is any
repeated data (e.g. from recipient details or product details.
1 This section is mandatory if the “oneninetwo” section has been included in the message 2 This section is mandatory if the “productdetails” section has been included in the message
Customer Details Within the ReD Fraud Request message, the following customer details messages will be available to include within the integration message.
Name Type Size Usage Description customerid String 1-16 O The id number of the customer firstname String 1-30 C1 The customers first name lastname String 1-30 C1 The customers surname middleinitial String 1 C1 The customers middle initial birthdate String 10 C1 The birth date of the customer (YYYY-MM-
DD) emailaddress String 1-45 O The customers email address homephone String 1-19 O Home phone number of the customer workphone String 1-19 O Work phone number of the customer mobilephone String 1-19 O Mobile phone number of the customer addressline1 String 1-30 C1 Customers first line of address addressline2 String 1-30 O Customers second line of address city String 1-20 O Customers city state String 2-10 O Customers state countrycode String 3 C1 Customers country code (e.g. GBR)
Please note: This section is mandatory, only if 192 data has been requested.
Web Services Integration Guide – V2.0 – 30th July 2014 156
postcode String 1-9 C1 Customers post code ipaddress String 7-15 O Customers IP address (Note: IPv6
addresses are not supported) userid String 1-16 O Customers user id (alphanumeric, no special
characters) previouscustomer String 1 O Whether this customer has previously been
a customer (Y/N) fingerprint String 1-4000 O The fingerprint of the customers machine 1 These fields are mandatory if the “oneninetwo” section has been included in the message
Shipping Details
This is an optional field within the ReD Fraud Request message. If this field has been configured as required then the following fields will be available:
Name Type Size Usage Description shippingid String 1-16 O The items shipping ID firstname String 1-30 O The first name of the person to ship to lastname String 1-30 O The last name of the person to ship to middleinitial String 1 O The middle initial of the person to ship to emailaddress String 1-45 O The email address of the person to ship to homephone String 1-19 O The home phone number workphone String 1-19 O The work phone number mobilephone String 1-19 O The mobile number addressline1 String 1-30 O The address line number addressline2 String 1-30 O The 2nd line of the address city String 1-20 O The shipping city state String 2-10 O The state countrycode String 3 O The code of the country to ship to postcode String 1-9 O The post code of the country shippingmethod String 1 O Code Meaning
C Lowest Cost D Carrier Designated by
Customer I International M Military N Next Day / Overnight O Other P Store pickup T Two day service W Three day service
Custom Data If the merchant requires a fraud check on details specific to the customer, i.e. website address, then this optional field can be configured as a requirement. The following fields can be used to send the details:
Name Type Size Usage Description userdefinedfield userdefinedfields() O Custom data that can be sent in with the
request (alphanumeric & special characters)
website String 1-60 O The address of the website
Web Services Integration Guide – V2.0 – 30th July 2014 157
gmtoffset Integer 3 O Number of hours offset from GMT shipmessage String 1-160 O Message accompanying the shopping
items shipoccasion String 1 O The shipping occasion deliverycode String 3 O Code Meaning
CNC Cash and Carry DCT Digital Content DIG Digital Goods DNP Digital and Physical GFT Gift Certification PHY Physical Goods REN Renewals and Recharges SHW Shareware SVC Service
User Defined Field
The ‘userdefinedfield’ within the Custom Data field contains the following mandatory fields:
Name Type Size Usage Description key Integer 2 M A number from 1 to 25 value String 0-256 / 1-
301 M The value for the item which is sent in that
specific key field. 1 If the key is a number between 1 and 10 inclusive then the size is between 0 and 256 characters, while if the key is greater than 10, then the allowed size drops between 1 and 30 characters inclusive.
192 Data
The ‘oneninetwo’ section of the ReD Fraud Request message requests for additional customer data from this data service by ReD.
Name Type Size Usage Description gender String 1 C1 The gender of the person driverlicense String 1-20 O The driving license number passportnumber String 1-10 O The passport number passportexp String 10 O The passport expiry date (YYYY-MM-DD) passportissuingcountry String 3 O The country that issued the passport passportnationalitycode String 3 O The nationality code of the passport passportpersonalnumber String 16 O The personal number in the passport passportmrz1 String 44 O The MRZ1 code passportmrz2 String 44 O The MRZ2 code servicecode String 15 O Code Meaning
CheckID Check ID Check ProveID Prove ID Check ProveID_KYC
Prove ID KYC
apartmentno String 1-4 O The customers apartment number
Web Services Integration Guide – V2.0 – 30th July 2014 158
1 This field is conditional if we are sending a request to prove the id of the person by using the passport number and/or the driving licence number. It is also required if we are sending the driver license.
Web Services Integration Guide – V2.0 – 30th July 2014 159
Recipient Data In addition to the above fields, the ‘recipientdetails’ fields are available to perform a fraud check on the recipient’s details for the specific order.
Name Type Size Usage Description firstname String 1-30 O The recipients first name lastname String 1-30 O The recipients surname middleinitial String 1 O Middle initial of the recipient salutation String 1-5 O Recipient’s salutation (Miss, Mrs, Mr, Dr...) emailaddress String 1-45 O The email address of the recipient phonenumber String 1-19 O The phone number of the recipient addressline1 String 1-30 O Recipient address line 1 addressline2 String 1-30 O Recipient address line 2 city String 1-20 O Recipient city state String 2-10 O Recipient state countrycode String 3 O Recipient country code postcode String 1-9 O Recipient post code
Product Data
This field will provide information specific to the product for the particular purchase.
Name Type Size Usage Description ordersequencecode Decimal 2 M The sequence of the item (1-99) itemproductcode String 1-12 O The product code productdescription String 1-26 O The products description unitprice String 4-10 O The unit price of the item itempart String 1-30 O The Item part / EAN Number prodsku String 1-12 O Product number quantity String 4-12 O The number of products totalprice String 2-12 O The total price debitcreditindicator String 1 O Code Meaning
C Credit D Debit
partnumber String 1-30 O The products part number trackingnumber String 1-19 O The shipping tracking number giftmessage String 1-160 O The gift message for this item shippingcomments String 1-60 O Comments for shipping
Web Services Integration Guide – V2.0 – 30th July 2014 160
Repeated Data Header This field provides additional data relevant to the product details.
Name Type Size Usage Description orderitemrepeat Decimal 1-99 C1 Number of items in order netamount Decimal 2-12 C1 Total value of items freightamount Decimal 2-8 C1 The total cost of shipping refnumber String 1-17 C1 Purchase order number salestaxamount Decimal 2-12 C1 The amount of tax to be paid taxindicator String 1 C1 Code Meaning
A Alternate Tax Only G Both local and National Tax L Local Tax Only N National Tax Only X Non-taxable Transaction
destinationcountrycode String 3 C1 The destinations country code taxrate Decimal 3-4 C1 The rate of alternate tax applier totalamount Decimal 2-12 C1 The total monetary value of the transaction.
1 This is mandatory if the product data section has been included within the message.
Request Examples The following examples illustrate ReD fraud screening message formats utilised via session-based and non-session based transactions.
Session-Based Example The below session-based ReD fraud screening example contains several sections, i.e. ‘customerdetails’, ‘shippingdetails’, ‘productdetails’ and ‘repeateddataheader’.
<redrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="RED"> <sessionguid>A0A8B75F-3BFA-4ACE-808F-38EF70036E57</sessionguid> <orderdatetime>2012-030605:13:18</orderdatetime> <authorizationamount>104.98</authorizationamount> <paymentmethod>E</paymentmethod> <currencycode>826</currencycode> <actioncode>OA</actioncode> <customerdetails> <addressline1>10</addressline1> <addressline2>Acton Lane</addressline2> <city>Ashford</city> <countrycode>GBR</countrycode> <postcode>ME15 6LH</postcode> <customerid>17560024</customerid> <firstname>Nandini</firstname>
Please note: This section is mandatory only if the ‘productdetails’ field is included in the message.
Web Services Integration Guide – V2.0 – 30th July 2014 161
<lastname>Smith</lastname> <emailaddress>[email protected]</emailaddress> <homephone>09999999999</homephone> <ipaddress>00.00.00.00</ipaddress> <userid>17560020</userid> </customerdetails> <shippingdetails> <addressline1>10</addressline1> <addressline2>Stone lane</addressline2> <city>Southampton</city> <countrycode>GBR</countrycode> <postcode>ME154AZ</postcode> <shippingid>17560020</shippingid> <firstname>Adami</firstname> <lastname>Smith</lastname> <emailaddress> [email protected] </emailaddress> <homephone>09999999999</homephone> </shippingdetails> <productdetails><productdetails> <ordersequencecode>1</ordersequencecode> <productdescription>Colorado Steel Chimenea</productdescription> <unitprice>99.98</unitprice> <quantity>1</quantity> <totalprice>99.98</totalprice> <debitcreditindicator>D</debitcreditindicator> <trackingnumber>5055025560870</trackingnumber> </productdetails></productdetails> <repeateddataheader> <orderitemrepeat>1</orderitemrepeat> <netamount>99.98</netamount> <freightamount>5.00</freightamount> <refnumber>7005124</refnumber> <taxindicator>N</taxindicator> <totalamount>104.98</totalamount> </repeateddataheader> </redrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 162
Non-Session-Based Example The below non-session based example represents a message format with minimum data:
<redrequest xmlns="RED" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <mksystemid>10010735</mksystemid> <mktokenid>0</mktokenid> <orderdatetime>2012-02-12 18:18:08</orderdatetime> <authorizationamount>00.10</authorizationamount> <paymentmethod>R</paymentmethod> <currencycode>826</currencycode> <actioncode>OA</actioncode> <reddivnum>VERIFONE</reddivnum> <cardnumber>4929123123123</cardnumber> <startdate>0505</startdate> <expirationdate>1212</expirationdate> <customerdetails> <firstname>Adam</firstname> <lastname>Smith</lastname> <middleinitial>A</middleinitial> </customerdetails> </redrequest>
Web Services Integration Guide – V2.0 – 30th July 2014 163
ReD Fraud Response The below message format will be returned within the response message containing the relevant status of the message using ‘fraudstatuscode’.
Name Type Size Description mkredid Decimal 10 A unique transaction identifier
- Supplied by VeriFone requiredid Decimal 16 A unique identifier supplied by ReD orderid String 12 The order id from the request responsestatuscode String 10 The status of the authentication responsecode String 10 The payment processors response code responsedatetime String 10 The date the response was returned responseauthnumber String 6 The auth code responsemessage String 255 A message responseaddressverification String 18 Address verification code responsesecurity String 1 Card security response userid String 6 Additional customer identifier fraudstatuscode String 9 Code Meaning
ACCEPT No fraud detected DENY Recommend denial CHALLENGE Review for potential fraud NOSCORE Ignore fraud response ERROR Error in request / Internal error ENETFP Communication error EIVINF Invalid information
fraudresponsecode String 4 usecode String 1 Code Meaning
S Stop C Continue
neuralscore String 4 A number between 0 and 999 stating the score this request has generated.
rulecategoryflag String 400 Data on the rules hit errorcode* String The error code from VeriFone errormessage String The message describing the error
* Please contact ReD support for assistance, if an error code of ‘50’ (RED_ERROR) is returned in the response message.
Web Services Integration Guide – V2.0 – 30th July 2014 164
Response Example <redresponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="RED"> <mkredid>2885</mkredid> <requiredid>700004876777</requiredid> <orderid>2885</orderid> <responsestatuscode>PENDING</responsestatuscode> <responsecode /><responsedatetime /><responseauthnumber /><responsemessage /><responseaddressverification /><responsesecurity /><userid /><fraudstatuscode>ACCEPT</fraudstatuscode> <fraudresponsecode>0150</fraudresponsecode> <usecode>C</usecode> <neuralscore /><rulecategoryflag /> <errorcode>0</errorcode> </redresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 165
Dynamic Currency Conversion (DCC) Message Formats In order for merchants to provide customers with the option to utilise DCC, the below message format should be used for integration purposes. DCC is supported with both session-based and non-session-based transaction types.
The following message format should be used for session-based transactions:
DCC Request
The Message Type for DCC requests is ‘VGFEXCODCCREQUEST’ and the namespace is ‘DCC’.
Field Name Type/Format Description <vgfexcodccrequest> accountid Decimal The id of the account number as supplied by VeriFone acquirerid Decimal Decimal value representing an acquirer - this is converted by
VeriFone as one of the below: 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 (Please note: the ‘AcquirerID’ should be setup as per the EFT account, confirmed by VeriFone)
cardschemeid Decimal The card scheme which is being used: 2 – Visa 3 – MasterCard 4 – Maestro
mid String The merchant identification number is from the EFT account and will be confirmed by VeriFone
basecurrencycode String The currency code that the value is given in is from the EFT account in either GBP or Euros including the ISO currency code, provided by VeriFone
transactionvalue Decimal A numeric value of the cost of the transaction value (up to and including 11 digits, this also includes the minor units as described in ISO 4217)
gratuityvalue Decimal A numeric value of the cost of the gratuity value (up to and including 11 digits, this also includes the minor units as described in ISO 4217)
cashbackvalue Decimal A numeric value of the cost of the cashback value (up to and including 11 digits, this also includes the minor units as described in ISO 4217)
Web Services Integration Guide – V2.0 – 30th July 2014 166
dcc Integer This is the numeric representation of the DCC service provider, for DCC rate lookups. The numeric representation utilised by Fexco DCC is 3.
txntype String The type of this transaction: 01 – Purchase 02 – Refund
terminalid String The id of the terminal desk cardcurrencydecimalplaces Integer Number of decimal places of currency. If unknown, this can be
set to ‘-1’, otherwise this should be taken from the ISO currency code information listing for the cardholder currency
capturemethod Integer The method by which we have captured this transaction. Acceptable values are: Keyed Customer Not Present Mail Order = 2 Keyed Customer Not Present Telephone Order = 11 Keyed Customer Not Present E-Commerce = 12
transactiondatetime String YYYY-MM-DD HH:MM cardcountrycode String This should be the country code from the ISO specification. sessionguid String Session-Based session guid <vgfexcodccrequest>
DCC Request Example <vgfexcodccrequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="DCC"> <accountid>140007715</accountid> <acquirerid>1</acquirerid> <cardschemeid>3</cardschemeid> <mid>6819049</mid> <basecurrencycode>826</basecurrencycode> <transactionvalue>10.00</transactionvalue> <gratuityvalue>0.00</gratuityvalue> <cashbackvalue>0.00</cashbackvalue> <dcc>3</dcc> <txntype>01</txntype> <terminalid>12345678</terminalid> <cardcurrencydecimalplaces>2</cardcurrencydecimalplaces> <capturemethod>12</capturemethod> <transactiondatetime>2012-08-14 10:10</transactiondatetime> <cardcountrycode>978</cardcountrycode> <sessionguid>AC1D2BC9-C33E-435E-86CD-B21A2D9B51A8</sessionguid> </vgfexcodccrequest>]]></MsgData>
Web Services Integration Guide – V2.0 – 30th July 2014 167
DCC Response Upon receiving a DCC request, the Fexco server (within the VeriFone infrastructure) will perform an eligibility check to determine if DCC is possible on the Card ID received in the message.
If the result is false then the value of ‘0’ will be returned in the DCC response message and will continue with the transaction in the base (original) currency.
The Message Type for DCC response is ‘FEXCODCCRESPONSE’ and the namespace is ‘DCC’.
Field Name Type/Format Description <fexcodccresponse> id Decimal Response identifier mksystemid Decimal Merchant system ID eligible Boolean Identifies if DCC was possible on the CardID received
in the request message. The valid values are: 0 = Not Eligible 1 = Eligible
originalmid String Original Merchant ID originaltransactionvalue Decimal Original transaction value originalgratuityvalue Decimal Original gratuity value originalcashbackvalue Decimal Original cashback value originaltotalvalue Decimal Original total value originalcurrencycode String Original currencycode foreignmid String Foreign Merchant ID foreigntid String Foreign Terminal ID foreignaccountid Decimal This must be used in the EFT transaction request
should the transaction be processed in the cardholders preferred currency
foreignauthcentreid Decimal Foreign Authcentre ID foreigntransactionvalue Decimal This must be used in the EFT transaction request
should the transaction be processed in the cardholders preferred currency
foreigngratuityvalue Decimal This must be used in the EFT transaction request should the transaction be processed in the cardholders preferred currency
foreigncashbackvalue Decimal This must be used in the EFT transaction request should the transaction be processed in the cardholders preferred currency
foreigntotalvalue Decimal This must be used in the EFT transaction request should the transaction be processed in the cardholders preferred currency
foreigncurrencycode String This must be used in the EFT transaction request should the transaction be processed in the cardholders preferred currency
foreigncurrencysymbol String Foreign currency symbol foreigncurrencyabbreviation String Foreign currency abbreviation foreigncurrencydecimalpointcharacter
String This must be used in the EFT transaction request should the transaction be processed in the cardholders preferred currency
foreigncurrencydecimalplaces Integer This must be used in the EFT transaction request should the transaction be processed in the cardholders preferred currency
Web Services Integration Guide – V2.0 – 30th July 2014 168
dccconversiontext String This should be stored for reconciliation purposes dccconversionrateapplied Decimal This should be stored for reconciliation purposes dcccommissionfee Decimal This should be stored for reconciliation purposes dccmarkupfee Decimal This should be stored for reconciliation purposes receiptdisclaimer String This information should be provided to the cardholder
with any e-receipts exchangerateagreementdate String This is the date and time that the rate response was
returned from Fexco <fexcodccresponse>
DCC Response Example <fexcodccresponse xmlns="DCC">
<id>113994</id> <mksystemid>10000953</mksystemid> <eligible>1</eligible> <originalmid>6819049</originalmid> <originaltransactionvalue>10.00000</originaltransactionvalue> <originalgratuityvalue>0.00000</originalgratuityvalue> <originalcashbackvalue>0.00000</originalcashbackvalue> <originaltotalvalue>10.00000</originaltotalvalue> <OriginalCurrencyCode>826</OriginalCurrencyCode> <foreignmid>6819049</foreignmid> <foreigntid>20420001</foreigntid> <foreignaccountid>140008000</foreignaccountid> <foreignauthcentreid>19</foreignauthcentreid> <foreigntransactionvalue>24.32000</foreigntransactionvalue> <foreigngratuityvalue>0.00000</foreigngratuityvalue> <foreigncashbackvalue>0.00000</foreigncashbackvalue> <foreigntotalvalue>24.32000</foreigntotalvalue> <foreigncurrencycode>036</foreigncurrencycode> <foreigncurrencysymbol>AUD</foreigncurrencysymbol> <foreigncurrencyabbreviation>AUD</foreigncurrencyabbreviation> <foreigncurrencydecimalpointcharacter>.</foreigncurrencydecimalpointcharacter> <foreigncurrencydecimalplaces>2</foreigncurrencydecimalplaces> <dccconversionrateapplied>2.43220</dccconversionrateapplied> <dcccommissionfee>0.00000</dcccommissionfee> <dccmarkupfee>2.99000</dccmarkupfee> <receiptdisclaimer>I HAVE CHOSEN NOT TO USE THE MASTERCARD CURRENCY CONVERSION PROCESS AND AGREE THAT I WILL HAVE NO RECOURSE AGAINST MASTERCARD CONCERNING THE CURRENCY CONVERSION OR ITS DISCLOSURE</receiptdisclaimer> <exchangerateagreementdate>2010-11-18T09:51:00</exchangerateagreementdate>
</fexcodccresponse>
Web Services Integration Guide – V2.0 – 30th July 2014 169
Troubleshooting This section has been included in the manual to provide integrators with information to help resolve any issues.
Deserialization Errors When the elements which make up the XML document are populated with the necessary data, if the ‘Type’ of each is not adhered to then deserialization errors can occur.
Essentially, the information provided does not meet the format requirements and, when the XML document has been programmatically checked, it could not be parsed correctly.
An example of this would be:
If the ‘Track2’ element were to be populated with data that does not match the predefined type, (in this case, the track2 data should consist of a numeric value), then a deserialization error will be produced. The error will detail which element(s) contained the mismatch, which enables the problem to be resolved by checking what information was passed and comparing this to the required type.
1. The XML document ‘TRecord’ contains PAN information that doesn’t satisfy the type requirements:
....
<PAN>CardNumber</PAN>
....
2. A deserialization error is returned within the ‘InternalError’ tag, detailing which field caused the issue (in this case ‘PAN’):
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <CardTxnResponse xmlns="https://www.commidea.webservices.com"> <VeriFoneTxnResponse> <StdResponse /> <InternalError>[16277] TransactionProcessor.DeserializeXml: Bad Format in TRecord_Pan</InternalError> </VeriFoneTxnResponse> </CardTxnResponse> </soap:Body> </soap:Envelope>
Web Services Integration Guide – V2.0 – 30th July 2014 170
APPENDIX A VeriFone Error Codes Error Code
General Description Additional Technical Description (if required)
Recommended Action
0001 Unspecified error Contact VeriFone 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 VeriFone
0013 File permanently locked A file required by the EFT library was still locked after EFT FIO TRIES attempts.
Contact VeriFone
0014 Out of memory The library has failed to allocate sufficient heap.
Contact VeriFone
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 Check system configuration
Web Services Integration Guide – V2.0 – 30th July 2014 171
format 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. · 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
Web Services Integration Guide – V2.0 – 30th July 2014 172
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-Purchasing Card (where invoice data is not valid/required)
Re-enter transaction without invoice data or prompt for a valid Purchasing 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 VeriFone Support
0065 Invalid voucher target type The Target Voucher Type is invalid (M-Voucher)
Please contact VeriFone Support
0066 Invalid Refund Pin The refund pin entered is invalid Please enter the correct refund pin if continues to fail, please contact VeriFone 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
Web Services Integration Guide – V2.0 – 30th July 2014 173
0068 Report Failed Integrated report failed Contact VeriFone 0069 Gratuity value exceeded Check Gratuity Value Check Gratuity Value 0070 Invalid Capture Not
Supported Check PAYware 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 VeriFone
0076 Card is online only Attempt to process an online only card whilst offline
Check network or use another card
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 gateway, contact VeriFone Merchant Helpdesk.
0098 Unknown Client When using transaction Configure POS routing for that Point Of
Web Services Integration Guide – V2.0 – 30th July 2014 174
Unknown Transaction Source Unknown Message
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.
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 VeriFone 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 VeriFone Support
0106 General Enqueue Error General VeriFone Enqueueing Error
Please contact VeriFone Support
0107 Transaction Confirmation Error The transaction confirmation has errored.
Please retry the confirmation and if continues to fail please contact VeriFone Support
0108 Payer Auth Error The Payer Auth has encountered an error.
Please check the error message response and contact VeriFone support.
0109 Ukash Auth Error The Ukash transaction has encountered an error.
Please check the error message response and Contact VeriFone Support.
0110 Encryption Failure An error has occurred in the data encryption.
Please contact VeriFone Support
0111 Unable to build Auxillary Data Record
The auxillary data record failed to build correctly
Please contact VeriFone Support
0112 Transaction rejection error The attempt to reject the transaction has errored
Please retry the rejection and if continues to fail please contact VeriFone support
0113 Unknown Terminal The terminal\PTID is not recognised
Please contact VeriFone Support
0114 Invalid Download Type The download type is invalid Please contact VeriFone Support 0115 Terminal Registration Failed The attempt to register the terminal
has failed Please retry the registration if it continues to fail, please contact VeriFone Support
0116 Terminal has been deactivated The terminal has been marked as deactivated.
Please contact VeriFone Support
0117 Comms down Acquirer has been blocked in the database as acquirer is not processing any authorisations (comms down)
Please contact VeriFone 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 VeriFone Support
0119 Barclays Bonus Service Unavailable
Error response when Comms failure between server application and XLS Host experienced.
Please contact VeriFone Support
0120 Token Server Error The Token Server has encountered an error
Please contact VeriFone Support
0121 Purchase transaction type not The token provided does not allow Please supply another token that
Web Services Integration Guide – V2.0 – 30th July 2014 175
allowed on token purchase transactions 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 VeriFone 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 VeriFone 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 Account does not allow Account On file CNP transactions EFT transaction capture method does not support registration of details for Account On File processing
Please check that the terminal is online Please check the configuration of the account 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 VeriFone Support
0141 Ocius migration failed The PAYware Ocius migration failed on the database because the migration has not been setup / enabled
Contact VeriFone to arrange for migration
0142 S Record Timeout Terminal has timeout after 30 seconds from no response from user
Reprocess record if required
0143 Download Failed The software or configuration download on the Vx810 RS solution has failed to complete its download successfully.
Please retry the download if it continues to fail please contact VeriFone Support
Web Services Integration Guide – V2.0 – 30th July 2014 176
0150 Invalid PayPoint Configuration The PayPoint configuration that you have setup is invalid.
Please contact VeriFone Support
0151 No PayPoint Accounts There are no PayPoint accounts available.
Please contact VeriFone Support
0152 PayPoint Service Unavailable The PayPoint service is currently unavailable
Please retry the payment or contact VeriFone 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 VeriFone 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 VeriFone 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 VeriFone Support
0998
Token Not Found Supplied offline token ID does not have an associated online token
Please check the supplied offline token ID is correct
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 VeriFone 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 VeriFone 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 VeriFone Support 1005 Couldn't Extract Error Code
from Response The error code returned could not be extracted
Please contact VeriFone Support
1006 Failed to Retrieve System Config
Payment Page has failed to retrieve your System Configuration
Please contact VeriFone 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 VeriFone support
1008 Failed to Retrieve Session Data
Payment Page has failed to retrieve your session data
Please retry the payment or contact VeriFone support
1009 Failed to Create New Session Payment Page has failed to create a new session
Please retry the payment or contact VeriFone 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 VeriFone 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 VeriFone support
1014 Session Expired The session that you are trying to use has expired.
Please retry the payment or contact VeriFone support
Web Services Integration Guide – V2.0 – 30th July 2014 177
APPENDIX B Currency Code ISO 4217 Currency Code Num Locations using this currency Afghani AFN 971 Afghanistan Algerian dinar DZD 012 Algeria Argentine peso ARS 032 Argentina Armenian dram AMD 051 Armenia Aruban guilder AWG 533 Aruba Australian dollar 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 dollar BSD 044 Bahamas Bahraini dinar BHD 048 Bahrain Baht THB 764 Thailand Balboa PAB 590 Panama Bangladeshi taka BDT 050 Bangladesh Barbados dollar BBD 052 Barbados Belarusian ruble BYR 974 Belarus Belize dollar 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 dollar BND 096 Brunei, Singapore Bulgarian lev BGN 975 Bulgaria Burundian franc BIF 108 Burundi Canadian dollar CAD 124 Canada Cape Verde escudo CVE 132 Cape Verde Cayman Islands dollar 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 Denar MKD 807 Macedonia Djibouti franc DJF 262 Djibouti
Web Services Integration Guide – V2.0 – 30th July 2014 178
Dobra STD 678 São Tomé and Príncipe Dominican peso DOP 214 Dominican Republic East Caribbean dollar 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 birr ETB 230 Ethiopia Euro EUR 978 Austria, Belgium, Cyprus, Finland, France, Germany,
Greece, Ireland, Italy, Luxembourg, Malta, Netherlands, 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 dollar 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 dollar GYD 328 Guyana Haiti gourde HTG 332 Haiti Hong Kong dollar 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 dinar IQD 368 Iraq Israeli new sheqel ILS 376 Israel Jamaican dollar JMD 388 Jamaica Japanese yen JPY 392 Japan Jordanian dinar JOD 400 Jordan Kenyan shilling KES 404 Kenya Kina PGK 598 Papua New Guinea Kip LAK 418 Laos Kroon EEK 233 Estonia Kuwaiti dinar 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 dollar LRD 430 Liberia
Web Services Integration Guide – V2.0 – 30th July 2014 179
Libyan dinar 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 dollar NAD 516 Namibia Nepalese rupee NPR 524 Nepal Netherlands Antillean guilder ANG 532 Netherlands Antilles New Taiwan dollar TWD 901 Taiwan and other islands that are under the effective
control of the Republic of China (ROC) New Zealand dollar 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 dinar RSD 941 Serbia Seychelles rupee SCR 690 Seychelles Silver (one troy ounce) XAG 961
Web Services Integration Guide – V2.0 – 30th July 2014 180
Singapore dollar SGD 702 Singapore, Brunei Solomon Islands dollar 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 dollar SRD 968 Suriname Swedish krona/kronor 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 dollar TTD 780 Trinidad and Tobago Tugrik MNT 496 Mongolia Tunisian dinar 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 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 dollar 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 Vatu VUV 548 Vanuatu Venezuelan bolívar fuerte VEF 937 Venezuela Vietnamese đồng VND 704 Vietnam WIR euro (complementary currency)
CHE 947 Switzerland
WIR franc (complementary currency)
CHW 948 Switzerland
Yemeni rial YER 886 Yemen Zimbabwe dollar ZWL 932 Zimbabwe Złoty PLN 985 Poland
Web Services Integration Guide – V2.0 – 30th July 2014 181
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
Web Services Integration Guide – V2.0 – 30th July 2014 182
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 Dominica 212 DMA DM Dominican Republic 214 DOM DO Ecuador 218 ECU EC Egypt 818 EGY EG El Salvador 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 Gibraltar 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 of 364 IRN IR Iraq 368 IRQ IQ Ireland 372 IRL IE Isle of Man 833 IMN IM Israel 376 ISR IL
Web Services Integration Guide – V2.0 – 30th July 2014 183
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 of 408 PRK KP Korea, Republic of 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 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 of 807 MKD MK Madagascar 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 of 583 FSM FM Moldova, Republic of 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 Myanmar 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 Niger 562 NER NE Nigeria 566 NGA NG Niue 570 NIU NU Norfolk Island 574 NFK NF
Web Services Integration Guide – V2.0 – 30th July 2014 184
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 Qatar 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 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 of 834 TZA TZ Thailand 764 THA TH Timor-Leste 626 TLS TL Togo 768 TGO TG Tokelau 772 TKL TK
Web Services Integration Guide – V2.0 – 30th July 2014 185
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 Vanuatu 548 VUT VU Venezuela 862 VEN VE Viet Nam 704 VNM VN Virgin Islands, British 092 VGB VG Virgin 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
Web Services Integration Guide – V2.0 – 30th July 2014 186
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
Web Services Integration Guide – V2.0 – 30th July 2014 187
APPENDIX E Payer Authentication Decisions
The table below covers both Visa VbV Transactions and MasterCard SecureCode Transactions.
Case Number
MPI Authentication APACS Authorisation Streamline Settlement RAG Status Card Type VERes PARes CAVV/AVV ECI ECI CAVV/AVV Trans ID ATSD 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
Key to RAG Status:
Indicates a BAU (business as usual) transaction Indicates a system failure at some point Indicates attempted fraud or cardholder error
Web Services Integration Guide - V1.9 – 20th February 2014 188
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
Web Services Integration Guide – V2.0 – 30th July 2014 189
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 VERES PARES ATSD ECI Non supporting schemes i.e.- Creation, AMEX, JCB, Diners N/A N/A D08000 07
Please note: Cards such as Gift and trade cards do not require ATSD to be passed within the transaction.
Web Services Integration Guide – V2.0 – 30th July 2014 190
APPENDIX F
DCC Online Screen Examples As Visa and MasterCard have separate rules and regulations governing the provision of DCC in various payment environments, the following text will be displayed to the cardholder during DCC transaction processing.
DCC Payment Choice The following examples show the standard details provided to the cardholder at the currency choice stage:
Visa
MasterCard
Web Services Integration Guide – V2.0 – 30th July 2014 191
DCC Disclaimer
The following examples show the disclaimers provided to the cardholder for both Visa and MasterCard transactions:
Visa
MasterCard
© 2014 VeriFone. All rights reserved. VeriFone, the VeriFone logo, VX are either trademarks or registered trademarks of VeriFone. No part of the contents of this document may be reproduced or transmitted in any form without the written permission of VeriFone.
All content information is subject to change without notice.
Contact Details
VeriFone Services UK & Ireland 100 Eureka Park
Ashford Kent
TN25 4AZ
PAYware Ocius Merchant Helpdesk [email protected]
08444 828 222
VeriFone Technical Services [email protected]
08444 828 273
Sales Enquiries [email protected]
08444 828 200
Customer Services 08444 828 223
Website: www.verifone.co.uk