realex developer guide

RealEFT Developer’s Guide with XML Definitions

Version: v2.2

© 2000—2010 Realex Payments. All rights reserved. This material is proprietary to Pay and Shop Ltd, trading as Realex Payments, Ireland and is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of Realex Payments. All other trademarks, service marks, and trade names referenced in this material are the

property of their respective owners.


2

Document Information

Document Name: RealEFT Developer’s Guide with XML Definitions Document Version: 2.2 Release Date: 19 July 2010

Legal Statement

This guide, in addition to the software described within, is under the copyright owned by Pay and Shop Limited, trading as Realex Payments, and subject to license. The included software may contain and utilise third‐party software products. The guide and included software, whole or in part, cannot be published, downloaded, stored, reproduced, transmitted, transferred or combined with any other material, or be used for any other purpose without prior written permission from Realex Payments. All software, trademarks, logos, designs, and websites contained within this guide remain the intellectual property of the respective individual owners and companies.

Disclaimer

Every effort has been made to ensure the accuracy of information published in this guide. However Realex Payments cannot accept any responsibility for any errors, inaccuracies, or omissions that may or may not be published in the guide. To the extent permitted by law, Realex Payments is not liable for loss, damage, or liability arising from errors, omissions, inaccuracies, or any misleading or out‐of‐date information whether published in this guide or from any link in this guide. Realex Payments reserves the right to change this guide and the included software without prior notice or consent.

Company Information

Pay and Shop Limited, trading as Realex Payments has its registered office at Castlecourt, Monkstown Farm, Dun Laoghaire, Co Dublin, Ireland and is registered in Ireland, company number 324929.


3

Table of Contents 1 5 About This Guide

1.1 5 Purpose

1.2 5 Audience

1.3 5 Prerequisites

1.4 5 Related Documents

1.5 5 Conventions

2 7 Real EFT Integration

3 8 Payer Administration

3.1 8 Set up a New Payer

3.2 9 XML Syntax

3.3 10 Hash Value Syntax

3.4 11 Edit an Existing Payer

3.5 12 XML Syntax


3.7 14 Payment Method Set‐up

3.8 14 XML Syntax


3.10 16 Activate a Mandate

3.11 17 XML Syntax


4 20 Payment (direct debit – eft) processing

4.1 21 XML Syntax


5 24 Void a Direct Debit

5.1 24 XML Syntax


6 27 Mark a Direct Debit as Unpaid

6.1 27 XML Syntax


7 29 Cancel the Unpaid Mark on a Direct Debit

7.1 29 XML Syntax


8 31 Re‐Present a Direct Debit


4

8.1 31 XML Syntax


9 33 Responses

Appendix A – Result Codes 36

9.1 36 Successful Transaction

9.2 36 Internal Realex Payments Error

9.3 36 Invalid Data In Request

Appendix B – Result Codes 38


5

1 About This Guide This section outlines the purpose and aim of the guide, target audience, any source materials or terminology used, and a general document description. Please note that this document is regarded as confidential and is for customer use only. It has been supplied under the conditions of your payment‐processing contract.

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

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

1.3 Prerequisites

In order to use realeft from within your own systems, you must first integrate with Realex Payments. Details of how to do this, along with sample code, are contained in the realauth Developer’s Guide.

The remainder of this document describes the format of the XML messages needed and the correct way to use them. You must have access to application or web developers to amend your application or internet site so that it links to Realex Payments.

In addition, you must have arranged an Originator Identification Number with your sponsoring bank before you can accept Direct Debits. This process must be completed with your bank and your bank must be one of the banks to which Realex Payments is connected. Realex supports a multi account bank setup so it is possible to have your credit and debit card facility with one bank and your direct debit facility with another bank.

1.4 Related Documents In addition to this guide, you can also refer to the following documents in the Realex Payments documentation set for information about the Realauth service:

▪ RealEFT User Guide

1.5 Conventions

Realex documentation uses the following conventions:

Note: Tips or advice for the user.

Caution: Important note. Potential financial impact.


Conventions Description Example

Blue Italic or Plain Type

Hyperlinks and cross‐references For more information see Table 1.n

Italics Names of other guides Realauth Developer’s Guide

Courier New

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

<comments></comments>

Courier New

Placeholder for element names, field values, or user input

card_holder_name

BOLD CAPS Error and warning messages 101 / REFERRAL B

The following table outlines the main formatting conventions used in this guide:

6


2 Real EFT Integration

All XML requests must be sent to the following URL. https://epage.payandshop.com/epage‐remote‐plugins.cgi There are two set‐up steps required before you can begin charging a payer:

A payer has to be set up on the system A payment method must be set up for that payer.

Once these steps are completed, you can begin charging that payer on a regular basis with just a single XML request. This diagram shows the EFT Transaction Flow.

7

https://epage.payandshop.com/epage-remote-plugins.cgi


8

3 Payer Administration

This section describes the XML requests used to set up and maintain the payers on the system.

3.1 Set up a New Payer

The first set‐up stage is to create the payer. A “Payer” is the information you have regarding the actual person or company rather than their account or card details. This step can be performed manually via realcontrol or can be integrated into your sales/CRM application. The following sections provide the information necessary to submit a valid set up new payer request type:

▪ Example ▪ XML Syntax ▪ Hash Value Syntax

Example

<request type="payer-new" timestamp="20030516175919"> <merchantid>yourclientid</merchantid> <orderid>uniqueid</orderid> <payer type="Business" ref="smithj01"> <title>Mr</title> <firstname>John</firstname> <surname>Smith</surname> <company>Acme Inc</company> <address> <line1>Apt 167 Block 10</line1> <line2>The Hills</line2> <line3>67-69 High St</line3> <city>Hytown</city> <county>Dunham</county> <postcode>3</postcode> <country code="IE"> Ireland </country> </address> <phonenumbers> <home>+35317285355</home> <work>+35317433923</work> <fax>+35317893248</fax> <mobile>+353873748392</mobile> </phonenumbers> <email>[email protected]</email> <comments> <comment id="1" /> <comment id="2" /> </comments> </payer> <sha1hash>7daf026b193eb18344f5ab6822cd05959718c567</sha1hash> <comments> <comment id="1" /> <comment id="2" /> </comments> </request>


