Realex Payments Integration Guide - Ecommerce Remote Integration Version: v1.1
Document Information Document Name: Realex Payments Integration Guide Ecommerce Remote Integration Document Version: 1.1 Release Date: 26 th September 2012 Legal Statement This guide, in addition to the software described within, is under the copyright owned by Pay and Shop Limited, trading as Realex Payments, and subject to license. The included software may contain and utilise third-party software products. The guide and included software, whole or in part, cannot be published, downloaded, stored, reproduced, transmitted, transferred or combined with any other material, or be used for any other purpose without prior written permission from Realex Payments. All software, trademarks, logos, designs, and websites contained within this guide remain the intellectual property of the respective individual owners and companies. Disclaimer Every effort has been made to ensure the accuracy of information published in this guide. However Realex Payments cannot accept any responsibility for any errors, inaccuracies, or omissions that may or may not be published in the guide. To the extent permitted by law, Realex Payments is not liable for loss, damage, or liability arising from errors, omissions, inaccuracies, or any misleading or out-of-date information whether published in this guide or from any link in this guide. Realex Payments reserves the right to change this guide and the included software without prior notice or consent. Company Information Pay and Shop Limited, trading as Realex Payments has its registered office at The Observatory, 7-11 Sir John Rogerson s Quay, Dublin 2, Ireland and is registered in Ireland, company number 324929. 2000 2012 Realex Payments. All rights reserved. This material is proprietary to Pay and Shop Ltd, trading as Realex Payments, Ireland and is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of Realex Payments. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners. 2
Table of Contents 1 About This Guide 4 1.1 Purpose 4 1.2 Audience 4 1.3 Prerequisites 4 1.4 Related Documents 4 2 Go Live Checklist 5 3 Realex Payments Remote Integration 7 3.1 A note on PCI DSS Compliance 7 4 Your Merchant Services Agreement 9 5 Remote Integration 11 5.1 Process Flow 12 5.2 Sending the Authorisation Request 13 5.3 Processing the Authorisation Response 14 5.4 Additional XML Requests 14 6 Testing Required to Go Live 17 6.1 Testing Different Transaction Results 17 7 Additional Services 19 7.1 RealMPI 19 7.2 RealFX 19 7.3 RealVault 20 7.4 RealScore 20 7.5 RealEFT 21 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 Realex Payments 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 RealAuth 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 Realauth service, as outlined in the Realauth Developer's Guide 1.4 Related Documents In addition to this guide, you can also refer to the following documents in the Realex Payments documentation set for information about the Realauth service: Realcontrol User Guide Realex Payments Resource Document 4
2 Go Live Checklist To set an account live please ensure the following requirements are met: An email must be sent to support@realexpayments.com, or a member of the support team, by the Billing or Commercial contact on the account (as specified by the contract) requesting that the account be set to live. All invoices to date must be paid or the account must be set up for payment by Direct Debit. NOTE: Please allow 24 hours for the account to be set live following this request. The following information must be provided to Realex Payments prior to requesting account activation: This service requires that a merchant services agreement for ecommerce payments be set up with a bank with whom Realex are certified with. The merchant number issued and bank used must then be supplied to Realex Payments. Your merchant services agreement determines the currencies and card types acceptable on your account. Please note that the merchant number must be activated by Realex Payments with your acquiring bank before it can be used to process live transactions this process takes approximately 24 hours. Merchant ID Numbers are discussed in further detail on page 7 of this document. Several successful test transactions must be completed using Realex test card numbers. Please email support@realexpayments.com, or a member of the support team, to request these card numbers. Guidelines for testing are provided on page 12 of this document. If you intend on processing any request types other than standard authorisation requests, such as remote rebates, settlement or void requests, these request types should be test adequately before going live. Guidelines for testing are provided on page 20 of this document. You must provide the IP Address(es) of the server(s) from which your transactions will come to support@realexpayments.com or to a member of a support team. The IP Address requirement is discussed in further detail on pages 9 of this document. Further account configuration may be required if using any of the additional services outlined below: RealMPI: 3D Secure Cardholder Authentication (see page 14) 5
RealFX: Dynamic Currency Conversion (see page 14) RealVault: Card Storage for Recurring Payments (see page 15) RealScore: Transaction Suitability Scoring (see page 15) RealEFT: Direct Debit Processing (see page 15) 6
3 Realex Payments Remote Integration Thank you for choosing Realex Payments 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 Realex Payments 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, Realex Payments 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. 3.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. Realex Payments are a Level 1 PCI Compliant organisation, and submit to frequent audits of all of our systems and processes to ensure that this compliant status is upheld. 7
Where using a remote integration of Realex Payments 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 - https://www.pcisecuritystandards.org/. It is also recommend that you speak with your acquiring bank in relation to PCI DSS compliance and your obligations there under. 8
4 Your Merchant Services Agreement Realex Payments are a payment services provider or payment gateway. We provide infrastructure to connect you into the banking networks to allow you to seek authorisation on card transactions. We also provide a suite of transaction reconciliation, reporting and fraud management tools. Realex Payments do not provide card acquiring or banking services. As such, you will require a merchant services agreement signed with one of the banks that Realex Payments are certified with to facilitate authorisation and funding of card transactions. For a full list of acquiring banks that Realex Payments are certified with, please see http://www.realexpayments.com/ie/financial-institutions To take payments through a website using the remote integration, you will require a suitable E- Commerce merchant services agreement. Note that a merchant services agreement suitable for taking payments by a physical terminal, or a merchant number which facilitates Mail-Order/Telephone-Order payments, will not suffice for this purpose different conditions will apply as part of the merchant services agreement. Your merchant services agreement may cover a single currency or multiple currencies if you have a requirement for multicurrency processing please discuss this with your acquiring bank. Realex Payments should be notified of any changes in this regard. Note that your merchant services agreement also determines the card types that will be acceptable through your account once it goes live. Once your merchant services application has been fully processed, your acquiring bank will issue you with a merchant ID number. This number should be forwarded to support@realexpayments.com, or a member of the support team, immediately upon receipt. Realex Payments need to request associated information related to the merchant number before it can be used to take payments this process usually takes around 24 hours. Multiple merchant ID numbers may be added to your account to define different channels of payments. Individual sub-accounts may be configured to further assist reconciliation should you have a requirement to create multiple sub-accounts on your account, please contact a member of the support team for assistance. 9
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 Realex Payments 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. 10
5 Remote Integration A remote integration communicates directly with the Realex Payments 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: 1. You must ensure that a correctly formatted authorisation XML request is sent to the hosted payment page (https://epage.payandshop.com/epage-remote.cgi) from a known IP Address 2. You must ensure that your website can receive and process the authorisation XML response from the Realex Payments 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 RealAuth Developers Guide available for download at https://resourcecentre.realexpayments.com 11
5.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 Realex Payments API 4. The card details are forwarded to your acquiring bank, and the customer s issuing bank, for authorisation 5. The result of the authorisation is returned to Realex Payments, 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 12
Note: Because you will be transmitting sensitive customer account details in your request, it is very important that all communications with the Realex Payments 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. Realex Payments do 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. 5.2 Sending the Authorisation Request Authorisation requests are sent via XML to the payment gateway htts://epage.payandshop.com/epage-remote.cgi. 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 RealAuth Developers Guide available for download at https://resourcecentre.realexpayments.com 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 recommended that the shared secret not be sent by email as this is not a secure channel of communication. The creation and submission of digital signatures is discussed in more detail in the RealAuth Developers Guide available for download at https://resourcecentre.realexpayments.com. Realex Payments 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. Realex Payments 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 Realex Payments no payment will be taken. 13
To configure the IP addresses on your account please email the details to support@realexpayments.com or to a member of the support desk. Please note that all changes must be submitted by email by an authorised contact on your account. Please allow 24 hours for any account configuration changes. 5.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. Realex Payments 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 Realex Payments. The digital signature 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 Realex Payments as part of the transaction response. More information on the contents of the XML Response message can be found in the RealAuth Developers Guide located at https://resourcecentre.realexpayments.com. 5.4 Additional XML Requests The Realex Payments 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 Realex Payments account please contact support@realexpayments.com or a member of the support team for more information. Please allow 24 hours for any account configuration changes. 14
Unless otherwise noted, the format of all of the requests below, and their associated responses, is discussed in more detail in the Realex Payments XML Definitions Guide. The requests discussed below only apply to the RealAuth 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 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@realexpayments.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 Realex Payments 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. Realex 15
Payments 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 Realex Payments have received written authorisation from your bank. Please contact support@realexpayments.com or a member of the support desk for more information about the manual request type. 16
6 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 emailing support@realexpayments.com 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. 6.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 Realex Payments XML Definition Guide available for download at https://resourcecentre.realexpayments.com. 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. 17
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 RealControl 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. Realex Payments 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. 18
7 Additional Services Realex Payments provide 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. 7.1 RealMPI RealMPI is an implementation of 3D secure, 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 RealMPI implemented. It is strongly recommend that you consider the implementation of RealMPI if selling high value goods in a Customer Not Present environment. Implementing RealMPI remotely requires additional development work more information can be found in the RealMPI Remote Developers Guide available for download from https://resourcecentre.realexpayments.com. 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@realexpayments.com or a member of the support team for more information on this service. Implementing RealMPI requires some configuration work once the merchant numbers have been confirmed as registered please allow 24 hours for this configuration. 7.2 RealFX RealFX 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 RealFX requires additional 19
development work please contact support@realexpayments.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@realexpayments.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. Realex Payments do not charge for the implementation of RealFX. Implementing RealFX will require some configuration and so appropriate timelines should be allowed. 7.3 RealVault Realex Payments provide a card storage system called RealVault which can be used to securely store card details on the Level 1 PCI Compliant Realex Payments system. Once the card numbers have been added to RealVault, 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. Card Storage can be managed remotely via the exchange of a number of different XML requests. Further information on implementing RealVault can be found in the document RealVault Developers Guide available for download from https://resourcecentre.realexpayments.com. Note that RealVault is an additional service and carries additional monthly charges please contact support@realexpayments.com or a member of the support team for more information on the charges applicable. Implementing RealVault requires some configuration work please allow 24 hours for activation of the service. 7.4 RealScore RealScore is Realex Payment 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. Realscore 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. 20
RealScore is provided to all merchants free of charge, and can be configured via RealControl. RealScore 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 RealScore 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@realexpayments.com or a member of the support team for more information on the charges applicable. Implementing RealScore with autocheck requires some configuration work please allow 24 hours for activation of this service. 7.5 RealEFT RealEFT is a direct debit management system provided by Realex Payments to customers of Allied Irish Bank, Ulster Bank and Bank Of Ireland. RealEFT allows you to manage all of your payers and payment methods remotely based on the exchange of XML messages, raising payments against your customers on whatever basis you require. Please note that RealEFT currently only supports Euro payments to the three banks mentioned above. Note that RealEFT is an additional service and carries additional monthly charges as well as a one time setup fee please contact support@realexpayments.com or a member of the support team for more information on the charges applicable. Implementing RealEFT requires some configuration work please allow 24 hours for activation of this service. 21
Connect with us online: /realexpayments @realexpayments @realex_uk @realex_france /realexpayments /companies/realex-payments Our office Locations: Dublin The Observatory, 7-11 Sir John Rogerson s Quay, Diblin 2 Ireland tel: +353 (0)1 2808559 fax: +353 (0)1 2808538 www.realexpayments.com.ie sales@realexpayments.com London 1 Lyric Square London W6 0NB United Kingdom tel: +44 (0)203 178 5370 fax: +44 (0)207 691 7264 www.realexpayments.co.uk sales@realexpayments.co.uk Paris 5 rue du Helder 75009, Paris France Tel: +33 (0)1 53 24 53 29 fax: +33 (0)1 53 24 53 39 www.realexpayments.fr sales@realexpayments.fr 22