Использование плагина ecommpay Salesforce Commerce Cloud Cartridge

Введение

В этой статье представлена информация о работе с платёжным плагином ecommpay Salesforce Commerce Cloud Cartridge в облачной платформе Commerce Cloud. Плагин описываемой версии 2.0 может использоваться в веб-сервисах, разработанных на базе эталонной архитектуры для создания онлайн-магазинов Storefront Reference Architecture (SFRA) версии 6.0 или выше с применением решения B2C Commerce версии 23.8 или выше. Он позволяет открывать пользователям платёжную форму Payment Page от ecommpay и обеспечивать все необходимые действия для проведения платежей.

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

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

Скачать плагин ecommpay Salesforce Commerce Cloud Cartridge можно через магазин готовых решений от Salesforce — AppExchange.

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

Возможности

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

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

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

  • Настраивать использование платёжных методов, доступных для работы через плагин, — с прямым использованием карт, сервисов Apple Pay и Google Pay, а также методов группы Open Banking (если эти методы подключены для используемого проекта).

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

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

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

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

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

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

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

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

    Для этого можно использовать интерфейс Business Manager и, если актуально, — интерфейс Dashboard от ecommpay.

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

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

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

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

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

Схемы работы

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

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

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

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

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

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

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

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

В рамках представленных общих схем возможны два варианта работы:

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

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

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

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

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

Контролировать информацию о заказах и платежах по ним можно через интерфейс Business Manager: в разделе Ordering вкладки Merchant Tools. При этом следует учитывать, что для заказов и платежей используются разные идентификаторы и статусы. Заказам на стороне веб-сервиса присваиваются восьмизначные номера (например, 00001405) и статусы в соответствии с моделью выполнения заказов B2C Commerce (подробнее), платежам на стороне платёжной платформы — идентификаторы, включающие в себя префикс sfcc_ и код из сорока трёх случайных символов (например, sfcc_jsiEZCfbMDW7n3EQp8NyDqJ8B0YubPsp13QYCmPJvia), и статусы в соответствии с моделью проведения платежей ecommpay (подробнее). С вопросами о соответствии статусов заказов и платежей можно обращаться к курирующему менеджеру ecommpay.

Пользовательские сценарии

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

  1. На стороне веб-сервиса пользователь открывает страницу перехода к оплате, указывает необходимые данные для формирования заказа и переходит к выбору способов оплаты (с помощью кнопки Next: Payment).
  2. Пользователь выбирает проведение платежа с использованием карты, указывает её реквизиты во встроенной форме Payment Page и переходит к подтверждению заказа (с помощью кнопки Next: Place Order).
  3. Пользователь подтверждает формирование заказа (с помощью кнопки Place Order).
  4. Пользователь получает информацию о результате оплаты.
В остальных случаях, при открытии платёжной формы в отдельной вкладке браузера (для всех доступных методов), пользовательский сценарий отличается только тем, что указание реквизитов следует после подтверждения формирования заказа и до получения информации о результате оплаты.

Установка

