Использование плагина ecommpay для CMS nopCommerce

Введение

В этой статье представлена информация об использовании плагина ecommpay для различных веб-сервисов, разработанных на базе CMS nopCommerce версий 4.40 и выше.

С помощью описываемого плагина можно проводить оплаты и выполнять частичные или полные возвраты с использованием различных платёжных методов из числа поддерживаемых для платёжной формы Payment Page (подробнее). Также при работе с плагином можно использовать различные дополнительные возможности, обеспечиваемые со стороны ecommpay для Payment Page (подробнее) и со стороны разработчиков CMS nopCommerce для этой системы. Например, можно поддерживать для пользователей повторные попытки оплаты и регулировать применение плагина в разных странах. Применяя возможности такого рода, можно подстраиваться под различные региональные особенности, улучшать пользовательские сценарии, повышать конверсию платёжной формы и проходимость платежей.

Для подключения возможностей, предоставляемых ecommpay, следует обращаться к технической документации на этом портале и, по мере необходимости, к специалистам ecommpay.

Схема работы

В схеме проведения оплат с использованием плагина ecommpay задействуются пользователь, веб-сервис со встроенным в него плагином, платёжная форма 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 при подключении к тестовой среде.

Таким образом, чтобы настроить плагин для проведения тестовых платежей без реального списания средств, со стороны мерчанта необходимо выполнить следующее:

1. Открыть карточку плагина в интерфейсе nopCommerce.

   Для этого следует выбрать пункт Payment methods в разделе Configuration и щелкнуть кнопку Configure в строке с названием плагина ecommpay.

2. Установить режим работы плагина.

   Для работы в тестовом режиме необходимо установить флажок Test mode, в рабочем — снять.

3. При установке рабочего режима — задать обязательные параметры для подключения к тестовой среде платёжной платформы:
   • Production project ID — идентификатор тестового проекта, полученный от ecommpay.
   • Production secret key — секретный ключ для взаимодействия с ecommpay.
4. Задать доступные параметры работы плагина.
   • 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.

5. Сохранить параметры работы плагина.

   Для этого необходимо щёлкнуть кнопку Save.

Проведение тестовых оплат и возвратов

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

При выполнении тестирования через тестовый режим работы плагина стоит учитывать, что статусы заказов, созданные на стороне веб-сервиса, не могут меняться, им автоматически присваивается статус Pending. Для проверки изменения статусов тестовых заказов можно использовать вариант тестирования плагина через тестовую среду платёжной платформы ecommpay.

Рис.: Список платежей

После проведения тестовых оплат можно протестировать выполнение возвратов. Для этого со стороны мерчанта необходимо:

1. Перейти к списку заказов.

   Для этого необходимо перейти в раздел Sales и выбрать пункт Orders.

2. Выбрать из списка заказ, по которому необходимо выполнить возврат средств и щёлкнуть кнопку View.

   Следует учитывать, что выполнение возвратов доступно только для оплаченных заказов (Payment status = Paid).

3. Раскрыть вкладку с информацией об оплате, после чего:
   • для полного возврата средств — щёлкнуть кнопку Refund и подтвердить выполнение этого действия;
   • для частичного возврата средств — щёлкнуть кнопку Partial Refund и указать сумму возврата.

Информация о работе с заказами в интерфейсе nopCommerce также представлена в документации этой CMS.

Общая информация

Для проведения платежей с реальным списанием средств со стороны мерчанта необходимо подключиться к рабочей среде ecommpay (это можно сделать через сайт компании) и использовать полученные идентификатор проекта и секретный ключ в значении обязательных параметров рабочего режима плагина.

В рабочем режиме плагина доступны следующие возможности:

• выбор режима отображения платёжной формы;
• задание параметров вызова платёжной формы;
• использование разных способов начисления комиссии, взимаемой с пользователя;
• автоматическое открытие Payment Page в соответствии с заданными параметрами при проведении реальных оплат;
• получение информации об оплатах через оповещения;
• отображение информации о сформированных заказах и их актуальных статусах в интерфейсе nopCommerce;
• отображение информации об оплатах в интерфейсе nopCommerce.

Настройка параметров

Для проведения реальных платежей со стороны мерчанта необходимо получить доступ к рабочей среде ecommpay, установить рабочий режим плагина и настроить параметры его работы. В рабочем режиме обязательно должны быть заполнены идентификатор проекта и секретный ключ, полученные от специалистов ecommpay при подключении к рабочей среде. Дополнительно можно также указать и другие параметры, описанные далее.

Таким образом, чтобы настроить плагин для проведения реальных платежей, со стороны мерчанта необходимо выполнить следующее:

1. Открыть в карточку плагина в интерфейсе nopCommerce.

   Для этого необходимо выбрать пункт Payment methods в разделе Configuration и щелкнуть кнопку Configure в строке с названием плагина ecommpay.

2. Установить рабочий режим плагина.

   Для этого необходимо снять флажок Test mode.

3. Задать обязательные параметры работы плагина:
   • Production project ID — идентификатор рабочего проекта, полученный от ecommpay.
   • Production secret key — секретный ключ для взаимодействия с ecommpay.
4. Задать доступные параметры работы плагина.
   • 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.

5. Сохранить параметры работы плагина.

   Для этого необходимо щёлкнуть кнопку Save.

Рис.: Параметры работы плагина в рабочем режиме

Контроль проведения оплат

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

Рис.: Информация о заказах

Если после установки плагина в рабочий режим появляется необходимость вернуть его в тестовый режим, следует открыть карточку плагина и установить флажок Test mode.

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