RealAuth. Developers Guide. Version: 4.9

Transcription

1 RealAuth Developers Guide Version: 4.9

2 Document Information Document Name: RealAuth Developers Guide Document Version: 4.9 Release Date: 14 th April 2013 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 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

3 Table of Contents 1 About This Guide Purpose Audience Prerequisites Related Documents 4 2 Introduction The Redirect Method The Remote Method Realauth Redirect Features List Remote Features List Sub-Accounts 7 3 Realauth Redirect Redirect Example 8 4 Templates Redirect Integration Redirect Request Field Definitions Redirect Response Field Definitions Digital Signature for Redirect Address Verification Service: Redirect 17 5 Realauth Remote Remote Example Application Based Checking Remote Integration Remote Request Message Remote Response Message Digital Signatures for Remote Address Verification Service 30 6 Steps Required To Go Live 32 7 Appendix A Sample Code Luhn check 33 8 Appendix B Codes Currency Codes Card Types 34 9 Response Codes Country Codes Appendix C - Data Validation Rules Appendix D - Realex Guides 42 3

4 1 About This Guide This section outlines the purpose and aim of the guide, target audience, any source materials or terminology used, and a general document description. Please note that this document is regarded as confidential and is for customer use only. It has been supplied under the conditions of your payment-processing contract. 1.1 Purpose The purpose of this guide is to explain in detail what is involved in integrating the redirect or remote authorisation services. 1.2 Audience The target audience for this guide is software and web developers. 1.3 Prerequisites In order to use this guide, you should have experience with and knowledge of the following concepts: For redirect integration: A basic understanding of html and at least one server side dynamic scripting language. For remote integration: Creation and remote submission of XML messages 1.4 Related Documents In addition to this guide, you can also refer to the following documents in the Realex Payments documentation set for information about the Realauth service: Realauth Response Codes Realauth XML Definitions Realex 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: 4

5 Convention Description Example Blue Italic or Plain Type Hyperlinks and crossreferences For more information see Table 1. Italics Names of other guides Realauth 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 5

6 2 Introduction The RealAuth service works under two different scenarios. 2.1 The Redirect Method The redirect method is suitable for merchants that do not have their own secure server. Using this method, the customer will be redirected to Realex secure server to enter their credit card details. 2.2 The Remote Method The remote method affords the merchant greater control of the transaction process but requires that they maintain their own secure server. Using this method, the customers card details will be taken by the merchant and passed to Realex by XML messages. Your solution must integrate with our payment service at two levels firstly, you must submit correctly formed requests for authorisations and secondly, you must then accept the response that is returned by the Realex application. To determine which version of Realauth you should use, consult the following feature list and decide which one is the right choice for your situation: 2.3 Realauth Redirect Features List Merchant does not need a secure server. Can be hosted anywhere, and on any platform as long as CGI scripts are enabled. The merchant does not collect the card details, and does not have access to them. The customer is redirected to the Realauth application on a secure Realex Payments server by a script on the merchant s website. Realex Payments host a secure, merchant-branded web page. We collect the card details and process the payment. The customer and the results of the transaction are sent back to the merchant via another script on the merchant s web site (Realex can provide sample scripts to get you started). 2.4 Remote Features List Merchant needs a secure server or can integrate the service into a desktop application. Can be hosted anywhere, and on any platform as long as CGI is enabled. The card details are collected by the merchant and passed to Realex Payments as XML messages. Realex Payments respond with an XML message containing the results of the transaction in a matter of seconds. Realex can provide sample scripts to get you started. The merchant need not store card details, but they are available. The merchant controls full process, screen flow. Customer may never know Realex were involved in the process. 6

7 Note: In certain circumstances the acquiring bank may need to approve your use of the Realauth remote option and it is entirely the merchants/developers responsibility to ensure that the acquiring bank has agreed and authorised the merchant in this regard. In order to facilitate the use of multiple web-sites and bank accounts, merchants can set up a number of sub-accounts under their main Realex account. Each sub-account can use a different set of URLs/IP addresses and can channel the funds to a different bank account. The default sub-account will be 'internet' for all merchants. To have additional sub-accounts set up you will need to contact Realex payments and provide us with some details. 2.5 Sub-Accounts In order to create a sub account a merchant must provide: For redirect: A sub-account name Referring and response URLs Bank merchant number For remote: A sub-account name IP address of hosting server Bank merchant number 7

8 3 Realauth Redirect Merchants who do not have their own secure server can use Realauth redirect. Rather than entering their credit card number on a (non-secure) website, the customer is redirected to the Realex Payments secure server. Here they are presented with a payment page that you can customise to maintain the appearance of your website. After entering their card details customers are returned to your site to continue browsing. Redirect payment pages are customised using 'templates', these are described in the following section. Realex Payments can supply working sample code in ASP, PHP, Java,.NET and Perl. Please note that this is sample code only and will need to be modified to suit individual merchants needs. The sample code will provide guidance on how to carry out the steps required for a redirect transaction to succeed. 3.1 Redirect Example The process involved for a redirect transaction is shown in the following example 1. Once the full amount is known the customer is presented with a confirmation page. This page is hosted on the merchant s server. If the customer chooses to continue they are redirected to Realex' secure server. 8

