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

Введение

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

Прим.: В документации Magento и Hyvä для обозначения плагинов используется термин modules.

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

Рис. 1. Административный интерфейс Magento
Рис. 2. Интерфейс платёжной формы Payment Page на странице веб-сервиса

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

Возможности

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

  • Встраивать в веб-сервис возможность вызова платёжной формы Payment Page от ecommpay.

    Для этого достаточно установить плагин от ecommpay и настроить его использование через интерфейс Magento.

  • Настраивать использование отдельных платёжных методов, подключённых в рамках проекта мерчанта.

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

  • Настраивать оформление веб-сервиса с использованием тем оформления от Hyvä Themes и со встраиванием платёжной формы Payment Page от ecommpay на страницу формирования заказов Hyvä Checkout.

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

  • Тестировать работу платёжной формы и возможности проведения платежей.

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

  • Проводить разовые оплаты в одну или две стадии.

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

  • Выполнять частичные и полные возвраты средств по оплатам, проведённым с помощью плагина.

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

  • Контролировать информацию о платежах, проводимых с помощью плагина.

    Это можно делать через интерфейс Magento и, если актуально, — через Data API и пользовательский интерфейс Dashboard от ecommpay.

  • Управлять заказами, оплаты по которым проводятся с помощью плагина, через интерфейс Magento.

    При этом можно отменять такие заказы и корректировать их статусы вручную.

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

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

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

Схемы работы

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

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

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

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

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

Рис. 4. Проведение двухстадийной оплаты с использованием плагина. Описание шагов
  1. Пользователь на стороне веб-сервиса открывает страницу перехода к оплате и выбирает один из методов оплаты, доступных через плагин от ecommpay.
  2. С помощью плагина автоматически формируется и отправляется в платёжную платформу ecommpay запрос на открытие платёжной формы Payment Page с учётом выбранного пользователем метода.
  3. Запрос на открытие Payment Page поступает в платёжную платформу.
  4. В платформе выполняется обработка запроса, с проверкой его корректности.
  5. В платформе обеспечивается подготовка к открытию Payment Page.
  6. Пользователю отображается платёжная форма.
  7. Пользователь выполняет необходимые действия и подтверждает готовность провести оплату.
  8. В платёжную платформу поступает запрос на выполнение блокировки средств.
  9. Запрос передаётся в платёжную среду.
  10. В платёжной среде выполняется обработка платежа и блокировка средств пользователя. При этом, если необходимо, обеспечивается выполнение дополнительных действий со стороны платформы и пользователя (например, для аутентификации 3‑D Secure).
  11. Из платёжной среды к платёжной платформе направляется информация о результате блокировки средств.
  12. От платёжной платформы к веб-сервису направляется оповещение о результате блокировки. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе Magento обновляются базовые сведения о платеже.
  13. От платёжной платформы к Payment Page направляется информация о результате блокировки.
  14. Информация о результате блокировки отображается пользователю в платёжной форме Payment Page.
  15. После того как подтверждается необходимость списания средств, специалист мерчанта инициирует это списание, в результате чего (с помощью плагина) запрос на списание средств поступает в платёжную платформу и обрабатывается в ней.
  16. Запрос передаётся в платёжную среду.
  17. В платёжной среде выполняется обработка платежа.
  18. Из платёжной среды к платёжной платформе направляется информация о результате списания.
  19. От платёжной платформы к веб-сервису направляется оповещение о результате списания. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе Magento формируется счёт на оплату и обновляются базовые сведения о платеже.
  20. Пользователь уведомляется о результате списания средствами веб-сервиса.

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

  • со встраиванием платёжной формы непосредственно в интерфейс веб-сервиса (через элемент iframe);
  • с открытием платёжной формы в модальном окне или отдельной вкладке.

Первый из этих вариантов доступен только для оплат с прямым использованием платёжных карт и используется для них по умолчанию. В первомэтом варианте пользователь указывает данные платёжной карты и подтверждает формирование заказа в CMS Magento и платежа в платформе ecommpay непосредственно на странице перехода к оплате в веб-сервисе (с помощью кнопки Place Order).

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

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

