Payment Device API

Payment Device API позволяет терминалу смарт-кассы или экрану для гостя участвовать в приёме денег на кассе. Этот раздел — контракт для поставщика; машиночитаемая половина — документ OpenAPI, отдаваемый живьём по адресу GET /api/payments/v1/openapi.json (без аутентификации) и превращённый в страницы API reference этого сайта.

Модель: Sitora описывает приём денег, но не выполняет его

Sitora не двигает деньги и никогда не касается карточных данных. Платежи выполняют банки, платёжные провайдеры и сертифицированные платёжные приложения. Sitora — авторитет по процессам: ей принадлежат заказ, сумма, платёжное намерение, итоговая транзакция и журнал аудита.

Платёжное намерение — это созданный бэкендом запрос на приём полной суммы одного заказа на одной кассе. Это единственный объект, с которым вообще работает устройство, и каждое денежное поле в нём берётся из правды о заказе:

Каждую сумму определяет бэкенд. Ни устройство, ни клиент, ни полезная нагрузка провайдера не может задать или изменить её. Устройство, которое присылает сумму, не интегрируется — его просто игнорируют.

Одно правило

Всё остальное в этом разделе следует из одного ограничения:

Устройство может сообщить, что вернуло платёжное приложение. Оно никогда не может объявить, что деньги получены.

Сообщённый успех переводит намерение в processing и показывает кассиру, что сказало ваше приложение. Дальше кассир подтверждает его, и только это подтверждение создаёт подтверждённую транзакцию, которая помечает заказ оплаченным. Сообщённый отказ тоже не убивает намерение — ошибочный отказ освободил бы заказ для второго приёма денег, поэтому правило симметрично.

Это та же граница, которую Sitora проводит для роботов (они подают еду, но никогда не пишут статус заказа) и для своего ИИ-помощника (он готовит черновик, но никогда не исполняет). В приложении к деньгам это значит, что скомпрометированное или сломанное устройство не может выдумать платёж.

Виды устройств

Вид	Работает ли ПО	Типичная роль
smart_pos	да	Компаньон-рабочее место; передаёт приём денег соседнему сертифицированному платёжному приложению
customer_display	да	Показывает гостю сумму, динамический QR и момент оплаты
external_terminal	нет	Банковский терминал рядом с Sitora; исход подтверждает кассир
fiscal_register	нет	Касса, привязанная к фискальному оператору

Машинные учётные данные есть только у smart_pos и customer_display. Остальные два — записи в реестре: реальное железо, о котором Sitora знает, но с которым не разговаривает.

Возможности, а не бренды

Что устройству позволено, задаётся набором возможностей, который объявляют при регистрации устройства и который проверяется по платформенному реестру Sitora. Политики, маршрутизация и каждая подсказка в клиенте рассуждают в терминах возможностей; название бренда не появляется в логике Sitora нигде.

Возможность	Значение
payment_app_handoff	Может передать намерение соседнему платёжному приложению и вернуть корреляцию исхода
companion_workspace	Работает как Sitora Pro на подключённом устройстве
qr_dynamic_present	Рисует платёж провайдера динамическим QR для одного намерения
customer_total_display	Показывает гостю сумму заказа и ход оплаты
card_present_attested	Оплата принимается вне контура; исход подтверждает сотрудник
receipt_print	Печатает нефискальные чеки для гостя

Scope ваших учётных данных выводятся из этих возможностей, поэтому экран никогда не получает глаголы передачи, и компаньон без payment_app_handoff тоже их не получает.

Ещё две возможности есть в платформенном реестре, но сегодня за ними нет устройственной поверхности: fiscalize принадлежит фискальным кассам, которыми Sitora управляет через фискального оператора, а не через это API, а card_present_push зарезервирована для полуинтегрированных терминалов — ни один платёжный провайдер, с которым интегрирована Sitora, не публикует облачного API для отправки суммы на терминал, поэтому её пока никто не принимает. Объявление любой из них не меняет поведения на этой поверхности.

Что Sitora никогда не примет от устройства

• Любые данные держателя карты. Ни PAN, ни трек, ни EMV, ни CVV, ни OTP, ни учётные данные кошелька. Поля, куда их положить, не существует, и его появление не в планах.
• Сумму, валюту или ссылку на заказ по вашему выбору. Вам говорят, что принимать.
• Заявление о получении денег. См. «одно правило» выше.
• Свободный текст для чтения сотрудниками. Отчёты несут структурированную ссылку и ваш собственный кодированный результат; Sitora сама переводит коды в свой словарь.