realex payments magento 1 extension configuration guide€¦ · 2.2 hosted payment page ‘redirect...

Realex Payments

Magento 1 Extension

Configuration Guide

Version: 1.2

2

Document Information

Document Name: Magento 1 Extension Configuration Guide

Document Version: 1.2

Release Date: 03-10-17

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 The Observatory, 7-11 Sir John

Rogerson’s Quay, Dublin 2, Ireland and is registered in Ireland, company number 324929.

© 2000—2017 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

authorisation of Realex Payments. All other trademarks, service marks, and trade names referenced in this material are the

property of their respective owners.

3

Table of Contents

1 Compatibility & Support ................................................................................................................. 5

1.1 Dedicated Integration Team ................................................................................................... 5

2 Realex Payments Integration Features ........................................................................................... 6

2.1 XML Requests - ‘Remote API’ Integration ............................................................................... 6

2.2 Hosted Payment Page ‘Redirect HPP’ Integration .................................................................. 6

2.3 RealVault – Tokenisation and Recurring Payments ................................................................ 7

2.4 Dynamic Currency Conversion ................................................................................................ 8

2.4.1 What are the Benefits of Dynamic Currency Conversion? ..................................................... 8

3 Installation .................................................................................................................................... 10

3.1 Installing from a Downloaded Package ................................................................................. 10

4 Global Configuration ..................................................................................................................... 11

4.1 Realex Payments Account Information................................................................................. 11

5 API (Remote) Integration .............................................................................................................. 12

5.1 Configuration ........................................................................................................................ 12

5.2 API (Remote) Customer Checkout ........................................................................................ 16

5.2.1 Standard Checkout ................................................................................................................ 16

5.2.2 Checkout with 3DSecure Cardholder Authentication ........................................................... 18

6 Hosted Payment Page (HPP) Integration ...................................................................................... 19

6.1 Hosted Payment Page (HPP) Configuration .......................................................................... 19

6.2 Hosted Payment Page (HPP) Customer Checkout ................................................................ 21

6.2.1 Standard Checkout ................................................................................................................ 21

6.2.2 Checkout with 3DSecure Cardholder Authentication ........................................................... 23

6.2.3 Checkout with Dynamic Currency Conversion (DCC) ............................................................ 24

7 Tokenisation (RealVault) ............................................................................................................... 26

7.1 Tokenisation (RealVault) Configuration ................................................................................ 26

7.2 Tokenisation (RealVault) Customer Checkout ...................................................................... 29

7.3 Token Management .............................................................................................................. 30

7.3.1 Token Manager & Customer Profile ..................................................................................... 30

7.3.2 Customer Account Section .................................................................................................... 32

8 Reviewing Orders & Transactions ................................................................................................. 33

8.1 Payment Information ............................................................................................................ 33

8.2 The Transactions Tab ............................................................................................................ 34

4

8.3 Abandoned Carts – Failed Orders & Incomplete Transactions ............................................. 35

8.3.1 Reviewing Failed Orders ....................................................................................................... 35

8.3.2 Incomplete Transactions ....................................................................................................... 37

9 Order Management ...................................................................................................................... 39

9.1 Capturing an Order ............................................................................................................... 39

9.2 Rebating an Order ................................................................................................................. 40

9.3 Voiding an Order ................................................................................................................... 42

10 Transaction Logs ........................................................................................................................... 43

10.1 Reviewing Logs ...................................................................................................................... 43

11 Order Clean-Up ............................................................................................................................. 44

11.1 Order Clean-Up Configuration .............................................................................................. 44

11.2 Configuring the Magento Cron Job ....................................................................................... 45

12 Partner Referral Process ............................................................................................................... 48

12.1 Qualifying a referral lead ...................................................................................................... 48

12.2 Merchant Set-Up ................................................................................................................... 48

13 Appendix ....................................................................................................................................... 50

Appendix 1.0: e-Commerce Indicator (ECI) Results .......................................................................... 50

Appendix 2.0: Security Code (CVN / CVC / CVV) and Address Verification Service (AVS) Results .... 50

5

1 Compatibility & Support

The plugin has been tested and proven to work with the following versions of Magento:

Community 1.6+ & Enterprise 1.11+

The plugin is confirmed as incompatible with the following versions of Magento:

Community versions earlier than 1.6 & Enterprise versions earlier than 1.11

1.1 Dedicated Integration Team

Our integration team will work with you to implement and optimise the extensive functionality

provided by the plugin. You will benefit from professional phone and email support services, along

with full access to our sandbox environment. Need help fast? Pick up the phone and speak directly to

us; no IVRs, no hassle.

Contact: [email protected]

Dublin: +353(0)1 702 2000

London: +44(0)20 3178 5370

Paris: +33(0)1 53 24 53 28

mailto:[email protected]

6

2 Realex Payments Integration Features

2.1 XML Requests - ‘Remote API’ Integration

With the ‘Remote’ integration option you have full control of the transaction flow providing a

completely seamless experience for the customer. The card details are collected on your server and

passed to Realex Payments as secure XML messages. The transaction results are returned in real time.

2.2 Hosted Payment Page ‘Redirect HPP’ Integration

Realex Payments hosts a secure, fully customisable and responsive payment page. We collect the card

details and transmit them to the financial institution for authorisation. The customer and the

