Realauth XML Definitions Guide

Version 1.3

Table of Contents
Table of Contents................................................................................................................................................................... 1 Table of Contents................................................................................................................................................................... 2 Introduction to Realex Payments ......................................................................................................................................... 3 1 2 3 Realex Services .............................................................................................................................................................. 4 Introduction ................................................................................................................................................................... 4 Requests ......................................................................................................................................................................... 5 3.1 3.2 3.3 3.4 3.5 3.6 3.7 4 Auth Request Type ..................................................................................................................................... 5 Manual Request Type ............................................................................................................................... 8 Offline Request Type............................................................................................................................... 11 Rebate Request Type .............................................................................................................................. 13 Void Request Type.................................................................................................................................... 15 realscore Request Type......................................................................................................................... 16 Settle Request Type................................................................................................................................. 17

Responses ..................................................................................................................................................................... 19 4.1 4.2 4.3 Result codes that will return full responses............................................................................ 19 Result codes that will only return code and message....................................................... 19 Response Format....................................................................................................................................... 20

5

Contact details. ............................................................................................................................................................ 22

Appendix A – Version Control............................................................................................................................................ 22

Page 2 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

Introduction to Realex Payments
Thank you for your interest in our service. Realex Payments build and manage payment exchanges for businesses, merchants and banks. We provide a range of real time services in the area of card authorisation, fraud scoring, electronic funds transfer, foreign exchange, reporting and reconciliation tools and payer authentication. Certified and approved by many leading financial institutions, these services are designed to eliminate overhead for banks and merchants selling in call/contact centres or via the internet. We may be contacted by any of the following methods: Address The Forum 29/31 Glasthule Road Glasthule Co Dublin Ireland + 353 (0)1 280 8559 + 353 (0)1 280 8538 sales@realexpayments.com support@realexpayments.com www.realexpayments.com

Telephone Fax Sales email Support email Web Site

Please note that this document is regarded as confidential and it is for customer use only. It has been supplied under the conditions of your payment-processing contract. Pay and Shop Limited, trading as Realex Payments has its registered office at 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland and is registered in Ireland, company number 324929.

Page 3 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

1 Realex Services
Realex Payments offer a range of payment and financial services to banks, internet and call centre merchants. Our core business is the creation and running of payment exchanges that link banks with their customers via the internet.

We provide the following: ♦ ♦ ♦ ♦ ♦ ♦ ♦ Real time credit and debit card authorisation services. Real time fraud scoring and pattern checking services. A direct debit and recurring credit card payment service. A link to third party providers who offer dynamic currency conversion services. Payer authentication services for merchants and banks. Multi channel reporting and management tools. White labelled and customised payment exchanges.

Should you be interested in learning more about any of these services we would be delighted to hear from you.

2 Introduction
Although the sample code available provides a simple interface to the system, more complex implementations will require some knowledge of how the system works. Again, the Realauth XML definitions guide should be consulted for full details on the messages required. The following indicators are used to show whether or not an element is required or optional. R O R Required for this request type Optional Required depending on another optional field

For each element of the XML the length and format of the field is given in the following fashion: A N S V Alpha/Character (A-Za-z “ ” - _) Numeric (0-9) Special Characters (@ / ~ etc..) Variable length

For example: AN50V – Alpha Numeric field, up to 50 characters in length N3 – Numeric field, exactly 3 characters in length

Page 4 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

3 Requests
There are seven realauth request types. The main request type is the auth request type, which is used to obtain an authorisation for a particular debit or credit card. The remaining request types are manual, offline, rebate, void, realscore and settle. These request types are explained below.

3.1 Auth Request Type
Below is a sample of an auth request followed by a line-by-line analysis. The auth request is the primary request used with realauth.
<request timestamp="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>

SHA1 Initial Hash String

timestamp.merchantid.orderid.amount.currency.cardnumber Example for this request: 20010427124523.merchantid.orderid.2000.GBP.490303400005718902 Page 5 - Version 1.2.2 Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

<request timestamp="20010427124523" type="auth">

R

N14/ AN50V

<merchantid>merchantid</merchantid>

R

AN50V

<account>subaccount</account>

O

AN30V

<orderid>orderid</orderid>

R

AN50V

<amount currency="GBP">2000</amount>

R

A3/ N10V

<card> <number>490303400005718902</number> <expdate>0403</expdate> <chname>John Doe</chname> <type>SWITCH</type>

R R R R R N19V N4 AN100V A20V

