Links

Требования к реализации

Кошелёк Pay API
Документация перемещена
Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:
Для реализации сценариев технической интеграции с Кошелёк Pay API, к торгово-сервисному предприятию (ТСП) и разработчикам кассового ПО предъявляются следующие технические требования.
Все требования являются обязательными, если не указана отметка «опционально».

1. Требования к реализации сценариев

Перечень сценариев, реализующих платёжные операции в сервисе Кошелёк Pay, перечислен на странице Обзор сценариев API.
Необходимо поддерживать:
  • прямые сценарии;
  • частные случаи прямых сценариев;
  • альтернативные сценарии;
  • обработку ошибок.

2. Требования к формированию кассового чека

ℹ️
опционально
В кассовом чеке, формируемом кассой и передаваемом покупателю, рекомендуется предусмотреть блок с отображением информации об операции оплаты/возврата выполненной с использованием сервиса Кошелёк Pay.
Эта информация может быть важна для покупателя в случае обращения в службу поддержки, а для кассира — при оформлении возврата.
Параметр Pay API
Описание
Примечание
orderId
ID (номер) заказа на стороне ТСП.
Общий для сценариев оплаты и возврата.
paymentTransactionId
ID операции оплаты на стороне Кошелька.
Уникален для сценария оплаты.
refundTransactionId
ID операции возврата на стороне Кошелька.
Уникален для сценария возврата.
paymentType
Тип провайдера платежей (СБП / Долями).
Общий для сценариев оплаты и возврата.
qrcId
ID транзакции, зарегистрированный в СБП.
Для paymentType = SBP
kzo
Контрольное значение операции СБП.
Для paymentType = SBP

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, необходимо обеспечить приём и распознавание штрихкодов карт лояльности, содержащих не только номер карты, но и верифицирующую информацию:

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
Описание
Примечание
orderId
ID заказа
Общий для оплаты и возврата
paymentTransactionId
ID операции оплаты на стороне Кошелька
Уникален для сценария оплаты
refundTransactionId
ID операции возврата на стороне Кошелька
Уникален для сценария возврата
requestId
Уникальный ID запроса от кассы
Уникален для каждого запроса независимо от сценария
paymentType
Тип провайдера платежей в Кошелёк Pay
Тип провайдера определяет механизм оплаты покупки (Долями / СБП)
qrcId
ID транзакции , зарегистрированный в СБП
Для paymentType = SBP
kzo
Контрольное значение операции СБП
Для paymentType = SBP

8. Требования к конфигурациям

8.1. Конфигурация данных кассы

Для интеграции и организации информационного обмена с Pay API используется ряд идентификаторов и технологических параметров (см. Подключение к API → Параметры подключения). Партнёру необходимо предусмотреть возможность оперативного изменения следующих параметров сервиса, взаимодействующего с Pay API (вынесением их в отдельный конфигурационный файл или иным способом):
Параметр
Конфигурируемость
login
Обязательно
password
Обязательно
store
Обязательно
API Base URL (test)
Обязательно
API Base URL (production)
Обязательно
terminal
Опционально
paymentPurpose
Опционально

8.2. Конфигурация Pay API

Для гибкого управления автоматизации запросов часть логики необходимо реализовать через конфигурируемые параметры, а именно:
  • Допустимые значения как входящих, так и исходящих параметров типа ENUM. Это позволит не дорабатывать кассовое ПО, например, в случае появления новых провайдеров платежей.
  • Автоматизацию действий кассы в случае таймаутов и повторной отправки запросов. Это позволит улучшать пользовательский опыт в процессе эксплуатации.

8.3. Конфигурация TOTP

Для инициализации модуля TOTP партнёру необходимо предусмотреть возможность оперативного изменения идентификаторов и технологических параметров (см. Модуль Кошелёк TOTP → Установка и конфигурирование → Конфигурирование). Все параметры обязательны.