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

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

• CMS Drupal версии 9.5 или выше,
• модуль Drupal Commerce версии 2.3 или выше,
• язык PHP версии 7.3 или выше.

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

Возможности

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Схемы работы

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

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

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

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

Для взаимодействия с пользователями при проведении одностадийных оплат и блокировке средств в рамках двухстадийных оплат осуществляется открытие платёжной формы Payment Page в отдельной вкладке. При этом заказ в CMS Drupal формируется после добавления пользователем товара в корзину, а платёж в платформе ecommpay — после подтверждения пользователем платежа в платёжной форме (с помощью кнопки Оплатить).

В рамках работы с плагином Commerce ecommpay каждый платёж в платёжной платформе ecommpay соответствует платежу в CMS Drupal, формируемому в рамках заказа. Это соответствие определяется идентификатором, который присваивается платежу на стороне ecommpay и отображается в карточке заказа административного интерфейса Drupal, в строке этого платежа в поле REMOTE ID.

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

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

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

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

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

1. Перейти к параметрам конфигурирования платёжных шлюзов в интерфейсе Drupal.

   Для этого следует перейти в подраздел Configuration раздела Commerce, выбрать пункт Payment gateways в секции PAYMENT и щёлкнуть кнопку + Add payment gateway.

2. Указать в качестве поставщика используемого плагина ecommpay.

   Для этого следует выбрать в переключателе Plugin значение ecommpay.

3. Задать основные параметры работы плагина (оставив, где актуально, предварительно заполненные значения):
   • Name — название плагина в административном интерфейсе Drupal.
   • Display name — название плагина, отображаемое пользователям на странице перехода к оплате в веб-сервисе.
   • Collect billing information — применение на стороне веб-сервиса функций сбора и передачи в платформу информации о пользователях.
     Внимание: Следует учитывать, что при отключении этой функциональности в платёжной форме может быть задействована процедура дополнения информации о платеже (чтобы обеспечивать возможность проведения платежей с учётом требований различных платёжных систем).
   • Project ID — идентификатор тестового проекта для взаимодействия с платформой (должен соответствовать полученному от ecommpay).
   • Secret Key — ключ тестового проекта (должен соответствовать полученному от ecommpay).
   • Conditions — условия использования плагина в веб-сервисе (подробнее).
   • Status — применение плагина в веб-сервисе (с возможностью активировать и деактивировать его через значения Enabled и Disabled).
4. Сохранить изменения в параметрах работы плагина с помощью кнопки Save.

   

5. Задать вариант проведения оплат с использованием плагина — с незамедлительным списанием средств или с предварительной блокировкой и последующим списанием.

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

   1. Перейти в подраздел Configuration раздела Commerce и щёлкнуть ссылку Checkout flows в секции ORDERS.
   2. Щёлкнуть кнопку Edit в строке с используемым режимом работы страницы перехода к оплате (в колонке OPERATIONS).
   3. Щёлкнуть кнопку на панели Payment process и задать значение для параметра Transaction mode:
      • Authorize and capture — для проведения оплат в одну стадию (с незамедлительным списанием средств);
      • Authorize only — для проведения оплат в две стадии (с предварительной блокировкой и последующим списанием средств).
   4. Щёлкнуть кнопку Update на панели, а затем — кнопку Save в нижней части страницы.

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

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

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

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

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

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

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

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

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

   Для этого следует открыть подраздел Orders раздела Commerce.

2. Перейти к требуемому заказу в реестре (с помощью кнопки View в столбце OPERATIONS).

   Для этого следует щёлкнуть кнопку View в столбце OPERATIONS реестра заказов.

3. Перейти на вкладку Payments в карточке заказа.
4. Выбрать необходимое действие в столбце OPERATIONS в строке платежа, по которому инициируется вторая стадия оплаты.

   Чтобы инициировать списание заблокированных средств, следует выбрать действие Capture. Чтобы отменить блокировку средств, следует выбрать действие Void.

5. Подтвердить выбранное действие на открывшейся странице.

   Для списания средств необходимо указать сумму и щёлкнуть кнопку Capture. Для отмены блокировки — щёлкнуть кнопку Void.

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

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

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

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

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

   Для этого следует открыть подраздел Orders раздела Commerce.

2. Перейти к требуемому заказу в реестре (с помощью кнопки View в столбце OPERATIONS).

   Для этого следует щёлкнуть кнопку View в столбце OPERATIONS соответствующей строки реестра заказов.

3. Перейти на вкладку Payments в карточке заказа.
4. Выбрать действие Refund в столбце OPERATIONS в строке платежа, по которому необходимо выполнить возврат.
5. Подтвердить выбранное действие на открывшейся странице.

   Для этого необходимо указать сумму возврата и щёлкнуть кнопку Refund.

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

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

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

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

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

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