transaction results are then returned to your store. All card details are captured and encrypted by

Realex Payments before being sent for authorisation. The payment page is hosted on a Level 1 PCI

Compliant Realex Payments server. This significantly reduces the merchant’s own PCI requirements.

7

2.3 RealVault – Tokenisation and Recurring Payments

RealVault, the Realex Payments card storage solution, is designed to enhance your customer’s

shopping experience while alleviating the PCI compliance requirements associated with storing

sensitive card details. By using the supported RealVault functionality, you can easily avail of tokenised

payments and a simplified one-click checkout for your customers.

Each customer is assigned a token reference called a payer reference (or just payer-ref). Their

associated payment method, i.e. the card to be stored in RealVault, is given a payment reference (or

card reference).

Once the payment reference has been saved to RealVault, your customers can easily re-use their saved

cards at the checkout stage. You may also raise payments manually against saved card details or setup

scheduled recurring payments through our transaction processing and reporting tool – RealControl.

8

2.4 Dynamic Currency Conversion

Dynamic Currency Conversion (DCC) is available to all Realex Payments merchants, subject to their

Merchant Services Agreement. It allows merchants to price their products and services in their own

currency while giving customers the choice to pay in the currency of their card at the checkout stage.

This is in full compliance with Visa and MasterCard regulations.

2.4.1 What are the Benefits of Dynamic Currency Conversion?

Simplicity: Merchants require just one base currency funding account. There is no need for multiple

accounts in different currencies; this greatly reduces administration and fees.

Ease of integration: You don’t need to implement separate price lists for every currency that you want

to support. The automated currency conversion occurs at the point of sale.

Transparency: The customer knows in advance the exact amount that will be charged to their card -

they don’t have to wait for the funds to be debited.

9

A revenue opportunity: As part of the currency conversion process, you, as the merchant, will be in a

position to receive commission from your Dynamic Currency Conversion provider. For more

information, please consult your Merchant Services Provider.

Choice: Customers can choose to pay in the currency of their card or in your store’s base currency.

Versatility: The Dynamic Currency Conversion service is available in a call centre or website

environment.

10

3 Installation

This section outlines how to install the Realex Payments plugin through Magento Connect Manager.

3.1 Installing from a Downloaded Package

Navigate to System -> Magento Connect -> Magento Connect Manager and login using your

administrator credentials.

Under the Direct package file upload heading choose Browse. Select the Realex Payments plugin you

wish to install. Once selected, click Upload.

The terminal screen will display whether the plugin was successfully installed or not.

Choose Return to Admin to be brought back to the general Magento admin panel. You must logout

and log back in again in order for the changes to take effect.

You can now configure the Realex Payments plugin from System -> Configuration section.

11

4 Global Configuration

4.1 Realex Payments Account Information

Login to the Magento Admin Panel, navigate to System -> Configuration and under the Sales heading

click the Realex Payments option.

From here you can configure the various integration types supported by this plugin including API

(Remote), HPP (Hosted Payment Page) and Tokenisation (RealVault).

The first tab, Realex Payments Account Information allows you to enter your overall account

credentials. These are global settings that apply to all integration types. You can enter specific

credentials for different websites by changing the website scope in Magento.

Enable Logs: If this is set to Yes all requests and responses to and from Realex Payments will be

recorded and saved to the file path provided. They can also be viewed from Sales -> Realex Payments

-> Logs. Please see section 10 of this guide.

Merchant ID: The Merchant ID (or Client ID) as supplied by your Realex Payments account manager.

Shared Secret: The Shared Secret as supplied by your account manager. This is sensitive information

that should never be emailed.

Rebate Password: The Rebate password as supplied by your account manager. This is sensitive

information that should never be emailed.

12

5 API (Remote) Integration

With the API (Remote) integration type, the cardholder data is collected on your store and passed to

Realex Payments via a secure XML message and the results are returned in real time. Merchants using

this integration type must have an SSL certificate on their store and must adhere to PCI Compliance

rules regarding the capture of cardholder data.

5.1 Configuration

This section of the guide outlines each configuration field and the options available in the Magento

Admin Panel.

Enabled: Determines if the API (remote) payment method will be available on the checkout of your

Magento store.

Payment Action: Determines the settlement type of each transaction. If this is set to Authorize and

Capture (Autosettle), transactions will be authorised and the funds captured at checkout. If you wish

to authorise at checkout and capture the funds at a later time, select Authorize Only (Delayed

13

Settlement). You can settle delayed settled transactions by creating and capturing an invoice in the

Magento orders section. Please see section 9.1 of this guide.

New Order Status: Here you can set the default status of orders that are successfully processed

through this payment method.

Title: This is the description of the payment method that will be displayed to the customer at the

checkout stage, e.g. “Pay by Debit or Credit Card”. The title will also be recorded against the order in

Magento to indicate how the transaction was processed.

Mode: Allows you to switch between the Live and Sandbox version of your Realex Payments account.

Live URL: Sets the Realex Payments URL that transactions are sent to.

Default Subaccount: The subaccount through which transactions will be processed by default. Your

Realex Payments account manager will provide you with the subaccount names configured under your

Merchant ID.

Sub Account Rules: This allows you to route transactions to a particular subaccount based on the

customer’s card choice.