9 2. On Realex' secure server, the customer is presented with the payment form. This page uses a template to maintain the appearance of the merchant s own web-site. 9

10 3. After entering their card details, the customer clicks Pay Now and the card details are sent to the bank for authorisation. When the reply is received a script on the merchant site is contacted with the result (approved/declined etc). The HTML output of the merchants' response script is then taken and displayed on Realex' secure server using the template. Note: Requests should be sent to Realex Payments only at the end of the shopping experience, once the total amount of the payment is known. No information about the contents of the order is required for Realex to process the transaction, however you can send any information about the order to Realex as hidden fields these will be ignored and sent back to your response script once the transaction has been processed. Rather than maintaining a database of orders you may wish to simply send yourself an with this information once the order is successful. It is worth noting that the Internet is not 100% reliable and communication errors may occur so it is possible that the information will not make it back to your response script. We recommend that an with the order details and order ID be sent before the transaction is sent to the Realex application and another with the result sent afterwards. In this way, details of an order that someone has actually been charged for should not be lost. 10

11 4 Templates In order for the payment form to maintain the appearance of your website you will need to have a template page and (optionally) some images/style sheets etc. uploaded to the Realex Payments servers. This template should be sent to Realex support via (support@realexpayments.com). The basic structure of a template is shown below. Note the HTML comment that indicates where the payment form should be placed; this tag must be present in the template page. <html> <head> <title> Enter your credit card details. </title> </head> <body> more html <!--E-PAGE TABLE HERE--> more html </body> </html> The template should resemble the rest of the shopping experience so that the customer does not immediately realise that they have been redirected but, as a secure encrypted connection will be used, there should be as few images as possible. A typical template page consists of: a header image, a plaintext message for the customer and the required <!--E-PAGE TABLE HERE--> tag. Simply using the general colour scheme of the other pages in your shopping cart is quite effective. Below are the full requirements for the template page: Template pages must contain the payment form tag: <!--E-PAGE TABLE HERE--> 1. All images/css used in the template must be referred locally on our server. There should be no absolute URLs to external images/css. This means that you will need to send the image files to us along with the template page. 2. There can be no scripting of any kind in the template for security reasons. It should contain only basic HTML. 3. The name of the file must be: template.htm 4. All necessary files should be placed in a folder with the same name as the sub-account for which the template is intended (the default sub-account is always internet ). 4.1 Redirect Integration To link your shopping cart to the Realex Realauth application you must insert certain hidden fields into a form that redirects to the Realauth application over a secure link. The page that hosts this 11

12 script is know as the referring URL. This URL needs to be ed to to be added to the whitelist of referring URLs. The minimal implementation is shown below. <form method="post" action=" <input type="hidden" name="merchant_id" value="realex Payments merchant-id"> <input type="hidden" name="order_id" value="unique order-id"> <input type="hidden" name="account" value="sub account name"> <input type="hidden" name="amount" value="amount"> <input type="hidden" name="currency" value="currency code"> <input type="hidden" name="timestamp" value="yyyymmddhhmmss"> <input type="hidden" name="md5hash" value="32 character string"> <input type="hidden" name="auto_settle_flag" value="1 or 0"> <input type="submit" value="click here to Purchase"> </form> Note: Some form of server side programming is required to create the MD5HASH (or SHA1HASH). All merchants will be required to perform some script configuration on their side. 4.2 Redirect Request Field Definitions The fields in the table below are accepted by Realex Payments. Anything else will be returned back to your response script (if any) along with the Realex responses. The following indicators are used to show whether or not an element is required or optional. M O C Required for this request type Optional Required depending on another optional field Each field has certain constraints around length and format as per below (please note that "" means a space): Field Title Format Length R/O Field Description MERCHANT_ID a-z A-Z M Supplied by Realex note this is not the merchant number supplied by your bank. ACCOUNT a-z A-Z O The sub-account to use for this transaction. If not present, the default sub-account, internet, will be used. 12

