Realauth Developer s Guide Version 3.0.1

Transcription

1 Realauth Developer s Guide Version 3.0.1

2 Table of Contents INTRODUCTION TO REALEX PAYMENTS REALEX SERVICES REALAUTH SCENARIOS Sub-Accounts REALAUTH REDIRECT REDIRECT EXAMPLE TEMPLATES REDIRECT INTEGRATION REDIRECT REQUEST FIELD DEFINITIONS REDIRECT RESPONSE FIELD DEFINITIONS DIGITAL SIGNATURE FOR REDIRECT REALAUTH REMOTE REMOTE EXAMPLE APPLICATION BASED CHECKING REMOTE INTEGRATION Sample Java Code Sample ASP Code Sample Perl Code REMOTE REQUEST MESSAGE REMOTE RESPONSE MESSAGE DIGITAL SIGNATURES FOR REMOTE STEPS REQUIRED TO GO LIVE...30 APPENDIX A SAMPLE CODE...31 LUHN CHECK APPENDIX B CODES...32 CURRENCY CODES CARD TYPES RESPONSE CODES COUNTRY CODES APPENDIX C DATA VALIDATION RULES...39 APPENDIX D REALEX GUIDES...40 APPENDIX E VERSION CONTROL...41 Page 2 - Version 3.0.0

3 Introduction to Realex Payments Thank you for your interest in our service. Realex Payments build and manage payment exchanges for businesses, merchants and banks. We provide a range of real time services in the area of card authorisation, fraud scoring, electronic funds transfer, foreign exchange, reporting and reconciliation tools and payer authentication. Certified and approved by many leading financial institutions, these services are designed to eliminate overhead for banks and merchants selling in call/contact centres or via the internet. We may be contacted by any of the following methods: Address Castlecourt, Monkstown Farm, Monkstown, Co Dublin, Ireland Telephone (0) Fax (0) Sales [email protected] Support [email protected] Web Site Please note that this document is regarded as confidential and it is for customer use only. It has been supplied under the conditions of your payment-processing contract. Pay and Shop Limited, trading as Realex Payments has its registered office at Castlecourt, Monkstown Farm, Monkstown, Co Dublin, Ireland and is registered in Ireland, company number Page 3 - Version 3.0.0

4 1 Realex Services Realex Payments offer a range of payment and financial services to banks, internet and call centre merchants. Our core business is the creation and running of payment exchanges that link banks with their customers via the internet. We provide the following: Real time credit and debit card authorisation services. Real time fraud scoring and pattern checking services. A direct debit and recurring credit card payment service. A link to third party providers who offer dynamic currency conversion services. Payer authentication services for merchants and banks. Multi channel reporting and management tools. White labelled and customised payment exchanges. Should you be interested in learning more about any of these services we would be delighted to hear from you. 1.1 Realauth Scenarios The Realauth service works under two different scenarios. 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. Redirect is covered in section 2. 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. Remote is covered in section 3. 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: Page 4 - Version 3.0.0

5 Realauth redirect 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). Realauth remote 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. Important 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 Sub-Accounts 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. Page 5 - Version 3.0.0

