PaybyFinance Magento Plugin Installation Instructions and User Guide Hitachi Capital Contact Name Contact Number E-Mail Address <Firstname Surname> Firstname.surname@hitachicapital.co.uk PaybyFinance Team - paybyfinance@hitachicapital.co.uk Healthy Website Contact Name Contact Number E-Mail Address <Firstname Surname> 0141 249 0641 support@healthywebsites.co.uk
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 1 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 PBF Post Data... 13
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 Troubleshooting... 16 2
Overview 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: http://www.hitachicapital.co.uk/contact-us 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.*`) 3 Latest Version The Latest version of this extension is freely available from Magento Connect Features 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 Integration] PayPal Express Checkout DataCash by ontap:: Hosted Card Capture && API
Note: If your Magento ecommerce site is not compatible with the above list, please contact your Hitachi account manager. Server Environment Prerequisite 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. TLS_RSA_WITH_RC4_128_SHA 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. Install 4 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 logback in (it is important to do this in order to reset the permissions for the user). Enable PaybyFinance Logging Function By enabling the logging function, all requests to and from PaybyFiannce will be logged under:
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' 5
Click the Button 'Add Service' on the Top Right Corner Configure the service for your site. 6
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 Note 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. 7
Saving the Service You can save the service by click the 'Save Service' from top right corner. 8 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>
Open the following file: app/design/frontend/{yourpackage}/{yourtheme}/template/catalog/product/view.phtml If the file is not in the folder of your theme, then copy it from this location: app/design/frontend/base/default/template/catalog/product/view.phtml 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 9 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. Checkout 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>
<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');?> 10
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: frontend/{package}/{theme}/template/persistent/checkout/onepage/billing.phtml 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: skin/frontend/{package}/{theme}/js/paybyfinance/checkout.js And run a search and replace from: `$('co-billing-form')` to: `$('paybyfinance-billing-countrymessage')` Using vim this can be achieved with the following command: vim :%s/\$('co-billing-form')/\$('paybyfinance-billing-country-message')/g 11 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 SHIPPING & HANDLING (FLAT RATE - FIXED) 5.00 FINANCED AMOUNT - 904.50 * 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
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 12 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. Testing 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. 13 Surname Decision Decision Code TESTDO Decline Override TR05 TESTPD Policy Decline TD03 TESTSC Score Decline TD02 TESTDD Decline TD01 TESTFR Fraud Refer TR04 TESTRR Refer TR03 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 14 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: Change this: app\code\local\hc\paybyfinance\model\sales\quote\totalcost.php $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 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. Minimum deposit warning / whitespace issue 15
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 1.14.1.0) 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 http://www.myscreenshots.co.uk/sandor/selection_2015-04-09_aed3.png 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: https://github.com/ebizmarts/sage-pay-suitece/commit/93a6db9f5779dd9a7ff7b06e2f6fcb2a43cb1248 16 Troubleshooting 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.