Version 2.0.0
Contents 1. RELEASE NOTES...3 2. MODULE FEATURES... 4 3. PREREQUISITES... 5 4. INSTALLATION OF THE PAYMENT MODULE... 6 4.1. Package description... 6 4.2. Installation of the module... 6 5. CONFIGURATION OF THE PAYMENT MODULE... 7 5.1. General configuration... 7 5.2. Standard payment... 9 5.3. Credit card installment payment... 10 6. CONFIGURATION OF THE INSTANT PAYMENT NOTIFICATION URL... 12 6.1. Setting up the end of payment notification... 12 6.2. Setting up notifications in case of abandoned/canceled payments... 13 6.3. Testing the Instant Payment Notification URL... 15 7. MOVING ON TO TEST PHASE...16 8. SHIFTING THE SHOP TO PRODUCTION MODE... 17 9. DOCUMENTATION UPDATE... 18
1. RELEASE NOTES Version Date Comments 2.0.0 3/11/2016 Initial version Intellectual property rights - 3 / 18
2. MODULE FEATURES The payment module contains the following features: Compatibility with Magento version 2.0.2 Multi-shop / multi-view compatibility Multi-language compatibility Multi-currency compatibility Selective 3D-Secure depending on the order amount Automatic redirection to the shop at the end of payment Configuration of a minimum/maximum amount for each type of payment Customer group payment method restriction Systematic update of orders at the end of payment via a silent URL (Notification URL) Immediate payment Payment in installments (possibility to create several payment options) Intellectual property rights - 4 / 18
3. PREREQUISITES Before integrating the payment module, please make sure that you are in possession of the following elements: Payment module file: PayZen_Magento_2.x_v2.0.0.zip Your shop ID Test or production certificate The shop ID and the certificates are available in the PayZen Back Office (Menu: Settings > Shop > Certificates) Your PayZen Back Office is available at this address: https://secure.payzen.eu/vads-merchant/ Intellectual property rights - 5 / 18
4. INSTALLATION OF THE PAYMENT MODULE The PayZen payment module is installed via the Magento Component Manager. As for all the other extensions, make sure you have configured and activated the job scheduler (crontab) as explained in the Magento documentation: http://devdocs.magento.com/guides/v2.0/config-guide/cli/config-cli-subcommands-cron.html 4.1. Package description By default, the payment module files will be stored in app/code/lyra/payzen. Unzip the PayZen_Magento_2.x_v2.0.0.zip file. It contains: The app folder containing the payment module files The Integration_PayZen_Magento_2.x_v2.0.0.pdf file which corresponds to this document. 4.2. Installation of the module 1. Transfer the 'app' folder located in the PayZen file _Magento_2.x_v2.0.0.zip into the installation folder of your Magento solution using an FTP client or during the online order. 2. Empty the Magento cache via the Back Office (System > Cache Management). 3. Open the Component Manager (System > Web Setup Wizard > Component Manager). 4. In the list of extensions detected by Magento, search for the Lyra_Payzen module. 5. In the Action column, click on Select, then on Enable. 6. Magento will then perform several checks (PHP version, file permissions, presence of the cron, etc.). Click on Start Readiness Check to launch tests. 7. If Magento displays errors or alerts, contact your webmaster/host to fix them. 8. Once all the checks are finalized, click on Next to proceed to the next step. 9. If you wish, you can create a back-up of your installation (files and Database). Click on Next when you are ready to start the back-up process. This step can take several minutes. 10.Once the back-up has been created, click on Enable. 11.Magento will wait for the cron to pass by once again before activating the module. This step can take several minutes. If you experience any issues, contact your webmaster/host to analyze and fix the errors. 12.Once the module is activated, return to the Back Office. Intellectual property rights - 6 / 18
5. CONFIGURATION OF THE PAYMENT MODULE In the Magento Back Office: 1. Go to the Magento administration menu and click on Stores > Configuration. 2. Then click on SALES > Payment Methods 3. If your Magento platform has several sites, shops or views, configure the Portée de la configuration courante to match your desired configuration. 4. Click to expand the PayZen section. 5.1. General configuration Click to expand the General configuration section. It provides access to: information relative to the version of the module the configuration of the connection with the payment platform payment page configuration customization of the payment pages configuration of Selective 3D-Secure configuration of the return to the merchant website 1. Accessing the payment page: a. Enter the 8-digit long shop identifier available in your PayZen Back Office (Settings > Shop > Certificates). b. Fill in the Test certificate available in your Back Office (Settings > Shop > Certificates). c. If you have already generated the Production certificate, fill it in. It is available in your Back Office (Settings > Shop > Certificates). If not, leave the default value for the moment. The production certificate is only available after the test phase has been completed. d. Select the operating mode of the module (TEST or PRODUCTION). The PRODUCTION mode becomes available only after the test phase has been completed. The TEST mode is always available. e. The payment page URL is pre-populated by default and must not be modified. f. Copy the Instant Payment Notification URL into your Back Office (go to Settings > Notification rules > Instant Payment Notification URL at the end of payment). Intellectual property rights - 7 / 18
2. Payment page: a. Select available languages that you wish to offer to the buyer. The buyer will be able to change the language during the payment by clicking on the corresponding flag at the bottom of the payment page. To select multiple languages, press and hold CTRL. If you do not select any language, all the flags will be displayed. b. Select the default language of the payment page. This parameter will be used in case the language of Magento is not recognized by PayZen. c. Enter the capture delay if you wish to override the value defined in your Back Office (Settings > Shop > Configuration). d. Select the payment validation mode from the following options: Back Office configuration: uses the validation mode defined in your Back Office. Manual: the payments will be subject to manual validation by the merchant in the Back Office. If the transaction has not been validated by the merchant before the expiration date, it will never be captured in the bank. Automatic: the payments will be captured in the bank automatically without any action on the merchant's part. e. Select the card types to be displayed on the payment page or on the merchant website if you wish to enable payment method selection on the merchant website (see Configuration of the standard payment method). The payment types offered to the buyer on the payment page depend on the contracts and options associated with your PayZen offer. It is recommended to select the ALL value. f. Associate a type with each category of your catalog. This information is required to perform fraud verification (subject to the option). You can: rapidly associate a type of category to all the products in your catalog, associate a type with each category in your catalog. The categories are: Food and grocery Cars Entertainment Home and gardening Household appliances Auctions and group purchasing Flowers and presents Computers and software Health and beauty Services for individuals Services for companies Sports Clothes and accessories Travel Home audio, photo, video Telephony. 3. Customization of the payment page: a. If you have opted for an offer with the "Advanced customization of the payment page" option, populate the Theme configuration field with the provided keywords. For more information, see the Advanced Customization User Guide. b. If your Magento module has several sites, indicate the shop name that will be displayed on the payment pages. c. If your Magento module has several sites, indicate the shop URL that will be displayed on the payment pages. 4. If you have opted for an offer that includes the option Selective 3D Secure, configure the minimum amount for which you wish to request a 3D Secure authentication. Warning: some card types, such as MAESTRO, require a mandatory 3DS authentication. In this case, your configuration will not be taken into account. 5. Return to the shop: Intellectual property rights - 8 / 18
a. Enable automatic return if you wish to automatically redirect the buyer to the merchant website. b. Configure the delay in seconds before the buyer is redirected to the merchant website after a successfully completed payment. c. Enter the message that will be displayed to the buyer before redirection to the merchant website after a successfully completed payment. Default message: "Redirection vers la boutique dans quelques instants" (Redirection to the shop in a moment). d. Configure the delay in seconds before the buyer is redirected to the merchant website after a declined payment. e. Enter the message that will be displayed to the buyer before redirection to the merchant website after a declined payment. Default message: "Redirection vers la boutique dans quelques instants" (Redirection to the shop in a moment). f. Select the return mode of the parameters transmitted by the buyer's browser. It is recommended to select the GET mode which is more convenient for the buyer because it allows to avoid the display of a warning message. g. Select the status of successfully paid orders: Pending Processing It is recommended to select "Processing". If the payment gets declined, the order will be canceled. h. Select the method (automatic or manual) for generating the invoice when the status of successfully registered orders is "Processing". 6. Once you have completed the configuration, click on "Save config". 5.2. Standard payment Click to expand the Standard Payment section. 1. Configure the general settings: a. Activation: Select Yes to enable this payment method. b. If you offer several payment methods, enter a number in the Display order field to determine the position of Standard payment. The payment methods appear in acsending order depending on the value of Display order. c. Enter a Title to identify this payment method during checkout. The default value is Pay by Credit Card. d. Configure the countries for which the payment method is available: All countries: the payment method is available for all countries. Some countries: after choosing this option, the list of Authorized countries appears. Press and hold Ctrl and select the countries of your choice from the list of Authorized countries. e. Choose the Logo that you wish to display during checkout. 2. Configure the use restrictions for each user group: a. Enter the Minimum amount for which you wish to enable the payment method. b. Enter the Maximum amount above which you do not wish to enable this payment method. Intellectual property rights - 9 / 18
3. Configure the "Payment page" section options: a. Configure the Capture delay. Leave empty to use the value defined in your PayZen Back Office (Settings > Shop > Configuration section: capture delay). b. Configure the Validation mode for payments with one of the following values: PayZen General Configuration: Applies the configuration defined in the General configuration of the PayZen module. Back Office configuration: Recommended value. Applies the configuration defined in the Back Office. (Settings > Shop > Configuration section: validation mode). Manual: The transactions will be subject to manual validation by the merchant in the Back Office. Warning: if the transaction is not validated by the merchant before the expiration date, it will never be captured in the bank. Automatic: The transactions will be automatically captured in the bank without any action on the part of the merchant. 4. Once you have completed the configuration, click on "Save config". 5.3. Credit card installment payment Click to expand the Credit card installment payment section. 1. Configure the basic settings: a. Activation: Select Yes to enable this payment method. b. If you offer several payment methods, enter a number in the field Display order to determine the position of Credit Card Installment Payment. The payment methods appear in ascending order according to the Display order value. c. Enter a Title to identify this payment method during checkout. The default value is Pay by Credit Card in Installments. d. Configure the countries for which the payment method is available: All countries: the payment method is available for all countries. Some countries: after choosing this option, the list of Authorized countries appears. Press and hold Ctrl and select the countries of your choice from the list of Authorized countries. e. Choose the Logo that you wish to display during checkout. 2. Configure the use restrictions for each user group: a. Enter the Minimum amount for which you wish to enable the payment method. b. Enter the Maximum amount above which you do not wish to enable this payment method. 3. Configure the "Payment page" section options: a. Configure the Capture delay. Leave empty to use the value defined in your PayZen Back Office (Settings > Shop > Configuration section: capture delay). b. Configure the Validation mode for payments with one of the following values: PayZen General Configuration Intellectual property rights - 10 / 18
Applies the configuration defined in the General configuration of the PayZen module. Back Office configuration: Recommended value. Applies the configuration defined in the Back Office. (Settings > Shop > Configuration section: validation mode). Manual: The transactions will be subject to manual validation by the merchant in the Back Office. Warning: if the transaction is not validated by the merchant before the expiration date, it will never be captured in the bank. Automatic: The transactions will be automatically captured in the bank without any action on the part of the merchant. 4. Create the installment payment options that you wish to offer to your buyers: a. Click on Add b. Fill in the label of the option that will be displayed during checkout the minimum amount from which you wish to offer this payment option the maximum amount beyond which you do not wish offer this payment option the number of installments (3 for a payment in 3 installments, etc.) the period between each installment (in days) the amount of the first downpayment, expressed as a percentage of the total amount. For an amount of 100 euros paid in 3 installments, you can set the percentage of the first installment at 50% of the total amount. This means that the amount of the first installment will be 50 euros and that the two others will be of 25 euros. For 50%, enter 50. If you want the amount of every installment to be the same, leave this field empty. 5. Once you have completed the configuration, click on "Save config". Intellectual property rights - 11 / 18
6. CONFIGURATION OF THE INSTANT PAYMENT NOTIFICATION URL Several notification types are made available in the Back Office. They allow to manage events (payment abandoned by the buyer, payment canceled by the merchant, payment validated by the merchant, etc.) that will generate a call to the merchant website and configure the URL of the page to contact. To access the notification rule management: 1. Connect to: https://secure.payzen.eu/vads-merchant/. 2. Go to the following menu: Settings > Notification rules. Figure 1: Notification rules 6.1. Setting up the end of payment notification You must set up a URL in your PayZen Back Office that will be called after a payment. It will inform the merchant website of the result of the payment even if your client does not click on the return to the shop button. This setting is the Instant Payment Notification URL at the end of the payment. To set up this notification: 1. Right-click on Instant Payment Notification URL at the end of the payment. 2. Select Manage the rule. 3. Fill in the URL to notify in TEST mode and URL to notify in PRODUCTION mode fields: http:// www.mon-domaine.fr/index.php/payzen/payment/check/ Figure 2: Setting up the end of payment notification 4. Enter the E-mail address(es) to notify in case of failure. Intellectual property rights - 12 / 18
5. To enter several e-mail addresses, separate them by a semi-colon. 6. Configure the Automatic retry in case of failure. This option allows to automatically resend notifications to the merchant website in case of failure (up to 4 times). For more information, see chapter Activating the automatic retry of the implementation guide available on our documentation website : 7. Save the changes. If the platform is unable to access the URL of your page, an e-mail will be sent to the address specified in step 6. It contains: the HTTP code of the encountered error, parts of error analysis, its consequences, instructions to resend the request to the URL specified in step 5 from the PayZen Back Office. 6.2. Setting up notifications in case of abandoned/canceled payments It is possible to configure the settings so that the payment gateway systematically notifies the merchant website: When the buyer abandons/cancels a payment - via the Cancel an return to shop button. When the buyer has not completed the payment process and the payment session has expired. The maximum length of a payment session is 10 minutes. To set up this notification: 1. Right-click on Instant Payment Notification URL on cancellation. 2. Select Manage the rule. 3. Fill in URL to notify in TEST mode and URL to notify in PRODUCTION mode fields: http://www.mondomaine.fr/index.php/payzen/payment/check/ 4. Fill in the E-mail address(es) to notify in case of failure. 5. To specify several e-mail addresses, separate them by a semi-colon. 6. Set up the parameters for Automatic retry in case of failure. This option allows to automatically send notifications to the merchant website in case of failure, up to 4 times. For more information, see chapter Activating the automatic retry 7. Save the modifications. If the payment gateway is unable to access the URL of your page, an e-mail will be sent to the address specified in step 6. It contains: the HTTP code of the encountered error, analysis parts for the error, Intellectual property rights - 13 / 18
Instructions to resend the notification to the URL specified in step 5 from the Back Office PayZen. Intellectual property rights - 14 / 18
6.3. Testing the Instant Payment Notification URL In order to make sure that the Instant Payment Notification functions correctly, follow these steps: 1. Make sure that your URL is available online: your shop must neither be in maintenance mode nor be protected by an.htaccess file. 2. Make sure that the "Automatic redirection" option is disabled in the payment module settings. 3. Check that the Instant Payment Notification URL at the end of payment is populated in the PayZen Back Office (see above). 4. Make an order on your website and proceed to payment. 5. Do not click on "Return to shop" at the end of payment. 6. Make sure that the order status is Processing or Pending in the Magento Back Office. If the order status is still Pending (pending_payment), this means that the call has failed. Intellectual property rights - 15 / 18
7. MOVING ON TO TEST PHASE Now that the payment module has been configured and you have specified the IPN URLs, you can move on to test phase in order to generate the production certificate. The list of the tests to be done is provided in the PayZen Back Office in Settings > Shop > Certificates. Each row of the list contains card numbers associated with the same scenario (i.e. 2 accepted payments and 2 refused payments). Each column corresponds to a different card type: CB/VISA, MASTERCARD, MAESTRO, VISA ELECTRON. To perform the test phase: 1. Make an order on your merchant website as if you were one of your buyers. 2. Select the Pay by Credit Card payment mode. 3. Once redirected towards the payment page, select the card type of your choice 4. Go to the list of tests to identify the card number to use. 5. Once a test has been validated, its status is updated in the list. Click on Refresh the table if the status has not been updated automatically. 6. Once the 4 tests have been validated, the button Generate the production certificate becomes available. 7. Click on Generate the production certificate and accept the notification messages that will appear. The production certificate is now available. Intellectual property rights - 16 / 18
8. SHIFTING THE SHOP TO PRODUCTION MODE After you receive a confirmation e-mail informing you that a certificate has been generated, you can configure the payment method by following the steps below: Retrieve the production certificate provided in the Back Office (Settings > Shop > Certificates). In the module configuration parameters: Populate the Production certificate field Switch from TEST to PRODUCTION mode. Save the changes. Make sure that you have specified the IPN URL in production mode as described in the chapter Setting up the IPN URL. Once the production settings have been configured, we recommend to make a first real payment. You will be able to cancel this payment in the Back Office. This transaction will not be captured by the bank. Note on the production certificate: For security reasons, this certificate will no longer be visible after the first transaction in production mode has been made from your shop. Note on the TEST mode: When you shop is in production mode, the TEST mode remains available. To work in test mode, follow the steps below: Switch from PRODUCTION to TEST mode. Make sure that the Test certificate is correctly specified. Save the changes. Intellectual property rights - 17 / 18
9. DOCUMENTATION UPDATE As we constantly strive to improve the understanding and proper use of this product documentation, we value constructive remarks from our users. Please send us your comments and suggestions to the following address: support@payzen.eu. You must specify the version of Magento and of the payment module you use. Intellectual property rights - 18 / 18