HISTORY&NOTIFICATIONS API

Последнее обновление: 28-02-2022 |

Интерфейс предназначен для получения истории операций и уведомлений о различных событиях.

Термины, используемые в тексте:

• пользовательский интерфейс — web-сайт или мобильное приложение;
• пользователь — клиент (физическое лицо), использующий интерфейс;
• партнер — юридическое лицо, использующее данный API с целью предоставить физическим лицам платежную функциональность в своем интерфейсе;
• провайдер — поставщик услуги.

Взаимодействие с сервером партнера происходит по защищенному сетевому протоколу (HTTPS).

Данные при запросах передаются в формате параметров HTTP-запроса в кодировке UTF-8. В ответ данные возвращаются в формате JSON.

Общая информация

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

Процессы проведения операций, инициированных из интерфейса, не принадлежащего партнеру, описаны на этой странице.

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

Процесс проведения операции покупки с использованием карты

• Платежная система отправляет онлайн-авторизацию на совершение покупки. При успешной онлайн-авторизации происходит операция HOLD денежных средств пользователя. При этом денежные средства все еще могут стать доступны пользователю: они лишь зарезервированы.
• Для успешной онлайн-авторизации на совершение покупки платежная система может отправить онлайн-авторизацию отмены: REVERSAL. В рамках исходной онлайн-авторизации на совершение покупки происходит операция UNHOLD денежных средств на сумму отмены.
• Платежная система инициирует клиринг по ранее созданной онлайн-авторизации на совершение покупки. В рамках исходной онлайн-авторизации на совершение покупки происходит списание денежных средств на сумму, указанную в клиринге: CAPTURE. Здесь CAPTURE рассматривается как оффлайн-операция.
• Платежная система инициирует клиринг для покупки, по которой ранее не было онлайн-авторизации. При этом связи у данной покупки с какой-либо онлайн-авторизацией нет. Происходит резервирование и сразу же списание на сумму, указанную в клиринге: операции HOLD и CAPTURE. Здесь подобная операция рассматривается как оффлайн.

В клиринге может быть отражена операция возврата: REFUND. Она не имеет связи с исходной операцией (в отличие от REVERSAL, которая не отражается в клиринге). Это отдельная операция зачисления денежных средств от провайдера на счет пользователя.

Клиринг по одной и той же покупке может приходить несколько раз на разные суммы.

Взаимодействие через API

Авторизация

Поддерживаются только HTTPS-запросы. HTTP-запросы по нешифрованному каналу не поддерживаются.

Схема аутентификации - Bearer. В заголовках запроса передаётся bearer-токен в поле Authorization.

--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******"

Bearer-токен выдается партнеру при интеграции.

URL для вызовов API

• https://api-test.qiwi.com - testing окружение;
• https://api.qiwi.com - production окружение.

Уведомления — общая информация

Технически отправка уведомления — это POST-запрос по протоколу HTTP(S), выполняемому по адресу URL, который партнер разово передает курирующему менеджеру.

Сервер на стороне партнера должен быть готов к приему таких запросов.

Адрес URL уникален: для каждого productID указывается свой URL.

Запрос стандартно состоит из заголовков и тела. Тело запроса — строковое представление JSON-объекта, в котором содержатся данные входящего уведомления.

• HEADERS

В принимаемом запросе необходимо анализировать заголовок QIWI-Signature. Он содержит подпись, вычисленную по алгоритму "HmacSHA256" на основе "секрета" и тела запроса. "Секрет" в виде символьной строки предоставляется партнеру отдельно.

Необходимо обеспечить надежное хранение "секрета" и не допускать несанкционированный доступ к нему.

Сервер партнера при получении уведомления должен вычислить подпись на основе "секрета" и тела запроса, после чего сверить результат со значением, переданным в заголовке запроса QIWI-Signature. В случае расхождения запрос следует игнорировать.

Уведомления об изменении статуса идентификации пользователя

Пример запроса

{
  "type": "CLIENT_IDENTIFICATION_CHANGED",
  "clientId": "d8ce63e4-2213-4574-92f3-66bf381529a2",
  "oldIdentificationLevel": "NOT_VERIFIED",
  "newIdentificationLevel": "FULL",
  "changedAt": "2020-05-25T14:30:00+03:00",
  "changeNumber": 25
}

Параметр	Описание
type	Тип уведомления: CLIENT_IDENTIFICATION_CHANGED (изменение статуса идентификации)
clientId	Уникальный идентификатор пользователя
oldIdentificationLevel	Предыдущий уровень идентификации пользователя
newIdentificationLevel	Новый (текущий) уровень идентификации пользователя
changedAt	Временная метка: указывает, когда произошла смена уровня идентификации
changeNumber	Порядковый номер изменения. Несмотря на то, что это значение принадлежит к арифметической прогрессии с шагом равным единице и ведётся отдельно для каждого пользователя, уведомления могут приходить в произвольном порядке. Поле можно использовать для сортировки уведомлений и отбрасывания тех уведомлений, changeNumber которых меньше.

Уведомления об операциях, инициированных из интерфейса партнера

Пример уведомления о пополнении счета пользователя с банковской карты

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

Пример уведомления об оплате в пользу провайдера со счета пользователя

{
  "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": "WITHDRAWAL_TO_CARD",
  "txnId": "46829337545338664347",
  "txnType": "withdrawal-to-card",
  "fromClientId": "jloungozcz2298040076",
  "transactionAmount": {
    "value": 2.9,
    "currency": "RUB"
  },
  "clientCommission": {
    "value": 100.0,
    "currency": "RUB"
  },
  "status": "SUCCESS",
  "statusDetails": {},
  "creationDateTime": "2020-09-24T10:42:18+03:00"
}

Общие для всех типов уведомлений параметры

Параметр	Описание
type	Тип уведомления
txnId	Идентификатор операции, по которой пришло уведомление
txnType	Тип операции
transactionAmount	Блок с информацией о сумме операции
value	Значение с двумя десятичными разрядами
currency	Валюта: RUB
clientCommission	Блок с информацией о сумме комиссии, которая была удержана с пользователя (присутствует только для тех типов платежей, по которым настроена комиссия)
value	Значение с двумя десятичными разрядами
currency	Валюта: RUB
status	Статус операции: см. статусы для домена PAYMENTS
statusDetails	Если "Status": "SUCCESS" - пустой объект {}, если "Status": "DECLINED" — объект c полем failureCode
creationDateTime	Дата создания операции в сервисе Payments. DateTime в формате ISO 8601 ±hh:mm с московской Time Zone

Параметры, свойственные типу REPLENISHMENT_BY_WEBFORM

Параметр	Описание
toClientId	Идентификатор получателя платежа

Параметры, свойственные типу PAYMENT

Параметр	Описание
fromClientId	Идентификатор пользователя, со счета которого происходит списание денежных средств
toProviderId	Идентификатор провайдера/услуги, в пользу которого осуществляется платеж. Выдается партнеру при интеграции.
toProviderData	Блок с доп. информацией, необходимой провайдеру для успешного проведения платежа
account	Идентификатор пользователя на стороне провайдера

Параметры, свойственные типу WITHDRAWAL_TO_CARD

Параметр	Описание
fromClientId	Идентификатор пользователя, со счета которого происходит списание денежных средств

Типы уведомлений

