Using ecommpay payments for PrestaShop CMS

Overview

This article covers the information about using the payment plug-in ecommpay payments version 1.0.2. This plug-in version can be used in web services that are based on the PrestaShop CMS version 8.1.5 or later and allows opening the Payment Page payment form of ecommpay for customers and ensuring all necessary actions for payment processing.

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).

Figure 1. Administrative interface PrestaShop
Figure 2. Interface of the Payment Page payment form

General information

Capabilities

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.

  • Testing the operation of the payment form and the capabilities of payment processing.

    For initial testing, you can just use the plug-in test mode (with no additional actions required), while for deeper testing, you can get a test project in the ecommpay payment platform (by leaving an application on the company's main site).

  • Processing one-time one-step purchases with the use of various payment methods.

    For resolving all organisational issues and 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).

  • 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 Open Banking methods, provide customers with the capability of payment retries (details), and set up sending notifications to customers about the purchased goods and services (details). To have such capabilities set up, contact the ecommpay technical support specialists.

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

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.

Figure 3. The purchase processing steps with the use of the plug-in
  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 either in the Payment Page payment form (if the form was opened in a separate tab) or on the web service page (if the form was opened in a modal window).

For interaction with customers when processing purchases, the payment form can be opened in a separate tab or in a modal window. In both cases, the customer first confirms they are ready to proceed to payment (using the PLACE ORDER button in the web service), then specifies the needed data and confirms the payment to be created in the ecommpay platform (using the corresponding fields and the Pay button in the payment form that opens).

Along with that, it should be considered 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 used when working with the ecommpay payments plug-in. Depending on the states of payments in the platform, the following statuses can be used:

  • 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 correspond to the numbers of orders in the web service and statuses used by ecommpay (details).

With questions about the statuses of payments and orders, address the ecommpay account manager.

Installation

To start using the ecommpay Payments plug-in version 1.0.2, 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 on GitHub 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 download completion (the plug-in installation is performed automatically at this step).

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.

Figure 4. Module Manager page with the plug-in panel in the PrestaShop interface

Testing

Overview

For testing the plug-in operation and processing test payments without actual debiting of funds, there are the following options available:

  • Testing in the plug-in test mode. This is the option to carry out local basic testing of the payment form operation and separate scenarios card paymentswithout connecting the merchant's web service to the ecommpay payment platform. It allows you to promptly check the payment form operation and separate scenarios of card payments.
  • Testing in the test environment of the ecommpay payment platform. This is the option to carry out integrated and fully-featured testing after connecting the merchant's web service to the ecommpay payment platform and setting up the platform's components. You can connect to the platform by using the corresponding form on the company's main site and the received identifier and key of the test project. In this case, the plug-in is switched to the production mode and allows you to test a greater number of payment scenarios, including payments via alternative methods available for testing (details), and all payments remain not real.

To compare the two testing options, refer to the following table.

Testing capabilities in the plug-in test mode in the test environment of the platform
Opening the payment form using various options and parameters of its operation + +
Processing one-time purchases + +
Using alternative payment methods (as coordinated with the ecommpay specialists) – +
Using addition capabilities of the Payment Page payment form (as coordinated with the ecommpay specialists) – +
Issuing refunds + +
Monitoring payment information + +
Managing orders + +

Regardless of the selected testing option (in the test mode or via the test environment of ecommpay), the plug-in is connected to the web service and becomes available to customers as the payment option. Thus, Regardless of the selected testing option, in cases when the plug-in is connected to a web service that operates in live mode, it is recommended to ensure that testing takes place during a low-load period and notify the customers about the ongoing testing activities.