6 2 Realauth Redirect Merchants that do not have their own secure server can use Realauth redirect. Rather than entering their credit card number on your (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 can be returned to your site to continue browsing. Redirect payment pages are customised using templates, these are described in the following section. 2.1 Redirect Example The process involved for a redirect transaction is shown in the following example. Step 1. Once the full amount is known the customer can be presented with a confirmation page. This page is hosted on the merchants server. If the customer chooses to continue they will be redirected to Realex secure server. Page 6 - Version 3.0.0

7 Step 2. On Realex secure server, the customer is presented with the payment form. This page uses a template to maintain the appearance of the merchants own web-site. Step 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. Please 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. Page 7 - Version 3.0.0

8 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. 2.2 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 ([email protected]) or uploaded through the online resource centre ( 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. Page 8 - Version 3.0.0

9 Below are the full requirements for the template page: 1. Template pages must contain the payment form tag: <!--E-PAGE TABLE HERE--> 2. All images/css used in the template must be referred locally on our server. There should be no absolute URLs to external images/css. The <base /> html tag is also disallowed for this reason. This means that you will need to send the image files to us along with the template page. 3. There can be no scripting of any kind in the template for security reasons. It should contain only basic HTML. 4. The name of the file must be: template.htm 5. 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 ). This folder should then be placed in a zip file of the same name and the complete archive sent to the following address: [email protected] 2.3 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 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> Page 9 - Version 3.0.0

10 Some form of server side programming is required to create the MD5HASH (or SHA1HASH). Because of this, all merchants will be required to perform some script configuration on their side. Realex can supply working sample code in Perl, Java, PHP, ASP and server side JavaScript that will make the process as painless as possible. 2.4 Redirect Request Field Definitions The following fields are accepted by Realex Payments. Anything else will be returned back to your response script (if any) along with the Realex responses. R Required for this request type O Optional Ro Required depending on another optional field For each field the length and format of the field is given in the following fashion: A Alpha/Character (A-Z a-z - _) N Numeric (0-9) S Special Characters V Variable length MERCHANT_ID AN50V R Supplied by Realex note this is not the merchant number supplied by your bank. ACCOUNT AN30V O The sub-account to use for this transaction. If not present, the default sub-account, internet, will be used. ORDER_ID AN50V R A unique alphanumeric id that s used to identify the transaction. This can be up to 40 characters long. No spaces are allowed AMOUNT N10V R 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 A3 R A three-letter code as per currency table in Appendix A. TIMESTAMP N14 R Date and time of the transaction. Entered in the following format: yyyymmddhhmmss MD5HASH AN32 R 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 AN40 R 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. Page 10 - Version 3.0.0

11 AUTO_SETTLE_FLAG N1 R 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 AN255V O A freeform comment to describe the transaction. Up to 255 characters COMMENT2 AN255V O A freeform comment to describe the transaction. Up to 255 characters RETURN_TSS N1 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_CODE 30V O The postcode or ZIP of the shipping address. This can only have letters and digits. (ie no or /) SHIPPING_CO 30V O The country of the shipping address. This can only have letters and digits. (ie no or /) BILLING_CODE 30V O The postcode or ZIP of the billing address. This can only have letters and digits. (ie no or /) BILLING_CO 30V O The country of the billing address. This field can only have letters and digits.. (ie no or /) CUST_NUM ANS50V O The customer number of the customer. VAR_REF ANS50V O A variable reference also associated with this customer. PROD_ID ANS50V O A product id associated with this product. ANYTHING ELSE ANS255V 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) are user definable. Merchants will need to contact Realex in order to set up new sub-accounts. Page 11 - Version 3.0.0

12 2.5 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 or entered through the online resource centre. This application must only 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: MERCHANT_ID This is the merchant id that Realex Payments assign to you. ACCOUNT The sub-account used in the transaction. ORDER_ID The unique order id that you sent to us. AUTHCODE Will contain a valid authcode if the transaction was successful. Will be empty otherwise. RESULT 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. MESSAGE Will contain a text message that describes the result code above. CVNRESULT 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. PASREF A unique reference that Realex Payments assign to your transaction. BATCHID 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.) MD5HASH An MD5 digital signature created using the above fields and your shared secret. Needs to be sent in lowercase. SHA1HASH A SHA-1 digital signature created using the above fields and your shared secret. Needs to be sent in lowercase. TSS The Transaction Suitability Score for the transaction. TSS_idnum 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 by numbers thus TSS_1032 would be the result of the check with id You Page 12 - Version 3.0.0

13 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 Anything else you sent to us in the request will be returned to you. 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. 2.6 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). ( 91eedbf675e6a5af8802b193e8ea94309cbe61ea ) Page 13 - Version 3.0.0

