Требования к реализации
Кошелёк Pay API
Документация перемещена
Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:
Для реализации сценариев технической интеграции с Кошелёк Pay API, к торгово-сервисному предприятию (ТСП) и разработчикам кассового ПО предъявляются следующие технические требования.
Все требования являются обязательными, если не указана отметка «опционально».
1. Требования к реализации сценариев
Перечень сценариев, реализующих платёжные операции в сервисе Кошелёк Pay, перечислен на странице Обзор сценариев API.
Необходимо поддерживать:
прямые сценарии;
частные случаи прямых сценариев;
альтернативные сценарии;
обработку ошибок.
2. Требования к формированию кассового чека
ℹ️ опционально
В кассовом чеке, формируемом кассой и передаваемом покупателю, рекомендуется предусмотреть блок с отображением информации об операции оплаты/возврата выполненной с использованием сервиса Кошелёк Pay.
Эта информация может быть важна для покупателя в случае обращения в службу поддержки, а для кассира — при оформлении возврата.
| Параметр Pay API | Описание | Примечание |
|---|---|---|
| ID (номер) заказа на стороне ТСП. | Общий для сценариев оплаты и возврата. |
| ID операции оплаты на стороне Кошелька. | Уникален для сценария оплаты. |
| ID операции возврата на стороне Кошелька. | Уникален для сценария возврата. |
| Тип провайдера платежей (СБП / Долями). | Общий для сценариев оплаты и возврата. |
| ID транзакции, зарегистрированный в СБП. | Для |
| Контрольное значение операции СБП. | Для |
3. Требования к реализации контракта Pay API
Интеграция с сервисом Кошелёк Pay API должна осуществляться в соответствии с текущей наиболее свежей версией Pay API (указана в верхней строке списка версий на странице Общие сведения → История изменений). Ниже перечислены запросы Pay API с указанием обязательности их реализации:
| Запрос | Обязательность |
|---|---|
Запрос списка возможных провайдеров платежей | Опционален |
Инициализация платежа | Обязателен |
Получение статуса транзакции | Обязателен |
Отправка чека | Опционален |
Отмена оплаты | Обязателен |
Возврат оплаты | Обязателен |
3.1 Минимальная задержка при обработке сценариев
Необходимо обеспечить минимальную задержку при обработке сценариев взаимодействия с Кошелёк Pay API. Время задержки между нажатием кнопки на кассе и передачей данных на сервер Кошелька не должно превышать 0,5 секунды.
Пример: сценарий оплаты
После того, как покупатель указал способ оплаты через Кошелёк Pay и кассир выбрал соответствующий способ в кассовом ПО, система ТСП должна незамедлительно (в пределах 0,5 секунды) передать в Кошелёк Pay API данные, необходимые для оплаты.
3.2. Идемпотентность методов Pay API
Методы Кошелёк Pay API являются идемпотентными. Партнёру необходимо учитывать это при проектировании сервиса, взаимодействующего с Pay API. Особое внимание следует обратить на это при осуществлении возврата (см. Сценарий 3. Возврат оплаты → Альтернативные сценарии возврата и возможные ошибки).
4. Требования к дополнительным API
4.1. Store API
ℹ️ опционально
Для оперативного обновления информации о точках обслуживания, поддерживающих оплату через Кошелёк Pay, рекомендуется интеграция Store API.
5. Требования к обработке ошибок
5.1. Обработка кодов ошибок API
Необходимо реализовать корректную обработку ошибок Pay API. Список возможных HTTP-кодов ответов Pay API, включая ответы об ошибках, приведён на странице Коды ответов API.
5.2. Обработка ошибок с участием кассира
При обработке ошибок, требующих участия кассира, необходимо реализовать понятное отображение ошибок на экране кассового терминала, с краткой инструкцией для кассира. Рекомендации см. на странице Коды ответов API в столбце «Рекомендации кассиру».
6. Требования к реализации TOTP
6.1. Приём штрихкодов с поддержкой TOTP
Для верификации штрихкодов, поддерживающих Кошелёк Pay, необходимо обеспечить приём и распознавание штрихкодов карт лояльности, содержащих не только номер карты, но и верифицирующую информацию:
одноразовый код сессии
cardSession(см. Подключение к API);одноразовый пароль TOTP (см. Модуль Кошелёк TOTP).
6.1.1. Допустимые форматы штрихкодов с поддержкой TOTP
Допускаются следующие форматы TOTP-штрихкодов:
code128
PDF417
DataMatrix
QR code
6.2. Интеграция программного модуля Кошелёк TOTP
Для работы с TOTP-штрихкодами Кошелёк Pay партнёру необходимо интегрировать в свою инфраструктуру программный модуль «Кошелёк TOTP» — в соответствии с руководством на странице Модуль Кошелёк TOTP.
6.3. Поддержка обратной совместимости
Реализованная поддержка TOTP-штрихкодов должна обеспечивать обратную совместимость с картами лояльности ТСП, не поддерживающими TOTP-верификацию (до подключения к Кошелёк Pay — т.е. не содержащих значения cardSession и одноразового пароля TOTP).
7. Требования к кассовым отчётам
7.1. Сохранение параметров слип-чека операции
Все параметры слип-чека выполненной операции (на уровне Pay API передаются в объекте slip) должны сохраняться в базе данных кассы.
7.2. Расширение параметров внутренней отчётности кассы
Перечисленные ниже параметры, передаваемые в рамках взаимодействия с Pay API, должны быть добавлены в кассовые отчёты:
| Параметр Pay API | Описание | Примечание |
|---|---|---|
| ID заказа | Общий для оплаты и возврата |
| ID операции оплаты на стороне Кошелька | Уникален для сценария оплаты |
| ID операции возврата на стороне Кошелька | Уникален для сценария возврата |
| Уникальный ID запроса от кассы | Уникален для каждого запроса независимо от сценария |
| Тип провайдера платежей в Кошелёк Pay | Тип провайдера определяет механизм оплаты покупки (Долями / СБП) |
| ID транзакции , зарегистрированный в СБП | Для |
| Контрольное значение операции СБП | Для |
8. Требования к конфигурациям
8.1. Конфигурация данных кассы
Для интеграции и организации информационного обмена с Pay API используется ряд идентификаторов и технологических параметров (см. Подключение к API → Параметры подключения). Партнёру необходимо предусмотреть возможность оперативного изменения следующих параметров сервиса, взаимодействующего с Pay API (вынесением их в отдельный конфигурационный файл или иным способом):
| Параметр | Конфигурируемость |
|---|---|
| Обязательно |
| Обязательно |
| Обязательно |
| Обязательно |
| Обязательно |
| Опционально |
| Опционально |
8.2. Конфигурация Pay API
Для гибкого управления автоматизации запросов часть логики необходимо реализовать через конфигурируемые параметры, а именно:
Допустимые значения как входящих, так и исходящих параметров типа ENUM. Это позволит не дорабатывать кассовое ПО, например, в случае появления новых провайдеров платежей.
Автоматизацию действий кассы в случае таймаутов и повторной отправки запросов. Это позволит улучшать пользовательский опыт в процессе эксплуатации.
8.3. Конфигурация TOTP
Для инициализации модуля TOTP партнёру необходимо предусмотреть возможность оперативного изменения идентификаторов и технологических параметров (см. Модуль Кошелёк TOTP → Установка и конфигурирование → Конфигурирование). Все параметры обязательны.
Last updated