Using ecommpay Payments plug-in for WordPress CMS

This article covers the information about using the payment plug-in ecommpay Payments version 3.4. This plug-in version enhances the capabilities of the WooCommerce plug-in version 4.0 or later for web services that are based on the WordPress CMS version 5.0 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 WordPress 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: Administrative interface WordPress

Figure: Interface of the Payment Page payment form

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 WordPress CMS.

• Setting up the usage of separate payment methods available in the merchant's project.

  For this, you can use the tabs with parameters of using payment methods in the plug-in tab of the WordPress interface.

• 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 (within a few minutes by leaving an application on the company's main site).

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

  For using different payment methods, you may need to either configure a minimum of the plug-in parameters or take no actions at all, while all organisational issues can be resolved in cooperation with the ecommpay account manager.

• Registering and processing COF purchases (subscriptions) with the direct use of payment cards and the use of the Apple Pay and Google Pay methods—if the web service has the WooCommerce Subscriptions extension installed.

  For this, you can manage the properties of such purchases (such as the payment amount and schedule, free trial period), inform customers about subscription related events, and combine different purchases into a single order.

• Issuing partial and full refunds for purchases, which were processed with the help of the plug-in.

  For this, you can use the WordPress interface and if relevant—the Gate and Dashboard interfaces of the ecommpay payment platform.

• Monitoring the information about payments, which were processed with the help of the plug-in.

  For this, you can use the WordPress interface and if relevant—the Dashboard interface from ecommpay, with the information in these interfaces synchronised (except for the cases when the refunds were made via Gate or Dashboard; in such cases, the payment statuses may not be updated in the WordPress interface).

• Managing orders with related purchases processed with the help of the plug-in—via the WordPress interface.

  This includes cancelling and deleting 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 these capabilities set up, contact the ecommpay technical support specialists.

• Using various capabilities provided by the developers of the WooCommerce plug-in.

  Particularly, you can set up the usage of this plug-in (and the connected ecommpay Payments plug-in) in different countries (details).

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. With questions about using various capabilities for the WooCommerce plug-in, refer to the documentation on the corresponding portal.

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 WooCommerce and ecommpay Payments plug-ins, 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.

Usually, in case of working with the ecommpay Payments plug-in, an order is created after the customer proceeds to a purchase from the checkout page and before they confirm this purchase. In this case, the payment identifier consists of the number of the order and the number of the attempt to pay for this order in the web service (for example, the identifier can be 123_2 if the customer made two attempts to pay for order number123). Along with that, if the capability of payment retries is set up, the final digit of the payment identifier always equals to one, since all payment retries are made within one payment (for example, the identifier can be 123_1 even if the customer made at least two attempts to pay for the order).

If the Payment Page payment form is opened in the iframe element (details), the order is created only after the customer confirms the purchase. In this case, the payment identifier consists of the wp_ prefix and an arbitrary sequence of ten characters (for example, wp_ert12h2t1o), without the number of order and the number of the attempt to pay for this order included. Along with that, the capability of payment retries is not supported for this option of opening the payment form, all purchase attempts are made with the payment form reopened.

The purchases that are processed according to the provided workflow via the ecommpay payment platform are assigned the statuses used by ecommpay (details), while the orders created on the web service side are assigned the statuses used by WooCommerce (details). You can monitor the information about these payments and statuses in the sections of the WordPress interface: Orders (for one-time purchases) and Subscriptions (for COF purchases). With questions about the statuses of payments and orders, address the ecommpay account manager.

General information

To start using the ecommpay Payments plug-in version 3.4, you need to install it. Along with that, if an earlier version of this plug-in was previously used, it is recommended to deactivate this version before installing the new one (you can do it through the list of installed plug-ins in the WordPress interface). There are two ways to install the plug-in in the WordPress interface—via the plug-ins directory of WordPress (without prior download of the plug-in file) or via the plug-ins upload function in the WordPress interface (with the plug-in file downloaded beforehand). The plug-in file can be downloaded from the directory or from GitHub.

Installation via the plug-ins directory

To install the plug-in via the directory, go to the WordPress interface and proceed as follows:

1. Select the Plugins section in the navigation menu and the Add New item in the menu that appears.
2. Search for the ecommpay Payments plug-in from ecommpay using the search box on the page that opens.

   For this, use the search box on the right side of the page and ensure that the plug-in in the search results is provided by ecommpay (this is stated on the plug-in panel).

3. Click the Install now button (or the Update Now button if an earlier plug-in version was used) on the panel and wait for the installation completion.

   Figure: The CMS WordPress page used for installing plug-ins from the directory

   

4. Activate the plug-in using the Activate button, which is displayed instead of the Install now button (or instead of the Update Now button) after the installation.
5. If the plug-in is being installed for the web service that is already in live mode and the previous version was enabled—check that the plug-in has not been automatically connected to the web service as a result of the activation (in order to ensure the plug-in is not available to customers before the parameters setup).

   For this, proceed as follows: ensure that, for all methods set up in the plug-in, the Enable toggle switch is off.

   1. Go to the Payments tab in the Settings subsection of the WooCommerce section.
   2. Find the payment methods for working with ecommpay in the Method column and ensure that the Enable toggle switch is off for all the methods (and switch it off if needed).

Installation via the plug-ins upload function

To install the plug-in using the upload function, go to the WordPress interface and proceed as follows:

1. Select the Plugins section in the navigation menu and the Add New item in the menu that appears.
2. Click the Upload Plugin button on the page that opens.

   Figure: The CMS WordPress page used for installing plug-ins via the upload function

   

3. Select the previously downloaded zip file of the plug-in.
4. Click the Install Now button and wait for the installation completion.
5. Click the Activate Plugin button for activation (if the plug-in has not been installed in the web service) or the Replace current with uploaded button for the version update (if the plug-in has already been installed).
   Note: After an attempt to update the plug-in, you may see a notification in the WordPress interface stating that the plug-in cannot be updated and find its both versions—the previous and new one—on the list of installed plug-ins. This can happen when the names of zip files with the previous and the new version are different. When this is the case, deactivate and delete the previous version and active the new one for the plug-in to operate correctly.
6. If the plug-in is being installed for the web service that is already in live mode and the previous version was enabled—check that the plug-in has not been automatically connected to the web service as a result of the activation (in order to ensure the plug-in is not available to customers before the parameters setup).

   For this, proceed as follows: ensure that, for all methods set up in the plug-in, the Enable toggle switch is off.

   1. Go to the Payments tab in the Settings subsection of the WooCommerce section.
   2. Find the payment methods for working with ecommpay in the Method column and ensure that the Enable toggle switch is off for all the methods (and switch it off if needed).
7. If a notification about the needed parameters update is displayed in the WordPress interface—click the Run the updater button and wait for the update completion.

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 to the ecommpay payment platform. It allows you to promptly check the payment form operation and separate scenarios of card payments. In this mode, the statuses of test payments contain the code word Test (for example, Test Success). This can be convenient for monitoring the processing of 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 to the ecommpay payment platform and setting up its components. You can connect to the platform within a few minutes 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). All payments remain not real (although, their statuses do not contain the code word Test and all information displayed in the WordPress interface resembles real-life conditions).

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

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 WordPress interface. For this, proceed as follows:

1. Open the plug-in tab in the WordPress interface.

   For this, proceed as follows:

   1. Go to the Payments tab in the Settings subsection of the WooCommerce section.
   2. Find one of the payment methods set up for working with ecommpay in the Method column and click the General settings button in the corresponding line.
2. Switch the plug-in to the needed mode and set up the basic parameters of the plug-in operation:
   • Demo mode—the feature for switching the plug-in operation mode.

     For using the test mode of the plug-in, select the Enable Demo mode checkbox in the General tab, 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. Thus, to use the project of the ecommpay payment platform, you should disable the plug-in test mode.
   • Project ID—the test project identifier.
   • Secret Key—the test project key for interacting with the platform.
   • Language—the language in which the payment form is displayed.

   Figure: The General tab with basic parameters for setup

   

3. If necessary, specify additional plug-in parameters.:

   For this, click the Advanced settings link on the General tab and set up the parameters in the sections Transaction Cache and Shop Admin Setup:

   • Enable Caching—the feature for caching payment data to optimise the plug-in operation in the web service.
   • Cache Expiration—the duration of cached data storage in seconds.
   • Log Level—the level of logging the plug-in operation.

     The information about created logs is provided on the Logs tab in the Status subsection of the WooCommerce section.

   • Fetch Payment Info—the feature for displaying payment statuses in the Orders section.

     For the payment statuses to be displayed in the Orders section, select the Enable checkbox, otherwise, clear the checkbox. By default, the checkbox is selected.

   Figure: The General tab with additional parameters for setup

   