Контролировать информацию о заказах и платежах по ним можно через интерфейс Magento: в подразделе Orders раздела Sales. При этом следует учитывать, что для заказов и платежей используются разные идентификаторы и статусы. Заказам на стороне веб-сервиса присваиваются девятизначные номера (например, 000001503) и статусы в соответствии с моделью выполнения заказов Magento (подробнее), платежам на стороне платёжной платформы — идентификаторы, включающие в себя префикс mag_ и тринадцатизначный код (например, mag_64ca3135cffd3), и статусы в соответствии с моделью проведения платежей ecommpay (подробнее). С вопросами о соответствии статусов заказов и платежей можно обращаться к курирующему менеджеру ecommpay.

Установка

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

Чтобы начать работу с плагином от ecommpay версии 2.1.6 для CMS Magento, его необходимо установить. Это можно сделать через каталог плагинов Magento (без предварительного скачивания файлов плагина) или через загрузку zip-архива с файлами плагина (предварительно скачав этот архив).

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

Установка через каталог плагинов

Для установки через каталог плагинов следует:

  1. Выполнить команду composer require ecommpay/module-payments из корневой папки с файлами CMS Magento.
  2. При необходимости получить и указать ключ аутентификации для доступа к интеграционным модулям на стороне CMS Magento.
  3. Выполнить следующие команды из корневой папки с файлами CMS Magento и дождаться завершения установки.
    php bin/magento setup:upgrade
php bin/magento cache:flush
php bin/magento cache:clean
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy

Установка через загрузку архива

Для установки плагина через загрузку zip-архива следует:

  1. Скачать zip-архив плагина с портала GitHub.
  2. Распаковать zip-архив и добавить папку с файлами плагина в папку с исходным кодом веб-сервиса на базе CMS Magento — во вложенную папку app/code.
    Notice:

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

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

  3. Выполнить следующие команды из корневой папки с файлами CMS Magento и дождаться завершения установки.
    php bin/magento indexer:reindex 
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush
php bin/magento cache:clean
php bin/magento setup:static-content:deploy

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

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

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

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

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

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

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

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

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

  1. Перейти к параметрам работы плагина в интерфейсе Magento.

    Для этого следует:

    1. Выбрать раздел Stores на панели навигации и пункт Configuration в появившемся меню.
    2. Выбрать раздел Sales и пункт Payment Methods в левом меню подраздела Configuration.
    3. Найти секцию с параметрами работы плагина от ecommpay на открывшейся странице и щёлкнуть кнопку Configure.
  2. Задать основные параметры работы плагина в раскрывающемся блоке General settings:
    • Plugin Enabled — возможность подключить плагин к веб-сервису.;

      Если для этого параметра задано значение Yes, то все платёжные методы, ранее подключённые для работы через плагин, становятся доступными в веб-сервисе. Если задано значение No, то все платёжные методы отключаются от веб-сервиса и становятся недоступными для проведения платежей.

    • Demo mode — возможность установить тестовый режим работы плагина.;

      Для использования тестового режима работы плагина необходимо задать значение Yes, для использования тестовой среды платформы — задать значение No и параметры подключения, полученные от ecommpay, в полях Project ID и Secret Key.

      Прим.: При работе в тестовом режиме плагина значения, заданные в полях Project ID и Secret Key, игнорируются. Поэтому для использования тестового проекта в платёжной платформе ecommpay необходимо отключить тестовый режим плагина.
    • Project ID — идентификатор тестового проекта.;
    • Secret Key — ключ тестового проекта для взаимодействия с платформой.;
    • Language — язык отображения платёжной формы.;
    • Additional parameters — дополнительные параметры вызова платёжной формы;. При указании в этом поле нескольких параметров в качестве разделителя необходимо использовать символ &.
    • Payment action — вариант проведения оплат: Authorize (для проведения двухстадийных оплат) или Authorize and Capture (для проведения одностадийных оплат).
      • Authorize — в две стадии (с предварительной блокировкой и последующим списанием средств);
      • Authorize and Capture — в одну стадию (с незамедлительным списанием средств).

      Первый вариант доступен только для платежей с прямым использованием карт или методов Apple Pay и Google Pay, а второй — для всех платёжных методов, подключённых для работы через плагин.

    Рис. 5. Блок General settings с основными параметрами подключения
  3. Задать параметры использования платёжных методов (подробнее).

    При работе в тестовом режиме плагина достаточно задать параметры для карточных платежей в раскрывающемся блоке Card payments или More payment methods via ecommpay.

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

    Для этого следует щёлкнуть кнопку Save Config.

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

