Realauth Developer s Guide Version 3.0.1

(1)

(2)

Introduction to Realex Payments

Thank you for your interest in our service. Realex Payments build and manage payment exchanges for businesses, merchants and banks. We provide a range of real time services in the area of card authorisation, fraud scoring, electronic funds transfer, foreign exchange, reporting and reconciliation tools and payer authentication.

Certified and approved by many leading financial institutions, these services are designed to eliminate overhead for banks and merchants selling in call/contact centres or via the internet. We may be contacted by any of the following methods:

Address Castlecourt, Monkstown Farm, Monkstown, Co

Dublin, Ireland

Telephone + 353 (0)1 280 8559

Fax + 353 (0)1 280 8538

Sales email [email protected]

Support email [email protected]

Web Site www.realexpayments.com

Please note that this document is regarded as confidential and it is for customer use only. It has been supplied under the conditions of your payment-processing contract.

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

(4)

1 Realex Services

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

We provide the following:

♦ Real time credit and debit card authorisation services. ♦ Real time fraud scoring and pattern checking services. ♦ A direct debit and recurring credit card payment service.

♦ A link to third party providers who offer dynamic currency conversion services. ♦ Payer authentication services for merchants and banks.

♦ Multi channel reporting and management tools. ♦ White labelled and customised payment exchanges.

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

1.1 Realauth Scenarios

The Realauth service works under two different scenarios.

The redirect method is suitable for merchants that do not have their own secure server. Using this method, the customer will be redirected to Realex’ secure server to enter their credit card details.

Redirect is covered in section 2.

The remote method affords the merchant greater control of the transaction process but requires that they maintain their own secure server. Using this method, the customers’ card details will be taken by the merchant and passed to Realex by XML messages.

Remote is covered in section 3.

Your solution must integrate with our payment service at two levels – firstly, you must submit correctly formed requests for authorisations and secondly, you must then accept the

response that is returned by the Realex application.

To determine which version of Realauth you should use, consult the following feature list and decide which one is the right choice for your situation:

(5)

Realauth

redirect – Merchant does not need a secure server.

– Can be hosted anywhere, and on any platform as long as CGI scripts are enabled.

– The merchant does not collect the card details, and does not have access to them.

– The customer is redirected to the Realauth application on a secure Realex Payments server by a script on the merchant’s website.

– Realex Payments host a secure, merchant-branded web page. We collect the card details and process the payment. The customer and the results of the transaction are sent back to the merchant via another script on the merchant’s web site (Realex can provide sample scripts to get you started).

Realauth

remote – Merchant needs a secure server or can integrate the service into a

desktop application.

– Can be hosted anywhere, and on any platform as long as CGI is enabled. – The card details are collected by the merchant and passed to Realex

Payments as XML messages. Realex Payments respond with an XML message containing the results of the transaction in a matter of seconds. Realex can provide sample scripts to get you started.

– The merchant need not store card details, but they are available. – The merchant controls full process, screen flow. Customer may never

know Realex were involved in the process. Important Note:

In certain circumstances the acquiring bank may need to approve your use of the Realauth remote option and it is entirely the merchants/developers responsibility to ensure that the acquiring bank has agreed and authorised the merchant in this regard.

1.1.1 Sub-Accounts

In order to facilitate the use of multiple web-sites and bank accounts, merchants can set up a number of sub-accounts under their main Realex account. Each sub-account can use a

different set of URLs/IP addresses and can channel the funds to a different bank account. The default sub-account will be ‘internet’ for all merchants. To have additional sub-accounts

(6)

2 Realauth Redirect

Merchants that do not have their own secure server can use Realauth redirect. Rather than entering their credit card number on your (non-secure) website, the customer is redirected to the Realex Payments secure server. Here they are presented with a payment page that you can customise to maintain the appearance of your website. After entering their card details customers can be returned to your site to continue browsing. Redirect payment pages are customised using ‘templates’, these are described in the following section.

2.1 Redirect Example

The process involved for a redirect transaction is shown in the following example.

Step 1.

Once the full amount is known the customer can be presented with a confirmation page. This page is hosted on the merchants’ server. If the customer chooses to continue they will be redirected to Realex’ secure server.

(7)

Step 2.

On Realex’ secure server, the customer is presented with the payment form. This page uses a template to maintain the

appearance of the merchants’ own web-site.

Step 3.

After entering their card details, the customer clicks Pay Now and the card details are sent to the bank for authorisation. When the reply is received a script on the merchant site is contacted with the result (approved/declined etc). The HTML output of the merchants’ response script is then taken and displayed on Realex’ secure server using the template.

Please note:

Requests should be sent to Realex Payments only at the end of the shopping experience, once the total amount of the payment is known. No information about the contents of the order is required for Realex to process the transaction, however you can send any information about the order to Realex as hidden fields – these will be ignored and sent back to your response script once the transaction has been processed. Rather than maintaining a database of orders you may wish to simply send yourself an email with this information once the order is

(8)

It is worth noting that the Internet is not 100% reliable and communication errors may occur so it is possible that the information will not make it back to your response script. We

recommend that an email with the order details and order ID be sent before the transaction is sent to the Realex application and another email with the result sent afterwards. In this way, details of an order that someone has actually been charged for should not be lost.

2.2 Templates

In order for the payment form to maintain the appearance of your website you will need to have a template page and (optionally) some images/style sheets etc. uploaded to the Realex Payments servers. This template should be sent to Realex support via e-mail

