Вопросы
baas_support@qiwi.com
NAV Navbar
Примеры

HISTORY&NOTIFICATIONS API

Последнее обновление: 10-08-2022 |

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

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

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

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

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

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

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

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

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

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

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

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

Авторизация

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

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

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

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

Уведомления: общие сведения

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

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

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

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

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

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

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

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

Вычисление подписи

Для вычисления необходимы строковые представления "секрета" (secret) и подписываемых данных, т. е. тела запроса (data). Выполните следующие действия:

  1. Преобразуйте строки secret и data в байты UTF-8 secret_bytes и data_bytes, соответственно.
  2. Вызовите библиотечную реализацию алгоритма HmacSHA256 для вычисления байтового представления подписи:

    signature_bytes = HmacSHA256(secret_bytes, data_bytes).

  3. Закодируйте байты подписи в hex-представление и получите строку подписи:

    signature = hex(signature_bytes)

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

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

{
  "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 Снятие наличных через кассу банка
CASH_WITHDRAWAL_PURCHASE Снятие наличных при совершении покупки
REFUND_CASH_WITHDRAWAL_ATM Возврат средств по операции снятия наличных в банкомате
REFUND_CASH_WITHDRAWAL_CASHIER Возврат средств по операции снятия наличных через кассу банка
REFUND_CASH_WITHDRAWAL_PURCHASE Возврат средств по операции снятия наличных при совершении покупки
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 Сумма в оригинальной валюте для клиринга операции снятия наличных не соответствует сумме авторизации операции снятия наличных
DENIED_BY_PARTNER_ACL Авторизация отклонена, так как ее параметры соответствуют действующему блокирующему правилу, созданному партнёром. Либо параметры авторизации не соответствуют ни одному из действующих разрешающих правил, созданных партнером. Эта ошибка возможна только когда для партнера включена опция применения правил авторизации
DENIED_BY_BANK_ACL Авторизация отклонена, так как ее параметры соответствуют действующему блокирующему правилу, созданному QIWI. Эта ошибка возможна только когда для партнера включена опция применения правил авторизации

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

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

Поскольку технически выдача займа выполняется в отдельной транзакции, то в такой схеме партнер будет получать по два уведомления об авторизации: одно в рамках собственно авторизационной транзакции (тип операции 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

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

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 Снятие наличных через кассу банка
14 CASH_WITHDRAWAL_PURCHASE Снятие наличных при совершении покупки
8 REFUND_CASH_WITHDRAWAL_ATM Возврат по операции снятия наличных в банкомате
9 REFUND_CASH_WITHDRAWAL_CASHIER Возврат по операции снятия наличных через кассира
15 REFUND_CASH_WITHDRAWAL_PURCHASE Возврат средств по операции снятия наличных при совершении покупки
10 BALANCE_INQUIRY Запрос баланса
11 LOAN_ISSUE Выдача займа клиенту
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 Пользователь заблокирован