14 Create a new string by concatenating this string and your shared secret using a period. ( 91eedbf675e6a5af8802b193e8ea94309cbe61ea.mysecret ) Get the hash of this value. This is the value that you send to Realex Payments. ( 6f40e8a9a f78dab811a9147d5f94c1192 ) <input type="hidden" name="sha1hash" value="6f40e8a9a f78dab811a9147d5f94c1192"> 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. 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). Please note that both the MD5 and SHA1 hash need to be sent in lowercase. 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). (a686f8a684bf28dfe6cd4d18f41ef0ea50bf6c09) Create a new string by concatenating this string and your shared secret using a period. (a686f8a684bf28dfe6cd4d18f41ef0ea50bf6c09.mysecret) Get the hash of this value. This is the value that you send to Realex Payments. (c069226b737b5f8aee55c0f e5443a). Page 14 - Version 3.0.0

15 3 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. Important 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. 3.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. Step 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). Page 15 - Version 3.0.0

16 Step 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. 3.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. 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 will cause the transaction to fail. The allowed characters for all fields are detailed in the XML definitions guide and in Appendix C. Page 16 - Version 3.0.0

17 3.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 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. The following sections contain examples of the sample code available. Page 17 - Version 3.0.0

18 3.3.1 Sample Java Code Java example public Request request; public Response response = new Response(); request = new Request("auth"); request.setsecret("mysecret"); request.set("merchantid", "thestore"); request.set("orderid", "ORD "); request.set("currency", "EUR"); request.set("amount", "2999"); request.set("cardnumber", " "); request.set("cardexpdate", "0404"); request.set("cardtype", "MC"); request.set("cardholdername", "John Doe"); if (request.isvalid()) { response = request.send(); } else { System.out.println("Error in request."); } System.out.println("Result: " + response.get("result")); System.out.println("Message: " + response.get("message")); System.out.println("Authcode: " + response.get("authcode")); System.out.println("Suitability Score: " + response.get("tss")); Page 18 - Version 3.0.0

19 3.3.2 Sample ASP Code ASP example Set request = New clspayandshop request.createrequest "auth" request.setsecret mysecret request.setfield "merchantid", thestore request.setfield "orderid", ORD request.setfield "currency", EUR request.setfield "amount", request.setfield "cardnumber", request.setfield "cardexpdate", 0305 request.setfield "cardname", Luke Kelly request.setfield "cardtype", VISA equest.sendrequest RespResult = request.getfield("result") RespAuthCode = request.getfield("authcode") RespMessage = request.getfield("message") RespTSSResult = request.getfield("tssresult") RespPASRef = request.getfield("pasref") Page 19 - Version 3.0.0

20 3.3.3 Sample Perl Code Perl example use payandshop::request; my $cardnumber = " "; my $orderid = time; my $request; my $response; $request = new payandshop::request(type => "auth"); $request->setsecret("secret"); $request->set("merchantid", "thestore"); $request->set("orderid", $orderid); $request->set("currency", "IEP"); $request->set("amount", "4"); $request->set("cardnumber", "$cardnumber"); $request->set("cardexpdate", "0404"); $request->set("cardtype", "VISA"); $request->set("cardholdername", "John Doe"); $request->set("autosettle", "1"); if ($request->isvalid()) { $response = $request->send(); my $strresult = $response->get("result"); my $strmessage= $response->get("message"); } else { print "Invalid request: ".$request->geterror(); } Page 20 - Version 3.0.0

21 3.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. The following indicators are used to show whether or not an element is required or optional. R Required for this request type O Optional R Required depending on another optional field For each element of the XML the length and format of the field is given in the following fashion: A Alpha/Character (A-Za-z - _) N Numeric (0-9) S Special Characters (@ / ~ etc..) V Variable length For example: AN50V Alpha Numeric field, up to 50 characters in length N3 Numeric field, exactly 3 characters in length 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> <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> Page 21 - Version 3.0.0

