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

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

Структура¶

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

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

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

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

Описание уведомлений и примеры их содержимого см. в документации API приёма платежей.

Сценарий¶

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

• вычислить подпись;
• сравнить полученный результат со значением из 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"
}