RealAuth Developers Guide Version: 4.9
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 324929. 2000 2014 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 Introduction 6 2.1 The Redirect Method 6 2.2 The Remote Method 6 2.3 Realauth Redirect Features List 6 2.4 Remote Features List 6 2.5 Sub-Accounts 7 3 Realauth Redirect 8 3.1 Redirect Example 8 4 Templates 11 4.1 Redirect Integration 11 4.2 Redirect Request Field Definitions 12 4.3 Redirect Response Field Definitions 14 4.4 Digital Signature for Redirect 16 4.5 Address Verification Service: Redirect 17 5 Realauth Remote 19 5.1 Remote Example 19 5.2 Application Based Checking 21 5.3 Remote Integration 22 5.4 Remote Request Message 22 5.5 Remote Response Message 26 5.6 Digital Signatures for Remote 29 5.7 Address Verification Service 30 6 Steps Required To Go Live 32 7 Appendix A Sample Code 33 7.1 Luhn check 33 8 Appendix B Codes 34 8.1 Currency Codes 34 8.2 Card Types 34 9 Response Codes 35 9.1 Country Codes 35 10 Appendix C - Data Validation Rules 41 11 Appendix D - Realex Guides 42 3
1 About This Guide This section outlines the purpose and aim of the guide, target audience, any source materials or terminology used, and a general document description. Please note that this document is regarded as confidential and is for customer use only. It has been supplied under the conditions of your payment-processing contract. 1.1 Purpose The purpose of this guide is to 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
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
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
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
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
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
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 email 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 email with the order details and order ID be sent before the transaction is sent to the Realex application and another email with the result sent afterwards. In this way, details of an order that someone has actually been charged for should not be lost. 10
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 e-mail (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
script is know as the referring URL. This URL needs to be emailed to support@realexpayments.com to be added to the whitelist of referring URLs. The minimal implementation is shown below. <form method="post" action="https://epage.payandshop.com/epage.cgi"> <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 0-9. 1-50 M Supplied by Realex note this is not the merchant number supplied by your bank. ACCOUNT a-z A-Z 0-9 0-30 O The sub-account to use for this transaction. If not present, the default sub-account, internet, will be used. 12
Field Title Format Length R/O Field Description ORDER_ID a-z A-Z 0-9 _ - 0-40 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 0-9 2-11 M Total amount to authorise in the lowest unit of the currency i.e. 100 euro would be entered as 10000. 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 0-9 14 M Date and time of the transaction. Entered in the following format: yyyymmddhhmmss MD5HASH a-f 0-9 32 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 0-9 40 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 ' ", +. _ - & \ / @!? % ( ) * : $ & # [ ] = 0-255 O A freeform comment to describe the transaction. Up to 255 characters 0-255 O A freeform comment to describe the transaction. Up to 255 characters 13
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,. - 0-30 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,. - 0-30 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. 0-50 O A variable reference also associated with this customer. 0-50 O A product id associated with this product. 0-255 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 emails 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 emailed to support@realexpayments.com. This application must only 14
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 1032. 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
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 - 128 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="20120926112654"> <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: ( 20120926112654.thestore.ORD453-11.29900.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
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. (3c3cac74f2b783598b99af6e43246529346d95d1) <input type="hidden" name="sha1hash" value="3c3cac74f2b783598b99af6e43246529346d95d1"> 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 (. ) (20120926112654.thestore.ORD453-11.00.Successful.3737468273643.79347) 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. (368df010076481d47a21e777871012b62b976339). 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
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="142 382"> 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
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
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
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
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 e-mailing 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 (https://epage.payandshop.com/epage-remote.cgi). 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="20120926112654" type="auth"> <merchantid>yourmerchantid</merchantid> <account>account to use</account> <orderid>order id</orderid> <amount currency="eur">2000</amount> 22
<card> <number>490303400005718902</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>1.2.3.4</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.30314758a1bc</sha1hash> <md5hash>67dcc.787307</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 0-9 14 Top-level element. Must have timestamp="20120926 timestamp and type attributes. If 112654" 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 0-9. 1-50 This is your realex payments assigned merchant id O a-z A-Z 0-9 0-30 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 0-9 1-40 The unique order id of this transaction. Must be unique across all of your accounts. 3 2-11 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
Line per line description M/O/ Format Length Details unit of the required currency (i.e. 2000 = 20, $20 or 20) <card> M There must be a card element in auth requests <number>49030340000 M 0-9 12-19 The card number. 5718902 </number> <expdate>0403</expd ate> M 0-9 4 The card expiry date. The format is mmyy. <chname>john Doe</chname> M a-z A-Z 0-9 - + "", ' +. _ - ; & \ / 1-100 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 0-9 0-3 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 0-9 3-4 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
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 ' ", + "". _ - & \ / @!? % ( ) * : $ & # [ ] = 0-255 Free-text comment 0-255 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>1.2. 3.4 </custipaddress> O a-z A-Z 0-9 - "" _., + @ O a-z A-Z 0-9 - "" _., + @ O a-z A-Z 0-9 - "" _., + @ 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. 0-50 The product code you assign to the product. 0-50 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. 0-30 The ZIP Postal code of the billing 25
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 "",. - 0-30 The country of the billing address. This can be checked against a table of highrisk countries. The shipping address of the customer. 0-30 The ZIP Postal code of the shipping address. This can be checked (in conjunction with the country) against a table of highrisk area codes. 0-30 The country of the shipping address. This can be checked against a table of high-risk countries. M a-f 0-9 40 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 0-9 32 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="20120926112654"> <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
<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="20120926112654"> <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 0-9 14 Top-level element. Must have timestamp="20120926 timestamp and type attributes. If 112612"> 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 0-9. 1-50 This is your realex payments assigned merchant id O a-z A-Z 0-9 0-30 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 0-9 1-40 The unique order id of this transaction. Must be unique across all of your accounts. 0-10 If successful an authcode is returned from the bank. Used when referencing this transaction in refund and void requests. M 0-9 0-3 The result codes returned by the Realex Payments system. M a-z A-Z 0-0-100 The text of the response. Contains 9 ' ", + "" the authcode if successful or the. _ - & \ / error message if not. @!? % ( ) * : $ & 27
Line per line description M/O/ Format Length Details # [ ] = <pasref> realex M a-z A-Z 0-0-50 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 0-9 0-20 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 0-0-30 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 "",. - 0-30 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 0-9 0-3 The weighted total score of realscore. You may adjust the weights in the realcontrol application. M 0-9 0-9 4 1 The result of realscore check number xxxx. You can choose which checks to return using the realcontrol application. M a-f 0-9 40 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 0-9 32 The MD5 hash of certain elements of the response. The details of this are to be found in the realauth developer's guide. 28
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 - 128 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="20120926112612" type="auth"> <merchantid> thestore </merchantid> <account> theaccount </account> <orderid> ORD453-11 </orderid> <amount currency="eur"> 29900 </amount> <card> <number> 5105105105105100 </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 (. ) ( 20120926112654.thestore.ORD453-11.29900.EUR.5105105105105100 ) 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. (1537570e5f1d2aba5cad67ff5108ad3ff1d56c32) 29
<sha1hash> 1537570e5f1d2aba5cad67ff5108ad3ff1d56c32 </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 (. ) ( 20120926112654.thestore.ORD453-11.00.Successful.3737468273643.79347) 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. (368df010076481d47a21e777871012b62b976339). 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
<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>142 382</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
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 email 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: http://www.realexpayments.com/en/where_to_get_a_merchant_services_agreement.aspx 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 email. 3. 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
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 = "4444333322221111"; 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 0. 4. 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 3648455485235855 3 6 4 8 4 5 5 4 8 5 2 3 5 8 5 5 x2 x2 x2 x2 x2 x2 x2 x2 6 6 8 8 8 5 10 4 16 5 4 3 10 8 10 6+6+8+8+8+5+1+0+4+1+6+5+4+3+1+0+8+1+0 = 75 80 75 = 5 (correct) 33
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
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 101. 2xx 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 3166-1 country codes. The common use of these is in a dropdown list from which the customer can select their billing and shipping countries. 35
Code AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AZ BA BB BD BE BF BG BH BI BJ BM BN BO BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU Country ANDORRA UNITED ARAB EMIRATES AFGHANISTAN ANTIGUA AND BARBUDA ANGUILLA ALBANIA ARMENIA NETHERLANDS ANTILLES ANGOLA ANTARTICA ARGENTINA AMERICAN SAMOA AUSTRIA AUSTRALIA ARUBA AZERBAJAN BOSNIA AND HERZEGOVINA BARBADOS BANGLADESH BELGIUM BURKINA FASO BULGARIA BAHRAIN BURUNDI BENIN BERMUDA BRUNEI DARUSSALAM BOLIVIA BRAZIL BAHAMAS BHUTAN BOUVET ISLAND BOTSWANA BELARUS BELIZE CANADA COCOS (KEELING) ISLANDS CONGO, DEMOCRATIC REPUBLIC OF CENTRAL AFRICAN REPUBLIC CONGO SWITZERLAND COTE D IVOIRE COOK ISLANDS CHILE CAMEROON CHINA COLUMBIA COSTA RICA CUBA 36
CV CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IN IO CAPE VERDE CHRISTMAS ISLAND CYPRUS CZECH REPUBLIC GERMANY DJIBOUTI DENMARK DOMINICA DOMINICAN REPUBLIC ALGERIA ECUADOR ESTONIA EGYPT WESTERN SAHARA ERITREA SPAIN ETHIOPIA FINLAND FIJI FALKLAND ISLANDS (MALVINAS) MICRONESIA, FEDERATED STATES OF FAROE ISLANDS FRANCE GABON UNITED KINGDOM GRENADA GEORGIA FRENCH GUIANA GHANA GIBRALTAR GREENLAND GAMBIA GUINEA GUADELOUPE EQUATORIAL GUINEA GREECE SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS GUATEMALA GUAM GUINEA-BISSAU GUYANA HONG KONG HEARD ISLAND AND MCDONALD ISLANDS HONDURAS CROATIA HAITI HUNGRAY INDONESIA IRELAND ISRAEL INDIA BRITISH INDIAN OCEAN TERRITORY 37
IQ IR IS IT JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC IRAQ IRAN, ISLAMIC REPUBLIC OF ICELAND ITALY JAMAICA JORDAN JAPAN KENYA KYRGYZTAN CAMBODIA KIRIBATI COMOROS ST. KITTS AND NEVIS KOREA, DEMOCRATIC PEOPLE S REPUBLIC OF KOREA, REPUBLIC OF KUWAIT CAYMAN ISLANDS KAZAKSTAN LAO PEOPLE S DEMOCRATIC REPUBLIC LEBANON ST. LUCIA LIECHTENSTEIN SRI LANKA LIBERIA LESOTHO LITHUANIA LUXEMBOURG LATVIA LIBYA MOROCCO MONACO MOLDOVA, REPUBLIC OF MADAGASCAR MARSHALL ISLANDS MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF MALI MYANMAR MONGOLIA MACAU NORTHERN MARIANA ISLANDS MARTINIQUE MAURITANIA MONTSERRAT MALTA MAURITIUS MALDIVES MALAWI MEXICO MALAYSIA MOSAMBIQUE NAMIBIA NEW CALEDONIA 38
NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR ST SV SY SZ TC TD TF NIGER NORFOLK ISLAND NIGERIA NICARAGUA NETHERLANDS NORWAY NEPAL NAURU NIUE NEW ZEALAND OMAN PANAMA PERU FRENCH POLYNESIA PAPUA NEW GUINEA PHILIPPINES PAKISTAN POLAND ST. PIERRE AND MIQUELON PITCAIRN PUERTO RICO PALESTINIAN TERRITORY, OCCUPIED PORTUGAL PALAU PARAGUAY qatar REUNION ROMANIA RUSSIA FEDERATION RWANDA SAUDI ARABIA SOLOMON ISLANDS SEYCHELLES SUDAN SWEDEN SINGAPORE ST. HELENA SLOVENIA SVALBARD AND JAN MAYEN SLOVAKIA SIERRA LEONE SAN MARINO SENEGAL SOMALIA SURINAME SAO TOME AND PRINCIPE EL SALVADOR SYRIAN ARAB REPUBLIC SWAZILAND TURKS AND CAICOS ISLANDS CHAD FRENCH SOUTHERN TERRIOTORIES 39
TG TH TJ TK TM TN TO TP TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT YU ZA ZM ZW TOGO THAILAND TAJIKISTAN TOKELAU TURKMENISTAN TUNISIA TONGA EAST TIMOR TURKEY TRINIDAD UND TOBAGO TUVALU TAIWAN TANZANIA, UNITED REPUBLIC OF UKRAINE UGANDA UNITED STATES MINOR OUTLYING ISLANDS UNITED STATES URUGUAY UZBEKISTAN HOLY SEE (VATICAN CITY STATE) ST. VINCENT AND THE GRENADINES VENEZUELA VIRGIN ISLANDS, BRITISH VIRGIN ISLANDS, USA VIETNAM VANUATU WALLIS AND FUTUNA SAMOA YEMEN MAYOTTE YUGOSLAVIA SOUTH AFRICA ZAMBIA ZIMBABWE 40
10 Appendix C - Data Validation Rules Field Valid Data Comments Merchant ID a-z A-Z 0-9 Realex Payments assigned Account a-z A-Z 0-9 Realex Payments assigned Order ID a-z A-Z 0-9 - _ Max 50 characters Amount 0-9 No decimal point Currency A-Z a-z See Currency Codes Timestamp 0-9 Must be a legal timestamp, 14 digits long in the form yyyymmddhhmmss and within 24 hours of the current time. SHA1Hash/MD5Hash a-f 0-9 40 or 32 digits Autosettle Flag 0 or 1 Billing Code a-z A-Z 0-9 Billing Country a-z A-Z 0-9 Should be taken from the Error! Reference source ot found. if you are using the realscore checks Shipping Code a-z A-Z 0-9 Shipping Country a-z A-Z 0-9 Should be taken from the Error! Reference source ot found. if you are using the realscore checks Customer Number a-z A-Z 0-9 - _ Max 50 characters Variable Reference a-z A-Z 0-9 - _ Max 50 characters Product ID a-z A-Z 0-9 - _ Max 50 characters Comments a-z A-Z 0-9 - _ Max 255 characters Card type a-z A-Z See Card Types. Cardnumber 0-9 Must pass Luhn check, and be properly matched with the card type. Cardholder name See note. Max 50 characters. Most 506 errors (malformed XML error) that you will receive will be because the cardholder has funny characters in their name. These characters (e.g. ß, or ä) are encoded using the ISO-8859-1 standard and not UTF-8 (which is the default for the parser used by Realex Payments). Therefore you should ensure that the encoding set in the top line of the XML you send to Realex Payments is correct. In most cases ISO-8859-1 will suffice but as more and more international customers use your site, Unicode (or UTF-8) encoding may be encountered (which allows for many more characters such as Japanese or Hebrew words). Further information will follow as the UTF-8 standard is finalised. Issue Number 0-9 0, 1, or 2 digits only SWITCH cards Expiry Date 0-9 4 digits, mmyy, valid (i.e. 4598 is illegal) 41
11 Appendix D - Realex Guides Title Target Description Realauth XML Definitions Guide Developers This guide provides details of the XML messages required for each type of transaction. This will be required for any remote integration. RealMPI Redirect Guide Merchants RealMPI is the 3DSecure service available through Realex. Realex will carry out the integration work for redirect implementations, so this guide provides an overview of the service with fewer technical details. RealMPI Remote Guide Developers For remote implementations of RealMPI there will be some development work required by the merchant. This guide provides the technical details needed by developers. RealEFT Developers Guide All RealEFT is the direct debit and recurring credit card payment service provided by Realex. This guide provides both the details needed to complete integration along with an overview of how the service works and so is useful to both merchants and developers. Recurring Payments Guide All Realex also provide a recurring payments solution. This allows merchants to raise payments by storing card details on our secure servers and then passing a reference in the place of the card number. This guide provides both an overview and the details required to integrate the service. RealFX Guide Developers RealFX is the Dynamic Currency Conversion service provided by Realex. DCC allows merchants to provide customers with the option of making purchases in their native currency, with exchange rates retrieved in real time. 42
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, Dublin 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 43