Using the ECommPay for Bitrix CMS plug-in

This manual describes how to use the ECommPay plug-in version 1.0. The plug-in allows to perform payments by using ECommPay payment solutions for sites that are based on Bitrix CMS in Small Business, Business, and Enterprise revisions.

You can download the ECommPay for the Bitrix CMS plug-in by using the following link: here.

Operation workflow

Payments are processed by using the ECommPay payment page.

Figure: The diagram of payment processing with plug-in enabled



Request for opening the payment page is automatically generated by the plug-in when ECommPay is selected as a payment method.

If the payment is declined, a customer may re-enter the data on the payment page.

Upon receipt of the payment result, a callback is sent to the site's system. The callback is processed by the plug-in automatically. In accordance with the payment result, the status of the order changes. The correspondence of the payment result and the status of the order is set in the Bitrix CMS settings.

Installing

To install the plugin, do the following:
  1. Download file with the ECommPay plugin.
  2. Open Bitrix CMS.
  3. Go to the section Content > Site Explorer > Files and Folders.
  4. Add a ecommpay folder to the bitrix/modules folder.
  5. Go to the section Settings > System settings > Modules.
  6. Click the Install near ECommPay.

    When plugin is installed its status changes to Installed.



Callbacks

To automatically change the payment status of the order, it is necessary to ensure receipt of callbacks from ECommPay. Do the following:
  1. Add php-file to the section Content > Site Explorer > Files and Folders.


    That file should contain the following code:
    <? $APPLICATION->IncludeComponent(
        "bitrix:sale.order.payment.receive",
        "",
        Array(
            "PAY_SYSTEM_ID_NEW" => "7"
        )
    );
    ?>
    

    The PAY_SYSTEM_ID_NEW parameter is identifier of the ECommPay payment system in the Bitrix CMS. To find that identifier, go to the section e-Store > Settings > Payment systems.



  2. Provide URL to receive callbacks to the technical support during launching stage of integration.

Testing

When the plugin is activated, it is possible to switch it to the test mode. By using this mode, you can get familiar with the operation process of the plugin connected to the site, without an option to perform payments in real time. In the test mode, you may configure and test the plugin, perform test orders and view information about them. When paying in test mode, a corresponding message is displayed on the payment page.

Configuration

To configure parameters of the plugin in the test mode, do the following:
  1. Check module status in the section Settings > System settings > Modules. It should be Installed.
  2. Go to the section e-Store > Settings > Payment systems.
  3. Select ECommPay from the list and click Modify.


  4. Configure the required settings. For more details see below.
  5. Select Yes in the filed Test mode.
  6. Click Save.
The parameters of the plugin can be configured by default for all types of customers or separately for each type of customers. Plugin settings include the following parameters:
  • Parameters of ECommPay payment page operation while displaying:
    • Active—to display ECommPay as payment method on the site
    • Description—information about the payment method on the site
    • Payment system logo—to download logo of the payment method


    • Open in new window and Modal mode—to choose display mode. Combination of those fields allow to choose one of the three display modes: iframe, modal window, separate browser tab.

      Iframe display mode: uncheck the Open in new window checkbox and select No in the Modal mode field.

      Modal window display mode: uncheck the Open in new window checkbox and select Yes in the Modal mode field.

      Separate browser tab display mode: check the Open in new window checkbox and select No in the Modal mode field.

    • Display the page of selecting a payment method—to customize the display of the payment method selection page before proceeding to the payment.
    • Additional params—additional parameters of the payment page.

      A list of these parameters is available here. When specifying parameters select Value. For the specifying two or more parameters, they must be entered with "&" as separator.

    • Terminal language—to customize the language of the payment page. When specifying parameter select Value and use language code with the accordance to ISO 639-1 alpha-2.
  • Parameters Project ID and Secret salt are used for implementing ECommPay payment solutions.

    They are not used in the test mode.



Performing test orders

Once the parameters of the plugin are configured you should perform test orders on the site and check information regarding the orders in Bitrix CMS in the section e-Store > Orders.

Launching

Once the plugin is tested using all the planned payment methods it may be switched to production mode. In order to do this, you should receive the parameters for the production mode and adjust settings.

Receiving the parameters for the production mode

To receive the parameters for connecting to ECommPay payment solutions, do the following:

  1. Contact ECommPay technical support and provide the following parameters:
    • The site name and its URL.
    • The payment page currency.
    • URL to receive callbacks.
  2. Receive from ECommPay technical support the following parameters:
    • Project ID—site identifier.
    • Secret salt—secret key, that is generated for a particular merchant in the ECommPay processing system.

Configuring the operational parameters

In order to set the operational parameters, do the following:

  1. Open Bitrix CMS.
  2. Go to the section e-Store > Settings > Payment systems.
  3. Select ECommPay and configure the operational parameters:
    • Make sure, that Activity checkbox is enabled.
    • Select No in the Test mode field.
    • Fill in the fields Project ID and Secret salt in accordance with the values received from ECommPay technical support.
    • Make sure, that the remaining parameters are set to the required values.
  4. Click the Save button.

Using

Once the plugin is launched it operates autonomously.

We recommend that you control orders by reviewing the information in the section e-Store > Orders, and also to make sure that order numbers are unique within the site. In the case when an order number duplicates, the payment page does not open.

If the plugin is already operating in the production mode and you require to switch it back to the test mode, pay attention to how the payment method is displayed on the site. If Yes is selected in the Test mode and checkbox Activity is enabled, the payment method using the ECommPay payment page is displayed on the site. However, all payments are performed as test payments. Warning about the payment in test mode is displayed on the payment page.

Before you switch the plugin back to the production mode, make sure that the Project ID and Secret salt fields are filled in accordance with the values received from ECommPay technical support.

If you have any further questions regarding the plugin operation, contact ECommPay technical support at support@ecommpay.com.