22 </comments> <tssinfo> <custnum>customer number</custnum> <prodid>product id</prodid> <varref>variable reference</varref> <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> <narrative> <establishmentname>merchant Name</establishmentname> <establishmentcity>city</establishmentcity> <establishmentstate>cc</establishmentstate> <chargedescription>description</chargedescription> </narrative> <sha1hash>4dc4f20acc a1bc</sha1hash> <md5hash>67dcc </md5hash> </request> <request timestamp=" " type="auth"> <merchantid> YourMerchantID </merchantid> <account>account to use</account> <orderid>order id</orderid> <amount currency="eur">2000</amount> R N14/ AN50V R AN50V O AN30V R AN50V R A3/ N10V Top-level element. Must have timestamp and type attributes. If the timestamp is more than a day (86400 seconds) away from the server time then the request is rejected. This is your realex payments assigned merchant id This is the realex payments sub-account to use. If you omit this element then we will use your default account. The unique order id of this transaction. Must be unique across all of your accounts. The currency and amount of the transaction. Appendix B of the realauth developer s guide specifies the currency codes. The amount should be in the smallest unit of the required Page 22 - Version 3.0.0

23 <card> <number> </number > R R N19V <expdate>0403</expdate> R N4 <chname>john Doe</chname> R AN100 V <type>mc</type> R A20V <issueno></issueno> R N2V <cvn> <number>453</number> R N4V <presind>1</presind> R N1 </cvn> </card> <autosettle flag="1" /> R N1 <comments> <comment id="1">a comment</comment> <comment id="2">another comment</comment> O O O AN255 V O AN255 V currency (i.e = 20, $20 or 20) There must be a card element in auth requests The card number. The card expiry date. The format is mmyy The card holder s name. The card type. The legal values are: VISA, MC, AMEX, LASER, SWITCH, DINERS The issue number of the card in the case of a Switch card. Only required if the card type is SWITCH The card verification details element. If you use this then the next two elements are required. 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) 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 The auto-settle indicator. If 1 then the transaction will be sent to the bank for settlement tonight. If set to 0 then the transaction will sit in the realex payment s database until someone manually submits it for settlement You can associate up to 2 comments with any transaction for your own purposes. Free-text comment Free-text comment Page 23 - Version 3.0.0

24 </comments> <tssinfo> <custnum>customer number</custnum> <prodid>product id</prodid> <varref>variable reference</varref> <custipaddress> dress> O O ANS50 V O ANS50 V O ANS50 V O AN14V 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. 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. The IP address of the customer <address type="billing"> O The billing address of the customer. <code>zip/postal code</code> O AN30V The ZIP/Postal code of the billing address. This can be checked (in conjunction with the country) against a table of high-risk area codes. <country>country</country> O AN2V The country of the billing address. This can be checked against a table of high-risk countries. </address> <address type="shipping"> O The shipping address of the customer. <code>zip/postal code</code> O AN30V The ZIP/Postal code of the shipping address. This can be checked (in conjunction with the country) against a table of high-risk area codes. <narrative> O The Narrative The Merchant Name <establishmentname>name</establishmentn ame> R AN50V The Merchant City R AN30V <establishmentcity>city</establishmentcity> The Country Code of the R A2 <establishmentstate>cc</establishmentstate Merchant Page 24 - Version 3.0.0

25 > <chargedescription>description</charged escription> </narrative> <country>country</country> </address> </tssinfo> <sha1hash>4dc4f20acc a1bc</ sha1hash> R AN15V O AN2V R AN40 <md5hash>67dcc </md5hash> R AN32 </request> The Charge Description The country of the shipping address. This can be checked against a table of high-risk countries. 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. The MD5 hash of certain elements of the request. The details of this are to be found in the realauth developer s guide. 3.5 Remote Response Message The full version of the response is shown below, followed by the short version and a line-byline 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> <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> Page 25 - Version 3.0.0

26 <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> Page 26 - Version 3.0.0