Тип уведомления	Тип операции	Описание
REPLENISHMENT_BY_WEBFORM	replenishment-by-webform	Пополнение счета пользователя с банковской карты
REPLENISHMENT_FROM_FUNDER	replenishment-from-external-processing-funder	Пополнение счета пользователя с другого счета, инициированное через другие протоколы QIWI
PAYMENT	payment	Оплата в пользу провайдера со счета пользователя
WITHDRAWAL_TO_CARD	withdrawal-to-card	Перевод со счета пользователя на банковскую карту

Уведомления об операциях с использованием карты

Ознакомьтесь с процессом проведения покупки с использованием карты.

Реализованы перечисленные по ссылке типы уведомлений.

Ответ ←

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

Покупка

Пример уведомления по успешной онлайн-авторизации

{
  "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"
    },
    "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"
  }
}

Пример уведомления по неуспешной онлайн-авторизации

{
  "type": "AUTHORIZATION",
  "eventDateTime": "2020-08-12T13:24:45.601476+03:00",
  "txnId": "e9ebd6fb-f7ac-4736-8752-d79b702ccace",
  "txnType": "PURCHASE_E_POS",
  "actionId": "d872a658-d07f-42f3-84dc-9f940b1a54ee",
  "actionType": "HOLD",
  "actionStatus": "FAILED",
  "actionStatusDetails": {
    "failureCode": "ACCOUNT_BALANCE_INSUFFICIENT_FUNDS"
  },
  "actionData": {
    "cardTokenId": "100074267865",
    "clientId": "1",
    "transactionAmount": {
      "currency": "RUB",
      "value": "8.52"
    },
    "authorizationDateTime": "2020-08-12T13:24:40+03:00",
    "retrievalReferenceNumber": "001701330945",
    "merchantId": "498750000011107",
    "cardAcceptorNameAndLocation": "MIKROMARKET>MOSCOW",
    "merchantType": "5499",
    "terminalId": "99999999",
    "acquirerId": "498750",
    "correlationId": "d872a658-d07f-42f3-84dc-9f940b1a54ee"
  }
}

Пример уведомления по успешной оффлайн-операции

{
  "type": "CLEARING",
  "eventDateTime": "2020-11-08T19:46:47.547972+03:00",
  "txnId": "0b1f21da-890a-4083-ba08-1415eed9cd4b",
  "txnType": "PURCHASE_POS",
  "actionId": "3c10a347-7095-415e-835c-da3f34fd3a2b",
  "actionType": "CAPTURE_HOLD",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100074276831",
    "clientId": "c8193105661",
    "clearingDate": "2020-11-08",
    "transactionAmount": {
      "currency": "RUB",
      "value": "100.00"
    },
    "originTransactionAmount": {
      "currency": "USD",
      "value": "1.29"
    },
    "retrievalReferenceNumber": "005710141565",
    "merchantId": "781000007913   ",
    "merchantName": "MIKROMARKET>MOSCOW",
    "merchantType": "5499",
    "terminalId": "20733084",
    "acquirerId": "427600",
    "multiClearingData": {
      "partNumber": 1,
      "partTotalCount": 2
    }
  }
}

Пример уведомления об операции покупки в валюте

{
  "type": "AUTHORIZATION",
  "eventDateTime": "2020-08-12T13:14:23.706284+03:00",
  "txnId": "0fa734d0-c03b-4681-9365-65e55e10f002",
  "txnType": "PURCHASE_E_POS",
  "actionId": "ba3ae9f1-0f82-49e7-be16-ecd0add4407c",
  "actionType": "HOLD",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100074268301",
    "clientId": "1",
    "transactionAmount": {
      "currency": "RUB",
      "value": "73.28"
    },
    "originTransactionAmount": {
      "currency": "USD",
      "value": "1.00"
    },
    "authorizationDateTime": "2020-08-12T13:14:16+03:00",
    "retrievalReferenceNumber": "008141362354",
    "merchantId": "498750000011107",
    "cardAcceptorNameAndLocation": "MIKROMARKET>MOSCOW",
    "merchantType": "5499",
    "terminalId": "99999999",
    "acquirerId": "498750",
    "correlationId": "ba3ae9f1-0f82-49e7-be16-ecd0add4407c"
  }
}

Структура уведомлений об операциях с использованием карты

Поле уведомления	Описание
type	Тип уведомления
eventDateTime	Дата уведомления в формате ISO 8601
txnId	Идентификатор операции, по которой пришло уведомление
txnType	Тип операции, для которой сформировано уведомление
actionId	Идентификатор действия, которое произошло с операцией
actionType	Тип действия, которое произошло с операцией
actionStatus	Статус действия, которое произошло с авторизацией
actionStatusDetails	Пустой объект {}, если "actionStatus": "SUCCESS" Объект c полем failureCode, если "actionStatus": "FAILED". Это значит, что в момент проведения операции возникла ошибка. См. пример уведомления по неуспешной онлайн-авторизации.
actionData	Блок с описанием деталей операции
cardTokenId	Уникальный идентификатор (токен) карты
clientId	Уникальный идентификатор пользователя, которому принадлежит карта
partnerTxnId	Идентификатор транзакции, переданный партнером в ответе-подтверждении на запрос выдачи займа клиенту
transactionAmount	Блок с информацией о сумме операции в валюте счета (рубли). Сумма операции не включает в себя комиссию, которая была удержана с пользователя.
value	Значение суммы с двумя десятичными разрядами
currency	Валюта: RUB
clientCommission	Блок с информацией о сумме комиссии, которая была удержана с пользователя.
value	Значение суммы с двумя десятичными разрядами
currency	Валюта: RUB
partnerCommission	Блок с информацией о сумме комиссии, которая была удержана со специального счета партнера при выдаче займа клиенту.
value	Значение суммы с двумя десятичными разрядами
currency	Валюта: RUB
authorizationDateTime	Только для уведомлений с "type": "AUTHORIZATION". Дата онлайн-авторизации, которую передала платежная система.
retrievalReferenceNumber	RRN
merchantId	Идентификатор провайдера, который передала платежная система
cardAcceptorNameAndLocation	Только для уведомлений с "type": "AUTHORIZATION". Имя провайдера и локация, которые передала платежная система.
merchantName	Только для уведомлений с "type": "CLEARING". Имя провайдера, которое передала платежная система.
merchantType	MCC
terminalId	Идентификатор терминала, который передала платежная система
acquirerId	Идентификатор эквайера, который передала платежная система
correlationId	Идентификатор, позволяющий объединить уведомления и запросы в логически связанную группу операций
clearingDate	Только для уведомлений с "type": "CLEARING". Дата клиринга (расчета) по карточной операции.
originTransactionAmount	Блок с информацией по оригинальной сумме и валюте операции
currency	Оригинальная валюта операции
value	Значение оригинальной суммы операции, с двумя десятичными разрядами
multiClearingData	Опционально. Только для уведомлений с "type": "CLEARING". Присутствует в случе, когда клиринг является нефинальным (мультиклиринг): произошло списание лишь части изначально захолдированных денежных средств.
partNumber	Неупорядоченный номер части мультиклиринг-операции. Нумерация начинается с 1.
partTotalCount	Ожидаемое количество всех частей мультиклиринг-операции. Минимальное значение равно 1.
wasNotAuthorizedBefore	Опционально. Только для уведомлений с "type": "CLEARING", когда параметр actionType равен либо CAPTURE_FAST_FUNDS, либо CAPTURE_FAST_FUNDS_REVERSAL. Логический признак того, что было произведено пополнение по номеру карты в онлайн-операции ("type": "AUTHORIZATION", "txnType": "FAST_FUNDS", "actionType": "FAST_FUNDS"), либо была совершена отмена пополнения по номеру карты в онлайн-операции ("type": "AUTHORIZATION", "txnType": "FAST_FUNDS", "actionType": "FAST_FUNDS_REVERSAL"). Возможные значения: false — движения денежных средств в рамках этого уведомления совершено не было (оно произошло при обработке онлайн-операции); true — денежные средства были зачислены на счет пользователя в рамках этой оффлайн-операции (онлайн-операции пополнения карты не было).
accountBalance	Опционально. Только для уведомлений с "txnType": "BALANCE_INQUIRY" и "actionType": "BALANCE_INQUIRY", либо "txnType": "CASH_WITHDRAWAL_ATM", "txnType": "CASH_WITHDRAWAL_CASHIER" и "actionType": "CASH_WITHDRAWAL_HOLD", либо "txnType": "LOAN_ISSUE" и "actionType": "LOAN_ISSUE". Блок с информацией о сумме остатка на счете и валюте счета: - в случае операции с "actionType": "CASH_WITHDRAWAL_HOLD" — сумма остатка на счете после проведения операции авторизации; - в случае операции с "actionType": "BALANCE_INQUIRY" — текущая сумма остатка на счете; - в случае операции с "actionType": "LOAN_ISSUE" — сумма остатка на счете до запроса займа.

