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

Возможности

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

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

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

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

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

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

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

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

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

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

  Это можно делать через HTTP API и пользовательcкий интерфейс Merchant Center от commercetools и, если необходимо, — через Data API и пользовательский интерфейс Dashboard от ecommpay. При этом для того, чтобы в платформе commercetools была доступна актуальная информация о заказах и платежах при выполнении возвратов через интерфейсы платёжной платформы, необходимо настроить отправку оповещений со стороны ecommpay на URL модуля уведомления.

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

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

• Применять различные возможности, обеспечиваемые со стороны ecommpay.

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

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

Схема работы

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

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

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

Наряду с этим, заказам, платежам и транзакциям на стороне платформы commercetools автоматически присваиваются идентификаторы, состоящие из тридцати двух случайных символов, а оплатам в платформе ecommpay — идентификаторы, соответствующие идентификаторам платежей в платформе commercetools (например, eeb30cda-a8a1-4895-ab43-5ef8bb29ee80), и статусы в соответствии с моделью проведения платежей ecommpay (подробнее). С вопросами о соответствии статусов заказов и платежей можно обращаться к курирующему менеджеру ecommpay.

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

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

Наряду с этим следует учитывать, что при работе с плагином от ecommpay для платформы commercetools вызов Payment Page обеспечивается на стороне веб-сервиса с учётом параметров, включённых в URL для открытия Payment Page. Если необходимо использовать дополнительные параметры вызова платёжной формы, их следует передать в запросе, отправляемом в платформу commercetools для инициирования платежа, — в параметре initial_request в объекте fields внутри объекта custom. Информация об организации работы с платёжной формой Payment Page представлена в соответствующей статье этого портала.

{
  "amountPlanned": {
    "currencyCode": "EUR",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "ecommpay-integration",
    "method": "ecommpay-integration"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "key": "ecommpay-integration"
    },
    "fields": {
      "initial_request": "\"{\\\"customer_id\\\":123,\\\"billing_country\\\":\\\"DE\\\",\\\"customer_country\\\":\\\"DE\\\"}\""
    }
  }
}

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

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

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

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

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

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

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

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

Чтобы выполнить возврат, следует направить в платформу commercetools запрос на обновление информации о платеже (подробнее). При этом в запросе следует передать массив actions со следующими данными:

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

  Для инициирования возврата следует указать значение addTransaction.

• Объект transaction со следующими данными:
  • Параметр type с типом транзакции Refund в платформе commercetools.

    Для инициирования возврата следует указать значение Refund.

  • Объект amount с параметрами currencyCode и centAmount, в которых следует указать валюту и сумму возврата соответственно.

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

"actions": [
    {
      "action": "addTransaction",
      "transaction": {
        "type": "Refund",
        "amount": {
          "centAmount": 8300,
          "currencyCode": "EUR"
        }
      }
    }
  ]

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

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

Наряду с этим, следует учитывать, что при работе с плагином от ecommpay для платформы commercetools вызов Payment Page обеспечивается на стороне веб-сервиса с учётом параметров, включённых в URL для открытия Payment Page. Если необходимо использовать дополнительные параметры вызова платёжной формы, их следует передать в запросе, отправляемом в платформу commercetools для инициирования платежа, — в параметре initial_request в объекте fields внутри объекта custom. Информация об организации работы с платёжной формой Payment Page представлена в соответствующей статье этого портала.

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

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

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

Чтобы выполнить возврат, следует направить в платформу commercetools запрос на обновление информации о платеже (подробнее). При этом в запросе следует передать массив actions со следующими данными:

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

  Для инициирования возврата следует указать значение addTransaction.

• Объект transaction со следующими данными:
  • Параметр type с типом транзакции Refund в платформе commercetools.

    Для инициирования возврата следует указать значение Refund.

  • Объект amount с параметрами currencyCode и centAmount, в которых следует указать валюту и сумму возврата соответственно.

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

"actions": [
    {
      "action": "addTransaction",
      "transaction": {
        "type": "Refund",
        "amount": {
          "centAmount": 8300,
          "currencyCode": "EUR"
        }
      }
    }
  ]

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

Контролировать информацию о платежах, проводимых с помощью плагина от ecommpay, а также о соответствующих заказах можно через интерфейс Merchant Center и HTTP API от commercetools. Также при необходимости можно использовать интерфейсы Dashboard и Data API от ecommpay, но следует учитывать, что в этом случае можно получать информацию только о платежах, инициируемых в платёжной платформе.

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

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

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

• General — с информацией о заказе и расчётном адресе пользователя;
• Custom Fields — с набором дополнительных полей, используемых в рамках заказа;
• Shipping & Delivery — с информацией о способе доставки товаров;
• Returns — с информацией о возврате товаров;
• Payments — с информацией о платежах и транзакциях в рамках заказа.

Для получения информации о платеже, проведённом через плагин от ecommpay, следует перейти на вкладку Payments. На этой вкладке отображается код платёжного метода (в параметре Payment method name), название способа оплаты (в параметре Payment method), сумма и валюта платежа (в параметре Amount planned), статус, присвоенный платежу в платформе ecommpay, (в параметре PSP Status Code) и другие сведения.

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