4. Save the basic plug-in parameters.

   For this, click the Save changes button.

5. Set up the parameters for using payment methods (details).

   During the work in plug-in test mode, you only need to set up the parameters for card payments on the Card settings tab.

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 WordPress interface. in 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 numbers 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 sections about testing particular payment methods.

Processing test refunds

After processing test purchases, you can make test refunds. For this, you can use the Gate and Dashboard interfaces from ecommpay as well as the WordPress interface. But we recommend using the latter, since, if you make refunds via Gate or Dashboard, the payment statuses in the WordPress interface may not be updated. Note that refunds can be made for orders with the statuses Processing or Completed, and for payments with the statuses success or partially refunded.

To make a refund via the WordPress interface, proceed as follows:

1. Open the orders register.

   For this, open the WooCommerce section and select the Orders item in the menu that appears.

2. Select the order that should be refunded and click the Refund button in the order tab that opens.
3. Specify the number of the items that should be returned (in this case, the refund amount is calculated automatically) or specify the refund amount without changing the number of items in the order.
4. If necessary, specify the reason for the refund in the Reason for refund field.
5. Confirm the refund.

   For this, click the Refund via ecommpay button.

6. Ensure that the order amount has changed by the refund amount and the right sidebar Order notes displays the notification about the performed operation.

   In case of a partial refund, the order is assigned one of the statuses: Processing or Completed, while in case of a full refund, the order is assigned the status Refunded.

Figure: The order tab in the WordPress interface

General information

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 is set up 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.

Setup of the parameters for one-time purchases

To set up the plug-in for processing one-time purchases, proceed as follows:

1. Open the plug-in tab in the WordPress interface.

   For this, proceed as follows:

   1. Go to the Payments tab in the Settings subsection of the WooCommerce section.
   2. Find one of the payment methods set up for working with ecommpay in the Method column and click the General settings button in the corresponding line.
2. Switch the plug-in to the needed mode and set up the basic parameters of the plug-in operation on the General tab:
   • Demo mode—the feature for switching the plug-in operation mode.

     For using the test environment of the platform, clear the Enable Demo mode 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 for interacting with the platform.
   • Language—the language in which the payment form is displayed.

   Figure: The General tab with basic parameters for setup

   

3. If necessary, specify additional plug-in parameters.:

   For this, click the Advanced settings link on the General tab and set up the parameters in the sections Transaction Cache and Shop Admin Setup:

   • Enable Caching—the feature for caching payment data to optimise the plug-in operation in the web service.
   • Cache Expiration—the duration of cached data storage in seconds.
   • Log Level—the level of logging the plug-in operation.

     The information about created logs is provided on the Logs tab in the Status subsection of the WooCommerce section.

   • Fetch Payment Info—the feature for displaying payment statuses in the Orders section.

     For the payment statuses to be displayed in the Orders section, select the Enable checkbox, otherwise, clear the checkbox. By default, the checkbox is selected.

   Figure: The General tab with additional parameters for setup

   

4. Save the basic plug-in parameters.

   For this, click the Save changes button.

5. Set up the parameters for using payment methods (details).

Setup of parameters for COF purchases