([email protected]) or uploaded through the online resource centre (http://resource.realexpayments.com/).

The basic structure of a template is shown below. Note the HTML comment that indicates where the payment form should be placed; this tag must be present in the template page.

Enter your credit card details. </title>

</head> <body> more html…

 more html…

</body> </html>

The template should resemble the rest of the shopping experience so that the customer does not immediately realise that they have been redirected but, as a secure encrypted connection will be used, there should be as few images as possible. A typical template page consists of: a ‘header’ image, a plaintext message for the customer and the required “” tag. Simply using the general colour scheme of the other pages in your shopping cart is quite effective.

(9)

Below are the full requirements for the template page:

1. Template pages must contain the payment form tag:  2. All images/CSS used in the template must be referred locally on our server. There

should be no absolute URLs to external images/CSS. The <base… /> html tag is also disallowed for this reason. This means that you will need to send the image files to us along with the template page.

3. There can be no scripting of any kind in the template for security reasons. It should contain only basic HTML.

4. The name of the file must be: template.htm

5. All necessary files should be placed in a folder with the same name as the sub-account

for which the template is intended (the default sub-account is always ‘internet’). This folder should then be placed in a zip file of the same name and the complete archive sent to the following e-mail address: [email protected]

2.3 Redirect Integration

To link your shopping cart to the Realex Realauth application you must insert certain hidden fields into a form that redirects to the Realauth application over a secure link.

The minimal implementation is shown below.

<input type="hidden" name="MERCHANT_ID" value="Realex Payments merchant-id"> <input type="hidden" name="ORDER_ID" value="unique order-id">

<input type="hidden" name="ACCOUNT" value="sub account name"> <input type="hidden" name="AMOUNT" value="amount">

<input type="hidden" name="CURRENCY" value="currency code"> <input type="hidden" name="TIMESTAMP" value="yyyymmddhhmmss"> <input type="hidden" name="MD5HASH" value="32 character string"> <input type="hidden" name="AUTO_SETTLE_FLAG" value="1 or 0"> <input type="submit" value="Click here to Purchase">

(10)

Some form of server side programming is required to create the MD5HASH (or SHA1HASH). Because of this, all merchants will be required to perform some script configuration on their side.

Realex can supply working sample code in Perl, Java, PHP, ASP and server side JavaScript that will make the process as painless as possible.

2.4 Redirect Request Field Definitions

The following fields are accepted by Realex Payments. Anything else will be returned back to your response script (if any) along with the Realex responses.

R Required for this request type O Optional

Ro _{Required depending on another optional field}

For each field the length and format of the field is given in the following fashion: A Alpha/Character (A-Z a-z - _)

N Numeric (0-9)

S Special Characters (+ @ . ,) V Variable length

MERCHANT_ID AN50V R Supplied by Realex – note this is not the merchant number supplied by

your bank.

ACCOUNT AN30V O The sub-account to use for this transaction. If not present, the

default sub-account, ‘internet’, will be used.

ORDER_ID AN50V R A unique alphanumeric id that’s used to identify the

transaction. This can be up to 40 characters long. No spaces are allowed

AMOUNT N10V R Total amount to authorise in the lowest unit of the currency –

i.e. 100 euro would be entered as 10000. If there is no decimal in the currency then (e.g. JPY Yen) then contact Realex

Payments. No decimal points are allowed.

CURRENCY A3 R A three-letter code as per currency table in Appendix A.

TIMESTAMP N14 R Date and time of the transaction. Entered in the following

format: yyyymmddhhmmss

MD5HASH AN32 R A digital signature generated using the MD5 algorithm. You

have the option of using the MD5 hash or the SHA-1 hash (below). Realex prefer you use the SHA-1 hash as it is more secure. See section below on Digital Signatures.

SHA1HASH AN40 R A digital signature generated using the SHA-1 algorithm.

Realex prefer that you use a SHA-1 signature rather than an MD5. The MD5 option has been retained for compatibility with older systems. See section below on Digital Signatures.

(11)

AUTO_SETTLE_FLAG N1 R Used to signify whether or not you wish the transaction to be captured in the next batch or not. If set to “1” and assuming the transaction is authorised then it will automatically be settled in the next batch. If set to “0” then the merchant must use the realcontrol application to manually settle the

transaction. This option can be used if a merchant wishes to delay the payment until after the goods have been shipped. Transactions can be settled for up to 115% of the original amount.

COMMENT1 AN255V O A freeform comment to describe the transaction. Up to 255

characters

COMMENT2 AN255V O A freeform comment to describe the transaction. Up to 255

characters

RETURN_TSS N1 O Used to signify whether or not you want a Transaction

Suitability Score for this transaction. Can be “0” for no and “1” for yes. To maximise the usefulness of the realscore you should also supply the next 6 fields. See below for more on realscore.

SHIPPING_CODE 30V O The postcode or ZIP of the shipping address. This can only

have letters and digits. (ie no – or /)

SHIPPING_CO 30V O The country of the shipping address. This can only have letters

and digits. (ie no – or /)

BILLING_CODE 30V O The postcode or ZIP of the billing address. This can only have

letters and digits. (ie no – or /)

BILLING_CO 30V O The country of the billing address. This field can only have

letters and digits. . (ie no – or /)

CUST_NUM ANS50V O The customer number of the customer.

VAR_REF ANS50V O A variable reference also associated with this customer.

PROD_ID ANS50V O A product id associated with this product.

ANYTHING ELSE ANS255V O Anything else you send to Realex Payments will be returned in

the response (whatever other information you collected from the customer such as product or address/telephone numbers etc….)

All of these field values (except for the MERCHANT_ID which will be provided by Realex) are user definable. Merchants will need to contact Realex in order to set up new sub-accounts.

(12)

2.5 Redirect Response Field Definitions

Response data is sent back to your response script for each transaction. After the customer enters their credit card details on the Realex-hosted page, our application calls your response script with the response details. You can use this response to update your own database and send emails to your customers based on the result of the transaction.

In order to receive this data you must provide Realex Payments with the URL of your response script. The response URL is to be emailed to [email protected] or entered through the online resource centre. This application must only return text as output – if image tags are included there will be a popup warning about mixed secure/insecure content on the page. The template that was used for the credit card entry table will be used again for this page. You should include a link that continues the customers shopping experience. Again, we can provide working sample code that will make this process easier. In the case of an error whereby the Realauth application is unable to contact your response script, you can set a static

success/failure message. This can be changed in the administration section of Real Control. The response fields are as follows:

MERCHANT_ID This is the merchant id that Realex Payments assign to you. ACCOUNT The sub-account used in the transaction.

ORDER_ID The unique order id that you sent to us.

AUTHCODE Will contain a valid authcode if the transaction was successful. Will be empty otherwise.

RESULT The outcome of the transaction. Will contain “00” if the transaction was a success or another value (depending on the error) if not. See the result codes table in Appendix A.

MESSAGE Will contain a text message that describes the result code above. CVNRESULT The result of the Card Verification check (if enabled):

M: CVV Matched. N: CVV Not Matched.

I: CVV Not checked due to circumstances. U: CVV Not checked – issuer not certified. P: CVV Not Processed.

PASREF A unique reference that Realex Payments assign to your transaction. BATCHID This is the Realex Payments batch that this transaction will be in.

(This is equal to “-1” if the transaction was sent in with the autosettle flag off. After you settle it (either manually or programmatically) the response to that transaction will contain the batch id.)

MD5HASH An MD5 digital signature created using the above fields and your shared secret. Needs to be sent in lowercase.

SHA1HASH A SHA-1 digital signature created using the above fields and your shared secret. Needs to be sent in lowercase.

TSS The Transaction Suitability Score for the transaction.

TSS_idnum The realscore is comprised of various distinct tests. Using the

realcontrol application you can request that Realex Payments return certain individual scores to you. These are identified by numbers – thus TSS_1032 would be the result of the check with id 1032. You

(13)

can then use these specific checks in conjunction with realscore score to ascertain whether of not you wish to continue with the settlement.

ANYTHING ELSE Anything else you sent to us in the request will be returned to you.

All of these field values (except for the MERCHANT_ID which will be provided by Realex) are user definable. Merchants will need to contact Realex in order to set up new sub-accounts.

2.6 Digital Signature for Redirect

To ensure that the request comes from you we require that you send us a hash of certain elements (specifically the TIMESTAMP, MERCHANT_ID, ORDER_ID, AMOUNT, and CURRENCY) using a shared secret. This can be an MD5 hash or preferably a SHA-1 hash. If required we can also provide 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's no way to decrypt a secure hash. Given the larger key size, we prefer that you use a SHA-1 hash, but we have retained the MD5 for compatibility with older systems.

Here is a sample request:

To construct the hash follow this procedure:

Form a string by concatenating the above fields with a period (“.”) in the following order ( TIMESTAMP.MERCHANT_ID.ORDER_ID.AMOUNT.CURRENCY )

Like so:

( 20010403123245.thestore.ORD453-11.29900.EUR ) Get the hash of this string (SHA-1 shown below).

(14)

Create a new string by concatenating this string and your shared secret using a period. ( 91eedbf675e6a5af8802b193e8ea94309cbe61ea.mysecret )

Get the hash of this value. This is the value that you send to Realex Payments. ( 6f40e8a9a9976497f78dab811a9147d5f94c1192 )

<input type="hidden" name="SHA1HASH"

value="6f40e8a9a9976497f78dab811a9147d5f94c1192">

When Realex receive the request, we perform the same procedure on the five 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 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 Payments. (This will be a hash of the TIMESTAMP, MERCHANT_ID, ORDER_ID, RESULT, MESSAGE, PASREF and AUTHCODE with your secret key (see below for more on the Realex Payments response fields). If you sent us an MD5 hash you will receive an MD5 hash in the response and similarly for a SHA-1 hash).

Please note that both the MD5 and SHA1 hash need to be sent in lowercase. The response hash is constructed as follows:

Form a string by concatenating the above fields with a period (“.”)

( 20010403123245.thestore.ORD453-11.00.Successful.3737468273643.79347) Get the hash of this string (SHA-1 shown below).

(a686f8a684bf28dfe6cd4d18f41ef0ea50bf6c09)

Create a new string by concatenating this string and your shared secret using a period. (a686f8a684bf28dfe6cd4d18f41ef0ea50bf6c09.mysecret)

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

(15)

3 Realauth Remote

Merchants should use Realauth remote if they have a secure server or if their site is hosted internally (such as an intranet application for a call centre – a secure server isn’t necessary in that case as the card numbers will never travel outside of the internal network).

Remote can also be used if you are developing an application in Visual Basic or Java etc. (i.e. not a web application but a desktop application).

Realex Payments can supply working sample code in Perl, Java, ASP, VB, PHP, .NET and server side JavaScript.

Important Note:

In certain circumstances the acquiring bank may need to approve your use of the Realauth remote option and it is entirely the merchants/developers responsibility to ensure that the acquiring bank has agreed and authorised the merchant in this regard.

3.1 Remote Example

Realauth remote is ideal for any application that needs real time authorisation of credit cards. Information is sent between the merchant and Realex Payments in the form of XML messages. This service can be incorporated into any application that is capable of generating XML

messages.

Step 1.

Once the full amount is known, the customer can be asked to enter their card details. These details are then sent to Realex as XML

messages using a secure

connection. A reply is then sent as an XML message back from Realex that contains the result of the transaction (approved/declined etc).

(16)

Step 2.

The merchants’ application receives the response XML and extracts the information. It then displays the appropriate messages for the customer. One of the main

advantages of the remote version is that the merchant can control the entire shopping experience.

3.2 Application Based Checking

It is highly advisable to build in pre-authorisation checking for all data fields. This will eliminate many problems early on and rapidly improve response times. If any field contains an error, the transaction will fail. All mandatory fields must be included correctly and optional fields must contain valid data if included.

Validation information can be found in Appendix C of this document. The following are some checks that should be put in place:

• Card expiry date should be checked. The date itself should be valid and formatted correctly.

• The card length should be 12,13,14,15,16,18 or 19 digits depending on the card type, no alpha characters should be included.

(12 ≤ num_digits ≤ 19 will do).

• The card number should pass the Luhn check (see Appendix A) to ensure that it is a valid card number.

• There should be at least two words in the cardholder's name (this is recommended but will not cause transactions to fail) and it must contain no unusual characters.

• If CVN checking is to be enforced the corresponding value for the ‘presind’ field will need to be set. The possible values are listed in the XML definitions guide.

• The CVN itself will need to be sent in correctly. It should be 3 or 4 digits depending on the card type.

• Illegal characters cannot be present in any field. Each field should be checked to ensure that this is not the case as illegal characters will cause the transaction to fail. The allowed characters for all fields are detailed in the XML definitions guide and in Appendix C.

(17)

3.3 Remote Integration

Full details of the XML messages for each request type can be found in the Realauth XML definitions guide, which is available from the online resource centre or by e-mailing [email protected].

You will need to consult this guide in order to successfully complete a remote integration. Realex Payments can supply sample code to aide with integration, however this is sample code only and will need to be modified to suit individual merchants’ needs. The sample code will provide guidance on how to carry out the steps required for a remote transaction to succeed.

These steps are:

• Create the XML message for the request.

• Connect to Realauth (https://epage.payandshop.com/epage-remote.cgi). • Send the message.

• Wait for Realex to reply with XML.

• Parse the reply and provide access to the information.

(18)

3.3.1 Sample Java Code

Java example

public Request request;

public Response response = new Response(); request = new Request("auth");

request.setSecret("mysecret"); request.set("merchantid", "thestore"); request.set("orderid", "ORD3784-342"); request.set("currency", "EUR"); request.set("amount", "2999"); request.set("cardnumber", "5105105105105100"); request.set("cardexpdate", "0404"); request.set("cardtype", "MC"); request.set("cardholdername", "John Doe"); if (request.isValid()) { response = request.send(); } else { System.out.println("Error in request."); } System.out.println("Result: " + response.get("result")); System.out.println("Message: " + response.get("message")); System.out.println("Authcode: " + response.get("authcode")); System.out.println("Suitability Score: " + response.get("tss"));

(19)

3.3.2 Sample ASP Code

ASP example

Set request = New clsPayandshop

request.createRequest "auth" request.setSecret “mysecret”

request.setField "merchantid", “thestore” request.setField "orderid", “ORD238-23” request.setField "currency", “EUR” request.setField "amount", “29599”

request.setField "cardnumber", “4111111111111111” request.setField "cardexpdate", “0305”

request.setField "cardname", “Luke Kelly” request.setField "cardtype", “VISA” equest.sendRequest RespResult = request.getField("result") RespAuthCode = request.getField("authcode") RespMessage = request.getField("message") RespTSSResult = request.getField("tssresult") RespPASRef = request.getField("pasref")

(20)

3.3.3 Sample Perl Code

Perl example

use payandshop::Request; my $cardnumber = "4111111111111111"; my $orderid = time; my $request; my $response;

$request = new payandshop::Request(type => "auth"); $request->setSecret("secret"); $request->set("merchantid", "thestore"); $request->set("orderid", $orderid); $request->set("currency", "IEP"); $request->set("amount", "4"); $request->set("cardnumber", "$cardnumber"); $request->set("cardexpdate", "0404"); $request->set("cardtype", "VISA");

$request->set("cardholdername", "John Doe"); $request->set("autosettle", "1"); if ($request->isValid()) { $response = $request->send(); my $strResult = $response->get("result"); my $strMessage= $response->get("message"); } else {

print "Invalid request: ".$request->getError(); }

(21)

3.4 Remote Request Message

Although the sample code available provides a simple interface to the system, more complex implementations will require some knowledge of how the system works. Again, the Realauth XML definitions guide should be consulted for full details on the messages required.

The following indicators are used to show whether or not an element is required or optional. R Required for this request type

O Optional

R _{Required depending on another optional field}

For each element of the XML the length and format of the field is given in the following fashion:

A Alpha/Character (A-Za-z “ ” - _) N Numeric (0-9)

S Special Characters (@ / ~ etc..) V Variable length

For example:

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

Below is a sample of an auth request followed by a line-by-line analysis. The auth request is the primary request used with realauth.

<request timestamp="20010427124523" type="auth"> <merchantid>YourMerchantID</merchantid>

<account>account to use</account> <orderid>order id</orderid>

(22)

</comments> <tssinfo>

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

<varref>variable reference</varref>

<code>zip/postal code</code> <country>country</country> </address>

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

</tssinfo> <narrative>

<establishmentname>Merchant Name</establishmentname> <establishmentcity>CITY</establishmentcity>

<chargedescription>DESCRIPTION</chargedescription> </narrative>

<sha1hash>4dc4f20acc….30314758a1bc</sha1hash> <md5hash>67dcc….787307</md5hash> </request> <request timestamp="20010427124523" type="auth"> R N14/ AN50V

Top-level element. Must have timestamp and type attributes. If the timestamp is more than a day (86400 seconds) away from the server time then the request is rejected.

<merchantid> YourMerchantID

</merchantid> R AN50V

This is your realex payments assigned merchant id

<account>account to use</account> O AN30V

This is the realex payments sub-account to use. If you omit this element then we will use your default account.

<orderid>order id</orderid> R AN50V

The unique order id of this transaction. Must be unique across all of your accounts.

<amount currency="EUR">2000</amount> R A3/ N10V

The currency and amount of the transaction. Appendix B of the realauth developer’s guide specifies the currency codes. The amount should be in the smallest unit of the required

(23)

currency (i.e. 2000 = £20, $20 or €20)

<card> R There must be a card element

in auth requests <number>490303400005718902</number

> R N19V

The card number.

<expdate>0403</expdate> R N4 The card expiry date. The format is mmyy

<chname>John Doe</chname> R AN100 V

The card holder’s name.

<type>MC</type> R A20V

The card type. The legal values are: VISA, MC, AMEX,

LASER, SWITCH, DINERS <issueno></issueno> R N2V

The issue number of the card in the case of a Switch card. Only required if the card type is SWITCH

<cvn> O

The card verification details element. If you use this then the next two elements are required.

<number>453</number> R N4V

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)

<presind>1</presind> R N1

This is the presence indicator. It can take 4 values:

1: cvn present 2: cvn illegible 3: cvn not on card 4: cvn not requested </cvn> </card> <autosettle flag="1" /> R N1

The auto-settle indicator. If “1” then the transaction will be sent to the bank for settlement tonight. If set to “0” then the transaction will sit in the realex payment’s database until someone manually submits it for settlement

<comments> O

You can associate up to 2 comments with any transaction for your own purposes.

<comment id="1">a comment</comment> O AN255 V

Free-text comment <comment id="2">another AN255 Free-text comment

(24)

</comments>

<tssinfo> O

As part of the realex payment’s service we offer a realscore. This is a real time transaction screening and data checking system to assist the merchant with the identification of potentially high-risk transactions.

<custnum>customer number</custnum> O ANS50 V

The number you assign to the customer. This can allow checking of previous

transactions by this customer. <prodid>product id</prodid> O ANS50

V

The product code you assign to the product.

<varref>variable reference</varref> O ANS50 V

Any reference you also would like to assign to the customer. This can allow checking, using realscore, of previous

transactions by this customer. <custipaddress>www.xxx.yyy.zzz</custipad

dress> O AN14V

The IP address of the customer

<address type="billing"> O The billing address of the customer.

<code>zip/postal code</code> O AN30V

The ZIP/Postal code of the billing address. This can be checked (in conjunction with the country) against a table of high-risk area codes.

<country>country</country> O AN2V

The country of the billing address. This can be checked against a table of high-risk countries.

</address>

<address type="shipping"> O The shipping address of the customer.

<code>zip/postal code</code> O AN30V

The ZIP/Postal code of the shipping address. This can be checked (in conjunction with the country) against a table of high-risk area codes.

<narrative> O The Narrative

R AN50V

The Merchant Name

<establishmentcity>CITY</establishmentcity> R AN30V

The Merchant City

<establishmentstate>CC</establishmentstate R A2

The Country Code of the Merchant

(25)

>

<chargedescription>DESCRIPTION</charged escription>

R AN15V

The Charge Description

</narrative>

<country>country</country> O AN2V

The country of the shipping address. This can be checked against a table of high-risk countries.

</address> </tssinfo>

<sha1hash>4dc4f20acc….30314758a1bc</

sha1hash> R AN40

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

<md5hash>67dcc….787307</md5hash> R AN32

The MD5 hash of certain elements of the request. The details of this are to be found in the realauth developer’s guide. </request>

3.5 Remote Response Message

The full version of the response is shown below, followed by the short version and a line-by-line description.

Response format – long version:

<response timestamp="20010427043422"> <merchantid>YourMerchantID</merchantid> <account>account to use</account>

<orderid>order id from request</orderid> <authcode>authcode received</authcode> <result>00</result>

<message>message returned from system</message> <pasref> realex payments reference</pasref>

<batchid>batch id for this transaction (if any)</batchid> <cardissuer>

<bank>Issuing Bank Name</bank>

<country>Issuing Bank Country</country>

(26)

</response>

Response format – short version:

<message>message returned from system</message> </response>

(27)

<response timestamp="20010427043422"> R N14 Top-level element. Will have timestamp attribute.

<merchantid> YourMerchantID merchantid> R AN50V This is the realex payments assigned merchant id used. <account>account used</account> R AN30V This is the realex payments

sub-account used. <orderid>order id used</orderid> R AN50V

The order id of the request. Used when referencing this transaction in refund and void requests.

<authcode>authcode received</authcode> R AN10V

If successful there will be an authcode returned from the bank. Used when referencing this transaction in refund and void requests.

<result>00</result> R N3V

The authcode of the original

transaction (this was included in the response).

<message>message returned from

system</message> R

AN100 V

The text of the response. Will contain the authcode if successful or the error message if not.

<pasref> realex payments

reference</pasref> R AN40V

The realex payments reference for the transaction. Used when

referencing this transaction in refund and void requests.

<cvnresult>M</cvnresult> R A1

The result of the Card Verification check:

M: CVV Matched N: CVV Not Matched I: CVV Not checked due to circumstances

U: CVV Not checked – issuer not certified

P: CVV Not Processed

<batchid>batch id</batchid> R AN10V

The batch id of the transaction. Returned in the case of auth and refund requests. This can be used to assist with the reconciliation of your batches.

<cardissuer> R The Details of the cardholder’s bank (if available)

<bank>Issuing Bank Name</bank> R AN100

V

The Bank Name (e.g. First Data Bank)

<country>Issuing Bank Country</country> R AN40V The Bank Country in English (e.g. UNITED STATES)

<countrycode>Issuing Bank Co

Code</countrycode> R AN2

The country code of the issuing bank (e.g. US)

(28)

LAT (Latin America), US (United States), EUR (Europe), CAN (Canada), A/P (Asia/Pacific) </cardissuer> R

<tss> O The results of realscore

<result>67</result> R N3V

The weighted total score of realscore. You may adjust the weights in the realcontrol application.

<check id="xxxx">9</check> R N4/ N1

The result of realscore check number xxxx. You can choose which checks to return using the

realcontrol application. </tss>

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

The SHA-1 hash of certain elements of the response. The details of this are to be found in the realauth developer’s guide.

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

The MD5 hash of certain elements of the response. The details of this are to be found in the realauth developer’s guide.

</response>

3.6 Digital Signatures for Remote

To ensure authentication (that the request comes from you) we require that you send us a hash of certain elements (specifically the timestamp, merchant id, order id, amount, currency and card number) using a shared secret. This can be a MD5 hash or preferably a SHA-1 hash. If required we can also provide 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's no way to decrypt a secure hash. Given the larger key size, we prefer that you use a SHA-1 hash, but we have retained the MD5 for compatibility with older systems.

Here’s a fragment of a sample XML message:

<request timestamp="20010403123245" type="auth"> <merchantid> thestore </merchantid>

<account> theaccount </account> <orderid> ORD453-11 </orderid>

(29)

<card>

<chname> John Smith </chname> <type> VISA </type>

</card>

To construct the hash follow this procedure:

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

When Realex Payments receive the request, we perform the same procedure on the six 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 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, PASREF and AUTHCODE. This will be combined with your shared secret in the same way as the request hash.

If you sent us an MD5 hash you will receive an MD5 hash in the response and similarly for a SHA-1 hash).

