Использование плагина ecommpay для CMS nopCommerce
Общая информация
Введение
В этой статье представлена информация об использовании плагина ecommpay для различных веб-сервисов, разработанных на базе CMS nopCommerce версий 4.40 и выше.
С помощью описываемого плагина можно проводить оплаты и выполнять частичные или полные возвраты с использованием различных платёжных методов из числа поддерживаемых для платёжной формы Payment Page (подробнее). Также при работе с плагином можно использовать различные дополнительные возможности, обеспечиваемые со стороны ecommpay для Payment Page (подробнее) и со стороны разработчиков CMS nopCommerce для этой системы. Например, можно поддерживать для пользователей повторные попытки оплаты и регулировать применение плагина в разных странах. Применяя возможности такого рода, можно подстраиваться под различные региональные особенности, улучшать пользовательские сценарии, повышать конверсию платёжной формы и проходимость платежей.
Для подключения возможностей, предоставляемых ecommpay, следует обращаться к технической документации на этом портале и, по мере необходимости, к специалистам ecommpay.
Схема работы
В схеме проведения оплат с использованием плагина ecommpay задействуются пользователь, веб-сервис со встроенным в него плагином, платёжная форма Payment Page, платёжная платформа и платёжная среда. При этом на стороне веб-сервиса мерчанта обеспечиваются автоматический вызов Payment Page и автоматический приём оповещений от платёжной платформы в соответствии с параметрами работы плагина.
Рис.: Проведение оплаты с использованием плагина ecommpay. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату с использованием плагина ecommpay.
- В соответствии с параметрами работы плагина формируется запрос на открытие Payment Page.
- Запрос на открытие Payment Page поступает в платёжную платформу.
- На стороне платёжной платформы выполняется обработка запроса.
- Выполняется подготовка к открытию Payment Page в соответствии с параметрами работы плагина.
- Пользователю отображается платёжная форма.
- Пользователь выполняет необходимые действия для оплаты.
- В платёжную платформу поступает запрос на оплату.
- Запрос передаётся в платёжную среду.
- В платёжной среде выполняется обработка запроса.
- Из платёжной среды к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page направляется информация о результате оплаты.
- Информация о результате оплаты отображается пользователю в платёжной форме.
Каждому заказу, сформированному на стороне веб-сервиса, соответствует оплата с одним из возможных статусов: Pending
, Authorized
, Paid
(captured
), Partially refunded
, Refunded
, Voided
— в соответствии с моделью проведения платежей в CMS nopCommerce. Информация об управлении заказами через интерфейс nopCommerce представлена в документации к CMS.
Установка и настройка
Для начала работы с плагином ecommpay его необходимо скачать в интернет-магазине nopCommerce и установить одним из следующих способов:
- Переместить файлы плагина в каталог
/plugins
корневого каталога nopCommerce. - Загрузить архив с файлами плагина через интерфейс nopCommerce.
Для этого необходимо перейти в раздел Configuration, выбрать пункт Local plugins, щёлкнуть кнопку Upload plugin or theme и выбрать соответствующий файл для загрузки.
После установки плагина можно открыть его карточку и настроить параметры его работы. При этом рекомендуется сначала выполнить тестирование с тестовыми параметрами и уже после тестирования задать рабочие параметры и перейти к полноценному использованию плагина.
Чтобы открыть карточку плагина в интерфейсе nopCommerce, следует перейти в раздел Configuration, выбрать пункт Payment methods и щёлкнуть кнопку Configure в строке с названием плагина. В карточке плагина ecommpay отображается краткая инструкция по работе с ним и поля для настройки параметров его работы. Описания параметров для тестирования и работы представлены в следующих разделах этой статьи.
Рис.: Карточка плагина