13 Field Title Format Length R/O Field Description ORDER_ID a-z A-Z 0-9 _ M A unique alphanumeric id that s used to identify the transaction. This can be up to 40 characters long. No spaces are allowed AMOUNT M Total amount to authorise in the lowest unit of the currency i.e. 100 euro would be entered as If there is no decimal in the currency then (e.g. JPY Yen) then contact Realex Payments. No decimal points are allowed. CURRENCY a-z A-Z 3 M A three-letter code as per currency table in Appendix A. TIMESTAMP M Date and time of the transaction. Entered in the following format: yyyymmddhhmmss MD5HASH a-f M A digital signature generated using the MD5 algorithm. You have the option of using the MD5 hash or the SHA-1 hash (below). Realex prefer you use the SHA-1 hash as it is more secure. See section below on Digital Signatures. SHA1HASH a-f M A digital signature generated using the SHA-1 algorithm. Realex prefer that you use a SHA- 1 signature rather than an MD5. The MD5 option has been retained for compatibility with older systems. See section below on Digital Signatures. AUTO_SETTLE_ FLAG 0 or 1 1 M Used to signify whether or not you wish the transaction to be captured in the next batch or not. If set to 1 and assuming the transaction is authorised then it will automatically be settled in the next batch. If set to 0 then the merchant must use the realcontrol application to manually settle the transaction. This option can be used if a merchant wishes to delay the payment until after the goods have been shipped. Transactions can be settled for up to 115% of the original amount. COMMENT1 a-z A-Z 0-9 ' ", +. _ - & \ % ( ) * : $ & # [ ] = COMMENT2 a-z A-Z 0-9 ' ", +. _ - & \ % ( ) * : $ & # [ ] = O A freeform comment to describe the transaction. Up to 255 characters O A freeform comment to describe the transaction. Up to 255 characters 13

14 Field Title Format Length R/O Field Description RETURN_TSS 0 or 1 1 O Used to signify whether or not you want a Transaction Suitability Score for this transaction. Can be 0 for no and 1 for yes. To maximise the usefulness of the realscore you should also supply the next 6 fields. See below for more on realscore. SHIPPING_COD E a-z A-Z 0-9,. - / 0-30 O The postcode or ZIP of the shipping address. This can only have letters and digits. (ie no or /) SHIPPING_CO a-z A-Z 0-9, O The country of the shipping address. This can only have letters and digits. (ie no or /) BILLING_CODE a-z A-Z 0-9,. - / 0-30 O The postcode or ZIP of the billing address. This can only have letters and digits. (ie no or /) BILLING_CO a-z A-Z 0-9, O The country of the billing address. This field can only have letters and digits.. (ie no or /) CUST_NUM a-z A-Z 0-9 _., VAR_REF a-z A-Z 0-9 _., PROD_ID a-z A-Z 0-9 _., ANYTHING ELSE a-z A-Z 0-9 ' ", +. _ - & \ % ( ) * : $ & # [ ] = 0-50 O The customer number of the customer O A variable reference also associated with this customer O A product id associated with this product O Anything else you send to Realex Payments will be returned in the response (whatever other information you collected from the customer such as product or address/telephone numbers etc.) All of these field values (except for the MERCHANT_ID which will be provided by Realex Payments) are user definable. Merchants will need to contact Realex in order to set up new subaccounts. 4.3 Redirect Response Field Definitions Response data is sent back to your response script for each transaction. After the customer enters their credit card details on the Realex-hosted page, our application calls your response script with the response details. You can use this response to update your own database and send s to your customers based on the result of the transaction. In order to receive this data you must provide Realex Payments with the URL of your response script. The response URL is to be ed to support@realexpayments.com. This application must only 14

15 return text as output if image tags are included there will be a popup warning about mixed secure/insecure content on the page. The template that was used for the credit card entry table will be used again for this page. You should include a link that continues the customers shopping experience. Again, we can provide working sample code that will make this process easier. In the case of an error whereby the Realauth application is unable to contact your response script, you can set a static success/failure message. This can be changed in the administration section of Real Control. The response fields are as follows: Heading MERCHANT_ID ACCOUNT ORDER_ID AUTHCODE RESULT MESSAGE CVNRESULT PASREF BATCHID ECI CAVV XID MD5HASH SHA1HASH TSS TSS_idnum ANYTHING ELSE Heading This is the merchant id that Realex Payments assign to you. The sub-account used in the transaction. The unique order id that you sent to us. Will contain a valid authcode if the transaction was successful. Will be empty otherwise. The outcome of the transaction. Will contain 00 if the transaction was a success or another value (depending on the error) if not. See the result codes table in Appendix A. Will contain a text message that describes the result code above. The result of the Card Verification check (if enabled): M: CVV Matched. N: CVV Not Matched. I: CVV Not checked due to circumstances. U: CVV Not checked issuer not certified. P: CVV Not Processed. A unique reference that Realex Payments assign to your transaction. This is the Realex Payments batch that this transaction will be in. (This is equal to -1 if the transaction was sent in with the autosettle flag off. After you settle it (either manually or programmatically) the response to that transaction will contain the batch id.) This is the ecommerce indicator (this will only be returned for 3DSecure transactions). Cardholder Authentication Verification Value (this will only be returned for 3DSecure transactions). Exchange Identifier (this will only be returned for 3DSecure transactions). An MD5 digital signature created using the above fields and your shared secret. Needs to be sent in lowercase. A SHA-1 digital signature created using the above fields and your shared secret. Needs to be sent in lowercase. The Transaction Suitability Score for the transaction. The realscore is comprised of various distinct tests. Using the realcontrol application you can request that Realex Payments return certain individual scores to you. These are identified bynumbers - thus TSS_1032 would be the result of the check with id You can then use these specific checks in conjunction with realscore score to ascertain whether of not you wish to continue with the settlement. Anything else you sent to us in the request will be returned to you. 15

