SDK для JavaScript
SDK для JavaScript — это набор средств разработки для взаимодействия веб-сервисов, разработанных на JavaScript, с платёжной платформой ecommpay при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK для JavaScript с примерами кода на языке программирования JavaScript.
SDK для JavaScript совместим с JavaScript на платформе Node.js 4.x и доступен для загрузки на GitHub по следующей ссылке: https://github.com/ITECOMMPAY/paymentpage-sdk-js.
Возможности
- подписывать набор параметров платежа и формировать адрес для вызова Payment Page,
- проверять подлинность оповещений от ecommpay и получать из них информацию о платежах.
Состав
SDK для JavaScript содержит библиотеки и служебные файлы. Для работы могут использоваться:
- src — библиотека для разработки,
- _tests_ — библиотека для автоматизированного тестирования.
Порядок работы
Для использования SDK для JavaScript необходимо:
- Решить организационные вопросы, касающиеся взаимодействия с ecommpay:
- Если у компании нет идентификатора проекта и ключа для взаимодействия с ecommpay — отправить заявку на подключение по ссылке https://ecommpay.com/apply-now/.
- Если у компании есть идентификатор и ключ для взаимодействия с ecommpay есть — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для JavaScript и согласовать с ними порядок тестирования.
- Установить библиотеки, входящие в состав SDK для JavaScript, в каталог с исходным кодом веб-сервиса и подключить их в коде, а также доработать код для использования необходимой функциональности.
- Протестировать и запустить в работу обновлённый исходный код веб-сервиса.
- Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа и пример оповещения из библиотеки _tests_.
- Для перевода в рабочий режим необходимо заменить тестовое значение project_id на рабочее, полученное от ecommpay.
При возникновении вопросов о работе с SDK для JavaScript следует обращаться в службу технической поддержки ecommpay по адресу support@ecommpay.com.
Установка и подключение библиотек
Устанавливать библиотеки, входящие в состав SDK для JavaScript, в проект с исходным кодом веб-сервиса можно вручную или автоматически с помощью систем управления пакетами Yarn или npm, которые обеспечивают загрузку необходимых библиотек из репозитория.
Чтобы установить библиотеки с помощью Yarn или npm и подключить их в исходном коде веб-сервиса, необходимо:
- Если система управления пакетами не установлена — загрузить, установить и настроить. Подробнее:
- В командной строке операционной системы перейти в каталог с исходным кодом веб-сервиса и выполнить одну из команд:
npm install ecommpay // для npm yarn add ecommpay // для Yarn
Эта команда служит для загрузки и размещения библиотек и их зависимостей в каталоге с модулями для подключения необходимых модулей в коде веб-сервиса. - Подключить модули в исходном коде веб-сервиса:
const { Payment } = require('ecommpay'); const { Callback } = require('ecommpay');
Вызов платёжной формы
Запрос для вызова Payment Page включает в себя набор параметров, подписываемых для обеспечения защиты данных при передаче запроса в платёжную платформу ecommpay. SDK для JavaScript позволяет автоматически подписывать используемые параметры. Для вызова Payment Page с применением SDK для JavaScript следует:
- Создать объект класса
Paymentи указать значения параметров платежа и значение секретного ключа, полученное от ecommpay. Секретный ключ необходим для автоматического подписывания параметров.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 = 'Описание платежа'; // Описание платежа. Необязательный параметр
Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты. Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 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. Подробнее о доступных параметрах — в разделе Параметры вызова платёжной формы.
- Сформировать адрес для вызова платёжной формы.
const url = e.getUrl();
Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа:https://paymentpage.ecommpay.com/payment?signature=OEKRlLKStyoH%2BM36hokU zLZsuB2gO8JALVnyev9elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555943554067...
- Использовать сформированный адрес для вызова платёжной формы (подробнее).
Далее приведён пример формирования адреса для вызова платёжной формы 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(); // Готовый запрос с подписью
Обработка оповещений
Информацию о результатах проведения платежей можно получать в оповещениях, отправляемых со стороны ecommpay на URL, который необходимо сообщить службе технической поддержки ecommpay. Оповещение представляет собой HTTP POST запрос с данными в формате JSON-строки. Чтобы извлечь информацию о результате проведения платежа из JSON-строки, необходимо:
- Создать объект класса
Callback, используя значение секретного ключа, полученного от ecommpay, и данные из оповещения от ecommpay:const callback = new Callback(<secret_key>, req.body);
- Использовать методы и свойства, доступные для работы с оповещениями. В следующем примере используются метод и свойство в исходном коде веб-сервиса, разработанном с использованием 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..." // Подпись оповещения
}