Перейти к содержанию

Интеграция банка: фискализация в платежном шлюзе

Этот раздел описывает банковский слой, а не кассовый API. Кассовые сервисы делают фискальный документ на ККТ, а платежный шлюз банка дает партнеру единый способ передать чековые данные, запустить отдельную фискальную операцию и получить статус.

Два способа фискализации

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

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

Почему отдельный чек не равен новой оплате

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

Для этого нужен отдельный сервис фискализации, например doReceipt. Он не списывает деньги с карты. Он формирует чек по уже случившемуся или наступившему бизнес-событию.

Основные операции шлюза

Операция Зачем нужна Как объяснять человеку
Автоматическая фискализация при оплате Сформировать чек сразу после успешного платежа Обычный сценарий интернет-заказа, когда чек должен появиться вместе с оплатой
doReceipt Сформировать отдельный чек без нового платежа Закрывающий чек, ручная фискализация, фискальное событие отдельно от списания денег
retryReceipt Повторить фискализацию Если платеж прошел, но чек не сформировался из-за временной ошибки маршрута, кассового сервиса или ККТ
doCorrection Сформировать чек коррекции Если нужно исправить фискальную ошибку по правилам 54-ФЗ и ФФД
getReceiptStatus Получить статус чека Узнать, принят ли чек, ушел ли в кассу, фискализирован ли, есть ли ошибка

Типовой маршрут автоматической фискализации

Партнер создает/проводит платеж
  |
  | Передает payment data + receipt data
  v
Платежный шлюз
  |
  | Платеж успешен, сценарий требует чек
  v
Шлюз отправляет чековые данные кассовому сервису
  |
  v
Кассовый сервис и ККТ формируют фискальный документ
  |
  v
Шлюз получает статус и возвращает его партнеру

Типовой маршрут закрывающего чека

День 1: покупатель оплатил заказ
  |
  v
Партнер/шлюз сформировал чек на предоплату

День 7: товар передан покупателю
  |
  v
Партнер вызывает doReceipt
  |
  | В чеке отражается зачет предоплаты / полный расчет
  v
Кассовый сервис формирует закрывающий чек

Именно поэтому в сценарии «доставка через неделю» закрывающий чек формируется отдельной фискальной операцией doReceipt, если такой сценарий включен и партнер передает корректные данные.

Что должен передать партнер

Партнер передает не «текст чека», а структурированные данные:

  • состав предметов расчета;
  • цену, количество и сумму;
  • ставку и сумму НДС, если применимо;
  • признак способа расчета, например full_prepayment или full_payment;
  • признак предмета расчета: товар, услуга, платеж и так далее;
  • контакты покупателя для электронного чека;
  • реквизиты маркировки, если товар маркирован и сценарий допустим;
  • дополнительные реквизиты агента, поставщика или отраслевые реквизиты, если они нужны.

Шлюз может валидировать формат и обязательность на своем уровне, но он не должен подменять бизнес-смысл. Если партнер передал полный расчет, потому что товар уже передан, это один сценарий. Если товар будет передан позже, это предоплата и последующий закрывающий чек.

Статусы

Статус платежа и статус чека — разные вещи.

Платеж может быть успешным, а чек еще ожидать фискализации. Чек может упасть на стороне кассового сервиса, хотя деньги уже списаны. Чек может быть принят шлюзом, но еще не иметь финального фискального признака.

Поэтому для проверки сложной ситуации нужны оба слоя: статус платежа и статус фискализации. getReceiptStatus нужен именно для второго слоя.

Документация

Этот раздел не привязан к одному банковскому шлюзу: разные банки называют операции по-разному, но модель фискализации остается одинаковой. Для проверки нормативной и кассовой части используются официальные источники:

Если нужно сверить конкретный шлюз, сначала проверяется его актуальная спецификация по операциям автоматической фискализации, отдельного чека, повтора фискализации, чека коррекции и статуса чека. Без такой спецификации нельзя переносить названия методов из одного банка в другой как универсальный стандарт.