Elavon Payment Gateway- edcc Developer s Guide

Transcription

1 Elavon Payment Gateway- edcc Developer s Guide Version: v1.1

2 Table of Contents 1 About This Guide Purpose Audience Prerequisites Related Documents Conventions 4 2 Introduction 5 3 Service Description and Process 6 4 Merchant Integration Support 7 5 edcc Implementation Merchant Rebate Process Auths and DCCRate 10 6 Appendix A - Elavon Supported Currencies 20 7 Appendix B -Regulatory Requirements Regulatory Requirements 22 2

3 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 provide all of the details on the XML specification for currency conversion rate requests to the Elavon edcc service. 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: Knowledge of how to create formatted files as outlined in the Elavon Auth Developers guide 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 Auth service: Elavon Auth Developers guide 3D Secure Developers guide Elavon Auth XML Definitions guide 3

4 1.5 Conventions 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 Auth Developer s Guide 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 4

5 2 Introduction This document details the XML specification for currency conversion rate requests to the Elavon edcc service. It should be used in conjunction to the standard Developers Guide for the Payments Service Provider (PSP) that you are using for credit card authorisations - i.e. Elavon Payment Gateway Integration. Elavon deliver a point of sale system which allows for the processing of multi currency credit card transactions with the amounts specified in the customer's home currency. The currency conversion features are multi channel and can be easily integrated to an internet or call centre environment. In this document, examples of credit card authorisation methods are given for both Elavon GateConex2 and Elavon Payment Gateway Integration. If you have any queries please contact us and we will be happy to discuss the detail of these options. 5

