PaybyFinance Magento Plugin


Full text


Hitachi Capital

Contact Name Contact Number E-Mail Address

<Firstname Surname>

PaybyFinance Team -

Healthy Website

Contact Name Contact Number E-Mail Address

<Firstname Surname> 0141 249 0641

PaybyFinance Magento Plugin



Table of Contents

Overview... 3 Magento Compatibility ... 3 Latest Version ... 3 Features ... 3 Server Environment ... 4 Prerequisite ... 4 Installation Instructions ... 4

Backup Your Data ... 4

Install ... 4

Use Magento Connect ... 4

Manual installation using Pear... 4

Refresh the cache ... 4

Enable PaybyFinance Logging Function ... 4

How to configure services ... 5

Configure services ... 5

Add a new service ... 5

Click the Button 'Add Service' on the Top Right Corner ... 6

Configure the service for your site. ... 6

Field's that make up a service ... 7

Saving the Service ... 8

Product Pages ... 8

Basket Page ... 9

Checkout ... 9

Enterprise Idev OneStepCheckout ... 10

Customising Look And Feel ... 11

Billing country message ... 11

Grand Total ... 11

Finance Options ... 12



Testing ... 13

Compliance Review ... 14

Known Issues ... 14

Displaying vat and calculating finance ... 14

Deposits ... 15

Order Success Transactional email ... 15

Minimum deposit warning / whitespace issue ... 15

Magento 1.9.1additional check for the cookie ... 16




This extension provides integration with Hitachi Capital’s PaybyFinance online finance application system. You will need to have an existing relationship with Hitachi Capital to provide finance for your customers.

If you do not have an existing relationship with Hitachi Capital, please complete the form at: and select ‘Retailer Finance’ from the dropdown list. If you already have a relationship with Hitachi Capital but don’t yet use PaybyFinance, please contact your Hitachi relationship manager.

This extension supports Sage Pay (Ebizmarts), Paypal Express and Datacash Payment Gateways as well as OnePage Checkout and is compatible with Magento Community 1.7, 1.8 and 1.9 and Magento Enterprise 1.13 and 1.14.

Magento Compatibility

 Magento Community (`1.7.*`, `1.8.*`, `1.9.*`)

 Magento Enterprise Edition (`1.13.*`, `1.14.*`)

Latest Version