Allowed Card Types: Specifies the choice of cards the customer will have at checkout. The cards you

can accept will be determined by your Merchant Services Provider and your Realex Payments account

configuration.

14

Use 3DSecure: Determines if transactions are to be processed through 3DSecure Cardholder

Authentication. You will need to ensure your account is registered for Verified by Visa, MasterCard

SecureCode and American Express SafeKey (if required). Please contact your Realex Payments account

manager for assistance with this.

Use iframe: If the customer is enrolled for 3DSecure Cardholder Authentication, they will be

redirected to their Issuing Bank’s Access Control Server (ACS) to enter the passphrase associated with

their card. If this option is set to Yes, the ACS will load inside a frame on your Magento store thus

maintaining the checkout flow and enhancing the payment experience for your customer.

3DSecure URL: Sets the URL that 3DSecure transactions are sent to in Live / Sandbox mode.

Display iFrame on checkout page: Determines if the iFrame is loaded directly on the checkout or on

an interim page. Certain 3rd party plugins for Magento that enable one-step-checkout may be

incompatible with displaying the iFrame on the checkout page.

Require Liability Shift: Ensures that only those 3DSecure transactions that offer additional chargeback

protection will be allowed to proceed to authorisation. There are ten 3DSecure scenarios, three of

which provide a liability shift. If you set this to Yes, transactions that do not fall within these three

15

scenarios will be prevented from proceeding to authorisation. Note: the liability shift is subject to

further conditions outside of these ten scenarios; merchants should also check with their Merchant

Services Provider regarding their own chargeback rules.

Payment from applicable countries / specific countries: Specifies which customers are allowed access

this payment method based on their billing country. You can allow all countries or create a specific

list.

Sort order: Determines the placing of this payment method within the list at the checkout stage.

Setting this to ‘1’ will ensure that this payment method appears at the top.

16

5.2 API (Remote) Customer Checkout

Once your customer has chosen their items and entered their billing and shipping details they will be

presented with the option to enter their card details. The title that appears above the card payment

form can be customised in the Realex Payments Configuration panel.

5.2.1 Standard Checkout

Once the customer has chosen the appropriate payment method the card form fields will be displayed.

Name on Card: The customer should enter their card name exactly as it appears on their card.

Card Type: The choice of available cards will be determined by the Allowed Card Types selected in the

Realex Payments Configuration panel.

Card Number: The digits from the front of the customer’s card. If the number entered does not match

the card type the customer has selected, the form will prompt the customer to correct their details.

Expiration Date: Customers must enter a valid expiry date. If they don’t, the form will prompt to them

to correct their details.

Security Code: The Security Code, also known as the CVN, CVC or CVV2, is the three digit code on the

back of the customer’s card. Note: for American Express cards, the code is four digits long and will

17

appear on the front of the card. The form will warn the customer if they have entered their code in

the incorrect format.

Once the customer has entered their details and clicked Continue they will be presented with the

option to place their order. Their payment method of choice is summarised to the right of the

checkout.

As soon as they click Place Order the card data is sent to Realex Payments to be processed. Realex

Payments will check that the card data entered is in a valid format and will then forward the details of

the transaction on to the relevant Merchant Services Provider.

The result of the transaction is returned immediately. If the customer’s payment was successful they

will be redirected to the standard Magento success page.

In the event that the customer’s transaction is unsuccessful they will be redirected to the standard

Magento failure page. The items they have chosen will remain in their cart so they can easily return

to the checkout to try again. A record of the order will be created in the Orders section of Magento

with the status set to ‘Canceled’. Please see section 8 of this guide for more information on reviewing

orders.

18

5.2.2 Checkout with 3DSecure Cardholder Authentication

The API (Remote) payment method is fully compatible with 3DSecure Cardholder Authentication. If

3DSecure is enabled within your plug-in configuration and on your Realex Payments account, as soon

as the customer clicks Place Order a request is sent to Realex Payments to check that their card is

enrolled in 3DSecure.

If their card is not enrolled in 3Dsecure the authorisation will be processed as usual. Data within the

authorisation message will notify Realex Payments that the check was performed and that the

cardholder was not participating.

If the cardholder is participating, they will be redirected to their issuing bank’s Access Control Server

(ACS). This is the page where the customer enters the passphrase associated with their card. You can

choose to load this page in an iframe on your store in order to better maintain the checkout flow as

shown below.

The customer will be redirected to either the success or failure page, depending on whether the

3Dsecure outcome falls under the allowed scenarios (see Require Liability Shift in section 5.1). For

example if they enter their passphrase correctly the transaction will proceed as normal. The 3DSecure

result is recorded and can be viewed in the Orders section. Please see section 8 of this guide.

19

6 Hosted Payment Page (HPP) Integration

Realex Payments hosts a secure, fully customisable and responsive payment page. The payment page

collects the card details and they are transmitted by Realex Payments to the financial institution for

authorisation. The customer and transaction results are then returned to your store. The payment

page is hosted on a Level 1 PCI Compliant Realex Payments server.

6.1 Hosted Payment Page (HPP) Configuration


Admin Panel.

Enabled: Determines if the Hosted Payment Page payment method is available on the checkout of

your Magento store.

Payment Action: Determines the settlement type of each transaction. If this is set to Authorize and