Введение

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

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

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

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

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

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

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

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

  • Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS Magento, на URL в формате https://<merchant domain>/ecommpay/endpayment/index.

    Информация о работе с правилами отправки оповещений представлена в отдельной статье.

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

    Иначе в протоколах работы плагина появляются сообщения об ошибках, связанных с обработкой оповещений от платёжной платформы.

Процедуры

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

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

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

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

  2. Выбрать заказ, в рамках которого необходимо инициировать вторую стадию оплаты.
  3. Инициировать вторую стадию оплаты.

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

    1. Щёлкнуть кнопку Invoice в верхнем меню карточки заказа.
    2. Убедиться, что в столбце Qty to Invoice на открывшейся странице выбрано количество товаров, за которое необходимо выполнить списание.
      Прим.: Следует учитывать, что при списании средств только за часть товаров в рамках заказа блокировка оставшейся суммы автоматически отменяется.
    3. Убедиться, что для параметра Amount в нижней части страницы выбрано значение Capture Online, и щёлкнуть кнопку Submit Invoice.

    Для отмены блокировки средств следует щёлкнуть кнопку Void в верхнем меню карточки заказа и подтвердить действие в появившемся диалоговом окне.

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

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

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

Введение

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

Notice: Когда из платформы ecommpay в веб-сервис поступает информации о платеже, проведённом в рамках заказа, для этого заказа в интерфейсе Magento автоматически формируется счёт на оплату — invoice (информацию о таком счёте можно получить в разделе Invoices в карточке заказа). До формирования счёта на оплату выполнить возврат в рамках соответствующего заказа через интерфейс Magento нельзя.

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

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

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

  • Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS Magento, на URL в формате https://<merchant domain>/ecommpay/endpayment/index.

    Информация о работе с правилами отправки оповещений представлена в отдельной статье.

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

    Иначе в протоколах работы плагина появляются сообщения об ошибках, связанных с обработкой оповещений от платёжной платформы.

Процедуры

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

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

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

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

  2. Выбрать заказ, по которому необходимо выполнить возврат средств, и выбрать пункт Invoices в левом меню карточки заказа.
  3. Выбрать счёт на оплату, в рамках которого был проведён платёж, в таблице и щёлкнуть кнопку Credit Memo в верхнем меню страницы счёта на оплату.
  4. Указать количество товаров, которые необходимо вернуть, и при необходимости щёлкнуть кнопку Update Qty's для обновления суммы возврата на странице выполнения возвратов New Memo.
  5. При необходимости указать комментарий для возврата в поле Credit Memo Comments.
  6. Подтвердить выполнение возврата.

    Для этого следует щёлкнуть кнопку Refund.

  7. Убедиться в том, что в истории заказа отображается информация о выполненном возврате.

    При выполнении частичного возврата заказу присваивается статус Processing, при выполнении полного возврата заказу присваивается статус Closed.

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

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

При выполнении возвратов через интерфейс Magento в этом интерфейсе формируются записи с информацией о таких возвратах — credit memos. Просматривать такие записи можно через раздел Credit Memos в карточках отдельных заказов, а более детальную информацию о возвратах можно получать через интерфейсы платформы ecommpay (например, Dashboard и Data API).

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

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

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

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

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

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

  1. Перейти к параметрам работы плагина в интерфейсе Magento.

    Для этого следует:

    1. Выбрать раздел Stores на панели навигации и пункт Configuration в появившемся меню.
    2. Выбрать раздел Sales и пункт Payment Methods в левом меню подраздела Configuration.
    3. Найти секцию с параметрами работы плагина от ecommpay на открывшейся странице и щёлкнуть кнопку Configure.
  2. Задать основные параметры работы плагина в раскрывающемся блоке General settings:
    • Plugin Enabled — возможность подключить плагин к веб-сервису.

      Если для этого параметра задано значение Yes, то все платёжные методы, ранее подключённые для работы через плагин, становятся доступными в веб-сервисе. Если задано значение No, то все платёжные методы отключаются от веб-сервиса и становятся недоступными для проведения платежей.

    • Demo mode — возможность установить тестовый режим работы плагина.

      Для использования рабочей среды платформы следует задать значение No и параметры подключения, полученные от ecommpay, в полях Project ID и Secret Key.

    • Project ID — идентификатор рабочего проекта.
    • Secret Key — ключ рабочего проекта для взаимодействия с платформой.
    • Language — язык отображения платёжной формы.
    • Additional parameters — дополнительные параметры вызова платёжной формы. При указании в этом поле нескольких параметров в качестве разделителя необходимо использовать символ &.
    • Payment action — вариант проведения оплат: Authorize (для проведения двухстадийных оплат) или Authorize and Capture (для проведения одностадийных оплат).
      • Authorize — в две стадии (с предварительной блокировкой и последующим списанием средств);
      • Authorize and Capture — в одну стадию (с незамедлительным списанием средств).

      Первый вариант доступен только для платежей с прямым использованием карт или методов Apple Pay и Google Pay, а второй — для всех платёжных методов, подключённых для работы через плагин.

    Рис. 7. Блок General settings с основными параметрами подключения
  3. Задать параметры использования платёжных методов (подробнее).
  4. Сохранить параметры работы плагина.

    Для этого следует щёлкнуть кнопку Save Config.

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