The response hash is constructed as follows:

( 20010403123245.thestore.ORD453-11.00.Successful.3737468273643.79347) Get the hash of this string (SHA-1 shown below).

(30)

Create a new string by concatenating this string and your shared secret using a period. (a686f8a684bf28dfe6cd4d18f41ef0ea50bf6c09.mysecret)

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

4 Steps Required To Go Live

All accounts remain in test mode until it is specifically requested to switch the account live. This request must come from the billing or commercial contact for the account.

Before live cards can be processed you will also need to provide Realex with a bank merchant number by email to [email protected]. This number references an Internet Merchant Service Agreement (MSA), which you must set up with your acquiring bank. For information on how to obtain a MSA, please visit:

http://www.realexpayments.com/en/where_to_get_a_merchant_services_agreement.aspx Once you have requested the system to go live and have provided your merchant number, please allow 24 hours for the account to be fully enabled. When the account has been fully set live the merchant will be advised of this by Realex Payments support. At this point the

merchant should attempt a number of live transactions to ensure that the integration has been completed successfully.

The main steps involved in setting an account live are summarised below: 1. Secure merchant service agreement with acquiring bank.

2. Provide merchant numbers to Realex via email. 3. Integrate website/application with Realex service.

4. Conduct testing using approved test card numbers to confirm successful integration. 5. Contact Realex payments and request account be set live.