9

3.2 XML Syntax

For each XML element or field, the table below provides the following information:

▪ The syntax for the element or field ▪ An indication of whether the element or field is mandatory (M) or optional (O) ▪ The format for the value in terms of allowable characters or numbers ▪ The allowable length of the value ▪ A description

Please note that “” means a space.

Element/Field Mandatory Format Length Description <request type="payer-new" timestamp="20030516175919">

M 0‐9 14

The name for this request type is payer‐new.

<merchantid>yourclientid</ merchantid>

M a‐z A‐Z 0‐9 .

1‐50 Your client id as assigned by Realex Payments.

<orderid>uniqueid</orderid>

O a‐z A‐Z 0‐9 _ ‐

1‐40 A unique id to identify this transaction.

<payer type="Business" ref="smithj01">

M a‐z A‐Z a‐z A‐Z\ 0‐9 _ “” ‐

1‐20 1‐50

The payer ref for this customer. Must be unique.

<title>Mr</title> O a‐z A‐Z 0‐10 The payer’s title <firstname>John</firstname>

M a‐z A‐Z “” 1‐30 First name of payer.

<surname>Smith</surname> M a‐z A‐Z “” ‐

1‐50 Surname of payer.

<company>Acme Inc</company>

O a‐z A‐Z 0‐9 “”

0‐50 Company Name

<address> O Payer Address <line1>Apt 167 Block 10</ line1>

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

0‐50

<line2>The Hills</line2> O a‐z A‐Z 0‐9 “” ‐ / ,

0‐50

line3>67-69 High St</line2>

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

0‐50

<city>Hytown</city> 0 a‐z A‐Z “” ‐

0‐20

<county>Dunham</county> O a‐z A‐Z “” ‐

0‐20

<postcode>3</postcode> O a‐z A‐Z 0‐9 “”

0‐8

<country code="IE"> Ireland </country>

O a‐z A‐Z 0‐2 The list of country codes is available in the realauth developers guide.

</address> O <phonenumbers> O Payer Phone Numbers <home>+35317285355</home> O 0‐9 + ‐ “” 0‐20 <work>+35317433923</work> O 0‐9 + ‐ “” 0‐20 <fax>+35317893248</fax> O 0‐9 + ‐ “” 0‐20 <mobile>+353873748392</ O 0‐9 + ‐ “” 0‐20


10

Element/Field Mandatory Format Length Description mobile> </phonenumbers> O <email>[email protected]</ email>

O a‐z A‐Z 0‐9 . @ ‐ _

0‐50 Payer Email

<comments> O a‐z A‐Z 0‐9"" , . ‐ / |

0‐30 Comments about the payer

<comment id="1" /> O a‐z A‐Z 0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

<comment id="2" /> O a‐z A‐Z 0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

</comments> O </payer> O <sha1hash>7daf026b193e….59597 18c567</sha1hash>

M a‐f 0‐9 40 The SHA1 hash of this message.

<comments> O Comments about this transaction

<comment id="1" /> O a‐z A‐Z 0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

<comment id="2" /> O a‐z A‐Z 0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

</comments> O </request> O

3.3 Hash Value Syntax

The following table illustrates the hash value syntax for setting up a new payer:

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

Example: 20010427124523.merchantid.orderid.100.GBP.payerref

To construct the payer new hash follow this procedure:

▪ Form a string by concatenating the above fields with a period (“.”) (If a value for creating the hash is not included in the XML just leave it blank, but always include all of the dots.)

( 20010403123245.thestore.ORD453‐11.29900.EUR.smithj01 )

▪ Get the hash of this string (SHA‐1 shown below).

(153872918f7f4e81fa7a5a5763d73b32853ca54c )

▪ Create a new string by concatenating this string and your shared secret using a period.


11

(153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret )

▪ Get the hash of this value. This is the value that you send to Realex Payments.

(8e629d8455b760eff776f6ca6fb0be8b2fe18803)

<sha1hash> 8e629d8455b760eff776f6ca6fb0be8b2fe18803 </sha1hash>

3.4 Edit an Existing Payer

This request type is used to edit the details of a payer. It must contain the original payer reference.

It has two sets of comments. The first set is comments about the payer. The second set of comments is about the payer‐edit transaction itself. The following sections provide the information necessary to edit an existing payer:


Example

<request type="payer-edit" timestamp="20030516175919"> <merchantid>yourmerchantid</merchantid> <orderid>uniqueid</orderid> <payer type="Business" ref="smithj01"> <title>Mr</title> <firstname>John</firstname> <surname>Smith</surname> <company>Acme Inc</company> <address> <line1>123 Fake St.</line1> <line2 /> <line3 /> <city>Hytown</city> <county>Dunham</county> <postcode>3</po codst e> <country code="IE"> Ireland </country> </address> <phonenumbers> <home /> <work>+35317433923</work> <fax>+35317893248 x> </fa<mobile>+353873748392</mobile> </phonenumbers> <email>[email protected]</email> <passphrase /> <comments> <comment id="1" /> <comment id="2" /> </comments> </payer> <sha1hash>7daf026b193eb18344f5ab6822cd05959718c567</sha1hash> <comments> <comment id="1" /> <comment id="2" /> </comments> </request>


12

3.5 XML Syntax


▪ 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

XML Syntax to Edit an Existing Payer

Element/Field Mandatory Format Length Description <request type="payer-edit" timestamp="20030516175919">

M 0‐9 14 type:auth

