Требования к реализации
Кошелёк Pay API
Документация перемещена
Информация на этой странице не обновляется и может быть устаревшей.
Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:
Для реализации сценариев технической интеграции с Кошелёк Pay API, к торгово-сервисному предприятию (ТСП) и разработчикам кассового ПО предъявляются следующие технические требования.
Все требования являются обязательными, если не указана отметка «опционально».
Перечень сценариев, реализующих платёжные операции в сервисе Кошелёк Pay, перечислен на странице Обзор сценариев API.
Необходимо поддерживать:
- прямые сценарии;
- частные случаи прямых сценариев;
- альтернативные сценарии;
- обработку ошибок.
опционально
ℹ
В кассовом чеке, формируемом кассой и передаваемом покупателю, рекомендуется предусмотреть блок с отображением информации об операции оплаты/возврата выполненной с использованием сервиса Кошелёк Pay.
Эта информация может быть важна для покупателя в случае обращения в службу поддержки, а для кассира — при оформлении возврата.
Параметр Pay API | Описание | Примечание |
|---|---|---|
orderId | ID (номер) заказа на стороне ТСП. | Общий для сценариев оплаты и возврата. |
paymentTransactionId | ID операции оплаты на стороне Кошелька. | Уни кален для сценария оплаты. |
refundTransactionId | ID операции возврата на стороне Кошелька. | Уникален для сценария возврата. |
paymentType | Тип провайдера платежей (СБП / Долями). | Общий для сценариев оплаты и возврата. |
qrcId | ID транзакции, зарегистрированный в СБП. | Для paymentType = SBP |
kzo | Контрольное значение операции СБП. | Для paymentType = SBP |
Интеграция с сервисом Кошелёк Pay API должна осуществляться в соответствии с текущей наиболее свежей версией Pay API (указана в верхней строке списка версий на странице Общие сведения → История изменений). Ниже перечислены запросы Pay API с указанием обязательности их реа лизации:
Запрос | Обязательность |
|---|---|
Запрос списка возможных провайдеров платежей | Опционален |
Инициализация платежа | Обязателен |
Получение статуса транзакции | Обязателен |
Отправка чека | Опционален |
Отмена оплаты | Обязателен |
Возврат оплаты | Обязателен |
Необходимо обеспечить минимальную задержку при обработке сценариев взаимодействия с Кошелёк Pay API. Время задержки между нажатием кнопки на кассе и передачей данных на сервер Кошелька не должно превышать 0,5 секунды.
После того, как покупатель указал способ оплаты через Кошелёк Pay и кассир выбрал соответствующий способ в кассовом ПО, система ТСП должна незамедлительно (в пределах 0,5 секунды) передать в Кошелёк Pay API данные, необходимые для оплаты.
Методы Кошелёк Pay API являются идемпотентными. Партнёру необходимо учитывать это при проектировании сервиса, взаимодействующего с Pay API. Особое внимание следует обратить на это при осуществлении возврата (см. Сценарий 3. Возврат оплаты → Альтернативные сценарии возврата и возможные ошибки).
опционально
ℹ
Для оперативного обновления информации о точках обслуживания, поддерживающих оплату через Кошелёк Pay, рекомендуется интеграция Store API.
Необходимо реализо вать корректную обработку ошибок Pay API.
Список возможных HTTP-кодов ответов Pay API, включая ответы об ошибках, приведён на странице Коды ответов API.
При обработке ошибок, требующих участия кассира, необходимо реализовать понятное отображение ошибок на экране кассового терминала, с краткой инструкцией для кассира.
Рекомендации см. на странице Коды ответов API в столбце «Рекомендации кассиру».
Для верификации штрихкодов, поддерживающих Кошелёк Pay, необходимо обеспечить приём и распознавание штрихкодов карт лояльности, содержащих не только номер карты, но и верифицирующую информацию:
Допускаются следующие форматы TOTP-штрихкодов:
- code128
- PDF417
- DataMatrix
- QR code
Для работы с TOTP-штрихкодами Кошелёк Pay партнёру необходимо интегрировать в свою инфраструктуру программный модуль «Кошелёк TOTP» — в соответствии с руководством на странице Модуль Кошелёк TOTP.
Реализованная поддержка TOTP-штрихкодов должна обеспечивать обратную совместимость с картами лояльности ТСП, не поддерживающими TOTP-верификацию (до подключения к Кошелёк Pay — т.е. не содержащих значения
cardSession и одноразового пароля TOTP).Все параметры слип-чека выполненной операции (на уровне Pay API передаются в объекте
slip) должны сохраняться в базе данных кассы.Перечисленные ниже параметры, передаваемые в рамках взаимодействия с Pay API, должны быть добавлены в кассовые отчёты:
Параметр Pay API | Описание | Примечание |
|---|---|---|
orderId | ID заказа | Общий для оплаты и возврата |
paymentTransactionId | ID операции оплаты на стороне Кошелька | Уникален для сценария оплаты |
refundTransactionId | ID операции возврата на стороне Кошелька | Уникален для сценария возврата |
requestId | Уникальный ID запроса от кассы | Уникален для каждого запроса независимо от сценария |
paymentType | Тип провайдера платежей в Кошелёк Pay | Тип провайдера определяет механизм оплаты покупки (Долями / СБП) |
qrcId | ID транзакции , зарегистрированный в СБП | Для paymentType = SBP |
kzo | Контрольное значение операции СБП | Для paymentType = SBP |
Для интеграции и организации информационного обмена с Pay API используется ряд идентификаторов и технологических параметров (см. Подключение к API → Параметры подключения). Партнёру необходимо предусмотреть возможность оперативного изменения следующих параметров сервиса, взаимодействующего с Pay API (вынесением их в отдельный конфигурационный файл или иным способом):
Параметр | Конфигурируемость |
|---|---|
login | Обязательно |
password | Обязательно |
store | Обязательно |
API Base URL (test) | Обязательно |
API Base URL (production) | Обязательно |
terminal | Опционально |
paymentPurpose | Опционально |
Для гибкого управления автоматизации запросов часть логики необходимо реализовать через конфигурируемые параметры, а именно:
- Допустимые значения как входящих, так и исходящих параметров типа ENUM. Это позволит не дорабатывать кассовое ПО, например, в случае появления новых провайдеров платежей.
- Автоматизацию действий кассы в случае таймаутов и повторной отправки запросов. Это позволит улучшать пользовательский опыт в процессе эксплуатации.
Для инициализации модуля TOTP партнёру необходимо предусмотреть возможность оперативного изменения идентификаторов и технологических параметров (см. Модуль Кошелёк TOTP → Установка и конфигурирование → Конфигурирование).
Все параметры обязательны.
Last modified 4mo ago