❤
npm
Sign UpSign In

@nplus.tech/ktwidget-client

1.2.0 • Public • Published

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

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

v1.2:

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

v1.1:

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

v1.0:

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

Оглавление

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

Сайт KTWIDGET

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

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

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

  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. Установить пакет:

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

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

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

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

    <!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 - подсказка как поступить с ошибкой.

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

  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 © ТОО «НУРСАТ+»

Readme

Keywords

Package Sidebar

Install

npm i @nplus.tech/ktwidget-client

Repository

github.com/ktpay/ktwidget-client-js

Homepage

github.com/ktpay/ktwidget-client-js#readme

Weekly Downloads

162

Version

1.2.0

License

MIT

Unpacked Size

56.7 kB

Total Files

6

Last publish

Collaborators

  • idanchoi
  • kovalevcon
Try on RunKit
Report malware