16 All of these field values (except for the MERCHANT_ID which will be provided by Realex) are user definable. Merchants will need to contact Realex in order to set up new sub-accounts. 4.4 Digital Signature for Redirect To ensure 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, and CURRENCY) using a shared secret. This can be an MD5 hash or preferably a SHA-1 hash. If required we can also provide code for this. MD5 and SHA-1 algorithms are secure hash functions. They take a string as input, and produce a fixed size number 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 is a sample request: <input type="hidden" name="merchant_id" value="thestore"> <input type="hidden" name="account" value="internet"> <input type="hidden" name="order_id" value="ord453-11"> <input type="hidden" name="amount" value="29900"> <input type="hidden" name="currency" value="eur"> <input type="hidden" name="timestamp" value=" "> <input type="hidden" name="auto_settle_flag" value="1"> To construct the hash follow this procedure: Form a string by concatenating the above fields with a period (. ) in the following order ( TIMESTAMP.MERCHANT_ID.ORDER_ID.AMOUNT.CURRENCY ) Like so: ( thestore.ORD EUR ) Get the hash of this string (SHA-1 shown below). (b3d51ca21db725f9c7f13f8aca9e0e2ec2f32502) It is important that you convert this to lowercase letters. SHA1 and MD5 will give different answers in the next step if you use uppercase letters. 16

17 Create a new string by concatenating this string and your shared secret using a period. (b3d51ca21db725f9c7f13f8aca9e0e2ec2f32502.mysecret ) Get the hash of this value. This is the value that you send to Realex Payments. (3c3cac74f2b783598b99af6e d95d1) <input type="hidden" name="sha1hash" value="3c3cac74f2b783598b99af6e d95d1"> When Realex receive the request, we perform the same procedure on the five pieces of information and your shared secret (which we have stored in our database). If the resulting hash is the same as the one that you sent us then the data could only have been sent by someone that had your shared secret. Thus it is very important to keep this shared secret protected. When Realex are responding, we will send you a hash of the response elements in the same way so that you can confirm that the response came from Realex Payments. (This will be a hash of the TIMESTAMP, MERCHANT_ID, ORDER_ID, RESULT, MESSAGE, PASREF and AUTHCODE with your secret key (see below for more on the Realex Payments response fields). If you sent us an MD5 hash you will receive an MD5 hash in the response and similarly for a SHA-1 hash). The response hash is constructed as follows: Form a string by concatenating the above fields with a period (. ) ( thestore.ORD Successful ) Get the hash of this string (SHA-1 shown below). (a111135ea464bcd343c0f23db395fa1cf12a6837) Create a new string by concatenating this string and your shared secret using a period. (a111135ea464bcd343c0f23db395fa1cf12a6837.mysecret) Get the hash of this value. This should be the same as the value you receive from Realex. (368df d47a21e b62b976339). 4.5 Address Verification Service: Redirect The Address Verification Service (AVS) verifies the cardholders address by checking the information provided by at the time of sale against the issuing bank's records Note: This service only works for UK cardholders as it uses the street address and postcodes of the cardholders. The Realauth redirect service supports AVS where it is supported by the merchant s 17

18 acquiring bank and the cardholder s issuing bank. If a transaction fails an AVS check it will not automatically be declined by your bank. It is an advisory service and requires that the details of non matched transactions be checked by the merchant. AVS data must be passed in the BILLING_CODE field. This data should be formatted as follows: <digits from postcode> <digits from address> For example, if the billing address is: 382, The Road The Town WB1 A42 UK The corresponding AVS data will be: <input type="hidden" name="billing_code" value=" "> The possible responses that can be returned for the Address Verification Service are as follows: M (Matched) N (Not Matched) I (Problem with check) U (Unable to check (not certified etc)) P (Partial Match) These will be returned in the following fields in the response: AVSADDRESSRESULT AVSPOSTCODERESULT 18

19 5 Realauth Remote Merchants should use Realauth remote if they have a secure server or if their site is hosted internally (such as an intranet application for a call centre a secure server isn t necessary in that case as the card numbers will never travel outside of the internal network). Remote can also be used if you are developing an application in Visual Basic or Java etc. (i.e. not a web application but a desktop application). Realex Payments can supply working sample code in Perl, Java, ASP, VB, PHP,.NET and server side JavaScript. Note: In certain circumstances the acquiring bank may need to approve your use of the Realauth remote option and it is entirely the merchants/developers responsibility to ensure that the acquiring bank has agreed and authorised the merchant in this regard. 5.1 Remote Example Realauth remote is ideal for any application that needs real time authorisation of credit cards. Information is sent between the merchant and Realex Payments in the form of XML messages. This service can be incorporated into any application that is capable of generating XML messages. 19