Введение

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

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

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

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

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

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

  • Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS Magento, на URL в формате https://<merchant domain>/ecommpay/endpayment/index.

    Информация о работе с правилами отправки оповещений представлена в отдельной статье.

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

    Иначе в протоколах работы плагина появляются сообщения об ошибках, связанных с обработкой оповещений от платёжной платформы.

Процедуры

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

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

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

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

  2. Выбрать заказ, в рамках которого необходимо инициировать вторую стадию оплаты.
  3. Инициировать вторую стадию оплаты.

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

    1. Щёлкнуть кнопку Invoice в верхнем меню карточки заказа.
    2. Убедиться, что в столбце Qty to Invoice на открывшейся странице выбрано количество товаров, за которое необходимо выполнить списание.
      Прим.: Следует учитывать, что при списании средств только за часть товаров в рамках заказа блокировка оставшейся суммы автоматически отменяется.
    3. Убедиться, что для параметра Amount в нижней части страницы выбрано значение Capture Online, и щёлкнуть кнопку Submit Invoice.

    Для отмены блокировки средств следует щёлкнуть кнопку Void в верхнем меню карточки заказа и подтвердить действие в появившемся диалоговом окне.

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

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

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

Введение

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

Notice: Когда из платформы ecommpay в веб-сервис поступает информации о платеже, проведённом в рамках заказа, для этого заказа в интерфейсе Magento автоматически формируется счёт на оплату — invoice (информацию о таком счёте можно получить в разделе Invoices в карточке заказа). До формирования счёта на оплату выполнить возврат в рамках соответствующего заказа через интерфейс Magento нельзя.

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

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

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

  • Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS Magento, на URL в формате https://<merchant domain>/ecommpay/endpayment/index.

    Информация о работе с правилами отправки оповещений представлена в отдельной статье.

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

    Иначе в протоколах работы плагина появляются сообщения об ошибках, связанных с обработкой оповещений от платёжной платформы.

Процедуры

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

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

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

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

  2. Выбрать заказ, по которому необходимо выполнить возврат средств, и выбрать пункт Invoices в левом меню карточки заказа.
  3. Выбрать счёт на оплату, в рамках которого был проведён платёж, в таблице и щёлкнуть кнопку Credit Memo в верхнем меню страницы счёта на оплату.
  4. Указать количество товаров, которые необходимо вернуть, и при необходимости щёлкнуть кнопку Update Qty's для обновления суммы возврата на странице выполнения возвратов New Memo.
  5. При необходимости указать комментарий для возврата в поле Credit Memo Comments.
  6. Подтвердить выполнение возврата.

    Для этого следует щёлкнуть кнопку Refund.

  7. Убедиться в том, что в истории заказа отображается информация о выполненном возврате.

    При выполнении частичного возврата заказу присваивается статус Processing, при выполнении полного возврата заказу присваивается статус Closed.

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

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

При выполнении возвратов через интерфейс Magento в этом интерфейсе формируются записи с информацией о таких возвратах — credit memos. Просматривать такие записи можно через раздел Credit Memos в карточках отдельных заказов, а более детальную информацию о возвратах можно получать через интерфейсы платформы ecommpay (например, Dashboard и Data API).

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

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

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

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

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

  • Order & Account Information — с информацией о заказе и пользователе;
  • Address Information — с информацией о расчётном адресе и адресе доставки пользователя;
  • Payment & Shipping Method — с базовыми сведениями о платеже и способе доставки;
  • Items Ordered — с информацией о приобретённых товарах.
