Elavon Payment Gateway Integration Guide- Remote

Transcription

1 Elavon Payment Gateway Integration Guide- Remote Version: v1.1

2 Table of Contents 1 About This Guide Purpose Audience Prerequisites Related Documents 3 2 Elavon Payment Gateway Remote Integration A note on PCI DSS Compliance 4 3 Remote Integration Process Flow Sending the Authorisation Request Processing the Authorisation Response Additional XML Requests 10 4 Testing Required to Go Live Testing Different Transaction Results 12 5 Additional Services Elavon Payment Gateway 3D Secure Elavon Payment Gateway Multi-Currency Elavon Payment Gateway SecureDataVault Elavon Payment Gateway RiskManager 16 Page 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 paymentprocessing contract. 1.1 Purpose The purpose of this document is to outline the steps required to set your Elavon Payment Gateway account live, and to provide an estimation of the timelines involved. 1.2 Audience The target audience for this guide is merchants who will be using the Elavon Auth Remote service for Ecommerce Transactions 1.3 Prerequisites In order to use this guide, you should have experience with and knowledge of the following concepts: Correct use of the Elavon Auth service, as outlined in the Elavon Auth Developer's Guide 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: Reporting User Guide Elavon Payment Gateway Resource Document Page 3

4 2 Elavon Payment Gateway Remote Integration Thank you for choosing Elavon Payment Gateway as your Payment Services Provider. Your account is currently in test mode you can use the test account to familiarise yourself with the system and to complete the integration into your Elavon Payment Gateway account to allow you to take payments from your customers online. This document outlines the steps required to activate the account so that you can begin to take live payments. Where merchants have a requirement to take payments from their customers online, Elavon Payment Gateway provide an Application Programming Interface (API) which allows for the remote submission of authorisation requests. You host the payment page on your own servers and have complete control over the look and feel of this page. You may also implement a remote interface for processing void, settlement, rebate and other related requests. It should be noted that because you will be handling the customer s card details on your server, you will have some requirement to be PCI DSS Compliant (see below). Because you will be transmitting sensitive account details, all communications should be SSL secured. 2.1 A note on PCI DSS Compliance The Payment Card Industry Data Security Standard (PCI DSS) is a worldwide information security standard which dictates how sensitive details such as credit card numbers should be handled, stored and transmitted. The standard applies to all organisations that handle, store, process or exchange cardholder information from any card branded with the logo of one of the card brands (such as Visa and Mastercard amongst others). PCI DSS rules are administered by the card schemes and enforced by the acquiring banks who are members of said schemes. Adherence to the PCI DSS is mandated by the merchant services agreement that you have signed with your acquiring bank, and is a condition of that agreement. Elavon Payment Gateway are a Level 1 PCI Page 4

5 Compliant organisation, and submit to frequent audits of all of our systems and processes to ensure that this compliant status is upheld. Where using a remote integration of Elavon Payment Gateway service, you will handle and transmit (and potentially store) sensitive card details on your systems. As such, you will have a requirement to be PCI DSS compliant. For more information on PCI DSS and your obligations as outlined under those rules, please refer to the PCI Council website - It is also recommend that you speak with your acquiring bank in relation to PCI DSS compliance and your obligations there under. If you have not yet contacted your acquiring bank regarding your merchant services agreement, please do so immediately. Your merchant services application may take two weeks or more to process, which may delay you in going live with your Elavon Payment Gateway account. It should be noted that it is possible to remotely integrate a call centre solution for taking payments via Mai Order/Telephone Order. If this is your intention then a suitable MOTO (Mail Order/Telephone Order) merchant number should be provided. Note: Using a merchant ID number which is not suitable for the type of transactions that you intend to process may represent a violation of your merchant services agreement. Exception fees (fines) can be levied on you by your acquiring bank for the improper use of a merchant ID number. Page 5

