Real Auth Developers Guide v 4.6

 

 

 

     

Real Auth Developers Guide v 4.6  Version: v4.6             

 

                        © 2000—2010 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. 

   

 

Real Auth Developers Guide 

Document Information  Document Name: RealAuth Developers Guide    Document Version: 4.6    Release Date: 30 July 2010   

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  Castlecourt, Monkstown  Farm,  Dun Laoghaire, Co Dublin, Ireland and is registered in Ireland, company number 324929. 

2 

 

Real Auth Developers Guide 

Table of Contents  1

About This Guide 

5

1.1

Purpose 

5

1.2

Audience 

5

1.3

Prerequisites 

5

1.4

Related Documents 

5

2

Introduction 

7

2.1

The Redirect Method 

7

2.2

The Remote Method 

7

2.3

Realauth Redirect Features List 

7

2.4

Remote Features List 

7

2.5

Sub‐Accounts 

8

Realauth Redirect 

9

3 3.1 4

Redirect Example  Templates 

9 12

4.1

Redirect Integration 

13

4.2

Redirect Request Field Definitions 

13

4.3

Redirect Response Field Definitions 

16

4.4

Digital Signature for Redirect 

17

4.5

Address Verification Service: Redirect 

18

5

Realauth Remote 

20

5.1

Remote Example 

20

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 8

9

3 

Luhn check 

33

Appendix B – Codes 

34

8.1

Currency Codes 

34

8.2

Card Types 

34

Response Codes 

35

  9.1

Country Codes 

Real Auth Developers Guide  38

10

Appendix C ‐ Data Validation Rules 

44

11

Appendix D ‐ Realex Guides 

45

4 

 

1

Real Auth Developer’s Guide v 4.2 

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:           

 

Real Auth Developers Guide 

  Conventions 

Description 

Example 

Blue Italic or Plain Type

Hyperlinks and cross‐references 

For more information see Table  1.n 

 

Italics 

Realauth Developer’s Guide

Names of other guides   

Courier New 

Program code, screen messages, directory files, and file    names 

Courier New

Placeholder for element names, field values, or user  input 

card_holder_name

  BOLD CAPS 

101 / REFERRAL B 

Error and warning messages   

 

6 

 

2

Real Auth Developers Guide 

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 ▪ ▪ ▪

▪ ▪       7 

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. 

 

Real Auth Developers Guide 

  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:    ▪ ▪ ▪                            

8 

A sub‐account name  IP address of hosting server  Bank merchant number 

 

Real Auth Developers Guide 

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.

 

9 

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. 

 

Real Auth Developers Guide 

         

  2.  

10 

  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. 

 

Real Auth Developers Guide 

 

    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.   

11 

 

4

Real Auth Developers Guide 

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 ([email protected]).     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.    Enter your credit card details. more html… more 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 “” 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:      1.

2.

3. 4.  

12 

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.    There can be no scripting of any kind in the template for security reasons. It should contain only basic  HTML.    The name of the file must be: template.htm    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

Real Auth Developers Guide 

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  script  is  know  as  the  referring URL. This URL needs to be emailed to [email protected] to be added to the whitelist of  referring URLs.  The minimal implementation is shown below.      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  Required for this request type    O  Optional    C  Required depending on another optional field      Each field has certain constraints around length and format as per below (please note that "" means a space):                     

13 

 

Real Auth Developers Guide 

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. 

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_

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.  

FLAG 

14 

 

Real Auth Developers Guide 

Field Title 

Format 

Length 

COMMENT1 

a‐z A‐Z 0‐9 ' ", + “” .  0‐255 

R/O 

Field Description 

O 

A freeform comment to describe the  transaction. Up to 255 characters  

O 

A freeform comment to describe the  transaction. Up to 255 characters 

_ ‐ & \ / @ ! ? % ( )  * : £ $ & € # [ ] | =  COMMENT2 

a‐z A‐Z 0‐9 ' ", + “” .  0‐255  _ ‐ & \ / @ ! ? % ( )  * : £ $ & € # [ ] | = 

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

a‐z A‐Z 0‐9 “” , . ‐ / 

0‐30 

O 

E 

| 

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 – “” _ . , 

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. 

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….) 

+ @  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‐255  _ ‐ & \ / @ ! ? % ( )  * : £ $ & € # [ ] | = 

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.    15 

 

4.3

Real Auth Developers Guide 

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  [email protected]  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:  Heading  MERCHANT_ID  ACCOUNT  ORDER_ID  AUTHCODE  RESULT 

MESSAGE  CVNRESULT 

PASREF  BATCHID 

ECI  CAVV  XID  MD5HASH  SHA1HASH  TSS  TSS_idnum 