Рис. 10. Карточка заказа в интерфейсе Magento

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

  • Authorization — при блокировке средств (выполнении операции auth);
  • Capture — при списании средств (выполнении операции capture для двухстадийной оплаты или операции sale для одностадийной оплаты);
  • Void — при отмене блокировки средств в рамках двухстадийной оплаты (выполнении операции cancel);
  • Refund — при выполнении возврата (выполнении операции refund).

Идентификатор каждой транзакции (Transaction ID) соответствует идентификатору запроса на выполнение операции в платёжной платформе и присваивается следующей транзакции в заказе в качестве идентификатора „родительской“ транзакции (Parent Transaction ID).

Рис. 11. Реестр транзакций в интерфейсе Magento

Более подробная информация о работе с заказами в интерфейсе Magento представлена в документации Magento.

Использование тем оформления Hyvä

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

Для веб-сервисов, разработанных на базе CMS Magento версии 2.0, доступна возможность использовать вместо базовых тем Blank и Luma альтернативную тему оформления от Hyvä с поддержкой актуальных технологий и тенденций (подробнее). При работе с плагином от ecommpay для Magento можно использовать эту тему, установив в дополнение к нему следующие плагины:

  • Hyvä Themes версии 1.3 и выше — для подключения темы оформления веб-сервиса;
  • Hyvä Checkout версии 1.3 и выше — для подключения темы оформления страницы формирования заказов;
  • ecommpay Hyvä — для подключения платёжной формы Payment Page, адаптированной под работу с плагином Hyvä Checkout.

С темой оформления от Hyvä можно гибко настраивать страницу формирования заказов, размещая все шаги (заполнение контактных данных пользователей, информации о доставке и оплате) на одном экране или разделяя их на отдельные экраны. Независимо от выбранного варианта, работа с платёжной формой Payment Page поддерживается двумя способами — со встраиванием платёжной формы непосредственно в интерфейс веб-сервиса и с открытием платёжной формы в модальном окне или отдельной вкладке.

Кроме того, платёжная форма Payment Page, подключаемая с плагином ecommpay Hyvä, обратно совместима с базовыми темами Blank и Luma, благодаря чему использование базовых тем с этим плагином не влияет на проходимость платежей.

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

Чтобы начать работу с темой оформления Hyvä вместе с плагином от ecommpay для CMS Magento версии 2.0, необходимо дополнительно установить плагины от Hyvä и ecommpay и применить тему оформления Hyvä. Установка выполняется через через каталог плагинов Magento (без предварительного скачивания файлов плагина) или через загрузку zip-архива с файлами плагина (предварительно скачав этот архив).

Для работы с темой оформления Hyvä следует:

  1. Установить плагины Hyvä Themes и Hyvä Checkout и убедиться, что они установлены в качестве зависимостей.

    Для этого необходимо установить плагины в соответствии с инструкциями Hyvä Themes и Hyvä Checkout и проверить в файле composer.json из корневой папки с файлами CMS Magento наличие следующих зависимостей.

    "hyva-themes/magento2-default-theme": "^1.3",
"hyva-themes/magento2-hyva-checkout": "^1.3"
  2. Установить плагин ecommpay Hyvä в дополнение к плагину от ecommpay для CMS Magento версии 2.0 и убедиться, что он установлен в качестве зависимости.

    Для установки плагина через каталог плагинов необходимо выполнить следующие команды из корневой папки с файлами CMS Magento.

    composer config repositories.ecommpay/hyva-magento git https://github.com/ITECOMMPAY/hyva-magento.githttps://github.com/ITECOMMPAY/hyva-magento.git
composer require ecommpay/hyva-magento

    Для установки плагина через загрузку zip-архива следует скачать zip-архив плагина с портала GitHub, распаковать zip-архив и добавить папку с файлами плагина в папку с исходным кодом веб-сервиса на базе CMS Magento.

    В случае, если плагин от ecommpay для CMS Magento версии 2.0 ещё не установлен, он устанавливается автоматически вместе с плагином ecommpay Hyvä через каталог плагинов либо самостоятельно через загрузку zip-архива (подробнее).

    Для проверки наличия зависимостей необходимо открыть файл composer.json из корневой папки с файлами CMS Magento и найти их по названиям — ecommpay/hyva-magento и ecommpay/module-payments.

  3. Активировать установленные плагины, выполнив следующие команды.
    bin/magento setup:upgrade