Capture (Autosettle), transactions will be authorised and the funds captured at checkout. If you wish

20

to authorise at checkout and capture the funds at a later time, select Authorize Only (Delayed

Settlement). You can settle delayed settlement transactions by creating and capturing an invoice in

the Magento orders section. Please see section 9.1 of this guide.

New Order Status: Here you can specify the default status of orders that are successfully processed

through this payment method.

Title: This is the description of the payment method that will be displayed to the customer at the

checkout stage, e.g. “Pay by debit or credit card”. The title will also be recorded against the order in

Magento to indicate how the transaction was processed.

Mode: Allows you to switch between the Live and Sandbox version of your account.

Live URL: Sets the URL that transactions are sent to in Live mode.

Sandbox URL: Sets the URL that transactions are sent to in Sandbox mode.

Use iframe: As soon as the customer selects ‘Place Order’, they will be redirected to the Realex

Payments Hosted Payment Page to enter their card details. If you set this option to Yes the payment

form will load inside a frame on your Magento store thus maintaining the checkout flow and

enhancing the payment experience for your customer.

iframe Size: Allows you to specify the size of the iframe. You can edit this depending on the services

enabled on your Realex Payments account.

Display iframe on checkout page: Determines if the iframe is loaded directly on the checkout or on



Default Subaccount: Your Realex Payments account manager will provide you with the subaccount

names configured under your Merchant Id. Here you can enter the default subaccount to be used.

Allowed Card Types: Determines the choice of cards the customer will have at checkout. The cards

you can accept will be determined by your Merchant Services Provider and your Realex Payments

account configuration.

21

Payment from applicable countries/ specific countries: Specifies which customers are allowed access

this payment method based on their billing country. You can allow all countries or create a specific

list.

Sort order: Determines the placing of this payment method within the list available at the checkout

stage. Setting this to ‘1’ will ensure it appears at the top.

6.2 Hosted Payment Page (HPP) Customer Checkout

Once the customer has chosen their items and entered their billing and shipping details they will be

presented with the option to ‘Pay by Debit or Credit Card’. This title can be customised in the Realex

Payments Configuration panel.

6.2.1 Standard Checkout

Once the customer clicks Place Order they will be redirected to the Realex Payments secure Hosted

Payment Page (HPP). This page can be loaded in an iframe to better maintain the checkout flow.

Below is an example of the iframe loaded on the checkout page.

22

Whether you choose to use an iframe or not, the Hosted Payment Page can be styled with your own

branded template to maintain the look and feel of your Magento store. You can use a responsive

template if you want the design to adapt automatically to different devices along with the payment

form itself.

1. Responsive template using the standard Magento theme, displaying for a desktop device

23

2. Responsive template using the standard Magento theme, displaying for a mobile device

Alternatively, you can supply a standard template for rendering on all desktop/laptop devices, and a

mobile-aware template for rendering on mobile devices. The Hosted Payment Page will automatically

render the correct template depending on what device the customer is using.

For more information on templates please see the Developer Guide for HPP on the Realex Payments

Resource Centre: https://resourcecentre.realexpayments.com/products.html?id=198

Once the customer has completed their transaction, they will automatically be redirected back to your

Magento store. The success or failure page will be displayed depending on the outcome of the

transaction. If the transaction is unsuccessful the items will remain in the customer’s cart so they can

easily attempt to checkout again.

6.2.2 Checkout with 3DSecure Cardholder Authentication

The Hosted Payment Page (HPP) fully supports 3DSecure Cardholder Authentication and handles the

process for you. This includes checking if the cardholder is enrolled in 3DSecure.

https://resourcecentre.realexpayments.com/products.html?id=198

24

If the cardholder is participating, they will be redirected to their issuing bank’s Access Control Server

(ACS). This is the page where the customer enters the passphrase associated with their card. If you

are using an iframe in conjunction with the HPP, this page will also load within it.

For HPP, your 3DSecure settings are configured by your Realex Payments account manager. This

includes switching it on or off and configuring the 3DSecure scenarios you wish to allow or block. For

example you may choose for your account to be configured to allow only the transactions that offer

additional chargeback protection to proceed to authorisation. Note: the liability shift is subject to

further conditions. You should also check with your Merchant Services Provider regarding their

chargeback rules.

The customer will be redirected to either the success or failure page, depending on whether the

3DSecure outcome falls under the allowed scenarios (as configured by your Realex Payments account

manager). For example, the account can be configured to allow the transaction to proceed as normal

if the customer enters their passphrase correctly. The 3DSecure result is recorded and can be viewed

in the Orders section. Please see section 8 of this guide.

6.2.3 Checkout with Dynamic Currency Conversion (DCC)

Dynamic Currency Conversion (DCC) is available to all Realex Payments merchants, subject to their

Merchant Services Agreement. It allows merchants to price their products and services in their own

currency while giving customers the choice to pay in the currency of their card, in full compliance with

Visa and MasterCard regulations.

If you choose to use DCC on the HPP, it will be enabled and configured by your Realex Payments

account manager.

Below is an example of Dynamic Currency Conversion on the Hosted Payment Page. As soon as the

customer enters their card number it is checked by the Currency Conversion Processor. If the card is

of a different currency to the merchant’s base currency, the Currency Conversion Processor will