<issueno>1</issueno>

Ro

N2V

<cvn>

O

<number>453</number>

Ro

N4V

<presind>1</presind>

Ro

N1

Top-level element. Must have timestamp and type attributes. If the timestamp is more than a day (86400 seconds) away from the server time then the request is rejected. This is your realex payments assigned merchant id This is the realex payments subaccount to use. If you omit this element then we will use your default account The unique order id of this transaction. Must be unique across all of your subaccounts. The currency and amount of the transaction. Appendix B of the realauth developer’s guide specifies the currency codes. The amount should be in the smallest unit of the required currency (i.e. 2000 = £20, $20 or €20) There must be a card element in auth requests The card number. The card expiry date. The format is mmyy The card holder’s name. The card type. The legal values are: VISA, MC, AMEX, LASER, SWITCH, DINERS The issue number of the card in the case of a Switch card. Only required if the card type is SWITCH The card verification details element. If you use this then the next two elements are required. The Card Verification Number. This is the 3 digit number on the reverse of the card. (the CVC for VISA and the CVV2 for MasterCard) This is the presence indicator. It can take 4 values: 1: cvn present 2: cvn illegible 3: cvn not on card 4: cvn not requested

</cvn> </card> The auto-settle indicator. If “1” then the transaction will be sent to the bank for settlement tonight. If set to “0” then the transaction will remain in the realex payment’s database for 28 days or until manually settled. You can associate up to 2 comments with any transaction for your own purposes. Free-text comment Free-text comment

<autosettle flag="1" />

R

N1

<comments> <comment id="1">a comment</comment> <comment id="2">another comment</comment> </comments>

O O O AN255V AN255V

Page 6 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

<tssinfo>

O

<custnum>customer number</custnum> <prodid>product id</prodid>

O O

ANS50V ANS50V

<varref>variable reference</varref> <custipaddress>www.xxx.yyy.zzz</custipaddress> <address type="billing"> <code>zip/postal code</code>

O O O O

ANS50V AN14V

AN30V

<country>country</country> </address> <address type="shipping"> <code>zip/postal code</code>

O

AN2V

As part of the realex payment’s service we offer a realscore. This is a real time transaction screening and data checking system to assist the merchant with the identification of potentially high-risk transactions. The number you assign to the customer. This can allow checking of previous transactions by this customer. The product code you assign to the product. Any reference you also would like to assign to the customer. This can allow checking, using realscore, of previous transactions by this customer. The IP address of the customer The billing address of the customer. The ZIP/Postal code of the billing address. This can be checked (in conjunction with the country) against a table of high-risk area codes. The country of the billing address. This can be checked against a table of highrisk countries. The shipping address of the customer. The ZIP/Postal code of the shipping address. This can be checked (in conjunction with the country) against a table of high-risk area codes. The country of the shipping address. This can be checked against a table of high-risk countries.

O O AN30V

<country>country</country> </address> </tssinfo>

O

AN2V

<sha1hash>4dc4f20acc….30314758a1bc</sha1hash>

R

AN40

<md5hash>67dcc….787307</md5hash> </request>

R

AN32

The SHA-1 hash of certain elements of the request. The details of this are to be found in the realauth developer’s guide. Either this or the MD5 may be used. The MD5 hash of certain elements of the request. The details of this are to be found in the realauth developer’s guide.

Page 7 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

3.2 Manual Request Type
If for any reason you are unable to get an authorisation through the realex payments authorisation system, e.g. your internet connection is unavailable, you may get an authcode directly from your acquiring banks authorisation centre by phone. Once your internet connection is restored you can send a manual authorisation request (including the authcode that you received from the authorisation centre) to realex payments. This request is not allowed by default, and realex payments may require confirmation from your bank to allow you to use this facility. Below is a sample of a manual authorisation request followed by a line-by-line analysis.

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

Page 8 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

SHA1 Initial Hash String