Возврат

Пример уведомления о возврате средств с использованием интернет-эквайринга

{
  "type": "CLEARING",
  "eventDateTime": "2020-12-02T15:01:20.908945+03:00",
  "txnId": "745f0970-258c-41c1-afbd-da23401795b9",
  "txnType": "REFUND_E_POS",
  "actionId": "599c3285-5f36-4eca-bace-c31db3989636",
  "actionType": "CAPTURE_REFUND",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100075717766",
    "clientId": "xpemmwmewf0077828490",
    "clearingDate": "2020-12-02",
    "transactionAmount": {
      "currency": "RUB",
      "value": "9.04"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "9.04"
    },
    "merchantId": "544521933108",
    "merchantName": "MIKROMARKET",
    "merchantType": "3492",
    "terminalId": "02614260",
    "acquirerId": "646114"
  }
}

Пополнение

Пример уведомления об операции пополнения по номеру карты (онлайн-операция)

{
  "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"
    },
    "authorizationDateTime": "2021-06-08T18:06:29+03:00",
    "retrievalReferenceNumber": "005613823345",
    "merchantId": "SBOL",
    "cardAcceptorNameAndLocation": "VISAMONEYTRANSFER>VisaDirectLU",
    "merchantType": "4829",
    "terminalId": "99999999",
    "acquirerId": "402333",
    "correlationId": "ccc0859a-e714-4650-b55e-ac46aad8a904"
  }
}

Пример уведомления об операции пополнения по номеру карты (оффлайн-операция)

{
  "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",
    "clearingDate": "2021-06-08",
    "transactionAmount": {
      "currency": "RUB",
      "value": "3.29"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "3.29"
    },
    "merchantId": "351771137636",
    "merchantName": "TEST_MERCHANT_NAME",
    "merchantType": "1553",
    "terminalId": "83872934",
    "acquirerId": "295503",
    "wasNotAuthorizedBefore": true
  }
}

Снятие наличных

Пример уведомления об операции снятия наличных (онлайн-операция)

{
  "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"
    },
    "accountBalance": {
      "currency": "RUB",
      "value": "3.52"
    },
    "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"
  }
}

Пример уведомления об операции снятия наличных (оффлайн-операция)

{
  "type": "CLEARING",
  "eventDateTime": "2021-09-20T15:41:12.339933+03:00",
  "txnId": "438a86a6-b1d4-4a6b-afbd-e2983585d10a",
  "txnType": "CASH_WITHDRAWAL_ATM",
  "actionId": "00c74370-98a0-4c5e-b6b8-a53ff3fa89fb",
  "actionType": "CAPTURE_CASH_WITHDRAWAL_HOLD",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100079217733",
    "clientId": "toobbnnpwb2282661650",
    "clearingDate": "2021-09-20",
    "transactionAmount": {
      "currency": "RUB",
      "value": "100000.00"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "100000.00"
    },
    "merchantId": "436482220316",
    "merchantName": "TEST_MERCHANT_NAME",
    "merchantType": "1327",
    "terminalId": "39915295",
    "acquirerId": "604319"
  }
}

Пример уведомления об отмене операции снятия наличных (онлайн-операция)

{
  "type": "AUTHORIZATION",
  "eventDateTime": "2021-09-20T15:40:53.234782+03:00",
  "txnId": "51db107a-4711-4427-965f-aa2dd4184673",
  "txnType": "CASH_WITHDRAWAL_ATM",
  "actionId": "b9f94ebe-986c-4e02-8054-8e0ceccded25",
  "actionType": "CASH_WITHDRAWAL_REVERSAL",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100079220757",
    "clientId": "uflpniliwd0929192436",
    "transactionAmount": {
      "currency": "RUB",
      "value": "100000.00"
    },
    "clientCommission": {
      "currency": "RUB",
      "value": "0.00"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "100000.00"
    },
    "authorizationDateTime": "2021-09-20T15:40:47+03:00",
    "retrievalReferenceNumber": "008371274064",
    "merchantId": "VB24           ",
    "cardAcceptorNameAndLocation": "VB24           >SANKT-PETERBU         RU",
    "merchantType": "6011",
    "terminalId": "99999999",
    "acquirerId": "471461",
    "correlationId": "b9f94ebe-986c-4e02-8054-8e0ceccded25"
  }
}

Пример уведомления об отмене операции снятия наличных (оффлайн-операция)

{
  "type": "CLEARING",
  "eventDateTime": "2021-09-20T15:41:01.11133+03:00",
  "txnId": "7a195984-d098-47e9-81f2-8f4f51cf35ec",
  "txnType": "REFUND_CASH_WITHDRAWAL_ATM",
  "actionId": "2e0b3181-2369-4550-b3a6-de792ce0cac3",
  "actionType": "CAPTURE_CASH_WITHDRAWAL_REFUND",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "100079216564",
    "clientId": "koikfgthpw2108201601",
    "clearingDate": "2021-09-20",
    "transactionAmount": {
      "currency": "RUB",
      "value": "60000.01"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "60000.01"
    },
    "merchantId": "669280139004",
    "merchantName": "TEST_MERCHANT_NAME",
    "merchantType": "3097",
    "terminalId": "79249934",
    "acquirerId": "604527"
  }
}

Пример уведомления об онлайн-операции списания с карты для перевода на карту или счет (AFT)

{
  "type": "AUTHORIZATION",
  "eventDateTime": "2022-02-15T14:28:53.459536+03:00",
  "txnId": "db828678-b5db-473f-bebb-97383c496394",
  "txnType": "P2P_DEBIT",
  "actionId": "d5e30bbb-4e70-4410-81e2-e093e2910287",
  "actionType": "HOLD",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "999822534020",
    "clientId": "rresnbfy09650312",
    "transactionAmount": {
      "currency": "RUB",
      "value": "5.42"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "5.42"
    },
    "authorizationDateTime": "2022-02-15T14:28:50+03:00",
    "retrievalReferenceNumber": "006051743846",
    "merchantId": "809215         ",
    "cardAcceptorNameAndLocation": "CARD2CARD BANK_MOBILE>MOSCOW          RU",
    "merchantType": "5499",
    "terminalId": "809216  ",
    "acquirerId": "498750",
    "correlationId": "d5e30bbb-4e70-4410-81e2-e093e2910287"
  }
}

