Перейти к содержанию

Уведомления

Общие сведения

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

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

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

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

При получении и обработке уведомления сервер партнёра должен вернуть HTTP-код в диапазоне от 200 до 299. Если сервер вернет код, не входящий в этот диапазон, BaaS будет повторять попытку отправить уведомление в течение определённого времени.

Уведомления могут приходить о состоянии как финансовой, так и нефинансовой операции. Пример успешного сценария получения уведомления изображён на диаграмме ниже. Запрос описан в документации History&Notifications API.

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

Любая операция, о состоянии которой поступило уведомление, может быть совершена:

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

{
  "type": "PAYMENT",
  "txnId": "46829337545338664347",
  "txnType": "payment",
  "fromClientId": "jloungozcz2298040076",
  "toProviderId": "uid30",
  "toProviderData": {
    "fields": {
        "account": "3788673608"
    }
  },
  "transactionAmount": {
    "value": 2.9,
    "currency": "RUB"
  },
  "clientCommission": {
    "value": 100.0,
    "currency": "RUB"
  },
  "status": "SUCCESS",
  "statusDetails": {},
  "creationDateTime": "2020-09-24T10:42:18+03:00"
}

{
  "type": "AUTHORIZATION",
  "eventDateTime": "2020-08-12T13:14:23.706284+03:00",
  "txnId": "1436d6fb-17ac-6836-3252-779b702cca11",
  "txnType": "PURCHASE_E_POS",
  "actionId": "879e12ca-476a-4726-a5fb-e3c4546e47f1",
  "actionType": "HOLD",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100074268301",
    "clientId": "1",
    "transactionAmount": {
      "currency": "RUB",
      "value": "7.28"
    },
    "clientCommission": {
      "currency": "RUB",
      "value": "0.00"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "3.08"
    },
    "retrievalReferenceNumber": "008141362354",
    "merchantId": "498750000011107",
    "merchantType": "5499",
    "terminalId": "99999999",
    "acquirerId": "498750",
    "correlationId": "879e12ca-476a-4726-a5fb-e3c4546e47f1",
    "authorizationDateTime": "2020-08-12T13:14:16+03:00",
    "cardAcceptorNameAndLocation": "MIKROMARKET>MOSCOW"
  }
}

URL-адрес получения уведомлений задаётся для определённого productId. Использование нескольких адресов в рамках одного productId недоступно.

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

Финансовые операции

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

Операции из авторизованной зоны

Описание авторизованной зоны см. в статье «Термины и бизнес-сущности». Финансовая операция из такой зоны является операцией домена PAYMENTS.

Тело уведомления о состоянии финансовой операции из авторизованной зоны содержит:

  • обязательные параметры — присутствуют для любого типа уведомления;
  • опциональные параметры — присутствуют для конкретного типа уведомления.
Пример тела уведомления
  {
     //Обязательные параметры
     "type": "XXX",
     "txnId": "46829337545338664347",
     "txnType": "xxx",
     "transactionAmount": {
       "value": 2.9,
       "currency": "RUB"
     },
     "clientCommission": {
       "value": 100.0,
       "currency": "RUB"
     },
     "status": "SUCCESS",
     "statusDetails": {},
     "creationDateTime": "2020-09-24T10:42:18+03:00",
     //Опциональные параметры
     "fromClientId": "jloungozcz2298040076"
   }

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

{
  //Обязательные параметры любого уведомления о финансовой операции из авторизованной зоны
  "type": "REPLENISHMENT_BY_WEBFORM",
  "txnId": "56927813128178660527",
  "txnType": "replenishment-by-webform",
  "transactionAmount": {
    "value": 2.9,
    "currency": "RUB"
  },
  "clientCommission": {
    "value": 100.0,
    "currency": "RUB"
  },
  "status": "SUCCESS",
  "statusDetails": {},
  "creationDateTime": "2020-09-24T10:42:18+03:00",
  //Опциональные параметры (параметры для уведомления типа "REPLENISHMENT_BY_WEBFORM")
  "toClientId": "mismihtmdb6639011557"
}