20 1. Once the full amount is known, the customer can be asked to enter their card details. These details are then sent to Realex as XML messages using a secure connection. A reply is then sent as an XML message back from Realex that contains the result of the transaction (approved/declined etc).# 20

21 2. The merchants application receives the response XML and extracts the information. It then displays the appropriate messages for the customer. One of the main advantages of the remote version is that the merchant can control the entire shopping experience. 5.2 Application Based Checking It is highly advisable to build in pre-authorisation checking for all data fields. This will eliminate many problems early on and rapidly improve response times. If any field contains an error, the transaction will fail. All mandatory fields must be included correctly and optional fields must contain valid data if included. Validation information can be found in Appendix C of this document. The following are some checks that should be put in place: Card expiry date should be checked. The date itself should be valid and formatted correctly. The card length should be 12,13,14,15,16,18 or 19 digits depending on the card type, no alpha characters should be included. (12 num_digits 19 will do). The card number should pass the Luhn check (see Appendix A) to ensure that it is a valid card number. 21

22 There should be at least two words in the cardholder's name (this is recommended but will not cause transactions to fail) and it must contain no unusual characters. If CVN checking is to be enforced the corresponding value for the presind field will need to be set. The possible values are listed in the XML definitions guide. The CVN itself will need to be sent in correctly. It should be 3 or 4 digits depending on the card type. Illegal characters cannot be present in any field. Each field should be checked to ensure that this is not the case as illegal characters cause the transaction to fail. The allowed characters for all fields are detailed in the XML definitions guide and in Appendix C - Data Validation Rules. 5.3 Remote Integration Full details of the XML messages for each request type can be found in the Realauth XML definitions guide, which is available from the online resource centre or by ing support@realexpayments.com. You will need to consult this guide in order to successfully complete a remote integration. Realex Payments can supply sample code to aide with integration, however this is sample code only and will need to be modified to suit individual merchants needs. The sample code will provide guidance on how to carry out the steps required for a remote transaction to succeed. These steps are: Create the XML message for the request. Connect to Realauth ( Send the message. Wait for Realex to reply with XML. Parse the reply and provide access to the information. 5.4 Remote Request Message Although the sample code available provides a simple interface to the system, more complex implementations will require some knowledge of how the system works. Again, the Realauth XML definitions guide should be consulted for full details on the messages required. Below is a sample of an auth request followed by a line-by-line analysis. The auth request is the primary request used with realauth. <request timestamp=" " type="auth"> <merchantid>yourmerchantid</merchantid> <account>account to use</account> <orderid>order id</orderid> <amount currency="eur">2000</amount> 22

23 <card> <number> </number> <expdate>0403</expdate> <chname>john Doe</chname> <type>mc</type> <issueno></issueno> <cvn> <number>453</number> <presind>1</presind> </cvn> </card> <autosettle flag="1" /> <comments> <comment id="1">a comment</comment> <comment id="2">another comment</comment> </comments> <tssinfo> <custnum>customer number</custnum> <prodid>product id</prodid> <varref>variable reference</varref> <custipaddress> </custipaddress> <address type="billing"> <code>zip/postal code</code> <country>country</country> </address> <address type="shipping"> <code>zip/postal code</code> <country>country</country> </address> </tssinfo> <sha1hash>4dc4f20acc a1bc</sha1hash> <md5hash>67dcc </md5hash> </request> The following indicators are used to show whether or not an element is required or optional. Each field has certain constraints around length and format as per below (please note that means a space): Line per line description M/O/ Format Length Details <request M Top-level element. Must have timestamp=" timestamp and type attributes. If " the timestamp is more than a day type="auth"> (86400 seconds) away from the server time then the request is <merchantid>mer chant id used</ merchantid> <account>accoun t used</account> <orderid>order id</orderid> <amount currency="eur">2000 </amount> rejected. M a-z A-Z This is your realex payments assigned merchant id O a-z A-Z This is the realex payments subaccount to use. If you omit this element then we will use your default account. M M a-z A-Z 0-9 _ - a-z A-Z The unique order id of this transaction. Must be unique across all of your accounts The currency and amount of the transaction. Appendix B - Codes on page 35 of the realauth developer's guide specifies the currency codes. The amount should be in thesmallest 23

24 Line per line description M/O/ Format Length Details unit of the required currency (i.e = 20, $20 or 20) <card> M There must be a card element in auth requests <number> M The card number </number> <expdate>0403</expd ate> M The card expiry date. The format is mmyy. <chname>john Doe</chname> M a-z A-Z "", ' +. _ - ; & \ / The card holder's name. <type>mc</type> M See Details The card type. The legal values are: VISA, MC, LASER, SWITCH, AMEX, DINERS, UATP <issueno></issueno> M The issue number of the card in the case of a Switch card. Only required if the card type is SWITCH <cvn> O The card verification details element. If you use this then the next two elements are required. <number>453</number > <presind>1</presind > </cvn> </card> <autosettle flag="1" /> <recurring type="variable" sequence="first" /> M The Card Verification Number. This is the 3 digit number on the reverse of the card. (the CVC for VISA and the CVV2 for MasterCard) 3 digits on Visa and MC, 4 digits on Amex. M See Details 1 This is the presence indicator. It can take 4 values: 1: cvn present 2: cvn illegible 3: cvn not on card 4: cvn not requested M M M See Details The auto-settle indicator. If "1" then the transaction is sent to the bank for settlement tonight. If set to "0" then the transaction sits in the realex payment's database until someone manually submits it for settlement. C See Details If you are configured for recurring/continuous authority transactions, you must set these 24

