Входящие уведомления
Если вы хотите отслеживать состояние объектов оплаты, вы можете подписаться на уведомления (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": "Подпись уведомления"
}