6. Receive confirmation that account is live from Realex support. 7. Process live transactions.

If further testing is required after an account has been set live it is still possible to send transactions to the test environment. This can be done by appending ‘test’ to the name of the sub-account specified in the ACCOUNT field. For example, where the sub-account is called ‘internet’ the test transaction would use ‘internettest’.

(31)

Appendix A – Sample Code

Luhn check

Below is code in JavaScript that carries out Luhn checking on all card numbers. Code in other languages is widely available on the internet.

var number = "4444333322221111"; var i, sum, weight;

sum=0;

for (i = 0; i < number.length - 1; i++) {

weight = number.substr(number.length - (i + 2), 1) * (2 - (i % 2)); sum += ((weight < 10) ? weight : (weight - 9));

}

if (parseInt(number.substr(number.length-1)) == ((10 - sum % 10) % 10)) { return true;

} else {

alert("Card Number Fails LUHN Test"); return false;

}

In brief, the Luhn check is used to validate numbers such as credit cards, account numbers, and social security numbers. It works like this:

1. Double the value of every second digit beginning with the second-last right-hand digit. 2. Add the individual digits comprising the products obtained in step 1 to each of the other

digits in the original number.

3. Subtract the total obtained in step 2 from the next higher number ending in 0.

4. This number should be the same as the last digit (the check digit). If the total obtained in step 2 is a number ending in zero (30, 40 etc.), the check digit is 0.