The name for this request type is payer‐edit.


M a‐z A‐Z 0‐9 .



O a‐z A‐Z 0‐9 _ ‐


<payer type="Business" ref="smithj01">

M a‐z A‐Z a‐z A‐Z\ 0‐9 _ “” ‐

1‐20 1‐50

The payer ref for this customer. Must be unique.

<title>Mr</title> O a‐z A‐Z 0‐10 The payer’s title <firstname>John</firstname>

M a‐z A‐Z “” 1‐30 First name of payer.

<surname>Smith</surname> M a‐z A‐Z “” ‐

1‐50 Surname of payer.

<company>Acme Inc</company>

O a‐z A‐Z 0‐9 “”

0‐50 Company Name

<address> O Payer Address <line1>Apt 167 Block 10</ line1>

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

0‐50

<line2>The Hills</line2> O a‐z A‐Z 0‐9 “” ‐ / ,

0‐50

<line3>67-69 High St</line2>

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

0‐50

<city>Hytown</city> 0 a‐z A‐Z “” ‐

0‐20

<county>Dunham</county> O a‐z A‐Z “” ‐

0‐20

<postcode>3</postcode> O a‐z A‐Z 0‐9 “”

0‐8

<country code="IE"> Ireland </country>

O a‐z A‐Z 0‐2 The list of country codes is available in the realauth developers guide.

</address> O


13

Element/Field Mandatory Format Length Description <phonenumbers> O Payer Phone Numbers <home>+35317285355</home> O 0‐9 + ‐ “” 0‐20 <work>+35317433923</work> O 0‐9 + ‐ “” 0‐20 <fax>+35317893248</fax> O 0‐9 + ‐ “” 0‐20 <mobile>+353873748392</ mobile>

O 0‐9 + ‐ “” 0‐20

</phonenumbers> O <email>[email protected]</ email>

O a‐z A‐Z 0‐9 . @ ‐ _

0‐50 Payer Email

<comments> O a‐z A‐Z 0‐9"" , . ‐ / |

0‐30 Comments about the payer

<comment id="1" /> O a‐z A‐Z 0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

<comment id="2" /> O a‐z A‐Z 0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

</comments> O </payer> O <sha1hash>7daf026b193e….5959 718c567</sha1hash>


<comments> O Comments about this transaction

<comment id="1" /> O a‐z A‐Z 0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

<comment id="2" /> O a‐z A‐Z 0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

</comments> O </request> O


The following table illustrates the hash value syntax for editing an existing payer:

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

Example: 20010427124523.merchantid.orderid.100.GBP.payerref

To construct the payer‐edit hash follow this procedure:

Form a string by concatenating the above fields with a period (“.”) (If a value for creating the hash is not included in the XML just leave it blank, but always include all of the dots.)



14

Get the hash of this string (SHA‐1 shown below).

(153872918f7f4e81fa7a5a5763d73b32853ca54c )

Create a new string by concatenating this string and your shared secret using a period.


Get the hash of this value. This is the value that you send to Realex Payments.



3.7 Payment Method Set‐up

Once the payer is in place you can add payment methods to it. Once again this step may be performed manually via realcontrol or be integrated using the XML messages below.

Add Mandate Details

To add the details of a Direct Debit Mandate, use the ddi‐new request type. The following sections provide the information necessary to submit a valid add mandate details request type:

▪ Example

▪ XML Syntax

▪ Hash Value Syntax

Example

<request type="ddi-new" timestamp="20030516180730"> <merchantid>yourclientid</merchantid> <orderid>uniqueid</orderid> <ddi> <ref>mandate01</ref> <payerref>smithj01</payerref> <accounts> <account>eft</account> </accounts> <sortcode>933384</sortcode> <accountnumber>72121495</accountnumber> <bank>aib</bank> <name>John Smith</name> <expiry /> <comments> <comment id="1" /> <comment id="2" /> </comments> </ddi> <sha1hash>96879e9aeea251ce4e53db36d17780292d217856</sha1hash> </request>

3.8 XML Syntax



15


▪ An indication of whether the element or field is mandatory (M), optional (O), or conditional (C)

depending on another optional field



▪ A description

Element/Field Mandatory Format Length Description <request type="ddi-new" timestamp="20030516180730">


The name for this request type is ddi‐new.


M a‐z A‐Z 0‐9 . 1‐50 Your client id as assigned by Realex Payments.

<orderid>uniqueid</orderid> O a‐z A‐Z 0‐9 _ ‐


<ddi> M <ref>mandate01</ref> M a‐z A‐Z 0‐9_ 1‐30 The reference for

this card <payerref>smithj01</ payerref>

M a‐z A‐Z 0‐9_ 1‐50 The payer ref for this customer.

<accounts> M A list of accounts that this can be used with.

<account>eft</account> M a‐z A‐Z 0‐9 ‐ + “” '

1‐20

</accounts> M <sortcode>933384</sortcode> M 0‐9 1‐10 The Payer’s sort

code. <account number>72121495</ accountnumber>

M 0‐9 1‐20 The Payer’s account number.

<bank>aib</bank> M a‐z A‐Z 0‐9 1‐30 The Payer’s Bank <name>John Smith</name> M a‐z A‐Z 0‐9

“” . , ‐ _ + @ ! ? £ $ €

1‐20 The name on the Payer’s account.

<expiry>06/09/2010</expiry> O 0‐9/ 0‐10 The expiry date of the mandate. After this date this mandate can no longer be used.

<comments> 0 Comments made about this mandate

</comments> O </ddi> M <sha1hash>96879e9ae…d1778029 2d217856</sha1hash>


</request> M


16


The following table illustrates the hash value syntax for a validate request type:

Format: timestamp.merchant_id.order_id.amount.currency.ddipayerref.ddisortcode.ddiaccountnumber

Example: 20010427124523.merchantid.orderid.100.GBP.ddipayerref.ddisortcode.ddiaccountnumber

