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

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

Обеспечение синхронизации данных между платформами

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

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

• Для используемого проекта настроена отправка оповещений от платёжной платформы к модулю уведомлений плагина, на URL, указанный при установке плагина в качестве переменной среды для модуля расширения.

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

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

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

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

  Это может быть актуальным, в частности, при работе с платформами Docker и Node.js.

Процедуры

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

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

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

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

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

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

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

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

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

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

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

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

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

Введение

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

Обеспечение синхронизации данных между платформами

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

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

• Для используемого проекта настроена отправка оповещений от платёжной платформы к модулю уведомлений плагина, на URL, указанный при установке плагина в качестве переменной среды для модуля расширения.

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

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

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

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

  Это может быть актуальным, в частности, при работе с платформами Docker и Node.js.

Процедуры

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В таблице 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, если операция отклонена.

Для получения информации об операциях, инициированных в платформе 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.