Kassa24 Terminal

Обзор

Kassa24 Terminal — метод для проведения оплат с использованием физических терминалов Kassa24.

Характеристика

Тип платёжного метода Физический терминал
Регионы использования KZ
Валюты платежей KZT или USD*
Конвертация валют на стороне провайдера
Оплаты +
Выплаты
Оплаты по сохранённым данным
Полные возвраты
Частичные возвраты
Опротестования
Особенности
Организация и стоимость подключения По согласованию с курирующим менеджером ECommPay

* Пользователь может оплатить с использованием любой валюты, которая доступна в выбранном терминале. На стороне провайдера происходит конвертация валюты платежа в USD, и все платежи на стороне платёжной платформы и веб-сервиса проходят в валюте USD. Информацию о доступности валюты USD необходимо уточнять у курирующего менеджера ECommPay.

Схема работы

В проведении отдельной оплаты с использованием платёжного метода Kassa24 Terminal задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ECommPay, а также сервис Kassa24 Terminal.

Основные операции

Интерфейсы Суммы Время*
Payment Page CMS Plug-ins Gate Dashboard (Old Dashboard) минимум максимум базовое предельное
Оплаты + 1 минута 36 суток

* Базовое и предельное время определяются следующим образом:

  • Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.
  • Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус decline. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ECommPay.

Сценарии использования

Проведение оплат с использованием метода Kassa24 Terminal выполняется через физические терминалы Kassa24.

Рис.: Оплата Kassa24 Terminal



Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения оплат, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.

Оплаты через Gate

Общая информация

Для оплаты через Gate с использованием платёжного метода Kassa24 Terminal со стороны веб-сервиса необходимо:
  1. Обработать запрос на проверку существования лицевого счёта пользователя.
  2. Отправить ответ с информацией о существовании лицевого счёта пользователя.
  3. Обработать запрос на получение идентификатора платежа на стороне веб-сервиса.
  4. Отправить ответ с идентификатором платежа.
  5. Принять оповещение о результате оплаты.


Рис.: Проведение оплаты через Gate

  1. Пользователь выбирает веб-сервис, лицевой счёт в котором он хочет пополнить.
  2. От физического терминала на заданный URL ECommPay передаётся запрос на проверку существования лицевого счёта пользователя.
  3. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  4. От платёжной платформы к веб-сервису передаётся запрос на проверку существования лицевого счёта пользователя.
  5. На стороне веб-сервиса проводится обработка запроса.
  6. От веб-сервиса к платёжной платформе передаётся ответ на запрос.
  7. От платёжной платформе к сервису Kassa24 Terminal передаются данные о лицевом счёте пользователя.
  8. Пользователю отображается форма оплаты Kassa24 Terminal.
  9. Пользователь выполняет необходимые действия для пополнения лицевого счёта.
  10. На стороне сервиса Kassa24 Terminal выполняется обработка платежа.
  11. От сервиса Kassa24 Terminal к платёжной платформе направляется уведомление о результате оплаты.
  12. От платёжной платформе к веб-сервису передаётся запрос на получение идентификатора платежа на стороне веб-сервиса.
  13. На стороне веб-сервиса проводится обработка запроса.
  14. От веб-сервиса к платёжной платформе передаётся информация об идентификаторе платежа.
  15. На стороне платёжной платформы создаётся операция.
  16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  17. Пользователь получает информацию о результате проведения оплаты на экране физического терминала.

Информация о формате запросов и параметрах инициализации оплат методом Kassa24 Terminal через Gate, а также о формате оповещений о результатах оплат приведена далее. Общая информация о работе с API представлена в разделе Работа с API.

Формат запросов

При работе с запросами на проверку существования лицевого счёта пользователя необходимо учитывать следующее:

  1. Запрос verify для проверки существования лицевого счёта пользователя отправляется методом POST на заданный URL веб-сервиса.
  2. Запрос содержит следующие обязательные параметры:
    • action — тип операции на стороне веб-сервиса, значение параметра всегда verify;
    • site_login — идентификатор пользователя в системе мерчанта;
    • site_id — идентификатор проекта, полученный от ECommPay при интеграции;
    • signature — подпись запроса.

    Рис.: Пример запроса на проверку существования лицевого счёта пользователя

     {
        "action": "verify",   
        "site_id": "1487",
        "site_login": "123456789",
        "signature": "e19695449545fac562843ca06e7e0f3e51281ad6"
    }
  3. Ответ на запрос verify должен быть отправлен синхронно и содержать следующие обязательные параметры:
    • code — код ответа на запрос;
    • currency — валюта платежа в формате ISO-4217 alpha-3.