16 

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 

 

ANYTHING ELSE 

Real Auth Developers Guide  continue with the settlement.    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.   

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:   

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:   ( 20010403123245.thestore.ORD453‐11.29900.EUR )  Get the hash of this string (SHA‐1 shown below).  ( 91eedbf675e6a5af8802b193e8ea94309cbe61ea )    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.  ( 6f40e8a9a9976497f78dab811a9147d5f94c1192 )     

17 

 

Real Auth Developers Guide 

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 (“.”)   (20010403123245.thestore.ORD453‐11.00.Successful.3737468273643.79347)  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.  (c069226b737b5f8aee55c0f49473748764e5443a).   

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  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:    |  For example, if the billing address is:  382, The Road  The Town  WB1 A42  UK    The corresponding AVS data will be:      The possible responses that can be returned for the Address Verification Service are as  follows:    ▪ M (Matched)  18 

  ▪ ▪ ▪ ▪

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:    AVSPOSTCODERESPONSE  AVSADDRESSRESPONSE                   

19 

Real Auth Developers Guide 

 

5

Real Auth Developers Guide 

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.   

  20 

  1.

Real Auth Developers Guide 

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).# 

   

 

  2.

5.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.  

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.  

21 

  ▪ ▪ ▪

Real Auth Developers Guide 

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 [email protected].   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:  ▪ ▪ ▪ ▪ ▪  

5.4

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. 

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.    YourMerchantID account to use order id 2000 490303400005718902 0403 John Doe MC 453 1 a comment

22 

 

Real Auth Developers Guide 

another comment customer number product id variable reference www.xxx.yyy.zzz zip/postal code country zip/postal code country 4dc4f20acc….30314758a1bc 67dcc….787307   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  M  0‐9  14  (86400 seconds) away from the  server time then the request is  rejected.  M  a‐z A‐Z 0‐9 .  1‐50  mer This is your realex payments  chant id used O  a‐z A‐Z 0‐9 “”  0‐30  accoun This is the realex payments sub‐ t used account to use. If you omit this  element then we will use your  default account.  M  a‐z A‐Z 0‐9 _  1‐40  order The unique order id of this  ‐    id transaction. Must be unique  across all of your accounts.  M  a‐z A‐Z  3  2000 transaction.  “Appendix B ‐ Codes” on page 35  of the realauth developer's guide  specifies the currency codes. The  amount should be in thesmallest  unit of the required currency (i.e.  2000 = £20, $20 or €20)  M      There must be a card element in  auth requests  M  0‐9  12‐19  49030340000 The card number.  5718902 M  0‐9  4  0403 is mmyy.  M  a‐z A‐Z 0‐9 ‐  1‐100  John The card holder's name.  + 

23 

  Line per line description  Doe

Real Auth Developers Guide  M/O/ 

Format 

Length 

MC

M 

"" , ' + . _ ‐ ;  &  \ /  See Details 



M 

0‐9 



O 

 

453

M 

0‐9 

1

M 

See Details 

1 



M 

 

 

M 

 

 

M 

See Details 

 



C 

See Details 

 

24 

 

0‐3 

 

3‐4 

Details 

The card type. The legal values  are: VISA, MC,  LASER, SWITCH, AMEX, DINERS,  UATP  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) 3 digits on  Visa and MC, 4 digits on Amex.  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 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.  If you are configured for  recurring/continuous  authority transactions, you must  set these  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 

  Line per line description 

Real Auth Developers Guide  M/O/ 

Format 

Length 

0‐255 

Details  for transactions after that, and  last for the final transaction of the  set. Only supported by some  acquirers.  You can associate up to 2  comments with any  transaction for your own  purposes.  Free‐text comment 

0‐255 

Free‐text comment 



O 

 

a comment

O 

a comment

O 



O 

a‐z A‐Z 0‐9 '  ",  + "" . _ ‐ & \ /  @ ! ? % ( ) * :  £ $ & € # [ ] |  =  a‐z A‐Z 0‐9 '  ",  + "" . _ ‐ & \ /  @ ! ? % ( ) * :  £ $ & € # [ ] |  =   

O 

 

customer number

O 

a‐z A‐Z 0‐9 ‐  ""  _ . , + @ 

0‐50 

product id

O 

0‐50 

variable reference

O 

a‐z A‐Z 0‐9 ‐  ""  _ . , + @  a‐z A‐Z 0‐9 ‐  ""  _ . , + @ 

www. xxx.yyy.zzz

O 

zip|postal code

O 

25 

O 

0‐9  IP Address in  X.X.X.X  format    a‐z A‐Z 0‐9 ""  ,  . ‐ / | 

 

   