To construct the ddi‐jnew hash follow this procedure:


( 20010403123245.thestore.ORD453‐11.29900.EUR. smithj01. 933384.72121495)


(45c87c85cc54ba08628d03e3f45b8563b58425aa)


(45c87c85cc54ba08628d03e3f45b8563b58425aa.mysecret )


(6df141152a4e53afd1bc32d8e5192854964905f9)

<sha1hash> 6df141152a4e53afd1bc32d8e5192854964905f9 </sha1hash>

3.10 Activate a Mandate

The next request type is the DDI edit. This request type is used change the status of a particular DDI. It must contain the original DDI reference, original payer reference and original account. This request type is used to change the status of a DDI to either Pending(P), Active(A) or Cancelled(C). This is specified in the status tag. A mandate can only be used if it is Active.

The following sections provide the information necessary to submit a valid activate mandate request type:

▪ Example

▪ XML Syntax



17

Example

<<request type="ddi-edit" timestamp="20030516181127"> <merchantid>yourclientid</merchantid> <orderid>uniqueid</orderid> <ddi> <ref>visa01</ref> <payerref>smithj01</payerref> <accounts> <account>eft</account> </accounts> <status>A/status> <comments> <comment id = “1”>comment1</comment> <comment id = “2”>comment2</comment> </comments> </ddi> <sha1hash>4d708b24e3494bf80916ba3c8afd8347060fdd65</sha1hash> </request>

3.11 XML Syntax







▪ A description


18

Element/Field Mandatory Format Length Description <request type="ddi-edit" timestamp="20030516181127">


The name for this request type is ddi‐edit.




O a‐z A‐Z 0‐9 _ ‐


<ddi> M <ref>visa01</ref> M a‐z A‐Z 0‐9_ 1‐30 The reference for this

card <payerref>smithj01</ payerref>

M a‐z A‐Z 0‐9_ 1‐50 The payer ref for this customer.

<accounts> M A list of accounts that this can be used with.

<account>eft</account> M a‐z A‐Z 0‐9 ‐ + “” '

1‐20

</accounts> M

<status>A/status> M a‐z A‐Z 0‐9 ‐ + “” '

1‐50 The Status to set this

mandate

<comments> 0 Comments made about

this mandate

<comment id="1" /> O a‐z A‐Z 0‐9 ‐

+ “” '

0‐255

</comments> O </ddi> M <sha1hash>4d708b24e…8afd8347 060fdd65</sha1hash>


</request> M


The following table illustrates the hash value syntax for updating card expiry date:

Format timestamp.merchant_id.order_id.amount.currency.ddipayerref.ddisortcode.ddiaccountnumber

Example: 20010427124523.merchantid.orderid.100.GBP.ddipayerref.ddisortcode.ddiaccountnumber

To construct the ddi‐edit hash follow this procedure:


( 20010403123245.thestore.ORD453‐11.29900.EUR. smithj01. 933384. 72121495)


(45c87c85cc54ba08628d03e3f45b8563b58425aa)


19


(45c87c85cc54ba08628d03e3f45b8563b58425aa.mysecret )


(6df141152a4e53afd1bc32d8e5192854964905f9)

<sha1hash> 6df141152a4e53afd1bc32d8e5192854964905f9 </sha1hash>


20

4 Payment (direct debit – eft) processing

This section describes the XML requests used to process and administer the payment requests into Realex Payments.

Raise a payment

To raise a payment using any payment method, use the receipt‐in transaction.

The following sections provide the information necessary to submit a valid eft‐update‐ expiry‐date request type:

▪ Example

▪ XML Syntax


Example

<request type="receipt-in" timestamp="20030520151742"> <merchantid>yourclientid</merchantid> <account>eft</account> <orderid>transaction01</orderid> <amount currency="EUR">9999</amount> <paymentdata> <cvn> <number>123</number> </cvn> </paymentdata> <autosettle flag="1" /> <payerref>bloggsj01</payerref> <paymentmethod>mandate01</paymentmethod> <md5hash /> <sha1hash>c81377ac77b6c0a8ca4152e00cc173d01c3d98eb</sha1hash> <comments> <comment id="1" /> <comment id="2" /> </comments> <tssinfo> <address type="billing"> <code>zip/postal code</code> <country>country</country> </address> <address type="shipping"> <code>zip/postal code</code> <country>country</country> </address> <custnum></custnum> <varref></varref> <prodid></prodid> </tssinfo>

</request>


21

4.1 XML Syntax







▪ A description

Element/Field Mandatory Format Length Description <request type="receipt-in" timestamp="20030516181127">

M 0‐9 14

The name for this request type is receipt‐in.


M a‐z A‐Z 0‐9 .


<account>eft</account> M a‐z A‐Z 0‐9 – “”*

1‐20 The account through which to process this transaction


O a‐z A‐Z 0‐9 _ ‐


<paymentdata> O </cvn> O <number>123</number> O 0‐9 3‐4 The Card Verification Number. This

is the 3 digit number on the reverse of the card. (the CVC for VISA and the CVV2 for MasterCard) 4 digit number on an Amex.

</cvn> O <paymentdata> <autosettle flag="1" /> M See

Details N/A 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 Payments database for 28 days or until manually settled.

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

M a‐z A‐Z 0‐9

3 2‐11

The currency and amount of this transaction. See the realauth Developer’s Guide for details of the currency codes

<payerref>bloggsj01</ payerref>

M a‐z A‐Z 0‐9 ‐ _

1‐50 The payer reference of the customer.

<paymentmethod>mandate01< M a‐z A‐Z 1‐50 The payment reference.


22

Element/Field Mandatory Format Length Description / paymentmethod>

0‐9 “” _‐

<sha1hash>c81377ac77b6c…..3d0 1c3d98eb</sha1hash>

