Using ECommPay plug-in for nopCommerce CMS

Overview

Introduction

This article covers the information about using the ECommPay plug-in for web services based on the CMS nopCommerce version 4.40 or later.

This plug-in allows merchants to execute purchases and issue full or partial refunds by using various payment methods that are supported for the Payment Page payment form. For more information about these payment methods, see this section. Along with that, when working with the plug-in, merchants can use different additional capabilities—the ones provided by ECommPay for Payment Page (for more information, see Additional capabilities) and the ones provided by the CMS nopCommerce developers for this system. For example, it is possible to support the capability of payment retries for the customers and restrict payments coming from different countries (for more information about this capability, see Payment method restrictions). Such capabilities can be helpful in adjusting to various region-specific requirements, improve the user experience, and increase 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 our technical support specialists.

Workflow scheme

The following diagram illustrates the workflow of executing purchases with the use of the ECommPay plug-in. The workflow involves the customer, the merchant web service with the built-in plug-in, the Payment Page payment form, 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 ECommPay plug-in

  1. The customer initiates the purchase with the use of the ECommPay plug-in on the merchant web service side.
  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 purchase actions.
  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 Payment Page.

Each order created on the web service side corresponds to a purchase with one of the possible statuses: Pending, Authorized, Paid (captured), Partially refunded, Refunded, Voided—in accordance with the CMS nopCommerce payment model. The information about managing orders using the nopCommerce interface is presented in the CMS documentation.

Installation and setup

To start using the ECommPay plug-in, download it in the nopCommerce online marketplace and install it in one of the following ways:

  • Move the plug-in files to the /plugins folder of the nopCommerce root directory.
  • Download the archive with the plug-in files via the nopCommerce interface.

    For this, in the Configuration section, select Local plugins, click the Upload plugin or theme button, and select the corresponding file for downloading.

Note: For more information about installing and uninstalling plug-ins as well as configuring the parameters for using them in the nopCommerce CMS and the CMS-based web services, see the nopCommerce documentation .

After installing the plug-in, you can specify its parameters in the plug-in tab. It is recommended to test the plug-in work first using the test parameters, after that specify the parameters for processing real payments and start using the plug-in in the production mode.

To open the plug-in tab in the nopCommerce interface, go to the Configuration section, select Payment methods, and click the Configure button in the line with the plug-in name. The ECommPay plug-in tab contains a short instruction about using the plug-in and the fields for setting up the plug-in parameters. The descriptions of the parameters for testing the plug-in and using it for processing real payments are presented in the following sections of this article.

Figure: Plug-in tab



Testing

Overview

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

  • using the plug-in test mode;
  • using the test environment of the ECommPay payment platform.

The second option can be considered more functional since it implies the plug-in work in the production mode and the capability to control the changes of the order statuses in the CMS. Additionally, this option requires the access to the ECommPay test environment (the access can be obtained via the company website), while testing in the plug-in test mode requires no additional actions. If needed, test operations can be performed with the both options applied. The way of testing the plug-in depends upon the merchant's choice.

Both testing options provide the following capabilities:

  • choosing the payment form display mode;
  • specifying the parameters for opening the payment form;
  • using different ways of calculating fees to be paid by the customer;
  • automatic Payment Page opening in accordance with the specified parameters when processing test purchases;
  • displaying information about the created orders and test purchases in the nopCommerce interface.

Additionally, in the plug-in production mode, it is possible to receive current information about the order statuses via the nopCommerce interface as well as the capability to test the receipt of callbacks with the information about the payment statuses. The callbacks are sent to the URL that the merchant provides when getting the access to the ECommPay test environment.

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 operation, and specify the plug-in parameters. Along with that, it should be noted that for working in the plug-in test mode, the minimum set of parameters described further can suffice, while testing in the ECommPay test environment additionally requires the two parameters: the project identifier and the secret key received from the ECommPay specialists when the merchant gets the access to the test environment.

Ultimately, to set up the plug-in for processing test payments without actual debiting of funds, the merchant should perform the following steps:

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

    For this, select Payment methods in the Configuration section and click the Configure button in the line with the ECommPay plug-in name.

  2. Setp up the plug-in mode.

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

  3. When setting up the mode for processing real payments—specify the required parameters for accessing the payment platform test environment:
    • Production project ID—the test project identifier received from ECommPay.
    • Production secret key—the secret key for interacting with ECommPay.
  4. Specify the available parameters of the plug-in.
    • Payment flow—the way of displaying the payment form to the customers: in a separate browser tab or in an iframe object embedded in the HTML page of the web service (for more information, see the Options to open Payment Page section). It is recommended to test different variants of displaying Payment Page and choose the one that is most suitable for the work.
    • Additional parameters—additional parameters for opening the payment form. For working with test payments, it is recommended to use the parameters that can be relevant in certain cases and check how they affect different payment processing scenarios. The list of the available parameters is presented in the Payment Page invocation parameters section. For specifying several parameters simultaneously, use the & sign as a separator. For example, if you want to set a particular language of the payment form and a certain payment method, specify them with the use of the corresponding parameters in the following format: language_code=fr&force_payment_method=card.
    • Additional fee—the fee amount to be paid by the customer. This parameter can be left unspecified (with the zero value) if there are no fees applied. If a fee is applied, the amount is specified with the fractional part separated by the decimal point and, with regards to the state of the Additional fee. Use percentage checkbox, can be defined in the following ways:
      • absolute, corresponding to the fee amount for each payment (for example, 1.20 in the currency used for processing the payment);
      • relative, corresponding to a specified percentage of the total amount of each payment

        (for example, 1.20%).

    • Additional fee. Use percentage—the indicator for using the relative fee. When this checkbox is selected, the relative fee amount is applied, when the checkbox is disabled, the absolute fee amount is applied.

    The Callback endpoint field contains the URL for receiving callbacks and is unavailable for editing. The URL is specified automatically and corresponds to the one that the merchant provides to the ECommPay specialists when getting the access to the test environment. For changing the URL, the merchant should contact the ECommPay technical support specialists.

  5. Save the plug-in parameters.

    For this, click the Save button.