{
  //Обязательные параметры любого уведомления о финансовой операции из авторизованной зоны
  "type": "WITHDRAWAL_TO_CARD",
  "txnId": "46829337545338664347",
  "txnType": "withdrawal-to-card",
  "transactionAmount": {
    "value": 2.9,
    "currency": "RUB"
  },
  "clientCommission": {
    "value": 100.0,
    "currency": "RUB"
  },
  "status": "SUCCESS",
  "statusDetails": {},
  "creationDateTime": "2020-09-24T10:42:18+03:00",
  //Опциональные параметры (параметры для уведомления типа "WITHDRAWAL_TO_CARD")
  "fromClientId": "jloungozcz2298040076"
}

Уведомления формируются для определённого типа операции (пополнения с карты, перевода на карту и т.д.) и отправляются при присвоении операции одного из задокументированных статусов. Пример уведомления об успешно выполненном переводе суммой в 100 руб. на банковскую карту со счёта клиента client1 размещён ниже.

Пример тела уведомления
{
      "type": "WITHDRAWAL_TO_CARD", // уведомление о переводе на банковскую карту
      "txnId": "46829337545338664347",
      "txnType": "withdrawal-to-card", // тип операции — перевод на банковскую карту
      "transactionAmount": { // сумма, с которой совершена операция
        "value": 100,
        "currency": "RUB"
      },
      "clientCommission": {
        "value": 2.9,
        "currency": "RUB"
      },
      "status": "SUCCESS", // статус операции — финальный успешный
      "statusDetails": {},
      "creationDateTime": "2020-09-24T10:42:18+03:00",
      "fromClientId": "client1" // клиент, со счётом которого совершена операция
    }

Типы уведомлений, описание и примеры их содержимого см. в документации History&Notifications API.

Обратите внимание

Уведомления не приходят в случае синхронного варианта проведения платежа. Подробности см. в статье «Общие принципы и правила» → «Решение об успешности платежа».

Операции из неавторизованной зоны

Описание неавторизованной зоны см. в статье «Термины и бизнес-сущности». Финансовая операция из такой зоны является операцией домена CARDS. Процесс проведения операций домена CARDS описан в данной статье.

Уведомление о состоянии финансовой операции из неавторизованной зоны может относиться к одному из типов:

Тело уведомления о состоянии финансовой операции из неавторизованной зоны содержит:

  • обязательные параметры — присутствуют для любого типа уведомления;
  • опциональные параметры — присутствуют для конкретного типа уведомления.
Пример тела уведомления
  {
    //Обязательные параметры
    "type": "XXX",
    "eventDateTime": "2021-06-08T18:06:38.84364+03:00",
    "txnId": "edf9e5db-3fa1-4730-8259-4ac04ac2d2bd",
    "txnType": "XXX",
    "actionId": "ccc0859a-e714-4650-b55e-ac46aad8a904",
    "actionType": "XXX",
    "actionStatus": "SUCCESS",
    "actionStatusDetails": {},
    "actionData": {
      "cardTokenId": "100078557896",
      "clientId": "fauqjsjdof5724234527",
      "transactionAmount": {
        "currency": "RUB",
        "value": "3.08"
      },
      "originTransactionAmount": {
        "currency": "RUB",
        "value": "3.08"
      },
      "merchantId": "SBOL",
      "merchantType": "4829",
      "terminalId": "99999999",
      "acquirerId": "402333",
      //Опциональные параметры
      "correlationId": "ccc0859a-e714-4650-b55e-ac46aad8a904",
      "retrievalReferenceNumber": "005613823345",
      "authorizationDateTime": "2021-06-08T18:06:29+03:00",
      "cardAcceptorNameAndLocation": "VISAMONEYTRANSFER>VisaDirectLU",
      "clientCommission": {
        "currency": "RUB",
        "value": "0.00"
      }
    }
  }

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

{
  //Обязательные параметры любого уведомления о финансовой операции из неавторизованной зоны
  "type": "AUTHORIZATION",
  "eventDateTime": "2021-06-08T18:06:38.84364+03:00",
  "txnId": "edf9e5db-3fa1-4730-8259-4ac04ac2d2bd",
  "txnType": "FAST_FUNDS",
  "actionId": "ccc0859a-e714-4650-b55e-ac46aad8a904",
  "actionType": "FAST_FUNDS",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100078557896",
    "clientId": "fauqjsjdof5724234527",
    "transactionAmount": {
      "currency": "RUB",
      "value": "3.08"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "3.08"
    },
    "merchantId": "SBOL",
    "merchantType": "4829",
    "terminalId": "99999999",
    "acquirerId": "402333",
    //Опциональные параметры (параметры для уведомления типа "AUTHORIZATION")
    "correlationId": "ccc0859a-e714-4650-b55e-ac46aad8a904",
    "retrievalReferenceNumber": "005613823345",
    "authorizationDateTime": "2021-06-08T18:06:29+03:00",
    "cardAcceptorNameAndLocation": "VISAMONEYTRANSFER>VisaDirectLU",
    "clientCommission": {
      "currency": "RUB",
      "value": "0.00"
    },
  }
}

