Уведомления¶

Чтобы партнёр мог отслеживать состояние операций, QIWI использует уведомления — HTTPS POST-запросы, отправляемые на URL-адрес партнёра.

Структура¶

Каждый запрос состоит из заголовков и тела.

Заголовок запроса Signature содержит цифровую подпись. Цифровая подпись используется для защиты от подмены запросов: по её значению можно понять, что уведомление поступило от QIWI, а не от мошенников.

Тело запроса содержит строковое представление JSON-объекта с данными уведомления (data). Набор данных зависит от типа операции, для которого сформировано уведомление.

Уведомления могут приходить о состоянии как финансовой, так и нефинансовой операции. Пример финансовой операции — подтверждение платежа, нефинансовой — выпуск платёжного токена.

Актуальный формат и описание параметров уведомлений см. в документации API приёма платежей.

Типы¶

Типы уведомлений, которые поддерживает QIWI, перечислены в таблице ниже.

Сценарий¶

Каждый раз при получении уведомления сервер партнёра должен:

• вычислить подпись;
• сравнить полученный результат со значением из Signature.

В случае расхождения уведомление следует игнорировать.

При получении и обработке уведомления сервер партнёра должен вернуть HTTP-код 200 OK. До этого момента QIWI будет повторять попытку отправить уведомление в течение определённого времени.

Пример успешного сценария получения уведомления изображён на диаграмме ниже.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":14,
        "actorMargin":90 }}}%%
sequenceDiagram
    participant B as QIWI
    participant P as Партнёр
    Note left of B: Клиент оплатил товар или услугу
    B->>P: Уведомление о событии (Signature, data)
    P->>P: Вычисление подписи
    P->>P: Сравнение с Signature
    Note over P: Результат вычисления равен значению из Signature
    P->>B:  HTTP Status: 200 OK
    B->>B: Результат получения — успешный

Вычисление цифровой подписи¶

Для вычисления подписи необходимы строковые представления «секрета» (secret) и подписываемых данных, т.е. параметров тела уведомления (parameters).

Значение secret совпадает со значением ключа серверных уведомлений, указанным в разделе «Настройки» личного кабинета.

Подпись вычисляется для следующих параметров тела уведомления:

Алгоритм вычисления подписи

1. Приведите значения нужных параметров к строковому представлению (UTF-8) и объедините их в одну строку.

   Пример

   parameters = {payment.paymentId}|{payment.createdDateTime}|{payment.amount.value}

2. Вычислите хэш (HMAC), используя алгоритм SHA256: hash = HMAС(SHA256, secret, parameters).

Полученное в п.2 значение сравнивается со значением заголовка Signature в уведомлении.

URL-адрес¶

URL-адрес получения уведомлений задаётся для определённого siteId и указывается в личном кабинете в разделе «Настройки».

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

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

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

Уведомления, которые QIWI расценивает как неуспешно доставленные, распределяются по очередям для повторной отправки:

• 1 попытка с отложенным временем 5 секунд;
• 1 попытка с отложенным временем 1 минута;
• 3 попытки с отложенным временем по 5 минут.

Время повторной отправки может быть увеличено.

Пример уведомления¶

{
    "payment": {
      "type": "PAYMENT",
      //paymentId, необходимый для подтверждения платежа
      "paymentId": "824c7744-1650-4836-abaa-842ca7ca8a74",
      "createdDateTime": "2022-07-27T12:43:35+03:00",
      "merchantSiteUid": "test-00",
      "status": {
          "value": "SUCCESS",
          "changedDateTime": "2022-07-27T12:43:47+03:00"
      },
      "amount": {
          "value": 1.00,
          "currency": "RUB"
      },
      "paymentMethod": {
          "type": "CARD",
          "maskedPan": "512391******6871",
          "cardHolder": null,
          "cardExpireDate": "3/2030"
      },
      "tokenData": {
          "paymentToken": "cc123da5-2fdd-4685-912e-8671597948a3",
          "expiredDate": "2030-03-01T00:00:00+03:00"
      },
      "customFields": {
          "cf2": "dva",
          "cf1": "1",
          "cf4": "4",
          "cf3": "tri",
          "cf5": "5",
          "full_name": "full_name",
          "phone": "phone",
          "contract_id": "contract_id",
          "comment": "test",
          "booking_number": "booking_number"
      },
      "paymentCardInfo": {
          "issuingCountry": "643",
          "issuingBank": "Тинькофф банк",
          "paymentSystem": "MASTERCARD",
          "fundingSource": "UNKNOWN",
          "paymentSystemProduct": "TNW|TNW|Mastercard® New World—Immediate Debit|TNW|Mastercard New World-Immediate Debit"
      },
      "customer": {
          "email": "darta@mail.ru",
          "account": "11235813",
          "phone": "79850223243"
      },
      "gatewayData": {
          "type": "ACQUIRING",
          "eci": "2",
          "authCode": "0123342",
          "rrn": "001239598011"
      },
      "billId": "191616216126154",
      "flags": [
          "AFT"
      ]
    },
    "type": "PAYMENT",
    "version": "1"
}

{
    "payment": {
    "type": "PAYMENT",
    //paymentId, необходимый для подтверждения платежа
    "paymentId": "824c7744-1650-4836-abaa-842ca7ca8a74",
    "createdDateTime":"2020-11-28T12:58:49+03:00",
    "status":{
        "value":"SUCCESS",
        "changedDateTime":"2020-11-28T12:58:53+03:00"
    },
    "amount":{
      "value":100.00,
      "currency":"RUB"
    },
    "paymentMethod":{
      "type":"CARD",
      "maskedPan":"444444XXXXXX4444",
      "rrn":null,
      "authCode":null,
      "type":"CARD"
    },
    "merchantSiteUid":"test-00",
    "customer":{
      "phone":"75167693659"
    },
    "gatewayData":{
      "type":"ACQUIRING",
      "eci":"6",
      "authCode":"181218"
    },
    "billId":"autogenerated-a51d0d2c-6c50-405d-9305-bf1c13a5aecd",
    "flags":[]
  },
  "type":"PAYMENT",
  "version":"1"
}