Требования к реализации
Pay API
Для реализации сценариев технической интеграции с Pay API, к торгово-сервисному предприятию (ТСП) и разработчикам кассового ПО предъявляются следующие технические требования.
Все требования являются обязательными, если не указана отметка «опционально».
1. Требования к реализации сценариев
Перечень сценариев, реализующих платёжные операции в сервисе Koshelek Pay, приведён на странице Обзор сценариев API.
Необходимо поддерживать:
- прямые сценарии;
- частные случаи прямых сценариев;
- альтернативные сценарии;
- обработку ошибок.
2. Требования к формированию кассового чека
:information_source: опционально
В кассовом чеке, формируемом кассой и передаваемом покупателю, рекомендуется предусмотреть блок с отображением информации об операции оплаты / возврата выполненной с использованием сервиса Koshelek Pay.
Эта информация может быть важна для покупателя в случае обращения в службу поддержки, а для кассира — при оформлении возврата.
| Параметр Pay API | Описание | Примечание |
|---|---|---|
orderId |
ID (номер) заказа на стороне ТСП. | Общий для сценариев оплаты и возврата. |
paymentTransactionId |
ID операции оплаты на стороне Кошелька. | Уникален для сценария оплаты. |
refundTransactionId |
ID операции возврата на стороне Кошелька. | Уникален для сценария возврата. |
paymentType |
Тип провайдера платежей (Долями / СБП). | Общий для сценариев оплаты и возврата. |
qrcId |
ID транзакции, зарегистрированный в СБП. | Для paymentType = SBP |
kzo |
Контрольное значение операции СБП. | Для paymentType = SBP |
3. Требования к реализации контракта API
Интеграция с сервисом Pay API должна осуществляться в соответствии с текущей наиболее свежей версией API (указана в верхней строке списка версий на странице История изменений). Ниже перечислены запросы Pay API с указанием обязательности их реализации:
| Запрос Pay API | Обязательность |
|---|---|
| Запрос списка возможных провайдеров платежей | Опционален |
| Инициализация платежа | Обязателен |
| Получение статуса транзакции | Обязателен |
| Отправка чека | Опционален |
| Отмена оплаты | Обязателен |
| Возврат оплаты | Обязателен |
3.1 Минимальная задержка при обработке сценариев
Необходимо обеспечить минимальную задержку при обработке сценариев взаимодействия с Pay API. Время задержки между нажатием кнопки на кассе и передачей данных на сервер Кошелька не должно превышать 0,5 секунды.
Пример: сценарий оплаты
После того, как покупатель указал способ оплаты через Koshelek Pay и кассир выбрал соответствующий способ в кассовом ПО, система ТСП должна незамедлительно (в пределах 0,5 секунды) передать в Pay API данные, необходимые для оплаты.
3.2. Идемпотентность методов Pay API
Методы Pay API являются идемпотентными. Партнёру необходимо учитывать это при проектировании сервиса, взаимодействующего с Pay API. Особое внимание следует обратить на это при осуществлении возврата (см. Сценарий 3. Возврат оплаты → Альтернативные сценарии возврата и возможные ошибки).
4. Требования к дополнительным API
4.1. Store API
:information_source: опционально
Для оперативного обновления информации о точках обслуживания, поддерживающих оплату через Koshelek Pay, рекомендуется интеграция Store API.
5. Требования к обработке ошибок
5.1. Обработка кодов ошибок API
Необходимо реализовать корректную обработку ошибок Pay API. Список возможных HTTP-кодов ответов Pay API, включая ответы об ошибках, приведён на странице описания API.
5.2. Обработка ошибок с участием кассира
При обработке ошибок, требующих участия кассира, необходимо реализовать понятное отображение ошибок на экране кассового терминала, с краткой инструкцией для кассира. Рекомендации см. на странице описания API в столбце «Рекомендации кассиру».
6. Требования к реализации TOTP
6.1. Приём штрихкодов с поддержкой TOTP
Для верификации штрихкодов, поддерживающих Koshelek Pay, необходимо обеспечить приём и распознавание штрихкодов карт лояльности, содержащих не только номер карты, но и верифицирующую информацию:
- одноразовый код сессии
cardSession - одноразовый пароль TOTP
6.1.1. Допустимые форматы штрихкодов с поддержкой TOTP
Допускаются следующие форматы TOTP-штрихкодов:
- code128
- PDF417
- DataMatrix
- QR code
6.2. Интеграция программного модуля Koshelek TOTP
Для работы с TOTP-штрихкодами Koshelek Pay партнёру необходимо интегрировать в свою инфраструктуру программный модуль Koshelek TOTP — в соответствии с руководством на странице Модуль Koshelek TOTP.
6.3. Поддержка обратной совместимости
Реализованная поддержка TOTP-штрихкодов должна обеспечивать обратную совместимость с картами лояльности ТСП, не поддерживающими TOTP-верификацию (до подключения к Koshelek Pay — т.е. не содержащих значения cardSession и одноразового пароля TOTP).
7. Требования к кассовым отчётам
7.1. Сохранение параметров слип-чека операции
Все параметры слип-чека выполненной операции (на уровне Pay API передаются в объекте slip) должны сохраняться в базе данных кассы.
7.2. Расширение параметров внутренней отчётности кассы
Перечисленные ниже параметры, передаваемые в рамках взаимодействия с Pay API, должны быть добавлены в кассовые отчёты:
| Параметр Pay API | Описание | Примечание |
|---|---|---|
orderId |
ID заказа. | Общий для оплаты и возврата. |
paymentTransactionId |
ID операции оплаты на стороне Кошелька. | Уникален для сценария оплаты. |
refundTransactionId |
ID операции возврата на стороне Кошелька. | Уникален для сценария возврата. |
requestId |
Уникальный ID запроса от кассы. | Уникален для каждого запроса независимо от сценария. |
paymentType |
Тип провайдера платежей в Koshelek Pay. | Тип провайдера платежей (Долями / СБП), определяет механизм оплаты покупки. |
qrcId |
ID транзакции , зарегистрированный в СБП. | Для paymentType = SBP |
kzo |
Контрольное значение операции СБП | Для paymentType = SBP |
8. Требования к конфигурациям
8.1. Конфигурация данных кассы
Для интеграции и организации информационного обмена с Pay API используется ряд идентификаторов и технологических параметров. Партнёру необходимо предусмотреть возможность оперативного изменения следующих параметров сервиса, взаимодействующего с Pay API (вынесением их в отдельный конфигурационный файл или иным способом).
| Параметр информационного обмена | Конфигурируемость |
|---|---|
login |
Обязательно |
password |
Обязательно |
store |
Обязательно |
API Base URL (test) |
Обязательно |
API Base URL (production) |
Обязательно |
terminal |
Опционально |
paymentPurpose |
Опционально |
8.2. Конфигурация Pay API
Для гибкого управления автоматизации запросов часть логики необходимо реализовать через конфигурируемые параметры, а именно:
- Допустимые значения как входящих, так и исходящих параметров типа ENUM. Это позволит не дорабатывать кассовое ПО, например, в случае появления новых провайдеров платежей.
- Автоматизация действий кассы в случае таймаутов и повторной отправки запросов. Это позволит улучшать пользовательский опыт в процессе эксплуатации.
8.2. Конфигурация TOTP
Для инициализации модуля TOTP партнёру необходимо предусмотреть возможность оперативного изменения идентификаторов и технологических параметров (см. Модуль Koshelek TOTP → Установка и конфигурирование → Конфигурирование). Все параметры обязательны.