Пример уведомления об оффлайн-операции списания с карты для перевода на карту или счет (AFT)

{
  "type": "CLEARING",
  "eventDateTime": "2022-02-15T15:05:34.214314+03:00",
  "txnId": "ffc9d97c-1b61-4738-a5e4-d8502b818fba",
  "txnType": "P2P_DEBIT",
  "actionId": "0088aab9-1cde-4120-8c1f-ea82453d2a9b",
  "actionType": "CAPTURE_HOLD",
  "actionStatus": "SUCCESS",
  "actionStatusDetails": {},
  "actionData": {
    "cardTokenId": "999178641952",
    "clientId": "njbzudbnvd8065253135",
    "clearingDate": "2022-02-15",
    "transactionAmount": {
      "currency": "RUB",
      "value": "2.74"
    },
    "originTransactionAmount": {
      "currency": "RUB",
      "value": "2.74"
    },
    "retrievalReferenceNumber": "003885464570",
    "merchantId": "809215         ",
    "merchantName": "CARD2CARD BANK_MOBILE>MOSCOW          RU",
    "merchantType": "5499",
    "terminalId": "809216",
    "acquirerId": "498750"
  }
}

Запрос баланса по счету карты

Пример уведомления об операции запроса баланса

{
  "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"
    },
    "accountBalance": {
      "currency": "RUB",
      "value": "1.42"
    },
    "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"
  }
}

Справочники

Типы уведомлений

Описывает тип события, совершенного в рамках операции с использованием карты.

Наименование	Описание
AUTHORIZATION	Онлайн-авторизация
CLEARING	Оффлайн-операция

Типы операций с использованием карты

Тип операции	Описание
PURCHASE_E_POS	Покупка в интернете
PURCHASE_POS	Покупка посредством наземного эквайринга
REFUND_E_POS	Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием интернет-эквайринга
REFUND_POS	Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием наземного эквайринга
FAST_FUNDS	Пополнение по номеру карты
LOAN_ISSUE	Выдача займа клиенту
CASH_WITHDRAWAL_ATM	Снятие наличных в банкомате
CASH_WITHDRAWAL_CASHIER	Снятие наличных через кассу банка
REFUND_CASH_WITHDRAWAL_ATM	Возврат средств по операции снятия наличных в банкомате
REFUND_CASH_WITHDRAWAL_CASHIER	Возврат средств по операции снятия наличных через кассу банка
BALANCE_INQUIRY	Запрос баланса счета (обычно в банкомате)
P2P_DEBIT	Списание с карты для перевода на карту или счет (AFT)
REFUND_P2P_DEBIT	Возврат списания с карты для перевода на карту или счет (AFT)

Типы действия, которое произошло с операцией

Тип действия	Описание	Тип уведомления, в котором возвращается
HOLD	Резервирование денежных средств	AUTHORIZATION
REVERSAL	Отмена резерва	AUTHORIZATION
CAPTURE_HOLD	Списание денежных средств	CLEARING
CAPTURE_REFUND	Зачисление денежных средств по причине возврата от провайдера	CLEARING
FAST_FUNDS	Пополнение по номеру карты	AUTHORIZATION
FAST_FUNDS_REVERSAL	Отмена пополнения по номеру карты (техническое событие, инициируется платежной системой)	AUTHORIZATION
CAPTURE_FAST_FUNDS	Клиринг по операции пополнения по номеру карты	CLEARING
CAPTURE_FAST_FUNDS_REVERSAL	Клиринг по отмене пополнения по номеру карты	CLEARING
LOAN_ISSUE	Выдача займа клиенту в ходе авторизации платежа	AUTHORIZATION
CASH_WITHDRAWAL_HOLD	Авторизация по снятию наличных	AUTHORIZATION
CASH_WITHDRAWAL_REVERSAL	Отмена авторизация по снятию наличных	AUTHORIZATION
CAPTURE_CASH_WITHDRAWAL_HOLD	Клиринг по операции снятия наличных	CLEARING
CAPTURE_CASH_WITHDRAWAL_REFUND	Клиринг по отмене операции снятия наличных	CLEARING
BALANCE_INQUIRY	Запрос баланса по счету карты

Статусы действия

Статус	Описание
SUCCESS	Успешно: финальный статус
FAILED	Неуспешно: финальный статус. В процессе выполнения произошла ошибка

Справочник кодов ошибок авторизаций

Код	Описание
INTERNAL_ERROR	Внутренняя/сервисная ошибка
LIMITS_EXCEEDED	Лимиты (на оборот, на 1 операцию) нарушены
ACCOUNT_BALANCE_INSUFFICIENT_FUNDS	Недостаточно средств
ACCOUNT_BALANCE_EXCEEDED	Превышен допустимый лимит остатка на балансе
CLIENT_BLOCKED	Пользователь заблокирован
WRONG_CURRENCY	Некорректная/неподдерживаемая валюта
WRONG_IDENTIFICATION	Некорректный/неподдерживаемый уровень идентификации для совершения данного действия
REVERSAL_AMOUNT_EXCEEDS_HOLD_AMOUNT	Сумма отмены превысила сумму захолдированных по операции средств
FAST_FUNDS_REVERSAL_AMOUNT_NOT_EQUAL_FAST_FUNDS_AMOUNT	Сумма отмены операции пополнения по номеру карты не соответствует сумме операции пополнения по номеру карты
LOAN_ISSUE_REJECTED	Клиенту было отказано в выдаче займа в ходе авторизации платежа
CASH_WITHDRAWAL_REVERSAL_AMOUNT_NOT_EQUAL_CASH_WITHDRAWAL_HOLD_AMOUNT	Сумма отмены операции снятия наличных не соответствует сумме операции снятия наличных
CASH_WITHDRAWAL_CAPTURE_AMOUNT_NOT_EQUAL_CASH_WITHDRAWAL_HOLD_AMOUNT	Сумма в оригинальной валюте для клиринга операции снятия наличных не соответствует сумме авторизации операции снятия наличных

Выдача займа клиенту

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

Поскольку технически выдача займа выполняется в отдельной транзакции, то в такой схеме партнер будет получать по два уведомления об авторизации: одно в рамках собственно авторизационной транзакции (тип операции PURCHASE_POS или PURCHASE_E_POS), другое — в рамках транзакции выдачи займа (тип операции LOAN_ISSUE).

Процесс выдачи займа состоит из следующих шагов:

1. Если при авторизации платежа видно, что средств на балансе покупателя недостаточно, сервис проверяет наличие недостающей суммы на балансе специального счета партнера (для займов), включая комиссию, рассчитанную согласно договору с партнером.
2. Если средств недостаточно, то авторизация платежа отклоняется с двумя уведомлениями партнеру о неуспешной операции (авторизации/выдачи займа) с кодом ошибки ACCOUNT_BALANCE_INSUFFICIENT_FUNDS.
3. Если средств достаточно, сервис отправляет партнеру запрос на подтверждение выдачи займа покупателю в размере недостающей суммы.
4. В ответе от партнера сервис ожидает подтверждение или отказ в выдаче займа. В случае отказа авторизация платежа отклоняется с двумя уведомлениями партнеру о неуспешной операции (авторизации/выдачи займа) с кодом ошибки LOAN_ISSUE_REJECTED. В случае подтверждения, необходимая сумма переводится со специального счета партнера на счет покупателя.
5. Авторизация платежа продолжается. В результате партнер получает два уведомления:
   • Уведомление с типом действия HOLD об успешности проведения авторизации платежа.
   • Уведомление с типом действия LOAN_ISSUE об успешности операции выдачи займа покупателю. В нем будут присутствовать дополнительные поля:
     • поле actionData.partnerTxnId c идентификатором транзакции из ранее полученного от партнера подтверждения выдачи займа;
     • поле actionData.partnerCommission c суммой комиссии, удержанной с партнера в п. 1.

     При получении этого уведомления партнер может принять решение о том, что займ был выдан (или не выдан) его клиенту.

