Using ecommpay WooCommerce plug-in for WordPress CMS

Overview

This article covers the information about using the WooCommerce plug-in version 2.1.0 provided by ecommpay for various web services that are based on the CMS WordPress version 5.0 or later and that use the WooCommerce plug-in version 4.0 or later.

The WooCommerce plug-in of ecommpay allows:

  • processing purchases with the use of payment methods available in the merchant's project;
  • issuing partial and full refunds with the use of payment cards via the WooCommerce interface and with the use of other payment methods via the Gate and Dashboard interfaces;
  • processing, suspending, resuming, changing the conditions of, and cancelling regular purchases (subscriptions) with the use of the WooCommerce Subscriptions extension; for working with subscriptions, payment cards and the Apple Pay and Google Pay payment methods can be used.

Along with that, when working with the plug-in, merchants can use different additional capabilities—the ones provided by ecommpay for Payment Page (details) and the ones provided by the WooCommerce developers for web services. For example, it is possible to support the capability of payment retries for the customers and set up the shipping zones. Such capabilities can be helpful in adjusting to various region-specific requirements, improving the user experience, and increasing the payment form conversion and payment acceptance.

For setting up 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 WooCommerce 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, opening Payment Page is requested and automatic receipt of callbacks is provided in accordance with the plug-in parameters.

Figure: The purchase processing steps with the use of the WooCommerce plug-in

  1. The customer initiates the purchase on the merchant's web service side with the use of the WooCommerce plug-in.
  2. The request for opening Payment Page is generated in accordance with the plug-in parameters.
  3. The request for opening Payment Page is received in the payment platform
  4. The request is processed in the payment platform.
  5. The requested payment form is generated in accordance with the plug-in parameters.
  6. The payment form is displayed to the customer.
  7. The customer completes the required actions for purchase.
  8. The purchase request is received in the platform.
  9. The request is sent to the payment environment.
  10. The request is processed in the payment environment.
  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.
  13. The purchase result information is sent from the payment platform to Payment Page.
  14. The purchase result information is displayed to the customer on the payment form.

The orders created on the web service side are assigned the statuses used by WooCommerce (details), while the payments processed via the ecommpay payment platform are assigned the statuses used by ecommpay (details).

Installation

To start using the WooCommerce plug-in version 2.1.0 provided by ecommpay, download and install it. Along with that, if an earlier version of this plug-in was used, deactivate the plug-in before installation.

To install the plug-in version 2.1.0 (or update the plug-in to this version), go to the WordPress interface and proceed as follows:

  1. Go to the Plugins section and select Add New.
  2. Click the Upload Plugin button.
  3. Select the downloaded zip file with the plug-in.
  4. Click the Install Now button and wait for the installation completion.
    Note: If before the plug-in update, the previous version has not been deactivated, then, after the plug-in version 2.1.0 is installed, click the Run the updater button to update the settings. Otherwise, the plug-in can work incorrectly.
  5. Activate the plug-in using the Activate button.

Testing