Чтобы начать работу с плагином ecommpay Salesforce Commerce Cloud Cartridge версии 2.0, предварительно необходимо скачать zip-архив эталонной архитектуры для создания онлайн-магазинов Storefront Reference Architecture (SFRA) от Salesforce (из репозитория Salesforce) и zip-архив плагина от ecommpay (из репозитория ecommpay или через магазин AppExchange) и распаковать их. Файлы эталонной архитектуры можно скачать из репозитория Salesforce, а файлы плагина — из репозитория ecommpay на портале GitHub или через магазин AppExchange. Информация о получении доступа к репозиторию Salesforce представлена в документации Salesforce.

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

  1. В случае если не установлена платформа Node.js (или установленная версия ниже 16), установить (обновить) её и выполнить команду npm install --global yarn в командной строке операционной системы.
  2. Последовательно выполнить из папки с файлами эталонной архитектуры команды yarn install и yarn build.
  3. Скопировать все файлы для подключения базовых функций эталонной архитектуры из вложенной папки SFRA/cartridges во вложенную папку ecommpay_integration/cartridges.
  4. Последовательно выполнить из папки ecommpay_integration команды yarn install и yarn build.
  5. Создать файл dw.json в папке ecommpay_integration.

    Этот файл должен содержать данные для доступа к виртуальному окружению, в рамках которого осуществляется разработка веб-сервиса (sandbox). Также в файле необходимо указать версию исходного кода веб-сервиса, для которой актуально установить плагин. (Версии, использованные при работе с платформой Commerce Cloud, можно найти в интерфейсе Business Manager — на вкладке Administration, в подразделе Code Deployment раздела Site Development.) Информация об этом файле и работе с ним представлена в документации Salesforce.

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

  6. Выполнить команду yarn uploadCartridge из папки ecommpay_integration.
  7. Активировать версию кода, указанную в файле dw.json, через интерфейс Business Manager.

    Это можно сделать на вкладке Administration, в подразделе Code Development раздела Site Development.

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

    1. Перейти на вкладку Administration и далее в подраздел Code Development раздела Site Development.
    2. Щёлкнуть ссылку Activate в строке с нужной версией.
  8. Подключить плагин Salesforce Commerce Cloud Cartridge для работы в веб-сервисе.

    Для этого следует указать названия файлов плагина (int_ecommpay_sfra:int_ecommpay_core) первыми слева в значении для параметра Cartridges в параметрах работы веб-сервиса в интерфейсе Business Manager.

    За названиями файлов плагина ecommpay Salesforce Commerce Cloud Cartridge могут следовать названия любых других файлов для подключения дополнительных функций. При этом последним в параметре необходимо указать название файла с базовыми функциями эталонной архитектуры app_storefront_base.

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

    1. Перейти на вкладку Administration интерфейса Business Manager и далее в подраздел Manage Sites раздела Sites.
    2. Перейти к параметрам работы веб-сервиса, щёлкнув его название в реестре Storefront Sites, и перейти на вкладку Settings.
    3. Указать названия файлов плагина в параметре Cartridges первыми слева, используя двоеточие в качестве разделителя, — int_ecommpay_sfra:int_ecommpay_core — и щёлкнуть кнопку Apply.

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

    Рис.: Параметры работы веб-сервиса в интерфейсе Business Manager

  9. Подключить плагин ecommpay Salesforce Commerce Cloud Cartridge для работы в интерфейсе Business Manager.

    Для этого следует указать названия файлов плагина (bm_ecommpay:int_ecommpay_core) первыми слева в значении для параметра Cartridges в параметрах работы интерфейса Business Manager.

    За названиями файлов плагина ecommpay Salesforce Commerce Cloud Cartridge могут следовать названия любых других файлов для подключения дополнительных функций. При этом последним в параметре необходимо указать название файла с базовыми функциями эталонной архитектуры bm_app_storefront_base.

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

    1. Перейти на вкладку Administration и далее в подраздел Manage Sites раздела Sites и щёлкнуть ссылку Business Manager в секции Business Manager Site.
    2. Указать названия файлов плагина в значении для параметра Cartridges первыми слева, используя двоеточие в качестве разделителя, — bm_ecommpay:int_ecommpay_core — и щёлкнуть кнопку Apply.

      За названиями файлов плагина ecommpay Salesforce Commerce Cloud Cartridge могут следовать названия любых других файлов для подключения дополнительных функций. При этом последним в параметре необходимо указать название файла с базовыми функциями эталонной архитектуры bm_app_storefront_base.

    Рис.: Параметры работы интерфейса Business Manager

  10. Добавить метаданные плагина в веб-сервис.

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

    1. Изменить название папки RefArchGlobal на идентификатор веб-сервиса во вложенной папке ecp_meta/sites.

      Идентификатор веб-сервиса отображается в интерфейсе Business Manager, в подразделе Manage Sites раздела Sites.

    2. Выполнить команду yarn zipMetadata из папки ecommpay_integration для создания zip-архива с метаданными.
    3. Перейти на вкладку Administration и далее в подраздел Site Import & Export раздела Site Development.
    4. Загрузить zip-архив с метаданными плагина с помощью функции загрузки, выбрать строку с названием загруженного архива в реестре и щёлкнуть кнопку Import.
  11. При необходимости настроить возможность инициировать через карточки заказов возвраты по оплатам, а также списания и отмены блокировок в рамках двухстадийных оплат.

    Эта возможность настраивается для отдельных ролей, используемых в интерфейсе Business Manager. Чтобы предоставить доступ к указанным функциям в рамках конкретной роли, следует:

    1. Перейти на вкладку Administration и далее в подраздел Roles & Permissions раздела Organization.
    2. Перейти к параметрам требуемой роли, щёлкнув идентификатор этой роли в соответствующей строке реестра.
    3. Перейти на вкладку Business Manager Modules, установить флажок с названием настраиваемого веб-сервиса (в группе Sites) и щёлкнуть кнопку Apply.
    4. Перейти к секции ecommpay в реестре модулей, доступных для настройки прав доступа, установить флажок в строке ecommpay Order Action и щёлкнуть кнопку Update.

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

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

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

