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

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

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

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

Сейчас ЮKassa может уведомлять о таких событиях:

Событие	Описание
payment.waiting_for_capture	платеж перешел в статус waiting_for_capture
payment.succeeded	платеж перешел в статус succeeded
payment.canceled	платеж перешел в статус canceled
refund.succeeded	возврат перешел в статус succeeded

ЮKassa пришлет вам уведомление, как только платеж или возврат перейдет в нужный статус.

Подробнее о статусах платежа

Настройка

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

URL для уведомлений должен начинаться с https — это значит, что ваш сайт защищен SSL-сертификатом. Сертификат подойдет любой: самоподписанный или выданный центром сертификации. Версия TLS — 1.2 или выше.

Для партнеров

Если вы участвуете в партнерской программе ЮKassa, вам нужно подписываться на уведомления по 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.merchant-website.com/notification_url"
      }'

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

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

Вы можете посмотреть список созданных webhook и удалить те, которые не нужны.

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

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

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

Пример тела уведомления 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"
    },
    "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.154.128/25
2a02:5180:0:1509::/64
2a02:5180:0:2655::/64
2a02:5180:0:1533::/64
2a02:5180:0:2669::/64

Обработка с помощью 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();
?>

Что почитать еще

Получение информации о платеже Использование SDK Жизненный цикл платежа

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

Настройка

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

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

Обработка с помощью SDK