M a‐f 0‐9 40 The SHA1 hash of the request.

<comments> O Comments about the transaction <comment id="1" /> 0 a‐z A‐Z

0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

<comment id="2" /> O a‐z A‐Z 0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

</comments> O <tssinfo> O The realscore (formerly TSS)

information. <address type="billing"> O <code>zip/postal code</code>

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

0‐30

<country>country</country>

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

0‐30

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

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

0‐30


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

0‐30

</address> O <custnum></custnum> O a‐z A‐Z

0‐9 – “” _ . , + @

Your reference number for the customer.

<varref></varref> O a‐z A‐Z 0‐9 – “” _ . , + @

An email address or mobile number or any other useful value can be sent with each request.

<prodid></prodid> O a‐z A‐Z 0‐9 – “” _ . , + @

Typically your product code.

</tssinfo> O </request> M


23


The following table illustrates the hash value syntax for updating card expiry date:

Format: t: timestamp.merchant_id.order_id.amount.currency.payerref

Example: 20010427124523.merchantid.order_id.100.GBP.payerref

To construct the receipt‐in hash follow this procedure:

Form a string by concatenating the above fields with a period (“.”) (If a value for creating the hash is not

included in the XML just leave it blank, but always include all of the dots.)



(153872918f7f4e81fa7a5a5763d73b32853ca54c )







24

5 Void a Direct Debit

To void a direct debit use the eft‐void transaction.

The following sections provide the information necessary to submit a valid eft‐void request type:

▪ Example

▪ XML Syntax


Example

<request type="eft-void" timestamp="20030520151829"> <merchantid>yourclientid</merchantid> <account>eft</account> <orderid>transaction01</orderid> <pasref>3f60e007249d457d9200a11918af0eed</pasref> <sha1hash>af7e39fb7ab7e9824d0188c28d14eac37a4f5eec</sha1hash> <comments> <comment id="1">Wrong amount</comment> <comment id="2" /> </comments> </request>

5.1 XML Syntax







▪ A description


25

XML syntax to Raise a Process a Refund

Element/Field Mandatory Format Length Description <request type="eft-void" timestamp="20030520151742">

M 0‐9 14

The name for this request type is eft‐void.

<merchantid>yourclientid</merchantid>

M a‐z A‐Z 0‐9 .




<orderid>transaction01</orderid>

O a‐z A‐Z 0‐9 _ ‐


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

M a-z A-Z 0-9

3 2-11

The currency and amount of this transaction. See the realauth Developer’s Guide for details of the currency codes

<payerref>bloggsj01</ payerref>

M a-z A-Z 0-9 - _

1-50 The payer reference of the customer.

<paymentmethod>mandate01 </paymentmethod>

M a-z A-Z 0-9 “” _-

1-50 The payment reference.

<sha1hash>c81377ac77b6c…..3d0 1c3d98eb</sha1hash>

M a-f 0-9 40 The SHA1 hash of the request. See below for details.

<refundhash>738e83....3434dda e662a</refundhash>

M a-f 0-9 40 This is the hash of the refund password (Realex Payments will give this to you). The SHA1 algorithm must be used to generate this hash.

<comments> O Comments about this transaction.

<comment id="1" /> 0 a‐z A‐Z 0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

<comment id="2" /> O a‐z A‐Z 0‐9 “” . , ‐ _ + @ ! ? £ $ €

0‐255

</comments> O <tssinfo> O The realscore (formerly TSS)

information. <address type="billing">

O

<code>zip/postal code</code>

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

0‐30


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

0‐30

</address> O <address type="shipping">

O

<code>zip/postal O a‐z A‐Z 0‐9 0‐30


26

Element/Field Mandatory Format Length Description code</code> “” , . ‐ / | <country>country</country>

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

0‐30

</address> O <custnum></custnum> O a‐z A‐Z 0‐9

– “” _ . , + @

Your reference number for the customer.

<varref></varref> O a‐z A‐Z 0‐9 – “” _ . , + @

An email address or mobile number or any other useful value can be sent with each request.

<prodid></prodid> O a‐z A‐Z 0‐9 – “” _ . , + @

Typically your product code.

</tssinfo> O

</request> M

5.2 Hash Value Syntax The following table illustrates the hash value syntax for updating card expiry date:

Format: timestamp.merchant_id.order_id.amount.currency.payerref


To construct the eft‐void hash follow this procedure:




(153872918f7f4e81fa7a5a5763d73b32853ca54c )







27

6 Mark a Direct Debit as Unpaid

To mark a direct debit as unpaid, use the eft‐unpaid transaction.

The following sections provide the information necessary to submit a valid eft‐unpaid request type:

▪ Example

▪ XML Syntax


Example:

<request type="eft-unpaid" timestamp="20030520152117"> <merchantid>yourclientid</merchantid> <account>eft</account> <orderid>20030501-0023</orderid> <reasoncode>0</reasoncode> <pasref>8656d1e2fadf4bd9941888b95673bb93</pasref> <sha1hash>00af6e23b3fadc1f4486eacda720b5fa8644281d</sha1hash> <comments> <comment id="1">Refer to Payer</comment> <comment id="2" /> </comments> </request>

6.1 XML Syntax For each XML element or field, the table below provides the following information:



Element/Field Mandatory Format Length Description <request type="eft-unpaid" timestamp="20030520152117">

M 0‐9 14

The name for this request type is eft‐unpaid.


M a‐z A‐Z 0‐9 .




<orderid>20030501-0023</ orderid>

O a‐z A‐Z 0‐9 _ ‐

1‐40 The order id used in the original transaction.


28

Element/Field Mandatory Format Length Description <reasoncode>0</reasoncode>

M a‐z A‐Z 0‐9 “” :

1‐50 The reason the transaction was returned. These codes are outlines in Appendix C.

<pasref>8656d1e2fadf4bd99418 88b95673bb93</pasref>

M a‐z A‐Z 0‐9

1‐50 The PAS Reference returned in the response to the original transaction.

<sha1hash>00af6e23b3fadc…da7 20b5fa8644281d</sha1hash>

M a‐f 0‐9 40 The SHA1 hash of the request. See below for details.


<comment id="1">Refer to Payer</comment>

O a‐z A‐Z 0‐9 “” ‐_ . , + @ ! ? £ $ €

0‐255

<comment id="2" /> O a‐z A‐Z 0‐9 “” ‐_ . , + @ ! ? £ $ €

0‐255

</comments> O </request>




To construct the eft‐unpaid hash follow this procedure: Form a string by concatenating the above fields with a period (“.”) (If a value for creating the hash is not included in the XML just leave it blank, but always include all of the dots.) ( 20010403123245.thestore.ORD453‐11.29900.EUR.smithj01 ) Get the hash of this string (SHA‐1 shown below). (153872918f7f4e81fa7a5a5763d73b32853ca54c ) Create a new string by concatenating this string and your shared secret using a period. (153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret ) Get the hash of this value. This is the value that you send to Realex Payments. (8e629d8455b760eff776f6ca6fb0be8b2fe18803) <sha1hash> 8e629d8455b760eff776f6ca6fb0be8b2fe18803 </sha1hash>


29

7 Cancel the Unpaid Mark on a Direct Debit

To cancel an unpaid mark on a direct debit, use the eft‐cancel‐unpaid transaction. The following sections provide the information necessary to submit a valid eft‐cancel unpaid request type:


Example

<request type="eft-cancel-unpaid" timestamp="20030520152031"> <merchantid>yourclientid</merchantid> <account>eft</account> <orderid>20030474-138</orderid> <pasref>6ccf7e74c26f494c8e560e57cb467547</pasref> <sha1hash>8f57214737d483eceff15959646447a21d7176e7</sha1hash> <comments> <comment id="1"> Wrong transaction. Should not have marked unpaid!</comment> <comment id="2"></comment> </comments> </request>


The syntax for the element or field

An indication of whether the element or field is mandatory (M) or optional (O)

The format for the value in terms of allowable characters or numbers

The allowable length of the value

A description


Element/Field Mandatory Format Length Description <request type="eft-cancel-unpaid" timestamp="20030520152031">

M 0‐9 14

The name for this request type is eft‐unpaid.






O a‐z A‐Z 0‐9 _ ‐


<reasoncode>0</reasoncode> M a‐z A‐Z 0‐9 “” :

1‐50 The reason the transaction was returned. These codes are outlines


30

Element/Field Mandatory Format Length Description

in Appendix C. <pasref>8656d1e2fadf4bd99418 88b95673bb93</pasref>

M a‐z A‐Z 0‐9 1‐50 The PAS Reference returned in the response to the original transaction.

<sha1hash>00af6e23b3fadc…da7 20b5fa8644281d</sha1hash>



<comment id="1">Refer to Payer</comment>

O a‐z A‐Z 0‐9 “” ‐_ . , + @ ! ? £ $ €

0‐255

<comment id="2" /> O a‐z A‐Z 0‐9 “” ‐_ . , + @ ! ? £ $ €

0‐255





To construct the eft‐unpaid hash follow this procedure: Form a string by concatenating the above fields with a period (“.”) (If a value for creating the hash is not included in the XML just leave it blank, but always include all of the dots.) ( 20010403123245.thestore.ORD453‐11.29900.EUR.smithj01 ) Get the hash of this string (SHA‐1 shown below). (153872918f7f4e81fa7a5a5763d73b32853ca54c ) Create a new string by concatenating this string and your shared secret using a period. (153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret ) Get the hash of this value. This is the value that you send to Realex Payments. (8e629d8455b760eff776f6ca6fb0be8b2fe18803) <sha1hash> 8e629d8455b760eff776f6ca6fb0be8b2fe18803 </sha1hash>


31

8 Re‐Present a Direct Debit

To re‐present a direct debit, use the eft‐represent transaction. The following sections provide the information necessary to submit a valid eft‐cancel unpaid request type:


Example: <request type="eft-represent" timestamp="20030520152009"> <merchantid>yourclientid</merchantid> <account>eft</account> <orderid>20030428-018</orderid> <pasref>5b8aa0bf6f1c49b1a431ef26c251e430</pasref> <sha1hash>cdaea87dc26c852b6420e5419d765f45e9974e19</sha1hash> <comments> <comment id="1">Spoke to client - money in account now</comment> <comment id="2"></comment> </comments> </request>




Element/Field Mandatory Format Length Description <request type="eft-represent" timestamp="20030520152031">

M 0‐9 14

The name for this request type is eft‐represent.


M a‐z A‐Z 0‐9 .





O a‐z A‐Z 0‐9 _ ‐


<reasoncode>0</reasoncode> M a‐z A‐Z 0‐9“” :

1‐50 The reason the transaction was returned. These codes are outlines in Appendix C.

<pasref>8656d1e2fadf4bd99418 88b95673bb93</pasref>

M a‐z A‐Z 0‐9 1‐50 The PAS Reference returned in the response to the original


32

transaction. <sha1hash>00af6e23b3fadc…da7 20b5fa8644281d</sha1hash>



<comment id="1">Spoke to client - money in account now</comment>

O a‐z A‐Z 0‐9“” ‐_ . , + @ ! ? £ $ €

0‐255

<comment id="2" /> O a‐z A‐Z 0‐9“” ‐_ . , + @ ! ? £ $ €

0‐255