6 3 Remote Integration A remote integration communicates directly with the Elavon Payment Gateway Application Programming Interface (API) via the secure exchange of XML messages. The API allows for the remote submission of a number of different request types which allow you to process card authorisations, rebates, voids and other request types. To fully integrate your website into our systems using the Remote Integration method, the following steps must be completed: You must ensure that a correctly formatted authorisation XML request is sent to the hosted payment page ( from a known IP Address 1. You must ensure that your website can receive and process the authorisation XML response from the Elavon Payment Gateway API The sections below offer a high level overview of the integration process for informational purposes only for technical details on how to integrate into the hosted payment page please see the Elavon Auth Developers Guide available for download at Page 6

7 3.1 Process Flow The process is outlined step by step below: 1. The customer makes a purchase on your website, and goes to check out. 2. The customer is provided with a payment form on your website where they can enter their card details 3. An XML authorisation request is generated and sent securely to the Elavon Payment Gateway API 4. The card details are forwarded to your acquiring bank, and the customer s issuing bank, for authorisation Page 7

8 5. The result of the authorisation is returned to Elavon Payment Gateway, who return these results to your system in an XML message transmitted via the same connection which was opened by your system to ours 6. Your system parses the XML response, updates your own databases, and returns an appropriate response to the customer Note: Because you will be transmitting sensitive customer account details in your request, it is very important that all communications with the Elavon Payment Gateway gateway are SSL (Secure Socket Layer) secured. SSL encrypts all data sent between the two parties, ensuring that no third party can intercept the data sent. Elavon Payment Gateway does not validate or enforce this requirement you will need to speak to your developer about configuring your server with an SSL certificate. Failure to do so may result in exception charges (fines) from your acquiring bank or from the card schemes. 3.2 Sending the Authorisation Request Authorisation requests are sent via XML to the payment gateway The authorisation request must identify your merchant account on our servers and must provide the information necessary to process the transaction. The customer s card details must also be included in the authorisation request the request should include the cardholder name, card number, expiry date and three digit security (four digits for American Express transactions) as well as the presence indicator which determines the presence of the security code, to ensure maximum authorisation rates. Further details on correctly formatting and sending the authorisation request can be found in the Elavon Auth Developers Guide available for download at All authorisation requests must include a digital signature which is provided to ensure the integrity of the transaction data and to authenticate the sender as being the legitimate account holder. The digital signature is created using the shared secret passed to you by your account manager when your account was first configured it is very important that this information only be divulged to authorised account contacts. The shared secret will only be passed to you over the phone, and it is strongly Page 8

9 recommended that the shared secret not be sent by as this is not a secure channel of communication. The creation and submission of digital signatures is discussed in more detail in the Elavon Auth Developers Guide available for download at Elavon Payment Gateway maintain a white list of IP addresses from which authorisation requests for your account may come this is a security measure which prevents unauthorised transactions from being processed through your account. Multiple IP addresses may be provided for a single merchant account or sub-account. Elavon Payment Gateway can also configure your account to allow transactions from a range of IP addresses (limited to IPs within a single trailing octet). Transactions which originate at an unknown IP Address will be automatically blocked by Elavon Payment Gateway no payment will be taken. To configure the IP addresses on your account please the details to support@elavonpaymentgateway.com or to a member of the support desk. Please note that all changes must be submitted by by an authorised contact on your account. Please allow 24 hours for any account configuration changes. 3.3 Processing the Authorisation Response Authorisation responses are sent in a Response XML message back to your systems in the same connection that was opened to send the XML authorisation request. Elavon Payment Gateway will return a response code indicating whether the transaction has been successful or not, along with an authorisation code for successful transactions and any text messages returned by the bank in response to the authorisation request. This response should be used to update your own databases. All authorisation responses will include a digital signature which is provided to ensure the integrity of the transaction data and to authenticate the sender as Elavon Payment Gateway. The digital signature Page 9

10 is created using the shared secret passed to you by your account manager when your account was first configured. It is left to your discretion to check the digital signature returned by Elavon Payment Gateway as part of the transaction response. More information on the contents of the XML Response message can be found in the Elavon Auth Developers Guide located at Additional XML Requests The Elavon Payment Gateway API supports the submission and processing of a number of additional XML request types which can be used to wholly integrate your system. If implementing these additional request messages please inform your account manager. Further testing should be carried out for all request messages that you intend on submitting remotely. Please note that implementing certain request types requires configuration on your Elavon Payment Gateway account please contact support@elavonpaymentgateway.com or a member of the support team for more information. Please allow 24 hours for any account configuration changes. Unless otherwise noted, the format of all of the requests below, and their associated responses, is discussed in more detail in the Elavon Payment Gateway XML Definitions Guide. The requests discussed below only apply to the Elavon Auth core authorisation service additional services may require the implementation of additional request types. Rebate Request (type: rebate): Transactions may be reversed back to the card that was used to process the original authorisation within 180 days of authoriation this is known as a rebate. Rebates can be implemented remotely. Some data from the original transaction authorisation will be required to process a remote rebate and so must be stored on your servers. A rebate password is required to implement this request type a hash (Sha1 Hash) must be submitted alongside the rebate request to complete the rebate Refund Request (type: credit): Funds can be credited to customers account where no original transaction exists or where the original authorisation is older than 180 days. The credit request type is used to process a refund to a customer in this way. The customer s card details will be Page 10

11 required. A refund password is also required to implement this request type - a hash (Sha1 Hash) must be submitted alongside the credit request to complete the refund. Implementing this request type carries associated security concerns, and as such it is disabled on all accounts by default. Should you have a requirement to implement the credit request, please contact support@elavonpaymentgateway.com or a member of the support team for further assistance. Void Request (type: void): An authorisation may be voided prior to settlement no funds will be received for the transaction. Some data from the original transaction authorisation will be required to process a remote void and so must be stored on your servers. Settlement Request (type: settle): An authorisation which has been processed using delayed settlement can be remotely settled within 30 days of the authorisation using the remote settlement request. Some data from the original transaction authorisation will be required to process a remote settlement and so must be stored on your servers. Offline Authorisation Request (type: offline): In certain cases a transaction may be declined by the bank pending offline authorisation no funds will be received for the transaction unless your acquiring bank is willing to provide an authorisation code to allow the transaction to be completed. The authorisation code can be sent to Elavon Payment Gateway using the offline request type. Some data from the original transaction authorisation will be required to process a remote offline authorisation and so must be stored on your servers. Manual Authorisation Request (type: manual): In some cases your bank may be able to provide you with an authorisation code for a pre-approved transaction which should be added directly to the settlement file sent to the bank for funding without being authorised. Elavon Payment Gateway support this service where authorised by your acquiring bank using the manual request type. This request type is disabled on all accounts by default, and cannot be enabled until Elavon Payment Gateway have received written authorisation from your bank. Please contact support@elavonpaymentgateway.com or a member of the support desk for more information about the manual request type. Page 11

12 4 Testing Required to Go Live Your account is currently in test mode. One of the requirements for activating your account to allow you to process live transactions is that adequate testing be completed. It is very important that you test each card type that you intend on processing, and that you test each possible result that may arise (outlined below). Exhaustive testing of your account will minimise account issues in the live environment which may affect your customers. If implementing any of the additional request types outlined in the previous section, further testing of each request type should be carried out before going live. You can request test card numbers by ing or a member of the support team. The Test Card numbers provided allow you to test each card type that you may take through the system. 4.1 Testing Different Transaction Results There are a number of possible responses to a card authorisation request, which are outlined below. Test card numbers are provided to simulate each of the possible responses. It is recommended that you test each response for each card type you intend to accept in a live environment, so that you can ensure that your system is robust enough to handle each possible response appropriately. Note that the response below will only be returned to an authorisation request different responses may be returned for any of the additional request types discussed in the previous section. For further information, please refer to the Elavon Payment Gateway XML Definition Guide available for download at Page 12

13 00: Transaction Authorised Successfully. Transactions that return a result of 00 have been authorised by the bank and will be funded to the merchant once the transaction has been settled. 101: Transaction Declined. Transactions that return a result of 101 have been declined by the bank. While the most common cause of a declined transaction would be where insufficient funds exist to cover the cost of the transaction, other reasons may apply. The issuing bank cannot divulge the reasons for a declined transaction to anyone other than the cardholder themselves. No funds will be received for declined transactions. 102: Transaction Declined Pending Offline Authorisation. The transaction in question has been declined by the bank, but the merchant is given the opportunity to complete the transaction by contacting their acquiring bank s offline authorisation centre to get an authorisation code, which can be entered via Reporting to complete the transaction. No funds will be received unless this step is completed. 103: Card Reported Lost or Stolen. The transaction in question has been declined because the card number provided has been reported as lost or stolen. No funds will be received for the transaction. 200/205: Bank Communication Error. Elavon Payment Gateway have been unable to connect to the bank to carry out the authorisation. This is not a reflection of the customer s credit status the transaction may be tried later and may succeed. No funds will be received for a transaction which returns a 200 or 205 result. Page 13

14 5 Additional Services Elavon Payment Gateway provides a number of additional services for which you may have a requirement. These additional services may require additional configuration, and as such appropriate timelines should be allowed for implementation. Note that additional charges may apply for the implementation of any of the services below. 5.1 Elavon Payment Gateway 3D Secure 3D Secure is an implementation of the cardholder authentication service developed by Visa and Mastercard and released as Mastercard SecureCode and Verified by Visa. Implementing 3D secure will minimise your liability in the event of chargebacks that arise due to fraudulent activity on your account. You may be able to avail of a lower merchant services fee from your acquiring bank with 3D Secure implemented. It is strongly recommend that you consider the implementation of 3D Secure if selling high value goods in a Customer Not Present environment. Implementing 3D Secure remotely requires additional development work more information can be found in the 3D Secure Remote Developers Guide available for download from Please note that implementing 3D secure requires that your merchant number be registered for the service with the card schemes, a process that can take up to 10 working days. This process can only begin once your merchant services application has been completed. Please contact support@elavonpaymentgateway.com or a member of the support team for more information on this service. Implementing 3D Secure requires some configuration work once the merchant numbers have been confirmed as registered please allow 24 hours for this configuration. Page 14

15 5.2 Elavon Payment Gateway Multi-Currency Multi-Currency is a Dynamic Currency Conversion (DCC) service which allows you to offer international customers an exchange rate from your base currency to theirs at the point of sale (rather than at the point of settlement). This allows the customer to know exactly what they will be charged for their transaction without having to worry about fluctuations in the currency markets. Merchants who have implemented DCC can also share in the commission charged by the Currency Conversion Processor used, and can represent a significant stream of revenue. Implementing Multi-Currency requires additional development work please contact support@elavonpaymentgateway.com or a member of the support team for further information. Processing DCC transactions requires that you have an agreement with a Currency Conversion Processor who can facilitate the provision of exchange rates. Your Currency Conversion Processor may provide you with a merchant ID number specific for this purpose this number should be forwarded to support@elavonpaymentgateway.com or a member of the support team for configuration. This process will take at least 24 hours. Please note that this service is only supported for customers of certain acquiring banks. Elavon Payment Gateway do not charge for the implementation of Multi- Currency. Implementing Multi-Currency will require some configuration and so appropriate timelines should be allowed. 5.3 Elavon Payment Gateway SecureDataVault Elavon Payment Gateway provide a card storage system called SecureDataVault which can be used to securely store card details on the Level 1 PCI Compliant Elavon Payment Gateway system. Once the card numbers have been added to SecureDataVault, you can no longer view any of the sensitive card details themselves however, using tokens, you can raise payments against these stored card details at a later date. Page 15

16 Card Storage can be managed remotely via the exchange of a number of different XML requests. Further information on implementing SecureDataVault can be found in the document SecureDataVault Developers Guide available for download from Note that SecureDataVault is an additional service and carries additional monthly charges please contact support@elavonpaymentgateway.com or a member of the support team for more information on the charges applicable. Implementing SeucreDataVault requires some configuration work please allow 24 hours for activation of the service. 5.4 Elavon Payment Gateway RiskManager RiskManager is Elavon Payment Gateway s proprietary Transaction Suitability Scoring (TSS) system. A transaction suitability score is a score assigned to a transaction based on rules configured by you, highlighting potentially suspicious transactions which can be flagged for review. RiskManager can also be implemented with automatic transaction checking, where transactions which break certain predefined rules or which return a low score can be automatically declined. RiskManager is provided to all merchants free of charge, and can be configured via Reporting. RiskManager with autocheck is a chargeable service which carries a monthly charge this service is primarily designed for merchants who process large volumes of transactions. Implementing RiskManager may require some additional development work on your own systems if to be used with the Hosted Payment Page. This will require additional configuration on your account please contact support@elavonpaymentgateway.com or a member of the support team for more information on the charges applicable. Implementing RiskManager with autocheck requires some configuration work please allow 24 hours for activation of this service. Page 16

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