Masterpass Magento Plug-In Installation Guide Enterprise Edition Versions 1.13.1 and 1.14.1 27 October 2016 MTIG
Contents Contents Chapter 1: Introduction... 3 Purpose of This Guide... 4 Audience... 4 Assumptions... 4 Prerequisites...4 Chapter 2: Masterpass Portal and Mastercard Developers Registration... 6 Masterpass Portal and Mastercard Developers Registration... 7 Chapter 3: Masterpass Magento Plug-In Installation... 8 Masterpass Magento Plug-In Installation... 9 Chapter 4: Masterpass Magento Plug-In Configuration... 12 Masterpass Magento Plug-In Configuration...13 Chapter 5: Configuration Verification... 25 Configuration Verification... 26 Appendix A: Installation Instructions for Internationalization Module...32 Installation Instructions for Internationalization Module...33 Appendix B: Uninstallation Instructions for Masterpass Extension Module... 35 Uninstallation Instructions for Masterpass Extension Module... 36 Appendix C: FAQ...37 FAQ... 38 Notices...39 October 2016 2
Introduction Chapter 1 Introduction This chapter provides an overview of this document. Purpose of This Guide... 4 Audience... 4 Assumptions... 4 Prerequisites... 4 October 2016 3
Introduction Purpose of This Guide Purpose of This Guide The purpose of this document is to provide instructions on how to install and configure the Masterpass Magento Plug-in (aka Extension Module) into a standard Magento (Enterprise Edition, version 1.13.1 or 1.14.1) installation on Linux/Windows operating system. Audience The intended audience of this document is PCI-compliant merchants or system configurators/ integrators. Assumptions The instructions in this guide assume the following: Working knowledge of Linux/Windows operating system environments. Working knowledge of LAMP stack on Linux OS or WAMP stack on Windows or XAMPP. Working knowledge of Magento installation and administration. Working installation of Magento with no issues and warnings. Command access to the Linux OS with the proper permission. Successful completion of registration in the Masterpass Merchant or Service Provider Partner Portal and the Mastercard Developers website (see the instructions that follow) with the following information available for configuration. Consumer Keys Checkout Identifier(s) Keystore File Keystore Password To support Australian addresses, you must have installed the Fontis Australia plug-in from http://www.magentocommerce.com/magento-connect/fontis-australia.html. The plug-in is developed for use with the English language and compatible browsers are Internet Explorer and Chrome. Prerequisites Depending on your XAMPP/LAMP/WAMP installation, if the following file is not at the given pear location you need to externally download it and keep it in the location as follows. Download the XML Parser library from https://pear.php.net/package/xml_parser/download Copy the Parser.php file in the XML folder of the pear library folder (path, for example, /lib/php/pear/xml or /lib/php/pear/xml or /xampp/php/pear/xml or / xampp/php/pear/xml ) October 2016 4
Introduction Prerequisites Change the include_path variable in the php.ini file for the pear library, for example, include_path="/path/to/pear/" (This might be an optional/additional step or already there but you can try it if there is any error related to the pear/xml library) October 2016 5
Masterpass Portal and Mastercard Developers Registration Chapter 2 Masterpass Portal and Mastercard Developers Registration This chapter provides information on how to register with the Masterpass Portal and the Mastercard Developers website. Masterpass Portal and Mastercard Developers Registration...7 October 2016 6
Masterpass Portal and Mastercard Developers Registration Masterpass Portal and Mastercard Developers Registration Masterpass Portal and Mastercard Developers Registration Before you begin working with this plug-in, you must complete the registration process in the Masterpass Merchant or Service Provider Portal and the Mastercard Developers site. Please refer to the Onboarding instructions in the relevant Masterpass Integration Guide located here: https://developer.mastercard.com/documentation/masterpass-merchant-integration October 2016 7
Masterpass Magento Plug-In Installation Chapter 3 Masterpass Magento Plug-In Installation This chapter provides instructions on how to install the Masterpass Magento Plug-in. Masterpass Magento Plug-In Installation... 9 October 2016 8
Masterpass Magento Plug-In Installation Masterpass Magento Plug-In Installation Masterpass Magento Plug-In Installation You must obtain the plug-in extension zip file from Masterpass before you begin the manual installation process. The file can be found at either of the following locations: Mastercard Developers: https://developer.mastercard.com/ Masterpass Magento Plug-in at the Magento Connect Store: https:// www.magentocommerce.com/magento-connect/masterpass.html Procedure The following steps will guide you through the manual installation process. 1. Unzip/extract the plug-in extension zip file using the following command: tar -zxvf <filename> NOTE: For extracting packaged extension files (.tar or.tgz) on Windows, it is recommended to use WinRar in order to get uncorrupted files. 2. You should see the following top folder structure after you have successfully unzipped the file: Inside the app folder, you should see three subfolders as follows: 3. Assuming that Magento is installed at /var/www/magento, follow the instructions below to install the plug-in. Depending on the permissions, you might need to log in as special to copy the files or folders. a. Copy the etc/modules/mastercard_masterpass.xml file into the /var/www/ magento/app/etc/modules folder. b. Make sure that the /var/www/magento/app/code/local folder exists. If not, create the folder. October 2016 9
Masterpass Magento Plug-In Installation Masterpass Magento Plug-In Installation c. Copy the app/code/local/mastercard folder into the /var/www/magento/app/local folder. d. The following instructions will copy the layout and template files into your default theme folder. NOTE: If merchants have multiple web stores and only want to use the Masterpass plug-in on a certain web store, then merchants should only copy the Masterpass plugin template to that particular web store s template. i. Navigate to the merchant template folder. /var/www/magento/app/design/frontend/base ii. Copy the app/design/frontend/base/default/layout/masterpass folder into the /var/www/magento/app/design/frontend/base/default/layout folder. iii. Copy the app/design/frontend/base/default/template/masterpass folder into the /var/www/magento/app/design/frontend/base/default/template folder. iv. Copy the skin/frontend/base/default/css/masterpass folder into the /var/www/magento/skin/frontend/base/default/css folder. 4. To install the SDK as library files, copy the phar files from the lib folder (from the unzipped plug-in folder structure) into the var/www/magento/lib folder. 5. To install third-party libraries and use them in the plug-in module, copy the downloaded guzzle.phar, logging library folder, and config.xml (Logger configuration file) ) from the extracted plug-in s lib folder into the respective magento folders ( var/magento/lib ), and including the SDK files you will have all of the library files in the /var/magento/lib folder as follows: This configuration will print INFO, DEBUG level logs all together in a log file at the specified location. 6. The Masterpass Magento Plug-in is now installed and ready for configuration. October 2016 10
Masterpass Magento Plug-In Installation Masterpass Magento Plug-In Installation NOTE: The Masterpass Magento Plug-in package includes the following third-party libraries that are used with the Masterpass plug-in: Guzzle: Version 6.0.0 Log4PHP: Version 2.3.0 XML Serializer: Version 0.20.0 NOTE: The following Magento application pages are customized/extended for the Masterpass plug-in. Application Main Website Affected Pages Checkout page One page Checkout page Order Details Page Confirmation Page October 2016 11
Masterpass Magento Plug-In Configuration Chapter 4 Masterpass Magento Plug-In Configuration This chapter provides instructions on how to configure the installed Masterpass Magento Plug-in. Masterpass Magento Plug-In Configuration... 13 October 2016 12
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration The following instructions will step you through configuration of the Masterpass Magento Plug-in. Procedure 1. Log in to the Magento Administration Console. NOTE: If you were logged in to the Administration Console before completing the plug-in installation, you should log out and log back in again. Otherwise, when attempting to access Masterpass for the first time you will receive a 404 error. 2. You will land on the dashboard page. 3. From the top menu options select System. 4. From the System menu select Configuration. October 2016 13
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration 5. To make sure that the Masterpass plug-in is installed and enabled, scroll down to the ADVANCED section on the left side and select the Advanced submenu. 6. Scroll down to the MasterCard_Masterpass option. The Masterpass configuration is disabled by default. To configure Masterpass, Enable the Masterpass Wallet. October 2016 14
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration NOTE: After you install the plug-in, enable it on the Advanced configuration page and then enable it on the System > Masterpass configuration screen, then any future enabling/disabling should be done from the System > Masterpass configuration screen. If you only disable Masterpass from the Advanced configuration page, the normal checkout button will not appear. 7. Click Save Config if you made any changes. 8. If the Magento cache is enabled, you must flush the cache for your changes to take effect. 9. From the System menu click Configuration. Select the Masterpass option on the left under the GENERAL section. NOTE: If you see a 404 error page after clicking the Masterpass tab, log out and log back in to the Administration Console. October 2016 15
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration 10. Navigate to the Masterpass configuration screen by going to the Magento Admin Panel and then to System > Configuration, and then selecting Masterpass from the menu on the left side of the page. October 2016 16
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration After enabling the Masterpass Module, you must Enable the Masterpass Plug-in in order to view Masterpass configurations. Following is the list of configurable items for Masterpass for the Standard Checkout flow. Standard Checkout flow can be selected in the User Flows field on the configuration page shown in the following figure. October 2016 17
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration October 2016 18
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration Enable Masterpass Wallet Select the Enable or Disable option from the drop-down list. Notification Email Address October 2016 19
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration If a private key executable path is not entered in the administration console of Magento, a notification email will be sent to the email address entered into this field. Masterpass Button Size If desired, select a different size for the button that will be displayed next to the Proceed to Checkout button. Acceptance Marks If desired, select a different size for the button that will be displayed on the payment summary page and the order confirmation page. Environment It is set to Sandbox by default. You can switch between Sandbox and Production environments. Note that the Masterpass Consumer Key, Checkout Identifier, and Keystore File are different between the environments. Masterpass API Version (XML version) Set to v6 by default. This is a read-only value that indicates the current version of the Masterpass wallet that this plug-in/extension supports. Consumer Key Retrieve this key from the Masterpass Merchant Portal. This key is provided by Mastercard upon registration as a Masterpass provider. Checkout Identifier Retrieve this key from the Masterpass Merchant Portal. This key is provided by Mastercard upon registration as a Masterpass provider. Keystore File Empty by default. Enter the file provided during registration as a Masterpass provider. This must be a.p12 file type. Private Key Executable Path The path for the private key executable needs to be correctly configured in the Administration Console. Make certain that the Private Key Executable Path is populated and contains the correct path to an executable that retrieves the private key. For a Linux OS, use a.sh file type (sample path = /var/www.privatekey.sh ). For a Windows OS, use a.bat file type (sample path = C:\\privatekey.bat ). Callback URL Empty by default. If the merchant wants the consumer to land on a custom page (rather than the usual order confirmation page) after he or she has completed the interaction with Masterpass, enter the URL for the destination page. October 2016 20
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration Enter the desired location in the following format: https://servername:sslport/server store path/en/login/checkout Payment Gateway Select the payment gateway that will process the credit card transactions. Credit card validation needs to be turned off. In the Admin Panel, navigate to System > Configuration > Payment Methods. Select Payment Gateway. Set the value to No in the field labeled Request Card Security Code. User Flows If the merchant wishes to enable the Masterpass user flow for Express Checkout, select Express Checkout from the User Flows field and the following additional fields will appear on the configuration screen. Select the information that the merchant would like to capture during the user s Express Checkout experience. NOTE: Merchant must obtain approval from Mastercard in order to activate the Express Checkout user flow. Click on the link on the Masterpass configuration screen under the User Flows field, in order to access a request-approval form to activate this functionality. If Express Checkout is set as the user flow and the Merchant is not approved for same, only Standard Checkout will be available as the Masterpass checkout option. Shipping Suppression Set to false by default. October 2016 21
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration Update to true to suppress the shipping address selector in the Masterpass Wallet and to bypass it during the checkout process. Typically used for the sale of digital or other goods that do not require physical shipment. Rewards Program Set to false by default. Enter the list of valid values (obtained from Mastercard) separated by commas and no spaces. Note that this functionality is not handled by the plug-in. The configurator/integrator will need to add logic in order to apply the loyalty card program and affect the order total. Request Basic Checkout Set to false by default. This is the override for 3DS/Advanced Checkout. This parameter should not be changed within the plug-in. In order to enable the 3DS/ Advanced Checkout screens, the merchant must complete the Advanced Checkout configuration in the Masterpass Merchant Portal. Accepted Credit Cards Three cards selected by default: Mastercard, American Express, Visa. Make sure your payment gateway will accept these cards. If needed, deselect any of the defaults and/or select other cards accepted by your payment gateway. October 2016 22
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration Private Label Card Empty by default. If the merchant supports private label card(s), enter the code numbers of the supported private label card(s) separated by commas. These codes must be obtained from Mastercard. NOTE: The Masterpass module (plug-in) does not perform validation of credit card payments. The module passes information from the Masterpass wallet to the merchant. It is the merchant s responsibility to ensure that any private label card the merchant accepts will adhere to payment validation rules of the e-commerce platform and payment gateway. Generic Checkout Error Message If desired, edit the default message to customize the message that will be displayed to the consumer if Masterpass encounters an error. Enable Learn More Link Set to Enable by default. When set to Enable, the Learn More link appears below the masterpass button. The text will appear when you enable the Learn More link. The text is in MasterPass.enable.learn.more.text. October 2016 23
Masterpass Magento Plug-In Configuration Masterpass Magento Plug-In Configuration NOTE: The Masterpass Branding Requirements require that this link be enabled. Learn More Link If desired, edit the default styling code, to modify the position, font size, color, and location of the link text. Click Save Config to save changes. If the Magento cache is enabled, you must flush the cache for your changes to take effect. October 2016 24
Configuration Verification Chapter 5 Configuration Verification This chapter provides instructions on how to verify that the Masterpass Magento Plug-in has been successfully installed and configured. Configuration Verification... 26 October 2016 25
Configuration Verification Configuration Verification Configuration Verification If the Masterpass Magento Plug-in is installed and configured successfully, you should see the masterpass button next to the Proceed to Checkout button on the shopping cart page. 1. masterpass button displays on the shopping cart page when Masterpass is enabled. For Magento 1.13: For Magento 1.14: 2. After clicking the masterpass button, you should see the following wallet screens. Sign in to a Masterpass wallet and then select Finish shopping. October 2016 26
Configuration Verification Configuration Verification October 2016 27
Configuration Verification Configuration Verification 3. You should see the following screens after clicking the Finish shopping button. Note that the selections made in the Masterpass wallet should be displayed in the Payment, Shipping, and Billing sections. For Magento 1.13: October 2016 28
Configuration Verification Configuration Verification October 2016 29
Configuration Verification Configuration Verification For Magento 1.14: October 2016 30
Configuration Verification Configuration Verification October 2016 31
Installation Instructions for Internationalization Module Installation Instructions for Internationalization Module Appendix A Installation Instructions for Internationalization Module This appendix provides instructions on how to install the internationalization module. Installation Instructions for Internationalization Module...33 October 2016 32
Installation Instructions for Internationalization Module Installation Instructions for Internationalization Module Installation Instructions for Internationalization Module Installation of this module will resolve issues related to country address inconsistencies and will place data in correct address fields for billing and shipping addresses. The installation of this module is not required. However, failure to install the module could result in a need for some consumers/shoppers to enter additional information during the Standard Checkout flow. The module is recommended for any countries outside of the default addresses of USA, CAN, AUS, and UK. The following steps will guide you through the manual installation process. 1. Unzip the file using the following command. tar -zxvf <filename> 2. You should be able to see the following top folder structure after you have successfully unzipped the file. 3. Assuming that Magento is installed at /var/www/magento, follow the instructions below to install the plug-in. Depending on the permissions, you might need to log in as special to copy the files or folders. a. Copy the etc/modules/mastercard_countriesmapping.xml file into the /var/www/ magento/app/etc/modules folder. b. Make sure that the /var/www/magento/app/code/local folder exists. If not, create the folder. c. Copy the app/code/local/mastercard folder into the /var/www/magento/app/local folder. 4. Navigate to the Masterpass Administration Console and verify that the MasterCard_Countriesmapping option is enabled. October 2016 33
Installation Instructions for Internationalization Module Installation Instructions for Internationalization Module October 2016 34
Uninstallation Instructions for Masterpass Extension Module Uninstallation Instructions for Masterpass Extension Module Appendix B Uninstallation Instructions for Masterpass Extension Module This appendix provides instructions on how to uninstall the Masterpass Extension Module. Uninstallation Instructions for Masterpass Extension Module... 36 October 2016 35
Uninstallation Instructions for Masterpass Extension Module Uninstallation Instructions for Masterpass Extension Module Uninstallation Instructions for Masterpass Extension Module Follow the instructions below to uninstall the Masterpass Extension Module. 1. To disable the extension, select System > Configuration > Masterpass. Change Enable Masterpass Wallet to Disable, then click Save Config. 2. Edit the following Masterpass XML file: app/etc/modules/mastercard_masterpass.xml 3. Change <active>true</active> to <active>false</active> 4. Save the change. 5. Clear the cache. NOTE: Removing code is not required. In Magento, if the value is set to false in the XML file, then Magento ignores all code related to the Masterpass extension module. October 2016 36
FAQ FAQ Appendix C FAQ This appendix provides frequently asked questions about Masterpass Magento Plug-in installation, and their answers. FAQ... 38 October 2016 37
FAQ FAQ FAQ I have configured all of the items, yet my buttons do not show up. 1. Check the security settings in the administrative panel. 2. If you are the administrator, check your email to see if you received the hint regarding what is wrong. 3. Check if the executable file returns the correct Keystore Password. 4. Check the server logs for more information. October 2016 38
Notices Notices Following are policies pertaining to proprietary rights, trademarks, translations, and details about the availability of additional information online. Proprietary Rights The information contained in this document is proprietary and confidential to Mastercard International Incorporated, one or more of its affiliated entities (collectively Mastercard ), or both. This material may not be duplicated, published, or disclosed, in whole or in part, without the prior written permission of Mastercard. Trademarks Trademark notices and symbols used in this document reflect the registration status of Mastercard trademarks in the United States. Please consult with the Global Customer Service team or the Mastercard Law Department for the registration status of particular product, program, or service names outside the United States. All third-party product and service names are trademarks or registered trademarks of their respective owners. Disclaimer Mastercard makes no representations or warranties of any kind, express or implied, with respect to the contents of this document. Without limitation, Mastercard specifically disclaims all representations and warranties with respect to this document and any intellectual property rights subsisting therein or any part thereof, including but not limited to any and all implied warranties of title, non-infringement, or suitability for any purpose (whether or not Mastercard has been advised, has reason to know, or is otherwise in fact aware of any information) or achievement of any particular result. Without limitation, Mastercard specifically disclaims all representations and warranties that any practice or implementation of this document will not infringe any third party patents, copyrights, trade secrets or other rights. Translation A translation of any Mastercard manual, bulletin, release, or other Mastercard document into a language other than English is intended solely as a convenience to Mastercard customers. Mastercard provides any translated document to its customers AS IS and makes no representations or warranties of any kind with respect to the translated document, including, but not limited to, its accuracy or reliability. In no event shall Mastercard be liable for any damages resulting from reliance on any translated document. The English version of any Mastercard document will take precedence over any translated version in any legal proceeding. Information Available Online Mastercard provides details about the standards used for this document including times expressed, language use, and contact information on the Publications Support page available on Mastercard Connect. Go to Publications Support for centralized information. October 2016 39