На стороне Salesforce работа с веб-сервисами осуществляется в рамках виртуальных окружений определённых типов (instances; подробнее), которые используются: для разработки веб-сервисов (sandbox), для их настройки и тестирования (staging, development), для запуска и поддержания работы веб-сервисов (production). Чтобы тестировать плагин ecommpay Salesforce Commerce Cloud Cartridge, можно использовать любое из таких окружений, указав в параметрах плагина идентификатор и ключ тестового проекта ecommpay. При этом следует учитывать, что при подключении к работающему веб-сервису плагин становится доступен пользователям как вариант оплаты. Поэтому в таких случаях рекомендуется выполнять тестирование в период низкой нагрузки и предупреждать пользователей о проводимых работах.

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

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

Для подготовки к тестированию следует настроить плагин ecommpay Salesforce Commerce Cloud Cartridge следующим образом:

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

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

    1. Перейти в раздел Site Preferences на вкладке Merchant Tools.
    2. Перейти в подраздел Custom Preferences и щёлкнуть ссылку ecommpay Config в реестре.
  2. Включить возможность использования плагина в веб-сервисе в параметре Is ecommpay Enabled.

    Для этого в параметре Is ecommpay Enabled следует задать значение Yes.

  3. Задать параметры подключения к тестовой среде платёжной платформы.
    • Project ID — идентификатор тестового проекта;
    • Secret Key — ключ тестового проекта для взаимодействия с платформой.
  4. При необходимости задать следующие параметры:
    • ecommpay Card Display Mode — способ открытия платёжной формы Payment Page.

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

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

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

        Рис.: Пример открытия платёжной формы Payment Page на странице перехода к оплате

    • ecommpay Purchase Type — вариант проведения оплат через платёжную платформу.

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

      • Sale – One-step purchase (ecommpay_SALE) — в одну стадию (с незамедлительным списанием средств);
      • Auth – Two-step purchase (ecommpay_AUTH) — в две стадии (с предварительной блокировкой и последующим списанием средств).
      Прим.: Если выбран вариант проведения оплат в две стадии, то на странице перехода к оплате пользователям может быть доступно проведение платежей только с прямым использованием платёжных карт и сервисов Apple Pay и Google Pay. Для методов группы Open Banking проведение двухстадийных оплат не поддерживается.

    Рис.: Параметры работы плагина в интерфейсе Business Manager

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

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

  6. Задать параметры использования платёжных методов (в подразделе Payment Methods раздела Ordering на вкладке Merchant Tools).

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

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

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

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

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

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

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

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

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

Инициировать вторую стадию двухстадийной оплаты вручную, можно:

  • через интерфейс Business Manager с помощью кнопки Capture для списания средств или Cancel payment для отмены блокировки,
  • через интерфейс Dashboard с помощью кнопки Списание для списания средств или Отмена для отмены блокировки (подробнее),
  • через Gate API с помощью запроса capture для списания средств или cancel для отмены блокировки (подробнее).

При этом, чтобы информация о платежах и заказах обновлялась автоматически в интерфейсе Business Manager при инициировании второй стадии через интерфейсы платёжной платформы, необходимо убедиться, что для используемого проекта была настроена отправка оповещений от платёжной платформы на URL веб-сервиса в формате https://<site subdomain>.<site domain>/on/demandware.store/Sites-Mysite-Site/en_GB/Gate-Receive, где Gate-Receive — конечная точка для получения оповещений со стороны ecommpay. Вместе с тем важно, чтобы для одного типа платежа не было настроено насколько правил отправки оповещений с одинаковыми значениями типа события и кода платёжного метода, иначе в протоколах работы плагина отображаются сообщения об ошибках, связанных с обработкой оповещений от платёжной платформы. Информация о работе с правилами отправки оповещений представлена в соответствующей статье документации.

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

Рис.: Вкладка Payment в карточке заказа

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

После проведения тестовых оплат можно тестировать выполнение возвратов через интерфейс Business Manager, и если актуально, через интерфейсы Gate и Dashboard в платформе ecommpay. При этом можно учитывать, что вся информация о тестовых возвратах, представленная в этом подразделе, актуальна и для выполнения возвратов в рабочем режиме.