timestamp.merchantid.orderid.amount.currency.cardnumber Example for this request: 20010427124523.merchantid.orderid.2000.GBP.490303400005718902
Top-level element. Must have timestamp and type attributes. If the timestamp is more than a day (86400 seconds) away from the server time then the request is rejected. This is your realex payments assigned merchant id (not the merchant number that the bank will assign you) This is the realex payments subaccount to use. If you omit this element then we will use your default account The unique order id of this transaction. Must be unique across all of your accounts. The authcode you received from the voice authorisation centre, or alternative source. The currency and amount of the transaction. Appendix B of the realex developer’s guide specifies the currency codes. The amount should be in the smallest unit of the required currency (i.e. 2000 = £20, $20 or €20) There must be a card element in auth requests The card number. The card expiry date. The format is mmyy The card holder’s name. The card type. The legal values are: VISA, MC, AMEX, LASER, SWITCH, DINERS The issue number of the card in the case of a Switch card. Only required if the card type is SWITCH The card verification details element. If you use this then the next two elements are required. The Card Verification Number. This is the 3 digit number on the reverse of the card. (the CVC for VISA and the CVV2 for MasterCard) This is the presence indicator. It can take 4 values: 1: cvn present 2: cvn illegible 3: cvn not on card 4: cvn not requested In practise this is generally a drop down box that the cardholder can select the appropriate value from.

<request timestamp="20010427124523" type="manual">

R

N14/ AN50V

<merchantid>merchantid</merchantid>

R

AN50V

<account>subaccount</account>

O

AN30V

<orderid>orderid</orderid>

R

AN50V

<authcode>authcode</authcode>

R

AN10V

<amount currency="GBP">2000</amount>

R

A3/ N10V

<card> <number>490303400005718902</number> <expdate>0403</expdate> <chname>John Doe</chname> <type>SWITCH</type>

R R R R R N19V N4 AN100V A20V

<issueno>1</issueno>

Ro

N2V

<cvn>

O

<number>453</number>

Ro

N4V

<presind>1</presind>

Ro

N1

Page 9 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

</cvn> </card> The auto-settle indicator. If “1” then the transaction will be sent to the bank for settlement tonight. If set to “0” then the transaction will sit in the realex payment’s database until someone manually submits it for settlement You can associate up to 2 comments with any transaction for your own purposes. Free-text comment Free-text comment As part of the realex payment’s service we offer a realscore. This is a real time transaction screening and data checking system to assist the merchant with the identification of potentially high-risk transactions. The number you assign to the customer. This can allow checking of previous transactions by this customer. The product code you assign to the product. Any reference you also would like to assign to the customer. This can allow checking of previous transactions by this customer. The billing address of the customer. The ZIP/Postal code of the billing address. The country of the billing address. This can be checked against a table of high-risk counties. The shipping address of the customer. The ZIP/Postal code of the shipping address. The country of the shipping address. This can be checked against a table of high-risk counties.

<autosettle flag="1" />

R

N1

<comments> <comment id="1">a comment</comment> <comment id="2">a comment</comment> </comments>

O O O AN255V AN255V

<tssinfo>

O

<custnum>customer number</custnum>

O

ANS50V

<prodid>product id</prodid>

O

ANS50V

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

O O O O

ANS50V

AN30V AN2V

O O O AN30V AN2V

R R

AN40 AN32

The SHA-1 hash The MD5 hash.

Page 10 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

3.3 Offline Request Type
In some cases, you bank may reject a transaction with the error: 101 / REFERRAL B or CONTACT AUTH CENTRE. In this case there may not be a problem with the card, but because of the large amount being authorised or the location of the merchant they would prefer to speak to the merchant before authorising the card. You can call your authorisation centre and request an authcode for these transactions. You may then use the Offline authorisation request type to complete the transaction. The offline transaction will be linked to the original transaction for which the 101 / REFERRAL B or CONTACT AUTH CENTRE result was received. You will need to have the original order ID and pasref available. Below is a sample of an offline request followed by a line-by-line analysis.

<request timestamp="20010427124312" type="offline"> <merchantid>merchantid</merchantid> <account>subaccount</account> <orderid>original-orderid</orderid> <pasref>original realex 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>

SHA1 Initial Hash String

timestamp.merchantid.orderid... Example for this request: 20010427124312.merchantid.orderid...
Top-level element. Must have timestamp and type attributes. If the timestamp is more than a day (86400 seconds) away from the server time then the request is rejected. This is your realex payments assigned merchant id (not the merchant number that the bank will assign you) This is the realex payments subaccount to use. For this request type you must use the same sub-account as the original transaction. The unique order id of the original transaction. The realex payments reference of the original transaction (this was

<request timestamp="20010427014523" type="offline">

R

N14/ AN50V

<merchantid>merchantid</merchantid>

R

AN50V

<account>original-subaccount</account>

O

AN30V

<orderid>original-orderid</orderid> <pasref>original-realex-pasref</pasref>

R R

AN50V AN40V

Page 11 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

<authcode>authcode-from-auth-centre</authcode> <comments> <comment id="1">comment 1</comment> <comment id="2">comment 2</comment> </comments>

R O O O

AN10V

AN255V AN255V

included in the response). The authcode given to you by the authorisation centre. You can associate up to 2 comments with any transaction for your own purposes. Free-text comment Free-text comment The SHA-1 hash of certain elements of the request. The details of this are to be found in the epage integration guide. Either this or the MD5 may be used. The MD5 hash of certain elements of the request. The details of this are to be found in the epage integration guide. Either this or the SHA-1 may be used (however we do suggest you use the SHA-1 hash as it has been proven to be more secure).