Figure: The plug-in parameters in the test mode



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 nopCommerce interface: in the Orders subsection of the Sales section. For processing test purchases (with any of the testing options), the numbers of the test cards of different payment systems can be used and the necessary final statuses can be received.

During testing in the plug-in test mode, it is important to consider that the statuses of the orders created on the web service side cannot change, they are automatically assigned the Pending status. Changes of the order statuses can be monitored with the use of the ECommPay payment platform test environment.

Figure: Orders list



After processing test purchases, it is possible to test issuing refunds. For this, the merchant should perform the following steps:

  1. Open the orders list.

    For this, open the Sales section and select the Orders subsection.

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

    Note that issuing refunds is possible only for the orders for which the customers have already paid (Payment status = Paid).

  3. Open the tab with the purchase information, then do the following:
    • for issuing a full refund—click the Refund button and confirm this action;
    • for issuing a partial refund—click the Partial Refund button and specify the refund amount.

For the information about working with orders in the nopCommerce interface, see the documentation of the CMS.

Usage

Overview

For processing payments with actual debiting of funds, the merchant should access the ECommPay production environment (this can be done via the company website) 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:

  • selecting the payment form display mode;
  • specifying the parameters for opening the payment form;
  • using different ways of calculating fees to be paid by the customer;
  • automatic Payment Page opening in accordance with the specified parameters when processing real purchases;
  • receiving the purchase information in the callbacks;
  • displaying the information about the created orders and their current statuses in the nopCommerce interface;
  • displaying the purchase information in the nopCommerce interface.

Parameters setup

To process real payments, the merchant should get the access to the ECommPay production environment, switch to the plug-in production mode, and specify the plug-in parameters. In the production mode, it is required to specify the project identifier and the secret key that the merchant received from the ECommPay specialists when accessing the production environment. Additionally, it is possible to specify other parameters described further.

Ultimately, to set up the plug-in for processing real payments, the merchant should perform the following steps:

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

    For this, select the Payment methods subsection in the Configuration section and click the Configure button in the line with the ECommPay plug-in name.

  2. Set up the plug-in production mode.

    For this, the Test mode checkbox should be disabled.

  3. Specify the required plug-in parameters:
    • Production project ID—the production project identifier provided by ECommPay.
    • Production secret key—the secret key for interacting with ECommPay.
  4. Specify the available plug-in parameters.
    • Payment flow—the way of displaying the payment form to the customers: in a separate browser tab or in an iframe object embedded in the HTML page of the web service (for more information, see the Options to open Payment Page section).
    • Additional parameters—additional parameters for opening the payment form. The list of the available parameters is presented in the Payment Page invocation parameters section. For specifying several parameters simultaneously, use the & sign as a separator. For example, if you want to set a particular language of the payment form and a certain payment method, specify them with the use of the corresponding parameters in the following format: language_code=fr&force_payment_method=card.
    • Additional fee—the fee amount to be paid by the customer. This parameter can be left unspecified (with the zero value) if there are no fees applied. If a fee is applied, the amount is specified with the fractional part separated by the decimal point and, with regards to the state of the Additional fee. Use percentage checkbox, can be defined in the following ways:
      • absolute, corresponding to the fee amount for each payment (for example, 1.20 in the currency used for processing the payment);
      • relative, corresponding to a specified percentage of the total amount of each payment (for example, 1.20%).
    • Additional fee. Use percentage—the indicator for using the relative fee. When this checkbox is selected, the relative fee amount is applied, when the checkbox is disabled, the absolute fee amount is applied.

    The Callback endpoint field contains the URL for receiving callbacks with the information about payment processing and is unavailable for editing. The URL is specified automatically and corresponds to the one that the merchant provides to the ECommPay specialists when getting the access to the production environment. For changing the URL, the merchant should contact the ECommPay technical support specialists.

  5. Save the plug-in parameters.

    For this, click the Save button.

Figure: The plug-in parameters in the production mode



Controlling purchase processing

After the purchase processing, it is possible to get the purchase information via the nopCommerce interface: in the Orders subsection of the Sales section. The Orders subsection contains the Search tab with the capability of searching for data and filtering it. Below there is the orders list (Order), the statuses of the purchases that correspond to these orders (Payment status), shipment statuses (Shipping status), and other information. To see the detailed information about the order including the order creation date, purchase amount, payment method, purchase status, shipment address, and other information, click the View button.

Figure: Orders information



If after the plug-in setup, it is required to set it back to the test mode, this should be done in the plug-in tab by selecting the Test mode checkbox.

Note: Before switching the plug-in from the test mode to the production mode for processing real payments, make sure that the Production project ID and Production secret key fields are filled with the values of the merchant's production project in ECommPay.

The questions on working with the plug-in can be forwarded to the ECommPay technical support specialists (support@ecommpay.com).