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

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

Введение

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

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

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

Схема работы

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

Рис.: Проведение оплаты с использованием плагина ecommpay. Описание шагов

  1. Пользователь на стороне веб-сервиса инициирует оплату с использованием плагина ecommpay.
  2. В соответствии с параметрами работы плагина формируется запрос на открытие Payment Page.
  3. Запрос на открытие Payment Page поступает в платёжную платформу.
  4. На стороне платёжной платформы выполняется обработка запроса.
  5. Выполняется подготовка к открытию Payment Page в соответствии с параметрами работы плагина.
  6. Пользователю отображается платёжная форма.
  7. Пользователь выполняет необходимые действия для оплаты.
  8. В платёжную платформу поступает запрос на оплату.
  9. Запрос передаётся в платёжную среду.
  10. В платёжной среде выполняется обработка запроса.
  11. Из платёжной среды к платёжной платформе направляется информация о результате оплаты.
  12. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  13. От платёжной платформы к Payment Page направляется информация о результате оплаты.
  14. Информация о результате оплаты отображается пользователю в платёжной форме.

Каждому заказу, сформированному на стороне веб-сервиса, соответствует оплата с одним из возможных статусов: Pending, Authorized, Paid (captured), Partially refunded, Refunded, Voided — в соответствии с моделью проведения платежей в CMS nopCommerce. Информация об управлении заказами через интерфейс nopCommerce представлена в документации к CMS.

Установка и настройка

Для начала работы с плагином ecommpay его необходимо скачать в интернет-магазине nopCommerce и установить одним из следующих способов:

  • Переместить файлы плагина в каталог /plugins корневого каталога nopCommerce.
  • Загрузить архив с файлами плагина через интерфейс nopCommerce.

    Для этого необходимо перейти в раздел Configuration, выбрать пункт Local plugins, щёлкнуть кнопку Upload plugin or theme и выбрать соответствующий файл для загрузки.

Прим.: Более подробная информация об установке и удалении плагинов, а также о настройке параметров их использования в CMS nopCommerce и в веб-сервисах, разработанных на базе этой CMS, представлена в документации nopCommerce.

После установки плагина можно открыть его карточку и настроить параметры его работы. При этом рекомендуется сначала выполнить тестирование с тестовыми параметрами и уже после тестирования задать рабочие параметры и перейти к полноценному использованию плагина.

Чтобы открыть карточку плагина в интерфейсе 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.

Прим.: Перед установкой плагина из тестового режима в рабочий для проведения реальных платежей, необходимо убедиться, что поля Production project ID и Production secret key заполнены в соответствии со значениями рабочего проекта мерчанта в ecommpay.

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