<sha1hash>7384ae67....ac7d7d</sha1hash>

R

AN40

<md5hash>34e7....a77d</md5hash>

R

AN32

</request>

Page 12 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

3.4 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. You may only rebate: 0 to 115% of the value of the original transaction; using the original currency; using the same sub-account used in the original transaction; The order id you send 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_). (These conditions are not required when processing refunds via the realcontrol interface.) 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. Below is a sample of a rebate request followed by a line-by-line analysis.
<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>

SHA1 Initial Hash String

timestamp.merchantid.orderid.amount.currency. Example for this request: 20010427124312.merchantid.orderid.3000.EUR.

Page 13 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

<request timestamp="20010427124312" type="rebate">

R

N14/ AN50V

<merchantid>merchantid</merchantid>

R

AN50V

<account>original-account</account>

O

AN30V

<orderid>original-orderid</orderid> <pasref>original-realex- pasref</pasref>

R R

AN50V AN40V

<authcode>original-authcode</authcode>

R

AN10V

<amount currency="EUR">3000</amount>

R

A3/ N10V

<refundhash>738e83....3434ddae662a</refundhash>

R

AN40

<autosettle flag="1" />

R

N1

Top-level element. Must have timestamp and type attributes. If the timestamp is more than a day (86400 seconds) away from the server time then the request is rejected. This is your realex payments assigned merchant This is the realex payments subaccount to use. For this request type you must use the same sub-account as the original transaction. The unique order id of the original transaction. The realex payments reference of the original transaction (this was included in the response). The authcode of the original transaction (this was included in the response). The currency and amount of the transaction. Appendix B of the realauth developer’s guide specifies the currency codes. The amount should be in the smallest unit of the required currency (i.e. 2000 = £20, $20, 20 euros or 2000 lire). Must be the same currency as used in the original transaction and may only be up to 115% of the original value. This is a hash of the refund password (realex payments will give this to you). The SHA1 algorithm must be used to generate this hash. The auto-settle indicator. If “1” then the transaction will be sent to the bank for settlement tonight. If set to “0” then the transaction will sit in the realex payments database until someone manually submits it for settlement. For rebates you will generally set this to “1”. Free-text comment Free-text comment The SHA-1 hash of certain elements of the request. The MD5 hash of certain elements of the request. hash as it has been proven to be more secure).

<comments> <comment id="1">comment 1</comment> <comment id="2">comment 2</comment> </comments> <sha1hash>748328aed83....34789ade7</sha1hash> <md5hash>738e83....34ae662a</md5hash> </request>

O O O R R

AN255V AN255V AN40 AN32

Page 14 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

3.5 Void Request Type
Below is a sample of a void request followed by a line-by-line analysis.
<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>

SHA1 Initial Hash String

timestamp.merchantid.orderid.amount.currency.cardnumber Example for this request: 20010427014523.merchantid.orderid... It is possible to void an authorisation, manual, offline or rebate request, before settlement. If the transaction has been settled or batched then it cannot be voided and you can either submit another authorisation or rebate.
Top-level element. Must have timestamp and type attributes. If the timestamp is more than a day (86400 seconds) away from the server time then the request is rejected. This is your realex payments assigned merchant id. This is the realex payments subaccount to use. For this request type you must use the same sub-account as the original transaction. The original order id of the transaction. The realex payments reference of the original transaction. The authcode of the original transaction (this was included in the response). You can associate up to 2 comments with any transaction. Free-text comment Free-text comment The SHA-1 hash of certain elements of the request. The MD5 hash of certain elements of the request.

<request timestamp="20010427014523" type="void">

R

N14/ AN50V

<merchantid>merchantid</merchantid>

R

AN50V

<account>sub-account</account> <orderid>original-orderid</orderid> <pasref>original-realex-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>

O R R R O O O R R

