RealEFTDevelopersGuidewithXMLDefinitions

Version:v2.2
20002010RealexPayments.Allrightsreserved.ThismaterialisproprietarytoPayandShopLtd,tradingasRealex Payments,Irelandandisnottobereproduced,disclosed,orusedexceptinaccordancewithprogramlicenseorotherwritten authorizationofRealexPayments.Allothertrademarks,servicemarks,andtradenamesreferencedinthismaterialarethe propertyoftheirrespectiveowners.

RealEFTDevelopersGuidewithXMLDefinitions

DocumentInformation
DocumentName:RealEFTDevelopersGuidewithXMLDefinitions DocumentVersion:2.2 ReleaseDate:19July2010

LegalStatement
Thisguide,inadditiontothesoftwaredescribedwithin,isunderthecopyrightownedbyPayandShopLimited, tradingasRealexPayments,andsubjecttolicense.Theincludedsoftwaremaycontainandutilisethirdparty 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 purposewithoutpriorwrittenpermissionfromRealexPayments.Allsoftware,trademarks,logos,designs,and websitescontainedwithinthisguideremaintheintellectualpropertyoftherespectiveindividualownersand companies.

Disclaimer
Every effort has been made to ensure the accuracy of information published in this guide. However Realex Paymentscannotacceptanyresponsibilityforanyerrors,inaccuracies,oromissionsthatmayormaynotbe 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 outofdate information whether publishedinthisguideorfromanylinkinthisguide.RealexPaymentsreservestherighttochangethisguide andtheincludedsoftwarewithoutpriornoticeorconsent.

CompanyInformation
Pay and Shop Limited, trading as Realex Payments has its registered office at Castlecourt, Monkstown Farm, DunLaoghaire,CoDublin,IrelandandisregisteredinIreland,companynumber324929.

RealEFTDevelopersGuidewithXMLDefinitions

TableofContents
1 1.1 1.2 1.3 1.4 1.5 2 3 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 AboutThisGuide Purpose Audience Prerequisites RelatedDocuments Conventions RealEFTIntegration PayerAdministration SetupaNewPayer XMLSyntax HashValueSyntax EditanExistingPayer XMLSyntax HashValueSyntax PaymentMethodSetup XMLSyntax HashValueSyntax 5 5 5 5 5 5 7 8 8 9 10 11 12 13 14 14 16 16 17 18 20 21 23 24 24 26 27 27 28 29 29 30 31

3.10 ActivateaMandate 3.11 XMLSyntax 3.12 HashValueSyntax 4 4.1 4.2 5 5.1 5.2 6 6.1 6.2 7 7.1 7.2 8 Payment(directdebiteft)processing XMLSyntax HashValueSyntax VoidaDirectDebit XMLSyntax HashValueSyntax MarkaDirectDebitasUnpaid XMLSyntax HashValueSyntax CanceltheUnpaidMarkonaDirectDebit XMLSyntax HashValueSyntax RePresentaDirectDebit


8.1 8.2 9 XMLSyntax

RealEFTDevelopersGuidewithXMLDefinitions
31 32 33 36 36 36 36 38

HashValueSyntax Responses

AppendixAResultCodes 9.1 9.2 9.3 SuccessfulTransaction InternalRealexPaymentsError InvalidDataInRequest

AppendixBResultCodes

RealEFTDevelopersGuidewithXMLDefinitions

AboutThisGuide

Thissectionoutlinesthepurposeandaimoftheguide,targetaudience,anysourcematerialsorterminology used,andageneraldocumentdescription.Pleasenotethatthisdocumentisregardedasconfidentialandisfor customeruseonly.Ithasbeensuppliedundertheconditionsofyourpaymentprocessingcontract.

1.1

Purpose

The purpose of this guide is to provide all of the details required to submit valid XML requests for each transactiontypeavailableaspartoftheRealexservice.

1.2

Audience

Thetargetaudienceforthisguideissoftwareandwebdevelopers.

1.3

Prerequisites

Inordertouserealeftfromwithinyourownsystems,youmustfirstintegratewithRealexPayments.Detailsof howtodothis,alongwithsamplecode,arecontainedintherealauthDevelopersGuide. TheremainderofthisdocumentdescribestheformatoftheXMLmessagesneededandthecorrectwaytouse them. You must have access to application or web developers to amend your application or internet site so thatitlinkstoRealexPayments. Inaddition,youmusthavearrangedanOriginatorIdentificationNumberwithyoursponsoringbankbeforeyou canacceptDirectDebits.Thisprocessmustbecompletedwithyourbankandyourbankmustbeoneofthe bankstowhichRealexPaymentsisconnected.Realexsupportsamultiaccountbanksetupsoitispossibleto haveyourcreditanddebitcardfacilitywithonebankandyourdirectdebitfacilitywithanotherbank.

1.4

RelatedDocuments
RealEFTUserGuide

Inadditiontothisguide,youcanalsorefertothefollowingdocumentsintheRealexPaymentsdocumentation setforinformationabouttheRealauthservice:

1.5

Conventions

Realexdocumentationusesthefollowingconventions: Note:Tipsoradvicefortheuser. Caution:Importantnote.Potentialfinancialimpact.


Conventions Blue Italic or Plain Type

RealEFTDevelopersGuidewithXMLDefinitions
Example FormoreinformationseeTable 1.n

Description Hyperlinksandcrossreferences

Italics

Namesofotherguides

Realauth Developers Guide

Courier New Courier New

<comments></comments> Programcode,screenmessages,directoryfiles,andfile names Placeholderforelementnames,fieldvalues,oruser input card_holder_name

BOLD CAPS

Errorandwarningmessages

101 / REFERRAL B

Thefollowingtableoutlinesthemainformattingconventionsusedinthisguide:

RealEFTDevelopersGuidewithXMLDefinitions

RealEFTIntegration

AllXMLrequestsmustbesenttothefollowingURL.https://epage.payandshop.com/epageremoteplugins.cgi Therearetwosetupstepsrequiredbeforeyoucanbeginchargingapayer: Apayerhastobesetuponthesystem Apaymentmethodmustbesetupforthatpayer. Oncethesestepsarecompleted,youcanbeginchargingthatpayeronaregularbasiswithjustasingleXML request. ThisdiagramshowstheEFTTransactionFlow.

RealEFTDevelopersGuidewithXMLDefinitions

3
3.1

PayerAdministration
SetupaNewPayer

ThissectiondescribestheXMLrequestsusedtosetupandmaintainthepayersonthesystem.

Thefirstsetupstageistocreatethepayer.APayeristheinformationyouhaveregardingtheactualperson orcompanyratherthantheiraccountorcarddetails.Thisstepcanbeperformedmanuallyviarealcontrolor canbeintegratedintoyoursales/CRMapplication.Thefollowingsectionsprovidetheinformationnecessaryto submitavalidsetupnewpayerrequesttype: Example XMLSyntax HashValueSyntax

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>


3.2

RealEFTDevelopersGuidewithXMLDefinitions

XMLSyntax
Thesyntaxfortheelementorfield Anindicationofwhethertheelementorfieldismandatory(M)oroptional(O) Theformatforthevalueintermsofallowablecharactersornumbers Theallowablelengthofthevalue Adescription

ForeachXMLelementorfield,thetablebelowprovidesthefollowinginformation:

Pleasenotethatmeansaspace. Element/Field <request type="payer-new" timestamp="20030516175919 "> <merchantid>yourclientid< / merchantid> <orderid>uniqueid</orderi d> <payer type="Business" ref="smithj01"> <title>Mr</title> <firstname>John</firstnam e> <surname>Smith</surname> <company>Acme Inc</company> <address> <line1>Apt 167 Block 10</ line1> <line2>The Hills</line2> line3>67-69 High St</line2> <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</ Mandatory M M O M Format 09 Length 14 Description Thenameforthisrequest typeispayernew. Yourclientidasassigned byRealexPayments. Auniqueidtoidentify thistransaction. Thepayerrefforthis customer.Mustbe unique. Thepayerstitle Firstnameofpayer. Surnameofpayer. CompanyName PayerAddress Thelistofcountrycodes isavailableintherealauth developersguide. PayerPhoneNumbers

azAZ09 150 . azAZ09 _ azAZ azAZ\0 9_ azAZ azAZ azAZ azAZ09 azAZ09 /, azAZ09 /, azAZ09 /, azAZ azAZ azAZ09 azAZ 140 120 150 010 130 150 050 050 050 050 020 020 08 02

O M M O O O O O 0 O O O

O O O O O O

09+ 09+ 09+ 09+

020 020 020 020

O O O O

Format azAZ09 .@_ azAZ09 "",./| azAZ09 .,_+ @!? $ azAZ09 .,_+ @!? $ af09 azAZ09 .,_+ @!? $ azAZ09 .,_+ @!? $

RealEFTDevelopersGuidewithXMLDefinitions
Length 050 030 0255 Description PayerEmail Commentsaboutthe payer

Element/Field mobile> </phonenumbers> <email>[email protected]</ email> <comments> <comment id="1" />

Mandatory

<comment id="2" />

0255

</comments> </payer> <sha1hash>7daf026b193e.5 9597 18c567</sha1hash> <comments> <comment id="1" />

O O M O O

40 0255

TheSHA1hashofthis message. Commentsaboutthis transaction

<comment id="2" />

0255

</comments> </request>

O O

3.3
Format: Example:

HashValueSyntax

Thefollowingtableillustratesthehashvaluesyntaxforsettingupanewpayer:

timestamp.merchantid.orderid.amount.currency.payerref 20010427124523.merchantid.orderid.100.GBP.payerref

Toconstructthepayernewhashfollowthisprocedure: Formastringbyconcatenatingtheabovefieldswithaperiod(.)(Ifavalueforcreatingthehashis notincludedintheXMLjustleaveitblank,butalwaysincludeallofthedots.)

(20010403123245.thestore.ORD45311.29900.EUR.smithj01) Getthehashofthisstring(SHA1shownbelow).

(153872918f7f4e81fa7a5a5763d73b32853ca54c)
10

Createanewstringbyconcatenatingthisstringandyoursharedsecretusingaperiod.

RealEFTDevelopersGuidewithXMLDefinitions

(153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret) Getthehashofthisvalue.ThisisthevaluethatyousendtoRealexPayments.

(8e629d8455b760eff776f6ca6fb0be8b2fe18803) <sha1hash>8e629d8455b760eff776f6ca6fb0be8b2fe18803</sha1hash>

3.4

EditanExistingPayer

Thisrequesttypeisusedtoeditthedetailsofapayer.Itmustcontaintheoriginalpayerreference. Ithastwosetsofcomments.Thefirstsetiscommentsaboutthepayer.Thesecondsetofcommentsisabout thepayeredittransactionitself.Thefollowingsectionsprovidetheinformationnecessarytoeditanexisting payer: Example XMLSyntax HashValueSyntax

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</postcode> <country code="IE"> Ireland </country> </address> <phonenumbers> <home /> <work>+35317433923</work> <fax>+35317893248</fax> <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>

11


3.5

RealEFTDevelopersGuidewithXMLDefinitions

XMLSyntax
Thesyntaxfortheelementorfield Anindicationofwhethertheelementorfieldismandatory(M),optional(O),orconditional(C) dependingonanotheroptionalfield Theformatforthevalueintermsofallowablecharactersornumbers Theallowablelengthofthevalue Adescription

ForeachXMLelementorfield,thetablebelowprovidesthefollowinginformation:

XMLSyntaxtoEditanExistingPayer Element/Field <request type="payer-edit" 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</line2> <city>Hytown</city> <county>Dunham</county> <postcode>3</postcode> <country code="IE"> Ireland </country> </address> Mandatory M Format 09 Length 14 type:aut h azAZ09 150 . azAZ09 140 _ azAZ azAZ\0 9_ azAZ azAZ azAZ azAZ09 azAZ09 /, azAZ09 /, azAZ09 /, azAZ azAZ azAZ09 azAZ 120 150 010 130 150 050 050 050 050 020 020 08 02 Description Thenameforthis requesttypeis payeredit. Yourclientidas assignedby RealexPayments. Auniqueidto identifythis transaction. Thepayerreffor thiscustomer. Mustbeunique. Thepayerstitle Firstnameof payer. Surnameofpayer. CompanyName PayerAddress Thelistofcountry codesisavailable intherealauth developersguide.

O M M O O O O O 0 O O O

12

Format 09+ 09+ 09+ 09+ azAZ09 .@_ azAZ09 "",./| azAZ09 .,_+ @!? $ azAZ09 .,_+ @!? $ af09 azAZ09 .,_+ @!? $ azAZ09 .,_+ @!? $

RealEFTDevelopersGuidewithXMLDefinitions
Length 020 020 020 020 050 030 0255 Description PayerPhoneNumbers PayerEmail

Element/Field <phonenumbers> <home>+35317285355</home> <work>+35317433923</work> <fax>+35317893248</fax> <mobile>+353873748392</ mobile> </phonenumbers> <email>[email protected]</ email> <comments> <comment id="1" />

Mandatory O O O O O O O O O

Commentsaboutthepayer

<comment id="2" />

0255

</comments> </payer> <sha1hash>7daf026b193e.59 59 718c567</sha1hash> <comments> <comment id="1" />

O O M O O

40 0255

TheSHA1hashof thismessage. Commentsaboutthis transaction

<comment id="2" />

0255

</comments> </request>

O O

3.6
Format: Example:

HashValueSyntax

Thefollowingtableillustratesthehashvaluesyntaxforeditinganexistingpayer:

timestamp.merchantid.orderid.amount.currency.payerref 20010427124523.merchantid.orderid.100.GBP.payerref

Toconstructthepayeredithashfollowthisprocedure: Formastringbyconcatenatingtheabovefieldswithaperiod(.)(Ifavalueforcreatingthehashisnot includedintheXMLjustleaveitblank,butalwaysincludeallofthedots.) (20010403123245.thestore.ORD45311.29900.EUR.smithj01)

13

RealEFTDevelopersGuidewithXMLDefinitions

Getthehashofthisstring(SHA1shownbelow). (153872918f7f4e81fa7a5a5763d73b32853ca54c) Createanewstringbyconcatenatingthisstringandyoursharedsecretusingaperiod. (153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret) Getthehashofthisvalue.ThisisthevaluethatyousendtoRealexPayments. (8e629d8455b760eff776f6ca6fb0be8b2fe18803) <sha1hash>8e629d8455b760eff776f6ca6fb0be8b2fe18803</sha1hash>

3.7

PaymentMethodSetup

Once the payer is in place you can add payment methods to it. Once again this step may be performed manuallyviarealcontrolorbeintegratedusingtheXMLmessagesbelow. AddMandateDetails ToaddthedetailsofaDirectDebitMandate,usetheddinewrequesttype.Thefollowingsectionsprovidethe informationnecessarytosubmitavalidaddmandatedetailsrequesttype: Example XMLSyntax HashValueSyntax

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

XMLSyntax

ForeachXMLelementorfield,thetablebelowprovidesthefollowinginformation:

14

RealEFTDevelopersGuidewithXMLDefinitions

Thesyntaxfortheelementorfield Anindicationofwhethertheelementorfieldismandatory(M),optional(O),orconditional(C) dependingonanotheroptionalfield

Theformatforthevalueintermsofallowablecharactersornumbers Theallowablelengthofthevalue Adescription Mandatory M Format 09 Length 14 type:auth 150 Description Thenameforthis requesttypeis ddinew. Yourclientidas assignedby RealexPayments. Auniqueidto identifythis transaction. Thereferencefor thiscard Thepayerreffor thiscustomer. Alistofaccounts thatthiscanbe usedwith. ThePayerssort code. ThePayers accountnumber. ThePayersBank Thenameonthe Payersaccount.

Element/Field <request type="ddi-new" timestamp="20030516180730"> <merchantid>yourclientid</ merchantid> <orderid>uniqueid</orderid>

azAZ09.

azAZ09_ azAZ09_ azAZ09_

140

<ddi> <ref>mandate01</ref> <payerref>smithj01</ payerref> <accounts>

M M M M

130 150

<account>eft</account> </accounts> <sortcode>933384</sortcode> <account number>72121495</ accountnumber> <bank>aib</bank> <name>John Smith</name>

M M M M M M

azAZ09 +' 09 09 azAZ09 azAZ09 .,_+@ !? $ 09/

120 110 120 130 120

<expiry>06/09/2010</expiry>

010

<comments> </comments> </ddi> <sha1hash>96879e9aed1778029 2d217856</sha1hash> </request>

0 O M M M

af09

40

Theexpirydateof themandate.After thisdatethis mandatecanno longerbeused. Commentsmade aboutthismandate TheSHA1hashof thismessage.


3.9
Format: Example:

RealEFTDevelopersGuidewithXMLDefinitions

HashValueSyntax

Thefollowingtableillustratesthehashvaluesyntaxforavalidaterequesttype:

timestamp.merchant_id.order_id.amount.currency.ddipayerref.ddisortcode.ddiaccountnumber 20010427124523.merchantid.orderid.100.GBP.ddipayerref.ddisortcode.ddiaccountnumber

Toconstructtheddijnewhashfollowthisprocedure: Formastringbyconcatenatingtheabovefieldswithaperiod(.)(Ifavalueforcreatingthehashisnot includedintheXMLjustleaveitblank,butalwaysincludeallofthedots.) (20010403123245.thestore.ORD45311.29900.EUR.smithj01.933384.72121495) Getthehashofthisstring(SHA1shownbelow). (45c87c85cc54ba08628d03e3f45b8563b58425aa) Createanewstringbyconcatenatingthisstringandyoursharedsecretusingaperiod. (45c87c85cc54ba08628d03e3f45b8563b58425aa.mysecret) Getthehashofthisvalue.ThisisthevaluethatyousendtoRealexPayments. (6df141152a4e53afd1bc32d8e5192854964905f9) <sha1hash>6df141152a4e53afd1bc32d8e5192854964905f9</sha1hash>

3.10

ActivateaMandate

ThenextrequesttypeistheDDIedit.ThisrequesttypeisusedchangethestatusofaparticularDDI.Itmust containtheoriginalDDIreference,originalpayerreferenceandoriginalaccount.Thisrequesttypeisusedto changethestatusofaDDItoeitherPending(P),Active(A)orCancelled(C).Thisisspecifiedinthestatustag.A mandatecanonlybeusedifitisActive. Thefollowingsectionsprovidetheinformationnecessarytosubmitavalidactivatemandaterequesttype: Example XMLSyntax HashValueSyntax

16


Example

RealEFTDevelopersGuidewithXMLDefinitions

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

XMLSyntax
Thesyntaxfortheelementorfield Anindicationofwhethertheelementorfieldismandatory(M),optional(O),orconditional(C) dependingonanotheroptionalfield

ForeachXMLelementorfield,thetablebelowprovidesthefollowinginformation:

Theformatforthevalueintermsofallowablecharactersornumbers Theallowablelengthofthevalue Adescription

17

Mandatory M

Format 09

RealEFTDevelopersGuidewithXMLDefinitions
Length 14 type:auth 150 Description Thenameforthis requesttypeisddiedit. Yourclientidas assignedbyRealex Payments. Auniqueidtoidentify thistransaction. Thereferenceforthis card Thepayerrefforthis customer. Alistofaccountsthat thiscanbeusedwith. TheStatustosetthis mandate 0255 40 Commentsmadeabout thismandate TheSHA1hashofthis message.

Element/Field <request type="ddiedit" timestamp="200305161811 27"> <merchantid>yourclienti d</ merchantid> <orderid>uniqueid</orde rid> <ddi> <ref>visa01</ref> <payerref>smithj01</ payerref> <accounts> <account>eft</account> </accounts> <status>A/status> <comments> <comment id="1" /> </comments> </ddi> <sha1hash>4d708b24e8af d8347 060fdd65</sha1hash> </request>

azAZ09.

O M M M M M M M 0 O O M M M

azAZ09_ azAZ09_ azAZ09_ azAZ09 +' azAZ09 +' azAZ09 +' af09

140 130 150 120 150

3.12
Format Example:

HashValueSyntax
timestamp.merchant_id.order_id.amount.currency.ddipayerref.ddisortcode.ddiaccountnumber 20010427124523.merchantid.orderid.100.GBP.ddipayerref.ddisortcode.ddiaccountnumber

Thefollowingtableillustratesthehashvaluesyntaxforupdatingcardexpirydate:

Toconstructtheddiedithashfollowthisprocedure: Formastringbyconcatenatingtheabovefieldswithaperiod(.)(Ifavalueforcreatingthehashisnot includedintheXMLjustleaveitblank,butalwaysincludeallofthedots.) (20010403123245.thestore.ORD45311.29900.EUR.smithj01.933384.72121495) Getthehashofthisstring(SHA1shownbelow). (45c87c85cc54ba08628d03e3f45b8563b58425aa)

RealEFTDevelopersGuidewithXMLDefinitions

Createanewstringbyconcatenatingthisstringandyoursharedsecretusingaperiod. (45c87c85cc54ba08628d03e3f45b8563b58425aa.mysecret) Getthehashofthisvalue.ThisisthevaluethatyousendtoRealexPayments. (6df141152a4e53afd1bc32d8e5192854964905f9) <sha1hash>6df141152a4e53afd1bc32d8e5192854964905f9</sha1hash>

19

RealEFTDevelopersGuidewithXMLDefinitions

Payment(directdebiteft)processing

This section describes the XML requests used to process and administer the payment requests into Realex Payments. Raiseapayment Toraiseapaymentusinganypaymentmethod,usethereceiptintransaction. The following sections provide the information necessary to submit a valid eftupdate expirydate request type: Example XMLSyntax HashValueSyntax

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>

20


4.1

RealEFTDevelopersGuidewithXMLDefinitions

XMLSyntax
Thesyntaxfortheelementorfield Anindicationofwhethertheelementorfieldismandatory(M),optional(O),orconditional(C) dependingonanotheroptionalfield

ForeachXMLelementorfield,thetablebelowprovidesthefollowinginformation:

Theformatforthevalueintermsofallowablecharactersornumbers Theallowablelengthofthevalue Adescription

Element/Field <request type="receiptin" timestamp="20030516181127 "> <merchantid>yourclientid< / merchantid> <account>eft</account>

Mandatory M

Format 09

Length 14 150 120

Description Thenameforthisrequesttypeis receiptin. YourclientidasassignedbyRealex Payments. Theaccountthroughwhichto processthistransaction Auniqueidtoidentifythis transaction. TheCardVerificationNumber.This isthe3digitnumberonthe reverseofthecard.(theCVCfor VISAandtheCVV2for MasterCard)4digitnumberonan Amex. Theautosettleindicator.If1 thenthetransactionwillbesentto thebankforsettlementtonight.If setto0thenthetransactionwill remainintheRealexPayments databasefor28daysoruntil manuallysettled. Thecurrencyandamountofthis transaction.Seetherealauth DevelopersGuidefordetailsof thecurrencycodes Thepayerreferenceofthe customer. Thepaymentreference.

M M

azAZ 09. azAZ 09 * azAZ 09_ 09

<orderid>uniqueid</orderi d> <paymentdata> </cvn> <number>123</number>

O O O O

140 34

</cvn> <paymentdata> <autosettle flag="1" />

O M

See Details

N/A

<amount currency="EUR">9999</ amount> <payerref>bloggsj01</ payerref> <paymentmethod>mandate01<

azAZ 09

3 211

M M

azAZ 09_ azAZ

150 150

21

RealEFTDevelopersGuidewithXMLDefinitions
Description

Element/Field / paymentmethod> <sha1hash>c81377ac77b6c. .3d0 1c3d98eb</sha1hash> <comments> <comment id="1" />

Mandatory

Format Length 09_ af09 azAZ 09., _+@! ? $ azAZ 09., _+@! ? $ azAZ 09,. /| azAZ 09,. azAZ 09,. /| azAZ 09,. azAZ 09 _.,+@ azAZ 09 _.,+@ azAZ 09 _.,+@ 40 0255

M O 0

TheSHA1hashoftherequest. Commentsaboutthetransaction

<comment id="2" />

0255

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

O O O O

030

Therealscore(formerlyTSS) information.

030

O O O

030

030

O O

Yourreferencenumberforthe customer. Anemailaddressormobile numberoranyotherusefulvalue canbesentwitheachrequest. Typicallyyourproductcode.

<varref></varref>

<prodid></prodid>

</tssinfo> </request>

O M

22


4.2
Format: Example:

RealEFTDevelopersGuidewithXMLDefinitions

HashValueSyntax
t: timestamp.merchant_id.order_id.amount.currency.payerref 20010427124523.merchantid.order_id.100.GBP.payerref

Thefollowingtableillustratesthehashvaluesyntaxforupdatingcardexpirydate:

Toconstructthereceiptinhashfollowthisprocedure: Formastringbyconcatenatingtheabovefieldswithaperiod(.)(Ifavalueforcreatingthehashisnot includedintheXMLjustleaveitblank,butalwaysincludeallofthedots.) (20010403123245.thestore.ORD45311.29900.EUR.smithj01) Getthehashofthisstring(SHA1shownbelow). (153872918f7f4e81fa7a5a5763d73b32853ca54c) Createanewstringbyconcatenatingthisstringandyoursharedsecretusingaperiod. (153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret) Getthehashofthisvalue.ThisisthevaluethatyousendtoRealexPayments. (8e629d8455b760eff776f6ca6fb0be8b2fe18803) <sha1hash>8e629d8455b760eff776f6ca6fb0be8b2fe18803</sha1hash>

23

RealEFTDevelopersGuidewithXMLDefinitions

VoidaDirectDebit

Tovoidadirectdebitusetheeftvoidtransaction. Thefollowingsectionsprovidetheinformationnecessarytosubmitavalideftvoidrequesttype: 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> Example XMLSyntax HashValueSyntax

5.1

XMLSyntax
Thesyntaxfortheelementorfield Anindicationofwhethertheelementorfieldismandatory(M),optional(O),orconditional(C) dependingonanotheroptionalfield

ForeachXMLelementorfield,thetablebelowprovidesthefollowinginformation:

Theformatforthevalueintermsofallowablecharactersornumbers Theallowablelengthofthevalue Adescription

24

Mandatory M

Format 09

RealEFTDevelopersGuidewithXMLDefinitions
Length 14 Description Thenameforthisrequest typeiseftvoid. Yourclientidasassignedby RealexPayments. Theaccountthroughwhichto processthistransaction Auniqueidtoidentifythis transaction. Thecurrencyandamountof thistransaction.Seethe realauthDevelopersGuide fordetailsofthecurrency codes Thepayerreferenceofthe customer. Thepaymentreference. TheSHA1hashoftherequest. Seebelowfordetails. Thisisthehashoftherefund password(RealexPayments willgivethistoyou).TheSHA1 algorithmmustbeusedto generatethishash. Commentsaboutthis transaction.

XMLsyntaxtoRaiseaProcessaRefund Element/Field <request type="eftvoid" timestamp="20030520151 742"> <merchantid>yourclient id</merchantid> <account>eft</account> <orderid>transaction01 </orderid> <amount currency="EUR">9999</a mount>

M M O M

azAZ09 150 . azAZ09 120 * azAZ09 140 _

<payerref>bloggsj01</ payerref> <paymentmethod>mandate 01 </paymentmethod> <sha1hash>c81377ac77b6 c..3d0 1c3d98eb</sha1hash> <refundhash>738e83.... 3434dda e662a</refundhash>

M M M
M

a-z A-Z 09 - _ a-z A-Z 09 _- a-f 0-9

1-50 1-50

40

a-f 0-9

40

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

O 0

azAZ09 .,_+ @!? $ azAZ09 .,_+ @!? $ azAZ09 ,./| azAZ09 ,.

0255

<commentid="2"/>

0255

</comments> <tssinfo> <address type="billing"> <code>zip/postal code</code> <country>country</coun try> </address> <address type="shipping"> <code>zip/postal

O O O O O O O O

030 030

Therealscore(formerlyTSS) information.

azAZ09 030

25

O O O

Mandatory

Format ,./| azAZ09 ,. azAZ09 _.,+ @ azAZ09 _.,+ @

RealEFTDevelopersGuidewithXMLDefinitions
Length 030 Description Yourreferencenumberforthe customer. Anemailaddressormobile numberoranyotheruseful valuecanbesentwitheach request. Typicallyyourproductcode.

Element/Field code</code> <country>country</coun try> </address> <custnum></custnum>

<varref></varref>

<prodid></prodid>

</tssinfo> </request>

O M

azAZ09 _.,+ @

5.2
Format: Example:

HashValueSyntax

Thefollowingtableillustratesthehashvaluesyntaxforupdatingcardexpirydate:

timestamp.merchant_id.order_id.amount.currency.payerref 20010427124523.merchantid.order_id.100.GBP.payerref

Toconstructtheeftvoidhashfollowthisprocedure: Formastringbyconcatenatingtheabovefieldswithaperiod(.)(Ifavalueforcreatingthehashisnot includedintheXMLjustleaveitblank,butalwaysincludeallofthedots.) (20010403123245.thestore.ORD45311.29900.EUR.smithj01) Getthehashofthisstring(SHA1shownbelow). (153872918f7f4e81fa7a5a5763d73b32853ca54c) Createanewstringbyconcatenatingthisstringandyoursharedsecretusingaperiod. (153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret) Getthehashofthisvalue.ThisisthevaluethatyousendtoRealexPayments. (8e629d8455b760eff776f6ca6fb0be8b2fe18803) <sha1hash>8e629d8455b760eff776f6ca6fb0be8b2fe18803</sha1hash>

26

RealEFTDevelopersGuidewithXMLDefinitions

MarkaDirectDebitasUnpaid

Tomarkadirectdebitasunpaid,usetheeftunpaidtransaction. Thefollowingsectionsprovidetheinformationnecessarytosubmitavalideftunpaidrequesttype: Example XMLSyntax HashValueSyntax

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

XMLSyntax

ForeachXMLelementorfield,thetablebelowprovidesthefollowinginformation: Thesyntaxfortheelementorfield Anindicationofwhethertheelementorfieldismandatory(M)oroptional(O) Theformatforthevalueintermsofallowablecharactersornumbers Theallowablelengthofthevalue Adescription Pleasenotethatmeansaspace. Element/Field Mandatory Format Length Description <request type="eftM 09 14 Thenameforthisrequest unpaid" typeiseftunpaid. timestamp="20030520152117 "> <merchantid>yourclientid< M azAZ 150 Yourclientidasassignedby / 09. RealexPayments. merchantid> <account>eft</account> M azAZ 120 Theaccountthroughwhich 09 toprocessthistransaction * <orderid>20030501-0023</ O azAZ 140 Theorderidusedinthe orderid> 09_ originaltransaction.

27

Mandatory M

Format azAZ 09 :

RealEFTDevelopersGuidewithXMLDefinitions
Length 150 Description Thereasonthetransaction wasreturned.Thesecodes areoutlinesinAppendixC.

Element/Field <reasoncode>0</reasoncode >

<pasref>8656d1e2fadf4bd99 418 88b95673bb93</pasref> <sha1hash>00af6e23b3fadc da7 20b5fa8644281d</sha1hash> <comments> <comment id="1">Refer to Payer</comment>

azAZ 09

150

ThePASReferencereturned intheresponsetothe originaltransaction. TheSHA1hashofthe request.Seebelowfor details. Commentsaboutthis transaction.

af09

40

O O

azAZ 09 _., + @!? $ azAZ 09 _., + @!? $

0255

<comment id="2" />

0255

</comments> </request>

6.2
Format: Example:

HashValueSyntax
timestamp.merchant_id.order_id.amount.currency.payerref 20010427124523.merchantid.order_id.100.GBP.payerref

Toconstructtheeftunpaidhashfollowthisprocedure: Formastringbyconcatenatingtheabovefieldswithaperiod(.)(Ifavalueforcreatingthehashisnot includedintheXMLjustleaveitblank,butalwaysincludeallofthedots.) (20010403123245.thestore.ORD45311.29900.EUR.smithj01) Getthehashofthisstring(SHA1shownbelow). (153872918f7f4e81fa7a5a5763d73b32853ca54c) Createanewstringbyconcatenatingthisstringandyoursharedsecretusingaperiod. (153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret) Getthehashofthisvalue.ThisisthevaluethatyousendtoRealexPayments. (8e629d8455b760eff776f6ca6fb0be8b2fe18803) <sha1hash>8e629d8455b760eff776f6ca6fb0be8b2fe18803</sha1hash>
28

RealEFTDevelopersGuidewithXMLDefinitions

CanceltheUnpaidMarkonaDirectDebit

Tocancelanunpaidmarkonadirectdebit,usetheeftcancelunpaidtransaction. Thefollowingsectionsprovidetheinformationnecessarytosubmitavalideftcancelunpaidrequesttype: Example XMLSyntax HashValueSyntax 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>

7.1

XMLSyntax

ForeachXMLelementorfield,thetablebelowprovidesthefollowinginformation: Thesyntaxfortheelementorfield Anindicationofwhethertheelementorfieldismandatory(M)oroptional(O) Theformatforthevalueintermsofallowablecharactersornumbers Theallowablelengthofthevalue Adescription Pleasenotethatmeansaspace. Element/Field Mandatory Format Length Description <request type="eft-cancelM 09 14 Thenameforthisrequest unpaid" typeiseftunpaid. timestamp="20030520152031" > <merchantid>yourclientid</ M azAZ09. 150 Yourclientidasassigned merchantid> byRealexPayments. <account>eft</account> M azAZ09 120 Theaccountthrough * whichtoprocessthis transaction <orderid>20030501-0023</ O azAZ09_ 140 Theorderidusedinthe orderid> originaltransaction. <reasoncode>0</reasoncode> M azAZ09 150 Thereasonthe : transactionwasreturned. Thesecodesareoutlines
29


Element/Field

Format azAZ09

RealEFTDevelopersGuidewithXMLDefinitions
Length 150

Mandatory

<pasref>8656d1e2fadf4bd994 18 88b95673bb93</pasref> <sha1hash>00af6e23b3fadcd a7 20b5fa8644281d</sha1hash> <comments> <comment id="1">Refer to Payer</comment> <comment id="2" />

af09

40

O O

azAZ09 _.,+ @!?$ azAZ09 _.,+ @!?$

0255

Description inAppendixC. ThePASReference returnedintheresponse totheoriginal transaction. TheSHA1hashofthe request.Seebelowfor details. Commentsaboutthis transaction.

0255

</comments> </request>

7.2

HashValueSyntax

Format: timestamp.merchant_id.order_id.amount.currency.payerref Example: 20010427124523.merchantid.order_id.100.GBP.payerref Toconstructtheeftunpaidhashfollowthisprocedure: Formastringbyconcatenatingtheabovefieldswithaperiod(.)(Ifavalueforcreatingthehashisnot includedintheXMLjustleaveitblank,butalwaysincludeallofthedots.) (20010403123245.thestore.ORD45311.29900.EUR.smithj01) Getthehashofthisstring(SHA1shownbelow). (153872918f7f4e81fa7a5a5763d73b32853ca54c) Createanewstringbyconcatenatingthisstringandyoursharedsecretusingaperiod. (153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret) Getthehashofthisvalue.ThisisthevaluethatyousendtoRealexPayments. (8e629d8455b760eff776f6ca6fb0be8b2fe18803) <sha1hash>8e629d8455b760eff776f6ca6fb0be8b2fe18803</sha1hash>

30

RealEFTDevelopersGuidewithXMLDefinitions

RePresentaDirectDebit

Torepresentadirectdebit,usetheeftrepresenttransaction. Thefollowingsectionsprovidetheinformationnecessarytosubmitavalideftcancelunpaidrequesttype: Example XMLSyntax HashValueSyntax 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>

8.1

XMLSyntax

ForeachXMLelementorfield,thetablebelowprovidesthefollowinginformation: Thesyntaxfortheelementorfield Anindicationofwhethertheelementorfieldismandatory(M)oroptional(O) Theformatforthevalueintermsofallowablecharactersornumbers Theallowablelengthofthevalue Adescription Pleasenotethatmeansaspace. Element/Field <request type="eftrepresent" timestamp="20030520152031" > <merchantid>yourclientid</ merchantid> <account>eft</account> Mandatory M Format 09 Length 14 Description Thenameforthisrequest typeiseftrepresent. Yourclientidasassigned byRealexPayments. Theaccountthrough whichtoprocessthis transaction Theorderidusedinthe originaltransaction. Thereasonthe transactionwasreturned. Thesecodesareoutlines inAppendixC. ThePASReference returnedintheresponse totheoriginal

M M

azAZ09 150 . azAZ09 120 * azAZ09 140 _ azAZ09 150 :

<orderid>20030501-0023</ orderid> <reasoncode>0</reasoncode>

O M

<pasref>8656d1e2fadf4bd994 18 88b95673bb93</pasref>

azAZ09 150

31

af09

RealEFTDevelopersGuidewithXMLDefinitions
40 transaction. TheSHA1hashofthe request.Seebelowfor details. Commentsaboutthis transaction.

<sha1hash>00af6e23b3fadcd a7 20b5fa8644281d</sha1hash> <comments> <comment id="1">Spoke to client - money in account now</comment> <comment id="2" />

O O

azAZ09 _.,+ @!?$ azAZ09 _.,+ @!?$

0255

0255

</comments> </request>

8.2

HashValueSyntax

Format: timestamp.merchant_id.order_id.amount.currency.payerref Example: 20010427124523.merchantid.order_id.100.GBP.payerref Toconstructtheeftrepresenthashfollowthisprocedure: Formastringbyconcatenatingtheabovefieldswithaperiod(.)(Ifavalueforcreatingthehashisnot includedintheXMLjustleaveitblank,butalwaysincludeallofthedots.) (20010403123245.thestore.ORD45311.29900.EUR.smithj01) Getthehashofthisstring(SHA1shownbelow). (153872918f7f4e81fa7a5a5763d73b32853ca54c) Createanewstringbyconcatenatingthisstringandyoursharedsecretusingaperiod. (153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret) Getthehashofthisvalue.ThisisthevaluethatyousendtoRealexPayments. (8e629d8455b760eff776f6ca6fb0be8b2fe18803) <sha1hash>8e629d8455b760eff776f6ca6fb0be8b2fe18803</sha1hash>

32

RealEFTDevelopersGuidewithXMLDefinitions

Responses

AllrequestssenttotheRealexPaymentssystemwillreceivearesponse.Therearetwopossibleresponsesyou willreceivewhileusingtherealEFTservice: Asuccessfulresponse,whichindicatesthattherequestsentwascorrect Anunsuccessfulresponse,whichindicatestherequestwasinvalid. ResponseFormat Thetworesponseformatsareshownbelow. ResponseformatSuccessfulrequest: Thisresponsecontainsthemerchantid,theaccountused,theorderidused,aresultcodewithcorresponding resultmessage,aPASreference,batchid,thehashreturnedandthetimetakenforthetransactiontotake 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> ResponseformatUnsuccessfulrequest: Thisresponsecontainsaresulterrorcodewithacorrespondingerrormessage. <response timestamp="20030520152009"> <result>Unsuccessful result code</result> <message>Unsuccessful Message</message> </response>

ResponseResultCodes Thissectiondescribestheresponseresultcodesandtheircorrespondingmessages.Iftherequestwas successfultheresponseresultcodeis00andtheassociatedresultmessageisSUCCESSFUL. Iftheresponseresultcodeisnot00thentherewasanerrorprocessingtherequest.Thefollowingsections describepossibleerrorsreturnedbyRealexPayments.

33

RealEFTDevelopersGuidewithXMLDefinitions

3xxResultCodes The3xxresultcodesindicatethatthereisanerrorwithRealexPaymentsinternalsystem.Theseresulttypes areveryrare.Ifyoureceivea3xxresultcode,pleasecontactRealexPayments.AppendixAgivesamore detaileddescriptionofthepossibleerrorresultmessagesreturnedfora3xxerror. Result Message 300 ProblemconnectingtoRealexdatabase 304 Problemaccessingfileforprocessing 320 GeneralConfigurationError 5xxResultCodes The5xxresultcodesindicatethatthereisanerrorinthedatasenttoRealex.ThesectionInvalidDataIn RequestinAppendixAgivesalistof5xxerrormessagesreturnedbyRealex. Result Message 501 Thereferenceintherequestisnotvalid 502 MandatoryFieldMissing 503 Requesttypenotsupported 505 AuthenticationError 508 Invaliddateentereddeveloperhascodedincorrectly 520 InvalidreferencecombinationsentintoRealex 521 Merchantnotsetuptoprocessthatcurrency DigitalSignatures To ensure authentication (that the request comes from you) we require that you send us a hash of certain elements(specifichashfieldshavebeennotedattheendofeachrequest)usingasharedsecret.Thiscanbea MD5hashorpreferablyaSHA1hash.Ifrequired,wecanalsoprovidesamplecodeforthis. MD5 and SHA1 algorithms are secure hash functions. They take a string as input, and produce a fixed size number128bitsforMD5;160bitsforSHA1.Thisnumberisahashoftheinput,andasmallchangeinthe inputresultsinasubstantialchangeintheoutput.Thefunctionsarethoughttobesecureinthesensethatit requiresanenormousamountofcomputingpowerandtimetofindastringthathashestothesamevalue.In otherswords,thereisnowaytodecryptasecurehash.Giventhelargerkeysize,youmaypreferaSHA1hash, butwehaveretainedtheMD5forcompatibilitywitholdersystems. BelowisafragmentofasampleXMLmessage: <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

RealEFTDevelopersGuidewithXMLDefinitions

Toconstructthehashfollowthisprocedure: Formastringbyconcatenatingtheabovefieldswithaperiod(.)(Ifavalueforcreating thehashisnotincludedintheXMLjustleaveitblank,butalwaysincludeallofthedots.) (20010403123245.thestore.ORD45311.29900.EUR.5105105105105100) Getthehashofthisstring(SHA1shownbelow). (c5d02900c2ed43e0015d5e6792e2071a7b20afd5) Createanewstringbyconcatenatingthisstringandyoursharedsecretusingaperiod. (c5d02900c2ed43e0015d5e6792e2071a7b20afd5.mysecret) Getthehashofthisvalue.ThisisthevaluethatyousendtoRealexPayments. (9af7064afd307c9f988e8dfc271f9257f1fc02f6) <sha1hash> 9af7064afd307c9f988e8dfc271f9257f1fc02f6 </sha1hash> When Realex Payments receive the request, we perform the same procedure on the same pieces of informationandyoursharedsecret(whichwehavestoredinourdatabase).Iftheresultinghashisthesameas theonethatyousentus,thenthedatacouldonlyhavebeensentbysomeonethathadyoursharedsecret. Thus,itisveryimportanttopermissiontheCGIprogramappropriatelytokeepthissharedsecretprotected. Wewillsendyouahashoftheresponseelementsinthesamewaysothatyoucanconfirmthattheresponse came from Realex. (This will be a hash of the timestamp, merchant id, order id, result, message, Realex Paymentsreferenceandauthcodewithyoursecretkey.Ifyousentusanmd5hash,youwillreceiveanmd5 hashintheresponseandsimilarlyforasha1hash).

35

RealEFTDevelopersGuidewithXMLDefinitions

AppendixAResultCodes
9.1
Code 00 Description Successful

SuccessfulTransaction

9.2
Code 300 300 304 304 304 320 320 320

InternalRealexPaymentsError
Description CouldntconnecttotheEFTDatabase CouldntconnecttotheLiveDatabase Internalrealexerror.realexhavebeennotified,couldn'tdorequest.eft.rxp Internalrealexerror.realexhavebeennotified,couldn'tparserequest.eft.rxp Internalrealexerror.realexhavebeennotified,couldn'trunrequest.eft.rxp ErrorinSQLRealexPaymentshavebeennotified Thereisnooriginatordataforthisaccount! Unabletoopennewbatch!

9.3
Code 300 300 304 304 304 320 320 320 503 505 505 508 508 508 508 508 508 508

InvalidDataInRequest
Description ThisDDMandateRefmandatenamehasalreadybeenused[Perhapsyou've alreadysetupaDDMandateforthisPayer?] ThisDDIdoesnotexist ThisDDIRefddirefnamehasalreadybeenused[Perhapsyou'vealreadysetupa DDIforthisPayer?] ThisorderIDhasalreadybeenusedpleaseuseanotherone ThisPayerRefpayerrefdoesnotexist ThisPayerRefpayerrefhasalreadybeenusedpleaseuseanotherone MandatoryFieldsmissing:errormessage.SeeDevelopersGuide Requesttyperequesttypenotsupportedonthisaccountname YouhavenoEFTaccounts.Requesttyperequesttypenotsupported MD5Hashincorrect SHA1Hashincorrect AccountnameisnotaDirectDebitaccount Accountnumbersmustbebetween6and10digitsinlength Banknamescontainonlyletters. CannotfindoriginalDirectDebitindatabase Expirydateinpast Expirydateinwrongformat:pleaseusedd/mm/yyyy InvalidcharactersinDDIRefpleaseuseonlyAZaz09_

36


Code 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 508 520 520 521

RealEFTDevelopersGuidewithXMLDefinitions

Description Invalidcharactersinddireferencepleaseuseonlydigits,letters,_ Invalidcharactersinemailpleaseuseonlydigits,letters,spaces,\@._ InvalidcharactersinNarrativepleaseuseonlyAZaz09_space. InvalidcharactersinOriginatorNamepleaseuseonlyAZaz09_space InvalidcharactersinpasrefpleaseuseonlyAZaz09 InvalidcharactersinPayerRefpleaseuseonlyAZaz09_ Invalidcharactersinpayerreferencepleaseuseonlydigits,letters,_ Invalidcharactersinpayertypepleaseuseonlydigits,letters,spaces, Invalidcharactersinsortorder Invaliddataincurrencyfield Invaliddateshouldbeindd/mm/yyyyformat InvalidDDTypeseeDevelopersGuideforvalidStatusCodes InvalidDDIStatusseeDevelopersGuideforvalidStatusCodes InvalidStatus:onlyA(approved)isacceptable InvalidStatus:onlyA(approved)orP(pendingapproval)areacceptable InvalidStatus:onlyAorPallowed Leadingzerosororothererrorinamountfield Onlynumbersinaccountnumberplease Onlynumbersinsortcodeplease(format:9xxxxx) OriginalTransactionalreadyrepresented.Youcanonlyrepresentatransaction once. OriginalTransactionhasbeenrepresented.Youcan'tcancelthisunpaidmark. OriginalTransactionisalreadymarkedunpaid.orderid OriginalTransactionwasalreadyvoided! OriginalTransactionwasnotmarkedunpaid.Youcan'trepresentit. OriginalTransactionwasnotmarkedunpaid. OriginalTransactionwasvoided!Youcan'tdothis. OriginalTransactionwasvoided!Youcan'tmarkitunpaid. OriginalTransactionwasvoided!Youcan'trepresentit. Pleaseonlynumbersinamountseedevelopersguide PleaseuseonlylettersandnumbersinthePayerBankAccountName SortCodeshouldhave6digits Sortcodeisinvalidpleaseusexxxxxxonlynodashesorspaces ThatSortCodesortcodedoesnotcorrespondtothatbankbankname Theddihasexpired Thepayerddihasbeencancelled Thepayerddiisnotyetactive ThistransactionhasbeenmarkedUnpaidyoucannotvoidit YoucannotchangeacancelledDDIpleaseenteranewone Zero,negativeorinsufficientamountspecified ThereisnoDDIconfiguredforthatcombinationofPayerpayerrefandAccount accountname ThereisnosuchPayerpayerref Thatcurrencyisnotallowedthroughthataccount!

37

RealEFTDevelopersGuidewithXMLDefinitions

AppendixBResultCodes
Code 1 Reason InstructionCancelled Explanation ThePayerorthePayersBank BranchhascancelledtheDDI ThedeathofthePayer TheaccountofthePayerhasbeen transferredtoanotherbank.If directdebitingistocontinuethe Originatormustobtainanew Instruction ThePayerhasdisputedthe advancenotice TheidentityofthePayerdiffers fromthatknowntotheBank Branchandtheaccounthasnot beentraced TheappropriateDDIhasnotbeen lodgedwiththePayersBank Branch Theamountofthedirectdebit differsfromtheamountspecified intheDDI Thedateofdebitingisinadvance oftheduedatespecifiedinthe DDI Thepresentationisoverdue usually,thismeansthatitismore than7daysaftertheduedate specifiedintheDDI TheidentityoftheOriginator differsfromthatspecifiedinthe DDI Thepayersaccountisclosed ActiontoTake Nofurtherpresentations allowedcontactthe payer Nofurtherpresentations Allowed Obtainanewinstruction from thePayer.Nofurther instructionsallowed ContactthePayer ContactthePayer

2 3

PayerDeceased AccountTransferred

4 5

AdvanceNotice Dispute NoAccount

NoInstruction

ContactthePayer

AmountDiffers

AmountnotYetDue

Presentation Overdue

Originatormayonly submit debitsfortheagreed amount Delayreinputuntilthe due Date Seekpermissionfromthe payertopresentthedebit Late EnsurethePayer completesa validDDI ObtainanewDDIfrom the Payer Nofurtherpresentations allowedcontactthe payer

OriginatorDiffers

AccountClosed

RefertoPayer

ThePayersBankBranchisnotina positiontopaythedirectdebitOR theserviceofagarnisheeorderor arrestmentonthepayersaccount, hisbankruptcy,liquidation,orthe appointmentofareceiverto managehisaffairs

38

RealEFTDevelopersGuidewithXMLDefinitions

Connectwithusonline:

www.facebook.com/realexpayments

www.twitter.com/realexpayments

www.linkedin.com/companies/realex-payments

www.youtube.com/realexpayments

OurOtherWebsites:

OurofficeLocations:
RealexPaymentsIreland(Headquarters) Castlecourt,MonkstownFarm,DunLaoghaire,CoDublin.Ireland t:+353(0)12808559|f:+353(0)12808538| www.realexpayments.com [email protected] RealexPaymentsUnitedKingdom: 1LyricSquare,Hammersmith,LondonW6 0NB,UnitedKingdom. t:+44(0)2031785370|f:+44(0)207691 7264|www.realexpayments.co.uk [email protected]

RealexPaymentsFrance: 27avenuedel'Opra,75001Paris.France. t:+33(0)170385137|f:+33(0)17038 5151 www.realexpayments.com [email protected]

39