Realauth XML Definitions Guide.book by exx10251

VIEWS: 40 PAGES: 39

									                                      ggg
                        eyeQ360™
                                 al Use



Rear
Only




       Realauth XML Definitions Guide
                              VERSION 2.0
Document Information

               Document Name: Realauth XML Defintions
               Document Version: 2.0
               Release Date: 15 August 2009


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




Proprietary and Confidential Information of Realex
Contents

      About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
      Purpose. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
      Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
      Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
      Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
      Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
      Product Support Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3



      Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
      Auth Request Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
                            Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
                            XML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
                            Hash Value Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
      Manual Request Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
                            Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
                            XML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
                            Hash Value Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
      Offline Request Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
                            Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
                            XML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
                            Hash Value Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
      Rebate Request Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
                            Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
                            XML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
                            Hash Value Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
      Void Request Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
                            Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
                            XML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
                            Hash Value Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
      TSS Request Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
                            Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
                            Hash Value Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
      Settle Request Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
                            Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
                            XML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
                            Hash Value Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32



      Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
      Result Codes That Return Full Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Contents

      Result Codes That Only Return Code And Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33



      About Realex Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
About This Guide


               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.




               Purpose
               The purpose of this guide is to provide all of the details required to submit valid XML
               requests for each transaction type available as part of the Realex service.




               Audience
               The target audience for this guide is software and web developers.




               Prerequisites
               In order to use this guide, you should have experience with and knowledge of the following
               concepts:
                    Correct use of the Realauth service, as outlined in the Realauth Developer's Guide
                    Creation and remote submission of XML messages




               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 Developer's Guide
                    RealMPI Developer's Guide
                    RealControl User's Guide
                    RealScore User's Guide




Proprietary and Confidential Information of Realex                                                           1
                                                                             Relauth XML Definition Guide




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


                Conventions
                Convention          Description                        Example

                Blue Italic or      Hyperlinks and cross-references    For more information see Table 1.
                Plain Type

                Italics             Names of other guides              Realauth Developer’s Guide

                Courier New         Program code, screen messages,     <comments></comments>
                                    directory files, and file names

                Courier New         Placeholder for element names,     card_holder_name
                                    field values, or user input

                BOLD CAPS           Error and warning messages         101 / REFERRAL B




Proprietary and Confidential Information of Realex                                                         2
About This Guide


               Product Support Information
               You can contact us using any of the following methods:
               Contact Information - Ireland
                Method                         Contact Information

                Address                        Castlecourt, Monkstown Farm,
                                               Monkstown,
                                               Co Dublin, Ireland

                Telephone                      + 353 (0)1 280 8559

                Fax                            + 353 (0)1 280 8538

                Sales email                    sales@realexpayments.com

                Support email                  support@realexpayments.com

                Web Site                       www.realexpayments.com


               Contact Information - United Kingdom
                Method                         Contact Information

                Address                        Realex Payments London:
                                               1 Lyric Square,
                                               Hammersmith,
                                               London W6 0NB,
                                               United Kingdom.

                Telephone                      +44 (0)20 3178 5370

                Fax                            +44 (0)20 7691 7264

                Sales email                    sales@realexpayments.com

                Support email                  support@realexpayments.com

                Web Site                       www.realexpayments.co.uk




Proprietary and Confidential Information of Realex                            3
Requests


               Requests

               Realauth uses several different request types, including the following:
                    Auth Request Type
                    Manual Request Type
                    Offline Request Type
                    Rebate Request Type
                    Void Request Type
                    TSS Request Type
                    Settle Request Type




Proprietary and Confidential Information of Realex                                       4
                                                                              Relauth XML Definition Guide
                Auth Request Type
                The primary request type is the auth request type, which is used to obtain an authorisation
                for a particular debit or credit card. The following sections provide the information
                necessary to submit a valid auth request type:
                    Example
                    XML Syntax
                    Hash Value Syntax




Proprietary and Confidential Information of Realex                                                        5
Requests

               Example

                  <request timestamp="20010427124523" type="auth">
                    <merchantid>merchantid</merchantid>
                    <account>subaccount</account>
                    <orderid>orderid</orderid>
                    <amount currency="GBP">2000</amount>
                    <card>
                     <number>490303400005718902</number>
                     <expdate>0403</expdate>
                     <chname>John Doe</chname>
                     <type>SWITCH</type>
                     <issueno>1</issueno>
                     <cvn>
                      <number>453</number>
                      <presind>1</presind>
                     </cvn>
                    </card>
                  <autosettle flag="1" />
                  <comments>
                     <comment id="1">a comment</comment>
                     <comment id="2">another comment</comment>
                  </comments>
                  <tssinfo>
                     <custnum>customer number</custnum>
                     <prodid>product id</prodid>
                     <varref>variable reference</varref>
                     <custipaddress>www.xxx.yyy.zzz</custipaddress>
                     <address type="billing">
                      <code>zip/postal code</code>
                      <country>country</country>
                     </address>
                     <address type="shipping">
                      <code>zip/postal code</code>
                      <country>country</country>
                  </address>
                  </tssinfo>
                  <sha1hash>4dc4f20acc….30314758a1bc</sha1hash>
                  <md5hash>67dcc….787307</md5hash>
                  </request>


