Upload
danny-dawson
View
471
Download
12
Embed Size (px)
Citation preview
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.
RealEFT Developer’s Guide with XML Definitions
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.
RealEFT Developer’s Guide with XML Definitions
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.6 13 Hash Value Syntax
3.7 14 Payment Method Set‐up
3.8 14 XML Syntax
3.9 16 Hash Value Syntax
3.10 16 Activate a Mandate
3.11 17 XML Syntax
3.12 18 Hash Value Syntax
4 20 Payment (direct debit – eft) processing
4.1 21 XML Syntax
4.2 23 Hash Value Syntax
5 24 Void a Direct Debit
5.1 24 XML Syntax
5.2 26 Hash Value Syntax
6 27 Mark a Direct Debit as Unpaid
6.1 27 XML Syntax
6.2 28 Hash Value Syntax
7 29 Cancel the Unpaid Mark on a Direct Debit
7.1 29 XML Syntax
7.2 30 Hash Value Syntax
8 31 Re‐Present a Direct Debit
RealEFT Developer’s Guide with XML Definitions
4
8.1 31 XML Syntax
8.2 32 Hash Value 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
RealEFT Developer’s Guide with XML Definitions
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.
RealEFT Developer’s Guide with XML Definitions
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
RealEFT Developer’s Guide with XML Definitions
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
RealEFT Developer’s Guide with XML Definitions
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>
RealEFT Developer’s Guide with XML Definitions
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
RealEFT Developer’s Guide with XML Definitions
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.
RealEFT Developer’s Guide with XML Definitions
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 ▪ XML Syntax ▪ Hash Value Syntax
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>
RealEFT Developer’s Guide with XML Definitions
12
3.5 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), 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.
<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
RealEFT Developer’s Guide with XML Definitions
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>
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.6 Hash Value Syntax
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.)
( 20010403123245.thestore.ORD453‐11.29900.EUR.smithj01 )
RealEFT Developer’s Guide with XML Definitions
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.
(153872918f7f4e81fa7a5a5763d73b32853ca54c.mysecret )
Get the hash of this value. This is the value that you send to Realex Payments.
(8e629d8455b760eff776f6ca6fb0be8b2fe18803)
<sha1hash> 8e629d8455b760eff776f6ca6fb0be8b2fe18803 </sha1hash>
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
For each XML element or field, the table below provides the following information:
RealEFT Developer’s Guide with XML Definitions
15
▪ 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
Element/Field Mandatory Format Length Description <request type="ddi-new" timestamp="20030516180730">
M 0‐9 14 type:auth
The name for this request type is ddi‐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.
<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>
M a‐f 0‐9 40 The SHA1 hash of this message.
</request> M
RealEFT Developer’s Guide with XML Definitions
16
3.9 Hash Value Syntax
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:
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. 933384.72121495)
Get the hash of this string (SHA‐1 shown below).
(45c87c85cc54ba08628d03e3f45b8563b58425aa)
Create a new string by concatenating this string and your shared secret using a period.
(45c87c85cc54ba08628d03e3f45b8563b58425aa.mysecret )
Get the hash of this value. This is the value that you send to Realex Payments.
(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
▪ Hash Value Syntax
RealEFT Developer’s Guide with XML Definitions
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
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), 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
RealEFT Developer’s Guide with XML Definitions
18
Element/Field Mandatory Format Length Description <request type="ddi-edit" timestamp="20030516181127">
M 0‐9 14 type:auth
The name for this request type is ddi‐edit.
<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.
<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>
M a‐f 0‐9 40 The SHA1 hash of this message.
</request> M
3.12 Hash Value Syntax
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:
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. 933384. 72121495)
Get the hash of this string (SHA‐1 shown below).
(45c87c85cc54ba08628d03e3f45b8563b58425aa)
RealEFT Developer’s Guide with XML Definitions
19
Create a new string by concatenating this string and your shared secret using a period.
(45c87c85cc54ba08628d03e3f45b8563b58425aa.mysecret )
Get the hash of this value. This is the value that you send to Realex Payments.
(6df141152a4e53afd1bc32d8e5192854964905f9)
<sha1hash> 6df141152a4e53afd1bc32d8e5192854964905f9 </sha1hash>
RealEFT Developer’s Guide with XML Definitions
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
▪ Hash Value 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>
RealEFT Developer’s Guide with XML Definitions
21
4.1 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), 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
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.
<merchantid>yourclientid</ merchantid>
M a‐z A‐Z 0‐9 .
1‐50 Your client id as assigned by Realex Payments.
<account>eft</account> M a‐z A‐Z 0‐9 – “”*
1‐20 The account through which to process this transaction
<orderid>uniqueid</orderid>
O a‐z A‐Z 0‐9 _ ‐
1‐40 A unique id to identify this transaction.
<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.
RealEFT Developer’s Guide with XML Definitions
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
<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
RealEFT Developer’s Guide with XML Definitions
23
4.2 Hash Value Syntax
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.)
( 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>
RealEFT Developer’s Guide with XML Definitions
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
▪ Hash Value 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
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), 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
RealEFT Developer’s Guide with XML Definitions
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 .
1‐50 Your client id as assigned by Realex Payments.
<account>eft</account> M a‐z A‐Z 0‐9 – “”*
1‐20 The account through which to process this transaction
<orderid>transaction01</orderid>
O a‐z A‐Z 0‐9 _ ‐
1‐40 A unique id to identify this transaction.
<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
<country>country</country>
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
RealEFT Developer’s Guide with XML Definitions
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
Example: 20010427124523.merchantid.order_id.100.GBP.payerref
To construct the eft‐void 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>
RealEFT Developer’s Guide with XML Definitions
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
▪ Hash Value 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:
▪ 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="eft-unpaid" timestamp="20030520152117">
M 0‐9 14
The name for this request type is eft‐unpaid.
<merchantid>yourclientid</ merchantid>
M a‐z A‐Z 0‐9 .
1‐50 Your client id as assigned by Realex Payments.
<account>eft</account> M a‐z A‐Z 0‐9 – “”*
1‐20 The account through which to process this transaction
<orderid>20030501-0023</ orderid>
O a‐z A‐Z 0‐9 _ ‐
1‐40 The order id used in the original transaction.
RealEFT Developer’s Guide with XML Definitions
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.
<comments> O Comments about this transaction.
<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>
6.2 Hash Value Syntax
Format: timestamp.merchant_id.order_id.amount.currency.payerref
Example: 20010427124523.merchantid.order_id.100.GBP.payerref
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>
RealEFT Developer’s Guide with XML Definitions
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 ▪ XML Syntax ▪ Hash Value Syntax
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 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="eft-cancel-unpaid" timestamp="20030520152031">
M 0‐9 14
The name for this request type is eft‐unpaid.
<merchantid>yourclientid</ merchantid>
M a‐z A‐Z 0‐9 . 1‐50 Your client id as assigned by Realex Payments.
<account>eft</account> M a‐z A‐Z 0‐9 – “”*
1‐20 The account through which to process this transaction
<orderid>20030501-0023</ orderid>
O a‐z A‐Z 0‐9 _ ‐
1‐40 The order id used in the original transaction.
<reasoncode>0</reasoncode> M a‐z A‐Z 0‐9 “” :
1‐50 The reason the transaction was returned. These codes are outlines
RealEFT Developer’s Guide with XML Definitions
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>
M a‐f 0‐9 40 The SHA1 hash of the request. See below for details.
<comments> O Comments about this transaction.
<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>
7.2 Hash Value Syntax
Format: timestamp.merchant_id.order_id.amount.currency.payerref
Example: 20010427124523.merchantid.order_id.100.GBP.payerref
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>
RealEFT Developer’s Guide with XML Definitions
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 ▪ XML Syntax ▪ Hash Value Syntax
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 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="eft-represent" timestamp="20030520152031">
M 0‐9 14
The name for this request type is eft‐represent.
<merchantid>yourclientid</ merchantid>
M a‐z A‐Z 0‐9 .
1‐50 Your client id as assigned by Realex Payments.
<account>eft</account> M a‐z A‐Z 0‐9 – “”*
1‐20 The account through which to process this transaction
<orderid>20030501-0023</ orderid>
O a‐z A‐Z 0‐9 _ ‐
1‐40 The order id used in the original transaction.
<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
RealEFT Developer’s Guide with XML Definitions
32
transaction. <sha1hash>00af6e23b3fadc…da7 20b5fa8644281d</sha1hash>
M a‐f 0‐9 40 The SHA1 hash of the request. See below for details.
<comments> O Comments about this transaction.
<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
</comments> O </request>
8.2 Hash Value Syntax
Format: timestamp.merchant_id.order_id.amount.currency.payerref
Example: 20010427124523.merchantid.order_id.100.GBP.payerref
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>
RealEFT Developer’s Guide with XML Definitions
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.
RealEFT Developer’s Guide with XML Definitions
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
RealEFT Developer’s Guide with XML Definitions
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).
RealEFT Developer’s Guide with XML Definitions
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 _ ‐
RealEFT Developer’s Guide with XML Definitions
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!
RealEFT Developer’s Guide with XML Definitions
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
RealEFT Developer’s Guide with XML Definitions
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