0‐50 

[1‐3].{1‐  3}.{1‐3}.{1‐3} 

  0‐30 

  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. 

The billing address of the  customer.  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. This field is used  address verification with certain  acquirers. 

  Line per line description  country

zip|postal code

country

7384 ae67....ac7d7d

34e7. ...a77d

Real Auth Developers Guide  M/O/ 

Format 

Length 

O 

a‐z A‐Z 0‐9 ""  ,  . ‐ 

0‐30 

 

 

 

O 

 

 

O 

a‐z A‐Z 0‐9 ""  ,  . ‐ / | 

0‐30 

O 

a‐z A‐Z 0‐9 ""  ,  . ‐ 

0‐30 

 

 

 

 

M 

   

a‐f 0‐9 

40 

M 

a‐f 0‐9 

32 

 

 

 

Details  The country of the billing address.  This can be  checked against a table of high‐ risk countries.    The shipping address of the  customer.  The ZIP|Postal code of the  shipping address.  This can be checked (in  conjunction with the  country) against a table of high‐ risk area codes.  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.   

 

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    YourMerchantID account to use order id from request authcode received 00 message returned from system realex payments reference M batch id for this transaction (if any) Issuing Bank Name

26 

 

Real Auth Developers Guide 

Issuing Bank Country Issuing Bank Country Code Issuing Bank Region 89 9 9 … 7384ae67....ac7d7d 34e7....a77d   Response Format ‐ Short Version    508 message returned from system     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  M  0‐9  14  the timestamp is more than a day  (86400 seconds) away from the  server time then the request is  rejected.  M  a‐z A‐Z 0‐9 .  1‐50  mer This is your realex payments  chant id used O  a‐z A‐Z 0‐9 “”  0‐30  accoun This is the realex payments sub‐ t used account to use. If you omit this  element then we will use your  default account.  M  a‐z A‐Z 0‐9 _  1‐40  order The unique order id of this  ‐    id transaction. Must be unique  across all of your accounts.  M  0‐10  a-z A-Z 0authc If successful an authcode is  9  ode received when referencing this transaction  in refund and void requests.  M  0‐9  0‐3  00 Realex Payments system.  M  a-z A-Z 00-100  messa The text of the response. Contains  9 ' ", + "" ge returned from the authcode if successful or the  . system @!?%( )

realex payments

27 

M 

*:£$& € # [ ] | =  a-z A-Z 09 

0‐50 

The Realex payments reference  for the transaction. Used when 

  Line per line description  reference M

Real Auth Developers Guide  M/O/ 

Format 

Length 

M 

See Details 

1 

batch id

M 

0‐9 

0‐20 



M 

 

 

Issuing Bank Name Issuing Bank Country Iss uing Bank Co Code Issuing Bank Region

M 

a-z A-Z 09 _ 

0‐30 

M 

a-z A-Z 09 "" , . - 

0‐30 

M 

a-z A-Z 

2 

M 

a-a A-Z 09 / 

0‐20 

67

M 

 

 

O 

 

 

M 

0‐9 

0‐3 

9

M 

0‐9  0‐9 

4  1 

7384 ae67....ac7d7d

M 

a-f 0-9 

40 

34e7. ...a77d

M 

a-f 0-9 

32 

 

 

 



28 

Details  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), LAT (Latin America),  US (United States), EUR (Europe),  CAN (Canada), A/P (Asia/Pacific)    The results of realscore  The weighted total score of  realscore. You may adjust the  weights in the realcontrol  application.  The result of realscore check  number xxxx. You can choose  which checks to return using the  realcontrol application.  The SHA‐1 hash of certain  elements of the response. The  details of this are to be found in  the realauth developer's guide  The MD5 hash of certain elements  of the response. The details of this  are to be found in the realauth  developer's guide.   

 

Real Auth Developers Guide 

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:      thestore theaccount ORD453-11 29900 5105105105105100 0302 John Smith VISA     To construct the hash follow this procedure:  Form a string by concatenating the above fields with a period (“.”)   ( 20010403123245.thestore.ORD453‐11.29900.EUR.5105105105105100 )    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 )      9af7064afd307c9f988e8dfc271f9257f1fc02f6     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  29 

 

Real Auth Developers Guide 

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 (“.”)    ( 20010403123245.thestore.ORD453‐11.00.Successful.3737468273643.79347)    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.  (c069226b737b5f8aee55c0f49473748764e5443a). 

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:  |  For example, if the billing address is:  382, The Road  The Town  WB1 A42 

30 

 

Real Auth Developers Guide 

UK  The corresponding AVS data will be: