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

Введение

В этой статье представлена информация о работе с платёжным плагином ecommpay payments версии 1.0.2. Этот плагин может использоваться в веб-сервисах, разработанных на базе CMS PrestaShop версий 8.1.5 и выше, и позволяет открывать пользователям платёжную форму Payment Page от ecommpay, а также обеспечивать все необходимые действия для проведения платежей.

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

Рис. 1. Административный интерфейс PrestaShop

Рис. 2. Интерфейс платёжной формы Payment Page

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

Возможности

При использовании плагина ecommpay payments можно:

Оперативно встраивать в веб-сервис возможность вызова платёжной формы Payment Page от ecommpay.
Для этого достаточно всего нескольких действий в интерфейсе CMS PrestaShop.
Тестировать работу платёжной формы и возможности проведения платежей.
При этом для начального тестирования достаточно тестового режима работы плагина (без каких-либо дополнительных действий), а для более глубокого тестирования можно оформить тестовый проект в платёжной платформе ecommpay (что можно сделать через заявку на основном сайте компании).
Проводить разовые одностадийные оплаты с применением различных платёжных методов.
При этом для решения всех организационных вопросов и подключения платёжных методов следует обращаться к курирующему менеджеру ecommpay.
Выполнять частичные и полные возвраты средств по оплатам, проведённым с помощью плагина.
Для этого можно использовать интерфейс PrestaShop и, если актуально, интерфейсы платёжной платформы ecommpay (пользовательский интерфейс Dashboard и Gate API). Вместе с тем, при использовании интерфейсов платёжной платформы ecommpay информация о заказах в интерфейсе PrestaShop обновляется, только если настроена отправка оповещений со стороны платёжной платформы (подробнее).
Контролировать информацию о платежах, проводимых с помощью плагина.
Это можно делать через интерфейс PrestaShop и, если актуально, — через Data API и пользовательский интерфейс Dashboard от ecommpay.
Управлять заказами, оплаты по которым проводятся с помощью плагина.
Для этого можно использовать интерфейс PrestaShop, который позволяет отменять такие заказы и корректировать их статусы вручную.
Настраивать параметры работы платёжной формы Payment Page, адаптируя её под специфику веб-сервиса, и применять различные возможности, обеспечиваемые со стороны ecommpay.
В частности, можно применять процедуру подтверждения зачислений при работе с платёжными методами Open Banking, делать доступными для пользователей повторные попытки оплаты (подробнее) и подключать отправку пользователям уведомлений о результатах оплат (подробнее). Для подключения таких возможностей следует обращаться к специалистам технической поддержки ecommpay.

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

Схема работы

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

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

Пользователь на стороне веб-сервиса выбирает вариант оплаты с использованием плагина ecommpay payments.
На стороне веб-сервиса формируется и отправляется в платёжную платформу ecommpay запрос на открытие платёжной формы Payment Page.
Запрос на открытие Payment Page поступает в платёжную платформу.
В платёжной платформе выполняется обработка запроса, с проверкой его корректности.
В платёжной платформе обеспечивается подготовка к открытию Payment Page.
Пользователю отображается платёжная форма.
Пользователь выполняет необходимые действия и подтверждает готовность провести оплату.
В платёжную платформу поступает итоговый запрос на оплату (со всеми необходимыми сведениями).
Запрос передаётся в платёжную среду.
В платёжной среде выполняется обработка платежа. При этом, если необходимо, обеспечивается выполнение дополнительных действий со стороны платформы и пользователя (например, для аутентификации 3‑D Secure).
Из платёжной среды к платёжной платформе направляется информация о результате оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе PrestaShop обновляется информация о заказе.
От платёжной платформы к Payment Page направляется информация о результате оплаты.
Информация о результате оплаты отображается в платёжной форме Payment Page (если используется способ открытия платёжной формы в отдельной вкладке) или на странице веб-сервиса (если используется способ открытия платёжной формы в модальном окне).

Для взаимодействия с пользователями при проведении оплат могут использоваться варианты с открытием платёжной формы в отдельной вкладке и в модальном окне. В обоих этих вариантах пользователь сначала подтверждает переход к оплате (с помощью кнопки PLACE ORDER в веб-сервисе), после чего указывает необходимые данные и подтверждает формирование платежа в платформе ecommpay (с помощью соответствующих полей и кнопки Оплатить в открывшейся платёжной форме).

Вместе с тем, следует учитывать, что для заказов в веб-сервисе и платежей в платёжной платформе используются разные идентификаторы и статусы. Заказам на стороне веб-сервиса присваиваются порядковые номера (например, 71) и статусы, используемые при работе с плагином ecommpay payments. В зависимости от состояний платежей в платформе эти статусы могут быть следующими:

ecommpay: Pending, если платёж находится в промежуточном статусе;
ecommpay: Approved, если платёж проведён;
ecommpay: Declined, если платёж отклонён;
ecommpay: Partially refunded, если в рамках заказа был выполнен частичный возврат средств;
ecommpay: Refund, если в рамках заказа был выполнен возврат полной суммы платежа.

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

С вопросами о соответствии статусов заказов и платежей можно обращаться к курирующему менеджеру ecommpay.

Установка

Чтобы начать работу с плагином ecommpay payments версии 1.0.2, его необходимо установить.

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

Скопировать значения параметров работы плагина для их последующего указания при работе с новой версией.
Это связано с тем, что при обновлении плагина указанные ранее данные не сохраняются.
Деактивировать предыдущую версию плагина.
Это можно сделать через список установленных плагинов в интерфейсе PrestaShop, с помощью кнопки Uninstall.

Для установки плагина следует скачать его zip-архив на портале GitHub и выполнить следующие действия в интерфейсе PrestaShop:

Выбрать раздел Modules и пункт Module Manager в секции IMPROVE на панели навигации.
Щёлкнуть кнопку Upload a module на странице Module Manager и выбрать предварительно скачанный zip-архив плагина.
Дождаться завершения загрузки (установка плагина при этом осуществляется автоматически).

После выполнения этих действий на странице Module Manager можно найти панель плагина ecommpay payments и приступить к работе с ним.

Рис. 4. Страница Module Manager с панелью плагина в интерфейсе PrestaShop

Тестирование

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

Для проверки работы плагина и проведения тестовых платежей без реального списания средств можно использовать два варианта:

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

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


Возможности тестирования	через тестовый режим плагина	через тестовую среду платформы
Открытие платёжной формы с применением различных способов и параметров работы	+	+
Проведение разовых оплат	+	+
Использование альтернативных платёжных методов (при обращении к специалистам ecommpay)	–	+
Использование дополнительных возможностей платёжной формы Payment Page (при обращении к специалистам ecommpay)	–	+
Выполнение возвратов	+	+
Контроль информации о платежах	+	+
Управление заказами	+	+

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

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

Чтобы подготовить плагин к тестированию, необходимо определить предпочтительный вариант тестирования и настроить плагин в интерфейсе PrestaShop. Для этого следует:

Перейти к параметрам работы плагина в интерфейсе PrestaShop.
Для этого следует:
1. Выбрать раздел Modules и пункт Module Manager в секции IMPROVE на панели навигации.
2. Выполнить поиск плагина ecommpay payments на открывшейся странице и щёлкнуть кнопку Configure в соответствующей строке.
Задать основные параметры работы плагина ecommpay payments:
- Test mode — возможность установить тестовый режим работы плагина.;
  Для использования тестового режима плагина необходимо установить этот флажок, для использования тестовой среды платформы — снять и задать параметры подключения, полученные от ecommpay, в полях Project ID и Secret key.
  Прим.: При работе в тестовом режиме плагина значения, указанные в полях Project ID и Secret key, игнорируются.
- Project ID — идентификатор тестового проекта.;
- Secret key — ключ тестового проекта.;
- Title — название варианта оплаты с использованием плагина, отображаемое на странице перехода к оплате в веб-сервисе.;
- Description — текст, отображаемый пользователям при выборе варианта оплаты с использованием плагина.;
  Прим.: При необходимости поля Title и Description могут использоваться для предупреждения пользователей о работе плагина в тестовом режиме.
- Currency — валюта проведения платежей с использованием плагина.;
- Language — язык отображения платёжной формы.;
- Popup mode — возможность выбрать вариант открытия платёжной формы Payment Page в модальном окне.;
  Для открытия формы в модальном окне необходимо установить этот флажок, для открытия в отдельной вкладке — снять.
- Additional parameters — дополнительные параметры вызова платёжной формы. При указании в этом поле нескольких параметров в качестве разделителя необходимо использовать символ &.
Сохранить параметры работы плагина.
Для этого следует щёлкнуть кнопку Save Settings.

