SDK для JavaScript

SDK для JavaScript — это набор средств разработки для взаимодействия веб-сервисов, разработанных на JavaScript, с платёжной платформой ecommpay при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK для JavaScript с примерами кода на языке программирования JavaScript.

SDK для JavaScript совместим с Java​Script на платформе Node.js 4.x и доступен для загрузки на GitHub по следующей ссылке: https://github.com/ITECOMMPAY/paymentpage-sdk-js.

Возможности

SDK для JavaScript позволяет:
  • подписывать набор параметров платежа и формировать запрос для вызова Payment Page,
  • проверять подлинность оповещений от ecommpay и получать из них информацию о платежах.

Состав

SDK для JavaScript содержит библиотеки и служебные файлы. Для работы могут использоваться:

  • src — библиотека для разработки,
  • _tests_ — библиотека для автоматизированного тестирования.

Порядок работы

Для использования SDK для JavaScript необходимо:

  1. Решить организационные вопросы, касающиеся взаимодействия с ecommpay:
    • Если у компании нет идентификатора проекта и ключа для взаимодействия с ecommpay — отправить заявку на подключение по ссылке https://ecommpay.com/apply-now/.
    • Если у компании есть идентификатор и ключ для взаимодействия с ecommpay есть — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для JavaScript и согласовать с ними порядок тестирования.
  2. Установить библиотеки, входящие в состав SDK для JavaScript, в каталог с исходным кодом веб-сервиса и подключить их в коде, а также доработать код для использования необходимой функциональности.
  3. Протестировать и запустить в работу обновлённый исходный код веб-сервиса.
    • Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа и пример оповещения из библиотеки _tests_.
    • Для перевода в рабочий режим необходимо заменить тестовое значение project_id на рабочее, полученное от ecommpay.

При возникновении вопросов о работе с SDK для JavaScript следует обращаться в службу технической поддержки ecommpay по адресу support@ecommpay.com.

Установка и подключение библиотек

Устанавливать библиотеки, входящие в состав SDK для JavaScript, в проект с исходным кодом веб-сервиса можно вручную или автоматически с помощью систем управления пакетами Yarn или npm, которые обеспечивают загрузку необходимых библиотек из репозитория.

Чтобы установить библиотеки с помощью Yarn или npm и подключить их в исходном коде веб-сервиса, необходимо:

  1. Если система управления пакетами не установлена — загрузить, установить и настроить. Подробнее:
  2. В командной строке операционной системы перейти в каталог с исходным кодом веб-сервиса и выполнить одну из команд:
    npm install ecommpay // для npm
yarn add ecommpay    // для Yarn
    Эта команда служит для загрузки и размещения библиотек и их зависимостей в каталоге с модулями для подключения необходимых модулей в коде веб-сервиса.
  3. Подключить модули в исходном коде веб-сервиса:
    const { Payment } = require('ecommpay');
const { Callback } = require('ecommpay');

Вызов платёжной формы

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

Вместе с тем, рекомендуется передавать эти и ряд других параметров (с информацией о платёжном адресе пользователя) для проведения оплат с использованием карт всех платёжных систем, поскольку по данным платёжной системы Visa полноценное использование таких параметров может существенно (вплоть до 6 %) повышать проходимость платежей и кардинально (вплоть до 65 %) снижать число операций, признаваемых мошенническими после их выполнения.

Запрос для вызова ecommpay формируется из набора параметров, подписываемых для обеспечения защиты данных при передаче запроса в платёжную платформу ecommpay. SDK для JavaScript позволяет автоматически подписывать параметры и формировать из них запрос. Для вызова Payment Page с использованием SDK для JavaScript следует:

  1. Создать объект класса Payment и указать значения параметров платежа и значение секретного ключа, полученное от ecommpay. Секретный ключ необходим для автоматического подписывания параметров.
    const e = new Payment('186', '<secret_key>');
        // Идентификатор проекта и секретный ключ
e.paymentId = '1555943554067';
        // Идентификатор платежа, уникальный в рамках проекта
e.paymentAmount = 1000;
        // Сумма в дробных единицах валюты
e.paymentCurrency = 'EUR';
        // Код валюты в формате ISO-4217 alpha-3
e.paymentDescription = 'Описание платежа';
       // Описание платежа. Необязательный параметр

    Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты. Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом.

    e.paymentCustomerPhone = 'The customer phone number. Must have from 4 to 24 digits';
e.paymentCustomerEmail = 'The customer email';

    Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 (подробнее), индекс, названия города и улицы. Эти сведения указываются следующим образом.

    e.paymentBillingPostal = 'The postal code of the customer billing address';
