Если вы хотите отслеживать состояние объектов, например, платежей или возвратов, вы можете подписаться на уведомления (webhook, callback) о таких событиях.
Уведомления пригодятся в тех случаях, когда объект API изменяется без вашего участия. Например, если пользователю нужно подтвердить платеж, процесс оплаты может занять от нескольких минут до нескольких часов. Вместо того, чтобы всё это время периодически отправлять GET-запросы , чтобы узнать статус платежа, вы можете просто дожидаться уведомления от ЮKassa.
Событие в Ю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.
Если хотите получать уведомления от ЮKassa, нужно подписаться на них в личном кабинете. Для этого в разделе Интеграция — HTTP-уведомления укажите URL для уведомлений и события, которые хотите отслеживать.
URL для уведомлений должен начинаться с https — это значит, что ваш сайт защищен SSL-сертификатом.
Сертификат подойдет любой: самоподписанный или выданный центром сертификации. Версия TLS — 1.2 или выше.
Если вы участвуете в партнерской программе ЮKassa, вам нужно подписываться на уведомления по API.
Вы можете подписаться только на основные события — подписаться на события Безопасной сделки не получится.
Для каждого события, которое вы хотите отслеживать, необходимо создать объект webhook . Для этого передайте в запросе событие, на которое вы хотите подписаться, и URL для уведомлений.
Для каждого OAuth-токена нужно создавать свой набор webhook.
Пример запроса на создание объекта webhook
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" }'
Пример тела ответа
{ "id": "wh-e44e8088-bd73-43b1-959a-954f3a7d0c54", "event": "payment.succeeded", "url": "https://www.merchant-website.com/notification_url" }
Вы можете посмотреть список созданных webhook и удалить те, которые не нужны.
Уведомления будут приходить только для тех объектов, которые созданы вашим приложением.
Как только произойдет событие, на которое вы подписались, на URL, который вы указали при настройке, придет уведомление. В нем будут все данные об объекте на момент, когда произошло событие.
Пример тела уведомления payment.waiting_for_capture
{ "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-адрес, с которого пришло уведомление. Ю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:0:1509::/64
- 2a02:5180:0:2655::/64
- 2a02:5180:0:1533::/64
- 2a02:5180:0:2669::/64
Вы можете обрабатывать уведомления с помощью наших серверных SDK:
- Получите данные из POST-запроса от ЮKassa.
- Создайте объект класса уведомлений в зависимости от события.
- Получите объект платежа.
Пример обработки уведомления с помощью SDK
// Получите данные из 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 есть собственные события, о которых он может информировать. Вы можете обрабатывать эти события для взаимодействия с пользователем после оплаты и во всплывающем окне с платежной формой.
Есть вопросы или замечания по документации?
Можем созвониться и обсудить их лично: мы поможем вам разобраться, а вы нам — понять, что тут нужно улучшить.
Для этого оставьте свои контакты и выберите время.
Да, хочу обсудить