Using Ecommpay Payments plug-in for the BigCommerce platform

This article covers the information about using the payment plug-in Ecommpay Payments for the BigCommerce platform. This plug-in can be used in the web services developed and maintained on the basis of the supported versions of the BigCommerce platform on the basis of the BigCommerce platform 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 plug-ins directory Apps&Integrations and the administrative interface BigCommerce and allows opening the Payment Page payment form of Ecommpay for customers. The plug-in also allows you to ensure 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).

Technically, the plug-in is deployed in the Ecommpay payment platform and the interaction between the web service and the plug-in builds via a network connection between them. Thus, an up-to-date plug-in's version is always available in the web service.

Capabilities

With the Ecommpay Payments plug-in for the BigCommerce platform, the following is available:

• Implementing the capability to open the Payment Page payment form of Ecommpay in any web service based on the BigCommerce platform.

  For this, you need to install the plug-in and set up its usage in the BigCommerce CMS interface.

• Configuring the plug-in for use with different web services based on the BigCommerce platform.

  When working with several web services based on the BigCommerce platform, you can install, set up, and use a separate plug-in configuration for each web service to accommodate its specific requirements.

• Setting up the use of various payment methods available via the plug-in.

  Technically, for setting up different payment methods, you need to configure a minimum of the plug-in parameters in the BigCommerce interface, while all organisational issues can be resolved in cooperation with the Ecommpay account manager.

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

  For this, you should get a test project in the Ecommpay payment platform (by submitting an application on the company's main site) and configure the project parameters in the BigCommerce interface.

• Processing one-time one-step and two-step purchases.

  Within a single project, you can select one option to process purchases: when funds are debited immediately (in one step) using all of the set up payment methods or when funds are first authorised and then either withdrawn or released (in two steps) using the methods which support processing of such purchases via Payment Page.

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

  For this, you can use the BigCommerce interface and, if relevant, the interfaces of the Ecommpay payment platform (the Dashboard user interface and the Gate API). Keep in mind that, for information to be updated in the BigCommerce interface in cases of refunds via the payment platform interfaces, you must configure the settings of callbacks to be sent from Ecommpay (details).

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

  For this, you can use the BigCommerce interface and, if relevant—the Dashboard interface and the Data API from Ecommpay.

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

  This includes cancelling these orders and changing their statuses manually. Also keep in mind that automatic change of the statuses of the orders is not supported by default but can be set up by the merchant's specialists with the use of capabilities of the BigCommerce platform and other solutions.

• Configuring the options for opening Payment Page as well as using various capabilities provided by Ecommpay to adapt the form to the web service specifics.

  When working with the Ecommpay Payments plug-in, you can configure the options for opening the payment form for standard card payments (details) and use of different capabilities of the payment form (details). 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 receipts and notifications to customers about the purchased goods and services (details). However, some capabilities, such as payments by using tokens, may not be available when you use the plug-in.

Such range of capabilities allows you to adjust your processes to various business specifics, flexibly configure user scenarios, and ensure high rates of 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.

Workflows

The following diagrams illustrate the workflows of executing one-time one-step and two-step purchases with the use of the Ecommpay Payments plug-in, involving 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. The Ecommpay Payments plug-in enables the web service to invoke the Payment Page payment form automatically and interact with the payment platform in accordance with the configured plug-in parameters.

In case of one-step purchases, one initial request leads to a one-time transfer of funds from the customer to the merchant which is followed by a callback with the information about the payment result sent to the web service.

Within two-step purchases, first, a hold is placed on the funds on the customer's account, and then the funds are transferred to the merchant or released. Along with that, at each step, a callback with the information about the corresponding result is sent to the web service.

In case of two-step purchases, based on an initial request (at the first step), the funds are held on the customer's account and then (at the second step), based on the next request or automatically after a specified period of time, the funds are transferred to the merchant or released. Along with that, at each step, a callback with the information about the corresponding result is sent to the web service.

Options for opening Payment Page

Two options are available for interacting with customers when you process one-step purchases and place authorisation holds as part of performing two-step purchases:

• Redirected—for opening the payment form in a separate browser tab (details).

  This option is used by default for all payment methods. For alternative payment methods, it is the only available option, whereas for standard card payments, you can also select the Embedded option. In case of this option, the customer first confirms the creation of the order in the BigCommerce platform on the checkout page of the web service (by selecting the Place Order button). The customer then proceeds to the payment form, provides the required details, and confirms the payment in the Ecommpay platform by selecting the Pay button.

• Embedded—for embedding the payment form directly into the web service interface (via an iframe element; details).

  This option can be used only for standard card payments and can be set up in the plug-in settings (details). In this case, the form is displayed in an HTML element as Payment Page in embedded mode without a separate button for confirming the payment. The customer can select the payment card details (if previously saved) or enter them, and then confirm the purchase by using the Place Order button in the user interface of the web service. If the customer selects another payment method while this option is enabled, the customer is redirected to the payment form as a separate page (using the Redirected option).

When using these options for opening the payment form, note that some additional capabilities, such as payment retries, may not be available when the form is embedded in the web service's user interface (in case of the Embedded option). Other features, such as configuring the interface language of the payment form, are available regardless of the options for opening the payment form. For information about whether a specific capability is available in a particular configuration, contact the Ecommpay technical support.

Monitoring orders and payments

You can monitor the information about orders and payments via the BigCommerce interface in the Orders subsection of the Sales section. Note that orders and payments have different identifiers and statuses. Orders are assigned sequence numbers (for example, 151) and statuses used by BigCommerce (details), while payments on the payment platform side are assigned identifiers that consist of 32 random characters (for example, 5876281a-4129-4fad-86ae-f1a24f637c7f) and statuses used by Ecommpay (details). With questions about the statuses of payments and orders, contact the Ecommpay account manager.

Overview

Testing the plug-in operation and various payment scenarios without actual debiting of funds is possible via the test environment of the Ecommpay payment platform with the use of the plug-in test mode. You can connect to the platform by using the corresponding form on the company's main site and the identifier and key of the test project received from Ecommpay. Along with that, it is necessary to provide the Ecommpay technical support specialists with the name of the web service, for which the Ecommpay Payments plug-in should be used, the web service URL, and the payment currency if you want to process test payments in a particular currency.

Testing the plug-in operation and various payment scenarios is possible via the test environment of the Ecommpay payment platform. For this, you need to use the identifier and the key of the test project received from Ecommpay and provide the Ecommpay technical support specialists with the required information.

Keep in mind that when you use the testing environment of the Ecommpay payment platform, the plug-in will be connected to the web service and will become available as a payment option to the customers. Therefore, it is recommended that if you need to connect the plug-in to the web service in production mode, test the plug-in operation during the low-load time and warn your customers about planned maintenance.

Parameters setup

To prepare the Ecommpay Payments plug-in for testing, activate it as a payment option in the web service and set up the parameters of its operation. When working with several web services, configure the plug-in operation parameters for each of them individually.

To activate the plug-in in the web service, proceed as follows:

1. Go to the parameters of payment options in the BigCommerce interface.

   For this, select the Settings section in the navigation menu and click the Payments line in the Setup section on the page that opens.

2. Select one of the available payment options to enable the plug-in.

   For this, open the Offline Payment Methods accordion item in the Additional providers section and click the Set up button in the line of the appropriate payment option (Bank Depositor another method).

   

3. Specify Ecommpay in the Display Name field on the page that opens and save the changes by clicking the Save button.

   

To set up the plug-in operation parameters, proceed as follows:

1. Go to the plug-in operation parameters in the BigCommerce interface.

   For this, select the Apps section and then—the Ecommpay Payments item in the navigation menu.

2. Go over the key operation parameters of the plug-in and modify them if necessary:
   • Plugin Enabled—the feature for enabling the plug-in in the web service.

     If this toggle switch is off, then all payment methods previously set up for working via the plug-in become available in the web service. If this toggle switch is on, then all payment methods set up for working via the plug-in are unavailable for payment processing.

   • Store Channel—the name of the merchant web service in the BigCommerce platform (select a web service for which you need to set up the parameters of the plug-in).
   • Mode—the feature for switching the plug-in operation mode.

     To use the plug-in in test mode, enter test as the value and specify the connection parameters obtained from Ecommpay in the Test Project ID and Test Secret Key fields.

   • Test Project ID—the test project identifier for interacting with the platform (must be the one received from Ecommpay).
   • Test Secret Key—the secret key for the test project (must be the one received from Ecommpay).
   • Merchant Callback Url—the URL for receiving callbacks from the payment platform (the value is generated and specified automatically during the installation of the Ecommpay Payments plug-in).
   • Host Url—the domain name of the merchant web service for which the parameters of the plug-in are set up (must be specified manually).
   • Payment Mode—the option for processing payments via the payment platform.

     You can select either Sale (for processing one-step purchases) or Authorization Only (for processing two-step purchases). The first option is supported for all payment methods available via the plug-in, the second option—only for the methods that support two-step purchases (such as Apple Pay, Google Pay, and card payments).

     One of the following options can be selected:

     • Sale—for one-step purchases (with immediate debiting of funds)
     • Authorization Only—for two-step purchases (with debiting after authorisation hold)

     The first option is supported for all payment methods available via the plug-in, the second option—only for the methods that support two-step purchases (such as Apple Pay, Google Pay, and card payments).

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

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 BigCommerce interface—in the View subsection of the Orders section. Along with that, you can use special payment credentials that allow testing particular payment scenarios.

For testing card payments 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), you can use the information provided in the Testing article and in the corresponding sections of the articles about working with particular payment methods.

