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

HISTORY&NOTIFICATIONS API

Последнее обновление: 05-10-2021 |

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

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

Взаимодействие с сервером партнера происходит по защищенному сетевому протоколу (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. В случае расхождения запрос следует игнорировать.

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

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

{
  "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 См. creationDateTime из ответа на запрос совершения платежа

Параметры, свойственные типу 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": "8141362354",
  "txnType": "PURCHASE_E_POS",
  "actionId": "hold-8141362354-ZGP638",
  "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"
  }
}

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

{
  "type": "AUTHORIZATION",
  "eventDateTime": "2020-08-12T13:24:45.601476+03:00",
  "txnId": "1701330945",
  "txnType": "PURCHASE_E_POS",
  "actionId": "hold-1701330945-GPM906",
  "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"
  }
}

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

{
    "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": "8141362354",
  "txnType": "PURCHASE_E_POS",
  "actionId": "hold-8141362354-ZGP638",
  "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"
  }
}

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

Поле уведомления Описание
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
authorizationDateTime Только для уведомлений с "type": "AUTHORIZATION". Дата онлайн-авторизации, которую передала платежная система.
retrievalReferenceNumber RRN
merchantId Идентификатор провайдера, который передала платежная система
cardAcceptorNameAndLocation Только для уведомлений с "type": "AUTHORIZATION". Имя провайдера и локация, которые передала платежная система.
merchantName Только для уведомлений с "type": "CLEARING". Имя провайдера, которое передала платежная система.
merchantType MCC
terminalId Идентификатор терминала, который передала платежная система
acquirerId Идентификатор эквайера, который передала платежная система
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"
        },
        "authorizationDateTime": "2021-06-08T18:06:29+03:00",
        "retrievalReferenceNumber": "005613823345",
        "merchantId": "SBOL",
        "cardAcceptorNameAndLocation": "VISAMONEYTRANSFER>VisaDirectLU",
        "merchantType": "4829",
        "terminalId": "99999999",
        "acquirerId": "402333"
    }
}

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

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

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

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

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

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

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

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

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

Справочники

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

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

Наименование Описание
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 Запрос баланса счета (обычно в банкомате)

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

Тип действия Описание Тип уведомления, в котором возвращается
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 идентификатором транзакции из ранее полученного от партнера подтверждения выдачи займа. Получение этого уведомления может являться основанием для принятия решения партнером о том, что займ был выдан (или не выдан) его клиенту.

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

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

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

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

Поле запроса Описание
actionId Идентификатор действия, которое произошло с операцией
cardTokenId Уникальный идентификатор (токен) карты
clientId Уникальный идентификатор пользователя, которому принадлежит карта
transactionAmount Блок с информацией о сумме операции в валюте счета (рубли)
value Значение суммы с двумя десятичными разрядами
currency Валюта: RUB
authorizationDateTime Дата онлайн-авторизации, которую передала платежная система.
retrievalReferenceNumber RRN
merchantId Идентификатор провайдера, который передала платежная система
cardAcceptorNameAndLocation Имя провайдера и локация, которые передала платежная система.
merchantType MCC
terminalId Идентификатор терминала, который передала платежная система
acquirerId Идентификатор эквайера, который передала платежная система
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") -
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 Идентификатор продукта: выдается партнеру при интеграции String ^[A-Za-z0-9-]{1,100}$ Prd-123-DEF-456 +
accountId Идентификатор счета в системе партнера: партнер передает id конкретного счета пользователя, созданного по Clients API, для которого необходимо получить историю операций String ^[A-Za-z0-9-]{1,100}$ Acc-123-DEF-456 +
limit См. раздел Пагинация       +
cursor См. раздел Пагинация       -
dateFrom Дата начала временного диапазона. Указывается при необходимости ограничить выборку операций определенным временным диапазоном DateTime в формате ISO 8601 4.3.2 datetime complete extended (Z, ±hh:mm)   2017-08-13T14:30:00+03:00 -
dateTill Дата окончания временного диапазона. Указывается при необходимости ограничить выборку операций определенным временным диапазоном 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". Это означает, что следующую выборку нужно делать именно с этой позиции: в нее попадут все операции, которые были совершены после указанной.

Указанная операция в выборку не попадет.

Ответ ←

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

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

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

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

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

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

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

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

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

Параметр Тип Описание
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 String Значение с двумя десятичными разрядами
currency String Валюта, ISO 4217: RUB
commissionAmount   Блок с информацией о комиссии, удержанной с пользователя
value String Значение с двумя десятичными разрядами
currency String Валюта, ISO 4217: RUB
cursor String См. раздел Пагинация

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

Параметр Тип Описание
cardTxnInfo   Блок с информацией о карте, по которой была совершена операция, и деталях карточного платежа или запроса баланса
cardTokenId String Уникальный идентификатор (токен) карты
maskedPan String Маскированный PAN. Пример: 4153****4697
merchantType String MCC
merchantId String ^([\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 Идентификатор провайдера/услуги, в пользу которого совершен платеж

Справочники

Домены

Домен Описание
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 Запрос баланса

Ошибки

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

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

{
    "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 Пользователь заблокирован