npm:@nplus.tech/ktwidget-client

README

KTWidget Документация

Общее описание

Данный виджет помогает принимать и обрабатывать платежи для вашего онлайн-бизнеса. Установите его на сайт, и новый способ оплаты сразу станет доступен вашим покупателям.

Наши преимущества

Простая интеграция на сайт;
Реактивная служба поддержки;
Быстрый взаиморасчёт;
Мобильная версия.

Режимы работы виджета

Виджет может работать в двух режимах:

Оплата за товар/услугу merchant'a (type = 'ecom');
- Режим необходим, когда нужно получить оплату с клиентов за товары/услуги на сайте merchant'a.
Оплата в пользу сервиса ktpay (type = 'service').
- Режим необходим, когда нужно получить оплату с клиентов за услуги в сервисе ktpay на сайте merchant'a. Это могут быть сервисы пополнения мобильных операторов, коммунальных платежей, оплаты общественного траспорта и т.д. Список доступных сервисов необходимо уточнять у нашего менеджера.

Жизненый цикл транзакции

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

Клиент на странице оплаты, нажимает кнопку "Оплатить".
Открывается модальное окно, в котором показывается анимация загрузки, а в фоновом режиме выполняется следующее:
- Отправка параметров транзакции;
- Создание транзакции виджета;
- Получение параметров эквайринга;
- Открытие iFrame окна, в котором происходит перенаправление на страницу банка-эквайера.
Клиент видет в модальное окне форму для заполнения данных банковской карты, заполняет их и нажимает "Оплатить".
Происходит валидация данных банковской карты и процесс обработки транзакции.
- В случае ошибочных данных банковской карты, клиенту будет предложенно ввести данные еще раз. Это функционал банка-эквайера, на него мы повлиять никак не можем.
Процесс обработки транзакций может закончится двумя сценариями:
- Успех: деньги с указанной карты будут заблокированы до дальнейшего проведения клиринга (окончательное снятие с карты);
- Ошибка: по причине отказа банка-эквайера.
Пользователь будет перенаправлен на страницу чека платежа.
В зависимости от сценария процесса обработки транзакции далее будет:
- В случае успеха: при нажатии на кнопку "Продолжить", будет сделано перенаправление на страницу успеха merchant'a (если она была указана) или отображена стандартная страница виджета с чеком оплаты.
- В случае ошибки: при нажатии на кнопку "Продолжить", сделано перенаправление на страницу ошибки merchant'a (если она была указана) или отображена стандартная страница ошибки виджета.
Для успешного сценария предусмотрены дальнейшие действия:
- Если тип транзакции был type = 'service', (подробнее в разделе Режимы работы виджета) тогда идет выполнения начисления в пользу сервиса ktpay. В это время деньги на ранее указанной банковской карте остаются в блокировке. Сам процесс начисления может занимать от несколько секунд до минут, после этого следует следующий шаг.
- Окончательный этапом для каждой транзакции является клиринг, процесс окончательного снятия заблокированных денег с карты.
Предусмотрен дополнительный шаг в виде уведомления merchant'a о статусе проведенной транзакции. Данный шаг опционален и будет испольнен только в тех случаях, когда merchant указал необходимый callback_post_url либо в общий настройках при создании merchant'a либо при создании транзакции. Подробнее в разделе Уведомление merchant'a о статусе транзакции.

Подготовка

Вам необходимо создать Merchant'a - это клиент использующий виджет. В текущий момент, личный кабинет merchant'a в разработке, поэтому создание и изменения настроек, осуществляется через нашего менеджера.

При создании merchant'a обязательным является, лишь:

название - текстовое название для вашего merchant'a, оно будет отображаться в стандартных страницах с чеком;
домены - ваши доверенные домены, на которые будут установлен виджет.

Опциональные параметры:

Все параметры опциональны и могут отправляться при создании транзакции либо указаны в настройках merchant'a.

callback_back_url - URL для перенаправления клиента на сайт merchant'a;
callback_success_url - URL для перенаправления успешных платежей;
callback_failed_url - URL для перенаправления НЕуспешных платежей;
callback_post_url - URL на который будет отправляться запрос с результатом платежа. Подробнее в разделе Уведомление merchant'a о статусе транзакции.

После создания менеджером merchant'a, вы получите Идентификатор приложения (далее app_id) и Публичный Sodium ключ приложения (далее app_key), которые в дальнейшем будите использовать в виджете.

Интеграция виджета

Установить пакет:

npm i --save @nplus.tech/ktwidget-client

Импортировать класс:

import { ApiClient } from "@nplus.tech/ktwidget-client";

Создать метод и привязать этот метод к любому событию, пример:

<!DOCTYPE html>
<html lang="ru">
<head>
   <title>Тест виджета</title>
</head>
<body>
   <button onclick="openWidget()">Оплатить</button>
</body>
<script>
    function openWidget() {
     let transaction = new ApiClient(
         "h09acJ8QSLPw40XZxdNfLbq4hXzWInC5zXL319RdXUI=", // app_key - Публичный Sodium ключ приложения
         "e2d3d70d53c67bcd377266f74e98587c", // app_id - Идентификатор приложения
         true  // test_mode - флаг изменения работы виджета на тестовый и на боевой режим
               // true = test, false = production
     );
     transaction.createTransaction({
         // Список параметров транзакции, их описание смотрите в главе "Параметры транзакции"
         order_id: "1",
         amount: 1000,
         type: "service",
         service: {
             service_id: 1,
             contract_value: "1111111"
         },
         callback_back_url: "widget.nplus.tech",
         description: "Transaction from KTPAY"
     })
    }
