Elavon Payment Gateway- Remote Developers Guide Version: v1.1
Table of Contents 1 About This Guide. 3 1.1 Purpose 3 1.2 Audience 3 1.3 Prerequisites 3 1.4 Related Documents 3 2 Introduction 5 2.1 The Remote Method of integration 5 2.2 Remote Features List. 5 2.3 Sub-Accounts.. 6 3 Remote Authorisation. 7 3.1 Remote Authorisation Example. 7 3.2 Application Based Checking. 8 3.3 Remote Authorisation Integration.. 9 3.4 Remote Authorisation Request Message 10 3.5 Remote Authorisation Response Message 14 3.6 Digital Signatures for Remote. 17 3.7 Address Verification Service. 19 4 Steps Required To Go Live 21 5 Appendix A Sample Code. 22 5.1 Luhn check 22 6 Appendix B Codes. 23 6.1 Currency Codes. 23 6.2 Card Types 23 7 Response Codes. 24 7.1 Current List of Error Results and Messages.. 25 7.2 Country Codes 28 8 Appendix C - Data Validation Rules 33 9 Appendix D Elavon Payment Gateway Guides 34 Page 2
1 About This Guide This section outlines the purpose and aim of the guide, target audience, any source materials or terminology used, and a general document description. Please note that this document is regarded as confidential and is for customer use only. It has been supplied under the conditions of your payment-processing contract. 1.1 Purpose The purpose of this guide is to explain in detail what is involved in integrating the Remote services. 1.2 Audience The target audience for this guide is software and web developers. 1.3 Prerequisites In order to use this guide, you should have experience with and knowledge of the following concepts: For a Remote integration: Creation and remote submission of XML messages 1.4 Related Documents In addition to this guide, you can also refer to the following documents in the Elavon Payment Gateway documentation set for information about the Elavon Payment Gateway service: Elavon Payment Gateway Response Codes Elavon Payment Gateway XML Definitions Elavon Payment Gateway documentation uses the following conventions: Note: Tips or advice for the user. Caution: Important note. Potential financial impact. The following table outlines the main formatting conventions used in this guide: Convention Description Example Blue Italic or Plain Type Hyperlinks and crossreferences For more information see Table 1. Italics Names of other guides Elavon Payment Gateway XML Definitions Guide Page 3
Courier New Program code, screen messages, directory files, and file names <comments></comments> Courier New Placeholder for element names, field values, or user input card_holder_name BOLD CAPS Error and warning messages 101 / REFERRAL B Page 4
2 Introduction 2.1 The Remote Method of integration The remote method affords the merchant greater control of the transaction process but requires that they maintain their own secure server. Using this method, the customers card details will be taken by the merchant and passed to the Elavon Payment Gateway by XML messages. Your solution must integrate with our payment service at two levels firstly, you must submit correctly formed requests for authorisations and secondly, you must then accept the response that is returned by the Elavon Payment Gateway application. 2.2 Remote Features List Merchant needs a secure server or can integrate the service into a desktop application. Can be hosted anywhere, and on any platform as long as CGI is enabled. The card details are collected by the merchant and passed to Elavon Payment Gateway as XML messages. Elavon Payment Gateway responds with an XML message containing the results of the transaction in a matter of seconds. Elavon Payment Gateway can provide sample scripts to get you started. The merchant need not store card details, but they are available. The merchant controls full process, screen flow. Customer may never know that the Elavon Payment Gateway was involved in the process. In order to facilitate the use of multiple web-sites and bank accounts, merchants can set up a number of sub-accounts under their main Elavon Payment Gateway account. Each sub-account can use a different set of IP addresses and can channel the funds to a different bank account. The default sub-account will be 'internet' for all merchants. To have additional sub-accounts set up you will need to contact Elavon Payment Gateway and provide us with some details. Page 5
2.3 Sub-Accounts In order to create a sub account a merchant must provide: For remote: A sub-account name IP address of hosting server Bank merchant number Page 6
3 Remote Authorisation Merchants should use remote integration if they have a secure server or if their site is hosted internally (such as an intranet application for a call centre a secure server isn t necessary in that case as the card numbers will never travel outside of the internal network). Remote can also be used if you are developing an application in Visual Basic or Java etc. (i.e. not a web application but a desktop application). Elavon Payment Gateway can supply working sample code in Perl, Java, ASP, VB, PHP,.NET and server side JavaScript. 3.1 Remote Authorisation Example Remote is ideal for any application that needs real time authorisation of credit cards. Information is sent between the merchant and Elavon Payment Gateway in the form of XML messages. This service can be incorporated into any application that is capable of generating XML messages. Page 7
1. Once the full amount is known, the customer can be asked to enter their card details. These details are then sent to Elavon Payment Gateway as XML messages using a secure connection. A reply is then sent as an XML message back from Elavon Payment Gateway that contains the result of the transaction (approved/declined etc). 2. The merchants application receives the response XML and extracts the information. It then displays the appropriate messages for the customer. One of the main advantages of the remote version is that the merchant can control the entire shopping experience. 3.2 Application Based Checking It is highly advisable to build in pre-authorisation checking for all data fields. This will eliminate many problems early on and rapidly improve response times. If any field contains an error, the transaction Page 8
will fail. All mandatory fields must be included correctly and optional fields must contain valid data if included. Validation information can be found in Appendix C of this document. The following are some checks that should be put in place: Card expiry date should be checked. The date itself should be valid and formatted correctly. The card length should be 12, 13, 14, 15, 16, 18 or 19 digits depending on the card type, no alpha characters should be included. (12 num_digits 19 will do). The card number should pass the Luhn check (see Appendix A) to ensure that it is a valid card number. There should be at least two words in the cardholder's name (this is recommended but will not cause transactions to fail) and it must contain no unusual characters. If CVN checking is to be enforced the corresponding value for the presind field will need to be set. The possible values are listed in the XML definitions guide. The CVN itself will need to be sent in correctly. It should be 3 or 4 digits depending on the card type. Illegal characters cannot be present in any field. Each field should be checked to ensure that this is not the case as illegal characters cause the transaction to fail. The allowed characters for all fields are detailed in the XML definitions guide and in Appendix C - Data Validation Rules. 3.3 Remote Authorisation Integration Full details of the XML messages for each request type can be found in the Elavon Payment Gateway XML definitions guide, which is available from the online resource centre or by e-mailing support@elavonpaymentgateway.com. You will need to consult this guide in order to successfully complete a remote integration. Elavon Payment Gateway can supply sample code to aide with integration, however this is sample code only and will need to be modified to suit individual merchants needs. The sample code will provide guidance on how to carry out the steps required for a remote transaction to succeed. These steps are: Create the XML message for the request. Connect to Elavon Payment Gateway (https://remote.elavonpaymentgateway.com/remote). Page 9
Send the message. Wait for Elavon Payment Gateway to reply with XML. Parse the reply and provide access to the information. 3.4 Remote Authorisation Request Message Although the sample code available provides a simple interface to the system, more complex implementations will require some knowledge of how the system works. Again, the Elavon Payment Gateway XML definitions guide should be consulted for full details on the messages required. Below is a sample of an auth request followed by a line-by-line analysis. The auth request is the primary request used with Elavon Payment Gateway. <request timestamp="20120926112654" type="auth"> <merchantid>yourmerchantid</merchantid> <account>account to use</account> <orderid>order id</orderid> <amount currency="eur">2000</amount> <card> <number>490303400005718902</number> <expdate>0403</expdate> <chname>john Doe</chname> <type>mc</type> <issueno></issueno> <cvn> <number>453</number> <presind>1</presind> </cvn> </card> <autosettle flag="1" /> <comments> <comment id="1">a comment</comment> <comment id="2">another comment</comment> </comments> <tssinfo> <custnum>customer number</custnum> <prodid>product id</prodid> <varref>variable reference</varref> <custipaddress>1.2.3.4</custipaddress> <address type="billing"> <code>zip/postal code</code> <country>country</country> Page 10
</address> <address type="shipping"> <code>zip/postal code</code> <country>country</country> </address> </tssinfo> <sha1hash>4dc4f20acc.30314758a1bc</sha1hash> <md5hash>67dcc.787307</md5hash> </request> The following indicators are used to show whether or not an element is required or optional. Each field has certain constraints around length and format as per below (please note that means a space): Line per line description M/O/ Format Length Details <request timestamp="2012092611 2654" type="auth"> M 0-9 14 Top-level element. Must have timestamp and type attributes. If the timestamp is more than a day (86400 seconds) away from the server time then the request is rejected. <merchantid>merchant id used</merchantid> M a-z A-Z 0-9. 1-50 This is your Elavon Payment Gateway assigned merchant id <account>accoun t used</account> <orderid>order id</orderid> O a-z A-Z 0-9 M a-z A-Z 0-9 _ - 0-30 This is the Elavon Payment Gateway sub-account to use. If you omit this element then we will use your default account. 1-40 The unique order id of this transaction. Must be unique across all of your accounts. <amount currency="eur">2000</a mount> M a-z A-Z 0-9 3 2-11 The currency and amount of the transaction. Appendix B - Codes on page 35 of the Elavon Payment Gateway developer's guide specifies the currency codes. The amount should be in the smallest unit of the required currency (i.e. 2000 = 20, $20 or 20) <card> M There must be a card element in auth requests <number>490303400005 M 0-9 12-19 The card number. 718902</number> <expdate>0403</expdate > M 0-9 4 The card expiry date. The format is mmyy. <chname>john M a-z A-Z 0-9 - 1-100 The card holder's name. Page 11
Line per line description M/O/ Format Length Details Doe</chname> +"", ' +. _ - ; & \ / <type>mc</type> M See Details The card type. The legal values are: VISA, MC, LASER, SWITCH, AMEX, DINERS, UATP <issueno></issueno> M 0-9 0-3 The issue number of the card in the case of a Switch card. Only required if the card type is SWITCH <cvn> O The card verification details element. If you use this then the next two elements are required. <number>453</number> M 0-9 3-4 The Card Verification Number. This is the 3 digit number on the reverse of the card. (the CVC for VISA and the CVV2 for MasterCard) 3 digits on Visa and MC, 4 digits on Amex. <presind>1</presind> M See Details 1 This is the presence indicator. It can take 4 values: 1: cvn present 2: cvn illegible 3: cvn not on card 4: cvn not requested </cvn> M </card> M <autosettle flag="1" /> M See Details The auto-settle indicator. If "1" then the transaction is sent to the bank for settlement tonight. If set to "0" then the transaction sits in the Elavon Payment Gateway database until someone manually submits it for settlement. <recurring type="variable" sequence="first" /> C See Details If you are configured for recurring/continuous authority transactions, you must set these fields. type can be either fixed or variable depending on whether you will be changing the amounts or not. sequence must be Page 12
Line per line description M/O/ Format Length Details first for the first transaction for this card, subsequent for transactions after that, and last for the final transaction of the set. Only supported by some acquirers. <comments> O You can associate up to 2 comments with any transaction for your own purposes. <comment id="1">a comment</ comment> <comment id="2">a comment</ comment> O O a-z A-Z 0-9 ' ",+ "". _ - & \ / @!? % ( ) * : $ & # [ ] = a-z A-Z 0-9 ' ", + "". _ - & \ / @!? % ( ) * : $ & # [ ] = 0-255 Free-text comment 0-255 Free-text comment </comments> O <tssinfo> O As part of the Elavon Payment Gateway service we offer a RiskManager. This is a real time transaction screening and data checking system to assist the merchant with the identification of potentially highrisk transactions. <custnum>customer number</custnum> O a-z A-Z 0-9 - "" _., + @ 0-50 The number you assign to the customer. This can allow checking of previous transactions by this customer. <prodid>product id</prodid> O a-z A-Z 0-9 - ""_., + @ 0-50 The product code you assign to the product. <varref>variable reference</ varref> <custipaddress>1.2.3.4 </custipaddress> O a-z A-Z 0-9 - "" _., + @ O 0-9 IP Address in X.X.X.X format 0-50 Any reference you also would like to assign to the customer. This can allow checking, using RiskManager, of previous transactions by this customer. [1-3].[1- The IP address of the customer. 3].[1-3].[1-3] <address type="billing"> O The billing address of the customer. <code>zip postal O a-z A-Z 0-9 0-30 The ZIP Postal code of the billing Page 13
Line per line description M/O/ Format Length Details code</code> "",. - / address. This can be checked (in conjunction with the country) against a table of high-risk area codes. This field is used address verification with certain acquirers. <country>country</count ry> </address> <address type="shipping"> <code>zip postal code</code> <country>country</count ry> </address> </tssinfo> <sha1hash>7384 ae67...ac7d7d</ sha1hash> <md5hash>34e7....a77d</ md5hash> </response> O a-z A-Z 0-9 "",. - O O a-z A-Z 0-9 "",. - / O a-z A-Z 0-9 "",. - 0-30 The country of the billing address. This can be checked against a table of high-risk countries. The shipping address of the customer. 0-30 The ZIP Postal code of the shipping address. This can be checked (in conjunction with the country) against a table of high-risk area codes. 0-30 The country of the shipping address. This can be checked against a table of highrisk countries. M a-f 0-9 40 The SHA-1 hash of certain elements of the request. The details of this are to be found in the Elavon Payment Gateway developer's guide. Either this or the MD5 may be used. M a-f 0-9 32 The MD5 hash of certain elements of the request. The details of this are to be found in the Elavon Payment Gateway developer's guide. 3.5 Remote Authorisation Response Message The full version of the response is shown below, followed by the short version and a linebyline description. Response Format - Long Version Page 14
<response timestamp="20120926112654"> <merchantid>yourmerchantid</merchantid> <account>account to use</account> <orderid>order id from request</orderid> <authcode>authcode received</authcode> <result>00</result> <message>message returned from system</message> <pasref> Elavon Payment Gateway reference</pasref> <cvnresult>m</cvnresult> <batchid>batch id for this transaction (if any)</batchid> <cardissuer> <bank>issuing Bank Name</bank> <country>issuing Bank Country</country> <countrycode>issuing Bank Country Code</countrycode> <region>issuing Bank Region</region> </cardissuer> <tss> <result>89</result> <check id="1000">9</check> <check id="1001">9</check> </tss> <sha1hash>7384ae67...ac7d7d</sha1hash> <md5hash>34e7...a77d</md5hash> </response> Response Format - Short Version <response timestamp="20120926112654"> <result>508</result> <message>message returned from system</message> </response> The following indicators are used to show whether or not an element is required or optional. Each field has certain constraints around length and format as per below (please note that means a space): Line per line description M/O/ Format Length Details <response timestamp="2012092611 2612"> M 0-9 14 Top-level element. Must have timestamp and type attributes. If the timestamp is more than a day (86400 seconds) away from the server time then the request is rejected. Page 15
Line per line description M/O/ Format Length Details <merchantid>merchant id used</merchantid> M a-z A-Z 0-9. 1-50 This is your Elavon Payment Gateway assigned merchant id <account>account used</account> O a-z A-Z 0-9 0-30 This is the Elavon Payment Gateway sub-account to use. If you omit this element then we will use your default account. <orderid>orderid</orderi d> M a-z A-Z 0-9 _ - 1-40 The unique order id of this transaction. Must be unique across all of your accounts. <authcode>authcode received</authcode> M a-z A-Z 0-9 0-10 If successful an authcode is returned from the bank. Used when referencing this transaction in refund and void requests. <result>00</result> M 0-9 0-3 The result codes returned by the Elavon Payment Gateway system. <message>message returned from system</message> <pasref> Elavon Payment Gateway reference</pasref> <cvnresult>m</ cvnresult> <batchid>batch id</batchid> M a-z A-Z 0-9 ' ", + "". _ - & \ / @!? % ( ) * : $ & # [ ] = 0-100 The text of the response. Contains the authcode if successful or the error message if not. M a-z A-Z 0-9 0-50 The Elavon Payment Gateway reference for the transaction. Used when referencing this transaction in refund and void requests. M See Details 1 The result of the Card Verification check: M: CVV Matched N: CVV Not Matched I: CVV Not checked due to circumstances U: CVV Not checked - issuer not certified P: CVV Not Processed M 0-9 0-20 The batch id of the transaction. Returned in the case of auth and refund requests. This can be used to assist with the reconciliation of your batches. <cardissuer> M The Details of the cardholder's bank (if available) <bank>issuing Bank Name</bank> M a-z A-Z 0-9 _ 0-30 The Bank Name (e.g. First Data Bank) <country>issuing Bank Country</country> M a-z A-Z 0-9 "",. - 0-30 The Bank Country in English (e.g. UNITED STATES) <countrycode>iss uing Bank Co Code</ M a-z A-Z 2 The country code of the issuing bank (e.g. US) countrycode> <region>issuing M a-a A-Z 0-9 / 0-20 The region the card was issued Page 16
Line per line description M/O/ Format Length Details Bank Region</ region> (e.g. US) Can be MEA (Middle East/Asia), LAT (Latin America), US (United States), EUR (Europe), CAN (Canada), A/P (Asia/Pacific) </cardissuer> M <tss> O The results of RiskManager <result>67</result> M 0-9 0-3 The weighted total score of RiskManager. You may adjust the weights in the Reporting application. <check id="xxxx">9</ check> <sha1hash>7384ae67...a c7d7d</sha1hash> <md5hash>34e7...a77d< /md5hash> </response> M 0-9 0-9 3.6 Digital Signatures for Remote 4 1 The result of the RiskManager check number xxxx. You can choose which checks to return using the Reporting application. M a-f 0-9 40 The SHA-1 hash of certain elements of the response. The details of this are to be found in the Elavon Payment Gateway developer's guide M a-f 0-9 32 The MD5 hash of certain elements of the response. The details of this are to be found in the Elavon Payment Gateway developer's guide. To ensure authentication (that the request comes from you) we require that you send us a hash of certain elements (specifically the timestamp, merchant id, order id, amount, currency and card number) using a shared secret. This can be a MD5 hash or preferably a SHA-1 hash. If required we can also provide code for this. MD5 and SHA-1 algorithms are secure hash functions. They take a string as input, and produce a fixed size number - 128 bits for MD5; 160 bits for SHA-1. This number is a hash of the input, and a small change in the input results in a substantial change in the output. The functions are thought to be secure in the sense that it requires an enormous amount of computing power and time to find a string that hashes to the same value. In others words, there's no way to decrypt a secure hash. Given the larger key size, we prefer that you use a SHA-1 hash, but we have retained the MD5 for compatibility with older systems. Here s a fragment of a sample XML message: Page 17
<request timestamp="20120926112612" type="auth"> <merchantid> thestore </merchantid> <account> theaccount </account> <orderid> ORD453-11 </orderid> <amount currency="eur"> 29900 </amount> <card> <number> 5105105105105100 </number> <expdate> 0302 </expdate> <chname> John Smith </chname> <type> VISA </type> </card> To construct the hash follow this procedure: Form a string by concatenating the above fields with a period (. ) (20120926112654.thestore.ORD453-11.29900.EUR.5105105105105100) Get the hash of this string (SHA-1 shown below). (f7fa584d2f8d642c1a17e9ead6061e8beeffe308) Create a new string by concatenating this string and your shared secret using a period. (f7fa584d2f8d642c1a17e9ead6061e8beeffe308.mysecret ) Get the hash of this value. This is the value that you send to Elavon Payment Gateway. (1537570e5f1d2aba5cad67ff5108ad3ff1d56c32) <sha1hash> 1537570e5f1d2aba5cad67ff5108ad3ff1d56c32 </sha1hash> When Elavon Payment Gateway receive the request, we perform the same procedure on the six pieces of information and your shared secret (which we have stored in our database) If the resulting hash is the same as the one that you sent us then the data could only have been sent by someone that had your shared secret. Thus it is very important to keep this shared secret protected. We will send you a hash of the response elements in the same way so that you can confirm that the response came from Elavon Payment Gateway. This will be a hash of the TIMESTAMP, MERCHANT_ID, ORDER_ID, RESULT, MESSAGE, PASREF and AUTHCODE. This will be combined with your shared secret in the same way as the request hash. Page 18
If you sent us an MD5 hash you will receive an MD5 hash in the response and similarly for a SHA-1 hash). The response hash is constructed as follows: Form a string by concatenating the above fields with a period (. ) ( 20120926112654.thestore.ORD453-11.00.Successful.3737468273643.79347) Get the hash of this string (SHA-1 shown below). (a111135ea464bcd343c0f23db395fa1cf12a6837) Create a new string by concatenating this string and your shared secret using a period. (a111135ea464bcd343c0f23db395fa1cf12a6837.mysecret) Get the hash of this value. This is the value that you send to Elavon Payment Gateway. (368df010076481d47a21e777871012b62b976339). 3.7 Address Verification Service The Address Verification Service (AVS) verifies the cardholders address by checking the information provided by at the time of sale against the issuing bank's records. Note: This service only works for UK cardholders as it uses the street address and postcodes of the cardholders. The Elavon Payment Gateway service supports AVS where it is supported by the merchants acquiring bank and the cardholders issuing bank. If a transaction fails an AVS check it will not automatically be declined by your bank. It is an advisory service and requires that the details of non -matched be checked by the merchant. AVS data must be passed in the billing code field. This data should be formatted as follows: <digits from postcode> <digits from address> For example, if the billing address is: 382, The Road The Town WB1 A42 Page 19
UK The corresponding AVS data will be: <address type='billing> <code>142 382</code> </addresss> The possible responses that can be returned for the Address Verification Service are as follows: M (Matched). N (Not Matched). I (Problem with check). U (Unable to check (not certified etc)). P (Partial Match). These will be returned in the following XML tags in the response: <avspostcoderesponse></avspostcoderesponse> <avsaddressresponse></avsaddressresponse> Page 20
4 Steps Required To Go Live All accounts remain in test mode until it is specifically requested to switch the account live. This request must come from the billing or commercial contact for the account. Before live cards can be processed you will also need to provide Elavon Payment Gateway with a bank merchant number by email to support@elavonpaymentgateway.com. This number references an Internet Merchant Service Agreement (MSA), which you must set up with your acquiring bank. Once you have requested the system to go live and have provided your merchant number, please allow 24 hours for the account to be fully enabled. When the account has been fully set live the merchant will be advised of this by Elavon Payment Gateway support. At this point the merchant should attempt a number of live transactions to ensure that the integration has been completed successfully. The main steps involved in setting an account live are summarised below: 1. Secure merchant service agreement with acquiring bank. 2. Provide merchant numbers to the Elavon Payment Gateway via email. 3. Integrate website/application with Elavon Payment Gateway service. 4. Conduct testing using approved test card numbers to confirm successful integration. 5. Contact Elavon Payment Gateway and request account be set live. 6. Receive confirmation that account is live from Elavon Payment Gateway support. 7. Process live transactions. If further testing is required after an account has been set live it is still possible to send transactions to the test environment. This can be done by appending test to the name of the sub-account specified in the ACCOUNT field. For example, where the sub-account is called internet the test transaction would use internettest. Page 21
5 Appendix A Sample Code 5.1 Luhn check Below is code in JavaScript that carries out Luhn checking on all card numbers. Code in other languages is widely available on the internet. var number = "4444333322221111"; var i, sum, weight; sum=0; for (i = 0; i < number.length - 1; i++) { weight = number.substr(number.length - (i + 2), 1) * (2 - (i % 2)); sum += ((weight < 10)? weight : (weight - 9)); } if (parseint(number.substr(number.length-1)) == ((10 - sum % 10) % 10)) { return true; } else { alert("card Number Fails LUHN Test"); return false; } In brief, the Luhn check is used to validate numbers such as credit cards, account numbers, and social security numbers. It works like this: 1. Double the value of every second digit beginning with the second-last right-hand digit. 2. Add the individual digits comprising the products obtained in step 1 to each of the other digits in the original number. 3. Subtract the total obtained in step 2 from the next higher number ending in 0. 4. This number should be the same as the last digit (the check digit). If the total obtained in step 2 is a number ending in zero (30, 40 etc.), the check digit is 0. For example: credit card number 3648455485235855 3 6 4 8 4 5 5 4 8 5 2 3 5 8 5 5 x2 x2 x2 x2 x2 x2 x2 x2 6 6 8 8 8 5 10 4 16 5 4 3 10 8 10 6+6+8+8+8+5+1+0+4+1+6+5+4+3+1+0+8+1+0 = 75 80 75 = 5 (correct) Page 22
6 Appendix B Codes 6.1 Currency Codes EUR Euro GBP Pound Sterling USD US Dollar SEK Swedish Krona CHF Swiss Franc HKD Hong Kong Dollar JPY Japanese Yen (Further codes available on request.) 6.2 Card Types VISA MC SWITCH AMEX LASER DINERS Visa/Delta Mastercard Switch/Solo American Express Laser Diners Page 23
7 Response Codes The Table below details the current set of result codes returned by the Elavon Payment Gateway system. Additions and changes to the specific text of these messages can occur without notice! The best practise is to treat the codes in the following manner. Code Description 00 Successful the transaction has processed and you may proceed with the sale. 1xx A failed transaction. You can treat any 1xx code as a failed transaction and inform your customer that they should either try again or try another payment method. If you wish you may provide alternate flows based on the specific codes as follows: 101 Declined by Bank generally insufficient funds or incorrect expiry date. 102 Referral by Bank (treat as decline in automated system such as internet) 103 Card reported lost or stolen 107 Your fraud checks blocked the transaction. 1xx Other reason, rare. Treat as a decline like 101. 2xx 3xx 5xx Error with bank systems generally you can tell the customer to try again later. The resolution time depends on the issue. Error with Elavon Payment Gateway systems generally you can tell the customer to try again later. The resolution time depends on the issue. Incorrect XML message formation or content. These are either development errors, configuration errors or customer errors. There is a large list below, but in general: 508 Development issue check the message and correct your integration. 509 Customer issue check the message and ask the customer to confirm their payment details and try again. 5xx Configuration issue check the message. You may need to contact Elavon Payment Gateway support to fix these issues. 666 Client deactivated your Elavon Payment Gateway account has been suspended. Contact Elavon Payment Gateway support for further information. Page 24
7.1 Current List of Error Results and Messages RESULT MESSAGE 00 AUTH CODE: nnnnnn 101 CANCELLED CARD 101 CARD EXPIRED 101 DECLINED 101 INVALID AMOUNT 101 INVALID CARD NO. 101 INVALID CURRENCY 101 INVALID EXP DATE 101 INVALID MERCHANT 101 INVALID TRANS 101 NOT AUTHORISED 101 RETAILER UNKNOWN 101 UNABLE TO AUTH 102 CALL AMEX 102 CALL AUTH CENTRE 102 REFERRAL 102 REFERRAL B 103 REFERRAL A 103 PICK UP CARD 103 RETAIN CARD 104 UNABLE TO AUTH 106 Auth Failed - Contact Auth Centre (Generally Switch Card issue number is incorrect) 107 Fails RiskManager Fraud Checks 108 Using test system. Please use pre-approved test cards ONLY 109 Comms Error scheduled bank maintenance 200 Unspecified bank error 202 Network error: cannot connect to EPoS 205 Comms Error bank connection error. 301 Cannot connect to Database 302 Configuration error with your bank details (acquiring bank) - please contact Elavon Payment Gateway payments 303 There is no default merchant account set. Please contact Elavon Payment Gateway payments if you continue to experience this problem. 303 Error in configuration - merchant has more than one config for this currency/card combination 303 Somehow more than one transaction matches these parameters. 304 Can't find transaction details in database 305 Elavon Payment Gateway are currently updating the system. We apologise for the inconvenience. 501 This transaction has already been processed. 502 Compulsory field not present - cannot continue. Please check the Developer Documentation for compulsory fields 502 Type [type] not implemented. Please check the Developer Documentation for allowed Page 25
RESULT MESSAGE types 503 Request type not recognised 503 Request type [type] not allowed for this merchant 504 There is no such merchant id. Please contact Elavon Payment Gateway payments if you continue to experience this problem. 505 md5hash incorrect - check your code and the Developers Documentation 505 sha1hash incorrect - check your code and the Developers Documentation 505 You are not allowed to access this service from there! 505 The refund password you entered was incorrect. 506 There is no such merchant account. Please contact Elavon Payment Gateway payments if you continue to experience this problem. 506 No xml in request 506 Too much data 506 Bad xml formation 507 currency/card combination not allowed 508 Invalid data in merchantid field 508 Invalid data in account field 508 Invalid characters in order id - please use only A-Z a-z 0-9 _ - 508 Please only numbers in amount - see developers guide 508 Leading zeros or or other error in amount field 508 Zero, negative or insufficient amount specified 508 Invalid data in currency field 508 Invalid data in timestamp field 508 Invalid timestamp 508 Transaction out of date 508 Invalid hash supplied 508 Invalid Auto Settle flag 508 Invalid Auto Settle flag 508 Invalid Data in Billing code field 508 Invalid Data in Billing country field 508 Invalid Data in Shipping code field 508 Invalid Data in Shipping country field 508 invalid characters in cust num - please use only A-Z a-z 0-9 _ -., + @ 508 invalid characters in variable reference - please use only A-Z a-z 0-9 _ -., + @ 508 invalid characters in product id - please use only A-Z a-z 0-9 _ -., + @ 508 Invalid data in card type field 508 Can't find original transaction in database. 508 The original transaction failed! You can't rebate a failed transaction. 508 You may only rebate up to 115% of the original amount. 508 Can't find original transaction in database. 508 This transaction was successful the first time!. 508 Can't find original transaction in database. 508 Can't settle a settled transaction. 508 Can't settle for more than 115% of that which you authorised. 509 NonNumeric in Credit card number. 509 Invalid credit card length Page 26
RESULT MESSAGE 509 NonNumeric in issue number. 509 Invalid issue number length 509 Only Switch cards have issue numbers 509 Card number fails Luhn Check 509 Invalid expiry date 509 Card Expiry date in past 509 Expiry month invalid 509 That Card Number does not correspond to the card type you selected 509 An ECI value must be included for MPI enabled accounts. 509 Length of CVV data is incorrect 510 That amount is greater than the max allowed 511 Unable to connect to the merchant response url 512 This transaction has already been rebated and cannot be rebated again. 512 Original transaction not found 512 You may only refund the original cardnumber. 512 You can't refund a delayed transaction that has not been sent for settlement. (You are refunding money to a customer that has not and never will be charged!) 512 Original account was not [account] 512 Original transaction currency was not [currency] 512 You may only refund 115% of the value of the original transaction. 512 This transaction has already been refunded through the epage remote interface and cannot be refunded again. 513 Can't void a settled transaction. 514 Original Transaction Failed! If you just want to give money to the customer use the refund terminal in emerchant. 514 Original Transaction was Successful! 514 Can't settle a settled transaction. 514 Can't settle a transaction already settling. 666 This account has been deactivated. Please contact Elavon Payment Gateway for further details. Page 27
7.2 Country Codes Certain RiskManager checks require you to submit the country as data to be checked against. To ensure that the country names we use are the same, Elavon Payment Gateway use the following ISO 3166-1 country codes. The common use of these is in a dropdown list from which the customer can select their billing and shipping countries. code country name code country name AD ANDORRA AE UNITED ARAB EMIRATES AF AFGHANISTAN AG ANTIGUA AND BARBUDA AI ANGUILLA AL ALBANIA AM ARMENIA AN NETHERLANDS ANTILLES AO ANGOLA AQ ANTARCTICA AR ARGENTINA AS AMERICAN SAMOA AT AUSTRIA AU AUSTRALIA AW ARUBA AZ AZERBAIJAN BA BOSNIA AND HERZEGOVINA BB BARBADOS BD BANGLADESH BE BELGIUM BF BURKINA FASO BG BULGARIA BH BAHRAIN BI BURUNDI BJ BENIN BM BERMUDA BN BRUNEI DARUSSALAM BO BOLIVIA BR BRAZIL BS BAHAMAS BT BHUTAN BV BOUVET ISLAND BW BOTSWANA BY BELARUS BZ BELIZE CA CANADA CC COCOS (KEELING) ISLANDS CD CF CENTRAL AFRICAN REPUBLIC CG CONGO CH SWITZERLAND CI COTE D'IVOIRE CONGO, THE DEMOCRATIC REPUBLIC OF THE Page 28
CK COOK ISLANDS CL CHILE CM CAMEROON CN CHINA CO COLOMBIA CR COSTA RICA CU CUBA CV CAPE VERDE CX CHRISTMAS ISLAND CY CYPRUS CZ CZECH REPUBLIC DE GERMANY DJ DJIBOUTI DK DENMARK DM DOMINICA DO DOMINICAN REPUBLIC DZ ALGERIA EC ECUADOR EE ESTONIA EG EGYPT EH WESTERN SAHARA ER ERITREA ES SPAIN ET ETHIOPIA FI FINLAND FJ FIJI FK FALKLAND ISLANDS (MALVINAS) FM MICRONESIA, FEDERATED STATES OF FO FAROE ISLANDS FR FRANCE GA GABON GB UNITED KINGDOM GD GRENADA GE GEORGIA GF FRENCH GUIANA GH GHANA GI GIBRALTAR GL GREENLAND GM GAMBIA GN GUINEA GP GUADELOUPE GQ EQUATORIAL GUINEA GR GREECE GS GT GUATEMALA GU GUAM GW GUINEA-BISSAU GY GUYANA HK HONG KONG HM HN HONDURAS HR CROATIA HT HAITI HU HUNGARY ID INDONESIA IE IRELAND SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS HEARD ISLAND AND MCDONALD ISLANDS Page 29
IL ISRAEL IN INDIA IO BRITISH INDIAN OCEAN TERRITORY IQ IRAQ IR IRAN, ISLAMIC REPUBLIC OF IS ICELAND IT ITALY JM JAMAICA JO JORDAN JP JAPAN KE KENYA KG KYRGYZSTAN KH CAMBODIA KI KIRIBATI KM COMOROS KN SAINT KITTS AND NEVIS KP KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF KR KOREA, REPUBLIC OF KW KUWAIT KY CAYMAN ISLANDS KZ KAZAKSTAN LA LAO PEOPLE'S DEMOCRATIC REPUBLIC LB LEBANON LC SAINT LUCIA LI LIECHTENSTEIN LK SRI LANKA LR LIBERIA LS LESOTHO LT LITHUANIA LU LUXEMBOURG LV LATVIA LY LIBYAN ARAB JAMAHIRIYA MA MOROCCO MC MONACO MD MOLDOVA, REPUBLIC OF MG MADAGASCAR MH MARSHALL ISLANDS MK ML MALI MM MYANMAR MN MONGOLIA MO MACAU MP NORTHERN MARIANA ISLANDS MQ MARTINIQUE MR MAURITANIA MS MONTSERRAT MT MALTA MU MAURITIUS MV MALDIVES MW MALAWI MX MEXICO MY MALAYSIA MZ MOZAMBIQUE NA NAMIBIA NC NEW CALEDONIA NE NIGER MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF Page 30
NF NORFOLK ISLAND NG NIGERIA NI NICARAGUA NL NETHERLANDS NO NORWAY NP NEPAL NR NAURU NU NIUE NZ NEW ZEALAND OM OMAN PA PANAMA PE PERU PF FRENCH POLYNESIA PG PAPUA NEW GUINEA PH PHILIPPINES PK PAKISTAN PL POLAND PM SAINT PIERRE AND MIQUELON PN PITCAIRN PR PUERTO RICO PS PALESTINIAN TERRITORY, OCCUPIED PT PORTUGAL PW PALAU PY PARAGUAY QA QATAR RE REUNION RO ROMANIA RU RUSSIAN FEDERATION RW RWANDA SA SAUDI ARABIA SB SOLOMON ISLANDS SC SEYCHELLES SD SUDAN SE SWEDEN SG SINGAPORE SH SAINT HELENA SI SLOVENIA SJ SVALBARD AND JAN MAYEN SK SLOVAKIA SL SIERRA LEONE SM SAN MARINO SN SENEGAL SO SOMALIA SR SURINAME ST SAO TOME AND PRINCIPE SV EL SALVADOR SY SYRIAN ARAB REPUBLIC SZ SWAZILAND TC TURKS AND CAICOS ISLANDS TD CHAD TF FRENCH SOUTHERN TERRITORIES TG TOGO TH THAILAND TJ TAJIKISTAN TK TOKELAU TM TURKMENISTAN Page 31
TN TUNISIA TO TONGA TP EAST TIMOR TR TURKEY TT TRINIDAD AND TOBAGO TV TUVALU TW TAIWAN, PROVINCE OF CHINA TZ TANZANIA, UNITED REPUBLIC OF UA UKRAINE UG UGANDA UM UNITED STATES MINOR OUTLYING ISLANDS US UNITED STATES UY URUGUAY UZ UZBEKISTAN VA HOLY SEE (VATICAN CITY STATE) VC SAINT VINCENT AND THE GRENADINES VE VENEZUELA VG VIRGIN ISLANDS, BRITISH VI VIRGIN ISLANDS, U.S. VN VIET NAM VU VANUATU WF WALLIS AND FUTUNA WS SAMOA YE YEMEN YT MAYOTTE YU YUGOSLAVIA ZA SOUTH AFRICA ZM ZAMBIA ZW ZIMBABWE Page 32
8 Appendix C - Data Validation Rules Field Valid Data Comments Merchant ID a-z A-Z 0-9 Elavon Payment Gateway assigned. Account a-z A-Z 0-9 Elavon Payment Gateway assigned. Order ID a-z A-Z 0-9 - _ Max 50 characters. Amount 0-9 No decimal point. Currency A-Z a-z See Currency Codes. Timestamp 0-9 Must be a legal timestamp, 14 digits long in the form yyyymmddhhmmss and within 24 hours of the current time. SHA1Hash/MD5Hash a-f 0-9 40 or 32 digits. Autosettle Flag 0 or 1 Billing Code a-z A-Z 0-9 Billing Country a-z A-Z 0-9 Should be taken from the Error! Reference source not found. if you are using the RiskManager checks. Shipping Code a-z A-Z 0-9 Shipping Country a-z A-Z 0-9 Should be taken from 7.2 Country Codes if you are using the RiskManager checks. Customer Number a-z A-Z 0-9 - _ Max 50 characters Variable Reference a-z A-Z 0-9 - _ Max 50 characters Product ID a-z A-Z 0-9 - _ Max 50 characters Comments a-z A-Z 0-9 - _ Max 255 characters Card type a-z A-Z See Card Types. Cardnumber 0-9 Must pass Luhn check, and be properly matched with the card type. Cardholder name See note. Max 50 characters. Most 506 errors (malformed XML error) that you will receive will be because the cardholder has funny characters in their name. These characters (e.g. ß, or ä) are encoded using the ISO-8859-1 standard and not UTF-8 (which is the default for the parser used by Elavon Payment Gateway Therefore you should ensure that the encoding set in the top line of the XML you send to Elavon Payment Gateway is correct. In most cases ISO-8859-1 will suffice but as more and more international customers use your site, Unicode (or UTF-8) encoding may be encountered (which allows for many more characters such as Japanese or Hebrew words). Further information will follow as the UTF-8 standard is finalised. Issue Number 0-9 0, 1, or 2 digits only SWITCH cards Expiry Date 0-9 4 digits, mmyy, valid (i.e. 4598 is illegal) Page 33
9 Appendix D Elavon Payment Gateway Guides Title Target Description Elavon Payment Gateway XML Definitions Guide Developers This guide provides details of the XML messages required for each type of transaction. This will be required for any Remote integration. 3D Secure Remote Guide Developers For remote implementations of 3D Secure there will be some development work required by the merchant. This guide provides the technical details needed by developers. SecureDataVault Payments Guide All Elavon Payment Gateway also provide a recurring payments solution. This allows merchants to raise payments by storing card details on our secure servers and then passing a reference in the place of the card number. This guide provides both an overview and the details required to integrate the service. Multi-Currency Guide Developers Multi-Currency is the Dynamic Currency Conversion service provided by Elavon Payment Gateway. DCC allows merchants to provide customers with the option of making purchases in their native currency, with exchange rates retrieved in real time. Page 34
Elavon Financial Services Limited is registered in Ireland Number 418442. Registered Office: Block E, 1st Floor, Cherrywood Business Park, Loughlinstown, Co. Dublin, Ireland. Elavon Financial Services Limited is regulated by the Central Bank of Ireland. United Kingdom branch registered in England and Wales under the number BR009373. Elavon Merchant Services is a trading name of Elavon Financial Services Limited. Directors: Kurt Adams (USA), John Collins, Craig Gifford (USA), Bryan Calder (USA), Pamela Joseph (USA), Declan Lynch, John McNally, Malcolm Towlson Page 35