bin/magento cache:flush
bin/magento cache:clean
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
  4. Применить тему оформления Hyvä и, при необходимости, настроить свойства плагинов в интерфейсе Magento, следуя инструкциям Hyvä Themes и Hyvä Checkout.
    Прим.: Важно учитывать, что в набор обязательных сведений для проведении карточных оплат включены параметры, которые необходимы для проверки AVS (Address Verification Service). Поэтому при открытии платёжной формы в элементе iframe (в режиме Embedded) на странице перехода к оплате должны использоваться поля для указания пользователем его почтового индекса и адреса доставки. Для этого в свойствах плагина Hyvä Checkout необходимо отметить поле postcode и одно из полей из группы street в качестве обязательных для заполнения пользователем.
  5. Убедиться, что активированы установленные плагины и применена тема оформления Hyvä.

    Для этого необходимо перейти в веб-сервис и протестировать формирование заказа с переходом к его оплате.

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

Параметры использования платёжных методов

При работе с плагином от ecommpay в интерфейсе Magento можно настраивать использование различных платёжных методов, подключённых в рамках проекта мерчанта. Это можно делать через отдельные раскрывающиеся блоки на странице с параметрами работы плагина, задавая следующие параметры: — Card payments (с параметрами для карточных платежей) и Alternative payment settings (с параметрами использования альтернативных методов). Последний блок в частности содержит блок More payment methods via ecommpay, в котором можно настраивать использование полной группы методов, подключённых в проекте, — это может быть актуально, например, когда используются методы, для которых не выделены отдельные блоки в параметрах работы плагина.

Notice: Раскрывающиеся блоки, отображаемые по умолчанию, исключить из параметров работы плагина нельзя, даже если соответствующие методы не используются в проекте. Если актуально работать с другими методами, их использование в плагине можно настраивать только в блоке More payment methods via ecommpay, предварительно обратившись к специалистам технической поддержки ecommpay для подключения методов в проекте.

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

  • Общие параметры:
    • Enabled — возможность подключить платёжный метод для работы через плагин.;

      Для подключения метода следует установить значение Yes, для отключения метода — значение No.

    • Title — название платёжного метода, отображаемое на странице перехода к оплате в веб-сервисе.;
    • Show Description — возможность отображения текста из параметра Description.;
    • Description — текст, отображаемый пользователям при выборе конкретного платёжного метода.;
    • Sort Order — порядковый номер отображения названия платёжного метода, доступного через плагин от ecommpay, на странице перехода к оплате в веб-сервисе.;

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

  • Параметры, актуальные только для блока Card payments:
    • Display mode — способ открытия платёжной формы Payment Page.

      Можно выбрать один из следующих способов:

      • Redirect — открытие в виде отдельной HTML-страницы;
      • Popup — открытие в модальном окне;
      • Embedded — открытие в элементе iframe.
        Прим.: При установке плагина или обновлении его версии этот способ настроен по умолчанию.

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

      Рис. 12. Пример открытия платёжной формы Payment Page на странице перехода к оплате
    Рис. 13. Блок Card payments с параметрами для карточных платежей
  • Параметр, актуальный только для блока More payment methods via ecommpay:
    • Payment method code — код платёжного метода, используемого как единственный дополнительный (по отношению к методам, для настройки работы с которыми применяются отдельные раскрывающиеся блоки).
      • Если не применять этот параметр, то при выборе метода оплаты в интерфейсе веб-сервиса пользователь может выбрать вариант More payment methods и перейти к платёжной форме с возможностью выбрать там один из методов, доступных для инициируемого платежа через платформу ecommpay. При этом все методы от ecommpay, доступные для выбора непосредственно в веб-сервисе (наряду с вариантом More payment methods), оказываются доступными и в платёжной форме.
      • Если указать в значении этого параметра код одного из доступных методов (в соответствии со справочником), то при выборе методов оплаты в интерфейсе веб-сервиса наряду с другими доступными там для выбора методами пользователь может выбрать указанный и перейти к работе с ним, минуя выбор каких-либо других методов в платёжной форме. Чтобы не допускать коллизий с таким выбором, при указании кода какого-либо метода в этом разделе также следует указывать название этого метода для отображения в веб-сервисе (в поле Title).
      Прим.: Поскольку в тестовом режиме работы плагина доступны оплаты только с прямым использованием платёжных карт, тестировать работу блока More payment methods via ecommpay в таком случае можно только для метода card.
    Рис. 14. Блок More payment methods via ecommpay с параметрами использования полной группы методов