To construct the eft‐represent hash follow this procedure: Form a string by concatenating the above fields with a period (“.”) (If a value for creating the hash is not included in the XML just leave it blank, but always include all of the dots.) ( 20010403123245.thestore.ORD453‐11.29900.EUR.smithj01 ) Get the hash of this string (SHA‐1 shown below). (153872918f7f4e81fa7a5a5763d73b32853ca54c ) Create a new string by concatenating this string and your shared secret using a period. (153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret ) Get the hash of this value. This is the value that you send to Realex Payments. (8e629d8455b760eff776f6ca6fb0be8b2fe18803) <sha1hash> 8e629d8455b760eff776f6ca6fb0be8b2fe18803 </sha1hash>


33

9 Responses

All requests sent to the Realex Payments system will receive a response. There are two possible responses you will receive while using the realEFT service:

▪ A successful response, which indicates that the request sent was correct ▪ An unsuccessful response, which indicates the request was invalid.

Response Format The two response formats are shown below. Response format – Successful request: This response contains the merchant id, the account used, the order id used, a result code with corresponding result message, a PAS reference, batch id, the hash returned and the time taken for the transaction to take place.

<response timestamp="20030520152009"> <merchantid>yourclientid</merchantid> <account>eft</account> <orderid>20030428-018</orderid> <result>00</result> <message>Authorised</message> <pasref>PAS Reference</pasref> <batchid>Batch ID</batchid> <timetaken>Time taken in seconds</timetaken> <sha1hash>cdaea87dc26c852b6420e5419d765f45e9974e19</sha1hash> </response>

Response format – Unsuccessful request: This response contains a result error code with a corresponding error message.

<response timestamp="20030520152009"> <result>Unsuccessful result code</result> <message>Unsuccessful Message</message> </response> Response Result Codes This section describes the response result codes and their corresponding messages. If the request was successful the response result code is 00 and the associated result message is SUCCESSFUL. If the response result code is not 00 then there was an error processing the request. The following sections describe possible errors returned by Realex Payments.


3xx Result Codes The 3xx result codes indicate that there is an error with Realex Payments internal system. These result types are very rare. If you receive a 3xx result code, please contact Realex Payments. Appendix A gives a more detailed description of the possible error result messages returned for a 3xx error.

Result Message

300 Problem connecting to Realex database

304 Problem accessing file for processing

320 General Configuration Error

5xx Result Codes The 5xx result codes indicate that there is an error in the data sent to Realex. The section ‘Invalid Data In Request’ in Appendix A gives a list of 5xx error messages returned by Realex.

Result Message

501 The reference in the request is not valid

502 Mandatory Field Missing

503 Request type not supported

505 Authentication Error

508 Invalid date entered ‐ developer has coded incorrectly

520 Invalid reference combination sent into Realex

521 Merchant not setup to process that currency

Digital Signatures To ensure authentication (that the request comes from you) we require that you send us a hash of certain elements (specific hash fields have been noted at the end of each request) using a shared secret. This can be a MD5 hash or preferably a SHA‐1 hash. If required, we can also provide sample code for this. MD5 and SHA‐1 algorithms are secure hash functions. They take a string as input, and produce a fixed size number ‐ 128 bits for MD5; 160 bits for SHA‐1. This number is a hash of the input, and a small change in the input results in a substantial change in the output. The functions are thought to be secure in the sense that it requires an enormous amount of computing power and time to find a string that hashes to the same value. In others words, there is no way to decrypt a secure hash. Given the larger key size, you may prefer a SHA‐1 hash, but we have retained the MD5 for compatibility with older systems. Below is a fragment of a sample XML message:

<request timestamp="20010403123245" type="auth"> <merchantid> thestore </merchantid> <orderid> ORD453-11 </orderid> <amount currency="EUR"> 29900 </amount> <card> <number> 5105105105105100 </number> <expdate> 0302 </expdate> <chname> Test User </chname> <type> VISA </type> </card>

34


35

To construct the hash follow this procedure: Form a string by concatenating the above fields with a period (“.”) (If a value for creating the hash is not included in the XML just leave it blank, but always include all of the dots.) ( 20010403123245.thestore.ORD453‐11.29900.EUR.5105105105105100 ) Get the hash of this string (SHA‐1 shown below). ( c5d02900c2ed43e0015d5e6792e2071a7b20afd5 ) Create a new string by concatenating this string and your shared secret using a period. ( c5d02900c2ed43e0015d5e6792e2071a7b20afd5.mysecret ) Get the hash of this value. This is the value that you send to Realex Payments. ( 9af7064afd307c9f988e8dfc271f9257f1fc02f6 )

<sha1hash> 9af7064afd307c9f988e8dfc271f9257f1fc02f6 </sha1hash> When Realex Payments receive the request, we perform the same procedure on the same pieces of information and your shared secret (which we have stored in our database). If the resulting hash is the same as the one that you sent us, then the data could only have been sent by someone that had your shared secret. Thus, it is very important to permission the CGI program appropriately to keep this shared secret protected. We will send you a hash of the response elements in the same way so that you can confirm that the response came from Realex. (This will be a hash of the timestamp, merchant id, order id, result, message, Realex Payments reference and authcode with your secret key. If you sent us an md5 hash, you will receive an md5 hash in the response and similarly for a sha‐1 hash).


36

Appendix A – Result Codes

9.1 Successful Transaction

Code Description

00 Successful

9.2 Internal Realex Payments Error

Code Description

300 Couldn’t connect to the EFT Database

300 Couldn’t connect to the Live Database

304 Internal realex error. realex have been notified, couldn't do request.eft.rxp

304 Internal realex error. realex have been notified, couldn't parse request.eft.rxp

304 Internal realex error. realex have been notified, couldn't run request.eft.rxp

320 Error in SQL – Realex Payments have been notified

320 There is no originator data for this account!

320 Unable to open new batch!

9.3 Invalid Data In Request

Code Description