provide the most up to date rate for that currency.

25

This will be displayed to the customer along with the converted transaction amount. The customer

can choose to pay in their own currency at this rate, or in the merchant’s base currency. You can view

their choice and the conversion rate in the Orders section of Magento. Please see Section 8 of this

guide.

26

7 Tokenisation (RealVault)

Merchants using the Realex Payments Magento plugin can make use of our card storage solution -

RealVault. If the customer chooses to save their card, and their transaction is successful, they will be

able to avail of a simple one-click checkout option the next time they checkout. This does not involve

any storage of cardholder data in Magento.

7.1 Tokenisation (RealVault) Configuration


Admin Panel.

Enabled: Determines if RealVault (tokenisation) is available on the checkout of your Magento store.

27

Store Card: Setting this to Offer Save Card will place a checkbox on the checkout page which your

customers can tick /untick as appropriate to indicate if they want their card details stored. If this is set

to Always Store Card, the customer will not have this choice but you must inform them that their card

details will be stored.

Store Card Label / Always Store Card Label: Here you can edit the message you wish to display to the

customer. If you are giving the customer the option to save their card, this text will be the label for

the checkbox. If you are saving the card details without giving the customer the option, this message

should inform them that you are doing so.

Allow Delete Cards: By setting this to Yes you will allow customers to delete their cards from your

store and from RealVault. Customers can update and delete their cards through their account profile

in Magento, please see section 7.3.1.

Payer Type: Defines the category of payer submitted to RealVault.

Total Saved Cards Allowed: This restricts the number of cards that any one customer may save to

Magento / RealVault.

Require Security Code: Setting this to Yes will ensure that customers using one-click checkout are

prompted for their security code (the 3 digit number that is present on their card outside of the

magnetic strip). If you wish to set this to No you should ensure to check with your Merchant Services

Provider.

Payment Action: Determines the settlement type of tokenised transactions. If this is set to Authorize

and Capture (Autosettle), transactions will be authorised and the funds captured at checkout. If you

wish to authorise at checkout and capture the funds at a later time, select Authorize Only (Delayed

Settlement). You can settle Delayed Settlement transactions by creating and capturing an invoice in

the Magento orders section. Please see section 9.1 of this guide.

Mode: Allows you to switch between the Live and Sandbox version of your account.

Live URL: Sets the URL that tokenised transactions are sent to in Live mode.

Default Subaccount: Here you can enter the default subaccount to be used for tokenised transactions.

Some Merchant Service Providers may request that you process tokenised transactions through a

28

specific merchant number. Your Realex Payments account manager will help you set this number up

under a specific subaccount name, which you can enter here.

Sub Account Rules: This allows you to route transactions to a particular subaccount based on the card

type of the token.

Use 3DSecure: Determines whether tokenised transactions are to be processed through 3DSecure

Cardholder Authentication. You will need to ensure you are registered for Verified by Visa, MasterCard

SecureCode and American Express SafeKey (if required). Please contact your Realex Payments account

manager for assistance with this.

Use iframe: If the customer is enrolled for 3DSecure cardholder authentication, they will be redirected

to their Issuing Bank’s Access Control Server (ACS) to enter the passphrase associated with their card.

If you set this option to Yes the ACS will load inside a frame on your Magento store thus maintaining

the checkout flow and enhancing the payment experience for your customer.

Display iframe on checkout page: Determines if the iframe is loaded directly on the checkout or on



3DSecure URL: Sets the URL that 3DSecure transactions are sent to in Live / Sandbox mode.

Require Liability Shift: Ensures that only 3DSecure tokenised transactions that offer additional

chargeback protection will be allowed to proceed to authorisation. There are ten 3DSecure scenarios,

three of which provide a liability shift. If you set this to Yes, transactions that do not fall within these

three scenarios will be prevented from proceeding to authorisation. Note: the liability shift is subject

to further conditions outside of these ten scenarios; merchants should also check with their Merchant

Services Provider regarding their own chargeback rules.

29

7.2 Tokenisation (RealVault) Customer Checkout

The configuration for the previous section applies to both Realex Payments methods, i.e. the HPP

(Hosted Payment Page) and API (Remote).

If you are providing the customer the choice to save their card, a tick box will display when they are

selecting their payment method. This tick box will have a customisable description, for example, “Save

your card details for next time?”. If you are saving the customer’s card without giving them the choice,

a message will display advising them that their card details will be stored. You must inform customers

if you intend to store their card details.

If the transaction is successful, the customer’s card details will be saved to the Realex Payments

RealVault and an associated token will be stored in your Magento store.

The next time the customer checks-out they will have the option to use their stored card.

In the Realex Payments configuration section, you can specify if you want the customer to be

prompted for the security code of their saved card when making a payment. PCI Compliance rules

prohibit the storage of the security code.

Once the customer has chosen the card they wish to use and has clicked Place Order the result of the

transaction is returned instantly. The customer will be redirected to the standard Magento success or

failure page, depending on the transaction result.

Saved cards can also be processed through 3DSecure Cardholder Authentication. The process is the

same as the API (Remote). This time however, only the tokenised version of the card is involved. Please

see section 5.2.2.

30

7.3 Token Management

This section outlines how tokenised cards can be managed by both Magento store administrators and

customers.