{
  //Обязательные параметры любого уведомления о финансовой операции из неавторизованной зоны
  "type": "CLEARING",
  "eventDateTime": "2021-06-08T18:53:00.765517+03:00",
  "txnId": "6e652168-7bf5-4b0f-a3c8-9976e2a653d7",
  "txnType": "FAST_FUNDS",
  "actionId": "0a40efa1-9862-438b-9d56-c38222f182fe",
  "actionType": "CAPTURE_FAST_FUNDS",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100078560498",
    "clientId": "egfbiaclzz1241737707",
    "transactionAmount": {
      "currency": "RUB",
      "value": "3.29"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "3.29"
    },
    "merchantId": "351771137636",
    "merchantType": "1553",
    "terminalId": "83872934",
    "acquirerId": "295503",
    //Опциональные параметры (параметры для уведомления типа "CLEARING")
    "clearingDate": "2021-06-08",
    "merchantName": "TEST_MERCHANT_NAME",
    "wasNotAuthorizedBefore": true
  }
}

Параметры уведомления типа AUTHORIZATION можно условно разделить на две группы:

  • постоянные — всегда присутствуют в уведомлении типа AUTHORIZATION.
  • дополнительные — могут присутствовать для конкретного типа операции (выдача займа, снятие наличных и др.).

Сходство и отличие уведомлений типа AUTHORIZATION можно увидеть ниже на примере двух разных типов операций.

{
  //Постоянные параметры для типа AUTHORIZATION
  "type": "AUTHORIZATION",
  "eventDateTime": "2021-08-04T16: 30: 49.781279+03: 00",
  "txnId": "9c9f3877-97b6-4265-b1f0-57c69036dc93",
  "txnType": "CASH_WITHDRAWAL_ATM",
  "actionId": "2f5062bd-bd2f-4988-9f85-dfa15bb891f6",
  "actionType": "CASH_WITHDRAWAL_HOLD",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100079222878",
    "clientId": "gvmbgpkrxu7686940477",
    "transactionAmount": {
      "currency": "RUB",
      "value": "8.56"
    },
    "clientCommission": {
      "currency": "RUB",
      "value": "0.00"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "8.56"
    },
    "authorizationDateTime": "2021-08-04T16: 30: 39+03: 00",
    "retrievalReferenceNumber": "009966696813",
    "merchantId": "VB24",
    "cardAcceptorNameAndLocation": "VB24>SANKT-PETERBURU",
    "merchantType": "6011",
    "terminalId": "99999999",
    "acquirerId": "471461",
    "correlationId": "2f5062bd-bd2f-4988-9f85-dfa15bb891f6",
    //Дополнительные параметры (параметры для типа операции "CASH_WITHDRAWAL_ATM")
    "accountBalance": {
      "currency": "RUB",
      "value": "3.52"
    },
  }
}

{
  //Постоянные параметры для типа AUTHORIZATION
  "type": "AUTHORIZATION",
  "eventDateTime": "2021-06-08T18:06:38.84364+03:00",
  "txnId": "edf9e5db-3fa1-4730-8259-4ac04ac2d2bd",
  "txnType": "LOAN_ISSUE",
  "actionId": "ccc0859a-e714-4650-b55e-ac46aad8a904",
  "actionType": "LOAN_ISSUE",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100078557896",
    "clientId": "fauqjsjdof5724234527",
    "transactionAmount": {
      "currency": "RUB",
      "value": "20000.00"
    },
    "clientCommission": {
      "currency": "RUB",
      "value": "0.00"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "20000.00"
    },
    "merchantId": "SBOL",
    "merchantType": "4829",
    "terminalId": "99999999",
    "acquirerId": "402333",
    "correlationId": "ccc0859a-e714-4650-b55e-ac46aad8a904",
    "retrievalReferenceNumber": "005613823345",
    "authorizationDateTime": "2021-06-08T18:06:29+03:00",
    "cardAcceptorNameAndLocation": "VISAMONEYTRANSFER>VisaDirectLU",
    //Дополнительные параметры (параметры для типа операции "LOAN_ISSUE")
    "accountBalance": {
      "currency": "RUB",
      "value": "0.0"
    },
    "partnerTxnId":"7498c5e4-9b7b-4ccf-a345-240164acb1"
  }
}