В запросе на подтверждение выдачи займа покупателю, а также во всех уведомлениях, поступающих в процессе выдачи займа, будет присутствовать поле correlationId. Значение поля — идентификатор, с помощью которого можно объединить все уведомления и исходный запрос в логически связанную группу операций.

Формат запроса

Пример тела запроса партнеру на выдачу займа

{
  "clientId": "1",
  "cardTokenId": "100074268301",
  "transactionAmount": {
    "currency": "RUB",
    "value": "53.00"
  },
  "clientDebtAmount": {
    "currency": "RUB",
    "value": "15.00"
  },
  "insufficientAmount": {
    "currency": "RUB",
    "value": "68.00"
  },
  "txnId": "8141362354",
  "actionId": "hold-8141362354-ZGP638",
  "originTransactionAmount": {
    "currency": "RUB",
    "value": "53.00"
  },
  "authorizationDateTime": "2020-08-12T13:14:16+03:00",
  "retrievalReferenceNumber": "008141362354",
  "merchantId": "498750000011107",
  "merchantType": "5499",
  "cardAcceptorNameAndLocation": "MIKROMARKET>MOSCOW",
  "acquirerId": "498750",
  "terminalId": "99999999",
  "correlationId": "879e12ca-476a-4726-a5fb-e3c4546e47f1"
}

Обработка и формат запроса аналогичны другим уведомлениям. Время ожидания ответа от партнера составляет не более 500 миллисекунд.

Поле запроса	Описание
actionId	Идентификатор действия, которое произошло с операцией
cardTokenId	Уникальный идентификатор (токен) карты
clientId	Уникальный идентификатор пользователя, которому принадлежит карта
transactionAmount	Блок с информацией о сумме операции в валюте счета (рубли)
value	Значение суммы с двумя десятичными разрядами
currency	Валюта: RUB
authorizationDateTime	Дата онлайн-авторизации, которую передала платежная система
retrievalReferenceNumber	RRN
merchantId	Идентификатор провайдера, который передала платежная система
cardAcceptorNameAndLocation	Имя провайдера и локация, которые передала платежная система.
merchantType	MCC
terminalId	Идентификатор терминала, который передала платежная система
acquirerId	Идентификатор эквайера, который передала платежная система
correlationId	Идентификатор, позволяющий объединить уведомления и запросы в логически связанную группу операций
originTransactionAmount	Блок с информацией по оригинальной сумме и валюте операции
currency	Оригинальная валюта операции
value	Значение оригинальной суммы операции, с двумя десятичными разрядами
clientDebtAmount	Блок с информацией о сумме задолженности на счету покупателя на момент авторизации платежа. Сумма может быть больше или равна нулю
currency	Оригинальная валюта суммы задолженности
value	Значение оригинальной суммы задолженности, с двумя десятичными разрядами
insufficientAmount	Блок с информацией о сумме, недостающей покупателю для успешного проведения авторизации платежа. Сумма всегда больше нуля
currency	Оригинальная валюта недостающей суммы
value	Значение оригинальной недостающей суммы, с двумя десятичными разрядами

Формат ответа

Пример тела ответа партнера на запрос займа

{
  "status": "APPROVED",
  "statusDetails": {
    "productId": "Prd-123-DEF-456",
    "clientId": "1",
    "accountId": "Acc-123-DEF-456",
    "partnerTxnId": "14e7c47d-8151-48a7-9a4f-d67d2566fec9",
    "loanAmount": {
      "currency": "RUB",
      "value": "68.00"
    }
  }
}

При получении и обработке запроса сервер партнера должен вернуть HTTP-код в диапазоне от 200 до 299 и JSON со следующей структурой:

Поле ответа	Описание
status	Статус решения партнера о предоставлении займа клиенту: APPROVED или REJECTED
statusDetails	Блок с дополнительной информацией. При передаче поля "status": "APPROVED" все поля блока должны быть заполнены. В случае передачи "status": "REJECTED" блок не заполняется.
productId	Идентификатор продукта: выдается партнеру при интеграции
clientId	Уникальный идентификатор пользователя, которому принадлежит карта. Должен быть идентичен clientId, переданному в запросе
accountId	Уникальный идентификатор счета клиента в системе партнера; счет должен принадлежать клиенту clientId
partnerTxnId	Уникальный идентификатор операции выдачи займа, зарегистрированной в системе партнера
loanAmount	Блок с информацией о сумме выдаваемого займа. Структура и содержание должны быть идентичны блоку insufficientAmount, переданному в запросе

Уведомления о блокировке карты

Пример уведомления о блокировке карты

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

Поле уведомления	Описание
type	Тип уведомления: CARD_WAS_BLOCKED (блокировка карты)
clientId	Уникальный идентификатор пользователя, которому принадлежит карта
cardTokenId	Уникальный идентификатор (токен) карты
blockSource	Источник блокировки
blockedAt	Дата блокировки в формате ISO 8601 ±hh:mm с московской Time Zone

История операций

Метод возвращает список всех операций, совершенных с использованием конкретного счета пользователя. Речь идет как о карточных авторизациях, проведенных платежными системами, так и об операциях, инициированных из интерфейса партнера.

История возвращает перечисленные типы операций.

Запрос → GET

• URL /partner/openapi-reports/v1/products/{productId}/operations/history?accountId={accountId}&limit={limit}&cursor={cursor}&dateFrom={dateFrom}&dateTill={dateTill}

• HEADERS

  • Authorization: Bearer SECRET_KEY
  • Content-Type: application/json;charset=UTF-8/json

• Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-reports/v1/products/best-partner/operations/history?accountId=cdvvgtdiiu6310024653&limit=100 \
-X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'

Пример запроса с пагинацией и начальной позицией

curl https://api-test.qiwi.com/partner/openapi-reports/v1/products/best-partner/openapi-reports/v1/products/best-partner/operations/history?accountId=cdvvgtdiiu6310024653&limit=100&cursor=5379a6e7-50c6-48fe-3db4-d10be301f76d \
-X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'

Параметр	Описание	REGEX	Пример
productId	Обязательный параметр URL запроса. Идентификатор продукта: выдается партнеру при интеграции	^[A-Za-z0-9-]{1,100}$	Prd-123-DEF-456
accountId	Обязательный параметр URL запроса. Идентификатор счета в системе партнера: партнер передает id счета пользователя, созданного по Clients API, по которому необходимо получить историю операций	^[A-Za-z0-9-]{1,100}$	Acc-123-DEF-456
limit	Обязательный параметр URL запроса. Размер выборки. См. подробнее раздел Пагинация
cursor	Параметр URL запроса. Позиция начального элемента списка операций из предыдущего запроса. См. подробнее раздел Пагинация
dateFrom	Параметр URL запроса. Дата начала временного диапазона. Указывается при необходимости ограничить выборку операций определенным временным диапазоном	DateTime в формате ISO 8601 4.3.2 datetime complete extended (Z, ±hh:mm)	2017-08-13T14:30:00+03:00
dateTill	Параметр URL запроса. Дата окончания временного диапазона. Указывается при необходимости ограничить выборку операций определенным временным диапазоном	DateTime в формате ISO 8601 4.3.2 datetime complete extended (Z, ±hh:mm)	2017-08-13T14:30:00+03:00