7.3.1 Token Manager & Customer Profile

On the Magento main menu, navigate to Sales -> Realex Payments -> Token Manager. This tab

displays all tokenised cards on your store independent of any customer profile.

For each token the following information is displayed.

ID: The unique Magento ID for the token

Customer ID: The Magento customer profile ID that the token is associated with.

Customer Name: The customer name as determined by their Magento profile.

Token Ref: The Realex Payments unique RealVault token reference.

Payer Ref: When a customer saves their card for the first time a Payer Profile is created in RealVault.

All subsequent tokens are saved to this profile. The Payer Ref is the unique identifier for the Payer

Profile.

Card Holder Name: The name the customer entered when the card was saved.

Card Type: The card type code as saved in RealVault, for example ‘MC’ for Mastercard.

Last Four Digits: The last four digits of the card as stored in RealVault.

Expiry Date: The expiry date of the card as stored in RealVault.

31

It is possible to sort the tokens by expiry date so you can see which ones are close to expiring. You

may choose to notify the customer to update their card or update it yourself.

If you wish to delete a token you can select the relevant row and from the Actions drop-down menu

choose Delete Token Card. Once you click Submit, this will remove the tokenised card from both

Magento and RealVault.

Clicking on a particular token will bring you to the Edit Token tab.

You can choose to delete the token by clicking Delete Item. If you wish, you can edit both the Card

Holder Name and Expiry Date and select Save Item. This will update the tokenised card details not

only in Magento, but also in RealVault.

Stored cards can also be viewed per customer profile. Navigate to the Manage Customers section of

the Magento Admin Panel and click on the particular customer profile you wish to view. The menu on

the left-hand side gives you the option to view that customer’s saved cards.

This time, only tokens associated with the particular customer will be displayed. However, the

functionality is the same as in the Token Manager. Tokens can be edited and deleted.

32

7.3.2 Customer Account Section

Customers can view their stored cards through their Magento profile. Once logged in they can

navigate to My Account and select My Stored Cards

If you have Allow Delete Cards enabled the customer will have the option to Remove their card.

If the customer clicks Edit they will be presented with the option to edit their Card Name and the

Expiry Date.

Choosing to Update or Remove will perform this action not only in the Magento store but also in

RealVault.

33

8 Reviewing Orders & Transactions

A great deal of information relating to the transaction outcome is available in the Orders section of

Magento. This can be easily reviewed when you are deciding to capture or ship an order. If payment

was successful, the order status will be set to the New Order Status configured under the relevant

Realex Payments Configuration section.

8.1 Payment Information

In the Magento Orders tab, click on the order you wish to view. Underneath the customer’s billing

and shipping details the Payment Information will be displayed. Here you will find a summary of the

key information from the transaction outcome: in this example the payment method used, the card

type and the last four digits of the card number are displayed above the record of the transaction.

34

Result: The outcome of the transaction. Will contain “00” if the transaction was successful or another

value (depending on the outcome) if not.

Auth Code: Will contain a valid authcode if the transaction was successful. This field will be empty

otherwise.

Message: Will contain a text message that describes the result code above.

Transaction Reference: The unique Order ID that was submitted to Realex Payments.

CVN Result: This field indicates if the post code the customer provided was correct. Appendix 2.0

below shows the possible results for this check.

AVS Address Result: The AVS (Address Verification Service) check compares the billing details that the

customer provides against the address their bank has on file for that card. This is an advisory service.

This field indicates if the digits from the first line of the address that the customer provided were

correct. This is only applicable to UK based customers. Appendix 2.0 below shows the possible results

for this check.

AVS Postcode Result: This field indicates if the post code the customer provided was correct. This

check is only applicable to UK based customers. Appendix 2.0 below shows the possible results for this

check.

TSS Result: The Transaction Suitability Score for this transaction. This is based on a number of checks

performed by the Realex Payments fraud scoring tool - RealScore. These fraud checks can be modified

and weighted using our transaction processing and reporting tool - RealControl. For more information,

please contact your Realex Payments account manager.

8.2 The Transactions Tab

The full response returned by Realex Payments can be viewed in the transactions tab. When viewing

the order, select Transactions from the left-hand side menu. Click on the relevant transaction and the

full details of the response sent back from Realex Payments will be displayed.

35

For more details of the various response fields that can be returned from Realex Payments, please

consult the relevant developer guide on our Resource Centre.


8.3 Abandoned Carts – Failed Orders & Incomplete

Transactions

If a customer’s payment is unsuccessful or if they perhaps forgot their 3DSecure passphrase, the

Realex Payments plugin ensures this is recorded in the Magento Orders tab along with the full

customer profile. You can also view abandoned carts in the Incomplete Transactions tab.

8.3.1 Reviewing Failed Orders

In the event that a customer’s payment is declined or fails for another reason, the order will appear

in the Magento Orders tab with a status of ‘Canceled’.


36

Once you have selected the order you wish to view, you will be able to see the customer’s profile,

billing, shipping and contact details. Under Payment Information, a summary of why the payment

failed will be recorded.

Depending on the outcome of the transaction, you may wish to contact the customer to encourage

them to try their order again. They can do this by viewing their orders under the Magento account

profile and clicking Reorder.

This will re-open the order and allow the customer to proceed through the checkout as normal. A new