Для одного и того же типа операции (например, для пополнения с банковской карты) может быть сформировано как уведомление типа AUTHORIZATION, так уведомление типа CLEARING. Это связано с особенностями процесса проведения операции. Подробности см. в статье «Общие принципы и правила» → «Проведение операций домена CARDS».

Уведомление отправляется после совершения какого-либо действия, в результате которого произошло движение денежных средств: холдирования (резервирования), списания и т.д. Действие может быть успешно или неуспешно выполненным. Пример уведомления об успешном холдировании 2500 руб. на счёте клиента client1 в рамках авторизации покупки в интернете размещён ниже.

Пример тела уведомления
{
  "type": "AUTHORIZATION", // уведомление об авторизации операции
  "eventDateTime": "2020-08-12T13:14:23.706284+03:00",
  "txnId": "1436d6fb-17ac-6836-3252-779b702cca11",
  "txnType": "PURCHASE_E_POS", // тип операции — покупка в интернете
  "actionId": "879e12ca-476a-4726-a5fb-e3c4546e47f1",
  "actionType": "HOLD", // тип действия — холдирование средств
  "actionStatus": "SUCCESS", // статус действия — финальный успешный
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100074268301",
    "clientId": "1", // клиент, со счётом которого совершено действие
    "transactionAmount": { // сумма, с которой совершено действие
      "currency": "RUB",
      "value": "2500"
    },
    "authorizationDateTime": "2020-08-12T13:14:16+03:00",
    "retrievalReferenceNumber": "008141362354",
    "merchantId": "498750000011107",
    "cardAcceptorNameAndLocation": "MIKROMARKET>MOSCOW",
    "merchantType": "5499",
    "terminalId": "99999999",
    "acquirerId": "498750",
    "correlationId": "879e12ca-476a-4726-a5fb-e3c4546e47f1"
  }
}

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

Нефинансовые операции

Нефинансовыми являются операции, которые не приводят к движению денежных средств. Примеры нефинансовых операций — блокировка карты, запрос баланса в банкомате.

Операции из авторизованной зоны

Описание авторизованной зоны см. в статье «Термины и бизнес-сущности». Примерами нефинансовых операций, которые совершаются из авторизованной зоны, являются блокировка карты и изменение уровня идентификации клиента.

Набор параметров в уведомлении о состоянии нефинансовой операции из авторизованной зоны (1) отличается от набора параметров в уведомлении:

Отличие можно увидеть на примере ниже.

{
  "type":"CARD_WAS_BLOCKED",
  "clientId":"1",
  "cardTokenId":"100074269512",
  "blockSource":"PARTNER_API",
  "blockedAt":"2020-08-24T18:22:34.974+03:00"
}

{
  "type": "AUTHORIZATION",
  "eventDateTime": "2021-09-20T14:33:13.088799+03:00",
  "txnId": "4e2b3c60-0eac-4cf6-9619-20550e544616",
  "txnType": "BALANCE_INQUIRY",
  "actionId": "b026c332-ebcf-40dc-a2ae-97329f4e3624",
  "actionType": "BALANCE_INQUIRY",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100079219025",
    "clientId": "vgkmnvzrac5063019183",
    "transactionAmount": {
      "currency": "RUB",
      "value": "0.00"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "0.00"
    },
    "authorizationDateTime": "2021-09-20T14:33:12+03:00",
    "retrievalReferenceNumber": "003174424677",
    "merchantId": "VB24           ",
    "cardAcceptorNameAndLocation": "VB24           >SANKT-PETERBU         RU",
    "merchantType": "6011",
    "terminalId": "99999999",
    "acquirerId": "471461",
    "correlationId": "d5e30bbb-4e70-4410-81e2-e093e2910287",
    "accountBalance": {
      "currency": "RUB",
      "value": "1.42"
    }
  }
}

