Использование плагина 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 и обеспечивать все необходимые действия для проведения платежей.

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

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

Рис.: Административный интерфейс Business Manager

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

Возможности

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

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

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

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

  Это можно делать непосредственно через реестр платёжных методов в интерфейсе Business Manager.

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

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

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

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

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

  Для этого можно использовать интерфейс Business Manager и, если необходимо, — интерфейсы Gate и Dashboard платёжной платформы ecommpay.

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

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

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

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

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

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

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

Схемы работы

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

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

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

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

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

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

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

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

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

Контролировать информацию о заказах и платежах по ним можно через интерфейс 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. Пользователь получает информацию о результате оплаты.

Рис.: 1 — Указание данных для оформления заказа

Рис.: 2 — Выбор метода и указание реквизитов карты

Рис.: 3 — Подтверждение формирования заказа

Рис.: 4 — Отображение информации о результате оплаты

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

Тестировать работу плагина и проводить тестовые платежи по различным платёжным сценариям без реального списания средств можно через тестовую среду платёжной платформы 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), представленных в статье Тестовые карты.

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

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

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

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

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

После проведения тестовых оплат можно тестировать выполнение возвратов через интерфейс Business Manager, и если актуально, через интерфейсы Dashboard и Gate в платформе ecommpay. При этом следует учитывать, что для выполнения возвратов платежи на стороне платёжной платформы ecommpay должны быть в статусах success или 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), предназначенных для разработки и тестирования.

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

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

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).

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

По оплатам, проведённым с помощью плагина ecommpay Salesforce Commerce Cloud Cartridge, можно выполнять частичные и полные возвраты через интерфейс Business Manager, и если актуально, через интерфейсы Dashboard (с использованием инструментов единичной и пакетной отправки запросов; подробнее) и Gate (подробнее) от ecommpay. При этом платежи на стороне платформы ecommpay должны быть в статусах success или 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.