6 3 Service Description and Process The principle of edcc is to offer the cardholder the option to select the currency of the transaction prior to the actual authorisation. This can be done in both telesales and internet (online) transactions. In order to facilitate such a process there must be a rate lookup completed prior to authorisation. The rate lookup and the authorisation are two separate requests. This approach is in accordance with the Visa and MasterCard rules, and allows the card holder to accept or deny the exchange rate they are offered. The hosted rate lookup service is managed by Elavon Payment Gateway on behalf of Elavon. In order to use the edcc service, the merchant may or may not be using Elavon Payment Gateway for authorisation. In other words any Elavon merchant may use the edcc service. For both internet and telesales merchants there will be a rate lookup request, followed by an authorisation and optional settlement as follows: A merchant will submit a rate lookup to the system, which will validate that the request is from a genuine source and complete some data validation - e.g. correct LUHN check, service is active for this account/merchant etc. If the card is not supported by edcc (e.g. the currency of the card is unsupported or the card is in the same currency as the merchant's base currency) a response is created and returned to the merchant (Code 105), who can then authorise as normal in the base currency. If the card is supported by edcc then the current exchange rate is returned to the merchant, who can now display a choice to the cardholder. The merchant now submits an authorisation request and this includes the currency conversion information. Settlement is completed as normal with the Multi-Currency information included. In order to implement the above, merchants will need to modify their systems to submit a rate lookup request to the Elavon edcc service prior to authorisation. 6

7 4 Merchant Integration Support If you are interested in using the Elavon edcc service then you should contact your local Elavon sales office. Once the details have been agreed, they will advise Elavon Payment Gateway, who manage the edcc rate lookup service on their behalf. Elavon Payment Gateway will provide all merchant integration support, which includes: This Technical Integration Guide. Test access - we will maintain a test service for merchants as they complete their integration. Test card numbers programmed to return specific error and valid responses. Sample code in Perl, Java, ASP, PHP and any others required and within our capability. Shared secret for authenticating requests to the Elavon Payment Gateway servers. Access to our integration support personnel for telephone advice. On an ongoing basis the merchants may contact Elavon Payment Gateway for technical support. This is available via and phone at the number shown in Product Support Information. Any queries in relation to commissions and financial rebates should be directed to Elavon. 7

8 5 edcc Implementation The principle of edcc is to offer the cardholder the option to select the currency and fix the foreign amount of the transaction, as it will appear on her statement prior to the actual transaction. For example, say you are selling an item for 100. Without an edcc-enabled solution, a customer from the USA will be paying in Euro, and will see something similar to this on their statement following the sale: 12/03/2004 TOYS'R'US FIFTH AVENUE NY$ /03/2004 ANYMERCHANT DUBLIN IE USD/EUR$ /03/2004 MACY'S 134TH STREET NY$19.45 As you can see the customer will not know what amount they are going to be charged in dollars until they get their statement, and it is the bank that issued their credit card that controls the foreign exchange. With an edcc-enabled solution, the customer again shops with you. After they enter their card number they are offered the choice - either they can continue with the Euro transaction as above, or they can select to continue in their own currency at the following exchange rate: We notice that you have a US Dollar card. For your convenience you can opt to have this transaction charged as $ (transaction amount). Exchange rate: 1.00 = $ (I accept that I have been offered a choice of currencies for payment. I accept the conversion rate and final amount and that the final selected transaction currency is USD) Yes - charge me in US Dollars. No - I prefer to be charged in Euro. Note: The regulatory text is specific to each of Visa and MasterCard - the Visa version is shown above. For more information see Regulatory Requirements. 8

9 If the customer chooses the Dollar amount, then you will receive 100 as expected, and they will have the following on their statement: 12/03/2004 TOYS'R'US FIFTH AVENUE NY$ /03/2004 ANYMERCHANT DUBLIN IE USD/EUR$ /03/2004 MACY'S 134TH STREET NY$19.45 As you can see, the amount is exactly the same as the amount they were told they would be charged at the time of purchase (this can help to reduce disputes). Also, now Elavon (rather than the issuing bank) controls the foreign exchange, and will offer the merchant a rebate on each transaction that is successfully processed as an edcc transaction. 5.1 Merchant Rebate Process After the cardholder enters their card details and pressing the "Buy Now" button, a request is sent to Elavon (via Elavon Payment Gateway) called a dcc rate request. Lookup tables are referenced to determine if Elavon supports edcc for this card in this transaction. Elavon reply to the dcc rate request with a response that includes whether the transaction is eligible for edcc, and if so, the currency, rate and amount to offer the customer. If the card is not eligible for edcc (either because it is an unusual currency not supported by Elavon, or simply because it is the same currency as the transaction) then your application/website should go straight on and perform an authorisation as normal. If the card is supported, then you should offer the cardholder the choice as explained previously. Depending on the choice, send an authorisation request with the correct edcc information - either the foreign information or the original currency information (which is just a rate of 1 and the amount is identical to the sale price). The response from your PSP will be as normal. In addition to the Multi-Currency information returned in the response to the dccrate request, Elavon may return the expiry timestamp of the rate. The authorisation request must be received 9

10 before this expiry date, so as to ensure that the rate is still valid. Pre-authorisation is not supported currently, as the rate may have changed by the time the capture request is processed. 5.2 Auths and DCCRate Auths and dccrate requests should be sent via HTTPS to: A sample dccrate request looks like this: <request timestamp=" " type="dccrate"> <merchantid>yourmerchantid</merchantid> <account></account> <orderid> </orderid> <amount currency="eur">19000</amount> <card> <number> </number> <expdate>0405</expdate> <chname>peter Johnson</chname> <type>visa</type> </card> <autosettle flag="1"/> <dccinfo> <ccp>euroconex</ccp> <type>1</type></dccinfo> <sha1hash>764b429ea29e803c528a5ccb85faff40f4e41cad</sha1hash> </request> 10

11 The table below outlines each field, if it is mandatory (M) or optional (O) and an explanation. Field Element <request timestamp=" " type="dccrate"> M Description The name for this request type is dccrate <merchantid>yourmerchantid</merchantid> M Your client id as assigned by Elavon Payment Gateway <account /> O The Elavon Payment Gateway account to use. Defaults to your default account if blank. <orderid>test </orderid> M A unique id to identify this transaction. <amount currency="eur">2499</amount> M The amount and currency of the transaction in the merchant currency. <card> M The card details <number> </number> M Card Number. <expdate>0404</expdate> M Expiry Date 11

12 Field Element Description <type>visa</type> M Card Type - "VISA" or "MC" <chname>joe Pescquali</chname> </card> M Card holder name <sha1hash>c914a c4eebb33725</ sha1hash> M SHA1 hash of the elements in the XML as outlined below. <dccinfo> The DCC Info element <ccp>euroconex</ccp> M The DCC processor (Currency Conversion Processor) <type>1</type> M The type - always "1" </dccinfo> M </request> M 12

13 The returned response: <response timestamp=" "> <merchantid>yourmerchantid</merchantid> <account>internet</account> <orderid> </orderid> <result>00</result> <message>success</message> <pasref> </pasref> <dccinfo>< cardholdercurrency>gbp</cardholdercurrency> <cardholderamount>13049</cardholderamount> <cardholderrate>0.6868</cardholderrate> <merchantcurrency>eur</merchantcurrency> <merchantamount>19000</merchantamount> </dccinfo> <sha1hash>9cbaaf ceefa8c680ff8a773c83db140</sha1hash> </response> The returned response: Here you can see that the card is a GBP card and the amount you can offer the cardholder is GBP (at a rate of 1.00 EUR = GBP). The possible result codes are: Code Description 105 Card not supported by edcc 00 Card supported by edcc Field Element <merchantid>merchant id used</merchantid> <account /> <orderid>order id used</orderid> Description This is the Elavon Payment Gateway assigned merchant id used. This is the Elavon Payment Gateway account used. The order id of the request. 13

14 <amount currency="eur">2499</amount> <message>message returned from system</ message> <pasref> elavon payment gateway reference</pasref> The amount and currency of the transaction in the merchant currency. The text of the response. Will contain human readable version of result code. The Elavon Payment Gateway reference for the transaction. Used when referencing this transaction in subsequent requests if you are a Elavon Payment Gateway merchant. <dccinfo> The DCC Information element <cardholdercurrency>gbp</cardholdercurrency> The Currency of the cardholder <cardholderamount>13049</cardholderamount> The amount to offer the cardholder <cardholderrate>0.6868</cardholderrate> <merchantcurrency>eur</merchantcurrency> The Exchange Rate offered by Elavon for this transaction The original currency <merchantamount>19000</merchantamount> The original Amount. </dccinfo> <sha1hash>7384ae67...ac7d7d</sha1hash> </response> The SHA-1 hash of certain elements of the response - details below. 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. 14

15 MD5 and SHA-1 algorithms are secure hash functions. They take a string as input, and produce a fixed size number 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: <request timestamp=" " type="dccrate"> <merchantid> thestore </merchantid> <orderid> ORD </orderid> <amount currency="eur"> </amount> <card> <number> </number> <expdate> 0302 </expdate> <chname> Tony Danza </chname> <type> VISA </type> </card> To construct the hash follow this procedure: Form a string by concatenating the above fields with a period (".") ( thestore.ORD EUR ) Get the hash of this string (SHA-1 shown below). ( c5d02900c2ed43e0015d5e6792e2071a7b20afd5 ) Create a new string by concatenating this string and your shared secret using a period. ( c5d02900c2ed43e0015d5e6792e2071a7b20afd5.mysecret ) 15

16 Get the hash of this value. This is the value that you send to Elavon Payment Gateway. ( 9af7064afd307c9f988e8dfc271f9257f1fc02f6 ) <sha1hash> 9af7064afd307c9f988e8dfc271f9257f1fc02f6 </sha1hash> When we 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. Caution: It is very important to permission the CGI program appropriately 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. (This will be a hash of the timestamp, merchant id, order id, result, message, Elavon Payment Gateway reference and authcode with your secret key. If you sent us an md5 hash you will receive an md5 hash in the response and similarly for a sha-1 hash).you must then create an authorisation request and send this to your PSP as normal, including the current information returned in the previous response message. 16

17 <request timestamp=" " type="auth"> <merchantid>yourmerchantid</merchantid> <account></account> <orderid> </ordered> <amount currency="eur">19000</amount> <card> <number> </number> <expdate>0405</expdate> <chname>peter Johnson</chname> <type>visa</type> </card> <autosettle flag="1" /> <dccinfo> <ccp>euroconex</ccp> <type>1</type> <rate>0.6868</rate> <ratetype>s</ratetype> <amount currency="gbp">13049</amount> </dccinfo> <sha1hash> f58cef5b4dc8dc07b4592fae0fcaae61c</sha1hash> </request> 17

18 The response XML message is: <?xml version="1.0" encoding="utf-8"?> <response timestamp=" "> <merchantid>yourmerchantid</merchantid> <account>youraccount</account> <orderid> </orderid> <authcode>006073</authcode> <result>00</result> <cvnresult>u</cvnresult> <batchid>109338</batchid> <message>approval</message> <pasref> </pasref> <timetaken>1</timetaken> <authtimetaken>1</authtimetaken> <cardissuer> <bank>hsbc BANK PLC</bank> <country>united KINGDOM</country> <countrycode>gb</countrycode> <region>eur</region> </cardissuer> <dccinfo> <cardholdercurrency>gbp</cardholdercurrency> <cardholderamount>13049</cardholderamount> <cardholderrate>0.711</cardholderrate> <merchantcurrency>eur</merchantcurrency> <merchantamount>19000</merchantamount> <marginratepercentage>3.5%</marginratepercentage> <exchangeratesourcename>boi</exchangeratesourcename> <commissionpercentage>0.0%</commissionpercentage> <exchangeratesourcetimestamp> </exchangeratesourcetimestamp> </dccinfo> <sha1hash>3c88bbc815129fef5943d9d1495e719a9fe578ff</sha1hash> </response> 18

19 If you are using the Elavon Payment Gateway Redirect option, the values posted back would be similar to the ones below: Field Name Sample Value TIMESTAMP MERCHANT_ID yourmerchantid ACCOUNT Youraccount ORDER_ID RESULT 00 MESSAGEAUTH CODE BATCHID PASREF AUTHCODE CVNRESULT DCCCCP Euroconex DCCCHOICE YES, Please charge me in AUD DCCMERCHANTAMOUNT DCCMERCHANTCURRENCY EUR DCCRATE DCCCARDHOLDERAMOUNT DCCCARDHOLDERCURRENCY AUD DCCAUTHCARDHOLDERAMOUNT DCCAUTHCARDHOLDERCURRENCY AUD DCCAUTHRATE DCCAUTHMERCHANTAMOUNT DCCAUTHMERCHANTAMOUNT DCCAUTHMERCHANTCURRENCY EUR DCCEXCHANGERATESOURCETIMESTAMP DCCMARGINRATEPERCENTAGE 3.00 DCCEXCHANGERATESOURCENAME BOI DCCCOMMISSIONPERCENTAGE 0.00 SHA1HASH 107d26f0d d7e01783b0958 ec6b8580e0 19

20 6 Appendix A - Elavon Supported Currencies The following currencies are supported by Elavon for edcc enabled accounts. VI=Visa; VP=Visa Purchase; MC=MasterCard; JC=JCB; AX=American Express; DC=Diners Club; VD=Visa Delta; VE=Visa Electron; MD=Maestro; LA=Laser; SW=Switch/UKDM; SO=Solo; Currencies supported by Elavon ISO Currency Code VI VP MC JC AX DC VD VE MD LA SW SO EUR (Euro ) GBP (Sterling ) USD (US $) DKK (Danish Kr.) NOK (Norwegian Kr) CHF (Swiss Fr) AUD (Australian $) CAD (Canadian $) CZK (Czech Kr) JPY (Japanese ) NZD (New Zealand $) 20

21 HKD (Hong Kong $) ZAR (S. African Rand) SEK (Swedish Kr) 21

22 7 Appendix B -Regulatory Requirements 7.1 Regulatory Requirements MasterCard and Visa have introduced certain regulatory requirement surrounding currency conversion. By offering the cardholder the choice of currencies prior to the authorization request, the main requirement is met. Other requirements are as follows: The Merchant must inform the cardholder that edcc is optional. Both currencies (cardholder's and merchant's) must be available to the cardholder before authorisation. The total amount of the transaction in the merchant's currency should be displayed. The exchange rate that will be used should be displayed. The total amount of the transaction in the cardholder's currency should be displayed. It should be noted that the cardholder's choice is final. The currency symbols of both currencies must be displayed. For Visa the following must also be shown: The words "transaction amount" must be displayed after the amount in the cardholder's currency. The following statement: I accept that I have been offered a choice of currencies for payment. I accept the conversion rate and final amount and that the final selected transaction currency is cardholder's chosen currency, e.g. USD, EUR. For MasterCard the following statement must be shown: I accept the conversion rate and final amount and that the final selected transaction currency is cardholder's chosen currency, e.g. USD, EUR. 22

23 This statement should only be displayed if the cardholder chooses the merchant's base currency. I understand that MasterCard has a currency conversion process and that I have chosen not to use the MasterCard currency conversion process and I will have no recourse against MasterCard with respect to any matter related to the currency conversion or disclosure thereof. 23

24 Elavon Financial Services Limited is registered in Ireland Number 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 BR 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 24