{
  "type": "REPLENISHMENT_BY_WEBFORM",
  "txnId": "56927813128178660527",
  "txnType": "replenishment-by-webform",
  "transactionAmount": {
    "value": 2.9,
    "currency": "RUB"
  },
  "clientCommission": {
    "value": 100.0,
    "currency": "RUB"
  },
  "status": "SUCCESS",
  "statusDetails": {},
  "creationDateTime": "2020-09-24T10:42:18+03:00",
  "toClientId": "mismihtmdb6639011557"
}

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

Операции из неавторизованной зоны

Описание неавторизованной зоны см. в статье «Термины и бизнес-сущности». Примером нефинансовой операции, совершаемой из неавторизованной зоны, является запрос баланса в банкомате (т.к. у QIWI нет собственных банкоматов).

Уведомление о состоянии нефинансовой операции из неавторизованной зоны может быть только одного типа — AUTHORIZATION (см. описание онлайн-операции). Параметры такого уведомления можно условно разделить на две группы:

  • постоянные — присутствуют в уведомлении типа AUTHORIZATION независимо от вида операции (финансовая/нефинансовая);
  • дополнительные — могут присутствовать для конкретного типа операции (запрос баланса в банкомате и др.).

Сходство и отличие уведомлений типа AUTHORIZATION можно увидеть на примере ниже.

{
  //Обязательные для типа AUTHORIZATION параметры
  "type": "AUTHORIZATION",
  "eventDateTime": "2021-06-08T18:06:38.84364+03:00",
  "txnId": "edf9e5db-3fa1-4730-8259-4ac04ac2d2bd",
  "txnType": "FAST_FUNDS",
  "actionId": "ccc0859a-e714-4650-b55e-ac46aad8a904",
  "actionType": "FAST_FUNDS",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100078557896",
    "clientId": "fauqjsjdof5724234527",
    "transactionAmount": {
      "currency": "RUB",
      "value": "3.08"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "3.08"
    },
    "merchantId": "SBOL",
    "merchantType": "4829",
    "terminalId": "99999999",
    "acquirerId": "402333",
    "correlationId": "ccc0859a-e714-4650-b55e-ac46aad8a904",
    "retrievalReferenceNumber": "005613823345",
    "authorizationDateTime": "2021-06-08T18:06:29+03:00",
    "cardAcceptorNameAndLocation": "VISAMONEYTRANSFER>VisaDirectLU"
  }
}

{
  //Обязательные параметры
  "type": "AUTHORIZATION",
  "eventDateTime": "2021-09-20T14:33:13.088799+03:00",
  "txnId": "4e2b3c60-0eac-4cf6-9619-20550e544616",
  "txnType": "BALANCE_INQUIRY",
  "actionId": "b026c332-ebcf-40dc-a2ae-97329f4e3624",
  "actionType": "BALANCE_INQUIRY",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100079219025",
    "clientId": "vgkmnvzrac5063019183",
    "transactionAmount": {
      "currency": "RUB",
      "value": "0.00"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "0.00"
    },
    "authorizationDateTime": "2021-09-20T14:33:12+03:00",
    "retrievalReferenceNumber": "003174424677",
    "merchantId": "VB24           ",
    "cardAcceptorNameAndLocation": "VB24           >SANKT-PETERBU         RU",
    "merchantType": "6011",
    "terminalId": "99999999",
    "acquirerId": "471461",
    "correlationId": "d5e30bbb-4e70-4410-81e2-e093e2910287",
    //Опциональные параметры
    "accountBalance": {
      "currency": "RUB",
      "value": "1.42"
    }
  }
}

Тестирование

Общие правила тестирования описаны в статье BaaS → «Тестирование». Здесь мы расскажем об особенностях тестирования сценариев получения уведомлений.

Особенности

Для проверки получения уведомлений в тестовом контуре предоставьте вашему курирующему менеджеру URL-адрес, на который они должны отправляться.

Операции из неавторизованной зоны, относящиеся к домену CARDS, не могут быть совершены в тестовой среде. Чтобы протестировать получение уведомлений по операциям из неавторизованной зоны, направьте запрос представителям BaaS. Канал общения определяется для каждого партнёра индивидуально.

Документация
Разработчикам
Обратная связь
  • © 2023, КИВИ Банк (АО), лицензия ЦБ РФ № 2241
  • Россия, 117648, г. Москва, мкр. Чертаново Северное, д.1А, корп.1