For example: credit card number 3648455485235855

3 6 4 8 4 5 5 4 8 5 2 3 5 8 5 5

x2 ↓ x2 ↓ x2 ↓ x2 ↓ x2 ↓ x2 ↓ x2 ↓ x2

6 6 8 8 8 5 10 4 16 5 4 3 10 8 10 6+6+8+8+8+5+1+0+4+1+6+5+4+3+1+0+8+1+0 = 75 80 – 75 = 5 (correct)

(32)

Appendix B – Codes

Currency Codes

EUR Euro

GBP Pound Sterling

USD US Dollar

SEK Swedish Krona

CHF Swiss Franc

HKD Hong Kong Dollar

JPY Japanese Yen

(Further codes available on request.)

Card Types

VISA Visa/Delta

MC Mastercard

SWITCH Switch/Solo

AMEX American Express

(33)

Response Codes

The Table below details the current set of result codes returned by the Realex Payments system. These message are subject to change without notice. Best Practise is to treat the codes in the following manner:

00 Successful 101 Declined by Bank

102 Referral by Bank (treat as decline in automated system such as internet) 103 Card reported lost or stolen

2xx Error with bank systems

3xx Error with Realex Payments systems

5xx Incorrect XML message formation or content 666 Client deactivated. RESULT MESSAGE 00 AUTH CODE: nnnnnn 101 CANCELLED CARD 101 CARD EXPIRED 101 DECLINED 101 INVALID AMOUNT 101 INVALID CARD NO. 101 INVALID CURRENCY 101 INVALID EXP DATE 101 INVALID MERCHANT 101 INVALID TRANS 101 NOT AUTHORISED 101 RETAILER UNKNOWN 101 UNABLE TO AUTH 102 CALL AMEX