During the processing of two-step purchases, the first step, the authorisation hold, is initiated by the customer when they confirm the purchase, while the second step, the withdrawal of the authorised amount or the release of funds, can be initiated automatically, after the time allocated for the funds to remain authorised expires, or manually via the BigCommerce interface or via one of the interfaces of the Ecommpay payment platform—Dashboard (details) and the Gate API (details). Along with that, in most cases you can capture both full and partial amounts of the authorised funds. However, some payment methods can support only full captures.

To initiate the second step of a two-step purchase via the BigCommerce interface, proceed as follows:

1. Open the orders register in the BigCommerce interface.

   For this open the View subsection of the Orders section.

2. Open the panel with data about a two-step purchase as part of a particular order (via the button in the Action column).

   For this, click the button in the Action column of the relevant order row and select the Ecommpay item.

3. Initiate the required action (by clicking the Capture or Void button).

   To initiate the debiting of authorised funds, specify the amount for debiting and click the Capture button in the corresponding section. To release the authorised amount, click the Void button in the corresponding section.

To have the automatic initiation of the second step set up, contact the Ecommpay technical support specialists.

However, if you want payment information to be updated automatically in the BigCommerce interface when the second step of a two-step purchase is initiated via the Ecommpay platform interfaces, make sure that callbacks from the payment platform are configured for the project and sent to the specified URL of the web service. Note that you should have only one set of conditions configured for a payment type. There should not be more than one set of conditions with the same values of event types and payment method codes configured for the same payment type. The information about working with callback settings is provided in the corresponding article.