Proprietary and Confidential Information of Realex                    6
                                                                                  Relauth XML Definition Guide
                XML Syntax
                For each XML element or field, the following table provides the following information:
                    The syntax for the element or field
                    An indication of whether the element or field is mandatory (M), optional (O), or
                    conditional (C) depending on another optional field
                    The format for the value in terms of allowable characters or numbers
                    The allowable length of the value
                    A description
                                                M/
  Element/Field                                       Format          Length       Description
                                                O/C
  <request timestamp="YYYYMMDDHHMMSS"           M     0-9             14           Top-level element. Must have
  type="auth">                                                                     timestamp and type attributes.
  </request>                                                                       Timestamp must be in the
                                                                      type:auth
                                                                                   format YYYYMMDDHHMMSS,
                                                                                   which represents the time in the
                                                                                   format year month date hour
                                                                                   minute second.
                                                                                   If the timestamp is more than a
                                                                                   day (86400 seconds) away from
                                                                                   the server time, then the
                                                                                   request is rejected.
  <merchantid>merchantid</merchantid>           M     a-z A-Z 0-9 .   1-50         Where merchantid represents
                                                                                   Realex Payments assigned
                                                                                   merchant id.
  <account>subaccount</account>                 O     a-z A-Z 0-9     0-30         Where subaccount represents
                                                      ""                           the Realex Payments sub-
                                                                                   account to use. If this element is
                                                                                   omitted, then the default
                                                                                   account is used.
  <orderid>orderid</orderid>                    M     a-z A-Z 0-9     1-40         Where orderid represents the
                                                      _-                           unique order id of this
                                                                                   transaction. Must be unique
                                                                                   across all of the sub-accounts.
  <amount currency="aaa">1234</amount>          M     a-z A-Z 0-9     3 1-11       Where aaa represents the
                                                                                   currency code (such as GPB) and
                                                                                   1234 represents the amount of
                                                                                   the transaction. The Realauth
                                                                                   Developer's Guide has a
                                                                                   complete list of the currency
                                                                                   codes. The amount should be in
                                                                                   the smallest unit of the required
                                                                                   currency (For example: 2000 =
                                                                                   £20, $20 or €20).
  <card></card>                                 M                                  The card element is required in
                                                                                   auth requests and consists of the
                                                                                   following sub-elements:
                                                                                      number
                                                                                      expdate
                                                                                      chname
                                                                                      type
                                                                                      issueno
                                                                                      cvn
  <number>12345678901234</number>               M     0-9             12-19        Where 12345678901234
                                                                                   represents the card number
                                                                                   used for the transaction.
  <expdate>0101</expdate>                       M     0-9             4            Where 0101 represets the card
                                                                                   expiry date, in the format MMYY,
                                                                                   which must be a date in the
                                                                                   future.



Proprietary and Confidential Information of Realex                                                                      7
                                                                              Relauth XML Definition Guide
  <chname>card_holder_name</chname>             M    a-z A-Z 0-9      0-100    Where card_holder_name
                                                     - + "" , ' + .            represents the name of the card
                                                     _-;&\/                    holder.
  <type>card_type</type>                        M    VISA             N/A      Where card_type indicates the
                                                     MC                        type of card used in the
                                                                               transaction.
                                                     AMEX
                                                     LASER
                                                     SWITCH
                                                     DINERS
  <issueno>1</issueno>                          C    0-9              0-3      Where 1 represents the issue
                                                                               number of a SWITCH. Only
                                                                               required if the card type is
                                                                               SWITCH.
  <cvn></cvn>                                   O                              The card verification details
                                                                               element, which requires the
                                                                               following two sub-elements:
                                                                                  number
                                                                                  presind
  <number>123</number>                          C    0-9              3-4      Where 123 represents the Card
                                                                               Verification Number (CVN),
                                                                               which is a three-digit number on
                                                                               the reverse of the card. It is
                                                                               called the CVC for VISA and the
                                                                               CVV2 for MasterCard. For an
                                                                               AMEX card, it is a four-digit
                                                                               number.
  <presind>presence_indicator </presind>        C    See              1        Where presence_indicator
                                                     Description               represents the presence of the
                                                                               CVN and can take the following
                                                                               four values:
                                                                               1: CVN present
                                                                               2: CVN illegible
                                                                               3: CVN not on card
                                                                               4: CVN not requested by the
                                                                               merchant
  <autosettle flag="x" />                       M    See              1        Where x represents the value of
                                                     Description               the auto-settle indicator. If set to
                                                                               1, then the transaction will be
                                                                               included in today's settlement
                                                                               file. If set to 0, then the
                                                                               transaction will be authorised
                                                                               but not settled. Merchants must
                                                                               manually settle delayed
                                                                               transactions within 28 days of
                                                                               authorisation.
  <comments></comments>                         O                              Optionally, up to two comments
                                                                               can be associated with any
                                                                               transaction.
  <comment id="1">a_comment</comment>           O    a-z A-Z 0-9 '    0-255    Where a_comment represents a
                                                     ", + "" . _ -             free-text comment.
                                                     &\/@!?
                                                     %()*:£$
                                                     &€#[]|=
  <comment id="2">another comment</             O    a-z A-Z 0-9 '    0-255    Where another comment
  comment>                                           ", + "" . _ -             represents a free-text comment.
                                                     &\/@!?
                                                     %()*:£$
                                                     &€#[]|=




Proprietary and Confidential Information of Realex                                                                    8
                                                                                  Relauth XML Definition Guide
  <tssinfo></tssinfo>                           O                                  This element includes data to be
                                                                                   used with the Realscore service.
                                                                                   This information is also visible in
                                                                                   the reporting tool RealControl.
                                                                                   The tssinfo includes the following
                                                                                   sub-elements:
                                                                                      custnum
                                                                                      prodid
                                                                                      varref
                                                                                      address type = billing
                                                                                      address type = shipping
  <custnum>customer_number</custnum>            O    a-z A-Z 0-9      0-50         Where customer_number
                                                     - "" _ . , + @                represents the number assigned
                                                                                   to the customer, which can allow
                                                                                   checking of previous
                                                                                   transactions by this customer.
  <prodid>product_id</prodid>                   O    a-z A-Z 0-9      0-50         Where product_id is the product
                                                     - "" _ . , + @                code assigned to the product.
  <varref>variable_reference</varref>           O    a-z A-Z 0-9      0-50         Where variable_reference
                                                     - "" _ . , + @                represents any reference
                                                                                   assigned to the customer, which
                                                                                   can allow checking of previous
                                                                                   transactions by this customer,
                                                                                   through the use of the Realscore
                                                                                   service.
  <custipaddress>www.xxx.yyy.zzz</              O    0-9              [1-3].{1-    Where www.xxx.yyy.zzz
  custipaddress>                                     IP Address       3}.{1-       represents the IP address of the
                                                     in X.X.X.X       3}.{1-3}     customer.
                                                     format
  <address type="billing"></address>            O                                  The billing address of the
                                                                                   customer, which includes the
                                                                                   following sub-elements:
                                                                                      zip_postal_code
                                                                                      country
  <code>zip_postal_code</code>                  O    a-z A-Z 0-9      0-30         Where zip_postal_code
                                                     "" , . - / |                  represents the ZIP or Postal
                                                                                   code of the billing address,
                                                                                   which is useful for checking (in
                                                                                   conjunction with the country)
                                                                                   against a table of high-risk
                                                                                   areas.
                                                                                   This field is also used to pass
                                                                                   AVS data. For information, on
                                                                                   AVS see the RealAuth
                                                                                   Developer's Guide.
  <country>country</country>                    O    a-z A-Z          2            Where country represents the
                                                     2-character                   country of the billing address,
                                                     country                       which is useful for checking
                                                     code                          against a table of high-risk
                                                                                   countries. See Country Codes.
  <address type="shipping"></address>           O                                  The shipping address of the
                                                                                   customer, which includes the
                                                                                   following sub-elements:
                                                                                      code
                                                                                      country
  <code> zip_postal_code </code>                O    a-z A-Z 0-9      0-30         Where zip_postal_code
                                                     "" , . - / |                  represents the ZIP or Postal
                                                                                   code of the shipping address,
                                                                                   which is useful for checking (in
                                                                                   conjunction with the country)
                                                                                   against a table of high-risk
                                                                                   areas.