order will be created in Magento. Alternatively, you could contact the customer by phone and process

their payment through our transaction management tool – RealControl. This provides a terminal

through which you can process Mail-Order-Telephone-Order (MOTO) payments. Please see the

RealControl user guide on our Resource Centre:



37

8.3.2 Incomplete Transactions

Customers may abandon their cart earlier on in the order life cycle, before they have fully completed

checkout or before their payment is fully processed by Realex Payments. The Incomplete Transactions

tab allows you to gain crucial insight into these potentially lost sales.

Navigate to Sales -> Realex Payments -> Incomplete Transactions. Here you will be presented with

all recent declined, incomplete or abandoned transactions on your store.

In the example below, the customer has clicked Place Order and their card has been checked to see if

it is enrolled for 3DSecure Cardholder Authentication. At this particular time, there was an issue with

the 3DSecure Enrolment Server and because no chargeback protection is provided in this scenario,

the transaction has been blocked from proceeding.

There is no order associated with this transaction because Magento has prevented the user from

proceeding through the checkout process. However, in the Incomplete Transactions tab, we have a

record of the attempt to check the enrolment status of the card.

By clicking on this transaction and viewing the Transaction Details, you’ll be able to see the precise

response to the enrolment check.

38

There are two key indicators here. One is the result field – a value of ‘110’ indicates that the card was

not confirmed as enrolled for 3DSecure Cardholder Authentication; under certain circumstances this

would be fine. If a card is not enrolled, additional chargeback protection may be provided.

However, in this case, we can see the Enrolled field has returned ‘U’ which indicates that it wasn’t

possible to verify whether the cardholder was actually enrolled or not. In this case, additional

chargeback protection is not provided so the transaction has been blocked by our 3DSecure settings.

The Incomplete Transactions tab is designed to guarantee complete transparency and control over

abandoned, incomplete and failed transactions on your Magento store at each stage of the checkout

process.

39

9 Order Management

The Realex Payments plugin allows you to fully manage the order life-cycle from the Magento admin

panel. This section outlines how you can Capture, Rebate and Void an order.

9.1 Capturing an Order

Merchants who choose to Authorize Only at checkout (Delayed Settlement) can Capture (settle) their

orders for a fixed period of time after the initial authorisation. Navigate to Sales -> Orders and click

the order you wish to capture. If you choose Invoices from the left-hand side menu you’ll see that

there is no invoice associated with the order. This is because we haven’t captured it yet.

Clicking the Invoice button will create a new invoice to be raised against this order. Here you can

review the result of the transaction before deciding to capture the funds. You can edit the amount to

capture by ticking the Settle Amount box. Merchants can settle for 0 - 115% of the original order

value. For example, if a customer ordered three items and then contacted you to cancel one, you may

choose to only capture the cost of the remaining two items that are to be shipped.

You must choose to Capture Online in order for the request to be sent to Realex Payments. Once you

click Submit Invoice, a capture request (settle) with the amount specified will be sent.

Once complete, you will be returned to the Order View tab and a message will display indicating the

outcome of the capture request.

40

The record of the capture will also be added to the history of the order under Payment Information.

9.2 Rebating an Order

Whether your orders are set to Authorize Only or Authorize and Capture, once an order has been

successfully settled with your Merchant Services Provider, you may rebate the customer for 0 – 115%

of the original order value. In order to do this, you must create a credit memo in Magento. Please

note, the credit memo must be linked to a specific invoice.

Navigate to Sales -> Orders and click the order you wish to rebate. Open the relevant invoice and

select Credit Memo. Under Payment Information you can review the history of the order before

deciding to process the rebate.

41

You must choose Refund as opposed to Refund Offline. This will send the rebate request to Realex

Payments. You may edit the amount to rebate by editing the adjustment fields provided by Magento.


outcome of the rebate request.

The record of the rebate will also be added to the history of the order under Payment Information.

42

9.3 Voiding an Order

Orders which have not yet been sent for settlement may be voided; this will release the reserved funds

on the customer’s card. Some Merchant Service Providers may handle voids differently, so it may be

advisable to process a rebate instead.

Navigate to Sales -> Orders and click the order you wish to void. Clicking Void in the top-right hand

corner will send a void request to Realex Payments.


outcome of the void request.

The record of the void request will also be added to the history of the order under Payment

Information.

43

10 Transaction Logs

In addition to the advanced abandoned cart and incomplete transaction tracking as outlined in section

8, the Realex Payments plugin also provides easy access to comprehensive transaction logs. For more

in-depth troubleshooting, the logs can be consulted for insight into exactly what requests and

responses were sent and received.

10.1 Reviewing Logs

Navigate to Sales -> Realex Payments -> Logs. You can choose the payment method you wish to review

from the dropdown menu.

payment_hpp.log – HPP (Hosted Payment Page)

payment_api.log – API (Remote)

payment_token.log – Tokenisation (RealVault)

exceptions.log – Any issues with a payment will be treated by Magento as an exception, for example,

a payment blocked by 3DSecure configuration settings or one that is declined by the cardholder’s

Issuing Bank.

The most recent activity for the relevant payment method is shown in summary form in the display

window. You may also choose to Download file to review it in more detail.

44

11 Order Clean-Up

If a customer does not finalise an order, it will be held in a ‘Payment Review’ state until such time as

