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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Status

Поле	Описание	Тип	Обязательный
`value`	Строковое значение статуса	`string`	Да
`changedDateTime`	Дата обновления статуса. Строка, формат: ГГГГ-ММ-ДДTЧЧ:ММ:ССZ	`string`	Да
`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`	Нет
`rrn`	RRN платежа (по ISO 8583).	`Number`	Нет
`authCode`	Auth-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ЧЧ:ММ:ССZ	`string`	Да
`status`	Информация о статусе операции	`Object`	Да
`amount`	Информация о сумме операции	`Object`	Да
`paymentMethod`	Информация о средстве платежа	`Object`	Да
`billId`	Идентификатор счета, соответствующего операции	`String`	Да
`flags`	Дополнительные команды, переданные в API. Массив из строк: SALE, BIND_PAYMENT_TOKEN.	`array of strings`	Да
`billId`	Идентификатор счета, соответствующей операции	`String`	Да

Status

Поле	Описание	Тип	Обязательный
`value`	Строковое значение статуса	`string`	Да
`changedDateTime`	Дата обновления статуса. Строка, формат: ГГГГ-ММ-ДДTЧЧ:ММ:ССZ	`string`	Да
`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`	Нет
`rrn`	RRN платежа (по ISO 8583).	`Number`	Нет
`authCode`	Auth-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ЧЧ:ММ:ССZ	`string`	Да
`status`	Информация о статусе операции	`Object`	Да
`amount`	Информация о сумме операции	`Object`	Да
`paymentMethod`	Информация о средстве платежа	`Object`	Да
`billId`	Идентификатор счета, соответствующего операции	`String`	Да
`flags`	Дополнительные команды, переданные в API. Массив из строк: SALE, BIND_PAYMENT_TOKEN.	`array of strings`	Да
`billId`	Идентификатор счета, соответствующей операции	`String`	Да

Status

Поле	Описание	Тип	Обязательный
`value`	Строковое значение статуса	`string`	Да
`changedDateTime`	Дата обновления статуса. Строка, формат: ГГГГ-ММ-ДДTЧЧ:ММ:ССZ	`string`	Да
`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`	Нет
`rrn`	RRN платежа (по ISO 8583).	`Number`	Нет
`authCode`	Auth-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"
      }
   }
}

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

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

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

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

> HEADERS​

Пример:​

Тело запроса​

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

> HEADERS​

Пример:​

Тело запроса​

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

> HEADERS​

Пример:​

Тело запроса​

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

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

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

> HEADERS

Пример:

Тело запроса

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

> HEADERS

Пример:

Тело запроса

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

> HEADERS

Пример:

Тело запроса