Proprietary and Confidential Information of Realex                                                                       9
                                                                              Relauth XML Definition Guide
  <country>country</country>                    O     a-z A-Z       2           Where country represents the
                                                      2-character               country of the shipping address,
                                                      country                   which is useful for checking
                                                      code                      against a table of high-risk
                                                                                countries. See Country Codes.

  <sha1hash>SHA_1_hash</sha1hash>               M     a-f 0-9       40          Where SHA_1_hash represents
                                                                                the SHA-1 hash of certain
                                                                                elements of the request. For
                                                                                more information, see the
                                                                                Realauth Developer's Guide.
                                                                                Either the SHA-1 hash or the
                                                                                MD5 hash can be used.
  <md5hash>MD5_hash</md5hash>                   M     a-f 0-9       32          Where MD5_hash represents the
                                                                                MD5 hash of certain elements of
                                                                                the request. For more
                                                                                information, see the Realauth
                                                                                Developer's Guide.

                Hash Value Syntax
                The following table illustrates the hash value syntax for the auth request type:


                Format:        timestamp.merchantid.orderid.amount.currency.cardnumber

                Example:       20010427124523.merchantid.orderid.2000.GBP.490303400005718902




Proprietary and Confidential Information of Realex                                                             10
                                                                              Relauth XML Definition Guide
                Manual Request Type
                Manual transactions are not sent to the bank for authorisation, instead they are added
                directly to the day's settlement file. Merchants must manually obtain an authorisation code
                for transactions of this type. Typically, this involves contacting the acquiring bank's
                authorisation centre by phone. Realex Payments will require confirmation from the
                acquiring bank before this facility can be used.
                By default, this request is not allowed, and Realex Payments will require confirmation from
                the bank before this facility can be used.
                The following sections provide the information necessary to submit a valid manual request
                type:
                    Example
                    XML Syntax
                    Hash Value Syntax




Proprietary and Confidential Information of Realex                                                       11
                                                                    Relauth XML Definition Guide
                Example

                   <request timestamp="20010427124523" type="manual">
                    <merchantid>merchantid</merchantid>
                    <account>subaccount</account>
                    <orderid>orderid</orderid>
                    <authcode>auth code from alternative source</authcode>
                    <amount currency="GBP">2000</amount>
                    <card>
                     <number>490303400005718902</number>
                     <expdate>0403</expdate>
                     <chname>John Doe</chname>
                     <type>SWITCH</type>
                     <issueno>1</issueno>
                     <cvn>
                       <number>453</number>
                       <presind>1</presind>
                     </cvn>
                    </card>
                    <autosettle flag="1" />
                    <comments>
                     <comment id="1">a comment</comment>
                     <comment id="2">another comment</comment>
                    </comments>
                    <tssinfo>
                     <custnum>customer number</custnum>
                     <prodid>product id</prodid>
                     <varref>variable reference</varref>
                     <address type="billing">
                       <code>zip/postal code</code>
                       <country>country</country>
                     </address>
                     <address type="shipping">
                       <code>zip/postal code</code>
                       <country>country</country>
                     </address>
                    </tssinfo>
                    <sha1hash>4dc4f20acc….30314758a1bc</sha1hash>
                    <md5hash>67dcc….787307</md5hash>
                   </request>




Proprietary and Confidential Information of Realex                                           12
                                                                                  Relauth XML Definition Guide
                XML Syntax
                For each XML element or field, the following table provides the following information:
                    The syntax for the element or field
                    An indication of whether the element or field is mandatory (M), optional (O), or
                    conditional (C) depending on another optional field
                    The format for the value in terms of allowable characters or numbers
                    The allowable length of the value
                    A description
                                                M/
  Element/Field                                       Format        Length         Description
                                                O/C
  <request timestamp="YYYYMMDDHHMMSS"           M     0-9           14             Top-level element. Must have
  type="manual">                                                                   timestamp and type attributes.
  </request>                                                                       Timestamp must be in the
                                                                    type:manual
                                                                                   format YYYYMMDDHHMMSS,
                                                                                   which represents the time in the
                                                                                   format year month date hour
                                                                                   minute second.
                                                                                   If the timestamp is more than a
                                                                                   day (86400 seconds) away from
                                                                                   the server time, then the
                                                                                   request is rejected.
  <merchantid>merchantid</merchantid>           M     a-z A-Z 0-9   1-50           Where merchantid represents
                                                      .                            the Realex Payments assigned
                                                                                   merchant id (not the merchant
                                                                                   number the bank will assign).
  <account>subaccount</account>                 O     a-z A-Z 0-9   0-30           Where subaccount represents
                                                      ""                           the Realex Payments sub-
                                                                                   account to use. If this element is
                                                                                   omitted, then the default
                                                                                   account is used.
  <orderid>orderid</orderid>                    M     a-z A-Z 0-9   1-40           Where orderid represents the
                                                      _-                           unique order id of this
                                                                                   transaction. Must be unique
                                                                                   across all of the sub-accounts.
  <authcode>authcode</authcode>                 M     a-z A-Z 0-9   0-10           Where authcode represents the
                                                                                   authcode received from the
                                                                                   voice authorisation centre or a
                                                                                   similar alternative source.
  <amount currency="aaa">1234</amount>          M     a-z A-Z 0-9   3 1-11         Where aaa represents the
                                                                                   currency code (such as GPB) and
                                                                                   1234 represents the amount of
                                                                                   the transaction. The Realauth
                                                                                   Developer's Guide has a
                                                                                   complete list of the currency
                                                                                   codes. The amount should be in
                                                                                   the smallest unit of the required
                                                                                   currency (For example: 2000 =
                                                                                   £20, $20 or €20).
  <card></card>                                 M                                  The card element is required in
                                                                                   auth requests and consists of the
                                                                                   following sub-elements:
                                                                                      number
                                                                                      expdate
                                                                                      chname
                                                                                      type
                                                                                      issueno
                                                                                      cvn
  <number>12345678901234</number>               M     0-9           12-19          Where 12345678901234
                                                                                   represents the card number
                                                                                   used for the transaction.


