SDK for JavaScript

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

Возможности

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

Состав

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

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

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

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

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

При возникновении вопросов о работе с SDK for JavaScript следует обращаться в службу технической поддержки Benker по адресу help@benker.io.

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

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

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

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

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

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

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

    Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты.

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

  2. Сформировать адрес для вызова платёжной формы.
    const url = e.getUrl();
    Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа:
    https://paymentpage.benker.io/payment?signature=OEKRlLKStyoH%2BM36hokU
zLZsuB2gO8JALVnyev9elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555943554067...
  3. Использовать сформированный адрес для вызова платёжной формы (подробнее).

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

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

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

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

  1. Создать объект класса Callback, используя значение секретного ключа, полученного от Benker, и данные из оповещения от Benker: 
    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 for JavaScript проверка подписи в оповещении выполняется автоматически.

Рис. 2. Пример данных из оповещения о проведении оплаты 
POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: webservice.com

{
  "project_id": 200,
  "payment": {
    "id": "abc12345",
    "type": "purchase",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "method": "Greek Banks",
    "sum": {
      "amount": 1000,
      "currency": "EUR"
    },
    "description": "Success"
  },
  "customer": {
    "id": "123"
  },
  "operation": {
    "id": 9529253065607,
    "type": "sale",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "created_date": "2025-03-20T14:22:00+0000",
    "request_id": "f1de353331a01fd14163fe4226-00009530",
    "sum_initial": {
      "amount": 1000,
      "currency": "EUR"
    },
    "sum_converted": {
      "amount": 1000,
      "currency": "EUR"
    },
    "code": "0",
    "message": "Success",
    "provider": {
      "id": 1914,
      "payment_id": "",
      "auth_code": ""
    }
  },
  "signature": "OBjT3RaJnOWsDXOclvWoC6+CFSCtLprTo8VFbN6BYVQD2tVK/3d9k+RRA/7N9TV6OQqk+0uPUnx4/c8uaUurw=="
}

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

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