Чтобы информация о платежах и заказах обновлялась автоматически в интерфейсе Business Manager при выполнении возвратов через интерфейсы платёжной платформы, необходимо убедиться, что для используемого проекта была настроена отправка оповещений от платёжной платформы на URL веб-сервиса в формате https://<site subdomain>.<site domain>/on/demandware.store/Sites-Mysite-Site/en_GB/Gate-Receive, где Gate-Receive — конечная точка для получения оповещений со стороны ecommpay. Вместе с тем важно, чтобы для одного типа платежа не было настроено насколько правил отправки оповещений с одинаковыми значениями типа события и кода платёжного метода, иначе в протоколах работы плагина отображаются сообщения об ошибках, связанных с обработкой оповещений от платёжной платформы. Информация о работе с правилами отправки оповещений представлена в соответствующей статье документации.

Следует учитывать, что для выполнения возвратов платежи на стороне платёжной платформы ecommpay должны быть в статусах success, partially reversed или partially refunded. Контролировать информацию о возвратах можно через интерфейсы платформы и в карточках заказов интерфейса Business Manager.

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

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

    Для этого следует перейти на вкладку Merchant Tools и далее в подраздел Orders раздела Ordering.

  2. Открыть карточку заказа, по которому необходимо выполнить возврат средств.
  3. Инициировать возврат (на вкладке Payment).

    Для этого следует перейти на вкладку Payment, щёлкнуть кнопку Refund в секции Payment Method, указать сумму возврата и щёлкнуть кнопку Submit в открывшемся окне.

  4. Убедиться в выполнении возврата.

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

    При выполнении частичного возврата статус заказа автоматически не изменяется, при этом платежу на стороне платформы присваивается статус partially refunded. При выполнении полного возврата заказу присваивается статус Cancelled, а платежу на стороне платформы — статус refunded.

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

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

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

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

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

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

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

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

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

    1. Перейти в раздел Site Preferences на вкладке Merchant Tools.
    2. Перейти в подраздел Custom Preferences и щёлкнуть ссылку ecommpay Config в реестре.
  2. Включить возможность использования плагина в веб-сервисе в параметре Is ecommpay Enabled.

    Для этого в параметре Is ecommpay Enabled следует задать значение Yes.

  3. Задать параметры подключения к рабочей среде платёжной платформы:
    • Project ID — идентификатор рабочего проекта;
    • Secret Key — ключ рабочего проекта для взаимодействия с платформой.
  4. При необходимости задать следующие параметры:
    • ecommpay Card Display Mode — способ открытия платёжной формы Payment Page.

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

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

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

        Рис.: Пример открытия платёжной формы Payment Page на странице перехода к оплате

    • ecommpay Purchase Type — вариант проведения оплат через платёжную платформу.

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

      • Sale – One-step purchase (ecommpay_SALE) — в одну стадию (с незамедлительным списанием средств);
      • Auth – Two-step purchase (ecommpay_AUTH) — в две стадии (с предварительной блокировкой и последующим списанием средств).
      Прим.: Если выбран вариант проведения оплат в две стадии, то на странице перехода к оплате пользователю может быть доступно проведение платежей только с использованием платёжных карт и сервисов Apple Pay и Google Pay. Для методов группы Open Banking проведение двухстадийных оплат не поддерживается.

    Рис.: Параметры работы плагина в интерфейсе Business Manager

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

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

  6. Задать параметры использования платёжных методов (в подразделе Payment Methods раздела Ordering на вкладке Merchant Tools).

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

После проведения оплат можно выполнять возвраты по ним через интерфейс Business Manager, и если актуально, через интерфейсы Gate и Dashboard в платформе ecommpay. При этом все возможности и процедуры по работе с возвратами в рабочем режиме соответствуют тем, которые доступны в тестовых окружениях.

Чтобы информация о платежах и заказах обновлялась автоматически в интерфейсе Business Manager при выполнении возвратов через интерфейсы платёжной платформы, необходимо убедиться, что для используемого проекта была настроена отправка оповещений от платёжной платформы на URL веб-сервиса в формате https://<site subdomain>.<site domain>/on/demandware.store/Sites-Mysite-Site/en_GB/Gate-Receive, где Gate-Receive — конечная точка для получения оповещений со стороны ecommpay. Вместе с тем важно, чтобы для одного типа платежа не было настроено насколько правил отправки оповещений с одинаковыми значениями типа события и кода платёжного метода, иначе в протоколах работы плагина отображаются сообщения об ошибках, связанных с обработкой оповещений от платёжной платформы. Информация о работе с правилами отправки оповещений представлена в соответствующей статье документации.