</script>
</html>

Функция createTransaction обробатывает входящие данные и шифрует их с помощью публичного ключа app_key. Шифрование выполняет через libsodium подробнее на LIBSODIUM.

Параметры транзакции

Список параметров информацию о проводимой транзакции, он изменяется merchant'ом самостоятельно каждый раз при создании транзакции.

Описание параметров:

order_id (string, обязательно, уникально для каждой транзакции): номер транзакции, merchant сам решает как их генерировать;
amount (number, обязательно): сумма транзакции, целое число или число с плавающей точкой в 2 знака;
type (string, обязательно): тип транзакции, возможны 2 типа - ecom и service (подробнее в разделе Режимы работы виджета)
service (object, обязателен если type = 'service'): объект с параметрами сервиса;
- service_id (number, обязательно): id сервиса в системе ktpay. Список доступных сервисов необходимо уточнять у нашего менеджера.
- contract_value (string, обязательно): номер контракта для укаазанного сервиса. Это может быть номер телефона для сотовых операторов, номер лицевого счета для коммунальных платежей и т.д;
callback_back_url (string, опционально): URL куда необходимо вернуть клиента после проведения транзакции;
description (string, опционально): текстовое описание транзакции.

Уведомление merchant'a о статусе транзакции

Merchant может получать уведомления о статусе транзакций для этого неоходимо:

При создании merchant'a указать callback_post_url

или

При создании транзакции каждый раз отправлять параметр callback_post_url.

Приоритет следующий: если не был прислан параметр callback_post_url при создании транзакции, берется параметр callback_post_url из настроек merchant'a.

Отправка будет происходить только в момент окончательного статуса транзакции: completed, error, denied. Подробнее о статусах Статусы транзакции

URL merchant'a - callback_post_url должен принемать запрос методом POST и отвечать правильным JSON форматом, подробнее ниже в примере запроса.

Пример запроса:

URL: callback_post_url - полученный от merchant'a
Метод: POST
Заголовки: Content-Type: application/json

Тело запроса (Успех):

{
   "merchant_id":1,
   "order_id":"1",
   "description":"Description of transactions",
   "amount":1000,
   "transaction_hash":"af7ed500aa9f2132fae4b63e936af641bcc4ebaf",
   "created_at":"2019-02-05T14:22:53+06:00",
   "updated_at":null,
   "status":{
      "status":"completed",
      "created_at":"2019-02-05T14:23:09+06:00",
      "updated_at":null,
      "error":null
   }
}

Тело запроса (Ошибка):

{
   "merchant_id":1,
   "order_id":"1",
   "description":"Description of transactions",
   "amount":1000,
   "transaction_hash":"af7ed500aa9f2132fae4b63e936af641bcc4ebaf",
   "created_at":"2019-02-05T14:22:53+06:00",
   "updated_at":null,
   "status":{
      "status":"error",
      "created_at":"2019-02-05T14:23:09+06:00",
      "updated_at":null,
      "error": {
        "error_type": "ERROR_PAYMENT",
        "error_message": "KKB rejected payment"
    }
   }
}

Ожидаемый ответ:

Заголовки: Content-Type: application/json
Тело запроса:
```
{
  "status": "ok"
}
```

В случаях, когда ответ будет иным, будет сделаны повторные попытки отправки статуса через 15с, 60с, 3м, 10м, 30м, 60м.

Описание параметров тела запроса:

merchant_id (number): id merchant'a генерируемый ktpay-ем при регистрации merchant'a;
order_id (string): номер транзакции, присланный merchant'ом при регистрации транзакции;
description (string): текстовое описание транзакции, присланное merchant'ом при регистрации транзакции;
transaction_hash (string): id транзакции в системе ktpay, при каких обращении в тех.поддержку можно его использовать;
created_at (datetime): дата создания транзакции в системе ktpay;
updated_at (datetime): дата последнего обновления транзакции в системе ktpay;

Статусы транзакции

status (object): объект с параметрами статуса транзакции;
- status (string): текстовое поле со статусом транзакции, возможные следующие статусы:
  - pending - транзакции ожидает проведения, клиент не ввел еще карточные данные;
  - authorized - авторизован, с карты клиента заблокированы деньги, ожидается дальнейшая обработка транзакции;
  - success - успешен, но не завершен клиринг с карты клиента;
  - error (окончательный статус) - ошибка во время проведения транзакции, транзакция считается ошибочной;
  - denied (окончательный статус) - отклонен по одной из сторон, эквайер, шлюз сервиса, системой ktpay, транзакция считается ошибочной;
  - completed (окончательный статус) - успешен, завершен клиринг с карты клиента.
- created_at (datetime): дата создания статуса транзакции в системе ktpay;
- updated_at (datetime): дата последнего обновления статуса транзакции в системе ktpay;
- error (object): только при статусах error и denied будет содержать параметры ошибки транзакции:
  - error_type (string): текстовый тип ошибки транзакции, возможные варианты:
    - ERROR_PAYMENT - тип ошибки во время выполнения транзакции;
    - ERROR_INPUT - тип ошибки во время ввода карточных данных;
    - ERROR_SYSTEM - тип ошибки во время обработки транзакции внутри сервиса ktpay;
  - error_message (string): текстовое описание ошибки транзакции.

@nplus.tech/ktwidget-client

Usage no npm install needed!