# Using Ecommpay payments for PrestaShop CMS {#en_cms_prestashop} An article about using a plug-in for embedding Payment Page into websites powered by the PrestaShop CMS platform. **Parent topic:**[Integration using plug-ins](en_CMS.md) ## Overview {#en_cms_prestashop_overview} This article covers the information about using the payment plug-in Ecommpay payments version 2.0.0. This plug-in version can be used in web services that are based on the PrestaShop CMS version 8.1.5 or later. The Ecommpay payments plug-in is installed via the PrestaShop interface and allows opening the Payment Page payment form of Ecommpay for customers and ensuring all necessary actions for payment processing with regard to the interaction with both customers and the Ecommpay payment platform \(with all necessary information sent and received\). ![](images/ecommpay/cms/prestashop/cms_prestashop_orders_overview.svg "Administrative interface PrestaShop") ![](images/unimethods/en_pp_browser_tab.svg "Interface of the Payment Page payment form") ## General information {#en_cms_prestashop_general} ### Capabilities {#section_lbv_jb2_lwb .section} With the Ecommpay payments plug-in, the following is available: - Setting up the capability to open the Payment Page payment form of Ecommpay in the web service on the fly. For this, you only need to take a few actions in the interface of the PrestaShop CMS. - Setting up the usage of separate payment methods available via the plug-in: payments made with the direct use of payment cards, the Apple Pay and Google Pay methods, and other alternative methods\(if they are available for the project in use\). For this, you can use the tabs with parameters of using payment methods on the plug-in configuration page in the PrestaShop interface. - Testing the operation of the payment form and the capabilities of payment processing. For this, you can get a test project in the Ecommpay payment platform \(by submitting [an application](https://ecommpay.com/sign-up/) on the company's main site\) and use the identifier and secret key of this project. - Processing one-time one-step purchaseswith the use of various payment methods. For resolving all organisational issuesand setting up different payment methods, contact the Ecommpay account manager. - Issuing partial and full refunds for purchases, which were processed with the help of the plug-in. For this, you can use the PrestaShop interface and, if relevant, the interfaces of the Ecommpay payment form \(the user interface Dashboard and the Gate API\). Along with that, when using the interfaces of the Ecommpay payment platform, order information in the PrestaShop interface is updated only if conditions for sending callbacks from the payment platform have been configured \([details](en_dbl_projects.md)\). - Monitoring the information about payments, which were processed with the help of the plug-in. For this, you can use the PrestaShop and, if relevant,—the Data API and the Dashboard interface of Ecommpay. - Managing orders with related purchases processed with the help of the plug-in. For this, you can use the PrestaShop interface that allows cancelling these orders and changing their statuses manually \(if necessary\). - Configuring the parameters of the Payment Page operation and adjusting the form to the web service specifics, as well as using various capabilities provided by Ecommpay. Particularly, you can use the payment confirmation procedure when working with the Open Banking methods \([details](pm_openbanking.md#section_yln_qjn_ftb)\), provide customers with the capability of payment retries \([details](en_PP_Try_Again.md)\), and set up sending notifications to customers about the purchased goods and services \([details](en_PP_receipt_data.md)\). This range of capabilities allows you to adjust to various business specifics, flexibly configure user scenarios, and ensure a high rate of the payment form conversion and payment acceptance. For setting up and using the capabilities provided by Ecommpay, refer to the technical documentation on this portal and, if necessary, contact the Ecommpay specialists. ### Workflow {#section_wtg_4v3_mwb .section} The following diagram illustrates the workflow of executing purchases with the use of the Ecommpay payments plug-in. The workflow involves the customer, the merchant's web service with the built-in plug-in, the Payment Page payment form, the payment platform, and the payment environment. On the web service side, the opening of Payment Page is requested and automatic interaction with the payment platform is carried out in accordance with the plug-in parameters. ![](images/universal/cms/en_cms_workflow.svg) 1. On the web service side, the customer selects the option to pay with the use of the Ecommpay payments plug-in. 2. The request for opening the Payment Page payment form is automatically generated and sent to the payment platform via the plug-in. 3. The request for opening Payment Page is received in the payment platform. 4. The request is processed in the payment platform and checked for correctness. 5. The necessary actions are performed on the payment platform side to prepare for displaying the payment form to the customer. 6. The payment form is displayed to the customer. 7. The customer completes the required actions for purchase and confirms the purchase. 8. The final purchase request \(with all necessary data\) is received in the platform. 9. The request is sent to the payment environment. 10. The request is processed in the payment environment. And if necessary, additional actions are performed on the side of the platform and the customer \(for example, for the 3‑D Secure authentication\). 11. The purchase result information is sent from the payment environment to the payment platform. 12. The callback with the purchase result information is sent from the payment platform to the web service. The callback is automatically processed with the help of the plug-in, thus the order information is updated in the PrestaShop interface. 13. The purchase result information is sent from the payment platform to Payment Page. 14. The purchase result information is displayed to the customer eitherin the Payment Page payment form\(if the form was opened in a modal window or a separate tab\) or on the web service page \(if the form was opened directly in the web service\). ### Options for using the payment form {#section_rtj_mwk_bgd .section} Different options for invoking Payment Page can be used within the described general workflow of the Ecommpay payments plug-in: - For card payments, the payment form embedded directly into the web service interface \(in an iframe element\) is the default option. Opening the payment form in a modal window or a separate tab is also available for card payments. - For alternative payment methods, opening the payment form in a separate tab is the only option. When the Payment Page payment form is embedded directly into the web service interface \(in an iframe element\), the customer specifies the payment card credentials and confirms the order in the PrestaShop CMS and the payment initiated in the Ecommpay platform directly on the web service page for proceeding to payment \(using the **Place Order** button\). When the Payment Page payment form is opened in a modal window or a separate tab, the customer first confirms the order generated in the PrestaShop CMS on the web service page for proceeding to payment \(using the **Place Order** button\) and only after that specifies the necessary data in the payment form and confirms the payment initiated in the Ecommpay platform \(using the **Pay** button\). ![](images/ecommpay/cms/prestashop/en_cms_prestashop_pp_embedded.svg "Payment form embedded into the web service interface") ![](images/ecommpay/cms/prestashop/en_cms_prestashop_pp_popup.svg "Payment form opened in a modal window") More information about opening Payment Page is provided [in the corresponding articles](en_PP_Integration.md). ### Monitoring orders and payments {#section_vgh_wyk_bge .section} While working with the Ecommpay payments plug-in, keep in mind that orders in the web service and payments in the payment platform have different identifiers and statuses.Orders are assigned ordinal numbers \(for example, `71`\) and statuses associated with payment statuses in the Ecommpay platform: - `Ecommpay: Pending` if the payment has an intermediate status. - `Ecommpay: Approved` if the payment has been processed. - `Ecommpay: Declined` if the payment has been declined. - `Ecommpay: Partially refunded` if a partial refund has been made within the order. - `Ecommpay: Refund` if a full refund has been made within the order. Similarly, payments on the payment platform side are assigned identifiers that consist of the prefix `pt_` and ten arbitrary characters \(for example, `pt_64ca3135cf`\) and statuses that you can look up in the section about the payment processing model \([details](en_platform_payment_model.md)\). With questions about the statuses of payments and orders, contact your Ecommpay account manager. ## Installation {#en_cms_prestashop_installation} To start using the Ecommpay Payments plug-in version 2.0.0, you need to install it. If an earlier version of this plug-in was previously used, before updating the plug-in, it is recommended to do the following: 1. Copy the values of parameters of the plug-in operation for further use with the new plug-in version. This is because updating the plug-in leads to clearing the parameters which means you have to set up them again. 2. Deactivate the earlier version of the plug-in. This can be done via the register with the installed plug-ins in the PrestaShop interface, using the **Uninstall** button. To install the plug-in, download its [zip file](https://github.com/ITECOMMPAY/ecommpay-prestashop) and proceed in the PrestaShop interface as follows: 1. Select the **Modules** section and the **Module Manager** item in the **IMPROVE** section of the navigation menu. 2. Click the **Upload a module** button on the **Module Manager** page and select the previously downloaded zip file of the plug-in. 3. Wait for the completion of the download and automatic installation of the plug-in. Upon the completion of these steps, you can find the Ecommpay payments plug-in panel on the **Module Manager** page and proceed to working with the plug-in. ![](images/ecommpay/cms/prestashop/cms_prestashop_installation.png "Module Manager page with the plug-in panel in the PrestaShop interface") ## Testing {#en_cms_prestashop_testing} ### Overview {#en_cms_prestashop_testing_overview} Testing the plug-in operation and various payment scenarioswithout actual debiting of funds is possible via the test environment of the Ecommpay payment platform. You can connect to the platform by using the corresponding form [on the company's main site](https://ecommpay.com/apply-now/) andthe identifier and secret key of the test project received from Ecommpay.Along with that, it is necessary to provide the Ecommpay technical support specialists with the name of the web service for which the plug-in from Ecommpay will be used, the web service URL, and the payment currency. Keep in mind that when you use the testing environment of the Ecommpay payment platform, the plug-in will be connected to the web service and will become available as a payment option to the customers. Therefore, it is recommended that if you need to connect the plug-in to the web service in production mode, test the plug-in operation during the low-load time and warn your customers about planned maintenance. ### Parameters setup {#en_cms_prestashop_testing_setup} To prepare the plug-in for testing, decide on the preferable testing option and set up the plug-in in the PrestaShop interface. For this, proceed as follows: 1. Go to the plug-in operation parameters in the PrestaShop interface. For this, proceed as follows: 1. Select the **Modules** section and the **Module Manager** item in the **IMPROVE** section of the navigation menu. 2. Search for the Ecommpay payments plug-in on the page that opens and click the **Configure** button in the corresponding line. 2. Set up the basic parameters of the plug-in operation in the **General Settings** taband save changes by clicking **Save Settings**: - **Project ID**—the test project identifier. - **Secret key**—the test project key. - **Language**—the language in which the payment form is displayed. ![](images/ecommpay/cms/prestashop/cms_prestashop_general.png "Tab with the basic parameters of the plug-in operation") 3. Set up the general parameters for using the payment method on its setup taband save changes by clicking **Save Settings**: - **Enabled**—the setting for enabling a payment method to work via the plug-in. To enable a method, select the **Enabled** checkbox. By default, the checkbox is not selected. - **Title**—the payment method namedisplayed on the checkout page in the web service. - **Description**—the text displayed to the customers when they select a certain payment method. **Note:** If necessary, the fields **Title** and **Description** can be used for notifying customers that the plug-in is operating in the test mode. 4. If necessary, set up the other parameters for using payment methods \([details](en_cms_prestashop.md)\) and save changes by clicking **Save Settings** in each tab. ### Processing test purchases {#en_cms_prestashop_testing_purchase} When testing the plug-in operation, you can process test purchases in the web service and obtain information about them via the PrestaShop, in the **Orders** subsection of the **Orders** section. Along with that, you can use special payment credentials that allow testing particular payment scenarios. To test card payments, you can use the credentials of test cards. For testing according to the shortest scenarios\(without the emulation of the 3‑D Secure authentication\), the following numbers of cards can be used: - `4000 0000 0000 0077`—for a purchase to be processed - `4111 1111 1111 1111`—for a purchase to be declined For more comprehensive testing, it is possible to use extended test data for card payments\(including scenarios with the 3‑D Secure authentication\) provided in the [Test cards](en_test_cards.md) article. To test payments using alternative payment methods\(with these methods set up through an account manager or the technical support specialists in the test environment of payment platform\), you can use the information provided in the [Testing](en_pm_testing.md) article and in the corresponding sections of the articles about working with particular payment methods. ### Processing test refunds {#en_cms_prestashop_testing_refund} #### Overview {#section_ddh_41r_kbc .section} After processing test purchases, you can make test refundsvia the PrestaShop interface and, if relevant, via [the Gate API](en_Gate_Refund.md) and [Dashboard](en_dbl_payments.md) from Ecommpay. Refunds can be made for payments that meet two conditions. First, they must be the payments made using methods that support refunds. Second, they must be the payments for which the full amount has not been refunded—on the payment platform side, such payments are assigned statuses `success`, `partially reversed`, or `partially refunded`. You can monitor the execution of refunds through the Ecommpay platform interfaces and the PrestaShop interface. Also, note that all information about test refunds provided in this subsection is also relevant for issuing refunds in the production environment. #### Ensuring data synchronisation {#section_qvf_z1r_kbc .section} When refunds are initiated via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\), order information in the PrestaShop interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the order information via the PrestaShop interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the PrestaShop interface. For this, the following conditions must be met: - For the project in use, conditions that trigger callbacks sent from the payment platform to the PrestaShop CMS, to the URL specified on the page with the plug-in operation parameters \(in the format of `https:///en/module/Ecommpay/callback`\), are configured. Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md). - The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code. #### Procedures {#section_efy_1ck_kbc .section} Refunds are available for purchases that have been processed and not fully refunded.On the Ecommpay payment platform side, such purchases have the statuses `success`, `partially reversed`, and `partially refunded`. You can monitor the processing of refunds via the interfaces of the Ecommpay platform and the PrestaShop interface. To make a refund via the PrestaShop interface, proceed as follows: 1. Open the tab of the order that should be refunded. For this, select the **Orders** item in the similarly-named section of the **SELL** section and click the line of the needed order. 2. Initiate the refund. For this, proceed as follows: 1. Open the **Products** panel by clicking the **Partial refund** button. 2. Specify the refund amount in the **Amount \(Tax included\)** field and select the **Refund via Ecommpay** checkbox. 3. Click the **Partial refund** button in the bottom right corner of the **Products** panel. 3. Ensure that the refund has been made. For this, you can check that the order status has changed to `Ecommpay: Partially refunded` \(in case of a partial refund\) or `Ecommpay: Refund` \(in case of a full refund\). ![](images/ecommpay/cms/prestashop/cms_prestashop_info_refund.png "Products panel with the capability to issue refunds in the order tab") To make a refund via the Gate API or Dashboard of the Ecommpay platform, use the procedures provided in the corresponding articles: [Purchase refunds](en_Gate_Refund.md)\(for the Gate API\) and [Issuing refunds](en_dbl_payments.md)\(for the Dashboard interface\). ## Usage {#en_cms_prestashop_usage} ### Overview {#en_cms_prestashop_usage_overview} In order to process payments with actual debiting of funds, you should initially solve all organisational issues related to the interaction with Ecommpay\(submit the application for connecting to the payment platform, provide all necessary information, and receive a notification from Ecommpay about the possibility to process payments, as well as the identifier and secret key of the production project\). Along with that, it is necessary to provide the Ecommpay technical support specialists with the name and URL of the web servicefor which the Ecommpay payments plug-in will be used and the currency in which payments are to be processed. After that, specify the identifier and secret key of the production project received from Ecommpay in the parameters of the plug-in operation and set up other necessary parameters\(or check whether the current setup is relevant for working in real-life conditions\). If later you need to suspend the plug-in operation, the plug-in methods can be disabled. Besides, if additional testing is needed, for example when setting up new features, the plug-in can be switched to using the test project. ### Parameters setup {#en_cms_prestashop_usage_setup} To set up the plug-in parameters, proceed as follows: 1. Go to the plug-in operation parameters in the PrestaShop interface. For this, proceed as follows: 1. Select the **Modules** section and the **Module Manager** item in the **IMPROVE** section of the navigation menu. 2. Search for the Ecommpay payments plug-in on the page that opens and click the **Configure** button in the corresponding line. 2. Set up the basic parameters of the plug-in operation in the **General Settings** taband save changes by clicking **Save Settings**: - **Project ID**—the production project identifier. - **Secret key**—the production project secret key. - **Language**—the language in which the payment form is displayed. ![](images/ecommpay/cms/prestashop/cms_prestashop_general.png "Tab with the basic parameters of the plug-in operation") 3. Set up the general parameters for using the payment method on its setup taband save changes by clicking **Save Settings**: - **Enabled**—the feature for enabling a payment method to work via the plug-in. To enable a method, select the **Enabled** checkbox. By default, the checkbox is not selected. - **Title**—the payment method namedisplayed on the checkout page in the web service. - **Description**—the text displayed to the customers when they select a certain payment method. **Note:** If during testing the fields **Title** and **Description** were used for notifying customers about ongoing testing activities, when switching to work in the production project, it is important to remove the notifications. 4. If necessary, set up the other parameters for using payment methods \([details](en_cms_prestashop.md)\) and save changes by clicking **Save Settings** in each tab. ### Processing purchases {#en_cms_prestashop_usage_purchase} If the web service and the plug-in have been set up correctly, purchases are processed automatically.Along with that, it is important to ensure that all necessary data is collected on the web service side. **Note:** The data set mandatory for processing card payments with the 3‑D Secure authentication has been expanded. To submit these data, use the fields for collecting the customer's phone number or email on the checkout page. In case of questions or issues related to purchase processing, contact the Ecommpay technical support specialists. ### Issuing refunds {#en_cms_prestashop_usage_refund} After processing purchases, you can issue refunds as part of these purchasesvia the PrestaShop interface and, if relevant, via the interfaces [Gate](en_Gate_Refund.md) and [Dashboard](en_dbl_payments.md) from Ecommpay. Along with that, keep in mind that refunds can be made in case if orders in the PrestaShop interface have the statuses `Ecommpay: Approved` or `Ecommpay: Partially refunded` and if payments in the Ecommpay payment platform have the statuses `success`, `partially reversed`, or `partially refunded`. Also, you can take into consideration that all capabilities and procedures of working with refunds in the production environment correspond to those available in the test environment. #### Ensuring data synchronisation {#section_ac1_mhm_sbc .section} When refunds are initiated via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\), order information in the PrestaShop interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the order information via the PrestaShop interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the PrestaShop interface. For this, the following conditions must be met: - For the project in use, conditions that trigger callbacks sent from the payment platform to the PrestaShop CMS, to the URL specified on the page with the plug-in operation parameters \(in the format of `https:///en/module/Ecommpay/callback`\), are configured. Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md). - The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code. #### Procedures {#section_fkp_mhm_sbc .section} Refunds are available for purchases that have been processed and not fully refunded.On the Ecommpay payment platform side, such purchases have the statuses `success`, `partially reversed`, and `partially refunded`. You can monitor the processing of refunds via the interfaces of the Ecommpay platform and the PrestaShop interface. To make a refund via the PrestaShop interface, proceed as follows: 1. Open the tab of the order that should be refunded. For this, select the **Orders** item in the similarly-named section of the **SELL** section and click the line of the needed order. 2. Initiate the refund. For this, proceed as follows: 1. Open the **Products** panel by clicking the **Partial refund** button. 2. Specify the refund amount in the **Amount \(Tax included\)** field and select the **Refund via Ecommpay** checkbox. 3. Click the **Partial refund** button in the bottom right corner of the **Products** panel. 3. Ensure that the refund has been made. For this, you can check that the order status has changed to `Ecommpay: Partially refunded` \(in case of a partial refund\) or `Ecommpay: Refund` \(in case of a full refund\). ![](images/ecommpay/cms/prestashop/cms_prestashop_info_refund.png "Products panel with the capability to issue refunds in the order tab") To make a refund via the Gate API or Dashboard of the Ecommpay platform, use the procedures provided in the corresponding articles: [Purchase refunds](en_Gate_Refund.md)\(for the Gate API\) and [Issuing refunds](en_dbl_payments.md)\(for the Dashboard interface\). ### Monitoring payments and orders {#en_cms_prestashop_usage_monitoring} Information about payments processed with the use of the Ecommpay payments plug-in and about the corresponding orders can be monitored via the PrestaShop interfaceby using the tools of the **Orders** section in the similarly-named subsection, while more detailed information about payments and refunds can be obtained via Dashboard \([details](en_dbl_payments.md)\) and Data API \([details](en_dbl_using_api.md)\) from Ecommpay. In the PrestaShop interface, the **Orders** subsection contains orders register with main details about every order including the capabilities to search and filter data, open the tabs of separate orders, and perform various actions. ![](images/ecommpay/cms/prestashop/cms_prestashop_orders.png "Orders register in the PrestaShop interface") To open the tab of a particular order, click on the order's entry \(or the button ![](images/universal/cms/prestashop/cms_prestashop_icon_view.png)\) in the register. Each tab, among other functions, provides order details \(such as the information about customers, purchased products, and shipping methods\) as well as the capability to make refunds. For information about the payment initiated via the plug-in from Ecommpay, use the **Payment** section.This section displays the information about the payment amount and currency and other relevant data. Along with that, keep in mind that specific information regarding the status and details of the payment \(in particular, the payment method selected by the customer\) is updated based on the callbacks received from the payment platform. ![](images/ecommpay/cms/prestashop/cms_prestashop_order_tab.png "Order tab in the PrestaShop interface") More detailed information about working with orders can be obtained by using the **Help** button in the similarly-named subsection in the **Orders** section in the PrestaShop interface. ## Parameters for using payment methods {#en_cms_prestashop_methods} When working with the plug-in from Ecommpay, in the PrestaShop interface, you can set up the usage of various payment methods available in the merchant's project. You can do this on the page with the plug-in operation parametersvia separate tabs—for example, **Card Settings** \(with parameters for card payments\), **Apple Pay** \(with parameters for payments with the Apple Pay service\), **Google Pay** \(with parameters for payments with the Google Pay service\), and **More Methods** \(with parameters for payments with other alternative methods\). The tabs for payment methods setup contain the following parameters: - General parameters: - **Enabled**—the feature for enabling a payment method to work via the plug-in. To enable a method, select the **Enabled** checkbox. By default, the checkbox is not selected. - **Title**—the payment method namedisplayed on the checkout page in the web service. - **Description**—the text displayed to the customers when they select a certain payment method. - Parameters used only in the **Card Settings** tab: - **Display mode**—the option for opening the Payment Page payment form. One of the following options can be selected: - **Redirect**—opening as a separate HTML page; - **Popup**—opening in a modal window; - **Embedded**—opening in an iframe element. After installing the plug-in or updating its version, this option is set up by default. ![](images/ecommpay/cms/prestashop/cms_prestashop_settings_card.png "Card Settings tab with parameters for card payments") If the payment form is opened in an iframe element\(the **Embedded** option\), then, when the customer selects to make the purchase using a payment card, the Payment Page payment form is displayed in the section with payment options on the checkout page, is adapted to the standard checkout page design in the web service, and does not contain the button for confirming the purchase. In this payment form, the customer can select the payment card credentials \(if they were saved earlier\) or specify them and then confirm the purchase by using the checkout button on the web service page. When selecting other payment methods, the customer is redirected to subsequent pages. ![](images/ecommpay/cms/prestashop/en_cms_prestashop_pp_embedded.png "Example of opening Payment Page on the checkout page in an inframe element") - The parameter used only in the **More Methods** tab: - **Payment method code**—the code of a payment method used as the only additional one \(in relation to the methods which are set up via separate accordion items\). - Without this parameter used, when the customer selects a payment method in the web service interface, they can select the option specified in the **Title** field \(**More payment methods** is the default option\), proceed to the payment form, and select one of the methods available for the payment initiated in the Ecommpay platform.Along with that, all methods from Ecommpay that can be selected directly in the web service \(together with the **More payment methods** option\) become available in the payment form. - With this parameter containing the code of one of the available methods\(taken [from the reference](en_pm_codes.md)\), when the customer selects a payment method in the web service interface, among other available methods they can select the one specified via the code and proceed to paying with this method without selecting any other methods in the payment form.To prevent issues that may be triggered by such a selection, alongside the payment method code, the name of the method should also be specified in this section \(in the **Title** field\). ![](images/ecommpay/cms/prestashop/cms_prestashop_settings_pm.png "More Methods tab with parameters for other alternative methods")