102 CALL AUTH CENTRE 102 REFERRAL

102 REFERRAL B 103 REFERRAL A 103 PICK UP CARD 103 RETAIN CARD

106 Auth Failed - Contact Auth Centre (Generally Switch Card issue number is incorrect) 107 Fails Realscore Fraud Checks

108 Using test system. Please use pre-approved test cards ONLY 109 Comms Error – scheduled bank maintenance

200 Unspecified bank error

202 Network error: cannot connect to EPoS 205 Comms Error – bank connection error. 301 Cannot connect to Database

(34)

303 There is no default merchant account set. Please contact realex payments if you continue to experience this problem.

303 Error in configuration - merchant has more than one config for this currency/card combination

303 Somehow more than one transaction matches these parameters. 304 Can't find transaction details in database

305 Realex Payments are currently updating the system. We apologise for the inconvenience. 501 This transaction has already been processed.

502 Compulsory field not present - cannot continue. Please check the Developer Documentation for compulsory fields

502 Type [type] not implemented. Please check the Developer Documentation for allowed types 503 Request type not recognised

503 Request type [type] not allowed for this merchant

504 There is no such merchant id. Please contact realex payments if you continue to experience this problem.

505 md5hash incorrect - check your code and the Developers Documentation 505 sha1hash incorrect - check your code and the Developers Documentation 505 You are not allowed to access this service from there!

505 The refund password you entered was incorrect.

506 There is no such merchant account. Please contact realex payments if you continue to experience this problem.

506 No xml in request 506 Too much data 506 Bad xml formation

507 currency/card combination not allowed 508 Invalid data in merchantid field 508 Invalid data in account field

508 Invalid characters in order id - please use only A-Z a-z 0-9 _ - 508 Please only numbers in amount - see developers guide 508 Leading zeros or or other error in amount field

508 Zero, negative or insufficient amount specified 508 Invalid data in currency field

508 Invalid data in timestamp field 508 Invalid timestamp

508 Transaction out of date 508 Invalid hash supplied 508 Invalid Auto Settle flag 508 Invalid Auto Settle flag

508 Invalid Data in Billing code field 508 Invalid Data in Billing country field 508 Invalid Data in Shipping code field 508 Invalid Data in Shipping country field

508 invalid characters in cust num - please use only A-Z a-z 0-9 _ - . , + @

508 invalid characters in variable reference - please use only A-Z a-z 0-9 _ - . , + @ 508 invalid characters in product id - please use only A-Z a-z 0-9 _ - . , + @ 508 Invalid data in card type field

(35)

508 Can't find original transaction in database.

508 The original transaction failed! You can't rebate a failed transaction. 508 You may only rebate up to 115% of the original amount.

508 Can't find original transaction in database. 508 This transaction was successful the first time!. 508 Can't find original transaction in database. 508 Can't settle a settled transaction.

508 Can't settle for more than 115% of that which you authorised. 509 NonNumeric in Credit card number.

509 Invalid credit card length 509 NonNumeric in issue number. 509 Invalid issue number length

