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

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

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

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

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