Корректный ответ на запрос должен содержать код ответа на запрос и валюту платежа.

Рис.: Пример ответа на запрос

{
    "code": 0,
    "error_description": "",
    "currency": "KZT"
}
При работе с запросами на получение идентификатора платежа на стороне веб-сервиса необходимо учитывать следующее:
  1. Запрос check_deposit для получения идентификатора платежа на стороне веб-сервиса отправляется методом POST на заданный URL веб-сервиса.
  2. Запрос содержит следующие обязательные параметры:
    • action — тип операции на стороне веб-сервиса, значение параметра всегда check_deposit;
    • site_login — идентификатор пользователя в системе мерчанта;
    • site_id — идентификатор проекта, полученный от ECommPay при интеграции;
    • amount — сумма платежа в минорных единицах;
    • currency — валюта платежа в формате ISO-4217 alpha-3;
    • payment_group_id — идентификатор платёжной группы, значение параметра всегда kassa24;
    • signature — подпись запроса.

    Рис.: Пример запроса на получение идентификатора платежа на стороне веб-сервиса

    {
        "action": "check_deposit",   
        "site_id": "1487",
        "site_login": "123456789",
        "signature": "e19695449545fac562843ca06e7e0f3e51281ad6",
        "amount": "10000",
        "currency": "KZT",
        "payment_group_id":"kassa24"
    }
  3. Ответ на запрос check_deposit должен быть отправлен синхронно и содержать следующие обязательные параметры:
    • code — код ответа на запрос;
    • external_id — уникальный идентификатор платежа на стороне веб-сервиса.

Корректный ответ на запрос получения идентификатора платежа на стороне веб-сервиса должен содержать код ответа на запрос и уникальный идентификатор платежа на стороне веб-сервиса.

Рис.: Пример ответа на запрос

{
    "code": 0,
    "external_id": "12365",
    "description": "sale"
}

Формат оповещений

Для оповещений о результатах оплат с применением метода Kassa24 Terminal используется стандартный формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 2275 была успешно проведена оплата в размере 100,00 KZT.

Рис.: Пример оповещения о проведенной оплате

{
        "project_id": 2275,
        "customer": {
            "id": "4444"
        },
        "payment": {
            "id": "1549267511",
            "type": "purchase",
            "status": "success",
            "date": "2019-02-04T08:05:17+0000",
            "method": "kassa24",
            "sum": {
                "amount": 10000,
                "currency": "KZT"
            },
            "is_new_attempts_available": false,
            "attempts_timeout": 0,
            "description": ""
        },
        "customer_data": {
            "ip_address": "192.168.15.15"
        },
        "fee": {
            "amount": 2910,
            "currency": "KZT"
        },
        "merchant_account_id": 2275,
        "operation": {
            "id": 8,
            "type": "sale",
            "status": "success",
            "date": "2019-02-04T08:05:17+0000",
            "created_date": "2019-02-04T08:05:13+0000",
            "request_id": "c4e54119785dd37f18d8d9f585d6be2ff25d8d79c41e8",
            "sum_initial": {
                "amount": 10000,
                "currency": "KZT"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "KZT"
            },
            "provider": {
                "id": 2275,
                "payment_id": "1549267510",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "nOAt011EDZ9uw8JindTcrZnOr7F5M2ZObxBAqUPjHUv/L3
                         AjYNOdKvF9tFOER6QH/5L7e0d4Q8y8nCUs/2YqDA=="
    }

Дополнительные материалы

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

Анализ результатов проведения платежей

Как и при работе с другими платёжными методами, которые предоставляет ECommPay, при использовании метода Kassa24 Terminal доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.

Всю необходимую информацию можно получать и анализировать средствами Dashboard (Old Dashboard), в том числе с помощью аналитических панелей на вкладке Analytics.

Также можно выгружать нужную информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:

  • Dashboard (Old Dashboard) позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
  • Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.

С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ECommPay.