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

Если вы хотите отслеживать состояние объектов оплаты, вы можете подписаться на уведомления (webhook, callback) о событиях. Уведомления пригодятся в тех случаях, когда объект API изменяется без вашего участия. Вместо того, чтобы всё это время периодически отправлять GET-запросы, чтобы узнать статус платежа, вы можете просто дожидаться уведомления от Сам.Эквайринг.

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

Событие в Сам.Эквайринг — изменение статуса объекта. Как только произойдет событие, на которое вы подписались, вам придет уведомление. В нём будут все данные об объекте на момент, когда его статус изменился.

На данный момент в Сам.Эквайринг реализованы следующие события:

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

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

Уведомления высылаются в виде POST-запроса на адрес, который был указан в параметрах магазина

Настройка

Если хотите получать уведомления от Сам.Эквайринг, нужно подписаться на них в личном кабинете. Для этого в разделе Параметры магазина укажите URL для уведомлений (Callback уведомления) и события, которые хотите отслеживать.

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

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

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

Входящее уведомление можно проверить с помощью поля signature.

Для формирования подписи уведомления используются параметры:

• order_id
• amount
• api_key — Секретный ключ из параметров магазина

Безопасность секретного ключа

Никому не сообщайте секретный ключ. Он не должен фигурировать в запросе, в Javascript или внутри HTML-страницы. Секретный ключ не должен быть виден в браузере магазина. Если есть подозрение, что секретный ключ скомпрометирован, тогда сгенерируйте новый ключ в личном кабинете.

От полученной строки вычисляется хэш по алгоритму SHA-256, это значение можно сравнить с полем signature.

Пример

order_id: 97e196c0-a344-4230-a028
amount: 400000
api_key: UxYjU5ZDMxOGU1ZmFjYzE3

Формируем sha256 от (97e196c0-a344-4230-a028400000UxYjU5ZDMxOGU1ZmFjYzE3)

В итоге получим (sha256): 
04c54b5ca7bb15adc693479b4c0d04d5eaa16c0f2d4cba2c99dc8e6333dd3214

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

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

- 178.205.169.35
- 81.23.144.157

Уточнение для PHP

Мы отправляем уведомление типа "Content-type: application/json; charset=utf-8"
В PHP ответ с таким типом не записывается в $_POST, для этого надо добавить 
строку указанную ниже:

$_POST = json_decode(file_get_contents('php://input'), true);

Пример входящего уведомления

{
    "order_id": "ID заказа",
    "status": "Статус",
    "amount": "Сумма (в копейках)",
    "currency": "Валюта",
    "created_at": "Время создания операции (Timestamp)",
    "finish_at": "Время завершения операции (Timestamp)",
    "info":[{
            "name": "Название товара",
            "quantity": "Количество товара",
            "amount": "Стоимость товара (в копейках)"
    }],
    "payment_method":{
        "type": "Тип платежного метода",
        "pan": "Номер банковской карты (маскированный)"
    },
    "signature": "Подпись уведомления"
}