Следует учитывать, что для выполнения возвратов платежи на стороне платёжной платформы ecommpay должны быть в статусах success, partially reversed или partially refunded. Контролировать информацию о возвратах можно через интерфейсы платформы и в карточках заказов интерфейса Business Manager.

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

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

    Для этого следует перейти на вкладку Merchant Tools и далее в подраздел Orders раздела Ordering.

  2. Открыть карточку заказа, по которому необходимо выполнить возврат средств.
  3. Инициировать возврат (на вкладке Payment).

    Для этого следует перейти на вкладку Payment, щёлкнуть кнопку Refund в секции Payment Method, указать сумму возврата и щёлкнуть кнопку Submit в открывшемся окне.

  4. Убедиться в выполнении возврата.

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

    При выполнении частичного возврата статус заказа автоматически не изменяется, при этом платежу на стороне платформы присваивается статус partially refunded. При выполнении полного возврата заказу присваивается статус Cancelled, а платежу на стороне платформы — статус refunded.

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

Контролировать информацию о платежах, проводимых с помощью плагина ecommpay Salesforce Commerce Cloud Cartridge, а также о соответствующих заказах можно через интерфейс Business Manager, используя инструменты подраздела Orders в разделе Ordering.

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

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

Рис.: Реестр заказов в интерфейсе Business Manager

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

  • General — с информацией о заказе;
  • Payment — с информацией о платеже и расчётном адресе пользователя;
  • Notes — с записями об изменениях в рамках заказа, в том числе об изменениях статуса платежа на стороне платформы ecommpay и с возможностью добавлять и удалять записи;
  • History — с более детальной информацией об изменениях только в рамках заказа (но не платежа), без возможности добавлять и удалять записи.

Вкладка Attributes в рамках работы с плагином ecommpay Salesforce Commerce Cloud Cartridge не используется.

Рис.: Карточка заказа в интерфейсе Business Manager

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

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

При работе с плагином ecommpay Salesforce Commerce Cloud Cartridge в интерфейсе Business Manager можно настраивать проведение платежей с прямым использованием карт, сервисов Apple Pay и Google Pay, а также методов группы Open Banking. Это можно делать через реестр платёжных методов в подразделе Payment Methods раздела Ordering на вкладке Merchant Tools.

Реестр платёжных методов содержит записи с идентификаторами методов, их названиями и порядковыми номерами отображения на странице перехода к оплате, (в столбцах ID, Name и Sort Order соответственно), а также с возможностями подключать методы для работы через плагин, отключать их (задавая значение Yes или No соответственно в столбце Enabled) или удалять методы из реестра (с помощью кнопки в соответствующем столбце).

Рис.: Реестр платёжных методов в интерфейсе Business Manager

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

  • Description — текст, отображаемый пользователям при выборе платёжного метода.
  • Image — логотип платёжного метода.

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

  • Payment Processor — идентификатор организации, через которую осуществляется проведение платежей с использованием выбранного метода.
    Для проведения платежей через платформу ecommpay в этом параметре необходимо задавать одно из следующих значений:значение ecommpay_CREDIT <ecommpay_CREDIT> или ecommpay_APM <ecommpay_APM>.
    • ecommpay_CREDIT <ecommpay_CREDIT> — для карточных платежей;
    • ecommpay_APM <ecommpay_APM> — для платежей с использованием альтернативных методов.
  • Countries — страны, в которых доступно проведение платежей с использованием выбранного метода.
  • Currencies — валюты, в которых доступно проведение платежей с использованием выбранного метода.
  • Customer Groups — группы пользователей, которые могут выбрать настраиваемый метод для оплаты.

    Можно задавать следующие значения:

    • Big Spenders — пользователи, чья сумма покупок в предыдущем месяце составила не менее двухсот долларов США;
    • Everyone — все пользователи веб-сервиса;
    • Registered — пользователи, зарегистрированные в веб-сервисе;
    • Unregistered — пользователи, не зарегистрированные в веб-сервисе.
  • Min/Max Payment Ranges — нижняя и верхняя границы суммы платежа, при которой настраиваемый метод становится доступен для оплаты.
Внимание: Чтобы избегать отклонения платежей на стороне платформы ecommpay, значения для параметров Countries, Currencies и Min/Max Payment Ranges следует задавать в соответствии с договорными условиями ecommpay и ограничениями в рамках проекта мерачнта (если такие ограничения были установлены).

Рис.: Параметры для карточных платежей в интерфейсе Business Manager