Тестирование
Общая информация
Для проверки работы плагина и проведения тестовых платежей без реального списания средств можно использовать два варианта тестирования:
- тестирование через тестовый режим работы плагина;
- тестирование через тестовую среду платёжной платформы ecommpay.
Второй из этих вариантов можно считать более функциональным, в том числе потому, что в нём плагин работает в рабочем режиме и в CMS можно контролировать изменения статусов заказов. Вместе с тем, для использования этого варианта необходимо подключиться к тестовой среде ecommpay (это можно сделать через сайт компании), в то время как тестирование через тестовый режим работы плагина можно осуществлять без каких-либо дополнительных действий. При желании можно выполнять тестовые операции с использованием обоих вариантов. Выбор того, как проверять работу с плагином, остаётся за мерчантом.
Для обоих вариантов тестирования поддерживаются следующие возможности:
- выбор режима отображения платёжной формы;
- задание параметров вызова платёжной формы;
- использование разных способов начисления комиссии, взимаемой с пользователя;
- автоматическое открытие Payment Page в соответствии с заданными параметрами при проведении тестовых оплат;
- отображение информации о сформированных заказах и тестовых оплатах в интерфейсе nopCommerce.
В рабочем режиме плагина дополнительно доступно получение актуальной информации о статусах заказов через интерфейс nopCommerce, а также возможность протестировать получение оповещений о состоянии платежей. Оповещения отправляются на URL, переданный мерчантом при получении доступа к тестовой среде ecommpay.
Настройка параметров
Для подготовки к проведению тестовых платежей со стороны мерчанта следует определить предпочтительный вариант тестирования, установить соответствующий режим работы плагина и настроить параметры его работы. При этом стоит учитывать, что для работы через тестовый режим работы плагина может быть достаточно минимального набора параметров, описанных далее, а для проверки через тестовую среду платёжной платформы ecommpay к ним добавляются два обязательных параметра: идентификатор проекта и секретный ключ, полученные от специалистов ecommpay при подключении к тестовой среде.
Таким образом, чтобы настроить плагин для проведения тестовых платежей без реального списания средств, со стороны мерчанта необходимо выполнить следующее:
- Открыть карточку плагина в интерфейсе nopCommerce.
Для этого следует выбрать пункт Payment methods в разделе Configuration и щелкнуть кнопку Configure в строке с названием плагина ecommpay.
- Установить режим работы плагина.
Для работы в тестовом режиме необходимо установить флажок Test mode, в рабочем — снять.
- При установке рабочего режима — задать обязательные параметры для подключения к тестовой среде платёжной платформы:
- Production project ID — идентификатор тестового проекта, полученный от ecommpay.
- Production secret key — секретный ключ для взаимодействия с ecommpay.
- Задать доступные параметры работы плагина.
- Payment flow — способ отображения платёжной формы пользователям: в отдельной вкладке браузера или в объекте iframe, встроенном в HTML-страницу веб-сервиса (подробнее — в разделе Способы открытия платежной страницы). При выполнении тестирования рекомендуется проверить разные режимы отображения Payment Page и выбрать из них наиболее подходящий для работы.
- Additional parameters — дополнительные параметры вызова платёжной формы. При работе с тестовыми платежами рекомендуется использовать те параметры, которые могут быть актуальны в тех или иных случаях и проверять как они влияют на разные сценарии проведения платежей. Список возможных параметров представлен в разделе Параметры вызова платёжной формы. При одновременном указании нескольких параметров, в качестве разделителя используется
&
. Например, чтобы задать определённый язык отображения платёжной формы и конкретный способ оплаты, необходимо указать их через соответствующие параметры в следующем формате:language_code=fr&force_payment_method=card
. - Additional fee — размер комиссии, взимаемой с пользователя. Этот параметр может быть нулевым, если комиссия неактуальна. Если же применение комиссии актуально, её размер указывается с отделением дробной части с помощью точки и, с учётом состояния флажка Additional fee. Use percentage, может интерпретироваться как:
- абсолютный, что соответствует сумме комиссии для каждого платежа (например,
1.20
в валюте, используемой для проведения платежа); - относительный, что соответствует заданной доле от общей суммы для каждого платежа
(например,
1.20 %
).
- абсолютный, что соответствует сумме комиссии для каждого платежа (например,
- Additional fee. Use percentage — указатель использования относительной комиссии. Когда этот флажок установлен, применяется относительный размер комиссии, когда снят — абсолютный.
Поле Callback endpoint содержит URL для получения оповещений о проведении платежей и недоступно для редактирования. Этот URL заполняется автоматически и соответствует тому, который мерчант сообщает специалистам ecommpay при получении доступа к тестовой среде. Для смены URL необходимо обращаться к специалистам технической поддержки ecommpay.
- Сохранить параметры работы плагина.
Для этого необходимо щёлкнуть кнопку Save.
Рис.: Параметры работы плагина в тестовом режиме

Проведение тестовых оплат и возвратов
После настройки работы плагина рекомендуется провести тестовые оплаты в веб-сервисе и получить информацию о них через интерфейс nopCommerce: в пункте Orders раздела Sales. Для проведения тестовых оплат (в любом из вариантов тестирования) можно использовать номера тестовых карт разных платёжных систем и получать необходимые итоговые статусы оплат.
При выполнении тестирования через тестовый режим работы плагина стоит учитывать, что статусы заказов, созданные на стороне веб-сервиса, не могут меняться, им автоматически присваивается статус Pending
. Для проверки изменения статусов тестовых заказов можно использовать вариант тестирования плагина через тестовую среду платёжной платформы ecommpay.
Рис.: Список платежей

После проведения тестовых оплат можно протестировать выполнение возвратов. Для этого со стороны мерчанта необходимо:
- Перейти к списку заказов.
Для этого необходимо перейти в раздел Sales и выбрать пункт Orders.
- Выбрать из списка заказ, по которому необходимо выполнить возврат средств и щёлкнуть кнопку View.
Следует учитывать, что выполнение возвратов доступно только для оплаченных заказов (
Payment status = Paid
). - Раскрыть вкладку с информацией об оплате, после чего:
- для полного возврата средств — щёлкнуть кнопку Refund и подтвердить выполнение этого действия;
- для частичного возврата средств — щёлкнуть кнопку Partial Refund и указать сумму возврата.
Информация о работе с заказами в интерфейсе nopCommerce также представлена в документации этой CMS.
Использование
Общая информация
Для проведения платежей с реальным списанием средств со стороны мерчанта необходимо подключиться к рабочей среде ecommpay (это можно сделать через сайт компании) и использовать полученные идентификатор проекта и секретный ключ в значении обязательных параметров рабочего режима плагина.
В рабочем режиме плагина доступны следующие возможности:
- выбор режима отображения платёжной формы;
- задание параметров вызова платёжной формы;
- использование разных способов начисления комиссии, взимаемой с пользователя;
- автоматическое открытие Payment Page в соответствии с заданными параметрами при проведении реальных оплат;
- получение информации об оплатах через оповещения;
- отображение информации о сформированных заказах и их актуальных статусах в интерфейсе nopCommerce;
- отображение информации об оплатах в интерфейсе nopCommerce.
Настройка параметров
Для проведения реальных платежей со стороны мерчанта необходимо получить доступ к рабочей среде ecommpay, установить рабочий режим плагина и настроить параметры его работы. В рабочем режиме обязательно должны быть заполнены идентификатор проекта и секретный ключ, полученные от специалистов ecommpay при подключении к рабочей среде. Дополнительно можно также указать и другие параметры, описанные далее.
Таким образом, чтобы настроить плагин для проведения реальных платежей, со стороны мерчанта необходимо выполнить следующее:
- Открыть в карточку плагина в интерфейсе nopCommerce.
Для этого необходимо выбрать пункт Payment methods в разделе Configuration и щелкнуть кнопку Configure в строке с названием плагина ecommpay.
- Установить рабочий режим плагина.
Для этого необходимо снять флажок Test mode.
- Задать обязательные параметры работы плагина:
- Production project ID — идентификатор рабочего проекта, полученный от ecommpay.
- Production secret key — секретный ключ для взаимодействия с ecommpay.
- Задать доступные параметры работы плагина.
- Payment flow — способ отображения платёжной формы пользователям: в отдельной вкладке браузера или в объекте iframe, встроенном в HTML-страницу веб-сервиса (подробнее — в разделе Способы открытия платежной страницы).
- Additional parameters — дополнительные параметры вызова платёжной формы. Список доступных параметров представлен в разделе Параметры вызова платёжной формы. При одновременном указании нескольких параметров, в качестве разделителя используется
&
. Например, чтобы задать определённый язык отображения платёжной формы и конкретный способ оплаты, необходимо указать их через соответствующие параметры в следующем формате:language_code=fr&force_payment_method=card
. - Additional fee — размер комиссии, взимаемой с пользователя. Этот параметр может быть нулевым, если комиссия неактуальна. Если же применение комиссии актуально, её размер указывается с отделением дробной части с помощью точки и, с учётом состояния флажка Additional fee. Use percentage, может интерпретироваться как:
- абсолютный, что соответствует сумме комиссии для каждого платежа (например,
1.20
в валюте, используемой для проведения платежа); - относительный, что соответствует заданной доле от общей суммы для каждого платежа (например,
1.20 %
).
- абсолютный, что соответствует сумме комиссии для каждого платежа (например,
- Additional fee. Use percentage — указатель использования относительной комиссии. Когда флажок установлен, применяется относительный размер комиссии, когда снят — абсолютный.
Поле Callback endpoint содержит URL для получения оповещений о проведении платежей и недоступно для редактирования. Этот URL заполняется автоматически и соответствует тому, который мерчант сообщает специалистам ecommpay при получении доступа к рабочей среде. Для смены URL необходимо обращаться к специалистам технической поддержки ecommpay.
- Сохранить параметры работы плагина.
Для этого необходимо щёлкнуть кнопку Save.
Рис.: Параметры работы плагина в рабочем режиме

Контроль проведения оплат
После проведения оплат можно получать информацию о них через интерфейс nopCommerce: в пункте Orders раздела Sales. В пункте Orders доступна вкладка Search с возможностью поиска и фильтрации данных, а ниже отображается список заказов (Order
), статусы соответствующих им оплат (Payment status
), статусы доставки (Shipping status
) и другая информация. Чтобы посмотреть детальную информацию о заказе, которая включает в себя дату создания заказа, сумму оплаты, способ и статус оплаты, адрес доставки и другие данные, необходимо щёлкнуть кнопку View.
Рис.: Информация о заказах

Если после установки плагина в рабочий режим появляется необходимость вернуть его в тестовый режим, следует открыть карточку плагина и установить флажок Test mode.
По вопросам, связанным с работой плагина, можно обращаться в службу технической поддержки ecommpay (support@ecommpay.com).