Version 3.6.1 This document explains how to update an existing install of our Magento extension. Published: 3 August 2017
Introduction This Magento Community Edition extension allows you to seamlessly integrate with Secure Trading to process payments on your online store. This document outlines how to upgrade from existing install of the extension to the latest version of 3.6. As part of maintaining and improving the Magento extension, Secure Trading will release updates, periodically. As such, we recommend regularly checking the Magento Connect Manager for new versions of the extension. It is important to follow the procedures outlined in this document to ensure a smooth transition to the new extension. All new versions of the extension will be available on the Magento Connect website: http://www.magentocommerce.com/magento-connect/securetrading.html Click Follow this extension to be notified when the extension is updated. We recommend against using old versions of Secure Trading extensions for Magento. Reasons to stay up-to-date: Supports the latest Secure Trading features. Supports the latest versions of Magento. Improved integration between MyST and the Magento admin interface. Table of Contents 1 Release notes... 3 2 Pre-Requisites... 4 3 Which version am I on?... 5 4 Updating extension for Payment Pages... 6 5 Updating extension for Web Services... 9 6 Updating extension for STAPI client... 10 7 Migrating from legacy extension v2.x or earlier... 11 8 Further Information and Support... 12 9 Appendix... 13 Secure Trading Limited 2017 3 August 2017 Page 2 / 21
1 Release notes 1.1 Version 3.6.0a Payment Pages Version 2 - Version 2 of the Secure Trading Payment Pages is now supported. This allows you to display your own HTML on the Payment Pages. See the Payment Pages documentation (linked below) for more information. Payment Pages Redirects/Notifications New Payment Pages functionality is used so that merchants no longer need to configure MyST redirects and notifications manually. Existing merchants must disable their existing redirects and notifications immediately after upgrading to this module. Payment Pages Details Page Redirection - The Redirect payment method can now be configured to take customers directly to the details page of the Payment Pages from the Magento checkout. This bypasses the payment type selection page of the Payment Pages. The module can also be configured to either capture the payment type from the Magneto checkout or to make the Payment Pages automatically determine the payment type once the customer is on the Payment Pages. Virtual Product Support - Virtual products are now supported on the Payment Pages. Admin Configuration - The payment method configuration has been redesigned and simplified. No functionality has been removed. ST API Removal - The ST API client is no longer supported (the Secure Trading Web Services are still supported, providing an easier way to integrate with the Secure Trading gateway). Bugfix: SOFORT cron - When the SOFORT cron was run, all orders examined by the cron were updated with an empty comment in the order history if none of the orders were SOFORT transactions. Bugfix: multishipping checkout/direct payment method - 3 or more addresses in the multishipping checkout now work with the Secure Trading Direct payment method. 1.2 Version 3.6.1 Improved PHP support - The extension has been updated to support PHP versions 5.3.10-5.6.15 (tested up to 5.5.15). Secure Trading Limited 2017 3 August 2017 Page 3 / 21
2 Pre-Requisites 2.1 Back-Up Your System Before updating the extension, we recommend that you perform a full back-up of the existing extension files installed on your system, including your database. Magento provides tools to assist you: Go to System > Tools > Backups. Back-up files are compressed using the.gz format and are stored in the var/backups directory in your Magento file system. 2.2 Test Update on your Staging System We recommend first installing the extension update on your staging system, before deploying the new version of the extension on your live system. Please perform the following on your staging system, using your test site reference: Process a number of transactions on your staging system using the existing configuration. Upgrade to the new extension. Update transactions that you processed before the extension was upgraded (to ensure correct behaviour). Process a number of new transactions on your staging system, using the upgraded extension. Update the new transactions (to ensure correct behaviour). 2.3 If you haven t already, create a Web Services user (recommended) If you are using our Payment Pages, we recommend creating a Web Services user. You can then update the Magento admin interface to include this Web Services username and password. This will allow you to directly manage your transactions through the Magento admin interface. Web Services will work behind-the-scenes to update transactions on your Secure Trading account automatically. It only takes a few minutes to configure. See section 9.1 for instructions. Secure Trading Limited 2017 3 August 2017 Page 4 / 21
3 Which version am I on? Navigate to the following location within the Magento admin interface: System > Configuration > Payment Method If the Module Version number is shown (as above), then your extension can be updated in place to the latest version by following the steps outlined in this document. If the version number is not shown, then this extension cannot be updated directly. You will need to follow the steps outlined in section 7. 3.1 What procedure should I follow? Please perform the pre-requisites outlined in section 2 before proceeding. The steps to be performed next depend on the version you currently have installed. If you are unsure, refer to the information above for help on finding the version number. 3.1.1 Payment Pages Existing install Section reference Versions 3.0.0-3.6.0 See section 4.1 Versions 1.x or 2.x See section 7 3.1.2 Web Services Existing install Section reference Versions 3.0.0-3.6.0 See section 5.1 Versions 1.x or 2.x See section 7 3.1.3 STAPI Client See section 6. Secure Trading Limited 2017 3 August 2017 Page 5 / 21
4 Updating extension for Payment Pages 4.1 Updating from v3.0.0 - v3.6.0 Please follow these steps before upgrading your extension to version 3.6.1. 4.1.1 Site security You will need to notify the Secure Trading Support team by email (support@securetrading.com) of the site reference being used and that you need to update your site security hash to use the following fields in this order: currencyiso3a mainamount sitereference settlestatus settleduedate authmethod paypaladdressoverride strequiredfields version stprofile ruleidentifier stdefaultprofile successfulurlredirect declinedurlredirect successfulurlnotification declinedurlnotification merchantemail allurlnotification stextraurlnotifyfields stextraurlredirectfields orderreference accounttypedescription order_increment_ids order_increment_id PASSWORD It is imperative that you contact Support to update your site security configuration as described above; otherwise your site will no longer be able to process payments. If there is a problem with your site security hash, your customers will be displayed an invalid details error on the Payment Pages. Secure Trading Limited 2017 3 August 2017 Page 6 / 21
4.1.2 Upgrading to Payment Pages version 2 Version 3.6.0 of the extension introduced support for the new version 2 of the Payment Pages, which allows for more advanced customisation through the use of custom HTML and CSS: If you are upgrading from version 3.5.2 or earlier, you will already be configured to use Payment Pages version 1, which is still supported in this extension. You can proceed to section 4.1.3 to complete the update. Switching to Payment Pages version 2 with this update requires additional steps to be performed. Continue reading sections 4.1.2.1, 4.1.2.2 and 4.1.3. 4.1.2.1 Disabling previously-configured rules in the Notifications and Rule manager interface Previous versions of the extension required you to use MyST to create and enable notifications and redirects during first-time setup. Notifications are responsible for updating order information in your Magento store after payment has been completed. Redirects are used to redirect the customer back to your store after processing a transaction on our hosted Payment Pages. Version 3.6 performs these tasks automatically without the need for additional configuration in MyST, so you will need to disable pre-existing notifications and redirects for your Magento store to avoid any conflicts. To disable notifications, sign in to MyST and click Notifications from the left side menu. Then you can deselect the checkboxes in the Active column for previously-configured Magento store notifications. In a similar manner, you can disable redirects by clicking Rule manager from the left side menu and deselecting the checkboxes in the Active column for previously-configured Magento store redirects. 4.1.2.2 Customisation In Payment Pages version 2, we have improved how you can customise the appearance and layout of your pages, allowing for greater flexibility. New features supported: Use custom HTML to perform advanced customisation on the payment pages. The ability to implement different stprofiles, which allow you to switch between different layouts on your Payment Pages. If you have already implemented custom CSS on your Payment Pages, you will need to refer to our customisation documentation to make changes to your CSS to support version 2. Secure Trading Limited 2017 3 August 2017 Page 7 / 21
4.1.3 Performing the update Navigate to the Magento Connect Manager. When the extension is highlighted in yellow, a new version is available for install. To perform the update, select the version you would like to install from the drop-down box and click Commit Changes. Secure Trading Limited 2017 3 August 2017 Page 8 / 21
5 Updating extension for Web Services 5.1 Updating from v3.0.0 - v3.6.0 Navigate to the Magento Connect Manager. When the extension is highlighted in yellow, a new version is available for install. To perform the update, select the version you would like to install from the drop-down box and click Commit Changes. Secure Trading Limited 2017 3 August 2017 Page 9 / 21
6 Updating extension for STAPI client The STAPI client has been discontinued from version 3.6.0 In order to continue using this extension, you will need to switch to our Web Services connection to allow the extension to communicate using our APIs. Please ensure you follow these steps during installation: 6.1 Create a Web Services username and password If you have not already done so, you will need to sign into MyST and create a Web Services username and password. This should only take a few minutes. See section 9.1 for instructions. 6.2 Deactivate your STAPI client Before performing the update, turn off your STAPI client. This will no longer work after the update. 6.3 Install the extension Navigate to the Magento Connect Manager. When the extension is highlighted in yellow, a new version is available for install. To perform the update, select the version you would like to install from the drop-down box and click Commit Changes. 6.4 Reconfigure the extension after the update After you have performed the update, you will need to navigate to your configuration settings and enter your Web Services username and password, as documented in the Magento Extension User Guide for Web Services (see section 8.2). Secure Trading Limited 2017 3 August 2017 Page 10 / 21
7 Migrating from legacy extension v2.x or earlier You cannot directly update from legacy versions of the extension. To get the latest version: 1. Comment out the necessary lines of XML within your install directories by following the relevant instructions for your installation: For Payment Pages, see section 9.2. For Web Services, see section 9.3. For STAPI, see section 9.4. 2. Clear your Magento cache: a. Log in to the admin interface. b. Go to System > Cache Management. c. Click on the Flush Magento Cache button. 3. Follow the steps outlined in the Magento Extension User Guides and install the new extension alongside the legacy version. See section 8.2 for URLs for these documents. Once you have installed this extension, future extension updates can be installed using the Magento Connect Manager. We strongly recommend against uninstalling the legacy extension. Doing so will prevent you from viewing old orders placed using the legacy extension. Secure Trading Limited 2017 3 August 2017 Page 11 / 21
8 Further Information and Support This section provides useful information with regards to documentation and support for your Secure Trading solution. 8.1 Secure Trading Support If you require any assistance, please contact Secure Trading support. When contacting our Support team, please include the following logs: <Magento Directory>/var/log/securetrading.log <Magento Directory>/var/log/securetrading_api.log Please also send us any server access/error logs along with as much information as you can to assist us in troubleshooting your problem. Method Details Telephone +44 (0) 1248 672 050 Fax +44 (0) 1248 672 099 Email support@securetrading.com Website http://www.securetrading.com/support/support.html 8.2 Useful Documents Magento Extension 3.6 User Guide: Payment Pages http://www.securetrading.com/files/documentation/magento-paymentpages-user-guide-3-6.pdf Magento Extension 3.6 User Guide: Web Services http://www.securetrading.com/files/documentation/magento-api-user-guide-3-6.pdf Payment Pages version 2 Customisation http://www.securetrading.com/paymentpages/customisation.html Secure Trading Limited 2017 3 August 2017 Page 12 / 21
9 Appendix 9.1 Creating Web Services Username In order to use Web Services on your Secure Trading account, a user account with the role of Webservices must be assigned to your site(s) using MyST. Sign into your MyST account and click Add new username from the left side menu and fill out the form as follows: Username - Valid email address hosted on your server. Password - Enter a password. Role - Select Webservices. Valid IP/network(s) - Enter your system s IP or range of IPs. Multiple IP addresses can be separated with either a semicolon (;) or a comma (,). Role if invalid IP - Set this to Prevent login. Under the Manage sites tab, select the site reference you use on your Magento store. Then click Save. Once you have installed the new extension, you can go to the configuration settings and enter the Web Services username and password (this is explained in the relevant Magento user guide; see section 8.2). For more info on managing users on your Secure Trading site, please refer to the MyST User Guide All Secure Trading documents can be found on our website. Secure Trading Limited 2017 3 August 2017 Page 13 / 21
9.2 Modifying SecureTrading_PPages.xml If you are migrating from an old version of the extension (as described in section 7), you will need to comment out the following lines within www/app/etc/modules/securetrading_ppages.xml inside your install directories (as shown below in bold): <?xml version="1.0"?> <config> <modules> <SecureTrading_PPages> <version>2.5.x</version> </SecureTrading_PPages> </modules> <global> <!-- Register helpers <helpers> <PPages> <class>securetrading_ppages_helper</class> </PPages> </helpers> <!-- Register models <models> <PPages> <class>securetrading_ppages_model</class> </PPages> <!-- Overridden multishipping model <checkout> <type_multishipping>securetrading_ppages_model_type_multishipping</type_multis hipping> </checkout> </models> <!-- Register blocks <blocks> <PPages><class>SecureTrading_PPages_Block</class></PPages> </blocks> <!-- Rewrite admin/sales_order_create/save controller to use our own implementation. <unique_ppages_text_here_can_be_anything> <from><![cdata[#^/admin/sales_order_create/save#]]></from> <to>securetradingppages/create/save</to> </unique_ppages_text_here_can_be_anything> </global> <!-- Controllers <frontend> <routers> <!-- Create standard controller <ppages> <use>standard</use> <args> <module>securetrading_ppages</module> <frontname>securetrading</frontname> Secure Trading Limited 2017 3 August 2017 Page 14 / 21
</args> </ppages> <!-- Overridde core multishipping controller <checkout> <args> <modules> <SecureTrading_PPages before="mage_checkout">securetrading_ppages</securetrading_ppages> </modules> </args> </checkout> </routers> </frontend> <admin> <routers> <!-- Create admin controller <unique_text_admin_router_ppages> <use>admin</use> <args> <module>securetrading_ppages</module> <frontname>securetradingppages</frontname> </args> </unique_text_admin_router_ppages> </routers> </admin> <!-- Set default config values <default> <payment> <PPages_standard> <model>ppages/standard</model> <title>securetrading Payment Pages</title> <sort_order>1</sort_order> <payment_action>auth_capture</payment_action> <allowspecific>0</allowspecific> <!-- All allowed countries </PPages_standard> </payment> </default> </config> Secure Trading Limited 2017 3 August 2017 Page 15 / 21
9.3 Modifying SecureTrading_WebServices.xml If you are migrating from an old version of the extension (as described in section 7), you will need to comment out the following lines within www/app/code/local/securetrading/webservices/etc/config.xml inside your install directories (as shown below in bold): <?xml version="1.0"?> <config> <modules> <SecureTrading_WebServices> <version>2</version> </SecureTrading_WebServices> </modules> <global> <!-- Register helpers <helpers> <WebServices> <class>securetrading_webservices_helper</class> </WebServices> </helpers> <!-- Register models <models> <WebServices> <class>securetrading_webservices_model</class> </WebServices> <!-- Overridden multishipping model <checkout> <type_multishipping>securetrading_webservices_model_type_multishipping</type_m ultishipping> </checkout> <!-- Overriden Mage_CatalogInventory_Model_Observer <cataloginventory> <observer>securetrading_webservices_model_cataloginventory_observer</observer> </cataloginventory> <!-- Overridden Mage_Sales_Model_Order_Payment_Transaction <sales> <order_payment_transaction>securetrading_webservices_model_order_payment_trans action</order_payment_transaction> </sales> </models> <!-- Register blocks <blocks> <WebServices><class>SecureTrading_WebServices_Block</class></WebServices> <!-- Override Mage_Payment_Block_Info <payment> Secure Trading Limited 2017 3 August 2017 Page 16 / 21
<info>securetrading_webservices_block_payment_info</info> </payment> </blocks> <!-- Register observer <events> <!-- New event. Class extends core observer and runs Mage_CatalogInventory_Model_Observer::subtractQuoteInventory() when event dispatched. <securetrading_webservices_transaction_successful> <observers> <webservices_cataloginventory_observer> <class>securetrading_webservices_model_cataloginventory_observer</class> <method>subtractquoteinventorymanual</method> </webservices_cataloginventory_observer> </observers> </securetrading_webservices_transaction_successful> <!-- Overridden event. Activates a quote. <checkout_submit_all_after> <observers> <webservices_observer> <class>securetrading_webservices_model_observer</class> <method>setactivequote</method> </webservices_observer> </observers> </checkout_submit_all_after> </events> <!-- Rewrite admin/sales_order_create/save controller to use our own implementation. <unique_text_here_can_be_anything> <from><![cdata[#^/admin/sales_order_create/save#]]></from> <to>securetradingwebservices/create/save</to> </unique_text_here_can_be_anything> </global> <!-- Controllers <frontend> <routers> <!-- Create standard controller <webservices> <use>standard</use> <args> <module>securetrading_webservices</module> <frontname>securetradingwebservices</frontname> </args> </webservices> <!-- Overridde core multishipping controller <checkout> Secure Trading Limited 2017 3 August 2017 Page 17 / 21
<args> <modules> <SecureTrading_WebServices before="mage_checkout">securetrading_webservices</securetrading_webservices> </modules> </args> </checkout> </routers> </frontend> <admin> <routers> <!-- Create admin controller <unique_text_admin_router> <use>admin</use> <args> <module>securetrading_webservices</module> <frontname>securetradingwebservices</frontname> </args> </unique_text_admin_router> </routers> </admin> <!-- Register adminhtml observer <adminhtml> <events> <payment_info_block_prepare_specific_information> <observers> <preparespecific> <type>model</type> <class>securetrading_webservices_model_observer</class> <method>paymentinfoblockpreparespecificinformation</method> </preparespecific> </observers> </payment_info_block_prepare_specific_information> </events> </adminhtml> <!-- Set default config values <default> <payment> <WebServices_standard> <model>webservices/standard</model> <title>securetrading WebServices</title> <sort_order>1</sort_order> <payment_action>auth_capture</payment_action> <allowspecific>0</allowspecific> <!-- All allowed countries <risk_decision>0</risk_decision> </WebServices_standard> </payment> </default> </config> Secure Trading Limited 2017 3 August 2017 Page 18 / 21
9.4 Modifying SecureTrading_STAPI.xml If you are migrating from an old version of the extension (as described in section 7), you will need to comment out the following lines within www/app/code/local/securetrading/stapi/etc/config.xml inside your install directories (as shown below in bold): <?xml version="1.0"?> <config> <modules> <SecureTrading_STAPI> <version>2.5.0</version> </SecureTrading_STAPI> </modules> <global> <!-- Register helpers <helpers> <STAPI> <class>securetrading_stapi_helper</class> </STAPI> </helpers> <!-- Register models <models> <STAPI> <class>securetrading_stapi_model</class> </STAPI> <!-- Overridden multishipping model <checkout> <type_multishipping>securetrading_stapi_model_type_multishipping</type_multish ipping> </checkout> <!-- Overriden Mage_CatalogInventory_Model_Observer <cataloginventory> <observer>securetrading_stapi_model_cataloginventory_observer</observer> </cataloginventory> <!-- Overridden Mage_Sales_Model_Order_Payment_Transaction <sales> <order_payment_transaction>securetrading_stapi_model_order_payment_transaction </order_payment_transaction> </sales> </models> <!-- Register blocks <blocks> <STAPI><class>SecureTrading_STAPI_Block</class></STAPI> <!-- Override Mage_Payment_Block_Info Secure Trading Limited 2017 3 August 2017 Page 19 / 21
<payment> <info>securetrading_stapi_block_payment_info</info> </payment> </blocks> <!-- Register observer <events> <!-- New event. Class extends core observer and runs Mage_CatalogInventory_Model_Observer::subtractQuoteInventory() when event dispatched. <securetrading_stapi_transaction_successful> <observers> <stapi_cataloginventory_observer> <class>securetrading_stapi_model_cataloginventory_observer</class> <method>subtractquoteinventorymanual</method> </stapi_cataloginventory_observer> </observers> </securetrading_stapi_transaction_successful> <!-- Overridden event. Activates a quote. <checkout_submit_all_after> <observers> <stapi_observer> <class>securetrading_stapi_model_observer</class> <method>setactivequote</method> </stapi_observer> </observers> </checkout_submit_all_after> </events> <!-- Rewrite admin/sales_order_create/save controller to use our own implementation. <unique_text_here_can_be_anything> <from><![cdata[#^/admin/sales_order_create/save#]]></from> <to>st/create/save</to> </unique_text_here_can_be_anything> </global> <!-- Controllers <frontend> <routers> <!-- Create standard controller <stapi> <use>standard</use> <args> <module>securetrading_stapi</module> <frontname>securetradingstapi</frontname> </args> </stapi> <!-- Overridde core multishipping controller Secure Trading Limited 2017 3 August 2017 Page 20 / 21
<checkout> <args> <modules> <SecureTrading_STAPI before="mage_checkout">securetrading_stapi</securetrading_stapi> </modules> </args> </checkout> </routers> </frontend> <admin> <routers> <!-- Create admin controller <unique_text_admin_router> <use>admin</use> <args> <module>securetrading_stapi</module> <frontname>st</frontname> </args> </unique_text_admin_router> </routers> </admin> <!-- Register adminhtml observer <adminhtml> <events> <payment_info_block_prepare_specific_information> <observers> <preparespecific> <type>model</type> <class>securetrading_stapi_model_observer</class> <method>paymentinfoblockpreparespecificinformation</method> </preparespecific> </observers> </payment_info_block_prepare_specific_information> </events> </adminhtml> <!-- Set default config values <default> <payment> <STAPI_standard> <model>stapi/standard</model> <title>securetrading API</title> <sort_order>1</sort_order> <payment_action>auth_capture</payment_action> <allowspecific>0</allowspecific> <!-- All allowed countries <risk_decision>0</risk_decision> </STAPI_standard> </payment> </default> </config> Secure Trading Limited 2017 3 August 2017 Page 21 / 21