Skip to main content

Серверные уведомления


Уведомление от QIWI — входящий POST-запрос с информацией о событии. Тело запроса содержит JSON-сериализованные данные платежа/счета (кодировка UTF-8).

Уведомления отправляются с IP адреса 185.22.67.220

Протокол поддерживает следующие типы уведомлений о событиях API:

  • PAYMENT — отправляются при совершении операций платежа;
  • CAPTURE — отправляются при подтверждении платежа;
  • REFUND — отправляются при возврате платежа;

Не установлено единого порядка отправки уведомлений разного типа в ходе выполнения одной и той же операции. Порядок может отличаться для разных операций.

Адрес вашего сервера для обработки уведомлений указывается при настройке по заявке на подключения. При необходимости изменения, обратитесь в Службу поддержки.

URL для уведомлений должен начинаться с https, так как уведомления отправляются по протоколу HTTPS на порт 443. URL должен быть доступен из Интернета.

Сертификат сайта должен быть выпущен доверенным центром сертификации (например Comodo, Verisign, Thawte и т.п.).

Запрос статуса счёта

Если уведомление об операции не поступило вам в течение 10 минут после совершения операции, необходимо запросить статус операции запросом статуса счета.

Уведомление считается успешно доставленным, если ваш сервер ответил HTTP кодом состояния 200 OK. До этого момента система будет пытаться доставить уведомление через увеличивающиеся интервалы времени в течение суток с момента операции.

Если по какой-либо причине ваш сервер успешно обработал уведомление по транзакции, но не вернул 200 OK, то при повторной попытке доставки не нужно обрабатывать такую транзакцию как новую.

Авторизация уведомлений


В уведомлении присутствует цифровая подпись запроса, которую необходимо проверять на вашей стороне для исключения возможности подделки уведомления.

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

Цифровая подпись уведомления помещается в HTTP-заголовок Signature.

Для проверки подписи используется механизм проверки целостности HMAC с хэш-функцией SHA256 и ключом доступа к API.

Алгоритм проверки подписи:

  1. Объединить значения определенных параметров в одну строку с разделителем "|". Например: parameters = {payment.paymentId}|{payment.createdDateTime}|{payment.amount.value} Подпись считается для следующих полей уведомления:
    • тип PAYMENT: payment.paymentId|payment.createdDateTime|payment.amount.value
  2. Вычислить HMAC-хэш c алгоритмом хэширования SHA256: hash = HMAС(SHA256, secret, parameters) Где:
    • secret — ключ хеширования (UTF-8). Совпадает с ключом доступа к API.
    • parameters — строка из п.1.
  3. Сравнить значение подписи из HTTP-заголовка Signature уведомления с результатом п.2.

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


Сервис отправки уведомлений распределяет неуспешные уведомления по очередям:

  • попытки отправок до 3 часов частотой 1 минута
  • попытки отправок от 3 часов до 12 часов частатой 15 минут
  • попытки отправок от 12 часов до сутки частатой 30 минут

Время повторной отправки может сдвигаться в большую сторону.

Формат уведомления PAYMENT


> HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

Request Body

ПолеОписаниеТипОбязательный
typeТип операции (только PAYMENT)stringДа
paymentОписание платежаObjectДа

Payment

ПолеОписаниеТипОбязательный
paymentIdID платежаstringДа
createdDateTimeДата создания операции. Строка, формат: ГГГГ-ММ-ДДTЧЧ:ММ:ССZstringДа
statusИнформация о статусе операцииObjectДа
amountИнформация о сумме операцииObjectДа
paymentMethodИнформация о средстве платежаObjectДа
billIdИдентификатор счета, соответствующей операцииStringДа
flagsДополнительные команды, переданные в API. Массив из строк: SALE, BIND_PAYMENT_TOKEN.array of stringsДа
tokenDataОбъект с информацией о выпущенном платежном токенеObjectНет

Status

ПолеОписаниеТипОбязательный
valueСтроковое значение статусаstringДа
changedDateTimeДата обновления статуса. Строка, формат: ГГГГ-ММ-ДДTЧЧ:ММ:ССZstringДа
reasonCodeКод причины отклоненияstringНет
reasonMessageОписание причины отклоненияstringНет
Amount
ПолеОписаниеТипОбязательный
valueСумма операции, округленная до двух десятичных знаков в меньшую сторонуnumber(6,2)Да
currencyИдентификатор валюты операции (Alpha-3 ISO 4217 код)string[3]Да
PaymentMethod
ПолеОписаниеТипОбязательный
typeТип метода оплаты: CARD — банковская карта, TOKEN — платежный токен, QIWI_WALLET — баланс QIWI КошелькаstringДа
paymentTokenПлатежный токен карты.stringНет
maskedPanМаскированный PAN карты.stringНет
rrnRRN платежа (по ISO 8583).NumberНет
authCodeAuth-code платежа.NumberНет
TokenData
ПолеОписаниеТипОбязательный
paymentTokenПлатежный токен карты.stringДа

Пример:

Signature: XXX

Тело запроса

{
"type": "PAYMENT",
"payment": {
"paymentId": "123213",
"createdDateTime": "2022-12-12 10:10:19",
"status": {
"value": "SUCCESS",
"changedDateTime":"2022-12-12 10:13:35"
},
"amount": {
"value": 200.00,
"currency": "KZT"
},
"paymentMethod": {
"type": "CARD",
"maskedPan": "440043******4583",
"rrn": 3456042506
},
"billId": "43432dfsf",
"flags": ["SALE"],
"tokenData": {
"paymentToken": "b9a4fab1-d4f8-4045-84d1-391fa994cde9"
}
}
}

