Notifications
If you'd like to keep track of the status of objects (for example, of payments and refunds), you can subscribe to notifications (webhook, callback) about such events.
Notifications are useful for cases when the API object changes without your participation, for example, if the user needs to confirm the payment, the payment process might take from a few minutes to several hours. Instead of sending periodic GET requests for the duration of this period, you can just wait for a YooMoney notification to learn about the status.
События, которые вы можете отслеживать, зависят от используемого платежного решения. Способ настройки уведомлений зависит от метода аутентификации запросов.
Changes in the status of objects are considered events in YooMoney. Вы можете отслеживать события платежей, возвратов, выплат и сделок.
События, на которые можно подписаться, зависят от платежного решения, которое вы используете (например, обычные платежи, Безопасная сделка, Партнерская программа). Чтобы следить за событиями, подпишитесь на них.
As soon as an event you're subscribed to occurs, you receive a notification. Вам нужно подтвердить его получение. В уведомлении будут все данные об объекте на момент, когда его статус изменился. Подробнее об использовании уведомлений
Название события формируется по шаблону
<объект>.<статус>
и состоит из двух частей:- объект, с которым произошло событие:
payment
— платеж,refund
— возврат,payout
— выплата,deal
— сделка; - статус, в который перешел объект, например
succeeded
илиcanceled
. Подробнее о статусах для разных объектов смотрите в Справочнике API .
Пример:
payment.succeeded
— платеж перешел в статус succeeded
.Event | Payments | Payouts | Split payments, Partnership program | Safe deal |
---|---|---|---|---|
Платежи | ||||
payment.waiting_for_capture | ✅ | ❌ | ✅ | ✅ |
payment.succeeded | ✅ | ❌ | ✅ | ✅ |
payment.canceled | ✅ | ❌ | ✅ | ✅ |
Возвраты | ||||
refund.succeeded | ✅ | ❌ | ✅ | ✅ |
Выплаты | ||||
payout.succeeded | ❌ | ✅ | ❌ | ✅ |
payout.canceled | ❌ | ✅ | ❌ | ✅ |
Сделки | ||||
deal.closed | ❌ | ❌ | ❌ | ✅ |
В ЮKassa есть два способа настройки уведомлений в зависимости от метода аутентификации запросов:
- Если вы используете HTTP Basic Auth, настраивать уведомления нужно в личном кабинете.
- Если вы используете OAuth, настроить уведомления можно только по API.
If you want to receive notifications from YooMoney, subscribe to them in the Merchant Profile.
Specify the URL for notifications and events you want to track in the Integration — HTTP-notifications section.
Чтобы отписаться от уведомлений, в разделе Интеграция — HTTP-уведомления отключите ненужные события.
If you’re taking part in the YooMoney for Business partnership program, you’ll need to subscribe to notifications via API.
You can only subscribe to basic events, you can't subscribe to Safe deal events. Create a webhook object for every event you want to track by specifying the event you want to subscribe to as well as the URL for notifications in the request .
Notifications will only be sent for objects created by your app.
Example of request for creating webhook object
curl https://api.yookassa.ru/v3/webhooks \ -X POST \ -H 'Authorization: Bearer <oauth_token>' \ -H 'Idempotence-Key: <Idempotence Key>' \ -H 'Content-Type: application/json' \ -d '{ "event": "payment.succeeded", "url": "https://www.example.com/notification_url" }'
Example of the response body
{ "id": "wh-e44e8088-bd73-43b1-959a-954f3a7d0c54", "event": "payment.succeeded", "url": "https://www.example.com/notification_url" }
You can view the list of created webhooks and remoove the ones you don’t need.
Чтобы отписаться от уведомлений о событии для переданного OAuth-токена, удалите соответствующий объект webhook . Для этого передайте в запросе его идентификатор.
After an event you’re subscribed to occurs, a notification will be sent to the URL that you specified during configuration.
Notification body parameters
Parameter | Type | Description |
---|---|---|
type | string | Object type. Fixed value: notification .Required parameter |
event | string | Event that YooMoney notifies about. Example: payment.waiting_for_capture .Required parameter |
object | string | Object that was affected by the specified event. For example, if payment.waiting_for_capture is specified in the event parameter, the object parameter will contain the payment object whose status changed to waiting_for_capture .The object will contain all the details relevant at the time of the event. Object parameters are provided in the API Reference . Required parameter |
Example of the payment.waiting_for_capture notification body
{ "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": "Order No. 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 } }
You will need to confirm that you’ve received the notification. Reply with HTTP 200 code. YooMoney will ignore everything specified in the body or header of the response. Responses containing any other HTTP codes are considered invalid, and YooMoney will continue sending out the notification for the next 24 hours following the moment when the event occurred.
You can check the authenticity of a notification, for example, by the object status or IP address. This will help you defend yourself against attacks based on fake notifications.
Check the current status of the object to ensure that the status in the notification is up-to-date.
Check the IP address that the notification was sent from. YooMoney can send notifications from any of the following IP addresses:
- 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
You can process notifications using our server SDKs:
- Obtain data from a POST request made by YooMoney.
- Create a notification class object depending on the event.
- Obtain the Payment object.
Example of processing notifications using an SDK
// Obtain data from a POST request made by YooMoney <?php $source = file_get_contents('php://input'); $requestBody = json_decode($source, true); ?> // Create a notification class object depending on the event // 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) { // Processing errors } ?> // Obtain the Payment object <?php $payment = $notification->getObject(); ?>
The widget has its own events about which it can send notifications. You can handle these events to interact with the user after the payment is finished or after the pop-up window with the payment form gets closed.
See also