27 <response timestamp=" "> R N14 <merchantid> YourMerchantID merchantid> <account>account used</account> <orderid>order id used</orderid> <authcode>authcode received</authcode> R AN50V R AN30V R AN50V R AN10V <result>00</result> R N3V <message>message returned from system</message> <pasref> realex payments reference</pasref> R AN100 V R AN40V <cvnresult>m</cvnresult> R A1 <batchid>batch id</batchid> <cardissuer> <bank>issuing Bank Name</bank> <country>issuing Bank Country</country> <countrycode>issuing Bank Co Code</countrycode> <region>issuing Bank Region</region> R AN10V R R AN100 V R AN40V R AN2 R AN20V Top-level element. Will have timestamp attribute. This is the realex payments assigned merchant id used. This is the realex payments subaccount used. The order id of the request. Used when referencing this transaction in refund and void requests. If successful there will be an authcode returned from the bank. Used when referencing this transaction in refund and void requests. The authcode of the original transaction (this was included in the response). The text of the response. Will contain the authcode if successful or the error message if not. The realex payments reference for the transaction. Used when referencing this transaction in refund and void requests. 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 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. The Details of the cardholder s bank (if available) The Bank Name (e.g. First Data Bank) The Bank Country in English (e.g. UNITED STATES) The country code of the issuing bank (e.g. US) The region the card was issued (e.g. US) Can be MEA (Middle East/Asia), Page 27 - Version 3.0.0

28 LAT (Latin America), US (United States), EUR (Europe), CAN (Canada), A/P (Asia/Pacific) </cardissuer> R <tss> O The results of realscore <result>67</result> R N3V The weighted total score of realscore. You may adjust the weights in the realcontrol application. The result of realscore check <check id="xxxx">9</check> R realcontrol application. N4/ number xxxx. You can choose which N1 checks to return using the </tss> The SHA-1 hash of certain elements <sha1hash>7384ae67...ac7d7d</sha1hash> R AN40 of the response. The details of this are to be found in the realauth developer s guide. The MD5 hash of certain elements <md5hash>34e7...a77d</md5hash> R AN32 of the response. The details of this are to be found in the realauth developer s guide. </response> 3.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> Page 28 - Version 3.0.0

29 <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). ( c5d02900c2ed43e0015d5e6792e2071a7b20afd5 ) Create a new string by concatenating this string and your shared secret using a period. ( c5d02900c2ed43e0015d5e6792e2071a7b20afd5.mysecret ) Get the hash of this value. This is the value that you send to Realex Payments. ( 9af7064afd307c9f988e8dfc271f9257f1fc02f6 ) <sha1hash> 9af7064afd307c9f988e8dfc271f9257f1fc02f6 </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). (a686f8a684bf28dfe6cd4d18f41ef0ea50bf6c09) Page 29 - Version 3.0.0

30 Create a new string by concatenating this string and your shared secret using a period. (a686f8a684bf28dfe6cd4d18f41ef0ea50bf6c09.mysecret) Get the hash of this value. This is the value that you send to Realex Payments. (c069226b737b5f8aee55c0f e5443a). 4 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 [email protected]. 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. Page 30 - Version 3.0.0

31 Appendix A Sample Code 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) Page 31 - Version 3.0.0

32 Appendix B Codes Currency Codes EUR Euro GBP Pound Sterling USD US Dollar SEK Swedish Krona CHF Swiss Franc HKD Hong Kong Dollar JPY Japanese Yen (Further codes available on request.) Card Types VISA MC SWITCH AMEX LASER Visa/Delta Mastercard Switch/Solo American Express Laser Page 32 - Version 3.0.0