Формат уведомления CAPTURE


> HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

Request Body

ПолеОписаниеТипОбязательный
typeТип операции (только CAPTURE)stringДа
captureОписание платежаObjectДа

Capture

ПолеОписаниеТипОбязательный
captureIdУникальный идентификатор подтверждения в системе.stringДа
createdDateTimeДата создания операции. Строка, формат: ГГГГ-ММ-ДДTЧЧ:ММ:ССZstringДа
statusИнформация о статусе операцииObjectДа
amountИнформация о сумме операцииObjectДа
paymentMethodИнформация о средстве платежаObjectДа
billIdИдентификатор счета, соответствующего операцииStringДа
flagsДополнительные команды, переданные в API. Массив из строк: SALE, BIND_PAYMENT_TOKEN.array of stringsДа
billIdИдентификатор счета, соответствующей операцииStringДа
Status
ПолеОписаниеТипОбязательный
valueСтроковое значение статусаstringДа
changedDateTimeДата обновления статуса. Строка, формат: ГГГГ-ММ-ДДTЧЧ:ММ:ССZstringДа
reasonCodeКод причины отклоненияstringНет
reasonMessageОписание причины отклоненияstringНет
Amount
ПолеОписаниеТипОбязательный
valueСумма операции, округленная до двух десятичных знаков в меньшую сторонуnumber(6,2)Да
currencyИдентификатор валюты операции (Alpha-3 ISO 4217 код)string[3]Да
PaymentMethod
ПолеОписаниеТипОбязательный
typeТип метода оплаты: CARD — банковская карта, TOKEN — платежный токен, QIWI_WALLET — баланс QIWI КошелькаstringДа
paymentTokenПлатежный токен карты.stringНет
maskedPanМаскированный PAN карты.stringНет
rrnRRN платежа (по ISO 8583).NumberНет
authCodeAuth-code платежа.NumberНет

Пример:

Signature: XXX

Тело запроса

{
"type": "CAPTURE",
"capture": {
"captureId": "4352",
"createdDateTime": "2022-12-12 10:10:23",
"status": {
"value": "SUCCESS",
"changedDateTime":"2022-12-12 10:11:35"
},
"amount": {
"value": 200.00,
"currency": "KZT"
},
"paymentMethod": {
"type": "CARD",
"maskedPan": "440043******4583",
"rrn": 3456042506
},
"billId": "43432dfsf",
"flags": ["SALE"],
"tokenData": {
"paymentToken": "b9a4fab1-d4f8-4045-84d1-391fa994cde9"
}
}
}

Формат уведомления REFUND


> HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

Request Body

ПолеОписаниеТипОбязательный
typeТип операции (только REFUND)stringДа
refundОписание платежаObjectДа

Refund

ПолеОписаниеТипОбязательный
refundIdУникальный идентификатор отмены/возврата в системе.stringДа
createdDateTimeДата создания операции. Строка, формат: ГГГГ-ММ-ДДTЧЧ:ММ:ССZstringДа
statusИнформация о статусе операцииObjectДа
amountИнформация о сумме операцииObjectДа
paymentMethodИнформация о средстве платежаObjectДа
billIdИдентификатор счета, соответствующего операцииStringДа
flagsДополнительные команды, переданные в API. Массив из строк: SALE, BIND_PAYMENT_TOKEN.array of stringsДа
billIdИдентификатор счета, соответствующей операцииStringДа
Status
ПолеОписаниеТипОбязательный
valueСтроковое значение статусаstringДа
changedDateTimeДата обновления статуса. Строка, формат: ГГГГ-ММ-ДДTЧЧ:ММ:ССZstringДа
reasonCodeКод причины отклоненияstringНет
reasonMessageОписание причины отклоненияstringНет
Amount
ПолеОписаниеТипОбязательный
valueСумма операции, округленная до двух десятичных знаков в меньшую сторонуnumber(6,2)Да
currencyИдентификатор валюты операции (Alpha-3 ISO 4217 код)string[3]Да
PaymentMethod
ПолеОписаниеТипОбязательный
typeТип метода оплаты: CARD — банковская карта, TOKEN — платежный токен, QIWI_WALLET — баланс QIWI КошелькаstringДа
paymentTokenПлатежный токен карты.stringНет
maskedPanМаскированный PAN карты.stringНет
rrnRRN платежа (по ISO 8583).NumberНет
authCodeAuth-code платежа.NumberНет

Пример:

Signature: XXX

Тело запроса

{
"type": "REFUND",
"refund": {
"refundId": "3412",
"createdDateTime": "2022-12-12 10:12:23",
"status": {
"value": "SUCCESS",
"changedDateTime":"2022-12-12 10:13:35"
},
"amount": {
"value": 200.00,
"currency": "KZT"
},
"paymentMethod": {
"type": "CARD",
"maskedPan": "440043******4583",
"rrn": 3456042506
},
"billId": "43432dfsf",
"flags": ["SALE"],
"tokenData": {
"paymentToken": "b9a4fab1-d4f8-4045-84d1-391fa994cde9"
}
}
}