npm package: @nplus.tech/ktwidget-client
Description: KTWidget api client
Author: Kovalev Konstantin|Mitrofanov Danil
Latest version: 1.2.1

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

# История изменений версий

### *v1.2.1*:
* Обновлен пакет `libsodium-wrappers` до версии `0.7.16`.

### *v1.2*:
* Добавлены новый параметр `show_close_button` - флаг указывающий необходимо ли отображать крестик закрытия
  на странице виджета.

### *v1.1*:
* Добавлены новые параметры `callback_force_back_url`, `callback_force_success_url`,
`callback_force_failed_url` - необходимые для исключительного перенаправления на
необходимые страницы мерчанта.

### *v1.0*:
* Изначальная версия.

#### Оглавление

- [Общее описание](#Общее-описание)
- [Режимы работы виджета](#Режимы-работы-виджета)
- [Подготовка](#Подготовка)
- [Интеграция виджета](#Интеграция-виджета)
- [Уведомление мерчанта о статусе транзакции](#Уведомление-мерчанта-о-статусе-транзакции)
- [Ошибки транзакции](#Ошибки-транзакции)

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

Сайт [KTWIDGET](https://widget.test.nplus.tech/)

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

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

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

1. Оплата за товар/услугу `merchant'a` (`type = 'ecom'`);
    * Режим необходим, когда нужно получить оплату с клиентов за товары/услуги на сайте
`merchant'a`.

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

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

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

1. Клиент на странице оплаты, нажимает кнопку "Оплатить".

2. Открывается модальное окно, в котором показывается анимация загрузки, а в фоновом режиме
выполняется следующее:

    * Отправка параметров транзакции;
    * Создание транзакции виджета;
    * Получение параметров эквайринга;
    * Открытие iFrame окна, в котором происходит перенаправление на страницу банка-эквайера.

3. Клиент видет в модальное окне форму для заполнения данных банковской карты, заполняет их и
нажимает "Оплатить".

4. Происходит валидация данных банковской карты и процесс обработки транзакции.

    * В случае ошибочных данных банковской карты, клиенту будет предложено ввести данные еще раз.
    Это функционал банка-эквайера, повлиять на него мы никак не можем.

5. Процесс обработки транзакций может закончиться двумя сценариями:

    * `Успех`: деньги с указанной карты будут заблокированы до дальнейшего проведения клиринга
    (окончательное снятие с карты);

    * `Ошибка`: по причине отказа банка-эквайера.

6. Пользователь будет перенаправлен на страницу чека платежа.

7. В зависимости от сценария процесса обработки транзакции далее будет:

    * В случае `успеха`: при нажатии на кнопку "Продолжить", будет сделано перенаправление на
    страницу успеха `merchant'a` (если она была указана) или отображена стандартная страница
    виджета с чеком оплаты.

    * В случае `ошибки`: при нажатии на кнопку "Продолжить", сделано перенаправление на страницу
    ошибки `merchant'a` (если она была указана) или отображена стандартная страница ошибки виджета.

8. Для успешного сценария предусмотрены дальнейшие действия:
    * Если тип транзакции был `type = 'service'`,
    (подробнее в разделе [Режимы работы виджета](#Режимы-работы-виджета))
    тогда идет выполнения начисления в пользу сервиса ktpay. В это время деньги на ранее
    указанной банковской карте остаются в блокировке. Сам процесс начисления может занимать от
    несколько секунд до минут, после этого следует следующий шаг.

    * Окончательный этап для каждой транзакции является `клиринг`, процесс окончательного снятия
    заблокированных денег с карты.

9. Предусмотрен дополнительный шаг в виде уведомления `merchant'a` о статусе проведенной транзакции.
   Данный шаг опционален и будет исполнен только в тех случаях, когда `merchant` указал необходимый
   `callback_post_url` либо в общий настройках при создании `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 на который будет отправляться запрос с результатом платежа.
  Подробнее в разделе
  [Уведомление мерчанта о статусе транзакции](#Уведомление-мерчанта-о-статусе-транзакции).

**Исключительное перенаправление** на страницы мерчанта, можно использовать, когда нет необходимости показывать
страницы виджета (страницы успеха/ошибки), перенаправление происходит сразу после прохождения оплаты.
Используются для этого следующие опциональные параметры:
* `callback_force_back_url` - URL для перенаправления клиента на сайт `merchant'a`, исключая показ
  страниц виджета (страницы успеха/ошибки);
* `callback_force_success_url` - URL для перенаправления только успешных платежей, исключая показ
  страниц виджета (страницы успеха/ошибки);
* `callback_force_failed_url` - URL для перенаправления только **НЕ**успешных платежей, исключая показ
  страниц виджета (страницы успеха/ошибки);

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

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

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

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

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

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

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

    ```html
    <!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",
             show_close_button: true,
         })
        }
    </script>
    </html>
    ```

Функция `createTransaction` обрабатывает входящие данные и шифрует их с помощью публичного ключа `app_key`.
Шифрование выполняет через `libsodium` подробнее на [LIBSODIUM](https://libsodium.gitbook.io/doc/).

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

Список параметров информацию о проводимой транзакции, он изменяется `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`, опционально): текстовое описание транзакции.

* `show_close_button` (`bool`, опционально, по умолчанию будет передано true): флаг для отображения кнопки
   закрытия виджета, в случае значения `false` кнопка будет скрыта.

### Уведомление мерчанта о статусе транзакции

`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`

* Тело запроса (Успех):
    ```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
       }
    }
    ```

* Тело запроса (Ошибка):
    ```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":"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`

* Тело запроса:
    ```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`): текстовое описание ошибки транзакции.

### Ошибки транзакции
Формат ответа в случаи ошибки при создании/обработки транзакции будет следующим:
    
```json
{
  "success": false,
  "data": [],
  "error": {
    "code": 0,
    "messages": {
      "error": "Error text"
    },
    "hint": "Hint text"
  }
}
```

где `code` - код ошибки, integer;

`messages` - массив из ошибок, может содержать одно или несколько `error`;

`hint` - подсказка как поступить с ошибкой.

Ошибки могут быть двух типов:

1. На стороне KTPay:

   *
      `code`: 5000001,
  
      `error`: Общая внутренняя ошибка сервера.
  
      `hint`: Неполадки в работе сервера, попробуйте сделать запрос позднее или обратиться в тех. поддержку.

   *
      `code`: 5000105,

      `error`: Непредвиденная ошибка во время создания транзакции мерчанта.

      `hint`: Неполадки в работе сервера, попробуйте сделать запрос позднее или обратиться в тех. поддержку.

   *
      `code`: 5000106,

      `error`: Непредвиденная ошибка во время получения данных авторизации для указанной транзакции мерчанта.

      `hint`: Неполадки в работе сервера, попробуйте сделать запрос позднее или обратиться в тех. поддержку.

   *
      `code`: 5000107,

      `error`: Непредвиденная ошибка во время получения информации о транзакции мерчанта.

      `hint`: Неполадки в работе сервера, попробуйте сделать запрос позднее или обратиться в тех. поддержку.

   *
      `code`: 5000110,

      `error`: Непредвиденная ошибка в работе модуле генерации чека транзакции мерчанта.

      `hint`: Неполадки в работе сервера, попробуйте сделать запрос позднее или обратиться в тех. поддержку.

   *
      `code`: 5000109,

      `error`: Непредвиденная ошибка во время генерации чека транзакции мерчанта.

      `hint`: Неполадки в работе сервера, попробуйте сделать запрос позднее или обратиться в тех. поддержку.

   *
      `code`: 4010103,

      `error`: Неверный/несуществующий идентификатор приложения мерчанта.

      `hint`: Для решения проблемы обратитесь в тех. поддержку с указанием кода ошибки.

   * 
      `code`: 4220002,

      `error`: Ошибка валидации параметров запроса.

      `hint`: Исправьте указанные замечания по валидации.
   *
      `code`: 4220101,

      `error`: Некорректный формат или содержимое данных.

      `hint`: Проверки корректность данных, их формат и содержимое или обратиться в тех. поддержку.
   *
      `code`: 4220102,

      `error`: Некорректный тип шифрования для данных.

      `hint`: Неполадки в работе сервера, обратиться в тех. поддержку с указанием кода ошибки.

   *
      `code`: 4220104,

      `error`: Используемый крипто-ключ истек по сроку использования.

      `hint`: Необходимо обновить крипто-ключ, для решения проблемы обратитесь в тех. поддержку с указанием кода ошибки.

2. На стороне банка-эквайера. KTPay перенаправляет клиента и управление банку-эквайеру, все дальнейшие ошибки могут возникнуть на разных этапах обработки, валидации карточных данных и т.д.:

   *
     `code`: -22

     `error`: Системная ошибка, попробуйте провести транзакцию позже, если ошибка повторяется обратитесь в службу поддержки help.epay@halykbank.kz

   *
     `code`: -21 или 21

     `error`: Повторное проведение транзакции будет доступно не менее чем через 30 минут.

   *
     `code`: -19

     `error`: 3DSecure/Securecode введен или введен некорректно. Пожалуйста, убедитесь в корректности ввода, либо переустановите пароль. Если ошибка повторяется обратитесь в службу поддержки help.epay@halykbank.kz

   * 
      `code`: -17
      
      `error`: Проведение транзакции временно невозможно, попробуйте позже.

   * 
      `code`: -9

      `error`: Некорректно введен срок действия карты.

   *
     `code`: -8, -4 или 8

     `error`: Сервер не отвечает. Попробуйте попозже.

   *
     `code`: -3

     `error`: Произошла ошибка, возможно сумма заблокировалась на карте, обратитесь службу поддержки help.epay@halykbank.kz

   *
     `code`: -2 или 77

     `error`: Системная ошибка, попробуйте провести транзакцию позже, если ошибка повторяется обратитесь в службу поддержки help.epay@halykbank.kz

   *
     `code`: 1A, 01, 02, 05 или 37

     `error`: Транзакция отклонена вашим банком. Для уточнения причины отказа необходимо обратиться по контактам, указанным на обратной стороне вашей карты.

   *
     `code`: 04, 07, 36, 46, 62, 75 или 86

     `error`: Карта заблокирована. Для уточнения необходимо обратиться по контактам, указанным на обратной стороне вашей карты.

   *
     `code`: 12

     `error`: Недействительная транзакция, перепроверить введенные данные.

   *
     `code`: 14 или 15

     `error`: Недействительный номер карточки, пожалуйста, убедитесь в корректности ввода номера карты и попробуйте ещё раз.

   *
     `code`: 19

     `error`: 3DSecure/Securecode введен или введен некорректно. Пожалуйста, убедитесь в корректности ввода, либо переустановите пароль. Если ошибка повторяется обратитесь в службу поддержки help.epay@halykbank.kz

   *
     `code`: 20

     `error`: Транзакция не успешна. Пожалуйста, повторите снова.

   *
     `code`: 30

     `error`: Ошибка, пожалуйста, воспользуйтесь другой картой. В случае её отсутствия обратитесь в службу поддержки help.epay@halykbank.kz

   *
     `code`: 33 или 54

     `error`: Срок действия карты истек.

   *
     `code`: 41 или 43

     `error`: Карта недействительна. Пожалуйста, обратитесь в Банк для выпуска новой карты.

   *
     `code`: 45

     `error`: Статус карты - украдена. Пожалуйста, обратитесь в Банк для выпуска новой карты.

   *
     `code`: 51

     `error`: Недостаточно средств на карте.

   *
     `code`: 57

     `error`: Транзакция отклонена. На карте запрещена возможность покупок в сети интернет, либо карточные данные введены неверно.

   *
     `code`: 58

     `error`: Транзакция отклонена, пожалуйста, обратитесь в службу поддержки i@nplus.tech

   *
     `code`: 59, 78, 88 или 94

     `error`: Транзакция отклонена вашим банком. Для уточнения причины отказа необходимо обратиться по контактам, указанным на обратной стороне вашей карты.

   *
     `code`: 61

     `error`: Сумма превышает допустимый лимит.

   *
     `code`: 63

     `error`: Запрет на проведение транзакции по вашей карте, за дополнительной информацией обратитесь по контактам, указанным на обратной стороне вашей карты.

   *
     `code`: 65

     `error`: Превышен лимит частоты оплат.

   *
     `code`: 75

     `error`: Карта заблокирована по причине неверного ввода пин-кода, за дополнительной информацией обратитесь по контактам, указанным на обратной стороне вашей карты.

   *
     `code`: 82

     `error`: Недоступен банк выпустивший карту, попробуйте повторить оплату позже.

   *
     `code`: 91

     `error`: Транзакция не успешна - недоступен банк выпустивший карту, попробуйте провести транзакцию позже.

   *
     `code`: 93

     `error`: Транзакция запрещена, воспользуйтесь другой картой.

   *
     `code`: 96

     `error`: Транзакция не успешна. Для карты Qazkom, Halyk -установите3DSecure/Securecode в HOMEBANK.kz. Для других карт - обратитесь в банк, выпустивший карту.

   *
     `code`: 189

     `error`: Некорректно введены данные по карте или email. Убедитесь в корректности вводимых данных.

   *
     `code`: 190, 198 или 199

     `error`: Проверка 3DSecure/Securecode недоступна. Попробуйте попозже.

   *
     `code`: 191

     `error`: 3DSecure/Securecode не введен или введен неверно.

   *
     `code`: 192

     `error`: Проверка 3DSecure/Securecode недоступна, либо неверно введен номер карты. Попробуйте воспользоваться другим браузером/устройством. Если ошибка повторяется, переустановите код.

   *
     `code`: 193

     `error`: Ошибка в обслуживании карты. Убедитесь, что верно вводите номер карты. Если ошибка повторяется обратитесь в службу поддержки help.epay@halykbank.kz

   *
     `code`: 194

     `error`: Ошибка. Недоступна платежная система Visa/Mastercard. Попробуйте провести оплату позже. Если ошибка повторяется, обратитесь в службу поддержки help.epay@halykbank.kz

   *
     `code`: 195, 196 или 961

     `error`: Данный вид транзакции требует обязательного использования 3DSecure/Securecode пароля, пожалуйста воспользуйтесь картой, на которой возможно использование 3DSecure пароля.

   *
     `code`: 216

     `error`: Попробуйте попозже. Терминал занят.

   *
     `code`: 962

     `error`: Ошибка! Данная операция требует обязательного ввода 3DSecure/Securecode кода. Если Вы клиент Qazkom, Halyk установить 3D -код можно в www.HOMEBANK.kz. Если Вы клиент других казахстанских банков просим Вас обратится в свой банк.

----
License © ТОО «НУРСАТ+»