Proprietary and Confidential Information of Realex                                                                   13
                                                                             Relauth XML Definition Guide
  <expdate>0101</expdate>                       M    0-9             4        Where 0101 represets the card
                                                                              expiry date, in the format MMYY,
                                                                              which must be a date in the
                                                                              future.
  <chname>card_holder_name</chname>             M    a-z A-Z 0-9     0-100    Where card_holder_name
                                                     - + "" , ' +             represents the name of the card
                                                     ._-;&\/                  holder.
  <type>card_type</type>                        M    VISA            N/A      Where card_type indicates the
                                                     MC                       type of card used in the
                                                                              transaction.
                                                     AMEX
                                                     LASER
                                                     SWITCH
                                                     DINERS
  <issueno>1</issueno>                          C    0-9             0-3      Where 1 represents the issue
                                                                              number of a SWITCH. Only
                                                                              required if the card type is
                                                                              SWITCH.
  <cvn></cvn>                                   O                             The card verification details
                                                                              element, which requires the
                                                                              following two sub-elements:
                                                                                 number
                                                                                 presind
  <number>123</number>                          C    0-9             3-4      Where 123 represents the Card
                                                                              Verification Number (CVN),
                                                                              which is a three-digit number on
                                                                              the reverse of the card. It is
                                                                              called the CVC for VISA and the
                                                                              CVV2 for MasterCard. For an
                                                                              AMEX card, it is a four-digit
                                                                              number.
  <presind>presence_indicator </presind>        C    1               1        Where presence_indicator
                                                     2                        represents the presence of the
                                                                              CVN and can take the following
                                                     3
                                                                              four values:
                                                     4
                                                                              1: CVN present
                                                                              2: CVN illegible
                                                                              3: CVN not on card
                                                                              4: CVN not requested by the
                                                                              merchant
                                                                              In practise, this is generally a
                                                                              drop-down list from which the
                                                                              cardholder can select the
                                                                              appropriate value.
  <autosettle flag="x" />                       M    1               1        Where x represents the value of
                                                     0                        the auto-settle indicator. If set to
                                                                              1, then the transaction will be
                                                                              included in today's settlement
                                                                              file. If set to 0, then the
                                                                              transaction will be authorised
                                                                              but not settled. Merchants must
                                                                              manually settle delayed
                                                                              transactions within 28 days of
                                                                              authorisation.
  <comments></comments>                         O                             Optionally, up to two comments
                                                                              can be associated with any
                                                                              transaction.
  <comment id="1">a_comment</comment>           O    a-z A-Z 0-9     0-255    Where a_comment represents a
                                                     ' ", + "" . _            free-text comment.
                                                     -&\/@!
                                                     ?%()*:
                                                     £$&€#[
                                                     ]|=




Proprietary and Confidential Information of Realex                                                               14
                                                                             Relauth XML Definition Guide
  <comment id="2">another comment</             O    a-z A-Z 0-9     0-255    Where another comment
  comment>                                           ' ", + "" . _            represents a free-text comment.
                                                     -&\/@!
                                                     ?%()*:
                                                     £$&€#[
                                                     ]|=
  <tssinfo></tssinfo>                           O                             This element includes data to be
                                                                              used with the Realscore service.
                                                                              This information is also visible in
                                                                              the reporting tool RealControl.
                                                                              The tssinfo includes the following
                                                                              sub-elements:
                                                                                 custnum
                                                                                 prodid
                                                                                 varref
                                                                                 address type = billing
                                                                                 address type = shipping
  <custnum>customer_number</custnum>            O    a-z A-Z 0-9     0-50     Where customer_number
                                                     - "" _ . , +             represents the number assigned
                                                     @                        to the customer, which can allow
                                                                              checking of previous
                                                                              transactions by this customer.
  <prodid>product_id</prodid>                   O    a-z A-Z 0-9     0-50     Where product_id is the product
                                                     - "" _ . , +             code assigned to the product.
                                                     @
  <varref>variable_reference</varref>           O    a-z A-Z 0-9     0-50     Where variable_reference
                                                     - "" _ . , +             represents any reference
                                                     @                        assigned to the customer, which
                                                                              can allow checking of previous
                                                                              transactions by this customer,
                                                                              through the use of the Realscore
                                                                              service.
  <address type="billing"></address>            O                             The billing address of the
                                                                              customer, which includes the
                                                                              following sub-elements:
                                                                                 zip_postal_code
                                                                                 country
  <code>zip_postal_code</code>                  O    a-z A-Z 0-9     0-30     Where zip_postal_code
                                                     "" , . - / |             represents the ZIP or Postal
                                                                              code of the billing address,
                                                                              which is useful for checking (in
                                                                              conjunction with the country)
                                                                              against a table of high-risk
                                                                              areas.
  <country>country</country>                    O    a-z A-Z         2        Where country represents the
                                                     2-                       country of the billing address,
                                                     character                which is useful for checking
                                                     country                  against a table of high-risk
                                                     code                     countries. See Country Codes.
  <address type="shipping"></address>           O                             The shipping address of the
                                                                              customer, which includes the
                                                                              following sub-elements:
                                                                                 code
                                                                                 country
                                                O    a-z A-Z 0-9     0-30     Where zip_postal_code
                                                     "" , . - / |             represents the ZIP or Postal
                                                                              code of the shipping address,
                                                                              which is useful for checking (in
                                                                              conjunction with the country)
                                                                              against a table of high-risk
                                                                              areas.




Proprietary and Confidential Information of Realex                                                               15
                                                                              Relauth XML Definition Guide
  <country>country</country>                    O    a-z A-Z     2             Where country represents the
                                                     2-                        country of the shipping address,
                                                     character                 which is useful for checking
                                                     country                   against a table of high-risk
                                                     code                      countries. See Country Codes.


  <sha1hash>SHA_1_hash</sha1hash>               M    a-f 0-9     40            Where SHA_1_hash represents
                                                                               the SHA-1 hash of certain
                                                                               elements of the request. For
                                                                               more information, see the
                                                                               Realauth Developer's Guide.
  <md5hash>MD5_hash</md5hash>                   M    a-f 0-9     32            Where MD5_hash represents the
                                                                               MD5 hash of certain elements of
                                                                               the request. For more
                                                                               information, see the Realauth
                                                                               Developer's Guide.

                Hash Value Syntax
                The following table illustrates the hash value syntax for the manual request type:


                Format:        timestamp.merchantid.orderid.amount.currency.cardnumber

                Example:       20010427124523.merchantid.orderid.2000.GBP.490303400005718902