AN30V AN50V AN40V AN10V

AN255V AN255V AN40 AN32

Page 15 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

3.6 realscore Request Type
Below is a sample of a realscore request.

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

SHA1 Initial Hash String

timestamp.merchantid.orderid.amount.currency.cardnumber Example for this request: 20010427124523.merchantid.orderid.2000.GBP.490303400005718902 This is exactly the same format as an auth request (only the type attribute of the request has changed). The only difference between an auth request and a realscore request is that no auth is performed for a realscore request. Only the realscore and the results of the individual checks are returned. For a line-by-line analysis please see the auth request type (section 3.1).

Page 16 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

3.7 Settle Request Type
This only applies to transactions that were sent to realex payments with the autosettle flag off. Transactions with the autosettle flag set to 1 will settle automatically the next day. Below is a sample of a settle request followed by a line-by-line analysis.

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

SHA1 Initial Hash String

timestamp.merchantid.orderid... Example for this request: 20010427014523.merchantid.orderid...

The settle request is used to capture a transaction that has previously been authorised using an auth request with the autosettle flag turned off (set to “0” or “off”). Transactions with the autosettle flag off (known as “delayed transactions”) will sit in the database forever unless you explicitly request that it be settled using the settle request OR void it using a void request. NB – no funds will move from the cardholder’s account to the merchant account unless the transaction is settled manually using the realcontrol application or programmatically using a settle request. This only applies to delayed transactions. Depending on the bank, delayed transactions will only be valid for a certain number of days (ranging from 3 days to 10 days in most cases). After this time the settle request may fail and you will need to re-authorise the transaction again. Transactions can be settled for 0 – 115% of the originally authorised amount. Note – If you are processing 3DSecure transactions you will need to settle for the same amount as the initial authorisation. For more details on 3DSecure transactions, see the RealMPI Developers Guide or e-mail support@realexpayments.com It is possible to void a delayed authorisation request at any time before settlement.

Page 17 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

<request timestamp="20010427014523" type="settle">

R

N14/ AN50V

<merchantid>merchantid</merchantid>

R

AN50V

<account>sub-account</account>

O

AN30V

<orderid>original-orderid</orderid> <pasref>original-realex-pasref</pasref> <authcode>original-authcode</authcode> <comments> <comment id="1">comment 1</comment> <comment id="2">comment 2</comment> </comments> <sha1hash>7384ae67....ac7d7d</sha1hash>

R R R O O O

AN50V AN40V AN10V

AN255V AN255V

Top-level element. Must have timestamp and type attributes. If the timestamp is more than a day (86400 seconds) away from the server time then the request is rejected. This is your realex payments assigned merchant id (not the merchant number that the bank will assign you) This is the realex payments sub-account to use. For this request type you must use the same sub-account as the original transaction. The unique order id of the original transaction. The realex payments reference of the original transaction (this was included in the response). The authcode of the original transaction (this was included in the response). You can associate up to 2 comments with any transaction for your own purposes. Free-text comment Free-text comment The SHA-1 hash of certain elements of the request. The details of this are to be found in the realauth developer’s guide. Either this or the MD5 may be used. The MD5 hash of certain elements of the request. The details of this are to be found in realauth developer’s guide. Either this or the SHA-1 may be used (however we do suggest you use the SHA-1 hash as it has been proven to be more secure).

R

AN40

<md5hash>34e7....a77d</md5hash>

R

AN32

</request>

Page 18 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

4 Responses
A response will be returned for every request sent to Realex. There are two different response classes that can be returned: Full responses and basic responses. The details of the response messages are given below. Depending on how far the request has progressed before the response is generated you will or will not receive a hash in the response. For example – if you use the wrong merchant id, there is no way for us to retrieve your shared secret and create the hash. You will only receive a full response if the request is valid (i.e. the xml is properly formatted, the data is within legal limits, the information in the data is legal etc…). Therefore your application must cater for both full and basic responses. You can find a full list of result codes in the Appendix of the realauth developer’s guide.

4.1 Result codes that will return full responses
00 1xx 2xx Successful Transaction Bank errors EPoS errors

4.2 Result codes that will only return code and message
3xx 5xx Realex payments errors Developer/Data errors

Page 19 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

4.3 Response Format
The full version of the response is shown below, followed by the short version and a line-byline description. Full response:

<response timestamp="20010427043422"> <merchantid>merchantid</merchantid> <account>subaccount</account> <orderid>orderid-from-request</orderid> <authcode>authcode-received</authcode> <result>00</result> <message>message-returned-from-system</message> <pasref>realex-pasref</pasref> <cvnresult>M</cvnresult> <batchid>batchid-for-this-transaction</batchid> <cardissuer> <bank>Issuing Bank Name</bank> <country>Issuing Bank Country</country> <countrycode>Issuing Bank Country Code</countrycode> <region>Issuing Bank Region</region> </cardissuer> <tss> <result>89</result> <check id="1000">9</check> <check id="1001">9</check> … </tss> <sha1hash>7384ae67....ac7d7d</sha1hash> <md5hash>34e7....a77d</md5hash> </response>

SHA1 Initial Hash String

timestamp.merchantid.orderid.result.message.pasref.authcode Example for this request: 20010427043422.merchantid.orderid-from-request.00.message-returned.realex-pasref.authcode-received

Basic response:

<response timestamp="20010427043422"> <result>508</result> <message>message returned from system</message> </response>

Page 20 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

<response timestamp="20010427043422"> <merchantid>merchant id used</merchantid> <account>account used</account> <orderid>order id used</orderid>

R R R R

N14 AN50V AN30V AN50V

<authcode>authcode received</authcode>

R

AN10V

<result>00</result> <message>message returned from system</message>

R R

N3V AN100V

<pasref> realex payments reference</pasref>

R

AN40V

<cvnresult>M</cvnresult>

R

A1

<batchid>batch id</batchid>

R

AN10V

<cardissuer> <bank>Issuing Bank Name</bank> <country>Issuing Bank Country</country> <countrycode>Issuing Bank Co Code</countrycode>

R R R R AN100V AN40V AN2

<region>Issuing Bank Region</region> </cardissuer> <tss> <result>67</result>

R R O R

AN20V

Top-level element. Will have timestamp attribute. This is the realex payments assigned merchant id used. This is the realex payments account used. The order id of the request. Used when referencing this transaction in refund and void requests. If successful there will be an authcode returned from the bank. Used when referencing this transaction in refund and void requests. The authcode of the original transaction (this was included in the response). The text of the response. Will contain the authcode if successful or the error message if not. The realex payments reference for the transaction. Used when referencing this transaction in refund and void requests. The result of the Card Verification check: M: CVV Matched N: CVV Not Matched I: CVV Not checked due to circumstances U: CVV Not checked – issuer not certified P: CVV Not Processed The batch id of the transaction. Returned in the case of auth and refund requests. This can be used to assist with the reconciliation of your batches. The Details of the cardholder’s bank (if available) The Bank Name (e.g. First Data Bank) The Bank Country in English (e.g. UNITED STATES) The country code of the issuing bank (e.g. US) The region the card was issued (e.g. US) Can be MEA (Middle East/Asia), LAT (Latin America), US (United States), EUR (Europe), CAN (Canada), A/P (Asia/Pacific) The results of realscore The weighted total score of realscore. You may adjust the weights in the realcontrol application. The result of realscore check number xxxx. You can choose which checks to return using the realcontrol application. The SHA-1 hash of certain elements of the response. The details of this are to be found in the realauth developer’s guide. The MD5 hash of certain elements of the response. The details of this are to be found in the realauth developer’s guide.

N3V N4/ N1

<check id="xxxx">9</check> </tss> <sha1hash>7384ae67....ac7d7d</sha1hash>

R

R

AN40

<md5hash>34e7....a77d</md5hash> </response>

R

AN32

Page 21 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com

5 Contact details.
Should you have any queries please contact Realex Payments by any of the means below: Realex Payments The Forum 29/31 Glasthule Road Glasthule, Co, Dublin, Ireland. email – support@realexpayments.com Phone + 353 (0) 1 280 8559 Fax + 353 (0) 1 280 8538 www.realexpayments.com

Appendix A – Version Control
Version 1.2.1 1.2.2 1.3 Date 16/6/06 11/09/06 19/06/07 Amendments Included possible cvnresult codes Updated CVN results Added SHA1 details. Completed By Chris Dare Darren G Brendan H.

Page 22 - Version 1.2.2

Printed on: 21 Jun 2007

All material © and ™ of Pay and Shop Limited, trading as Realex Payments. This guide is strictly confidential and intended for customer use only. Realex Payments, The Forum, 29/31 Glasthule Road, Glasthule, Co. Dublin, Ireland telephone: +353 (0)1 280 8559 - email: info@realexpayments.com - web: www.realexpayments.com