they complete checkout. For example, a customer may forget their 3DSecure password and return to

the order much later once they have recalled or reset it. This plugin offers the ability to determine

the amount of time an order can be held in this state by enabling Order Clean-Up.

11.1 Order Clean-Up Configuration

Order Clean-Up will, on a scheduled basis, check all orders marked as ‘Payment Review’ in Magento.

The following options are available under System -> Configuration -> Sales -> Realex Payments

Clean-Up Enabled: Determines whether Clean-Up is enabled for this particular store.

Order Timeframe: The amount of time, in hours, that an order is allowed to stay open. By default, any

open order that hasn’t completed checkout will be marked as ‘Payment Review’. Setting this field will

determine how long the order can stay in this state before it is closed and marked as ‘Canceled’.

If an open order exceeds the time configured, it will be closed and the stock count of the product(s)

replenished. The customer’s cart will also be cleared. They can view their cancelled order under My

Account -> My Orders; here they will also have the option to reorder the products chosen if they are

in stock.

45

11.2 Configuring the Magento Cron Job

This section of the guide is only relevant if the Magento Cron job is not already scheduled to run on

your server. For most users of Magento Community and Enterprise this will already be setup as a wide

range of Magento’s functionality relies on it.

‘Payment Review’ orders must be checked periodically to ensure that none are older than the order

timeframe that you specified in Section 11.1. To do this, we use Cron. The Magento Cron job must be

scheduled to run as this checks for all other scheduled tasks to be run in Magento.

Note: Magento users should exercise caution when configuring Cron jobs on their server. Please

contact your hosting provider or developer for more information.

The Cron.php file or Cron.sh script located in the Magento root folder must be scheduled to execute.

Please see the following guide on how to do this:

http://www.magentocommerce.com/wiki/1_-_installation_and_configuration/how_to_setup_a_cron_job

For users of cPanel, under the Advanced tab, you will see the Cron jobs option.

Clicking this will take you to the Cron jobs screen; this displays all existing Cron jobs on your server. If

the overall Magento Cron job is already scheduled to run, it will display under Current Cron Jobs.



46

You will also have the option to Add New Cron Job.

You can set the time intervals by minute, hour, day, month or weekday. If you want to set the Magento

Cron job to run every 15 minutes, you can do so by choosing 15 from the minute dropdown menu or

entering ‘*/15’ in the minute field. In the other fields that you are not using, type “*”.

The Command field is where you must enter the path to the Cron command you wish to run. The path

will be determined by your server configuration. In this case we’re going to enter the Cron script path.

47

/bin/sh /path_to_magento/cron.sh

Once you click Add New Cron Job, the scheduled job will then be displayed under Current Cron Jobs.

48

12 Partner Referral Process

This section outlines how partners of Realex Payments can refer a lead.

12.1 Qualifying a referral lead

To qualify for a referral fee, you must inform Realex Payments that you are passing a lead on. You can

do this in the following ways:

Have the merchant sign up via your own co-branded Realex Payments affiliate sign-up page;

this will accredit the lead to your account automatically.

An email/call with the client’s company name and the expected start date for set up (if the

client wants to contact us directly).

An email/call with the client’s contact details and the expected start date for testing (if you

would like Realex Payments to contact the client).

12.2 Merchant Set-Up

If the client requires a call-back, Realex Payments will contact them within 24 hours. Realex Payments

will explain its service, the relationship with Merchant Service Providers and the set-up process.

If the merchant has yet to set up a Merchant Services Agreement, Realex Payments will offer to refer

their contact details on to a Merchant Services Provider for a call back.

A merchant application will typically take up to 10 working days for the bank to process following

receipt of a completed application form. We advise that all clients be prepared to provide the

following when applying for a Merchant Services Agreement:

Valid identification Business plan (if new business)

Proof of address Audited accounts (if existing business)

While the merchant is in the process of setting up their Merchant Services Agreement, Realex

Payments will contact them on a regular basis to ensure there are no questions and that all is

49

proceeding smoothly with the Merchant Service Provider. During this time, Realex Payments will issue

a service agreement to the merchant that must be signed in order to begin testing.

As Realex Payments doesn’t charge any set-up fee, the monthly fee (€29 / £19) is charged once the

test account is activated. For this reason, we advise merchants to apply for their merchant account

and to ensure their developer is ready to begin testing before they set up their Realex Payments

account.

Upon receipt of the signed set-up forms, Realex Payments will activate the merchant's test account

within 24 hours.

50

13 Appendix

Appendix 1.0: e-Commerce Indicator (ECI) Results

ECI VALUE

Visa /

Amex

MasterCard /

Maestro Interpretation

Liability Shift?

(additional chargeback protection)

5 2 Transaction fully authenticated. Yes

6 1

Cardholder was not enrolled for

3DSecure or the authentication

attempt has been acknowledged.

Yes

7 0 Transaction not 3DSecure. No

Appendix 2.0: Security Code (CVN / CVC / CVV) and Address

Verification Service (AVS) Results

AVS VALUE Interpretation

M Matched

N Not matched

I Problem with check

U Unable to check (not certified etc.)

P Partial match

realex payments magento 1 extension configuration guide€¦ · 2.2 hosted payment page ‘redirect...

Documents