Proprietary and Confidential Information of Realex                                                            16
                                                                               Relauth XML Definition Guide
                Offline Request Type
                Some authorisations will be declined with a code 102 response, the message will be
                REFFERAL B or similar. These transactions may still be authorised using the offline request
                type. Merchants must manually obtain an authorisation code for transactions of this type.
                Typically, this involves contacting the acquiring bank's authorisation centre by phone.
                The offline transaction will be linked to the original transaction for which the REFERRAL B
                result was received. The original order ID and pasref are required.
                The following sections provide the information necessary to submit a valid offline request
                type:
                    Example
                    XML Syntax
                    Hash Value Syntax




Proprietary and Confidential Information of Realex                                                        17
                                                                                     Relauth XML Definition Guide
                Example

                   <request timestamp="20010427124312" type="offline">
                     <merchantid>merchantid</merchantid>
                     <account>subaccount</account>
                     <orderid>original-orderid</orderid>
                     <pasref>original realex paymentsRealex Payments reference</pasref>
                     <authcode>authcode from auth centre</authcode>
                     <comments>
                      <comment id="1">comment 1</comment>
                      <comment id="2">comment 2</comment>
                     </comments>
                     <sha1hash>7384ae67....ac7d7d</sha1hash>
                     <md5hash>34e7....a77d</md5hash>
                   </request>


                XML Syntax
                For each XML element or field, the following table provides the following information:
                     The syntax for the element or field
                     An indication of whether the element or field is mandatory (M), optional (O), or
                     conditional (C) depending on another optional field
                     The format for the value in terms of allowable characters or numbers
                     The allowable length of the value
                     A description
                                                 M/
   Element/Field                                         Format       Length          Description
                                                 O/C
   <request timestamp="YYYYMMDDHHMMSS"           M       0-9          14              Top-level element. Must have
   type="offline">                                                                    timestamp and type attributes.
   </request>                                                                         Timestamp must be in the
                                                                      type:offline
                                                                                      format YYYYMMDDHHMMSS,
                                                                                      which represents the time in the
                                                                                      format year month date hour
                                                                                      minute second.
                                                                                      If the timestamp is more than a
                                                                                      day (86400 seconds) away from
                                                                                      the server time, then the
                                                                                      request is rejected.
   <merchantid>merchantid</merchantid>           M       a-z A-Z 0-   1-50            Where merchantid represents
                                                         9.                           Realex Payments assigned
                                                                                      merchant id (not the merchant
                                                                                      number the bank will assign).
   <account>original-subaccount</account>        O       a-z A-Z 0-   0-30            Where original-subaccount
                                                         9""                          represents the Realex Payments
                                                                                      sub-account to use. An offline
                                                                                      request type must use the same
                                                                                      sub-account as the original
                                                                                      transaction.
   <orderid>original-orderid</orderid>           M       a-z A-Z 0-   1-40            Where original-orderid
                                                         9_-                          represents the unique order id of
                                                                                      the original transaction.




Proprietary and Confidential Information of Realex                                                                    18
                                                                               Relauth XML Definition Guide
   <pasref>original-realex-pasref</pasref>       M     a-z A-Z 0-    0-50        Where original-realex-pasref
                                                       9                         represents the Realex Payments
                                                                                 reference of the original
                                                                                 transaction,which was included
                                                                                 in the response.
   <authcode>authcode-from-authcentre</          M     a-z A-Z 0-    0-10        Where authcode-from-auth-
   authcode>                                           9                         centre represents the authcode
                                                                                 provided by the authorisation
                                                                                 centre.
   <comments></comments>                         O                               Optionally, up to two comments
                                                                                 can be associated with any
                                                                                 transaction.
   <comment id="1">a_comment</comment>           O     a-z A-Z 0-    0-255       Where a_comment represents a
                                                       9 ' ", + ""               free-text comment.
                                                       ._-&\/
                                                       @!?%(
                                                       )*:£$&
                                                       €#[]|
                                                       =
   <comment id="2">another comment</             O     a-z A-Z 0-    0-255       Where another comment
   comment>                                            9 ' ", + ""               represents a free-text comment.
                                                       ._-&\/
                                                       @!?%(
                                                       )*:£$&
                                                       €#[]|
                                                       =
   <sha1hash>SHA_1_hash</sha1hash>               M     a-f 0-9       40          Where SHA_1_hash represents
                                                                                 the SHA-1 hash of certain
                                                                                 elements of the request. For
                                                                                 more information, see the
                                                                                 Realauth Developer's Guide.
                                                                                 Either the SHA-1 hash or the
                                                                                 MD5 hash can be used.
   <md5hash>MD5_hash</md5hash>                   M     a-f 0-9       32          Where MD5_hash represents the
                                                                                 MD5 hash of certain elements of
                                                                                 the request. For more
                                                                                 information, see the Realauth
                                                                                 Developer's Guide.
                                                                                 Either the MD5 r the SHA-1 can
                                                                                 be used, however the SHA-1 is
                                                                                 recommended because it has
                                                                                 been proven to be more secure.

                Hash Value Syntax
                The following table illustrates the hash value syntax for the offline request type:


                 Format:        timestamp.merchantid.orderid...

                 Example:       20010427124312.merchantid.orderid...




Proprietary and Confidential Information of Realex                                                                19
                                                                                Relauth XML Definition Guide
                Rebate Request Type
                It is possible to process rebates through the realauth and realcontrol interfaces. A rebate is
                a refund to an existing successfully settled authorisation.
                In order to ensure a valid request via realauth, the following conditions must be met:
                    The order id, pasref, and authcode must match the values from the original transaction
                    Rebates are only available according to the following conditions:
                    — For between 0 to 115% of the value of the original transaction
                    — In the original currency
                    — For the same sub-account used in the original transaction
                The order id sent in the rebate request must be the original order id. A new order id is
                assigned by Realex Payments (specifically it will be the original transaction order id prefixed
                with _rebate_).
                For an extra layer of security, we require the rebate password to be passed in the XML in
                the refundhash XML element. This must be hashed using the SHA1 algorithm.
                The following sections provide the information necessary to submit a valid rebate request
                type:
                    Example
                    XML Syntax
                    Hash Value Syntax