33 Response Codes The Table below details the current set of result codes returned by the Realex Payments system. These message are subject to change without notice. Best Practise is to treat the codes in the following manner: 00 Successful 101 Declined by Bank 102 Referral by Bank (treat as decline in automated system such as internet) 103 Card reported lost or stolen 2xx Error with bank systems 3xx Error with Realex Payments systems 5xx Incorrect XML message formation or content 666 Client deactivated. RESULT MESSAGE 00 AUTH CODE: nnnnnn 101 CANCELLED CARD 101 CARD EXPIRED 101 DECLINED 101 INVALID AMOUNT 101 INVALID CARD NO. 101 INVALID CURRENCY 101 INVALID EXP DATE 101 INVALID MERCHANT 101 INVALID TRANS 101 NOT AUTHORISED 101 RETAILER UNKNOWN 101 UNABLE TO AUTH 102 CALL AMEX 102 CALL AUTH CENTRE 102 REFERRAL 102 REFERRAL B 103 REFERRAL A 103 PICK UP CARD 103 RETAIN CARD 106 Auth Failed - Contact Auth Centre (Generally Switch Card issue number is incorrect) 107 Fails Realscore Fraud Checks 108 Using test system. Please use pre-approved test cards ONLY 109 Comms Error scheduled bank maintenance 200 Unspecified bank error 202 Network error: cannot connect to EPoS 205 Comms Error bank connection error. 301 Cannot connect to Database 302 Configuration error with your bank details (acquiring bank) - please contact realex payments Page 33 - Version 3.0.0

34 303 There is no default merchant account set. Please contact realex payments if you continue to experience this problem. 303 Error in configuration - merchant has more than one config for this currency/card combination 303 Somehow more than one transaction matches these parameters. 304 Can't find transaction details in database 305 Realex Payments are currently updating the system. We apologise for the inconvenience. 501 This transaction has already been processed. 502 Compulsory field not present - cannot continue. Please check the Developer Documentation for compulsory fields 502 Type [type] not implemented. Please check the Developer Documentation for allowed types 503 Request type not recognised 503 Request type [type] not allowed for this merchant 504 There is no such merchant id. Please contact realex payments if you continue to experience this problem. 505 md5hash incorrect - check your code and the Developers Documentation 505 sha1hash incorrect - check your code and the Developers Documentation 505 You are not allowed to access this service from there! 505 The refund password you entered was incorrect. 506 There is no such merchant account. Please contact realex payments if you continue to experience this problem. 506 No xml in request 506 Too much data 506 Bad xml formation 507 currency/card combination not allowed 508 Invalid data in merchantid field 508 Invalid data in account field 508 Invalid characters in order id - please use only A-Z a-z 0-9 _ Please only numbers in amount - see developers guide 508 Leading zeros or or other error in amount field 508 Zero, negative or insufficient amount specified 508 Invalid data in currency field 508 Invalid data in timestamp field 508 Invalid timestamp 508 Transaction out of date 508 Invalid hash supplied 508 Invalid Auto Settle flag 508 Invalid Auto Settle flag 508 Invalid Data in Billing code field 508 Invalid Data in Billing country field 508 Invalid Data in Shipping code field 508 Invalid Data in Shipping country field 508 invalid characters in cust num - please use only A-Z a-z 0-9 _ -., 508 invalid characters in variable reference - please use only A-Z a-z 0-9 _ -., 508 invalid characters in product id - please use only A-Z a-z 0-9 _ -., 508 Invalid data in card type field Page 34 - Version 3.0.0

35 508 Can't find original transaction in database. 508 The original transaction failed! You can't rebate a failed transaction. 508 You may only rebate up to 115% of the original amount. 508 Can't find original transaction in database. 508 This transaction was successful the first time!. 508 Can't find original transaction in database. 508 Can't settle a settled transaction. 508 Can't settle for more than 115% of that which you authorised. 509 NonNumeric in Credit card number. 509 Invalid credit card length 509 NonNumeric in issue number. 509 Invalid issue number length 509 Only Switch cards have issue numbers 509 Card number fails Luhn Check 509 Invalid expiry date 509 Card Expiry date in past 509 Expiry month invalid 509 That Card Number does not correspond to the card type you selected 509 An ECI value must be included for MPI enabled accounts. 509 Length of CVV data is incorrect 510 That amount is greater than the max allowed 511 Unable to connect to the merchant response url 512 This transaction has already been rebated and cannot be rebated again. 512 Original transaction not found 512 You may only refund the original cardnumber. 512 You can't refund a delayed transaction that has not been sent for settlement. (You are refunding money to a customer that has not and never will be charged!) 512 Original account was not [account] 512 Original transaction currency was not [currency] 512 You may only refund 115% of the value of the original transaction. 512 This transaction has already been refunded through the epage remote interface and cannot be refunded again. 513 Can't void a settled transaction. 514 Original Transaction Failed! If you just want to give money to the customer use the refund terminal in emerchant. 514 Original Transaction was Successful! 514 Can't settle a settled transaction. 514 Can't settle a transaction already settling. 666 This account has been deactivated. Please contact realex payments for further details. Page 35 - Version 3.0.0