1. Перейти к параметрам конфигурирования платёжных шлюзов в интерфейсе Drupal.

   Для этого следует перейти в подраздел Configuration раздела Commerce, выбрать пункт Payment gateways в секции PAYMENT и щёлкнуть кнопку + Add payment gateway.

2. Указать в качестве поставщика используемого плагина ecommpay.

   Для этого следует выбрать в переключателе Plugin значение ecommpay.

3. Задать основные параметры работы плагина (оставив, где актуально, предварительно заполненные значения):
   • Name — название плагина в административном интерфейсе Drupal.
   • Display name — название плагина, отображаемое пользователям на странице перехода к оплате в веб-сервисе.
   • Collect billing information — применение на стороне веб-сервиса функций сбора и передачи в платформу информации о пользователях.
     Внимание: Следует учитывать, что при отключении этой функциональности в платёжной форме может быть задействована процедура дополнения информации о платеже (чтобы обеспечивать возможность проведения платежей с учётом требований различных платёжных систем).
   • Project ID — идентификатор рабочего проекта для взаимодействия с платформой (должен соответствовать полученному от ecommpay).
   • Secret Key — ключ рабочего проекта (должен соответствовать полученному от ecommpay).
   • Conditions — условия использования плагина в веб-сервисе (подробнее).
   • Status — применение плагина в веб-сервисе (с возможностью активировать и деактивировать его через значения Enabled и Disabled).
4. Сохранить изменения в параметрах работы плагина с помощью кнопки Save.

   

5. Задать вариант проведения оплат с использованием плагина — с незамедлительным списанием средств или с предварительной блокировкой и последующим списанием.

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

   1. Перейти в подраздел Configuration раздела Commerce и щёлкнуть ссылку Checkout flows в секции ORDERS.
   2. Щёлкнуть кнопку Edit в строке с используемым режимом работы страницы перехода к оплате (в колонке OPERATIONS).
   3. Щёлкнуть кнопку на панели Payment process и задать значение для параметра Transaction mode:
      • Authorize and capture — для проведения оплат в одну стадию (с незамедлительным списанием средств);
      • Authorize only — для проведения оплат в две стадии (с предварительной блокировкой и последующим списанием средств).
   4. Щёлкнуть кнопку Update на панели, а затем — кнопку Save в нижней части страницы.

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

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

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

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

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

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

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

   Для этого следует открыть подраздел Orders раздела Commerce.

2. Перейти к требуемому заказу в реестре (с помощью кнопки View в столбце OPERATIONS).

   Для этого следует щёлкнуть кнопку View в столбце OPERATIONS соответствующей строки реестра заказов.

3. Перейти на вкладку Payments в карточке заказа.
4. Выбрать действие Refund в столбце OPERATIONS в строке платежа, по которому необходимо выполнить возврат.
5. Подтвердить выбранное действие на открывшейся странице.

   Для этого необходимо указать сумму возврата и щёлкнуть кнопку Refund.

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

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

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

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

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

• View — с информацией о заказе и заметками об изменениях в рамках этого заказа;
• Edit — с возможностью редактировать заказ;
• Payments — с информацией о платежах в рамках заказа.

Отображение информации во вкладке Payments можно редактировать, используя кнопку , а затем — Edit view в выпадающем списке. Через открывшуюся страницу для редактирования, наряду с прочим, можно управлять отображением столбцов во вкладке. В этих столбцах доступны определённые сведения о платежах и возможности выполнять конкретные действия по платежам. Так, при работе с плагином Commerce ecommpay может быть актуально отображение следующих столбцов:

• PAYMENT — сумма платежа и сумма возврата, если по этому платежу был выполнен возврат средств.
• STATE — статус платежа на стороне CMS Drupal.
• REMOTE STATE — статус платежа на стороне организации, через которую был инициирован платёж.

  При работе с плагином Commerce ecommpay значение этого параметра соответствует статусу платежа в платёжной платформе ecommpay.

• PAYMENT GATEWAY — название плагина в административном интерфейсе Drupal.

  При работе с плагином Commerce ecommpay значение этого параметра соответствует значению из параметра Name в параметрах работы плагина.

• REMOTE ID — идентификатор платежа на стороне организации, через которую был инициирован платёж.

  При работе с плагином Commerce ecommpay значение этого параметра соответствует идентификатору платежа в платёжной платформе ecommpay.

• OPERATIONS — возможность выбрать действие для выполнения в рамках платежа.

  В этом столбце могут быть доступны следующие кнопки:

  • Capture — для инициирования списаний в рамках двухстадийных оплат;
  • Void — для отмены списаний в рамках двухстадийных оплат;
  • Refund — для выполнения возвратов по оплатам;
  • Delete — для удаления информации о платежах из CMS Drupal.

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