Входящие уведомления

Если вы хотите отслеживать состояние объектов, например платежей или возвратов, вы можете подписаться на уведомления (webhook, callback) о таких событиях.

Уведомления пригодятся в тех случаях, когда объект API изменяется без вашего участия. Например, если пользователю нужно подтвердить платеж, процесс оплаты может занять от нескольких минут до нескольких часов. Вместо того, чтобы всё это время периодически отправлять GET-запросы , чтобы узнать статус платежа, вы можете просто дожидаться уведомления от ЮKassa.

События, которые вы можете отслеживать, зависят от используемого платежного решения. Способ настройки уведомлений зависит от метода аутентификации запросов.

О событиях в ЮKassa

Событие в ЮKassa — изменение статуса объекта. Вы можете отслеживать события платежей, возвратов, выплат и сделок.

События, на которые можно подписаться, зависят от платежного решения, которое вы используете (например, обычные платежи, Безопасная сделка, Партнерская программа). Чтобы следить за событиями, подпишитесь на них.

Как только произойдет событие, на которое вы подписались, вам придет уведомление. Вам нужно подтвердить его получение. В уведомлении будут все данные об объекте на момент, когда его статус изменился. Подробнее об использовании уведомлений

Название события формируется по шаблону <объект>.<статус> и состоит из двух частей:

объект, с которым произошло событие: payment — платеж, payment_method — способ оплаты, refund — возврат, payout — выплата, deal — сделка;
статус, в который перешел объект, например succeeded или canceled. Подробнее о статусах для разных объектов смотрите в Справочнике API .

Пример: payment.succeeded — платеж перешел в статус succeeded.

Доступные события

Событие	Платежи	Выплаты	Сплитование платежей, Партнерская программа	Безопасная сделка
Платежи
payment.waiting_for_capture	✅	❌	✅	✅
payment.succeeded	✅	❌	✅	✅
payment.canceled	✅	❌	✅	✅
Способы оплаты
payment_method.active	✅	✅	✅	✅
Возвраты
refund.succeeded	✅	❌	✅	✅
Выплаты
payout.succeeded	❌	✅	❌	✅
payout.canceled	❌	✅	❌	✅
Сделки
deal.closed	❌	❌	❌	✅

Настройка

В ЮKassa есть два способа настройки уведомлений в зависимости от метода аутентификации запросов:

Если вы используете HTTP Basic Auth, настраивать уведомления нужно в личном кабинете.
Если вы используете OAuth, настроить уведомления можно только по API.

Для платежных решений с HTTP Basic Auth

Если вы используете платежное решение с HTTP Basic Auth (обычные платежи, выплаты, Сплитование платежей, Безопасная сделка), вы можете подписаться на уведомления от ЮKassa в личном кабинете.

Для этого в разделе Интеграция — HTTP-уведомления укажите URL для уведомлений и события, которые хотите отслеживать.

Требования к URL для уведомлений — протокол HTTPS и TCP-порт 443 или 8443. TLS/SSL-сертификат подойдет любой: самоподписанный или выданный центром сертификации. Версия TLS/SSL — 1.2 или выше.

Чтобы отписаться от уведомлений, в разделе Интеграция — HTTP-уведомления отключите ненужные события.

Подписаться или отписаться от уведомления payment_method.active можно только через менеджера ЮKassa.

Для партнерской программы (OAuth)

Если вы участвуете в партнерской программе, вы можете подписаться на уведомления только по API.

Вы можете отслеживать только события платежей и возвратов. Для каждого события, которое вы хотите отслеживать, необходимо создать объект webhook . Для этого передайте в запросе событие, на которое вы хотите подписаться, и URL для уведомлений.

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

Для каждого OAuth-токена нужно создавать свой набор webhook.

Пример запроса на создание объекта 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"
}

С помощью API вы также можете просмотреть список отслеживаемых событий и отписаться от тех, которые не нужны.

Чтобы отписаться от уведомлений о событии для переданного OAuth-токена, удалите соответствующий объект webhook . Для этого передайте в запросе его идентификатор.

Использование

Как только произойдет событие, на которое вы подписались, на URL, который вы указали при настройке, придет уведомление.

Параметры тела уведомления

Параметр	Тип	Описание
type	string	Тип объекта. Фиксированное значение — `notification` (уведомление). Обязательный параметр
event	string	Событие, о котором уведомляет ЮKassa. Пример: `payment.waiting_for_capture`. Обязательный параметр
object	object	Объект, с которым произошло указанное событие. Например, если в параметре `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:

Получите данные из POST-запроса от ЮKassa.
Создайте объект класса уведомлений в зависимости от события.
Получите объект платежа.

Пример обработки уведомления с помощью 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

Жизненный цикл платежа

Проверка подлинности уведомлений