Обзор

Данная документация описывает методы API сервиса Cloud.

Документация охватывает методы, реализованные в сервисе на сегодня:

• Приём платежей — оплата по криптограмме карты, по токену и через СБП, обработка 3-D Secure.
• Управление платежом — подтверждение и отмена двухстадийной оплаты, возврат средств.
• Просмотр операций — детализация по транзакции, выгрузка списка транзакций за день.
• Вспомогательные методы — публичный ключ и checkout.js для построения криптограммы.
• Фискализация — формирование кассового чека по транзакции.

Аутентификация запросов

Для аутентификации запроса используется HTTP Basic Auth — логин и пароль передаются в заголовке Authorization HTTP-запроса.

• Логин — PublicId терминала.
• Пароль — ApiSecret терминала.

Оба значения выдаются при подключении терминала. Если заголовок с данными аутентификации не передан или переданы неверные данные, сервис вернёт HTTP-статус 401 Unauthorized.

Идемпотентность запросов

Для защиты от повторной обработки одного и того же запроса (например, при сетевых ретраях) можно передавать заголовок X-Request-ID с уникальным идентификатором запроса.

Если запрос с таким же X-Request-ID на тот же метод уже был обработан, сервис вернёт сохранённый ранее ответ без повторного обращения к провайдеру. Результат хранится 10 секунд.

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

Это отдельный механизм, не путайте его с идемпотентностью выше: идемпотентность защищает от повторной обработки того же самого запроса, а повторная попытка — это новый запрос на оплату (возможно, другой картой) с тем же InvoiceId, что и у ранее неудачной попытки.

Поддерживается в методах payments/cards/charge, payments/cards/auth, payments/tokens/charge, payments/tokens/auth и payments/qr/sbp/link.

Если отправить InvoiceId, который уже использовался, сервис проверяет предыдущие попытки оплаты по нему:

• если все они закончились ошибкой (транзакция отклонена, просрочена и т.п. — финальные ошибочные статусы, см. Статусы транзакции) — сервис создаёт новую попытку оплаты по тому же заказу;
• если хотя бы одна из предыдущих попыток ещё не завершилась или завершилась успешно — новый запрос будет отклонён с ошибкой 400: "Транзакция с таким InvoiceId уже существует".

Формат ответа

Ответ на любой запрос возвращается в формате JSON с тремя полями:

Поле	Тип	Описание
Success	bool	Результат запроса
Message	string	Описание ошибки (если запрос завершился ошибкой)
Model	object	Данные ответа

Поле Success отражает только успешность самого запроса к API, а не статус транзакции. Статус транзакции нужно смотреть в поле Status объекта Model (см. Статусы транзакции).

Структура документации

Каждый раздел документации содержит:

• краткое назначение метода;
• HTTP-метод и полный URL;
• параметры запроса;
• параметры ответа;
• пример запроса и ответа;
• возможные примечания.