Пагинация

Параметр limit определяет количество операций, которое необходимо вернуть в одном txnList. Минимум — 1, максимум — 200. Если в запросе будет указан limit > 200, в txnList вернется не более 200 операций.

Параметр cursor определяет позицию, начиная с которой будет произведена выборка операций для выдачи в ответе на запрос истории. Например, если в ответе вернулся "cursor":"5379a6e7-50c6-48fe-3db4-d10be301f76d", то последняя операция, полученная в истории, имеет идентификатор "txnHistoryId": "5379a6e7-50c6-48fe-3db4-d10be301f76d". Это означает, что следующую выборку нужно делать именно с этой позиции: в нее попадут все операции, которые были совершены после указанной. Сама указанная операция в выборку не попадет.

Ответ ←

Пример ответа: покупка в интернете с использованием карты.

{
  "txnList" : [ {
    "commonTxnInfo" : {
      "txnHistoryId" : "98478192-19a9-decc-092a-468dab0afabb",
      "domain" : "CARDS",
      "domainTxnId" : "2740a95f-2cfd-49b8-b39f-534a1be4b18d",
      "domainTxnStatus" : {
        "domainTxnStatusId" : "1",
        "name" : "PROCESSING"
      },
      "txnType" : {
        "domainTxnTypeId" : "2",
        "name" : "PURCHASE_E_POS"
      },
      "txnClientBalanceImpact" : "EXPENSE",
      "clientId" : "mxmyrdxxxx8585680090",
      "accountId" : "xxxxxxzsp7009773700",
      "productId" : "best-partner",
      "txnCreationDateTime" : "2021-08-13T10:23:11+03:00",
      "txnAmount" : {
        "value" : "5.15",
        "currency" : "RUB"
      },
      "commissionAmount" : {
        "value" : "0.00",
        "currency" : "RUB"
      },
      "txnErrorInfo" : null
    },
    "cardTxnInfo" : {
      "cardTokenId" : "100079217135",
      "maskedPan" : "4153****8772",
      "merchantType" : "5499",
      "merchantId" : "498750000011107",
      "merchantName" : "FACEBK ADS>fb.me/adsIE"
    }
  } ]
}

Пример ответа: возврат средств от провайдера с использованием интернет-эквайринга.

{
  "txnList": [ 
    {
      "commonTxnInfo" : {
        "txnHistoryId" : "e107a317-17eb-7675-9b9b-1e086abf3e5f",
        "domain" : "CARDS",
        "domainTxnId" : "99ed233c-fa50-4c99-b55c-0bad7f975e5f",
        "domainTxnStatus" : {
          "domainTxnStatusId" : "2",
          "name" : "SUCCESS"
        },
        "txnType" : {
          "domainTxnTypeId" : "4",
          "name" : "REFUND_E_POS"
        },
        "txnClientBalanceImpact" : "INCOME",
        "clientId" : "xkyygptxei2154520025",
        "accountId" : "katnccfnot1406007604",
        "productId" : "best-partner",
        "txnCreationDateTime" : "2020-11-30T15:23:05+03:00",
        "txnAmount" : {
          "value" : "9.13",
          "currency" : "RUB"
        },
        "commissionAmount" : {
          "value" : "0.00",
          "currency" : "RUB"
        },
        "txnErrorInfo" : null
      },
      "cardTxnInfo" : {
        "cardTokenId" : "100075721030",
        "maskedPan" : "4153****0746",
        "merchantType" : "8988",
        "merchantId" : "792185921248",
        "merchantName" : "FACEBK ADS>fb.me/ads"
      }
    } 
  ],
  "cursor" : "e107a317-17eb-7675-9b9b-1e086abf3e5f"
}

Пример ответа: пополнение счета пользователя с банковской карты, пополнение счета пользователя с другого счета.

{
  "txnList": [
    {
      "commonTxnInfo": {
        "txnHistoryId": "034032d3-4d21-da6f-4e81-c218e3f73fd3",
        "domain": "PAYMENTS",
        "domainTxnId": "20841334328035502954",
        "domainTxnStatus": {
          "domainTxnStatusId": 60,
          "name": "SUCCESS"
        },
        "txnType": {
          "domainTxnTypeId": 5,
          "name": "INVOICING_SERVICE"
        },
        "txnClientBalanceImpact": "INCOME",
        "clientId": "ftwoubqzju7006699932",
        "accountId": "aclalfffci6896603637",
        "productId": "best-partner",
        "txnCreationDateTime": "2020-09-24T16:05:21+03:00",
        "txnAmount": {
          "value": 7.06,
          "currency": "RUB"
        },
        "commissionAmount": {
          "value": 100.00,
          "currency": "RUB"
        },
        "txnErrorInfo": null
      }
    },
    {
      "commonTxnInfo": {
        "txnHistoryId": "5379a6e7-50c6-48fe-3db4-d10be301f76d",
        "domain": "PAYMENTS",
        "domainTxnId": "74568770091151849147",
        "domainTxnStatus": {
          "domainTxnStatusId": 60,
          "name": "SUCCESS"
        },
        "txnType": {
          "domainTxnTypeId": 3,
          "name": "REPLENISHMENT_FROM_FUNDER"
        },
        "txnClientBalanceImpact": "INCOME",
        "clientId": "xizbttxisz9836366129",
        "accountId": "cdvvgtdiiu6310024653",
        "productId": "best-partner",
        "txnCreationDateTime": "2020-09-21T16:24:02+03:00",
        "txnAmount": {
          "value": 7.96,
          "currency": "RUB"
        },
        "commissionAmount": {
          "value": 0.00,
          "currency": "RUB"
        },
        "txnErrorInfo": null
      }
    }
  ],
  "cursor": "0a58b04f-23e2-ce66-4a93-e8dfdc3094e3"
}

Пример ответа: перевод между счетами пользователей, оплата в пользу провайдера со счета пользователя, перевод средств со счета пользователя на банковскую карту.

