Уведомления

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

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

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

Настройка

Вы можете подписаться на уведомления в личном кабинете.

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

Укажите URL для уведомлений в разделе Интеграция — HTTP-уведомления или передайте webhook_url при создании платежа.

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

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

О событиях

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

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

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

• объект, с которым произошло событие: payment — платеж, refund — возврат, payout — выплата;
• статус, в который перешел объект, например confirmed или canceled.

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

Типы событий

Событие	Описание
Платежи
Успешный платёж	payment.confirmed
Отмена платежа	payment.canceled
Возвраты
Успешный возврат	refund.confirmed
Отмена возврата	refund.canceled
Выплаты
Успешная выплата	payout.done
Отмена выплаты	payout.canceled

Вам нужно подтвердить, что вы получили уведомление. Для этого ответьте кодом состояния HTTP 200. Всё, что будет находиться в теле или заголовках ответа, будет игнорироваться. Ответы с любыми другими кодами состояний HTTP будут считаться невалидными, и Pear продолжит доставлять уведомление в течение 24 часов, начиная с момента, когда событие произошло.

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

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

Пример уведомления payment.confirmed

JSON

{
  "type": "notification",
  "event": "payment.confirmed",
  "object": {
    "id": "02b150d3-6302-4358-9be5-b3606718791f",
    "shop_id": 33661,
    "paid": true,
    "order_id": "02b150d3-6302-4358-9be5-b3606718791f",
    "status": "CONFIRMED",
    "description": "Оплата заказа №123",
    "webhook_url": "https://example.com/callback"
    "amount": {
      "value": 1000.00,
      "currency": "RUB"
    },
    "confirmation": {
      "type": "redirect",
      "confirmation_url": "https://paypear.ru/SID382s",
      "return_url": "https://example.com/success"
    },
    "metadata": {},
    "created_at": "2025-02-27T15:55:05.600Z",
    "expires_at": "2025-02-27T19:55:05.600Z",
  },
  "signature": "f5e180a3ea7b6aa31173ac988efc3806f5e180a3ea7b6aa31173ac988efc3806"
}

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

Когда получите уведомление, проверьте его подлинность, например по IP-адресу или по подписи запроса. Это поможет защититься от атак, основанных на поддельных уведомлениях.

Проверка IP-адреса

Проверьте IP-адрес, с которого пришло уведомление. Pear может присылать уведомления с любого IP-адреса из списка:

• 158.160.85.101

Рекомендуется проверить ID магазина в теле уведомления, чтобы убедиться, что уведомление предназначалось для вашего магазина.

Проверка статуса объекта

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