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/ru/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 // для Yarn
    yarn add ecommpay    // для npm
    Эта команда служит для загрузки и размещения библиотек и их зависимостей в каталоге с модулями для подключения необходимых модулей в коде веб-сервиса.
  3. Подключить модули в исходном коде веб-сервиса:
    const { Payment } = require('ecommpay');
    const { Callback } = require('ecommpay');
    

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

Запрос для вызова 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 = 'RUB';
            // Код валюты в формате ISO-4217 alpha-3
    e.paymentDescription = 'Описание платежа';
           // Описание платежа. Необязательный параметр

    Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты. Дополнительно можно использовать любые другие параметры из числа доступных для работы с 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 = 'RUB';
        // Код валюты в формате ISO-4217 alpha-3
e.paymentDescription = 'Описание платежа';
       // Описание платежа. Необязательный параметр
e.language_code: 'EN';
       // Код языка, на котором Payment Page открывается пользователю
e.redirect = true;
       // Параметр, который отвечает за открытие сгенерированной платежной страницы в отдельной вкладке браузера
const url = e.getUrl();
        // Готовый запрос с подписью

Использование режима отладки

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

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

const payment = new Payment(<project_id>, '<secret_key>');
payment.paymentId = "<payment_id_in_your_service>";
payment.paymentAmount = 1001;
payment.paymentCurrency = 'EUR';
payment.paymentDescription = 'Тестовый платёж';
payment.testMode = true; // Включение режима отладки
 
try:

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

One or more parameters is not valid:
 
Customer_id:
    Must be not null  // Не указан идентификатор пользователя, обязательный для запроса
Account_token:
    Invalid account token  // Указан некорректный токен

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

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

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

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