Входящие уведомления
Если вы хотите отслеживать состояние платежей и возвратов, вы можете подписаться на уведомления (webhook, callback).
Уведомления пригодятся в тех случаях, когда объект API изменяется без вашего участия. Например, если пользователю нужно подтвердить платеж, процесс оплаты может занять от нескольких минут до нескольких часов. Вместо того, чтобы всё это время периодически отправлять GET-запросы, чтобы узнать статус платежа, вы можете просто дожидаться уведомления от Яндекс.Кассы.
Доступные события
Сейчас Яндекс.Касса может уведомлять о таких событиях:
СобытиеОписание
payment.waiting_for_captureплатеж перешел в статус
waiting_for_capture
payment.succeededплатеж перешел в статус
succeeded
payment.canceledплатеж перешел в статус
canceled
refund.succeededвозврат перешел в статус
succeeded
Яндекс.Касса пришлет вам уведомление, как только платеж или возврат перейдет в нужный статус.
Подробнее о статусах платежа
Настройка
Если хотите получать уведомления от Яндекс.Кассы, нужно подписаться на них в личном кабинете. Для этого в настройках магазина, в разделе HTTP-уведомления, укажите URL для уведомлений и события, которые хотите отслеживать.
URL для уведомлений должен начинаться с https — это значит, что ваш сайт защищен SSL-сертификатом. Сертификат подойдет любой: самоподписанный или выданный центром сертификации.
Использование
Как только произойдет событие, на которое вы подписались, на 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"
      },
      "title": "Bank card *4444"
    },
    "test": false
  }
}
Вам нужно подтвердить, что вы получили уведомление. Для этого ответьте HTTP-кодом
200
. Яндекс.Касса проигнорирует всё, что будет находиться в теле или заголовках ответа. Ответы с любыми другими HTTP-кодами будут считаться невалидными, и Яндекс.Касса продолжит доставлять уведомление в течение 24 часов, начиная с момента, когда событие произошло.
Когда получите уведомление, проверьте текущий статус объекта (запросив информацию о нем GET-методом). Статус объекта должен совпадать со статусом из уведомления.
Кроме того, мы рекомендуем проверять 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:
  1. Получите данные из POST-запроса от Яндекс.Кассы.
  2. Cоздайте объект класса уведомлений в зависимости от события.
  3. Получите объект платежа.
Пример обработки уведомления с помощью SDK
PHP
Python
// Получите данные из POST-запроса от Яндекс.Кассы

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

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

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

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

<?php
  $payment = $notification->getObject();
?>
Что почитать еще
Получение информации о платежеИспользование SDKЖизненный цикл платежа