300 This DD Mandate Ref mandate name has already been used [Perhaps you've already set up a DD Mandate for this Payer?]

300 This DDI does not exist

304 This DDI Ref ddi ref name has already been used [Perhaps you've already set up a DDI for this Payer?]

304 This order ID has already been used ‐ please use another one

304 This Payer Ref payerref does not exist

320 This Payer Ref payerref has already been used ‐ please use another one

320 Mandatory Fields missing: error message. See Developers Guide

320 Request type request type not supported on this account name

503 You have no EFT accounts. Request type request type not supported

505 MD5 Hash incorrect

505 SHA1 Hash incorrect

508 Account name is not a Direct Debit account

508 Account numbers must be between 6 and 10 digits in length

508 Bank names contain only letters.

508 Cannot find original Direct Debit in database

508 Expiry date in past

508 Expiry date in wrong format: please use dd/mm/yyyy

508 Invalid characters in DDI Ref ‐ please use only A‐Z a‐z 0‐9 _ ‐


37

Code Description

508 Invalid characters in ddi reference ‐ please use only digits, letters, _ ‐

508 Invalid characters in email ‐ please use only digits, letters, spaces, \@ . _ ‐

508 Invalid characters in Narrative ‐ please use only A‐Z a‐z 0‐9 _ ‐ space .

508 Invalid characters in Originator Name ‐ please use only A‐Z a‐z 0‐9 _ ‐ space

508 Invalid characters in pasref ‐ please use only A‐Z a‐z 0‐9

508 Invalid characters in Payer Ref ‐ please use only A‐Z a‐z 0‐9 _ ‐

508 Invalid characters in payer reference ‐ please use only digits, letters, _ ‐

508 Invalid characters in payer type ‐ please use only digits, letters, spaces,‐

508 Invalid characters in sort order

508 Invalid data in currency field

508 Invalid date ‐ should be in dd/mm/yyyy format

508 Invalid DD Type ‐ see Developers Guide for valid Status Codes

508 Invalid DDI Status ‐ see Developers Guide for valid Status Codes

508 Invalid Status: only A (approved) is acceptable

508 Invalid Status: only A (approved) or P (pending approval) are acceptable

508 Invalid Status: only A or P allowed

508 Leading zeros or or other error in amount field

508 Only numbers in account number please

508 Only numbers in sortcode please (format: 9xxxxx)

508 Original Transaction already represented. You can only represent a transaction once.

508 Original Transaction has been represented. You can't cancel this unpaid mark.

508 Original Transaction is already marked unpaid. order id

508 Original Transaction was already voided!

508 Original Transaction was not marked unpaid. You can't represent it.

508 Original Transaction was not marked unpaid.

508 Original Transaction was voided! You can't do this.

508 Original Transaction was voided! You can't mark it unpaid.

508 Original Transaction was voided! You can't represent it.

508 Please only numbers in amount ‐ see developers guide

508 Please use only letters and numbers in the Payer Bank Account Name

508 Sort Code should have 6 digits

508 Sortcode is invalid ‐ please use xxxxxx only ‐ no dashes or spaces

508 That Sort Code sort code does not correspond to that bank bank name

508 The ddi has expired

508 The payer ddi has been cancelled

508 The payer ddi is not yet active

508 This transaction has been marked Unpaid ‐ you cannot void it

508 You cannot change a cancelled DDI ‐ please enter a new one

508 Zero, negative or insufficient amount specified

520 There is no DDI configured for that combination of Payer payerref and Account account name

520 There is no such Payer payerref

521 That currency is not allowed through that account!


38

Appendix B – Result Codes

Code Reason Explanation Action to Take

1 Instruction Cancelled The Payer or the Payers Bank Branch has cancelled the DDI

No further presentations allowed ‐ contact the payer

2 Payer Deceased The death of the Payer No further presentations Allowed

3 Account Transferred The account of the Payer has been transferred to another bank. If direct debiting is to continue the Originator must obtain a new Instruction

Obtain a new instruction from the Payer. No further instructions allowed

4 Advance Notice Dispute

The Payer has disputed the advance notice

Contact the Payer

5 No Account The identity of the Payer differs from that known to the Bank Branch and the account has not been traced

Contact the Payer

6 No Instruction The appropriate DDI has not been lodged with the Payers Bank Branch

Contact the Payer

7 Amount Differs The amount of the direct debit differs from the amount specified in the DDI

Originator may only submit debits for the agreed amount

8 Amount not Yet Due The date of debiting is in advance of the due date specified in the DDI

Delay re‐input until the due Date

9 Presentation Overdue

The presentation is overdue ‐ usually, this means that it is more than 7 days after the due date specified in the DDI

Seek permission from the payer to present the debitLate

A Originator Differs The identity of the Originator differs from that specified in the DDI

Ensure the Payer completes a valid DDI

B Account Closed The payers account is closed Obtain a new DDI from the Payer

0 Refer to Payer The Payers Bank Branch is not in a position to pay the direct debit OR the service of a garnishee order or arrestment on the payers account, his bankruptcy, liquidation, or the appointment of a receiver to manage his affairs

No further presentations allowed ‐ contact the payer


Connect with us online:

www.facebook.com/realexpayments

www.twitter.com/realexpayments

www.linkedin.com/companies/realex-payments

www.youtube.com/realexpayments

Our Other Websites:

Our office Locations: Realex Payments Ireland (Headquarters) Castlecourt, Monkstown Farm, Dun Laoghaire, Co Dublin. Ireland t: +353 (0)1 2808559 | f: +353 (0)1 2808538 | www.realexpayments.com [email protected]

Realex Payments United Kingdom: 1 Lyric Square, Hammersmith, London W6 0NB, United Kingdom. t: +44 (0)20 3178 5370 | f: +44 (0)20 7691 7264 | www.realexpayments.co.uk [email protected]

Realex Payments France: 27 avenue de l'Opéra, 75001 Paris. France. t: +33 (0)1 70 38 51 37 | f: +33 (0)1 70 38 51 51 www.realexpayments.com [email protected]

39