Оплата картой без чека

только TCP

Запустить оплату на терминале и получить результат по TCP. Чек не пробивается.

Простой локальный метод для кассовых систем, которым нужна только банковская операция. Запустить её можно и документом с fiscal: false, см. способы оплаты: он работает на обоих каналах и даёт полный протокол v4.

Как это работает

 Клиент                   YaKassa                     Банк
   │  GET /payment            │                         │
   │  amount, processId ────► │ запуск оплаты ────────► │
   │  ◄── status=wait         │                         │
   │  GET /status?processId=… │                         │
   │  ──────────────────────► │                         │
   │  ◄── status=wait         │ ◄── результат операции ─│
   │  GET /status?processId=… │                         │
   │  ──────────────────────► │                         │
   │  ◄── success или fail    │                         │

Параметр	Значение
Адрес	`http://<IP кассы>:<порт>`, порт по умолчанию `8090`
Метод	только `GET`, параметры в строке запроса
Ответ	JSON в UTF-8
Авторизация	нет
Соединение	один запрос, один ответ, затем сокет закрывается

На кассе должны быть включены TCP сервер и настроена безналичная оплата.

Запустить оплату

GET/paymentTCP

Командная строка

curl --get 'http://192.168.0.50:8090/payment' \
  --data-urlencode 'amount=250.00' \
  --data-urlencode 'processId=61d770e8-7c70-4d2f-b3f4-e4b1dbac4462'

Поле	Тип	Обяз.	Описание
`amount`	Decimal	да	сумма, разделитель точка или запятая. Передавайте положительную сумму с двумя знаками
`processId`	String	да	уникальный идентификатор операции, лучше UUID v4

JSON

{ "processId": "61d770e8-7c70-4d2f-b3f4-e4b1dbac4462", "status": "wait", "amount": 250.00 }

wait значит только, что запрос передан в обработку. Он не подтверждает списание денег.

Получить результат

GET/statusTCP

Командная строка

curl --get 'http://192.168.0.50:8090/status' \
  --data-urlencode 'processId=61d770e8-7c70-4d2f-b3f4-e4b1dbac4462'

Опрашивайте раз в секунду. Общий таймаут ставьте не меньше времени, которое даёт банк, обычно 2–4 минуты. Истечение таймаута у вас не означает отказ банка.

Успех

{
  "processId": "61d770e8-7c70-4d2f-b3f4-e4b1dbac4462",
  "status": "success",
  "amount": 250.00,
  "chequeInfo": { "method": "card", "rrn": "123456789012" }
}

Отказ

{ "processId": "61d770e8-7c70-4d2f-b3f4-e4b1dbac4462", "status": "fail", "amount": 250.00 }

Поле	Описание
`processId`	идентификатор запроса
`status`	`wait`, `success` или `fail`
`amount`	сумма операции
`chequeInfo.method`	способ, всегда `card`
`chequeInfo.rrn`	RRN банка. Поля нет, если банк его не вернул

Повторы и занятая касса

Терминал один, поэтому оплата идёт только одна.

Запрос	Что ответит касса
Повтор `/payment` с тем же `processId`, оплата идёт	текущее состояние, вторая оплата не запускается
Повтор `/payment` с тем же `processId`, оплата успешна	сохранённый результат
`/payment` с другим `processId`, пока идёт оплата	код 400, `Касса занята оплатой на сумму …, идёт процесс …`

Если результат так и не пришёл, через 5 минут касса освобождается для новых оплат.

После обрыва связи нельзя создавать новый processId и сразу повторять списание. Сначала вызовите /status со старым идентификатором, иначе возможна двойная оплата.

Успешный результат хранится на кассе и переживает перезапуск приложения. Отказ хранится только в памяти: после перезапуска /status ответит ошибкой Result not found by processId ….

Ошибки

JSON

{ "status": "fail", "message": "описание ошибки" }

HTTP	Условие	`message`
400	нет `amount`	`amount absent`
400	неверная сумма	`amount error`
400	нет `processId`	`processId absent`
400	безнал не настроен	`on terminal not settings for card pay`
400	результат не найден	`Result not found by processId …`
400	идёт другая оплата	`Касса занята оплатой на сумму …, идёт процесс …`
404	метод не `GET`	`method POST not supported`
500	внутренняя ошибка	текст ошибки

Проверяйте и код HTTP, и поле status: часть ошибок разбора запроса приходит с кодом 200 и телом status: fail.

Чего здесь нет

Метод только запускает оплату и выдаёт её статус. Здесь нет авторизации, возврата, отмены и причины отказа банка. Значения параметров не декодируются, поэтому processId передавайте латинскими буквами и цифрами, а сумму без пробелов. Для возвратов используйте документ обмена.

План проверки

Новая оплата: wait, затем success.
Отказ или отмена: wait, затем fail.
Неизвестный processId в /status.
Повторный /payment после успеха.
Потеря соединения после /payment и восстановление через /status.
Перезапуск YaKassa после успешной операции.
Неверная и отсутствующая сумма, отсутствующий processId.
Оплата при ненастроенном безнале.
Вторая оплата, пока идёт первая.