Overview

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

  1. Testing in the plug-in test mode. In this mode, the following is available: working with regular purchases (if the WooCommerce Subscription extension is used), processing test payments and refunds for these payments, and receiving information about the orders and payments created in the test mode (for more information, see the WooCommerce documentation).
  2. Testing in the test environment of the ecommpay payment platform. In this mode, processing payments with the use of test cards is available, while processing payments with the use of other payment methods should be coordinated with the ecommpay technical support specialists. To use this option, get the access to the ecommpay test environment (this can be done via the company's website), after which ecommpay provides you with the test project identifier and the corresponding secret key—use them as the values for the parameters required for the plug-in operation.

Parameters setup

To prepare for processing test payments, the merchant should decide on the preferable testing option, set up the corresponding mode of the plug-in, and specify the plug-in parameters. To set up the plug-in for processing test payments without actual debiting of funds, proceed as follows:

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

    For this, go to the WooCommerce section, select Settings in the drop-down menu, go to the Payments tab, select ecommpay and click the Manage button.

  2. Set up the capability of using the WooCommerce plug-in provided by ecommpay.

    For this, go to the General tab and select the Enable plugin checkbox.

  3. Set up the plug-in mode.

    For working in the test mode, select the Test mode checkbox in the General tab, for switching to the production mode—disable the checkbox.

  4. When setting up the production mode, specify the parameters required for connecting to the payment platform test environment:
    • Project ID—the test project identifier received from ecommpay.
    • Secret Key—the secret key for interacting with ecommpay.
  5. If necessary, specify other plug-in parameters. For example, the parameters for working with the payment form.
    • Display mode—the option for displaying the payment form: in an iframe object, in a modal window, or in a current tab.
    • Close on misclick—the mode in which the modal window with the payment form closes with a mouse click outside of this window.
    • Language—the language in which the payment form is displayed.
  6. Save the plug-in parameters.

    For this, click the Save changes button.

Processing test purchases and refunds

After the plug-in is set up, it is recommended to process test purchases in the web service and get the purchase information via the WordPress interface in the Orders section. For processing purchases via the plug-in test mode, you can use the numbers of the test cards provided in the WooCommerce documentation, while for testing via the ecommpay test environment, you can use the numbers of the test cards provided in the ecommpay documentation and get the needed final statuses of purchases.

After processing test purchases, you can test refunds. For this, proceed as follows:

  1. Open the orders list.

    For this, open the WooCommerce section and select Orders in the drop-down list.

  2. Select the order that should be refunded and click the Refund button.

    Note that issuing refunds is possible only for the orders with the status Processing or Complete.

  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, add the refund description in the Reason for refund field.
  5. Confirm the refund.

    For this, click the Refund via ecommpay button.

Figure: Order tab

After processing the refund, check if the order amount has changed by the refund amount and if the notification about the performed operation has been received (this notification is displayed in the right sidebar Order notes). In case of a partial refund, the order gets one of the statuses: Processing or Complete, while in case of a full refund, the order gets the status Refunded.

Usage

Overview

For processing payments with actual debiting of funds, the merchant should connect to the ecommpay production environment (for this, submit the application for connecting to the ecommpay payment platform and provide all necessary information) and use the obtained project identifier and secret key as the required parameters of the plug-in production mode.

The plug-in production mode provides the following capabilities:

  • Processing purchases and issuing partial and full refunds for these purchases.
  • Automatic Payment Page opening in accordance with the specified parameters.
  • Displaying information about the created orders and their current statuses in the WordPress interface.
  • Displaying information about payments and their current statuses in the WordPress interface.

Along with that, with the WooCommerce Subscription extension, the following is available in the production mode:

  • Extending the range of your web service products with the subscription products (with a subscription, the debiting of funds can be initiated by the merchant and performed automatically based on a set schedule and a fixed amount) and specifying the properties of each subscription product, including the following ones: the payment amount and schedule (daily, weekly, monthly, etc.), sign-up fee, and free trial period (details).
  • Registering, processing, suspending, cancelling, resuming, and changing the conditions of regular purchases with the use of payment cards and the use of the Apple Pay and Google Pay payment methods. (details).
  • Buying several subscription products within one order.
  • Informing customers about various subscription related events, for example, about debiting of funds, suspending, cancelling, and resuming subscriptions, about the debiting attempt failures and the requirement to make a purchase (details).

Setup of Payment group parameters

To process real payments, the merchant should provide the technical support specialists with the name and the URL of the web service, for which the WooCommerce plug-in is to be used, the currency in which payments are to be processed, and the URL for receiving notifications. After that, set up the plug-in production mode, then, in the Payment group parameters (required for processing payments), specify the identifier of the production project and the secret key, including other parameters described further.

Ultimately, 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, go to the WooCommerce section, select Settings in the drop-down menu, select ecommpay on the Payments tab, and click the Manage button.

  2. Set up the capability of using the WooCommerce plug-in provided by ecommpay.

    For this, go to the General tab and select the Enable plugin checkbox.

  3. Set up the plug-in mode.

    For this, disable the Test mode checkbox.

  4. Specify the plug-in required parameters.
    • Project ID—the production project identifier received from ecommpay.
    • Secret Key—the secret key for interacting with ecommpay.
  5. If necessary, specify other plug-in parameters, such as:
    • The parameters for displaying the payment option in the web service:
      • Title—the name of the payment option.
      • Customer message—the text displayed to the customer when they select ecommpay as the payment option.
      • Order button text—the name of the button used for proceeding to payment (for example, ‘Pay for order’).
    • The parameters for working with the payment form.
      • Display mode—the option for displaying the payment form: in an iframe object, in a modal window, or in a current tab.
      • Close on misclick—the mode in which the modal window with the payment form closes with a mouse click outside of this window.
      • Language—the language in which the payment form is displayed.
    • The parameters in the Shop Admin tab.
      • The capability of displaying payment statuses in the Orders section.

        For this, go to the Shop Admin tab and select the Fetch Payment Info checkbox.

      • If, within the project in use, it is relevant to display additional fields for gathering customer information (and sending this information to the ecommpay payment platform) in the payment form, select these fields.

        For this, go to the Shop Admin tab and select the available options in the Additional Information parameter.

  6. Save the plug-in parameters.

    For this, click the Save changes button.

Setup of Subscriptions group parameters

If the WooCommerce Subscriptions extension is used, the additional tab Subscriptions appears in the WooCommerce section. This tab contains the parameters of the Subscriptions group that are relevant for working with regular purchases. With these parameters, you can, for example, customise text for buttons that is displayed in the web service when the customer makes a purchase and adds subscription products to the cart. You also can set up the options for resuming subscriptions and other parameters.

Figure: Subscriptions tab

The information about working with regular purchases via the WooCommerce Subscriptions extension is provided in the WooCommerce documentation.

Controlling orders

After the orders have been created, the information about them can be obtained in the Orders subsection of the WooCommerce section. In this subsection, you can search and filter the data, and below you can find the list of orders (Order), the order creation date (Date), the order amount (Total), and other information.

If the Fetch Payment Info checkbox is selected in the plug-in parameters, then for each order, the corresponding payment status (Payment) used in the ecommpay payment platform is displayed.

Figure: Orders list

The detailed order information, which includes the order creation date, the purchase amount, the payment option and status, delivery address, and other data, is provided in the order tab. The order tab also contains the following sidebars:

  • Order Notes—displays various notifications, for example, about the change of an order status and the status of a corresponding payment.
  • ecommpay Payment—displays the payment information which includes the payment amount, currency, identifier, and method, and the operation type and status used in the ecommpay payment platform. This tab also contains relevant information about the payment in the ecommpay platform.

Figure: Order tab

The information about working with orders is also provided in the WooCommerce documentation.

Controlling subscriptions

The information about regular purchases is provided in the Subscriptions subsection of the WooCommerce section. Here, just as in the Orders subsection, the capability of searching and filtering data is supported. The more detailed information about a regular purchase, including its status and amount and the date of the next payment is provided in the subscription tab.

Figure: Subscriptions list

The information about working with regular purchases is provided in the WooCommerce documentation.