509 Only Switch cards have issue numbers 509 Card number fails Luhn Check

509 Invalid expiry date 509 Card Expiry date in past 509 Expiry month invalid

509 That Card Number does not correspond to the card type you selected 509 An ECI value must be included for MPI enabled accounts. 509 Length of CVV data is incorrect

510 That amount is greater than the max allowed

511 Unable to connect to the merchant response url

512 This transaction has already been rebated and cannot be rebated again. 512 Original transaction not found

512 You may only refund the original cardnumber.

512 You can't refund a delayed transaction that has not been sent for settlement. (You are refunding money to a customer that has not and never will be charged!)

512 Original account was not [account]

512 Original transaction currency was not [currency]

512 You may only refund 115% of the value of the original transaction.

512 This transaction has already been refunded through the epage remote interface and cannot be refunded again.

513 Can't void a settled transaction.

514 Original Transaction Failed! If you just want to give money to the customer use the refund terminal in emerchant.

514 Original Transaction was Successful! 514 Can't settle a settled transaction.

514 Can't settle a transaction already settling.

(36)

Country Codes

Certain realscore checks require you to submit the country as data to be checked against. To ensure that the country names we use are the same, Realex Payments use the following ISO 3166-1 country codes. The common use of these is in a dropdown list from which the customer can select their billing and shipping countries.

code country name AD ANDORRA

AE UNITED ARAB EMIRATES

AF AFGHANISTAN

AG ANTIGUA AND BARBUDA AI ANGUILLA AL ALBANIA AM ARMENIA AN NETHERLANDS ANTILLES AO ANGOLA AQ ANTARCTICA AR ARGENTINA AS AMERICAN SAMOA AT AUSTRIA AU AUSTRALIA AW ARUBA AZ AZERBAIJAN

BA BOSNIA AND HERZEGOVINA BB BARBADOS BD BANGLADESH BE BELGIUM BF BURKINA FASO BG BULGARIA BH BAHRAIN BI BURUNDI BJ BENIN BM BERMUDA BN BRUNEI DARUSSALAM BO BOLIVIA BR BRAZIL BS BAHAMAS BT BHUTAN BV BOUVET ISLAND BW BOTSWANA BY BELARUS BZ BELIZE CA CANADA

CC COCOS (KEELING) ISLANDS

CD CONGO, THE DEMOCRATIC REPUBLIC OF THE CF CENTRAL AFRICAN REPUBLIC

CG CONGO CH SWITZERLAND

CI COTE D'IVOIRE

code country name CK COOK ISLANDS CL CHILE CM CAMEROON CN CHINA CO COLOMBIA CR COSTA RICA CU CUBA CV CAPE VERDE CX CHRISTMAS ISLAND CY CYPRUS CZ CZECH REPUBLIC DE GERMANY DJ DJIBOUTI DK DENMARK DM DOMINICA DO DOMINICAN REPUBLIC DZ ALGERIA EC ECUADOR EE ESTONIA EG EGYPT EH WESTERN SAHARA ER ERITREA ES SPAIN ET ETHIOPIA FI FINLAND FJ FIJI

FK FALKLAND ISLANDS (MALVINAS) FM MICRONESIA, FEDERATED STATES OF FO FAROE ISLANDS FR FRANCE GA GABON GB UNITED KINGDOM GD GRENADA GE GEORGIA GF FRENCH GUIANA GH GHANA GI GIBRALTAR GL GREENLAND GM GAMBIA GN GUINEA GP GUADELOUPE GQ EQUATORIAL GUINEA

(37)

code country name GR GREECE

GS SOUTH GEORGIA AND THE SOUTH SANDWICH

ISLANDS GT GUATEMALA GU GUAM GW GUINEA-BISSAU GY GUYANA HK HONG KONG

HM HEARD ISLAND AND MCDONALD ISLANDS HN HONDURAS HR CROATIA HT HAITI HU HUNGARY ID INDONESIA IE IRELAND IL ISRAEL IN INDIA

IO BRITISH INDIAN OCEAN TERRITORY IQ IRAQ

IR IRAN, ISLAMIC REPUBLIC OF

IS ICELAND IT ITALY JM JAMAICA JO JORDAN JP JAPAN KE KENYA KG KYRGYZSTAN KH CAMBODIA KI KIRIBATI KM COMOROS

KN SAINT KITTS AND NEVIS

KP KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF KR KOREA, REPUBLIC OF

KW KUWAIT

KY CAYMAN ISLANDS KZ KAZAKSTAN

LA LAO PEOPLE'S DEMOCRATIC REPUBLIC LB LEBANON LC SAINT LUCIA LI LIECHTENSTEIN LK SRI LANKA LR LIBERIA LS LESOTHO LT LITHUANIA LU LUXEMBOURG LV LATVIA

LY LIBYAN ARAB JAMAHIRIYA MA MOROCCO

MC MONACO

MD MOLDOVA, REPUBLIC OF MG MADAGASCAR

code country name

OF

ML MALI MM MYANMAR MN MONGOLIA MO MACAU

MP NORTHERN MARIANA ISLANDS MQ MARTINIQUE MR MAURITANIA MS MONTSERRAT MT MALTA MU MAURITIUS MV MALDIVES MW MALAWI MX MEXICO MY MALAYSIA MZ MOZAMBIQUE NA NAMIBIA NC NEW CALEDONIA NE NIGER NF NORFOLK ISLAND NG NIGERIA NI NICARAGUA NL NETHERLANDS NO NORWAY NP NEPAL NR NAURU NU NIUE NZ NEW ZEALAND OM OMAN PA PANAMA PE PERU PF FRENCH POLYNESIA PG PAPUA NEW GUINEA PH PHILIPPINES PK PAKISTAN PL POLAND

PM SAINT PIERRE AND MIQUELON PN PITCAIRN

PR PUERTO RICO

PS PALESTINIAN TERRITORY, OCCUPIED PT PORTUGAL PW PALAU PY PARAGUAY QA QATAR RE REUNION RO ROMANIA RU RUSSIAN FEDERATION RW RWANDA SA SAUDI ARABIA SB SOLOMON ISLANDS SC SEYCHELLES

(38)

code country name SE SWEDEN

SG SINGAPORE SH SAINT HELENA

SI SLOVENIA

SJ SVALBARD AND JAN MAYEN