36 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. code country name AD ANDORRA AE UNITED ARAB EMIRATES AF AFGHANISTAN AG ANTIGUA AND BARBUDA AI ANGUILLA AL ALBANIA AM ARMENIA AN NETHERLANDS ANTILLES AO ANGOLA AQ ANTARCTICA AR ARGENTINA AS AMERICAN SAMOA AT AUSTRIA AU AUSTRALIA AW ARUBA AZ AZERBAIJAN BA BOSNIA AND HERZEGOVINA BB BARBADOS BD BANGLADESH BE BELGIUM BF BURKINA FASO BG BULGARIA BH BAHRAIN BI BURUNDI BJ BENIN BM BERMUDA BN BRUNEI DARUSSALAM BO BOLIVIA BR BRAZIL BS BAHAMAS BT BHUTAN BV BOUVET ISLAND BW BOTSWANA BY BELARUS BZ BELIZE CA CANADA CC COCOS (KEELING) ISLANDS CD CONGO, THE DEMOCRATIC REPUBLIC OF THE CF CENTRAL AFRICAN REPUBLIC CG CONGO CH SWITZERLAND CI COTE D'IVOIRE code country name CK COOK ISLANDS CL CHILE CM CAMEROON CN CHINA CO COLOMBIA CR COSTA RICA CU CUBA CV CAPE VERDE CX CHRISTMAS ISLAND CY CYPRUS CZ CZECH REPUBLIC DE GERMANY DJ DJIBOUTI DK DENMARK DM DOMINICA DO DOMINICAN REPUBLIC DZ ALGERIA EC ECUADOR EE ESTONIA EG EGYPT EH WESTERN SAHARA ER ERITREA ES SPAIN ET ETHIOPIA FI FINLAND FJ FIJI FK FALKLAND ISLANDS (MALVINAS) FM MICRONESIA, FEDERATED STATES OF FO FAROE ISLANDS FR FRANCE GA GABON GB UNITED KINGDOM GD GRENADA GE GEORGIA GF FRENCH GUIANA GH GHANA GI GIBRALTAR GL GREENLAND GM GAMBIA GN GUINEA GP GUADELOUPE GQ EQUATORIAL GUINEA Page 36 - Version 3.0.0

37 code country name GR GREECE GS SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS GT GUATEMALA GU GUAM GW GUINEA-BISSAU GY GUYANA HK HONG KONG HM HEARD ISLAND AND MCDONALD ISLANDS HN HONDURAS HR CROATIA HT HAITI HU HUNGARY ID INDONESIA IE IRELAND IL ISRAEL IN INDIA IO BRITISH INDIAN OCEAN TERRITORY IQ IRAQ IR IRAN, ISLAMIC REPUBLIC OF IS ICELAND IT ITALY JM JAMAICA JO JORDAN JP JAPAN KE KENYA KG KYRGYZSTAN KH CAMBODIA KI KIRIBATI KM COMOROS KN SAINT KITTS AND NEVIS KP KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF KR KOREA, REPUBLIC OF KW KUWAIT KY CAYMAN ISLANDS KZ KAZAKSTAN LA LAO PEOPLE'S DEMOCRATIC REPUBLIC LB LEBANON LC SAINT LUCIA LI LIECHTENSTEIN LK SRI LANKA LR LIBERIA LS LESOTHO LT LITHUANIA LU LUXEMBOURG LV LATVIA LY LIBYAN ARAB JAMAHIRIYA MA MOROCCO MC MONACO MD MOLDOVA, REPUBLIC OF MG MADAGASCAR MH MARSHALL ISLANDS MK MACEDONIA, THE FORMER YUGOSLAV REPUBLIC code country name OF ML MALI MM MYANMAR MN MONGOLIA MO MACAU MP NORTHERN MARIANA ISLANDS MQ MARTINIQUE MR MAURITANIA MS MONTSERRAT MT MALTA MU MAURITIUS MV MALDIVES MW MALAWI MX MEXICO MY MALAYSIA MZ MOZAMBIQUE NA NAMIBIA NC NEW CALEDONIA NE NIGER NF NORFOLK ISLAND NG NIGERIA NI NICARAGUA NL NETHERLANDS NO NORWAY NP NEPAL NR NAURU NU NIUE NZ NEW ZEALAND OM OMAN PA PANAMA PE PERU PF FRENCH POLYNESIA PG PAPUA NEW GUINEA PH PHILIPPINES PK PAKISTAN PL POLAND PM SAINT PIERRE AND MIQUELON PN PITCAIRN PR PUERTO RICO PS PALESTINIAN TERRITORY, OCCUPIED PT PORTUGAL PW PALAU PY PARAGUAY QA QATAR RE REUNION RO ROMANIA RU RUSSIAN FEDERATION RW RWANDA SA SAUDI ARABIA SB SOLOMON ISLANDS SC SEYCHELLES SD SUDAN Page 37 - Version 3.0.0