Proprietary and Confidential Information of Realex                                                           20
                                                                                   Relauth XML Definition Guide
                Example

                   <request timestamp="20010427124312" type="rebate">
                    <merchantid>merchantid</merchantid>
                    <account>original-subaccount</account>
                    <orderid>original-orderid</orderid>
                    <pasref>original-realex-payments-pasref</pasref>
                    <authcode>original-authcode</authcode>
                    <amount currency="EUR">3000</amount>
                    <refundhash>738e83....3434ddae662a</refundhash>
                    <autosettle flag="1" />
                    <comments>
                     <comment id="1">comment 1</comment>
                     <comment id="2">comment 2</comment>
                    </comments>
                    <sha1hash>748328aed83....34789ade7</sha1hash>
                    <md5hash>738e83....34ae662a</md5hash>
                   </request>


                XML Syntax
                For each XML element or field, the following table provides the following information:
                    The syntax for the element or field
                    An indication of whether the element or field is mandatory (M), optional (O), or
                    conditional (C) depending on another optional field
                    The format for the value in terms of allowable characters or numbers
                    The allowable length of the value
                    A description
                                                 M/
   Element/Field                                        Format       Length         Description
                                                 O/C
   <request timestamp="YYYYMMDDHHMMSS"           M      0-9          14             Top-level element. Must have
   type="rebate">                                                                   timestamp and type attributes.
   </request>                                                                       Timestamp must be in the
                                                                     type:rebate
                                                                                    format YYYYMMDDHHMMSS,
                                                                                    which represents the time in the
                                                                                    format year month date hour
                                                                                    minute second.
                                                                                    If the timestamp is more than a
                                                                                    day (86400 seconds) away from
                                                                                    the server time, then the
                                                                                    request is rejected.
   <merchantid>merchantid</merchantid>           M      a-z A-Z 0-   1-50           Where merchantid represents
                                                        9.                          Realex Payments assigned
                                                                                    merchant id.
   <account>original-account</account>           O      a-z A-Z 0-   0-30           Where original-account
                                                        9""                         represents the Realex Payments
                                                                                    sub-account to use. For this
                                                                                    request type, the same sub-
                                                                                    account as the original
                                                                                    transaction must be used.




Proprietary and Confidential Information of Realex                                                                 21
                                                                           Relauth XML Definition Guide
   <orderid>original-orderid</orderid>           M   a-z A-Z 0-    1-40     Where original-orderid
                                                     9_-                    represents the unique order id of
                                                                            this transaction.
   <pasref>original-realex-pasref</pasref>       M   a-z A-Z 0-    0-50     Where original-realex-pasref
                                                     9                      represents the Realex Payments
                                                                            reference of the original
                                                                            transaction, which was included
                                                                            in the response.
   <authcode>original-authcode</authcode>        M   a-z A-Z 0-    0-10     Where original-authcode
                                                     9                      represents the authcode of the
                                                                            original transaction, which was
                                                                            included in the response.
   <amount currency="aaa">1234</amount>          M   a-z A-Z       3        Where aaa represents the
                                                     0-9           1-11     currency code (such as GPB) and
                                                                            1234 represents the amount of
                                                                            the transaction. The Realauth
                                                                            Developer's Guide has a
                                                                            complete list of the currency
                                                                            codes. The amount should be in
                                                                            the smallest unit of the required
                                                                            currency (For example: 2000 =
                                                                            £20, $20 or €20).
                                                                            Must be the same currency as
                                                                            used in the original transaction
                                                                            and may only be up to 115% of
                                                                            the original value.
   <refundhash>refund_hash</refundhash>          M   a-f 0-9       40       Where refund_hash represents a
                                                                            hash of the refund password,
                                                                            whichRealex Payments will
                                                                            provide. The SHA1 algorithm
                                                                            must be used to generate this
                                                                            hash.
   <autosettle flag="x" />                       M   1             1        Where x represents the value of
                                                     0                      the auto-settle indicator. If set to
                                                                            1, then the transaction will be
                                                                            included in today's settlement
                                                                            file. If set to 0, then the
                                                                            transaction will be authorised
                                                                            but not settled. Merchants must
                                                                            manually settle delayed
                                                                            transactions within 28 days of
                                                                            authorisation.
   <comments></comments>                         O                          Optionally, up to two comments
                                                                            can be associated with any
                                                                            transaction.
   <comment id="1">a_comment</comment>           O   a-z A-Z 0-    0-255    Where a_comment represents a
                                                     9 ' ", + ""            free-text comment.
                                                     ._-&\/
                                                     @!?%(
                                                     )*:£$&
                                                     €#[]|
                                                     =
   <comment id="2">another comment</             O   a-z A-Z 0-    0-255    Where another comment
   comment>                                          9 ' ", + ""            represents a free-text comment.
                                                     ._-&\/
                                                     @!?%(
                                                     )*:£$&
                                                     €#[]|
                                                     =
   <sha1hash>SHA_1_hash</sha1hash>               M   a-f 0-9       40       Where SHA_1_hash represents
                                                                            the SHA-1 hash of certain
                                                                            elements of the request.




Proprietary and Confidential Information of Realex                                                             22
                                                                              Relauth XML Definition Guide
   <md5hash>MD5_hash</md5hash>                   M    a-f 0-9     32            Where MD5_hash represents the
                                                                                MD5 hash of certain elements of
                                                                                the request. For more
                                                                                information, see the Realauth
                                                                                Developer's Guide.
                                                                                Either the MD5 or the SHA-1 can
                                                                                be used, however the SHA-1 is
                                                                                recommended because it has
                                                                                been proven to be more secure.

                Hash Value Syntax
                The following table illustrates the hash value syntax for the rebate request type:


                Format:        timestamp.merchantid.orderid.amount.currency.

                Example:       20010427124312.merchantid.orderid.3000.EUR.




Proprietary and Confidential Information of Realex                                                            23
                                                                                Relauth XML Definition Guide
                Void Request Type
                Before settlement, it is possible to void an authorisation, manual, offline, or rebate request.
                If the transaction has been settled or batched, then it cannot be voided, although it can be
                submitted using another authorisation or rebate.
                The following sections provide the information necessary to submit a valid void request
                type:
                    Example
                    XML Syntax
                    Hash Value Syntax