{
  "txnList": [
    {
      "commonTxnInfo": {
        "txnHistoryId": "7bc9122b-24a9-6fd3-00de-ab5ee29a1ed0",
        "domain": "PAYMENTS",
        "domainTxnId": "689834129540",
        "domainTxnStatus": {
          "domainTxnStatusId": 60,
          "name": "SUCCESS"
        },
        "txnType": {
          "domainTxnTypeId": 4,
          "name": "TRANSFER_BETWEEN_CLIENTS"
        },
        "txnClientBalanceImpact": "EXPENSE",
        "clientId": "fciscvrywl9511144790",
        "accountId": "jctfeudxbv9350100550",
        "productId": "best-partner",
        "txnCreationDateTime": "2020-09-22T01:33:22+03:00",
        "txnAmount": {
          "value": 2.72,
          "currency": "RUB"
        },
        "commissionAmount": {
          "value": 0.00,
          "currency": "RUB"
        },
        "txnErrorInfo": null
      },
      "transferBetweenClientsTxnInfo": {
        "anotherClientId": "dvqpsshreq7474202590",
        "anotherAccountId": "colwlksyqr4407625231"
      }
    },
    {
      "commonTxnInfo": {
        "txnHistoryId": "0a58b04f-23e2-ce66-4a93-e8dfdc3094e3",
        "domain": "PAYMENTS",
        "domainTxnId": "35215795065636956590",
        "domainTxnStatus": {
          "domainTxnStatusId": 60,
          "name": "SUCCESS"
        },
        "txnType": {
          "domainTxnTypeId": 1,
          "name": "PAYMENT"
        },
        "txnClientBalanceImpact": "EXPENSE",
        "clientId": "sjrpngawef8770553957",
        "accountId": "bwfefjwtfl3624831470",
        "productId": "best-partner",
        "txnCreationDateTime": "2020-09-24T10:18:40+03:00",
        "txnAmount": {
          "value": 9.63,
          "currency": "RUB"
        },
        "commissionAmount": {
          "value": 0.00,
          "currency": "RUB"
        },
        "txnErrorInfo": null
      },
      "providerTxnInfo": {
        "providerId": "best-partner",
        "providerDisplayName": "Покупка у тестового провайдера"
      }
    },
    {
      "commonTxnInfo" : {
      "txnHistoryId" : "f6b6be6b-073d-76c0-4b1e-95ed0a2f948c",
      "domain" : "PAYMENTS",
      "domainTxnId" : "08292288230573782472",
      "domainTxnStatus" : {
        "domainTxnStatusId" : "60",
        "name" : "SUCCESS"
      },
      "txnType" : {
        "domainTxnTypeId" : "8",
        "name" : "WITHDRAWAL_TO_CARD"
      },
      "txnClientBalanceImpact" : "EXPENSE",
      "clientId" : "wfdskihzwf6832842867",
      "accountId" : "opigfnqcrj2066445848",
      "productId" : "best-partner",
      "txnCreationDateTime" : "2020-11-10T12:17:41+03:00",
      "txnAmount" : {
        "value" : "55.67",
        "currency" : "RUB"
      },
      "commissionAmount" : {
        "value" : "49.00",
        "currency" : "RUB"
      },
      "txnErrorInfo" : null
      }
    }   
  ],
  "cursor": "0a58b04f-23e2-ce66-4a93-e8dfdc3094e3"
}

Пример ответа: пополнение по номеру карты

{
  "txnList" : [ {
    "commonTxnInfo" : {
      "txnHistoryId" : "a143b835-aaae-33df-f9c0-981b491c5d02",
      "domain" : "CARDS",
      "domainTxnId" : "a3bed765-3cdd-49bc-b341-7c46c4b4fe51",
      "domainTxnStatus" : {
        "domainTxnStatusId" : "2",
        "name" : "SUCCESS"
      },
      "txnType" : {
        "domainTxnTypeId" : "5",
        "name" : "FAST_FUNDS"
      },
      "txnClientBalanceImpact" : "INCOME",
      "clientId" : "tkzqgecfhp6318792298",
      "accountId" : "gsttucvuti5446745286",
      "productId" : "best-partner",
      "txnCreationDateTime" : "2021-09-22T13:04:14+03:00",
      "txnAmount" : {
        "value" : "9.79",
        "currency" : "RUB"
      },
      "commissionAmount" : {
        "value" : "0.00",
        "currency" : "RUB"
      },
      "txnErrorInfo" : null
    },
    "cardTxnInfo" : {
      "cardTokenId" : "100080518948",
      "maskedPan" : "4153****2761",
      "merchantType" : "4829",
      "merchantId" : "SBOL           ",
      "merchantName" : "VISA MONEY TRANSFER>Visa Direct       LU",
      "retrievalReferenceNumber": "001877916339"
    }
  } ]
}

Пример: снятие наличных через банкомат

{
  "txnList" : [ {
    "commonTxnInfo" : {
      "txnHistoryId" : "ae1b63b4-d6b0-5c15-d69a-2d344f36b9b8",
      "domain" : "CARDS",
      "domainTxnId" : "ef872961-2902-4a6b-97fa-34236b960ad2",
      "domainTxnStatus" : {
        "domainTxnStatusId" : "2",
        "name" : "SUCCESS"
      },
      "txnType" : {
        "domainTxnTypeId" : "6",
        "name" : "CASH_WITHDRAWAL_ATM"
      },
      "txnClientBalanceImpact" : "EXPENSE",
      "clientId" : "afcncmtyrs9142907318",
      "accountId" : "pextklmxrp7402082649",
      "productId" : "best-partner",
      "txnCreationDateTime" : "2021-09-22T12:45:24+03:00",
      "txnAmount" : {
        "value" : "9.67",
        "currency" : "RUB"
      },
      "commissionAmount" : {
        "value" : "0.00",
        "currency" : "RUB"
      },
      "txnErrorInfo" : null
    },
    "cardTxnInfo" : {
      "cardTokenId" : "100080522305",
      "maskedPan" : "4153****4924",
      "merchantType" : "6011",
      "merchantId" : "VB24           ",
      "merchantName" : "VB24           >SANKT-PETERBU         RU",
      "retrievalReferenceNumber": "001877916339"
    }
  } ]
}

Пример: запрос баланса (через банкомат)

{
  "txnList" : [ {
    "commonTxnInfo": {
        "txnHistoryId": "a81fff40-51b2-64e7-d7d2-89690c263a57",
        "domain": "CARDS",
        "domainTxnId": "1bd51bf1-3b02-4b73-bfbe-f07a39876f6b",
        "domainTxnStatus": {
            "domainTxnStatusId": 2,
            "name": "SUCCESS"
        },
        "txnType": {
            "domainTxnTypeId": 10,
            "name": "BALANCE_INQUIRY"
        },
        "txnClientBalanceImpact": "EXPENSE",
        "clientId": "mqyixkhjsr0446961069",
        "accountId": "dvdsaqznqh8727979115",
        "productId": "best-partner",
        "txnCreationDateTime": "2021-09-22T17:07:04+03:00",
        "txnAmount": {
            "value": 0.00,
            "currency": "RUB"
        },
        "commissionAmount": {
            "value": 0.00,
            "currency": "RUB"
        },
        "txnErrorInfo": null
    },
    "cardTxnInfo": {
        "cardTokenId": "100080518560",
        "maskedPan": "4153****2630",
        "merchantType": "6011",
        "merchantId": "VB24           ",
        "merchantName": "VB24           >SANKT-PETERBU         RU",
        "accountBalance": {
            "value": 8.11,
            "currency": "RUB"
        },
        "retrievalReferenceNumber": "001877916339"
    }
  } ]
}

Пример: cписание с карты для перевода на карту или счет (AFT)

{
  "txnList" : [ {
    "commonTxnInfo" : {
      "txnHistoryId" : "693611c8-8b25-e2f9-1895-09fc528bf129",
      "domain" : "CARDS",
      "domainTxnId" : "a0ca5dfd-bbd8-43f7-ac5d-77159cc6f6b6",
      "domainTxnStatus" : {
        "domainTxnStatusId" : "2",
        "name" : "SUCCESS"
      },
      "txnType" : {
        "domainTxnTypeId" : "12",
        "name" : "P2P_DEBIT"
      },
      "txnClientBalanceImpact" : "EXPENSE",
      "clientId" : "xmpukctjq520056273",
      "accountId" : "gjvhkvaxw73728124",
      "productId" : "b2b2c-test-full-access",
      "txnCreationDateTime" : "2022-02-15T16:47:48+03:00",
      "txnAmount" : {
        "value" : 7.52,
        "currency" : "RUB"
      },
      "commissionAmount" : {
        "value" : 0.00,
        "currency" : "RUB"
      }
    },
    "cardTxnInfo" : {
      "cardTokenId" : "999654310083",
      "maskedPan" : "4153****2349",
      "merchantType" : "5499",
      "merchantId" : "809215         ",
      "merchantName" : "CARD2CARD ALFA_MOBILE>MOSCOW          RU",
      "retrievalReferenceNumber" : "003885464570"
    }
  } ],
  "cursor" : "0e674276-5157-7975-7691-20e1c20c1c28"
}