25 Line per line description M/O/ Format Length Details fields. type can be either fixed or variable depending on whether you will be changing the amounts or not. sequence must be first for the first transaction for this card, subsequent for transactions after that, and last for the final transaction of the set. Only supported by some acquirers. <comments> O You can associate up to 2 comments with any transaction for your own purposes. <comment id="1">a comment</ comment> <comment id="2">a comment</ comment> O O a-z A-Z 0-9 ' ", + "". _ - & \ % ( ) * : $ & # [ ] = a-z A-Z 0-9 ' ", + "". _ - & \ % ( ) * : $ & # [ ] = Free-text comment Free-text comment </comments> O <tssinfo> O As part of the realex payment's service we offer a realscore. This is a real time transaction screening and data checking system to assist the merchant with the identification of potentially high-risk transactions. <custnum>customer number</custnum> <prodid>product id</prodid> <varref>variable reference</ varref> <custipaddress> </custipaddress> O a-z A-Z "" _., O a-z A-Z "" _., O a-z A-Z "" _., O 0-9 IP Address in X.X.X.X format O <address type="billing"> <code>zip postal O a-z A-Z 0-9 "", 0-50 The number you assign to the customer. This can allow checking of previous transactions by this customer The product code you assign to the product Any reference you also would like to assign to the customer. This can allow checking, using realscore, of previous transactions by this customer. [1-3].{1- The IP address of the customer. 3}.{1-3}.{1-3} The billing address of the customer The ZIP Postal code of the billing 25

26 Line per line description M/O/ Format Length Details code</code>. - / address. This can be checked (in conjunction with the country) against a table of highrisk area codes. This field is used address verification with certain acquirers. <country>country</c ountry> </address> <address type="shipping"> <code>zip postal code</code> <country>country</c ountry> </address> </tssinfo> <sha1hash>7384 ae67...ac7d7d</ sha1hash> <md5hash>34e7....a77d</ md5hash> </response> O a-z A-Z 0-9 "",. - O O a-z A-Z 0-9 "",. - / O a-z A-Z 0-9 "", The country of the billing address. This can be checked against a table of highrisk countries. The shipping address of the customer The ZIP Postal code of the shipping address. This can be checked (in conjunction with the country) against a table of highrisk area codes The country of the shipping address. This can be checked against a table of high-risk countries. M a-f The SHA-1 hash of certain elements of the request. The details of this are to be found in the realauth developer's guide. Either this or the MD5 may be used. M a-f The MD5 hash of certain elements of the request. The details of this are to be found in the realauth developer's guide. 5.5 Remote Response Message The full version of the response is shown below, followed by the short version and a lineby- line description. Response Format - Long Version <response timestamp=" "> <merchantid>yourmerchantid</merchantid> <account>account to use</account> <orderid>order id from request</orderid> <authcode>authcode received</authcode> <result>00</result> <message>message returned from system</message> <pasref>realex payments reference</pasref> 26

27 <cvnresult>m</cvnresult> <batchid>batch id for this transaction (if any)</batchid> <cardissuer> <bank>issuing Bank Name</bank> <country>issuing Bank Country</country> <countrycode>issuing Bank Country Code</countrycode> <region>issuing Bank Region</region> </cardissuer> <tss> <result>89</result> <check id="1000">9</check> <check id="1001">9</check> </tss> <sha1hash>7384ae67...ac7d7d</sha1hash> <md5hash>34e7...a77d</md5hash> </response> Response Format - Short Version <response timestamp=" "> <result>508</result> <message>message returned from system</message> </response> The following indicators are used to show whether or not an element is required or optional. Each field has certain constraints around length and format as per below (please note that means a space): Line per line description M/O/ Format Length Details <response M Top-level element. Must have timestamp=" timestamp and type attributes. If "> the timestamp is more than a day (86400 seconds) away from the server time then the request is <merchantid>mer chant id used</ merchantid> <account>accoun t used</account> <orderid>order id</orderid> <authcode>authc ode received</ authcode> <result>00</ result> <message>messa ge returned from system</ message> rejected. M a-z A-Z This is your realex payments assigned merchant id O a-z A-Z This is the realex payments subaccount to use. If you omit this element then we will use your default account. M a-z A-Z 0-9 _ - M a-z A-Z The unique order id of this transaction. Must be unique across all of your accounts If successful an authcode is returned from the bank. Used when referencing this transaction in refund and void requests. M The result codes returned by the Realex Payments system. M a-z A-Z The text of the response. Contains 9 ' ", + "" the authcode if successful or the. _ - & \ / error message if % ( ) * : $ & 27