The Latest version of this extension is freely available from Magento Connect


 Multi-sites/store environment  Discount codes

 One Step Checkout Version 4  Webshopapps Matrix Rates

 Sage Pay Suite PRO v3.0.8 by Ebizmarts: Sage Pay Suite [Frontend – SERVER Integration]

 Sage Pay Suite Community Edition v3.0.19.1 by Ebizmarts: Sage Pay Suite [Frontend – SERVER


 PayPal Express Checkout


4 Note: If your Magento eCommerce site is not compatible with the above list, please contact your

Hitachi account manager.

Server Environment


Please ensure that the following TLS1.2 cipher is available on your server for secure communication with the PaybyFinance Server, a finance application cannot be processed without this.


Installation Instructions

Backup Your Data

It is recomended that you first install this extension on a staging environment and backup your store database and web directory.


Use Magento Connect

The extension is freely available from Magento Connect

Manual installation using Pear

You can install the plugin using pear, the extension key is on the Magento Connect page.

Refresh the cache

After installing the extension, you will need to clear the cache by logging in and navigating to System ->Cache Management, select refresh for the All Cache select box. You will then need to logout and log-back in (it is important to do this in order to reset the permissions for the user).

Enable PaybyFinance Logging Function


5 magento root/var/log/paybyfinance

This extension also logs all data communications inside the database in the event all server logs are cleared and a finance application still needs to be examined.

How to configure services

Please contact your Hitachi relationship manager to agree the services you can use on your site.

Configure services

A service describes how the customer will pay back the finance. It is used to calculate monthly instalments and defines under what conditions the finance service will be available for the product or the shopping basket. An eTailer can have more than one service.

Add a new service

To add a new service, in the admin menu, select PaybyFinance > Services > Add Service. Fill in the service details and click Save. Repeat this for all services.

Login to your Magento Admin Panel. Navigate to 'Pay By Finance' → 'Service'



Click the Button 'Add Service' on the Top Right Corner



Fields that make up a service

Type (ID): numeric, example: 31

Name: string, for example "IFC12" or "IBC36" APR: numeric, for example 6

Term: numeric, for example 12 Defer term: numeric, example: 6 Option term: numeric, example: 0

Deposit: percentage, for example: 10

Fee: price, example: 0

Minimum amount: price, example: 500

Multiplier: float (8 digit after the floating point), example: 0.09168000 RPM: float, example: 0.0


 For Service Type 31 – Interest Bearing Credit - You HAVE to configure the 'Rpm' for this service type, otherwise the finance application will fail.

 For Service Type 32 - Internet Free Credit - You do not need to configure 'Rpm' for this type of services.



Saving the Service

You can save the service by click the 'Save Service' from top right corner.

Product Pages

If the finance widget does not appear by default on your sites product pages, the following instruction will provide a guide for how to make it visible.

Open the following file, if it does not exist, create it:

app/design/frontend/{yourpackage}/{yourtheme}/layout/local.xml And add this or edit the file with the following:

<?xml version="1.0"?> <layout>

<catalog_product_view> <reference name="content">

<block type="paybyfinance/selector" name="paybyfinance.selector" as="pbfselector" template="paybyfinance/selector.phtml"> </block> </reference> </catalog_product_view> </layout>


9 Open the following file:


If the file is not in the folder of your theme, then copy it from this location:


Add this line of code:

<?php echo $this->getChildHtml('paybyfinance.selector') ?>

To only display the finance widget on product pages where finance is available, we provide a helper method which returns with a boolean type:

<?php if Mage::helper('paybyfinance')->isProductEligible($_product): ?> <?php echo $this->getChildHtml('paybyfinance.selector') ?>

<?php endif; ?>

Basket Page

Open the file:

app/design/frontend/{yourpackage}/{yourtheme}/templates/checkout/cart.phtml And place the following code anywhere you want to display the finance selector widget:

<?php echo $this->getChildHtml('cartpbfselector'); ?>

In the rwd template, this step is not required as the extension pushes the widget to the `shopping.cart.table.after` reference.

Be aware, the default `app/design/frontend/base/default/templates/checkout/cart.phtml` template is overridden in favour of automatically adding the widget to the cart.


How to place the finance selector on the checkout pages if it's not appearing by default. The extension provides block by default on the right sidebar, this following will show how to add it to those

templates where it's not appearing by default. Open the following file, if it does not exist, create it:

app/design/frontend/{yourpackage}/{yourtheme}/layout/local.xml And add this or edit the file with the following:

<?xml version="1.0"?> <layout>


10 <checkout_onepage_index>

<reference name="right">

<block type="paybyfinance/selector" name="paybyfinance.selector" as="pbfselector" template="paybyfinance/selector.phtml">

</block> </reference>

</checkout_onepage_index> </layout>

Note the actual XML could be different as different layout handles or section names might appear in a custom template. Regarding the layout handle or reference name, consult your trusted Magento developer.

Enterprise Idev OneStepCheckout

Configuring the module to work with OneStepCheckout requires two small changes to the code. Add this block to the ./app/design/frontend/base/default/layout/onestepcheckout.xml layout xml here:

<layout version="0.1.0">

<onestepcheckout_index_index> <reference name="content">

<block type="onestepcheckout/checkout" name="onestepcheckout.checkout" template="onestepcheckout/checkout.phtml">


<block type="paybyfinance/selector" name="paybyfinance.selector" as="pbfselector" template="paybyfinance/selector.phtml" />

</block> </reference>

</onestepcheckout_index_index> </layout>

Add this line of code where you would like the paybyfinance block to be displayed: <?php echo $this->getChildHtml('pbfselector'); ?>

For example, to have it below the payment method option you could add it between these two lines (approx line 185 at time of writing this instruction):

<?php echo $this->getChildHtml('choose-payment-method'); ?> <?php echo $this->getChildHtml('pbfselector'); ?>



Customising Look And Feel

Billing country message

The billing country message by default is placed on the top of the Billing Information step on the checkout screen:

If you are paying by finance then goods MUST be delivered to your billing address. Products cannot be delivered outside of the UK.

To modify the position of this text, simply create a containing div tag anywhere in your template file, it's location by default is:


If the file does not exist, copy it from the base/default template and modify it in your shop's template. Add the following code anywhere:

Copy skin/frontend/base/default/js/paybyfinance/checkout.js to your template's skin folder to the below path:


And run a search and replace from: `$('co-billing-form')` to: `$('paybyfinance-billing-country-message')`

Using vim this can be achieved with the following command:

vim :%s/\$('co-billing-form')/\$('paybyfinance-billing-country-message')/g

Grand Total

Be sure to modify the templates to add an asterisk to the "Grand Totals" like this to both the basket and the order reviews:

SUBTOTAL £1,000.00


* GRAND TOTAL £100.50

* Grand total is the amount to be paid by credit/debit card

This can be done in the templates and we have provided sample files doing this: app/design/frontend/base/default/template/checkout/cart/totals.phtml


12 app/design/frontend/base/default/template/checkout/onepage/review/info.phtml app/design/frontend/base/default/template/checkout/onepage/review/totals.phtml app/design/frontend/rwd/default/template/checkout/onepage/review/info.phtml

Finance Options

To Edit the CMS page that the extension created, it's called `finance-options`, go to CMS, Pages, Manage Content and find finance-options here. Change the text as required for the services that you have set up.

Place a link to this page in your footer. This is required for compliance reason.



PBF Post Data

How to add a non-mandatory field to the PBF post request.

To preserve any changes you make to the extension so that they are not lost when the extension is upgraded you will need to create an extension override and re write this class:

HC_PayByFinance_Model_Post::setQuoteData() in your own extension.

You will then be able to add any field to the $fields array.


It is recommended that you test all the services that have been set up using the different payment gateways and shipping methods that your site uses before presenting your staging site for a compliance review.

During integration testing, an e-tailer will wish to guarantee the loan decision. By entering the following data as the applicant’s surname, the corresponding decision will always be returned.



Decision Code

TESTDO Decline Override TR05

TESTPD Policy Decline TD03

TESTSC Score Decline TD02

TESTDD Decline TD01

TESTFR Fraud Refer TR04


TESTCA Conditionally Accept TR02

TESTPA Provisionally Accept TR01

TESTAA Accept TA01



Compliance Review

Wording: Credit is provided by Hitachi Capital Consumer Finance, a division of Hitachi Capital (UK) PLC authorised and regulated by the Financial Conduct Authority.

All sites must go through a compliance review prior to being given live IDs for use in production environments.

Once your plugin has been successfully set up and tested please contact your Hitachi relationship manager to request a compliance review.

A compliance review takes 10 working days to complete and may raise recommendations regarding the appearance of how finance is presented to the end customer.

Every attempt has been made in producing this plugin to minimise any revisions that may be required to sign off your site for processing finance applications.

Known Issues

Displaying vat and calculating finance

If your shop is configured to display prices ex vat then finance is calculating on the ex vat subtotals. To resolve this issue:

Add a line to the fetch function in:

“app\code\local\HC\PayByFinance\Model\Sales\Quote\Totalcost.php” Change this: $amount = $address->getQuote()->getSubtotal() + $address->getShippingAmount() + $address->getDiscountAmount() - $address->getGiftCardsAmount(); To this: $amount = $address->getQuote()->getSubtotal() + $address->getTaxAmount() + $address->getShippingAmount() + $address->getDiscountAmount() - $address->getGiftCardsAmount();




Deposits can be for either a fixed amount, e.g. 25% or a range from 0-60%.

The facility to enter a min/max deposit and specify what interval there should be would give eTailers more flexibility over the user experience.

Order Success Transactional email

When an order is placed Magento triggers the transactional email and then redirects the user to PaybyFinance at which point the application can fail or be abandoned.

If the application fails or is deferred, PBF will send a further email. The user experience would be enhanced if the order success transactional email made a comment that the order is placed and a separate email will be sent regarding the status of the finance application.


16 Depending on what template you are using there may be an issue with the minimum deposit /

minimum loan amount error message not having white space between it and the service toggle switch box. This issue needs to be resolved on the individual eTailer template files.

Magento 1.9.1additional check for the cookie

In Magento 1.9.1 (and EE there's an additional check for the cookie which is deleting the cookie when the cookie domain is the same and transferred with Access-Control-Request-Headers. Please comment out the following lines in Magento 1.9.1:

app/code/core/Mage/Core/Model/Session/Abstract/Varien.php line 135-157

If you wish to implement a fix for this issue yourself you can see an example of how Ebizmarts fixed this in their SagePay extension:


If in Magento, the logging is enabled in System -> Configuration -> Developer -> Log Settings, then the extension will log each request to the configured var/log/ folder's paybyfinance subfolder.

The paybyfinance-log.log contains general logging, such as errors generated by a software bug. paybyfinance-post.log file contains the POST requests made to the Hitachi Capital servers, while the paybyfinance-notification.log will contain each notification requests made by the Hitachi Capital servers to the e-tailer website.

If you need help troubleshooting finance applications please forward these log files to your Hitachi relationship manager.

N.B. In the event that system logs are not available then the extension logs the same data to the database in the paybyfinance_log table.





Related subjects :