В таблице Payment transactions отображается информация о транзакциях в платформе commercetools. Эта таблица состоит из следующих столбцов:

• Date — дата создания транзакции;
• Transaction type — тип транзакции (Charge для операции типа sale и Refund для операции типа refund или reversal);
• Status — статус транзакции;
• Amount — сумма и валюта транзакции;
• Interaction ID — идентификатор операции, относящейся к конкретной транзакции, присвоенный на стороне ecommpay;
• Transaction ID — идентификатор транзакции.

Статус каждой транзакции в платформе commercetools зависит от состояния соответствующей операции в платформе ecommpay и может быть одним из следующих: Initial, Pending, Successful или Failure. Так, транзакциям присваиваются следующие статусы:

• Initial, если оповещение с информацией о соответствующей операции ещё не поступило в платформу commercetools;

• Pending, если операция находится в промежуточном статусе;

• Successful, если операция выполнена;
• Failure, если операция отклонена.

Рис.: Таблица с данными о транзакциях в карточке заказа интерфейса Merchant Center

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

Рис.: Страница с данными об операциях из оповещений от платёжной платформы

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

{
      "id": "7c081cc3-353d-4a80-8879-36e2f7dc5ac4",
      "version": 15,
      "versionModifiedAt": "2023-12-19T11:47:37.374Z",
      "lastMessageSequenceNumber": 10,
      "createdAt": "2023-12-19T11:27:56.278Z",
      "lastModifiedAt": "2023-12-19T11:47:37.374Z",
      "lastModifiedBy": {
        "clientId": "4cD5VUC9rScyTo69eOueu6Jh",
        "isPlatformClient": false
      },
      "createdBy": {
        "clientId": "4cD5VUC9rScyTo69eOueu6Jh",
        "isPlatformClient": false,
        "anonymousId": "f661235a-abf9-4ec6-915a-e7c4b3154902"
      },
      "amountPlanned": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 12300,
        "fractionDigits": 2
      },
      "paymentMethodInfo": {
        "paymentInterface": "ecommpay-integration",
        "method": "ecommpay-integration",
        "name": {
          "en": "card"
        }
      },
      "custom": {
        "type": {
          "typeId": "type",
          "id": "62408c35-a8b1-4bd0-9c15-99aa86cf8efc"
        },
        "fields": {
          "initial_request": "{\"redirect_success_url\":\"https://example.com/complete-redirect?id=success\"...}",
          "pp_url": "https://paymentpage.ecommpay.com/payment?project_id=109751&interface_type=33..."
        }
      },
      "paymentStatus": {
        "interfaceCode": "success"
      },
      "transactions": [
        {
          "id": "a503a5e0-9677-46d8-bab2-2dbbb10595ce",
          "timestamp": "2023-12-19T11:27:56.272Z",
          "type": "Charge",
          "amount": {
            "type": "centPrecision",
            "currencyCode": "EUR",
            "centAmount": 12300,
            "fractionDigits": 2
          },
          "interactionId": "47382010085133",
          "state": "Success"
        },
        {
          "id": "424ca2fd-0d31-475c-98f1-0f945a30a9ef",
          "type": "Refund",
          "amount": {
            "type": "centPrecision",
            "currencyCode": "EUR",
            "centAmount": 8300,
            "fractionDigits": 2
          },
          "interactionId": "0",
          "state": "Initial"
        }
      ],
      "interfaceInteractions": [
        {
          "type": {
            "typeId": "type",
            "id": "8978cfd5-fb49-4082-a4cf-2e49237e1c86"
          },
          "fields": {
            "operation_type": "sale",
            "sum_initial": "{\"amount\":12300,\"currency\":\"EUR\"}",
            "date": "2023-12-19T11:47:18+0000",
            "operation_id": 47382010085133,
            "operation_status": "awaiting 3ds result",
            "message": "Awaiting processing",
            "sum_converted": "{\"amount\":10592,\"currency\":\"GBP\"}"
          }
        },
        {
          "type": {
            "typeId": "type",
            "id": "8978cfd5-fb49-4082-a4cf-2e49237e1c86"
          },
          "fields": {
            "operation_type": "sale",
            "sum_initial": "{\"amount\":12300,\"currency\":\"EUR\"}",
            "date": "2023-12-19T11:47:25+0000",
            "operation_id": 47382010085133,
            "operation_status": "awaiting 3ds result",
            "message": "Awaiting processing",
            "sum_converted": "{\"amount\":10592,\"currency\":\"GBP\"}"
          }
        },
        {
          "type": {
            "typeId": "type",
            "id": "8978cfd5-fb49-4082-a4cf-2e49237e1c86"
          },
          "fields": {
            "operation_type": "sale",
            "sum_initial": "{\"amount\":12300,\"currency\":\"EUR\"}",
            "date": "2023-12-19T11:47:35+0000",
            "operation_id": 47382010085133,
            "operation_status": "success",
            "message": "Success",
            "sum_converted": "{\"amount\":10592,\"currency\":\"GBP\"}"
          }
        }
      ],
      "anonymousId": "f661235a-abf9-4ec6-915a-e7c4b3154902"
    }
  }
}

Более подробная информация о работе с платежами и заказами с использованием инструментов платформы commercetools представлена в документации commercetools.