28 Line per line description M/O/ Format Length Details # [ ] = <pasref> realex M a-z A-Z The Realex payments reference payments 9 for the transaction. Used when reference</ referencing this transaction in pasref> <cvnresult>m</ cvnresult> <batchid>batch id</batchid> M See Details refund and void requests. 1 The result of the Card Verification check: M: CVV Matched N: CVV Not Matched I: CVV Not checked due to circumstances U: CVV Not checked - issuer not certified P: CVV Not Processed M The batch id of the transaction. Returned in the case of auth and refund requests. This can be used to assist with the reconciliation of your batches. <cardissuer> M The Details of the cardholder's bank (if available) <bank>issuing M a-z A-Z The Bank Name (e.g. First Data Bank Name</ 9 _ bank> Bank) <country>issuing Bank Country</ country> <countrycode>iss uing Bank Co Code</ countrycode> <region>issuing Bank Region</ region> M a-z A-Z 0-9 "", The Bank Country in English (e.g. UNITED STATES) M a-z A-Z 2 The country code of the issuing bank (e.g. US) M a-a A-Z 0-9 / 0-20 The region the card was issued (e.g. US) Can be MEA (Middle East/Asia), LAT (Latin America), US (United States), EUR (Europe), CAN (Canada), A/P (Asia/Pacific) </cardissuer> M <tss> O The results of realscore <result>67</ result> <check id="xxxx">9</ check> <sha1hash>7384 ae67...ac7d7d</ sha1hash> <md5hash>34e7....a77d</ md5hash> M The weighted total score of realscore. You may adjust the weights in the realcontrol application. M The result of realscore check number xxxx. You can choose which checks to return using the realcontrol application. M a-f The SHA-1 hash of certain elements of the response. The details of this are to be found in the realauth developer's guide M a-f The MD5 hash of certain elements of the response. The details of this are to be found in the realauth developer's guide. 28

29 Line per line description M/O/ Format Length Details </response> 5.6 Digital Signatures for Remote To ensure authentication (that the request comes from you) we require that you send us a hash of certain elements (specifically the timestamp, merchant id, order id, amount, currency and card number) using a shared secret. This can be a MD5 hash or preferably a SHA-1 hash. If required we can also provide code for this. MD5 and SHA-1 algorithms are secure hash functions. They take a string as input, and produce a fixed size number 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="auth"> <merchantid> thestore </merchantid> <account> theaccount </account> <orderid> ORD </orderid> <amount currency="eur"> </amount> <card> <number> </number> <expdate> 0302 </expdate> <chname> John Smith </chname> <type> VISA </type> </card> To construct the hash follow this procedure: Form a string by concatenating the above fields with a period (. ) ( thestore.ORD EUR ) Get the hash of this string (SHA-1 shown below). (f7fa584d2f8d642c1a17e9ead6061e8beeffe308) Create a new string by concatenating this string and your shared secret using a period. (f7fa584d2f8d642c1a17e9ead6061e8beeffe308.mysecret ) Get the hash of this value. This is the value that you send to Realex Payments. ( e5f1d2aba5cad67ff5108ad3ff1d56c32) 29

30 <sha1hash> e5f1d2aba5cad67ff5108ad3ff1d56c32 </sha1hash> When Realex Payments receive the request, we perform the same procedure on the six pieces of information and your shared secret (which we have stored in our database) If the resulting hash is the same as the one that you sent us then the data could only have been sent by someone that had your shared secret. Thus it is very important to keep this shared secret protected. We will send you a hash of the response elements in the same way so that you can confirm that the response came from Realex. This will be a hash of the TIMESTAMP, MERCHANT_ID, ORDER_ID, RESULT, MESSAGE, PASREF and AUTHCODE. This will be combined with your shared secret in the same way as the request hash. If you sent us an MD5 hash you will receive an MD5 hash in the response and similarly for a SHA-1 hash). The response hash is constructed as follows: Form a string by concatenating the above fields with a period (. ) ( thestore.ORD Successful ) Get the hash of this string (SHA-1 shown below). (a111135ea464bcd343c0f23db395fa1cf12a6837) Create a new string by concatenating this string and your shared secret using a period. (a111135ea464bcd343c0f23db395fa1cf12a6837.mysecret) Get the hash of this value. This is the value that you send to Realex Payments. (368df d47a21e b62b976339). 5.7 Address Verification Service The Address Verification Service (AVS) verifies the cardholders address by checking the information provided by at the time of sale against the issuing bank's records. Note: This service only works for UK cardholders as it uses the street address and postcodes of the cardholders. The Realauth remote service supports AVS where it is supported by the merchants acquiring bank and the cardholders issuing bank.if a transaction fails an AVS check it will not automatically be declined by your bank. It is an advisory service and requires that the details of non matched be checked by the merchant. AVS data must be passed in the billing code field. This data should be formatted as follows: 30