Proprietary and Confidential Information of Realex                                                           24
                                                                                  Relauth XML Definition Guide
                Example

                   <request timestamp="20010427014523" type="void">
                     <merchantid>merchantid</merchantid>
                     <account>original-subaccount</account>
                     <orderid>original-orderid</orderid>
                     <pasref>original-realex-payments-pasref</pasref>
                     <authcode>original-authcode</authcode>
                     <comments>
                      <comment id="1">comment 1</comment>
                      <comment id="2">comment 2</comment>
                     </comments>
                     <sha1hash>7384ae67....ac7d7d</sha1hash>
                     <md5hash>34e7....a77d</md5hash>
                   </request>


                XML Syntax
                For each XML element or field, the following table provides the following information:
                     The syntax for the element or field
                     An indication of whether the element or field is mandatory (M), optional (O), or
                     conditional (C) depending on another optional field
                     The format for the value in terms of allowable characters or numbers
                     The allowable length of the value
                     A description
                                                 M/
   Element/Field                                         Format       Length       Description
                                                 O/C
   <request timestamp="YYYYMMDDHHMMSS"           M       0-9          14           Top-level element. Must have
   type="void">                                                                    timestamp and type attributes.
   </request>                                                                      Timestamp must be in the
                                                                      type:void
                                                                                   format YYYYMMDDHHMMSS,
                                                                                   which represents the time in the
                                                                                   format year month date hour
                                                                                   minute second.
                                                                                   If the timestamp is more than a
                                                                                   day (86400 seconds) away from
                                                                                   the server time, then the
                                                                                   request is rejected.
   <merchantid>merchantid</merchantid>           M       a-z A-Z 0-   1-50         Where merchantid represents
                                                         9.                        Realex Payments assigned
                                                                                   merchant id.
   <account>sub-account</account>                O       a-z A-Z 0-   0-30         Where sub-account represents
                                                         9""                       the Realex Payments sub-
                                                                                   account to use. For this request
                                                                                   type, the same sub-account as
                                                                                   the original transaction must be
                                                                                   used.
   <orderid>original-orderid</orderid>           M       a-z A-Z 0-   1-40         Where original-orderid
                                                         9_-                       represents the unique order id of
                                                                                   this transaction.




Proprietary and Confidential Information of Realex                                                                    25
                                                                               Relauth XML Definition Guide
   <pasref>original-realex-pasref</pasref>       M    a-z A-Z 0-    0-50        Where original-realex-pasref
                                                      9                         represents the Realex Payments
                                                                                reference of the original
                                                                                transaction, which was included
                                                                                in the response.
   <authcode>original-authcode</authcode>        M    a-z A-Z 0-    0-10        Where original-authcode
                                                      9                         represents the authcode of the
                                                                                original transaction, which was
                                                                                included in the response.
   <comments></comments>                         O                              Optionally, up to two comments
                                                                                can be associated with any
                                                                                transaction.
   <comment id="1">a_comment</comment>           O    a-z A-Z 0-    0-255       Where a_comment represents a
                                                      9 ' ", + ""               free-text comment.
                                                      ._-&\/
                                                      @!?%(
                                                      )*:£$&
                                                      €#[]|
                                                      =
   <comment id="2">another comment</             O    a-z A-Z 0-    0-255       Where another comment
   comment>                                           9 ' ", + ""               represents a free-text comment.
                                                      ._-&\/
                                                      @!?%(
                                                      )*:£$&
                                                      €#[]|
                                                      =
   <sha1hash>SHA_1_hash</sha1hash>               M    a-f 0-9       40          Where SHA_1_hash represents
                                                                                the SHA-1 hash of certain
                                                                                elements of the request.
   <md5hash>MD5_hash</md5hash>                   M    a-f 0-9       32          Where MD5_hash represents the
                                                                                MD5 hash of certain elements of
                                                                                the request.

                Hash Value Syntax
                The following table illustrates the hash value syntax for the void request type:


                 Format:        timestamp.merchantid.orderid.amount.currency.cardnumber

                 Example:       20010427014523.merchantid.orderid...




Proprietary and Confidential Information of Realex                                                                26
                                                                              Relauth XML Definition Guide
                TSS Request Type
                The TSS request will not carry out an authorisation; it will only return the Transaction
                Suitability Score for the transaction. This score will be determined based on the merchant's
                realscore rules. For information on realscore, see the Realscore Developer's Guide.
                For a line-by-line analysis, please see the Auth Request Type section.
                The following sections provide the information necessary to submit a valid void request
                type:
                    Example
                    XML Syntax
                    Hash Value Syntax




Proprietary and Confidential Information of Realex                                                        27
                                                                     Relauth XML Definition Guide
                Example

                   <request timestamp="20010427124523" type="tss">
                    <merchantid>merchantid</merchantid>
                    <account>subaccount</account>
                    <orderid>orderid</orderid>
                    <amount currency="GBP">2000</amount>
                    <card>
                     <number>490303400005718902</number>
                     <expdate>0403</expdate>
                     <chname>John Doe</chname>
                     <type>SWITCH</type>
                     <issueno>1</issueno>
                     <cvn>
                       <number>453</number>
                       <presind>1</presind>
                     </cvn>
                    </card>
                    <autosettle flag="1" />
                    <comments>
                     <comment id="1">a comment</comment>
                     <comment id="2">another comment</comment>
                    </comments>
                    <tssinfo>
                     <custnum>customer number</custnum>
                     <prodid>product id</prodid>
                     <varref>variable reference</varref>
                     <address type="billing">
                       <code>zip/postal code</code>
                       <country>country</country>
                     </address>
                     <address type="shipping">
                       <code>zip/postal code</code>
                       <country>country</country>
                     </address>
                    </tssinfo>
                    <sha1hash>4dc4f20acc….30314758a1bc</sha1hash>
                    <md5hash>67dcc….787307</md5hash>
                   </request>




Proprietary and Confidential Information of Realex                                            28
                                                                              Relauth XML Definition Guide
                Hash Value Syntax
                The following table illustrates the hash value syntax for the TSS request type:


                Format:        timestamp.merchantid.orderid.amount.currency.cardnumber

                Example:       20010427124523.merchantid.orderid.2000.GBP.490303400005718902