Processing test refunds

After processing test purchases, you can make test refunds via the BigCommerce interface and, if relevant, via the Dashboard and Gate interfaces in the Ecommpay platform. Also keep in mind that refunds can be made for payments that have been assigned the statuses success, partially reversed, or partially refunded on the payment platform side. The information about refunds can be monitored with the use of the platform interfaces and the BigCommerce interface.

For the information about payments to be automatically updated in the BigCommerce interface in cases of test refunds made via the payment platform interfaces, ensure that, for the project in use, the settings of callbacks to be sent from the payment platform have been configured. Along with that, it is important that, for a single payment type, there are no several sets of conditions with the same values of event types and payment method codes set up. The information about working with callback settings is provided in the corresponding article of this documentation.

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

1. Open the orders register in the BigCommerce interface.

   For this, open the View subsection of the Orders section.

2. Open the panel with the payment data from the payment platform (using the button in the Action column).

   For this, click the button in the Action column and select the Ecommpay item.

3. Initiate the refund (via the Refund section on the panel with the payment data).

   For this, specify the amount and the reason for refund and click the Refund button in the corresponding section.

4. Ensure that the refund has been made.

   For this, you can check that the operation information has been updated on the panel with the payment data.

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 installed 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 prepare the Ecommpay Payments plug-in for work, activate it as a payment option in the web service and set up the parameters of its operation. When working with several web services, configure the plug-in operation parameters for each of them individually. Keep in mind that if the plug-in has been activated for test payments, you do not need to reactivate it, but you should modify the configuration settings as necessary (details).

To activate the plug-in the web service, proceed as follows:

1. Go to the parameters of payment options in the BigCommerce interface.

   For this, select the Settings section in the navigation menu and click the Payments line in the Setup section on the page that opens.

2. Select one of the available payment options to enable the plug-in.

   For this, open the Offline Payment Methods accordion item in the Additional providers section and click the Set up button in the line of the appropriate payment option (Bank Depositor another method).

   

3. Specify Ecommpay in the Display Name field on the page that opens and save the changes by clicking the Save button.

   

To set up the plug-in operation parameters, proceed as follows:

1. Go to the plug-in operation parameters in the BigCommerce interface.

   For this, select the Apps section, the select the Ecommpay Payments item in the navigation menu.