31 <digits from postcode> <digits from address> For example, if the billing address is: 382, The Road The Town WB1 A42 UK The corresponding AVS data will be: <address type='billing> <code> </code> </addresss> The possible responses that can be returned for the Address Verification Service are as follows: M (Matched) N (Not Matched) I (Problem with check) U (Unable to check (not certified etc)) P (Partial Match) These will be returned in the following XML tags in the response: <avspostcoderesponse></avspostcoderesponse> <avsaddressresponse></avsaddressresponse> 31

32 6 Steps Required To Go Live All accounts remain in test mode until it is specifically requested to switch the account live. This request must come from the billing or commercial contact for the account. Before live cards can be processed you will also need to provide Realex with a bank merchant number by to support@realexpayments.com. This number references an Internet Merchant Service Agreement (MSA), which you must set up with your acquiring bank. For information on how to obtain a MSA, please visit: Once you have requested the system to go live and have provided your merchant number, please allow 24 hours for the account to be fully enabled. When the account has been fully set live the merchant will be advised of this by Realex Payments support. At this point the merchant should attempt a number of live transactions to ensure that the integration has been completed successfully. The main steps involved in setting an account live are summarised below: 1. Secure merchant service agreement with acquiring bank. 2. Provide merchant numbers to Realex via Integrate website/application with Realex service. 4. Conduct testing using approved test card numbers to confirm successful integration. 5. Contact Realex payments and request account be set live. 6. Receive confirmation that account is live from Realex support. 7. Process live transactions. If further testing is required after an account has been set live it is still possible to send transactions to the test environment. This can be done by appending test to the name of the sub-account specified in the ACCOUNT field. For example, where the sub-account is called internet the test transaction would use internettest. 32

33 7 Appendix A Sample Code 7.1 Luhn check Below is code in JavaScript that carries out Luhn checking on all card numbers. Code in other languages is widely available on the internet. var number = " "; var i, sum, weight; sum=0; for (i = 0; i < number.length - 1; i++) { weight = number.substr(number.length - (i + 2), 1) * (2 - (i % 2)); sum += ((weight < 10)? weight : (weight - 9)); } if (parseint(number.substr(number.length-1)) == ((10 - sum % 10) % 10)) { return true; } else { alert("card Number Fails LUHN Test"); return false; } In brief, the Luhn check is used to validate numbers such as credit cards, account numbers, and social security numbers. It works like this: 1. Double the value of every second digit beginning with the second-last right-hand digit. 2. Add the individual digits comprising the products obtained in step 1 to each of the other digits in the original number. 3. Subtract the total obtained in step 2 from the next higher number ending in This number should be the same as the last digit (the check digit). If the total obtained in step 2 is a number ending in zero (30, 40 etc.), the check digit is 0. For example: credit card number x2 x2 x2 x2 x2 x2 x2 x = = 5 (correct) 33

34 8 Appendix B Codes 8.1 Currency Codes EUR GBP USD SEK CHF HKD JPY Euro Pound Sterling US Dollar Swedish Krona Swiss Franc Hong Kong Dollar Japanese Yen (Further codes available on request) 8.2 Card Types VISA MC SWITCH AMEX LASER DINERS Visa/Delta Mastercard Switch/Solo American Express Laser Diners 34

35 9 Response Codes The Table below details the current set of result codes returned by the Realex Payments system. Additions and changes to the specific text of these messages can occur without notice! The best practise is to treat the codes in the following manner. Code Description 00 Successful the transaction has processed and you may proceed with the sale. 1xx A failed transaction. You can treat any 1xx code as a failed transaction and inform your customer that they should either try again or try another payment method. If you wish you may provide alternate flows based on the specific codes as follows: 101 Declined by Bank generally insufficient funds or incorrect expiry date. 102 Referral by Bank (treat as decline in automated system such as internet) 103 Card reported lost or stolen 107 Your fraud checks blocked the transaction. 1xx Other reason, rare. Treat as a decline like xx 3xx 5xx Error with bank systems generally you can tell the customer to try again later. The resolution time depends on the issue. Error with Realex Payments systems generally you can tell the customer to try again later. The resolution time depends on the issue. Incorrect XML message formation or content. These are either development errors, configuration errors or customer errors. There is a large list below, but in general: 508 Development issue check the message and correct your integration. 509 Customer issue check the message and ask the customer to confirm their payment details and try again. 5xx Configuration issue check the message. You may need to contact Realex support to fix these issues. 666 Client deactivated your Realex account has been suspended. Contact Realex support for further information. 9.1 Country Codes Certain realscore checks require you to submit the country as data to be checked against. To ensure that the country names we use are the same, Realex Payments use the following ISO country codes. The common use of these is in a dropdown list from which the customer can select their billing and shipping countries. 35