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

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