@nplus.tech/ktwidget-client

v1.2.0

Published

6 months ago

KTWidget api client

Downloads

2,006

0High
0Medium
0Low

idanchoi

kovalevcon

fintech api widget ktwidget nplus.tech

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

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

v1.2:

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

v1.1:

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

v1.0:

Изначальная версия.

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

Сайт 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.

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), которые в дальнейшем будите использовать в виджете.

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

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

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",
         show_close_button: true,
     })
    }
</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, опционально): текстовое описание транзакции.
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

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

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

Ошибки транзакции

Формат ответа в случаи ошибки при создании/обработки транзакции будет следующим:

{
  "success": false,
  "data": [],
  "error": {
    "code": 0,
    "messages": {
      "error": "Error text"
    },
    "hint": "Hint text"
  }
}

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

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

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

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

На стороне 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: Необходимо обновить крипто-ключ, для решения проблемы обратитесь в тех. поддержку с указанием кода ошибки.
На стороне банка-эквайера. KTPay перенаправляет клиента и управление банку-эквайеру, все дальнейшие ошибки могут возникнуть на разных этапах обработки, валидации карточных данных и т.д.:
- code: -22
  error: Системная ошибка, попробуйте провести транзакцию позже, если ошибка повторяется обратитесь в службу поддержки [email protected]
- code: -21 или 21
  error: Повторное проведение транзакции будет доступно не менее чем через 30 минут.
- code: -19
  error: 3DSecure/Securecode введен или введен некорректно. Пожалуйста, убедитесь в корректности ввода, либо переустановите пароль. Если ошибка повторяется обратитесь в службу поддержки [email protected]
- code: -17
  error: Проведение транзакции временно невозможно, попробуйте позже.
- code: -9
  error: Некорректно введен срок действия карты.
- code: -8, -4 или 8
  error: Сервер не отвечает. Попробуйте попозже.
- code: -3
  error: Произошла ошибка, возможно сумма заблокировалась на карте, обратитесь службу поддержки [email protected]
- code: -2 или 77
  error: Системная ошибка, попробуйте провести транзакцию позже, если ошибка повторяется обратитесь в службу поддержки [email protected]
- 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 введен или введен некорректно. Пожалуйста, убедитесь в корректности ввода, либо переустановите пароль. Если ошибка повторяется обратитесь в службу поддержки [email protected]
- code: 20
  error: Транзакция не успешна. Пожалуйста, повторите снова.
- code: 30
  error: Ошибка, пожалуйста, воспользуйтесь другой картой. В случае её отсутствия обратитесь в службу поддержки [email protected]
- code: 33 или 54
  error: Срок действия карты истек.
- code: 41 или 43
  error: Карта недействительна. Пожалуйста, обратитесь в Банк для выпуска новой карты.
- code: 45
  error: Статус карты - украдена. Пожалуйста, обратитесь в Банк для выпуска новой карты.
- code: 51
  error: Недостаточно средств на карте.
- code: 57
  error: Транзакция отклонена. На карте запрещена возможность покупок в сети интернет, либо карточные данные введены неверно.
- code: 58
  error: Транзакция отклонена, пожалуйста, обратитесь в службу поддержки [email protected]
- 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: Ошибка в обслуживании карты. Убедитесь, что верно вводите номер карты. Если ошибка повторяется обратитесь в службу поддержки [email protected]
- code: 194
  error: Ошибка. Недоступна платежная система Visa/Mastercard. Попробуйте провести оплату позже. Если ошибка повторяется, обратитесь в службу поддержки [email protected]
- code: 195, 196 или 961
  error: Данный вид транзакции требует обязательного использования 3DSecure/Securecode пароля, пожалуйста воспользуйтесь картой, на которой возможно использование 3DSecure пароля.
- code: 216
  error: Попробуйте попозже. Терминал занят.
- code: 962
  error: Ошибка! Данная операция требует обязательного ввода 3DSecure/Securecode кода. Если Вы клиент Qazkom, Halyk установить 3D -код можно в www.HOMEBANK.kz. Если Вы клиент других казахстанских банков просим Вас обратится в свой банк.