Инструкции
Помощь
Подключить ЮKassa
Входящие уведомления
Если вы хотите отслеживать состояние объектов, например платежей или возвратов, вы можете подписаться на уведомления (webhook, callback) о таких событиях.
Уведомления пригодятся в тех случаях, когда объект API изменяется без вашего участия. Например, если пользователю нужно подтвердить платеж, процесс оплаты может занять от нескольких минут до нескольких часов. Вместо того, чтобы всё это время периодически отправлять GET-запросы , чтобы узнать статус платежа, вы можете просто дожидаться уведомления от ЮKassa.
Доступные события
Событие в ЮKassa — изменение статуса объекта. Как только произойдет событие, на которое вы подписались, вам придет уведомление. В нём будут все данные об объекте на момент, когда его статус изменился.
В ЮKassa есть две группы событий, на уведомления которых можно подписаться:
Чтобы получать уведомления, их нужно настроить. После получения уведомления вам необходимо подтвердить его получение. Подробнее про использование уведомлений
Основные события
Вы можете подписаться на уведомления о смене статусов платежей и возвратов:
СобытиеОписание
payment.waiting_for_captureплатеж перешел в статус waiting_for_capture
payment.succeededплатеж перешел в статус succeeded
payment.canceledплатеж перешел в статус canceled
refund.succeededвозврат перешел в статус succeeded
События Безопасной сделки
Если вы пользуетесь Безопасной сделкой, вам также доступны уведомления о смене статусов созданных сделок и выплат:
СобытиеОписание
deal.closedсделка перешла в статус closed
payout.canceledвыплата перешла в статус canceled
payout.succeededвыплата перешла в статус succeeded
Настройка
Если хотите получать уведомления от ЮKassa, нужно подписаться на них в личном кабинете. Для этого в разделе Интеграция — HTTP-уведомления укажите URL для уведомлений и события, которые хотите отслеживать.
Для партнеров
Если вы участвуете в партнерской программе ЮKassa, вам нужно подписываться на уведомления по API.
Вы можете подписаться только на основные события — подписаться на события Безопасной сделки не получится.
Для каждого события, которое вы хотите отслеживать, необходимо создать объект webhook . Для этого передайте в запросе  событие, на которое вы хотите подписаться, и URL для уведомлений.
Пример запроса на создание объекта webhook
cURL
PHP
Python
curl https://api.yookassa.ru/v3/webhooks \
  -X POST \
  -H 'Authorization: Bearer <oauth_token>' \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "event": "payment.succeeded",
        "url": "https://www.example.com/notification_url"
      }'
Пример тела ответа
JSON
{
  "id": "wh-e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "event": "payment.succeeded",
  "url": "https://www.example.com/notification_url"
}
Вы можете посмотреть список созданных webhook  и удалить  те, которые не нужны.
Использование
Как только произойдет событие, на которое вы подписались, на URL, который вы указали при настройке, придет уведомление.
Параметры тела уведомления
ПараметрТипОписание
typestring
Тип объекта. Фиксированное значение — notification (уведомление).
Обязательный параметр
eventstring
Событие, о котором уведомляет ЮKassa. Пример: payment.waiting_for_capture.
Обязательный параметр
objectstring
Объект, с которым произошло указанное событие. Например, если в параметре event указано событие payment.waiting_for_capture, то в object вернется объект платежа , статус которого изменился на waiting_for_capture.
Объект содержит данные, актуальные на тот момент, когда произошло событие. Параметры объектов описаны в Справочнике API .
Обязательный параметр
Пример тела уведомления payment.waiting_for_capture
JSON
{
  "type": "notification",
  "event": "payment.waiting_for_capture",
  "object": {
    "id": "22d6d597-000f-5000-9000-145f6df21d6f",
    "status": "waiting_for_capture",
    "paid": true,
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    },
    "authorization_details": {
      "rrn": "10000000000",
      "auth_code": "000000",
      "three_d_secure": {
        "applied": true
      }
    },
    "created_at": "2018-07-10T14:27:54.691Z",
    "description": "Заказ №72",
    "expires_at": "2018-07-17T14:28:32.484Z",
    "metadata": {},
    "payment_method": {
      "type": "bank_card",
      "id": "22d6d597-000f-5000-9000-145f6df21d6f",
      "saved": false,
      "card": {
        "first6": "555555",
        "last4": "4444",
        "expiry_month": "07",
        "expiry_year": "2021",
        "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
      },
      "title": "Bank card *4444"
    },
    "refundable": false,
    "test": false
  }
}
Вам нужно подтвердить, что вы получили уведомление. Для этого ответьте кодом состояния HTTP 200. ЮKassa проигнорирует всё, что будет находиться в теле или заголовках ответа. Ответы с любыми другими кодами состояний HTTP будут считаться невалидными, и ЮKassa продолжит доставлять уведомление в течение 24 часов, начиная с момента, когда событие произошло.
Проверка подлинности уведомлений
Когда получите уведомление, проверьте его подлинность, например по статусу объекта или по IP-адресу. Это поможет защититься от атак, основанных на поддельных уведомлениях.
Проверка статуса объекта
Проверьте текущий статус объекта, чтобы убедиться, что статус из уведомления актуален.
Проверка IP-адреса
Проверьте IP-адрес, с которого пришло уведомление. ЮKassa может присылать уведомления с любого 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
Обработка с помощью SDK
Вы можете обрабатывать уведомления с помощью наших серверных SDK:
  1. Получите данные из POST-запроса от ЮKassa.
  2. Создайте объект класса уведомлений в зависимости от события.
  3. Получите объект платежа.
Пример обработки уведомления с помощью SDK
PHP
Python
// Получите данные из POST-запроса от ЮKassa

<?php
    $source = file_get_contents('php://input');
    $requestBody = json_decode($source, true);
?>

// Создайте объект класса уведомлений в зависимости от события
// NotificationSucceeded, NotificationWaitingForCapture,
// NotificationCanceled,  NotificationRefundSucceeded

<?php
    use YooKassa\Model\Notification\NotificationSucceeded;
    use YooKassa\Model\Notification\NotificationWaitingForCapture;
    use YooKassa\Model\NotificationEventType;

    try {
      $notification = ($requestBody['event'] === NotificationEventType::PAYMENT_SUCCEEDED)
        ? new NotificationSucceeded($requestBody)
        : new NotificationWaitingForCapture($requestBody);
    } catch (Exception $e) {
        // Обработка ошибок при неверных данных
    }
?>

// Получите объект платежа

<?php
    $payment = $notification->getObject();
?>
Обработка событий виджета ЮKassa
У виджета ЮKassa есть собственные события, о которых он может информировать. Вы можете обрабатывать эти события для взаимодействия с пользователем после оплаты и во всплывающем окне с платежной формой.
Что почитать еще
Получение информации о платежеИспользование SDKЖизненный цикл платежа