2. Go over the key operation parameters of the plug-in and modify them if necessary:
   • Plugin Enabled—the feature for enabling the plug-in in the web service.

     If this toggle switch is off, then all payment methods previously set up for working via the plug-in become available in the web service. If this toggle switch is on, then all payment methods set up for working via the plug-in are unavailable for payment processing.

   • Store Channel—the name of the merchant web service in the BigCommerce platform (select a web service for which you need to set up the parameters of the plug-in).
   • Mode—the plug-in operation mode (the live option must be selected).
   • Project ID—the project identifier for interacting with the platform (must be the one received from Ecommpay).
   • Secret Key—the secret key for the project (must be the one received from Ecommpay).
   • Merchant Callback Url—the URL for receiving callbacks from the payment platform (the value is generated and specified automatically during the installation of the Ecommpay Payments plug-in).
   • Host Url—the domain name of the merchant web service for which the parameters of the plug-in are set up (must be specified manually).
   • Payment Mode—the option for processing payments via the payment platform.

     You can select either Sale (for processing one-step purchases) or Authorization Only (for processing two-step purchases). The first option is supported for all payment methods available via the plug-in, the second option—only for the methods that support two-step purchases (such as Apple Pay, Google Pay, and card payments).

     One of the following options can be selected:

     • Sale—for one-step purchases (with immediate debiting of funds)
     • Authorization Only—for two-step purchases (with debiting after authorisation hold)

     The first option is supported for all payment methods available via the plug-in, the second option—only for the methods that support two-step purchases (such as Apple Pay, Google Pay, and card payments).

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

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.

During the processing of two-step purchases, the first step, the authorisation hold, is initiated by the customer when they confirm the purchase, while the second step, the withdrawal of the authorised amount or the release of funds, can be initiated automatically, after the time allocated for the funds to remain authorised expires, or manually via the BigCommerce interface or via one of the interfaces of the Ecommpay payment platform—Dashboard (details) and the Gate API (details). Along with that, in most cases you can capture both full and partial amounts of the authorised funds. However, some payment methods can support only full captures.

To have the automatic initiation of the second step set up, contact the Ecommpay technical support specialists.

To initiate the second step of a two-step purchase via the BigCommerce interface, proceed as follows:

1. Open the orders register in the BigCommerce interface.

   For this open the View subsection of the Orders section.

2. Open the panel with data about a two-step purchase as part of a particular order (via the button in the Action column).

   For this, click the button in the Action column of the relevant order row and select the Ecommpay item.

3. Initiate the required action (by clicking the Capture or Void button).

   To initiate the debiting of authorised funds, specify the amount for debiting and click the Capture button in the corresponding section. To release the authorised amount, click the Void button in the corresponding section.

In case of questions or issues related to purchase processing, contact the Ecommpay technical support specialists.

Issuing refunds

For purchases processed with the use of the Ecommpay Payments plug-in, you can make partial and full refunds via the BigCommerce interface and, if relevant, via the interfaces Dashboard (with the tools for sending individual and batch requests; details) and the Gate API (details) from Ecommpay—for payments with the statuses success, partially reversed, or partially refunded on the payment platform side. All relevant information about refunds and the corresponding payments can be obtained via the BigCommerce interface and the interfaces of the payment platform.

To issue a refund via the BigCommerce interface, proceed as follows:

1. Open the orders register in the BigCommerce interface.

   For this, open the View subsection of the Orders section.

2. Open the panel with the payment data from the payment platform (using the button in the Action column).

   For this, click the button in the Action column and select the Ecommpay item.

3. Initiate the refund (via the Refund section on the panel with the payment data).

   For this, specify the amount and the reason for refund and click the Refund button in the corresponding section.

4. Ensure that the refund has been made.

   For this, you can check that the operation information has been updated on the panel with the payment data.

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 BigCommerce interface, with the use of the tools of the View subsection in the Orders 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 View subsection of the Orders section contains an orders register with various capabilities of working with orders, including the capability to obtain payment information within separate orders.

The View subsection of the Orders section contains a register with information about every order. Along with that, the orders register provides various functions for working with orders including the capabilities of searching and filtering data and obtaining payment information within separate orders.

Clicking the button in the corresponding column of the register leads you to opening a panel with detailed information about the order.To obtain more detailed information about an order, click the button in corresponding column of the register. This leads to opening a panel which contains such information as the customer's address, the creation date and amount of the order and other information.

The Billing section of the panel displays the name of the organisation through which the processing of payments with the use of the selected method takes place with the name of the payment method (in the field with the icon) and the payment identifier (in the field with the icon). To obtain more detailed information about the payment, click the button in the Action column and the Ecommpay item in the drop-down list. The panel that opens displays the Order Details section with information about the payment and can display the following sections (if the corresponding functions are available within the selected order):

• Capture—with the capability to initiate debiting of authorised funds as part of a two-step purchase
• Void—with the capability to release the authorised funds as part of a two-step purchase
• Refund—with the capability to initiate a refund as part of a purchase

More information about working with orders in the BigCommerce interface is provided in the BigCommerce documentation.