SK SLOVAKIA SL SIERRA LEONE SM SAN MARINO SN SENEGAL SO SOMALIA SR SURINAME

ST SAO TOME AND PRINCIPE SV EL SALVADOR

SY SYRIAN ARAB REPUBLIC SZ SWAZILAND

TC TURKS AND CAICOS ISLANDS TD CHAD

TF FRENCH SOUTHERN TERRITORIES TG TOGO TH THAILAND TJ TAJIKISTAN TK TOKELAU TM TURKMENISTAN TN TUNISIA TO TONGA TP EAST TIMOR

code country name TR TURKEY

TT TRINIDAD AND TOBAGO TV TUVALU

TW TAIWAN, PROVINCE OF CHINA TZ TANZANIA, UNITED REPUBLIC OF UA UKRAINE

UG UGANDA

UM UNITED STATES MINOR OUTLYING ISLANDS US UNITED STATES

UY URUGUAY UZ UZBEKISTAN

VA HOLY SEE (VATICAN CITY STATE) VC SAINT VINCENT AND THE GRENADINES VE VENEZUELA

VG VIRGIN ISLANDS, BRITISH VI VIRGIN ISLANDS, U.S. VN VIET NAM

VU VANUATU

WF WALLIS AND FUTUNA WS SAMOA YE YEMEN YT MAYOTTE YU YUGOSLAVIA ZA SOUTH AFRICA ZM ZAMBIA ZW ZIMBABWE

(39)

Appendix C – Data Validation Rules

Field Valid Data Comments

Merchant ID a-z A-Z 0-9 Realex Payments assigned

Account a-z A-Z 0-9 Realex Payments assigned

Order ID a-z A-Z 0-9 - _ Max 50 characters

Amount 0-9 No decimal point

Currency A-Z a-z See Currency Codes

Timestamp 0-9 Must be a legal timestamp, 14 digits long

in the form yyyymmddhhmmss and within 24 hours of the current time.

SHA1Hash/MD5Hash a-f 0-9 40 or 32 digits Autosettle Flag 0 or 1

Billing Code a-z A-Z 0-9

Billing Country a-z A-Z 0-9 Should be taken from the Country Codes if you are using the realscore checks

Shipping Code a-z A-Z 0-9

Shipping Country a-z A-Z 0-9 Should be taken from the Country Codes if you are using the realscore checks

Customer Number a-z A-Z 0-9 “ ” - _ Max 50 characters Variable Reference a-z A-Z 0-9 “ ” - _ Max 50 characters Product ID a-z A-Z 0-9 “ ” - _ Max 50 characters Comments a-z A-Z 0-9 “ ” - _ Max 255 characters

Card type a-z A-Z See Card Types.

Cardnumber 0-9 Must pass Luhn check, and be properly

matched with the card type.

Cardholder name See note. Max 50 characters. Most 506 errors (malformed XML error) that you will receive will be because the cardholder has “funny” characters in their name. These characters (e.g. ß, or ä) are encoded using the ISO-8859-1 standard and not UTF-8 (which is the default for the parser used by Realex Payments). Therefore you should ensure that the encoding set in the top line of the XML you send to Realex Payments is correct. In most cases ISO-8859-1 will suffice but as more and more international customers use your site, Unicode (or UTF-8) encoding may be encountered (which allows for many more characters such as Japanese or Hebrew words). Further information will follow as the UTF-8 standard is finalised.

Issue Number 0-9 0, 1, or 2 digits – only SWITCH cards

(40)

Appendix D – Realex Guides

Title Target Description

Realauth XML Definitions Guide

Developers This guide provides details of the XML messages required for each type of transaction. This will be required for any remote integration.

RealMPI Redirect Guide Merchants RealMPI is the 3DSecure service available through Realex. Realex will carry out the integration work for redirect implementations, so this guide provides an overview of the service with fewer technical details. RealMPI Remote Guide Developers For remote implementations of RealMPI there will be

some development work required by the merchant. This guide provides the technical details needed by developers.

RealEFT Developers Guide

All RealEFT is the direct debit and recurring credit card payment service provided by Realex. This guide provides both the details needed to complete

integration along with an overview of how the service works and so is useful to both merchants and

developers. Recurring Payments

Guide

All Realex also provide a recurring payments solution. This allows merchants to raise payments by storing card details on our secure servers and then passing a reference in the place of the card number. This guide provides both an overview and the details required to integrate the service.

RealFX Guide Developers RealFX is the Dynamic Currency Conversion service provided by Realex. DCC allows merchants to provide customers with the option of making purchases in their native currency, with exchange rates retrieved in real time.

Realauth Developer s Guide Version 3.0.1

Table of Contents

Introduction to Realex Payments

1

Realex Services

1.1 Realauth Scenarios

1.1.1 Sub-Accounts

2

Realauth Redirect

2.1 Redirect Example

2.2 Templates

2.3 Redirect Integration

2.4 Redirect Request Field Definitions

2.5 Redirect Response Field Definitions

2.6 Digital Signature for Redirect

3

Realauth Remote

3.1 Remote Example

3.2 Application Based Checking

3.3 Remote Integration

3.3.1 Sample Java Code

Java example

3.3.2 Sample ASP Code

ASP example

3.3.3 Sample Perl Code

Perl example

3.4 Remote Request Message

3.5 Remote Response Message

3.6 Digital Signatures for Remote

4

Steps Required To Go Live

Appendix A – Sample Code

Luhn check

For example: credit card number 3648455485235855

Appendix B – Codes

Currency Codes

Card Types

Response Codes

Country Codes

Appendix C – Data Validation Rules

Appendix D – Realex Guides

Appendix E – Version Control

Version

Date

Amendments

Completed By

2.5

02/11/05

Added 108 response code

Colm Reid

2.6

08/12/05

Added template guidelines

Colm Reid

2.7

05/01/06

Changed Appendix C and page 33

Colm Reid

2.8

25/01/06

Added response code 511

Darren Greaney

2.9.1

12/04/06 Updated Special Characters

Darren Greaney

2.9.2

13/04/06

Updated 509 errors with APACS 30 responses

Colm Reid

2.9.3

16/06/06 Added cvnresult codes to response definitions

Chris Dare

2.9.4

11/09/06 Updated CVN responses

Darren Greaney