Global Iris Integration Guide ecommerce Remote Integration February 2013
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 Overview... 4 2.1 A Note On PCI DSS Compliance... 4 3 Remote Integration... 5 3.1 Process Flow... 6 3.2 Sending The Authorisation Request... 7 3.3 Processing The Authorisation Response... 7 3.4 Additional XML Requests... 7 4 Testing Required to Go Live... 9 4.1 Testing Different Transaction Results... 9 5 Go Live Checklist... 11 6 Other Services... 12 6.1 Real MPI... 12 6.2 RealScore... 12 6.3 RealVault... 12 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 developer and customer use only. It has been supplied under the conditions of your payment-processing contract. 1.1 Purpose The purpose of this document is to outline the steps required to set your Global Iris account live, and to provide an estimation of the timelines involved. 1.2 Audience This guide is targeted at merchants and developers who will be using the Global Iris RealAuth remote service for e-commerce 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 Global Iris RealAuth service, as outlined in the Global Iris RealAuth Developer's Guide 1.4 Related Documents In addition to this guide, you can also refer to the following: Global Iris RealControl User Guide 3
2 Overview Thank you for choosing Global Payments. Your Global Iris account is currently in test mode. In test mode you can use the account to familiarise yourself with the system and to complete the integration into your Global Iris account, this will then 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; Global Iris provides 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 must be noted that because you will be handling the customer s card details on your server, you will have a requirement to be compliant with Payment Card Industry Data Security Standard (PCI DSS) because you will be transmitting sensitive account details; all communications should be secured using Secure Socket Layer (SSL). 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. This 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 schemes (these include but are not exclusive to Visa and MasterCard). PCI DSS rules are administered by the card schemes and enforced by the acquiring banks and card processors who are members of these schemes. Adherence to the PCI DSS is expected as part of the Card Processing Agreement that you have signed with Global Payments, and is a condition of that agreement. When using the Global Iris remote service, you will handle and transmit (and potentially store) card details on your systems and as such you will have a requirement to be PCI DSS compliant. For more information on PCI DSS and your obligations under these rules, please refer to the PCI Council website - https://www.pcisecuritystandards.org/. It is also strongly recommended that you speak with Global Payments in relation to PCI DSS compliance and your obligations. 4
3 Remote Integration A remote integration enables your web pages to communicate directly with the Global Iris Application Programming Interface (API) via the secure exchange of extensible Markup Languages (XML) messages. The API allows for the 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 the Global Iris system 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://remote.globaliris.com/realauth) from a known IP Address. 2. You must ensure that your website can receive and process the authorisation XML response from the Global Iris API. The following section 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 refer to the Global Iris RealAuth Developers Guide which is available to download at https://resourcecentre.globaliris.com. 5
3.1 Process Flow Global Iris RealAuth Remote Integration Customer flow Data flow Merchant Website Global Iris Card details transmitted securely to payment gateway 3 Global Iris arranges authorisation with issuing bank 4 Customer visits Merchant website to make a purchase 1 Customer enters card details on Merchant website 2 Merchant s shopping cart receives response and updates result 5 Result displayed to customer 6 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 Global Iris API. 4. The card details are forwarded to Global Payments, and the customer s issuing bank, for authorisation. 5. The result of the authorisation is returned to Global Iris, which returns 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 passes 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 Global Iris 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. You will need to speak to your developer about configuring your server with an SSL certificate. Failure to do so may result in you receiving fines from the card schemes. 6
3.2 Sending The Authorisation Request Authorisation requests are sent via XML to the payment gateway https://remote.globaliris.com/realauth. The authorisation request must identify your merchant account on the Global Iris 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 Global Iris RealAuth Developers Guide available for download at https://resourcecentre.globaliris.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 merchant. 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 Global Iris RealAuth Developers Guide available for download at https://resourcecentre.globaliris.com. Global Iris maintains 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 subaccount. Your Global Iris account can also be configured to allow transactions from a range of IP addresses (limited to IPs within a single trailing octet). Transactions which originate from an unknown IP address will be automatically blocked no payment will be taken. To configure the IP addresses on your account, please email the details to globaliris@realexpayments.com or to a member of the Global Iris Support Team. Please note that all changes must be submitted by email by an authorised contact on your account. Please allow 24 hours Monday Friday for any account configuration changes to be completed. 3.3 Processing The Authorisation Response Authorisation responses are sent in a XML response message back to your systems using the same connection that was opened to send the XML authorisation request. Global Iris will return a response code indicating whether the transaction has been successful or not. In addition, Global Iris will also provide an authorisation code for all successful transactions and any text messages returned by the card issuer 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 a Global Iris merchant. The digital signature is created using the shared secret passed to you by your account manager when your account was initially configured. It is left to your discretion to check the digital signature returned by Global Iris as part of the transaction response. More information on the content of the XML response message can be found in the Global Iris RealAuth Developers Guide located at https://resourcecentre.globaliris.com. 3.4 Additional XML Requests The Global Iris 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 Global Iris account manager. Further testing should be carried out for all request messages that you intend to submit remotely. Please note that implementing certain request types requires configuration on your Global Iris account please contact globaliris@realexpayments.com or a 7
member of the Global Iris Support Team for more information. Please allow 24 hours Monday Friday for any account configuration changes to be completed. Unless otherwise noted, the format of all of the requests below, and their associated responses, is discussed in more detail in the Global Iris XML Definitions Guide. The requests discussed below only apply to the Global Iris 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 authorisation 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 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 a customer s 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 globaliris@realexpayments.com or a member of the Global Iris 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 must be stored on your servers. Settlement Request (type: settle): An authorisation which has been processed using delayed settlement can be remotely settled within 28 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 must be stored on your servers. Offline Authorisation Request (type: offline): In certain cases, a transaction may be declined by the card issuer pending offline authorisation no funds will be received for the transaction unless you contact the Global Payments authorisation centre to obtain an authorisation code to allow the transaction to be completed. This authorisation code can be sent to Global Iris using the offline request type. Some data from the original transaction authorisation will be required to process a remote offline authorisation and must be stored on your servers. Manual Authorisation Request (type: manual): In some cases Global Payments authorisation centre may be able to provide you with an authorisation code for a pre-approved transaction. This should be added directly to the settlement file sent for funding without being authorised. This request type is disabled on all accounts by default, and requires authorisation from Global Payments to enable it. Please contact globaliris@realexpayments.com or a member of the Global Iris Support Team for more information about this manual request type. 8
4 Testing Required To Go Live Your Global Iris account is currently in test mode. You are required to complete adequate testing. It is very important that you test each card type that you intend to process, and that you test each possible result that may arise (outlined below). Exhaustive testing of your account will minimise 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 globaliris@realexpayments.com or a member of the Global Iris 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 Global Iris XML Definition Guide available for download at https://resourcecentre.globaliris.com. 00: Transaction Authorised Successfully. Transactions that return a result of 00 have been authorised by the card issuer and will be funded to you once the transaction has been settled. 101: Transaction Declined. Transactions that return a result of 101 have been declined by the card issuer. 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 card issuer cannot divulge the reason 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 card issuer but you are given the opportunity to complete the transaction by contacting Global Payments authorisation centre to get an authorisation code, which can be entered via Global Iris 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 to the card issuer as lost or stolen. No funds will be received for the transaction. 9
200/205: Bank Communication Error. Global Iris has been unable to connect to the card issuer 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 200 or 205 results code. 10
5 Go Live Checklist 5.1 To Set An Account Live An email must be sent by the billing or commercial contact on the account to either globaliris@realexpayments.com or a member of the Global Iris Support Team, requesting that the account be set to live. NOTE: Please allow 24 hours Monday Friday for the account to be set live following this request. The following must be completed & details provided to the Global Iris Support Team prior to requesting account activation: This service requires that a Card Processing Agreement for ecommerce payments be set up with Global Payments. The merchant number issued will be used by Global Iris. Your Card Processing Agreement determines the currencies and card types acceptable on your account. Several successful test transactions must be completed using Global Iris test card numbers. Please email globaliris@realexpayments.com, or a member of the Global Iris Support Team to request these card numbers. You must provide the referring and response URLs for your account to globaliris@realexpayments.com or to a member of the Global Iris Support Team. If providing a payment page template (which is recommended) the template package must be created in accordance with the guidelines and must be provided to globaliris@realexpayments.com or a member of the Global Iris Support Team at least 24 hours in advance of going live. Further account configuration may be required for the services outlined below: Global Iris Real MPI: 3D Secure Cardholder Authentication Global Iris RealScore: Transaction Suitability Scoring Global Iris RealVault: Card Storage for Recurring Payments 11
6 Other Services Global Iris also provides the services described below, which may be provided as part of your set up. These services may require additional configuration, and as such appropriate timelines should be allowed for implementation. 6.1 Global Iris Real MPI Global Iris Real MPI is an implementation of 3D Secure, the cardholder authentication service developed by Visa and MasterCard and released as Verified by Visa and MasterCard SecureCode. Implementing 3D Secure will minimise your liability in the event of charge-backs that arise due to fraudulent activity on your account. It is strongly recommended that you consider the implementation of Global Iris Real MPI if selling high value goods in a Customer Not Present environment.* *If you accept Maestro cards it is mandatory to support MasterCard 3D Secure. Implementing Global Iris Real MPI remotely requires additional development work more information can be found in the Global Iris Real MPI Remote Developers Guide available to download from https://resourcecentre.globaliris.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. Please contact globaliris@realexpayments.com or a member of the Global Iris Support Team for more information on this service. Implementing Global Iris Real MPI requires some configuration work once the merchant numbers have been confirmed as registered please allow time for this configuration. 6.2 Global Iris RealScore Global Iris RealScore is a proprietary Transaction Suitability Scoring (TSS) system. A transaction suitability score is a score assigned to a transaction based on rules configured within the system, highlighting potentially suspicious transactions which can be flagged for review. Global Iris 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. Global Iris RealScore is configurable; a standard set of rules will be applied to all accounts. Please contact globaliris@realexpayments.com or a member of the Global Iris Support Team for more information. Any changes to the standard rules will need to be approved by Global Payments before being implemented.. 6.3 Global Iris RealVault Global Iris provides a card storage system called Global Iris RealVault which can be used to securely store card details on a Level 1 PCI compliant system. Once the card numbers have been added to Global Iris RealVault, you can no longer view any of the sensitive card details however, by using tokens, you can raise payments against these stored card details at a later date. The payment page can be used to capture customer card details to be stored in the Global Iris RealVault system. Card numbers and payments can then be managed either via Global Iris RealControl or via the remote submission of XML messages. Implementing Global Iris RealVault requires some configuration work please allow time for this service to be activated. 12
Global Payments 51 De Montfort Street Leicester LE1 7BB Tel 0845 702 3344* Textphone 0845 602 4818 Email globaliris@realexpayments.com Global Payments is HSBC s preferred supplier for card processing in the UK. Global Payments is a trading name of GPUK LLP. GPUK LLP is authorised by the Financial Conduct Authority under the Payment Services Regulations 2009 (504290) for the provision of payment services. GPUK LLP is a limited liability partnership registered in England number OC337146. Registered Office: 51, De Montfort Street, Leicester, LE1 7BB. The members are Global Payments U.K. Limited and Global Payments U.K. 2 Limited. Service of any documents relating to the business will be effective if served at the Registered Office. *Lines are open between 9am 5pm Monday to Friday excluding public holidays. To help us continually improve our service and in the interests of security, we may monitor and/or record your telephone calls with us. Any recordings remain our sole property. We also provide a Textphone service on 0845 602 4818. GPUK LLP. All rights reserved. GP020 02/2013