In order to set up registering and processing of COF purchases (subscriptions) with the use of the ecommpay Payments plug-in and the WooCommerce Subscriptions extension, you should set up the parameters of the ecommpay Payments plug-in (according to the setup instructions for one-time purchases) and use the tools available in the WooCommerce plug-in tab of the Subscriptions tab. On the Subscriptions tab, it is possible to set up different parameters, including the following ones: the names of the buttons, which are used for adding the products to the cart and paying for them, options of COF purchases renewal after their suspension, and other parameters. Information about working with COF purchases via the WooCommerce Subscriptions extension is provided in the WooCommerce documentation.

Figure: The Subscriptions tab with parameters for COF purchases setup

Issuing refunds

For purchases processed with the use of the ecommpay Payments plug-in, you can make partial and full refunds—for orders with the statuses Processing or Completed and for payments with the statuses success or partially refunded. Refunds can be made via the WordPress interface (for card payments) and via the interfaces of the ecommpay payment platform (for payments made with any payment method set up in the project): the programming interface Gate and the user interface Dashboard (with the tools for making individual and batch requests). In case of refunds via the WordPress interface, all information about them can be obtained via this interface and the interfaces of the payment platform (for example, Dashboard and the Data API), since all information is synchronised. Along with that, note that, in case of refunds via the payment platform interfaces, the statuses of payments and orders can remain unchanged in the WordPress interface, however, you can change the statuses of order manually.

In order to make a refund, via the WordPress interface, proceed as follows:

1. Open the orders register.

   For this, open the WooCommerce section and select the Orders item in the menu that appears.

2. Select the order that should be refunded and click the Refund button in the order tab that opens.
3. Specify the number of the items that should be returned (in this case, the refund amount is calculated automatically) or specify the refund amount without changing the number of items in the order.
4. If necessary, specify the reason for the refund in the Reason for refund field.
5. Confirm the refund.

   For this, click the Refund via ecommpay button.

6. Ensure that the order amount has changed by the refund amount and the right sidebar Order notes displays the notification about the performed operation.

   In case of a partial refund, the order is assigned one of the statuses: Processing or Completed, while in case of a full refund, the order is assigned the status Refunded.

Besides, it is possible to make manual refunds (in cash or by other means, without the refund information being registered in the ecommpay payment platform). In such cases, it is recommended to register refund information in the plug-in interface using the Refund manually button.

Monitoring payments and orders

The information about payments (including series of debits as part of COF purchases) processed with the use of the ecommpay Payments plug-in and about the corresponding orders can be monitored via the WordPress interface via the tools of the Orders subsection in the WooCommerce section.

Additionally, the payment information can be obtained via the Dashboard interface from ecommpay (details). This interface provides the information about payments and refunds processed via the ecommpay payment platform, but it does not display information about orders.

The Orders subsection contains an orders register with main details about every order and with the capabilities of searching and filtering data, as well as opening the tabs of separate orders and performing various actions related to the orders. (Alongside order statuses, the register can also contain payment statuses—if the Fetch Payment Info checkbox in the plug-in parameters is selected.)

Figure: The Orders register in the WordPress interface

Clicking on an order's entry leads you to the order's tab containing the details about the order andTo open a tab of a particular order, click on the order's entry in the register. The tabs contain the details about orders and payments, such as the order creation date, the purchase amount, the payment option and status, delivery address, and other data. The tabs also contain the specialised panels:

• ecommpay Payment—with the payment information and the capability to update this information manually using the Refresh button.
• Order actions—with tools for performing various actions on the order.
• Order notes—with notifications about various events related to the order and the payment.

Figure: The order tab in the WordPress interface

More detailed information about working with orders in the WordPress interface is provided in the WooCommerce documentation.

Monitoring COF purchases

With the WooCommerce Subscriptions extension, you have the access to the Subscriptions subsection in the WooCommerce section. This subsection contains the information about COF purchases (in addition to the information displayed in the Orders subsection). Similarly to the Orders subsection, the Subscriptions subsection displays the subscriptions register with main details about every subscription and provides the capabilities of searching and filtering data as well as opening the tabs of separate subscriptions and performing various actions related to the subscriptions.

Figure: The Subscriptions register in the WordPress interface

More detailed information about working with COF purchases in the WordPress interface is provided in the WooCommerce documentation.