Успешный ответ содержит список операций в объекте txnList.

Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.

Параметры, общие для всех типов операций

Параметр	Тип	Описание
txnList		Список операций
commonTxnInfo		Блок с информацией по одной конкретной операции
txnHistoryId	String	Уникальный идентификатор истории одной конкретной операции
domain	String	Домен, к которому относится операция
domainTxnId	String	Для домена PAYMENTS — значение transactionId из запроса на совершение платежа, для домена CARDS — значение txnId из уведомления об операции с использованием карты
domainTxnStatus		Блок с информацией о статусе операции
domainTxnStatusId		Код статуса операции
name		Статус операции
txnType		Блок с описанием типа операции
domainTxnTypeId	String	Код типа операции
name	String	Тип операции
txnClientBalanceImpact		Признак операции: INCOME - приход, EXPENSE - расход
clientId	String	Уникальный идентификатор пользователя, совершившего операцию
accountId	String	Идентификатор счета, по которому совершена операция
productId	String	Идентификатор продукта, в рамках которого совершена операция
txnCreationDateTime	DateTime в формате ISO 8601 ±hh:mm с московской Time Zone	Для домена PAYMENTS — значение creationDateTime из ответа на платежный запрос, для домена CARDS — значение authorizationDateTime
txnAmount		Блок с информацией о сумме операции
value	Number	Значение с двумя десятичными разрядами
currency	String	Валюта, ISO 4217: RUB
commissionAmount		Блок с информацией о комиссии, удержанной с пользователя
value	Number	Значение с двумя десятичными разрядами
currency	String	Валюта, ISO 4217: RUB
cursor	String	Позиция, начиная с которой будет произведена выборка операций для выдачи в ответе на следующий запрос истории. См. подробнее раздел Пагинация

Параметры, свойственные операциям домена CARDS

Параметр	Тип	Описание
cardTxnInfo		Блок с информацией о карте, по которой была совершена операция, и деталях карточного платежа или запроса баланса
cardTokenId	String	Уникальный идентификатор (токен) карты
maskedPan	String	Маскированный PAN. Пример: 4153****4697
merchantType	String	MCC
merchantId	String	Идентификатор провайдера, который передала платежная система. REGEX: ^([\w\s]{15})?\$
merchantName	String	Имя провайдера, которое передала платежная система
accountBalance	String	Опционально. Блок с информацией о сумме остатка на счете и валюте счета.
retrievalReferenceNumber	String	Идентификатор банковской транзакции (RRN)

Параметры, свойственные операции TRANSFER_BETWEEN_CLIENTS домена PAYMENTS

Параметр	Тип	Описание
transferBetweenClientsTxnInfo		Блок с информацией о получателе перевода
anotherClientId	String	Идентификатор пользователя. Если "txnClientBalanceImpact": "EXPENSE" - история запрошена по отправителю платежа и в данном параметре вернется уникальный идентификатор пользователя, на счет которого зачислен перевод. Если "txnClientBalanceImpact": "INCOME" - история запрошена по получателю платежа и в данном параметре вернется уникальный идентификатор пользователя, со счета которого совершен перевод.
anotherAccountId	String	Счет пользователя. Аналогично anotherClientId.

Параметры, свойственные операции PAYMENT домена PAYMENT

Параметр	Тип	Описание
providerTxnInfo		Блок с информацией о провайдере — получателе платежа
providerId	String	Идентификатор провайдера/услуги, в пользу которого совершен платеж

Параметры, свойственные операциям REPLENISHMENT_FROM_FUNDER и REPLENISHMENT_FROM_EXTERNAL_PROCESSING_FUNDER домена PAYMENT

Параметр	Тип	Описание
funderTxnInfo		Блок с информацией об источнике денежных средств
funderId	String	Идентификатор источника денежных средств

Домены

Домен	Описание
PAYMENTS	Операции, инициированные из интерфейса партнера
CARDS	Операции с использованием карты, которые инициированы не из интерфейса партнера и проводились через платежную систему

Статусы операций

Для домена PAYMENTS

Код	Статус	Описание
50	PROCESSING	В процессе проведения
60	SUCCESS	Успешно (финальный статус)
100	DECLINED	Неуспешно (финальный статус)

Для домена CARDS

Код	Статус	Описание
1	PROCESSING	В процессе проведения
2	SUCCESS	Успешно (финальный статус). Операция приобретает этот статус, когда платежная система инициировала клиринг. См. процесс проведения покупки с использованием карты.
3	FAILED	Неуспешно (финальный статус)

Типы операций

Для домена PAYMENTS

Код	Операция	Описание
1	PAYMENT	Оплата в пользу провайдера со счета пользователя
3	REPLENISHMENT_FROM_FUNDER	Пополнение счета пользователя с другого счета
4	TRANSFER_BETWEEN_CLIENTS	Перевод между счетами пользователей
5	INVOICING_SERVICE	Пополнение счета пользователя с банковской карты
8	WITHDRAWAL_TO_CARD	Перевод со счета пользователя на банковскую карту
9	REPLENISHMENT_FROM_EXTERNAL_PROCESSING_FUNDER	Пополнение счета пользователя с другого счета, инициированное через другие протоколы QIWI

Для домена CARDS

Код	Операция	Описание
1	PURCHASE_POS	Покупка посредством наземного эквайринга
2	PURCHASE_E_POS	Покупка с использованием карты в интернете
3	REFUND_POS	Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием наземного эквайринга
4	REFUND_E_POS	Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием интернет-эквайринга
5	FAST_FUNDS	Пополнение по номеру карты
6	CASH_WITHDRAWAL_ATM	Снятие наличных в банкомате
7	CASH_WITHDRAWAL_CASHIER	Снятие наличных через кассу банка
8	REFUND_CASH_WITHDRAWAL_ATM	Возврат по операции снятия наличных в банкомате
9	REFUND_CASH_WITHDRAWAL_CASHIER	Возврат по операции снятия наличных через кассира
10	BALANCE_INQUIRY	Запрос баланса
12	P2P_DEBIT	Списание с карты для перевода на карту или счет (AFT)
13	REFUND_P2P_DEBIT	Возврат списания с карты для перевода на карту или счет (AFT)

Формат ошибок API

Структура ответа на неуспешный запрос:

Пример ответа

{
    "serviceName": "openapi-reports",
    "errorCode": "openapi.reports.client.not.found",
    "dateTime": "2020-07-23T20:13:22.290416+03:00",
    "traceId": "67477569e8bc6838"
} 

Поле ответа	Описание
serviceName	Имя сервиса, который вернул ошибку
errorCode	Код ошибки. См. справочник кодов ошибок
dateTime	Дата и время формирование ответа
traceId	Параметр, необходимый для анализа логов. Его значение также всегда присутствует в заголовках ответа (response headers) в параметре X-B3-TraceId

Справочник кодов ошибок

Код	Описание
openapi.reports.client.not.found	Пользователь не найден
openapi.reports.internal.error	В сервисе истории произошла внутренняя ошибка
openapi.reports.validation.error	Ошибка валидации, проверьте корректность данных в запросе
openapi.reports.product.not.found	Продукт не найден
openapi.reports.invalid.cursor	Некорректный cursor
openapi.reports.client.blocked	Пользователь заблокирован