Proprietary and Confidential Information of Realex                                                     29
                                                                                                   Relauth XML Definition Guide
                  Settle Request Type
                  This request type is used to settle delayed settlement transactions. This must be done
                  within 28 days of the initial authorisation. These transactions can be settled for 0 - 115% of
                  the original authorisation amount.

    Caution: For delayed settlement transactions, no funds will move from the cardholder's account to the merchant account unless
    the transaction is explicitly settled. Merchants must contact their acquiring bank to ensure they are compliant with the bank's rules
    on delaying settlement.


    Note:3DSecure transactions must be settled for the original authorisation amount to avail of the liability shift. For more
    information, see the RealMPI Developers Guide or e-mail support@realexpayments.com


                  The following sections provide the information necessary to submit a valid settle request
                  type:
                       Example
                       XML Syntax
                       Hash Value Syntax




Proprietary and Confidential Information of Realex                                                                                     30
                                                                                    Relauth XML Definition Guide
                Example

                   <request timestamp="20010427014523" type="settle">
                     <merchantid>merchantid</merchantid>
                     <account>subaccount</account>
                     <orderid>original-orderid</orderid>
                     <pasref>original-realex-payments-pasref</pasref>
                     <authcode>original-authcode</authcode>
                     <comments>
                      <comment id="1">comment 1</comment>
                      <comment id="2">comment 2</comment>
                     </comments>
                     <sha1hash>7384ae67....ac7d7d</sha1hash>
                     <md5hash>34e7....a77d</md5hash>
                   </request>


                XML Syntax
                For each XML element or field, the following table provides the following information:
                     The syntax for the element or field
                     An indication of whether the element or field is mandatory (M), optional (O), or
                     conditional (C) depending on another optional field
                     The format for the value in terms of allowable characters or numbers
                     The allowable length of the value
                     A description
                                                 M/
   Element/Field                                         Format       Length         Description
                                                 O/C
   <request timestamp="YYYYMMDDHHMMSS"           M       0-9          14             Top-level element. Must have
   type="settle">                                                                    timestamp and type attributes.
   </request>                                                                        Timestamp must be in the
                                                                      type:settle
                                                                                     format YYYYMMDDHHMMSS,
                                                                                     which represents the time in the
                                                                                     format year month date hour
                                                                                     minute second.
                                                                                     If the timestamp is more than a
                                                                                     day (86400 seconds) away from
                                                                                     the server time, then the
                                                                                     request is rejected.
   <merchantid>merchantid</merchantid>           M       a-z A-Z 0-   1-50           Where merchantid represents
                                                         9.                          Realex Payments assigned
                                                                                     merchant id (not the merchant
                                                                                     number that the bank will
                                                                                     assign).
   <account>sub-account</account>                O       a-z A-Z 0-   0-30           Where sub-account represents
                                                         9""                         the Realex Payments sub-
                                                                                     account to use. For this request
                                                                                     type, the same sub-account as
                                                                                     the original transaction must be
                                                                                     used.
   <orderid>original-orderid</orderid>           M       a-z A-Z 0-   1-40           Where original-orderid
                                                         9_-                         represents the unique order id of
                                                                                     this transaction.




Proprietary and Confidential Information of Realex                                                                      31
                                                                               Relauth XML Definition Guide
   <pasref>original-realex-pasref</pasref>       M     a-z A-Z 0-    0-50       Where original-realex-pasref
                                                       9                        represents the Realex Payments
                                                                                reference of the original
                                                                                transaction, which was included
                                                                                in the response.
   <authcode>original-authcode</authcode>        M     a-z A-Z 0-    0-10       Where original-authcode
                                                       9                        represents the authcode of the
                                                                                original transaction, which was
                                                                                included in the response.
   <comments></comments>                         O                              Optionally, up to two comments
                                                                                can be associated with any
                                                                                transaction.
   <comment id="1">a_comment</comment>           O     a-z A-Z 0-    0-255      Where a_comment represents a
                                                       9 ' ", + ""              free-text comment.
                                                       ._-&\/
                                                       @!?%(
                                                       )*:£$&
                                                       €#[]|
                                                       =
   <comment id="2">another comment</             O     a-z A-Z 0-    0-255      Where another comment
   comment>                                            9 ' ", + ""              represents a free-text comment.
                                                       ._-&\/
                                                       @!?%(
                                                       )*:£$&
                                                       €#[]|
                                                       =
   <sha1hash>SHA_1_hash</sha1hash>               M     a-f 0-9       40         Where SHA_1_hash represents
                                                                                the SHA-1 hash of certain
                                                                                elements of the request. For
                                                                                more information, see the
                                                                                Realauth Developer's Guide.
                                                                                Either SHA-1 or the MD5 can be
                                                                                used.
   <md5hash>MD5_hash</md5hash>                   M     a-f 0-9       32         Where MD5_hash represents the
                                                                                MD5 hash of certain elements of
                                                                                the request. For more
                                                                                information, see the Realauth
                                                                                Developer's Guide. Either the
                                                                                MD5 or the SHA-1 can be used,
                                                                                but the SHA-1 hash is
                                                                                recommended because it has
                                                                                been proven to be more secure.

                Hash Value Syntax
                The following table illustrates the hash value syntax for the settle request type:


                 Format:        timestamp.merchantid.orderid...

                 Example:       20010427014523.merchantid.orderid...




Proprietary and Confidential Information of Realex                                                                32
                                                                                 iDEAL Developer’s Guide

            Responses

            Realex Payments uses the following two response classes:
                Full: A full response will be returned if the data included in the transaction request was
                valid and it was possible to process the request.
                Basic: A basic response will be returned if the transaction could not be processed for
                any reason. The reason will be given in the response message.
            For a full list of result codes, refer to the Realauth Developer's Guide.

            Result Codes That Return Full Responses

                RESULT        MESSAGE
                00            Successful Transaction
                1xx           Bank errors
                2xx           EPoS errors

            Result Codes That Only Return Code And Message

                RESULT        MESSAGE
                3xx           Realex Payments errors
                5xx           Developer/Data errors




Responses                                                                                               33
About Realex Payments


               About 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.
               Realex Payments operate a number of international web sites including the following:
               www.realexpayments.com, www.realexpayments.co.uk, www.airlinepayments.com, and
               www.sepa.ie. These are leading web sites designed to provide industry information for
               specific payment areas. SEPA is the Single European Payments Area and it is an important
               development in the context of European payments. The www.airlinepayments.com web site
               provides an overview of the strategic payment processing issues facing airlines today.




Proprietary and Confidential Information of Realex                                                         34

								
To top