Рис. 5. Страница с параметрами подключения

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

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

Чтобы тестировать проведение карточных платежей, можно использовать номера тестовых карт. При этом для тестирования по заданным кратчайшим сценариям (без эмулирования аутентификации 3‑D Secure) можно использовать следующие номера карт:

4000 0000 0000 0077 — для проведения оплаты;
4111 1111 1111 1111 — для отклонения оплаты.

Для более масштабного тестирования можно использовать расширенный набор тестовых данных для карточных платежей (подробнее). (в том числе с аутентификацией 3‑D Secure), представленных в статье Тестовые карты.

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

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

Введение

После проведения тестовых оплат можно тестировать выполнение возвратов через интерфейс PrestaShop, и если актуально, через интерфейсы Gate и Dashboard от ecommpay. При этом следует учитывать, что для выполнения возвратов заказы в интерфейсе PrestaShop должны быть в статусах ecommpay: Approved или ecommpay: Partially refunded, а платежи на стороне платёжной платформы ecommpay — в статусах success, partially reversed или partially refunded. Также можно иметь в виду, что вся информация о тестовых возвратах, представленная в этом подразделе, актуальна и для выполнения возвратов в рабочей среде.

Обеспечение синхронизации данных

При инициировании возвратов через интерфейсы платёжной платформы ecommpay (Dashboard и Gate API) информация о заказах в интерфейсе PrestaShop обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускаются возвраты через интерфейсы платформы ecommpay и контроль информации о заказах через интерфейс PrestaShop, важно обеспечить отправку оповещений для автоматического обновления информации в интерфейсе PrestaShop. Для этого должны выполняться следующие условия:

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

Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS PrestaShop, на URL, отображаемый на странице с параметрами работы плагина (в формате https://<sitedomain>/en/module/ecommpay/callback).
Информация о работе с правилами отправки оповещений представлена в отдельной статье.
Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода.

Процедуры

Выполнять возвраты можно для проведённых оплат, по которым не были возвращены их полные суммы. На стороне платёжной платформы ecommpay таким оплатам соответствуют статусы success, partially reversed или partially refunded. В свою очередь, контролировать выполнение возвратов можно через интерфейсы платформы ecommpay и интерфейс PrestaShop.

Чтобы выполнить возврат через интерфейс PrestaShop, следует:

Перейти к карточке заказа, в рамках которого необходимо выполнить возврат.
Для этого следует выбрать пункт Orders в разделе Orders секции SELL и щёлкнуть строку требуемого заказа.
Инициировать возврат.
Для этого следует:
1. Раскрыть панель Products, щёлкнув кнопку Partial refund.
2. Указать сумму возврата в поле Amount (Tax included) и установить флажок Refund via ecommpay.
3. Щёлкнуть кнопку Partial refund в правой нижней части панели Products.
Убедиться в выполнении возврата.
Для этого можно проверить, что статус заказа изменился на ecommpay: Partially refunded (при частичном возврате) или ecommpay: Refund (при полном возврате).

Рис. 6. Панель Products с возможностью выполнения возвратов в карточке заказа

Чтобы выполнить возврат через Gate API или Dashboard платформы ecommpay, следует использовать процедуры, представленные в соответствующих статьях: Возвраты средств после оплат (для Gate API) и Выполнение возвратов (для интерфейса Dashboard).

Использование

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

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

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

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

Чтобы настроить параметры работы плагина, следует:

Перейти к параметрам работы плагина в интерфейсе PrestaShop.
Для этого следует:
1. Выбрать раздел Modules и пункт Module Manager в секции IMPROVE на панели навигации.
2. Выполнить поиск плагина ecommpay payments на открывшейся странице и щёлкнуть кнопку Configure в соответствующей строке.
Задать параметры работы плагина ecommpay payments:
- Test mode — возможность установить тестовый режим работы плагина.;
  Для использования рабочей среды платформы необходимо снять этот флажок и задать параметры подключения, полученные от ecommpay, в полях Project ID и Secret key.
- Project ID — идентификатор рабочего проекта.;
- Secret key — ключ рабочего проекта.;
- Title — название варианта оплаты с использованием плагина, отображаемое на странице перехода к оплате в веб-сервисе.;
- Description — текст, отображаемый пользователям при выборе варианта оплаты с использованием плагина.;
  Прим.: Если при тестировании плагина в полях Title и Description использовались соответствующие предупреждения, при переводе плагина в рабочий режим важно их убрать.
- Currency — валюта проведения платежей с использованием плагина.;
- Language — язык отображения платёжной формы.;
- Popup mode — возможность выбрать вариант открытия платёжной формы Payment Page в модальном окне.;
  Для открытия формы в модальном окне необходимо установить этот флажок, для открытия в отдельной вкладке — снять.
- Additional parameters — дополнительные параметры вызова платёжной формы. При указании в этом поле нескольких параметров в качестве разделителя необходимо использовать символ &.
Сохранить параметры работы плагина.
Для этого следует щёлкнуть кнопку Save Settings.

Рис. 7. Страница с параметрами подключения

Проведение оплат

Если веб-сервис и плагин корректно настроены, оплаты проводятся автоматически. При этом важно обеспечивать сбор всех необходимых данных на стороне веб-сервиса.

Внимание: С 12 августа 2024 года в связи с вступлением в силу новых требований платёжной системы Visa расширяется набор сведений, необходимых для аутентификации 3‑D Secure при проведении оплат с использованием карт этой платёжной системы. Для сбора и передачи таких сведений на странице перехода к оплате должны использоваться поля для указания пользователем номера его телефона или адреса электронной почты.

При возникновении вопросов или проблем с проведением оплат можно обращаться к специалистам технической поддержки ecommpay.

Выполнение возвратов

Введение

После проведения оплат можно выполнять возвраты по ним через интерфейс PrestaShop, и если актуально, через интерфейсы Gate и Dashboard от ecommpay. При этом следует учитывать, что для выполнения возвратов заказы в интерфейсе PrestaShop должны быть в статусах ecommpay: Approved или ecommpay: Partially refunded, а платежи на стороне платёжной платформы ecommpay — в статусах success, partially reversed или partially refunded. Также можно иметь в виду, что все возможности и процедуры по работе с возвратами в рабочем режиме соответствуют тем, которые доступны в тестовом режиме.

Обеспечение синхронизации данных

Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS PrestaShop, на URL, отображаемый на странице с параметрами работы плагина (в формате https://<sitedomain>/en/module/ecommpay/callback).
Информация о работе с правилами отправки оповещений представлена в отдельной статье.
Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода.

Процедуры

Чтобы выполнить возврат через интерфейс PrestaShop, следует:

Перейти к карточке заказа, в рамках которого необходимо выполнить возврат.
Для этого следует выбрать пункт Orders в разделе Orders секции SELL и щёлкнуть строку требуемого заказа.
Инициировать возврат.
Для этого следует:
1. Раскрыть панель Products, щёлкнув кнопку Partial refund.
2. Указать сумму возврата в поле Amount (Tax included) и установить флажок Refund via ecommpay.
3. Щёлкнуть кнопку Partial refund в правой нижней части панели Products.
Убедиться в выполнении возврата.
Для этого можно проверить, что статус заказа изменился на ecommpay: Partially refunded (при частичном возврате) или ecommpay: Refund (при полном возврате).

Рис. 8. Панель Products с возможностью выполнения возвратов в карточке заказа

Контроль платежей и заказов

Контролировать информацию о платежах, проводимых с использованием плагина ecommpay payments, и соответствующих заказах можно через интерфейс PrestaShop, используя инструменты подраздела Orders в одноимённом разделе. При этом более подробную информацию о платежах и возвратах можно получать через интерфейс Dashboard (подробнее) и Data API (подробнее) от ecommpay.

При работе с интерфейсом PrestaShop в подразделе Orders отображается реестр заказов с основными сведениями о каждом из них, а также с возможностями поиска, фильтрации, перехода к карточкам отдельных заказов и выполнения различных действий.

Рис. 9. Реестр заказов в интерфейсе PrestaShop

Щёлкнув строку отдельного заказа в реестре, можно перейти в его карточку, где Для перехода к карточке конкретного заказа можно щёлкнуть его строку (или кнопку ) в реестре. Через карточки, в частности, можно получить получать развёрнутые сведения о нём, а также инициировать выполнение возврата заказах (например, о пользователях, приобретённых продуктах и способах доставки), а также инициировать выполнение возвратов.

Рис. 10. Карточка заказа в интерфейсе PrestaShop

Более подробную информацию о работе с заказами можно получить с помощью кнопки Help в подразделе Orders одноимённого раздела в интерфейсе PrestaShop.