e.paymentBillingCountry = 'The country of the customer billing address, in ISO 3166-1 alpha-2';
e.paymentBillingCity = 'The city of the customer billing address';
e.paymentBillingAddress = 'The street of the customer billing address';

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

  2. Сформировать запрос для вызова платёжной формы.
    const url = e.getUrl();
    Корректный запрос для вызова платёжной формы содержит подпись и параметры платежа:
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLKStyoH%2BM36hokU
zLZsuB2gO8JALVnyev9elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555943554067...
  3. Использовать сформированный запрос для вызова платёжной формы, например следующим образом:
    <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" />
<script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
<script type="text/javascript">
    EPayWidget.run({ baseUrl: '<URL, полученный на предыдущем шаге>'}, 'get');
</script>

    Другие варианты вызова платёжной формы описаны в разделе Способы открытия платёжной формы.

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

Рис.: Пример формирования запроса на открытие Payment Page

const e = new Payment('186', '<secret_key>');
        // Идентификатор проекта и секретный ключ
e.paymentId = '1555943554067';
        // Идентификатор платежа, уникальный в рамках проекта
e.paymentAmount = 1000;
        // Сумма в дробных единицах валюты
e.paymentCurrency = 'EUR';
        // Код валюты в формате ISO-4217 alpha-3
e.paymentDescription = 'Описание платежа';
       // Описание платежа. Необязательный параметр
e.language_code: 'EN';
       // Код языка, на котором Payment Page открывается пользователю
e.redirect = true;
       // Параметр, который отвечает за открытие сгенерированной платежной страницы в отдельной вкладке браузера
const url = e.getUrl();
        // Готовый запрос с подписью

Обработка оповещений

Информацию о результатах проведения платежей можно получать в оповещениях, отправляемых со стороны ecommpay на URL, который необходимо сообщить службе технической поддержки ecommpay. Оповещение представляет собой HTTP POST запрос с данными в формате JSON-строки. Чтобы извлечь информацию о результате проведения платежа из JSON-строки, необходимо:

  1. Создать объект класса Callback, используя значение секретного ключа, полученного от ecommpay, и данные из оповещения от ecommpay: 
    const callback = new Callback(<secret_key>, req.body);
  2. Использовать методы и свойства, доступные для работы с оповещениями. В следующем примере используются метод и свойство в исходном коде веб-сервиса, разработанном с использованием Express:
    app.post('/payment/callback', function(req, res) {
  const callback = new Callback(<secret_key>, req.body);
  if (callback.isPaymentSuccess()) {
    const paymentCont = callback.payment();    // Получение всей информации о платеже
    const paymentId = callback.getPaymentId(); // Получение идентификатора платежа

    // Здесь размещается исходный код для обработки оповещения проведённого платежа
  }
});

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

Рис.: Пример данных из оповещения о проведении оплаты 

{
      "project_id": 186,       // Идентификатор проекта
      "payment": {             // Информация о платеже
          "id": "1555943554067",        // Идентификатор платежа
          "type": "purchase",  // Тип платежа
          "status": "success", // Статус платежа
          "date": "2021-08-28T09:11:28+0000",  // Дата и время проведения платежа
          "method": "card",  // Платёжный метод
          "sum": {           // Сумма и валюта платежа
            "amount": 1000,
            "currency": "EUR"
          },
          "description": "Тестовый платёж"  // Описание платежа
      },
      "account": {           // Информация о платёжном средстве
          "number": "431422******0056",
          "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
          "type": "visa",
          "card_holder": "ADA LOVELACE",
          "id": 778804,
          "expiry_month": "11",
          "expiry_year": "2024"
      },
      "operation": {     // Информация о последней операции в рамках платежа
        "id": 17839000001150,  // Идентификатор операции
        "type": "sale",        // Тип операции
        "status": "success",   // Статус операции
        "date": "2021-08-28T09:11:28+0000", // Дата и время проведения операции
        "created_date": "2021-08-28T09:10:50+0000",
        "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Идентификатор запроса
        "sum_initial": {    // Сумма и валюта операции, указанные в запросе
          "amount": 1000,
          "currency": "EUR"
        },
        "sum_converted": {
          // Сумма и валюта операции с учётом настроенных для проекта правил конвертации
            "amount": 1000,
            "currency": "EUR"
        },
        "provider": {     // Информация о проведении платежа в платёжной системе
          "id": 6,
          "payment_id": "15354474886323",
          "date": "2021-02-07T08:34:24+0000",
          "auth_code": "563253",
          "endpoint_id": 6
        },
        "code": "0",          // Унифицированный код ответа
        "message": "Success", // Расшифровка кода ответа
        "eci": "05"           // Код индикатора ECI, отображающий результат 3D-Secure проверки  
      },
      "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."   // Подпись оповещения
  }

Дополнительные материалы

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