CloudPayments API: Принимать уведомления об оплате и сверять платежи

Сценарий из mcp-everything. Актуально на 2026-10-24.

Pay-, Fail- и Check-уведомления сообщают о результате оплаты; сверка за период ловит то, что могло потеряться.

Укажи адреса уведомлений в личном кабинете. Проверяй подлинность каждого: HMAC-SHA256 от тела запроса с ключом API Secret, в base64, должен совпасть с заголовком Content-HMAC (или X-Content-HMAC).
На Check-уведомление (до списания) отвечай {"code":0}, чтобы принять платёж, или кодом 10–13, 20, чтобы отклонить (неверный заказ, сумма и т. д.). На Pay и Fail тоже отвечай {"code":0}, иначе CloudPayments будет повторять уведомление до 100 раз.
Сомневаешься в статусе — запроси транзакцию: POST /payments/get с TransactionId.
Раз в день сверяй операции за период: POST /v2/payments/list с CreatedDateGte, CreatedDateLte и PageNumber — 100 записей на страницу.

import base64, hashlib, hmac

def is_valid(body: bytes, header_hmac: str, api_secret: str) -> bool:
    digest = hmac.new(api_secret.encode(), body, hashlib.sha256).digest()
    return hmac.compare_digest(base64.b64encode(digest).decode(), header_hmac)

# В обработчике: if not is_valid(request.body, request.headers["Content-HMAC"], API_SECRET): вернуть 403
# Затем обновить заказ по InvoiceId и ответить {"code": 0}

Базовые URL

Боевой: https://api.cloudpayments.ru

Авторизация

Тип: Basic Auth

HTTP Basic Auth: логин — Public ID, пароль — API Secret. Оба значения есть в личном кабинете. Без заголовка авторизации или с неверными данными API возвращает HTTP 401 Unauthorized. API Secret нужно хранить в защищённом месте.

Параметры передаются методом POST в теле запроса: application/x-www-form-urlencoded («ключ=значение») или application/json. Ответ всегда JSON и содержит как минимум Success и Message.

{ "Success": false, "Message": "Invalid Amount value" }

Методы сценария

POST /payments/get — Просмотр транзакции

Детализация транзакции по номеру.

Параметр	Где	Тип	Обяз.	Описание
`TransactionId`	body	Long	да	Номер транзакции

Пример запроса:

{"TransactionId":897749645}

POST /v2/payments/list — Список транзакций за период

Результат сортируется по CreatedDate от старых к новым, 100 записей на страницу.

Параметр	Где	Тип	Обяз.	Описание
`CreatedDateGte`	body	Date	да	Начальная дата создания операций
`CreatedDateLte`	body	Date	да	Конечная дата создания операций
`PageNumber`	body	Number	да	Номер страницы, от 1
`TimeZone`	body	String	нет	Код временной зоны, по умолчанию UTC
`Statuses`	body	String Array	нет	Статусы: Authorized, Completed, Cancelled, Declined; по умолчанию все

Пример запроса:

{
    "PageNumber": 1,
    "CreatedDateGte":"2021-03-09T00:00:00+03:00",
    "CreatedDateLte":"2021-03-10T00:00:00+03:00",
    "TimeZone": "MSK",
    "Statuses": ["Authorized", "Completed", "Cancelled", "Declined"]
}

Нюансы

Success в ответе показывает только успешность запроса, а не статус транзакции. Статус транзакции смотрят в поле Model.Status или в уведомлениях.
Идемпотентность включается заголовком X-Request-ID с уникальным значением; результат хранится 1 час, новый запрос требует нового значения.
Если в целочисленное поле передать дробное число, ошибки не будет: значение математически округлится.
Токен работает только на том терминале (publicId), где был получен.
Финальный статус оплаты по токену СБП приходит только в Pay- и Fail-уведомлениях, а не в ответе на запрос.
Для ТСП с MCC 4814 обязателен телефон плательщика в Payer.Phone (только цифры, например +71234567890), иначе банки отклоняют операции.
Pay, Fail, Recurrent, Cancel, Confirm, Refund-уведомления повторяются до 100 раз (интервалы 1, 2, 5, 10, 30 минут), если сервер магазина недоступен или ответил кодом, отличным от нуля; таймаут ответа — 30 секунд.
Подлинность уведомлений проверяют по заголовкам X-Content-HMAC и Content-HMAC: HMAC-SHA256 от тела запроса (для GET — от строки параметров) в UTF-8, ключ — API Secret, результат в base64.
Уведомления приходят с адресов 185.98.81.0/28, 87.251.91.160/27, 46.46.175.96/27, 46.46.168.160/27, 162.55.174.97/32, 91.216.178.243/32.
Ответ на Check-уведомление: {"code":0} — принять платёж; коды 10, 11, 12, 13, 20 отклоняют его (неверный InvoiceId, AccountId, сумма, платёж не принят, просрочен).

Другие сценарии

Если этого недостаточно — официальная документация: https://developers.cloudpayments.ru/#api Вся интеграция одним документом: https://mcp-everything.ru/integrations/cloudpayments.md