38 code country name SE SWEDEN SG SINGAPORE SH SAINT HELENA SI SLOVENIA SJ SVALBARD AND JAN MAYEN SK SLOVAKIA SL SIERRA LEONE SM SAN MARINO SN SENEGAL SO SOMALIA SR SURINAME ST SAO TOME AND PRINCIPE SV EL SALVADOR SY SYRIAN ARAB REPUBLIC SZ SWAZILAND TC TURKS AND CAICOS ISLANDS TD CHAD TF FRENCH SOUTHERN TERRITORIES TG TOGO TH THAILAND TJ TAJIKISTAN TK TOKELAU TM TURKMENISTAN TN TUNISIA TO TONGA TP EAST TIMOR code country name TR TURKEY TT TRINIDAD AND TOBAGO TV TUVALU TW TAIWAN, PROVINCE OF CHINA TZ TANZANIA, UNITED REPUBLIC OF UA UKRAINE UG UGANDA UM UNITED STATES MINOR OUTLYING ISLANDS US UNITED STATES UY URUGUAY UZ UZBEKISTAN VA HOLY SEE (VATICAN CITY STATE) VC SAINT VINCENT AND THE GRENADINES VE VENEZUELA VG VIRGIN ISLANDS, BRITISH VI VIRGIN ISLANDS, U.S. VN VIET NAM VU VANUATU WF WALLIS AND FUTUNA WS SAMOA YE YEMEN YT MAYOTTE YU YUGOSLAVIA ZA SOUTH AFRICA ZM ZAMBIA ZW ZIMBABWE Page 38 - Version 3.0.0

39 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 _ 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 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 Country Codes 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 Country Codes if you are using the realscore checks Customer Number a-z A-Z _ Max 50 characters Variable Reference a-z A-Z _ Max 50 characters Product ID a-z A-Z _ Max 50 characters Comments a-z A-Z _ 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 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 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 digits, mmyy, valid (i.e is illegal) Page 39 - Version 3.0.0

40 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 Recurring Payments Guide RealFX 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. 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. 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. Page 40 - Version 3.0.0

41 Appendix E Version Control Version Date Amendments Completed By /11/05 Added 108 response code Colm Reid /12/05 Added template guidelines Colm Reid /01/06 Changed Appendix C and page 33 Colm Reid /01/06 Added response code 511 Darren Greaney /04/06 Updated Special Characters Darren Greaney /04/06 Updated 509 errors with APACS 30 responses Colm Reid /06/06 Added cvnresult codes to response definitions Chris Dare /09/06 Updated CVN responses Darren Greaney /05/07 Revised & Updated All Sections Brendan Hickey Page 41 - Version 3.0.0