ЮKassa: Узнавать об оплате через HTTP-уведомления

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

ЮKassa сама сообщает о смене статуса платежа или возврата, не нужно опрашивать API.

1. В личном кабинете, в разделе Интеграция — HTTP-уведомления, укажи URL и события: payment.succeeded, payment.waiting_for_capture, payment.canceled, refund.succeeded. URL — только HTTPS на порту 443 или 8443, TLS 1.2 и выше.
2. Принимай POST-запрос с объектом события и отвечай HTTP 200. На любой другой код ЮKassa повторяет отправку в течение 24 часов.
3. Проверь подлинность: запроси объект — GET /payments/{payment_id} — и сверь статус. Еще один способ — проверить IP отправителя: 185.71.76.0/27, 185.71.77.0/27, 77.75.153.0/25, 77.75.156.11, 77.75.156.35, 77.75.154.128/25, 2a02:5180::/32.
4. Партнерам с OAuth-токеном подписка доступна через API: POST /webhooks.

Базовые URL

• Основной: https://api.yookassa.ru/v3

Авторизация

Тип: Basic Auth

HTTP Basic Auth: имя пользователя — идентификатор магазина (shopId, раздел Настройки — Магазин) или шлюза для выплат (agentId, раздел Настройки выплат), пароль — секретный ключ (раздел Интеграция — Ключи API). Для тестового магазина ключ выпускается автоматически. Участники партнерской программы используют OAuth 2.0 и передают Bearer-токен. Секретный ключ и OAuth-токен нельзя публиковать.

curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -u <Идентификатор магазина>:<Секретный ключ>

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

GET /payments/{payment_id} — Информация о платеже

Запрос позволяет получить информацию о текущем состоянии платежа по его уникальному идентификатору.

Документация: https://yookassa.ru/developers/api#get_payment

Параметр	Где	Тип	Обяз.	Описание
payment_id	path	string	да	Идентификатор платежа.

Пример ответа:

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "succeeded",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "created_at": "2017-11-03T11:52:31.827Z",
  "paid": true,
  "test": false,
  "refundable": true,
  "recipient": {
    "account_id": "123",
    "gateway_id": "456"
  }
}

POST /webhooks — Создание webhook

С помощью этого запроса можно подписаться на уведомления о событии (например, об изменении статуса платежа на succeeded). Через вебхуки можно подписаться только на события платежей и возвратов; чтобы получать уведомления о нескольких событиях, нужно создать отдельный вебхук для каждого из них. Для каждого OAuth-токена нужен свой набор вебхуков.

Документация: https://yookassa.ru/developers/api#create_webhook

Параметр	Где	Тип	Обяз.	Описание
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
event	body	string (payment.waiting_for_capture, payment.succeeded, payment.canceled, refund.succeeded, payment_method.active)	да	Событие, которое вы хотите отслеживать.
url	body	string	да	URL, на который ЮKassa будет отправлять уведомления.

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

{
  "event": "payment.succeeded",
  "url": "https://www.example.com/notification_url"
}

Пример ответа:

{
  "id": "wh-e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "event": "payment.succeeded",
  "url": "https://www.example.com/notification_url"
}

Нюансы

• capture по умолчанию false: без capture: true платеж останется в статусе waiting_for_capture и в момент expires_at отменится автоматически, деньги вернутся покупателю.
• Для POST и DELETE обязателен заголовок Idempotence-Key — до 64 символов, рекомендуется UUID. Повтор с тем же ключом в течение 24 часов вернет результат первого запроса; для новой операции нужен новый ключ.
• HTTP 500 не значит, что операция не прошла: результат неизвестен. Повтори запрос с теми же данными и тем же ключом идемпотентности или запроси объект через GET.
• Возврат покупателя на return_url не означает успешную оплату — статус проверяй на сервере или по HTTP-уведомлению.
• Сумма — строка с точкой и двумя знаками: "1000.00", вместе с кодом валюты.
• Методы /webhooks работают только с OAuth-токеном в партнерской программе. Обычный магазин настраивает уведомления в личном кабинете.
• Вернуть платеж можно в течение трех лет с момента создания. Комиссия ЮKassa за платеж не возвращается.
• Для Чеков от ЮKassa частичная предоплата, аванс и кредит не поддерживаются.

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

• Принять оплату с переадресацией на ЮKassa
• Двухстадийная оплата: заблокировать и списать
• Вернуть деньги покупателю
• Отправить чек по 54-ФЗ вместе с платежом
• Автоплатежи: сохранить способ оплаты и списывать без покупателя
• Выгрузить платежи за период

---

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