Parameters 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 parameters of the plug-in operation:
    • Test mode—the capability to switch to the test mode of the plug-in operation.;

      For using the test mode of the plug-in, select this checkbox in the, for using the test environment of the platform—clear this checkbox and specify the parameters for connecting to the test environment received from ecommpay in the fields Project ID and Secret key.

      Note: When the plug-in test mode is enabled, the values specified in the fields Project ID and Secret key are ignored.
    • Project ID—the test project identifier.;
    • Secret key—the test project key.;
    • Title—the payment option name displayed on the checkout page in the web service.;
    • Description—the text displayed to the customers when they select the payment option with the use of the plug-in.;
      Note: If necessary, the fields Title and Description can be used for notifying customers that the plug-in is operating in the test mode.
    • Currency—the currency in which payments can be processed with the use of the plug-in.;
    • Language —the language in which the payment form is displayed.;
    • Popup mode—the capability to select the option for opening the Payment Page payment form in a modal window.;

      For opening the form in a modal window, select this checkbox. For opening the form in a separate tab, clear this checkbox.

    • Additional parameters—additional parameters for opening payment form. When specifying several parameters in this field, use the & symbol as a separator.
  3. Save the parameters of the plug-in operation.

    For this, click the Save Settings button.

Figure 5. Page with the parameters of the plug-in operation

Processing test purchases

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 (details). (including scenarios with the 3‑D Secure authentication) provided in the Test cards 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 article and in the corresponding sections of the articles about working with particular payment methods.

Processing test refunds

Overview

After processing test purchases, you can make test refunds via the PrestaShop interface and, if relevant, via the interfaces Gate and Dashboard 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 information provided in this subsection is also relevant for issuing refunds in the production environment.

Ensuring data synchronisation

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:

If the merchant needs to issue refunds via the ecommpay platform interfaces, it is important to ensure 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://<sitedomain>/en/module/ecommpay/callback), are configured.

    Information about working with conditions for sending callbacks is provided in a separate article.

  • The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

Procedures

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).

Figure 6. 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 (for the Gate API) and Issuing refunds (for the Dashboard interface).

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 service for which the ecommpay payments plug-in should be used and the currency in which payments are to be processed.

After that, you can switch the plug-in to the production mode, specify the received 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, after the setup, you need to suspend the plug-in operation, for example, to test some additional features, the plug-in can be switched to the test mode or disabled.

Parameters 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 parameters of the plug-in operation:
    • Test mode—the capability to switch to the test mode of the plug-in operation.;

      For using the production environment of the platform, clear this checkbox and specify the parameters for connecting to the platform received from ecommpay in the fields Project ID and Secret key.

    • Project ID—the production project identifier.;
    • Secret key—the production project key.;
    • Title—the payment option name displayed on the checkout page in the web service.;
    • Description—the text displayed to the customers when they select the payment option with the use of the plug-in.;
      Note: If during testing the fields Title and Description were used for notifying customers about ongoing testing activities, when switching the plug-in to production mode, it is important to remove the notifications.
    • Currency—the currency in which payments can be processed with the use of the plug-in.;
    • Language —the language in which the payment form is displayed.;
    • Popup mode—the capability to select the option for opening the Payment Page payment form in a modal window.;

      For using the option for opening the form in a modal window, select this checkbox. For using the option for opening the form in a separate tab, clear this checkbox.

    • Additional parameters—additional parameters for opening payment form. When specifying several parameters in this field, use the & symbol as a separator.
  3. Save the parameters of the plug-in operation.

    For this, click the Save Settings button.

Figure 7. Page with the parameters of the plug-in operation

Processing purchases

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.

Warning: Starting August 12, 2024, Visa Rules will be updated to expand the data set mandatory for processing Visa card payments with the 3‑D Secure authentication. 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

After processing purchases, you can issue refunds as part of these purchases via the PrestaShop interface and, if relevant, via the interfaces Gate and Dashboard 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

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:

If the merchant needs to issue refunds via the ecommpay platform interfaces, it is important to ensure 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://<sitedomain>/en/module/ecommpay/callback), are configured.

    Information about working with conditions for sending callbacks is provided in a separate article.

  • The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

Procedures

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).

Figure 8. 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 (for the Gate API) and Issuing refunds (for the Dashboard interface).

Monitoring payments and orders

Information about payments processed with the use of the ecommpay payments plug-in and about the corresponding orders can be monitored via the PrestaShop interface by 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) and Data API (details) from ecommpay.

In the PrestaShop interface, the Orders subsection contains orders register with main details about every orderincluding the capabilities to search and filter data, open the tabs of separate orders, and perform various actions.

Figure 9. Orders register in the PrestaShop interface

Clicking on an order's entry leads you to the order's tab providing the order details and the capability to make refunds.To open the tab of a particular order, click on the order's entry (or the button ) 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.

Figure 10. 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.