HISTORY&NOTIFICATIONS API
Последнее обновление: 28-02-2022 |
Интерфейс предназначен для получения истории операций и уведомлений о различных событиях.
Термины, используемые в тексте:
- пользовательский интерфейс — web-сайт или мобильное приложение;
- пользователь — клиент (физическое лицо), использующий интерфейс;
- партнер — юридическое лицо, использующее данный API с целью предоставить физическим лицам платежную функциональность в своем интерфейсе;
- провайдер — поставщик услуги.
Взаимодействие с сервером партнера происходит по защищенному сетевому протоколу (HTTPS).
Данные при запросах передаются в формате параметров HTTP-запроса в кодировке UTF-8. В ответ данные возвращаются в формате JSON.
Общая информация
Процессы проведения операций, инициированных из пользовательского интерфейса партнера, описаны в документации Payments API.
Процессы проведения операций, инициированных из интерфейса, не принадлежащего партнеру, описаны на этой странице.
Уведомления отправляются по транзакциям, которые обрабатываются асинхронно. По операциям, инициированным партнером, на которые возвращается синхронный ответ о статусе проведения (Пополнение счета пользователя с другого счета, Перевод между счетами пользователей) уведомления не отправляются.
Процесс проведения операции покупки с использованием карты
- Платежная система отправляет онлайн-авторизацию на совершение покупки. При успешной онлайн-авторизации происходит операция HOLD денежных средств пользователя. При этом денежные средства все еще могут стать доступны пользователю: они лишь зарезервированы.
- Для успешной онлайн-авторизации на совершение покупки платежная система может отправить онлайн-авторизацию отмены: REVERSAL. В рамках исходной онлайн-авторизации на совершение покупки происходит операция UNHOLD денежных средств на сумму отмены.
- Платежная система инициирует клиринг по ранее созданной онлайн-авторизации на совершение покупки. В рамках исходной онлайн-авторизации на совершение покупки происходит списание денежных средств на сумму, указанную в клиринге: CAPTURE. Здесь CAPTURE рассматривается как оффлайн-операция.
- Платежная система инициирует клиринг для покупки, по которой ранее не было онлайн-авторизации. При этом связи у данной покупки с какой-либо онлайн-авторизацией нет. Происходит резервирование и сразу же списание на сумму, указанную в клиринге: операции HOLD и CAPTURE. Здесь подобная операция рассматривается как оффлайн.
В клиринге может быть отражена операция возврата: REFUND. Она не имеет связи с исходной операцией (в отличие от REVERSAL, которая не отражается в клиринге). Это отдельная операция зачисления денежных средств от провайдера на счет пользователя.
Клиринг по одной и той же покупке может приходить несколько раз на разные суммы.
Взаимодействие через API
Авторизация
Поддерживаются только HTTPS-запросы. HTTP-запросы по нешифрованному каналу не поддерживаются.
Схема аутентификации - Bearer.
В заголовках запроса передаётся bearer-токен в поле Authorization
.
--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******"
Bearer-токен выдается партнеру при интеграции.
URL для вызовов API
- https://api-test.qiwi.com - testing окружение;
- https://api.qiwi.com - production окружение.
Уведомления — общая информация
Технически отправка уведомления — это POST-запрос по протоколу HTTP(S)
, выполняемому по адресу URL
, который партнер разово передает курирующему менеджеру.
Сервер на стороне партнера должен быть готов к приему таких запросов.
Адрес URL
уникален: для каждого productID
указывается свой URL
.
Запрос стандартно состоит из заголовков и тела. Тело запроса — строковое представление JSON-объекта, в котором содержатся данные входящего уведомления.
HEADERS
В принимаемом запросе необходимо анализировать заголовок QIWI-Signature
. Он содержит подпись, вычисленную по алгоритму "HmacSHA256" на основе "секрета" и тела запроса. "Секрет" в виде символьной строки предоставляется партнеру отдельно.
Необходимо обеспечить надежное хранение "секрета" и не допускать несанкционированный доступ к нему.
Сервер партнера при получении уведомления должен вычислить подпись на основе "секрета" и тела запроса, после чего сверить результат со значением, переданным в заголовке запроса QIWI-Signature
. В случае расхождения запрос следует игнорировать.
Уведомления об изменении статуса идентификации пользователя
Пример запроса
{
"type": "CLIENT_IDENTIFICATION_CHANGED",
"clientId": "d8ce63e4-2213-4574-92f3-66bf381529a2",
"oldIdentificationLevel": "NOT_VERIFIED",
"newIdentificationLevel": "FULL",
"changedAt": "2020-05-25T14:30:00+03:00",
"changeNumber": 25
}
Параметр | Описание |
---|---|
type | Тип уведомления: CLIENT_IDENTIFICATION_CHANGED (изменение статуса идентификации) |
clientId | Уникальный идентификатор пользователя |
oldIdentificationLevel | Предыдущий уровень идентификации пользователя |
newIdentificationLevel | Новый (текущий) уровень идентификации пользователя |
changedAt | Временная метка: указывает, когда произошла смена уровня идентификации |
changeNumber | Порядковый номер изменения. Несмотря на то, что это значение принадлежит к арифметической прогрессии с шагом равным единице и ведётся отдельно для каждого пользователя, уведомления могут приходить в произвольном порядке. Поле можно использовать для сортировки уведомлений и отбрасывания тех уведомлений, changeNumber которых меньше. |
Уведомления об операциях, инициированных из интерфейса партнера
Пример уведомления о пополнении счета пользователя с банковской карты
{
"type": "REPLENISHMENT_BY_WEBFORM",
"txnId": "56927813128178660527",
"txnType": "replenishment-by-webform",
"toClientId": "mismihtmdb6639011557",
"transactionAmount": {
"value": 2.9,
"currency": "RUB"
},
"clientCommission": {
"value": 100.0,
"currency": "RUB"
},
"status": "SUCCESS",
"statusDetails": {},
"creationDateTime": "2020-09-24T10:42:18+03:00"
}
Пример уведомления об оплате в пользу провайдера со счета пользователя
{
"type": "PAYMENT",
"txnId": "46829337545338664347",
"txnType": "payment",
"fromClientId": "jloungozcz2298040076",
"toProviderId": "uid30",
"toProviderData": {
"fields": {
"account": "3788673608"
}
},
"transactionAmount": {
"value": 2.9,
"currency": "RUB"
},
"clientCommission": {
"value": 100.0,
"currency": "RUB"
},
"status": "SUCCESS",
"statusDetails": {},
"creationDateTime": "2020-09-24T10:42:18+03:00"
}
Пример уведомления о переводе средств со счета пользователя на банковскую карту
{
"type": "WITHDRAWAL_TO_CARD",
"txnId": "46829337545338664347",
"txnType": "withdrawal-to-card",
"fromClientId": "jloungozcz2298040076",
"transactionAmount": {
"value": 2.9,
"currency": "RUB"
},
"clientCommission": {
"value": 100.0,
"currency": "RUB"
},
"status": "SUCCESS",
"statusDetails": {},
"creationDateTime": "2020-09-24T10:42:18+03:00"
}
Общие для всех типов уведомлений параметры
Параметр | Описание |
---|---|
type | Тип уведомления |
txnId | Идентификатор операции, по которой пришло уведомление |
txnType | Тип операции |
transactionAmount | Блок с информацией о сумме операции |
value | Значение с двумя десятичными разрядами |
currency | Валюта: RUB |
clientCommission | Блок с информацией о сумме комиссии, которая была удержана с пользователя (присутствует только для тех типов платежей, по которым настроена комиссия) |
value | Значение с двумя десятичными разрядами |
currency | Валюта: RUB |
status | Статус операции: см. статусы для домена PAYMENTS |
statusDetails | Если "Status": "SUCCESS" - пустой объект {} , если "Status": "DECLINED" — объект c полем failureCode |
creationDateTime | Дата создания операции в сервисе Payments. DateTime в формате ISO 8601 ±hh:mm с московской Time Zone |
Параметры, свойственные типу REPLENISHMENT_BY_WEBFORM
Параметр | Описание |
---|---|
toClientId | Идентификатор получателя платежа |
Параметры, свойственные типу PAYMENT
Параметр | Описание |
---|---|
fromClientId | Идентификатор пользователя, со счета которого происходит списание денежных средств |
toProviderId | Идентификатор провайдера/услуги, в пользу которого осуществляется платеж. Выдается партнеру при интеграции. |
toProviderData | Блок с доп. информацией, необходимой провайдеру для успешного проведения платежа |
account | Идентификатор пользователя на стороне провайдера |
Параметры, свойственные типу WITHDRAWAL_TO_CARD
Параметр | Описание |
---|---|
fromClientId | Идентификатор пользователя, со счета которого происходит списание денежных средств |
Типы уведомлений
Тип уведомления | Тип операции | Описание |
---|---|---|
REPLENISHMENT_BY_WEBFORM | replenishment-by-webform | Пополнение счета пользователя с банковской карты |
REPLENISHMENT_FROM_FUNDER | replenishment-from-external-processing-funder | Пополнение счета пользователя с другого счета, инициированное через другие протоколы QIWI |
PAYMENT | payment | Оплата в пользу провайдера со счета пользователя |
WITHDRAWAL_TO_CARD | withdrawal-to-card | Перевод со счета пользователя на банковскую карту |
Уведомления об операциях с использованием карты
Ознакомьтесь с процессом проведения покупки с использованием карты.
Реализованы перечисленные по ссылке типы уведомлений.
Ответ ←
При получении и обработке уведомления сервер партнера должен вернуть HTTP-код в диапазоне от 200
до 299
. Если сервер вернет код, не входящий в этот диапазон, либо если системе не удалось выполнить отправку запроса на сервер партнёра, уведомление будет отложено до следующей попытки. Система будет повторять попытки отправки уведомления с некоторой периодичностью в течение некоторого времени.
Покупка
Пример уведомления по успешной онлайн-авторизации
{
"type": "AUTHORIZATION",
"eventDateTime": "2020-08-12T13:14:23.706284+03:00",
"txnId": "1436d6fb-17ac-6836-3252-779b702cca11",
"txnType": "PURCHASE_E_POS",
"actionId": "879e12ca-476a-4726-a5fb-e3c4546e47f1",
"actionType": "HOLD",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "100074268301",
"clientId": "1",
"transactionAmount": {
"currency": "RUB",
"value": "7.28"
},
"authorizationDateTime": "2020-08-12T13:14:16+03:00",
"retrievalReferenceNumber": "008141362354",
"merchantId": "498750000011107",
"cardAcceptorNameAndLocation": "MIKROMARKET>MOSCOW",
"merchantType": "5499",
"terminalId": "99999999",
"acquirerId": "498750",
"correlationId": "879e12ca-476a-4726-a5fb-e3c4546e47f1"
}
}
Пример уведомления по неуспешной онлайн-авторизации
{
"type": "AUTHORIZATION",
"eventDateTime": "2020-08-12T13:24:45.601476+03:00",
"txnId": "e9ebd6fb-f7ac-4736-8752-d79b702ccace",
"txnType": "PURCHASE_E_POS",
"actionId": "d872a658-d07f-42f3-84dc-9f940b1a54ee",
"actionType": "HOLD",
"actionStatus": "FAILED",
"actionStatusDetails": {
"failureCode": "ACCOUNT_BALANCE_INSUFFICIENT_FUNDS"
},
"actionData": {
"cardTokenId": "100074267865",
"clientId": "1",
"transactionAmount": {
"currency": "RUB",
"value": "8.52"
},
"authorizationDateTime": "2020-08-12T13:24:40+03:00",
"retrievalReferenceNumber": "001701330945",
"merchantId": "498750000011107",
"cardAcceptorNameAndLocation": "MIKROMARKET>MOSCOW",
"merchantType": "5499",
"terminalId": "99999999",
"acquirerId": "498750",
"correlationId": "d872a658-d07f-42f3-84dc-9f940b1a54ee"
}
}
Пример уведомления по успешной оффлайн-операции
{
"type": "CLEARING",
"eventDateTime": "2020-11-08T19:46:47.547972+03:00",
"txnId": "0b1f21da-890a-4083-ba08-1415eed9cd4b",
"txnType": "PURCHASE_POS",
"actionId": "3c10a347-7095-415e-835c-da3f34fd3a2b",
"actionType": "CAPTURE_HOLD",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "100074276831",
"clientId": "c8193105661",
"clearingDate": "2020-11-08",
"transactionAmount": {
"currency": "RUB",
"value": "100.00"
},
"originTransactionAmount": {
"currency": "USD",
"value": "1.29"
},
"retrievalReferenceNumber": "005710141565",
"merchantId": "781000007913 ",
"merchantName": "MIKROMARKET>MOSCOW",
"merchantType": "5499",
"terminalId": "20733084",
"acquirerId": "427600",
"multiClearingData": {
"partNumber": 1,
"partTotalCount": 2
}
}
}
Пример уведомления об операции покупки в валюте
{
"type": "AUTHORIZATION",
"eventDateTime": "2020-08-12T13:14:23.706284+03:00",
"txnId": "0fa734d0-c03b-4681-9365-65e55e10f002",
"txnType": "PURCHASE_E_POS",
"actionId": "ba3ae9f1-0f82-49e7-be16-ecd0add4407c",
"actionType": "HOLD",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "100074268301",
"clientId": "1",
"transactionAmount": {
"currency": "RUB",
"value": "73.28"
},
"originTransactionAmount": {
"currency": "USD",
"value": "1.00"
},
"authorizationDateTime": "2020-08-12T13:14:16+03:00",
"retrievalReferenceNumber": "008141362354",
"merchantId": "498750000011107",
"cardAcceptorNameAndLocation": "MIKROMARKET>MOSCOW",
"merchantType": "5499",
"terminalId": "99999999",
"acquirerId": "498750",
"correlationId": "ba3ae9f1-0f82-49e7-be16-ecd0add4407c"
}
}
Структура уведомлений об операциях с использованием карты
Поле уведомления | Описание |
---|---|
type | Тип уведомления |
eventDateTime | Дата уведомления в формате ISO 8601 |
txnId | Идентификатор операции, по которой пришло уведомление |
txnType | Тип операции, для которой сформировано уведомление |
actionId | Идентификатор действия, которое произошло с операцией |
actionType | Тип действия, которое произошло с операцией |
actionStatus | Статус действия, которое произошло с авторизацией |
actionStatusDetails | Пустой объект {} , если "actionStatus": "SUCCESS" Объект c полем failureCode, если "actionStatus": "FAILED" . Это значит, что в момент проведения операции возникла ошибка. См. пример уведомления по неуспешной онлайн-авторизации. |
actionData | Блок с описанием деталей операции |
cardTokenId | Уникальный идентификатор (токен) карты |
clientId | Уникальный идентификатор пользователя, которому принадлежит карта |
partnerTxnId | Идентификатор транзакции, переданный партнером в ответе-подтверждении на запрос выдачи займа клиенту |
transactionAmount | Блок с информацией о сумме операции в валюте счета (рубли). Сумма операции не включает в себя комиссию, которая была удержана с пользователя. |
value | Значение суммы с двумя десятичными разрядами |
currency | Валюта: RUB |
clientCommission | Блок с информацией о сумме комиссии, которая была удержана с пользователя. |
value | Значение суммы с двумя десятичными разрядами |
currency | Валюта: RUB |
partnerCommission | Блок с информацией о сумме комиссии, которая была удержана со специального счета партнера при выдаче займа клиенту. |
value | Значение суммы с двумя десятичными разрядами |
currency | Валюта: RUB |
authorizationDateTime | Только для уведомлений с "type": "AUTHORIZATION" . Дата онлайн-авторизации, которую передала платежная система. |
retrievalReferenceNumber | RRN |
merchantId | Идентификатор провайдера, который передала платежная система |
cardAcceptorNameAndLocation | Только для уведомлений с "type": "AUTHORIZATION" . Имя провайдера и локация, которые передала платежная система. |
merchantName | Только для уведомлений с "type": "CLEARING" . Имя провайдера, которое передала платежная система. |
merchantType | MCC |
terminalId | Идентификатор терминала, который передала платежная система |
acquirerId | Идентификатор эквайера, который передала платежная система |
correlationId | Идентификатор, позволяющий объединить уведомления и запросы в логически связанную группу операций |
clearingDate | Только для уведомлений с "type": "CLEARING" . Дата клиринга (расчета) по карточной операции. |
originTransactionAmount | Блок с информацией по оригинальной сумме и валюте операции |
currency | Оригинальная валюта операции |
value | Значение оригинальной суммы операции, с двумя десятичными разрядами |
multiClearingData | Опционально. Только для уведомлений с "type": "CLEARING" . Присутствует в случе, когда клиринг является нефинальным (мультиклиринг): произошло списание лишь части изначально захолдированных денежных средств. |
partNumber | Неупорядоченный номер части мультиклиринг-операции. Нумерация начинается с 1. |
partTotalCount | Ожидаемое количество всех частей мультиклиринг-операции. Минимальное значение равно 1. |
wasNotAuthorizedBefore | Опционально. Только для уведомлений с "type": "CLEARING" , когда параметр actionType равен либо CAPTURE_FAST_FUNDS , либо CAPTURE_FAST_FUNDS_REVERSAL . Логический признак того, что было произведено пополнение по номеру карты в онлайн-операции ("type": "AUTHORIZATION" , "txnType": "FAST_FUNDS" , "actionType": "FAST_FUNDS" ), либо была совершена отмена пополнения по номеру карты в онлайн-операции ("type": "AUTHORIZATION" , "txnType": "FAST_FUNDS" , "actionType": "FAST_FUNDS_REVERSAL" ). Возможные значения:false — движения денежных средств в рамках этого уведомления совершено не было (оно произошло при обработке онлайн-операции);true — денежные средства были зачислены на счет пользователя в рамках этой оффлайн-операции (онлайн-операции пополнения карты не было). |
accountBalance | Опционально. Только для уведомлений с "txnType": "BALANCE_INQUIRY" и "actionType": "BALANCE_INQUIRY" , либо "txnType": "CASH_WITHDRAWAL_ATM" , "txnType": "CASH_WITHDRAWAL_CASHIER" и "actionType": "CASH_WITHDRAWAL_HOLD" , либо "txnType": "LOAN_ISSUE" и "actionType": "LOAN_ISSUE" . Блок с информацией о сумме остатка на счете и валюте счета:- в случае операции с "actionType": "CASH_WITHDRAWAL_HOLD" — сумма остатка на счете после проведения операции авторизации;- в случае операции с "actionType": "BALANCE_INQUIRY" — текущая сумма остатка на счете;- в случае операции с "actionType": "LOAN_ISSUE" — сумма остатка на счете до запроса займа. |
Возврат
Пример уведомления о возврате средств с использованием интернет-эквайринга
{
"type": "CLEARING",
"eventDateTime": "2020-12-02T15:01:20.908945+03:00",
"txnId": "745f0970-258c-41c1-afbd-da23401795b9",
"txnType": "REFUND_E_POS",
"actionId": "599c3285-5f36-4eca-bace-c31db3989636",
"actionType": "CAPTURE_REFUND",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "100075717766",
"clientId": "xpemmwmewf0077828490",
"clearingDate": "2020-12-02",
"transactionAmount": {
"currency": "RUB",
"value": "9.04"
},
"originTransactionAmount": {
"currency": "RUB",
"value": "9.04"
},
"merchantId": "544521933108",
"merchantName": "MIKROMARKET",
"merchantType": "3492",
"terminalId": "02614260",
"acquirerId": "646114"
}
}
Пополнение
Пример уведомления об операции пополнения по номеру карты (онлайн-операция)
{
"type": "AUTHORIZATION",
"eventDateTime": "2021-06-08T18:06:38.84364+03:00",
"txnId": "edf9e5db-3fa1-4730-8259-4ac04ac2d2bd",
"txnType": "FAST_FUNDS",
"actionId": "ccc0859a-e714-4650-b55e-ac46aad8a904",
"actionType": "FAST_FUNDS",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "100078557896",
"clientId": "fauqjsjdof5724234527",
"transactionAmount": {
"currency": "RUB",
"value": "3.08"
},
"originTransactionAmount": {
"currency": "RUB",
"value": "3.08"
},
"authorizationDateTime": "2021-06-08T18:06:29+03:00",
"retrievalReferenceNumber": "005613823345",
"merchantId": "SBOL",
"cardAcceptorNameAndLocation": "VISAMONEYTRANSFER>VisaDirectLU",
"merchantType": "4829",
"terminalId": "99999999",
"acquirerId": "402333",
"correlationId": "ccc0859a-e714-4650-b55e-ac46aad8a904"
}
}
Пример уведомления об операции пополнения по номеру карты (оффлайн-операция)
{
"type": "CLEARING",
"eventDateTime": "2021-06-08T18:53:00.765517+03:00",
"txnId": "6e652168-7bf5-4b0f-a3c8-9976e2a653d7",
"txnType": "FAST_FUNDS",
"actionId": "0a40efa1-9862-438b-9d56-c38222f182fe",
"actionType": "CAPTURE_FAST_FUNDS",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "100078560498",
"clientId": "egfbiaclzz1241737707",
"clearingDate": "2021-06-08",
"transactionAmount": {
"currency": "RUB",
"value": "3.29"
},
"originTransactionAmount": {
"currency": "RUB",
"value": "3.29"
},
"merchantId": "351771137636",
"merchantName": "TEST_MERCHANT_NAME",
"merchantType": "1553",
"terminalId": "83872934",
"acquirerId": "295503",
"wasNotAuthorizedBefore": true
}
}
Снятие наличных
Пример уведомления об операции снятия наличных (онлайн-операция)
{
"type": "AUTHORIZATION",
"eventDateTime": "2021-08-04T16: 30: 49.781279+03: 00",
"txnId": "9c9f3877-97b6-4265-b1f0-57c69036dc93",
"txnType": "CASH_WITHDRAWAL_ATM",
"actionId": "2f5062bd-bd2f-4988-9f85-dfa15bb891f6",
"actionType": "CASH_WITHDRAWAL_HOLD",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "100079222878",
"clientId": "gvmbgpkrxu7686940477",
"transactionAmount": {
"currency": "RUB",
"value": "8.56"
},
"clientCommission": {
"currency": "RUB",
"value": "0.00"
},
"originTransactionAmount": {
"currency": "RUB",
"value": "8.56"
},
"accountBalance": {
"currency": "RUB",
"value": "3.52"
},
"authorizationDateTime": "2021-08-04T16: 30: 39+03: 00",
"retrievalReferenceNumber": "009966696813",
"merchantId": "VB24",
"cardAcceptorNameAndLocation": "VB24>SANKT-PETERBURU",
"merchantType": "6011",
"terminalId": "99999999",
"acquirerId": "471461",
"correlationId": "2f5062bd-bd2f-4988-9f85-dfa15bb891f6"
}
}
Пример уведомления об операции снятия наличных (оффлайн-операция)
{
"type": "CLEARING",
"eventDateTime": "2021-09-20T15:41:12.339933+03:00",
"txnId": "438a86a6-b1d4-4a6b-afbd-e2983585d10a",
"txnType": "CASH_WITHDRAWAL_ATM",
"actionId": "00c74370-98a0-4c5e-b6b8-a53ff3fa89fb",
"actionType": "CAPTURE_CASH_WITHDRAWAL_HOLD",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "100079217733",
"clientId": "toobbnnpwb2282661650",
"clearingDate": "2021-09-20",
"transactionAmount": {
"currency": "RUB",
"value": "100000.00"
},
"originTransactionAmount": {
"currency": "RUB",
"value": "100000.00"
},
"merchantId": "436482220316",
"merchantName": "TEST_MERCHANT_NAME",
"merchantType": "1327",
"terminalId": "39915295",
"acquirerId": "604319"
}
}
Пример уведомления об отмене операции снятия наличных (онлайн-операция)
{
"type": "AUTHORIZATION",
"eventDateTime": "2021-09-20T15:40:53.234782+03:00",
"txnId": "51db107a-4711-4427-965f-aa2dd4184673",
"txnType": "CASH_WITHDRAWAL_ATM",
"actionId": "b9f94ebe-986c-4e02-8054-8e0ceccded25",
"actionType": "CASH_WITHDRAWAL_REVERSAL",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "100079220757",
"clientId": "uflpniliwd0929192436",
"transactionAmount": {
"currency": "RUB",
"value": "100000.00"
},
"clientCommission": {
"currency": "RUB",
"value": "0.00"
},
"originTransactionAmount": {
"currency": "RUB",
"value": "100000.00"
},
"authorizationDateTime": "2021-09-20T15:40:47+03:00",
"retrievalReferenceNumber": "008371274064",
"merchantId": "VB24 ",
"cardAcceptorNameAndLocation": "VB24 >SANKT-PETERBU RU",
"merchantType": "6011",
"terminalId": "99999999",
"acquirerId": "471461",
"correlationId": "b9f94ebe-986c-4e02-8054-8e0ceccded25"
}
}
Пример уведомления об отмене операции снятия наличных (оффлайн-операция)
{
"type": "CLEARING",
"eventDateTime": "2021-09-20T15:41:01.11133+03:00",
"txnId": "7a195984-d098-47e9-81f2-8f4f51cf35ec",
"txnType": "REFUND_CASH_WITHDRAWAL_ATM",
"actionId": "2e0b3181-2369-4550-b3a6-de792ce0cac3",
"actionType": "CAPTURE_CASH_WITHDRAWAL_REFUND",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "100079216564",
"clientId": "koikfgthpw2108201601",
"clearingDate": "2021-09-20",
"transactionAmount": {
"currency": "RUB",
"value": "60000.01"
},
"originTransactionAmount": {
"currency": "RUB",
"value": "60000.01"
},
"merchantId": "669280139004",
"merchantName": "TEST_MERCHANT_NAME",
"merchantType": "3097",
"terminalId": "79249934",
"acquirerId": "604527"
}
}
Пример уведомления об онлайн-операции списания с карты для перевода на карту или счет (AFT)
{
"type": "AUTHORIZATION",
"eventDateTime": "2022-02-15T14:28:53.459536+03:00",
"txnId": "db828678-b5db-473f-bebb-97383c496394",
"txnType": "P2P_DEBIT",
"actionId": "d5e30bbb-4e70-4410-81e2-e093e2910287",
"actionType": "HOLD",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "999822534020",
"clientId": "rresnbfy09650312",
"transactionAmount": {
"currency": "RUB",
"value": "5.42"
},
"originTransactionAmount": {
"currency": "RUB",
"value": "5.42"
},
"authorizationDateTime": "2022-02-15T14:28:50+03:00",
"retrievalReferenceNumber": "006051743846",
"merchantId": "809215 ",
"cardAcceptorNameAndLocation": "CARD2CARD BANK_MOBILE>MOSCOW RU",
"merchantType": "5499",
"terminalId": "809216 ",
"acquirerId": "498750",
"correlationId": "d5e30bbb-4e70-4410-81e2-e093e2910287"
}
}
Пример уведомления об оффлайн-операции списания с карты для перевода на карту или счет (AFT)
{
"type": "CLEARING",
"eventDateTime": "2022-02-15T15:05:34.214314+03:00",
"txnId": "ffc9d97c-1b61-4738-a5e4-d8502b818fba",
"txnType": "P2P_DEBIT",
"actionId": "0088aab9-1cde-4120-8c1f-ea82453d2a9b",
"actionType": "CAPTURE_HOLD",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "999178641952",
"clientId": "njbzudbnvd8065253135",
"clearingDate": "2022-02-15",
"transactionAmount": {
"currency": "RUB",
"value": "2.74"
},
"originTransactionAmount": {
"currency": "RUB",
"value": "2.74"
},
"retrievalReferenceNumber": "003885464570",
"merchantId": "809215 ",
"merchantName": "CARD2CARD BANK_MOBILE>MOSCOW RU",
"merchantType": "5499",
"terminalId": "809216",
"acquirerId": "498750"
}
}
Запрос баланса по счету карты
Пример уведомления об операции запроса баланса
{
"type": "AUTHORIZATION",
"eventDateTime": "2021-09-20T14:33:13.088799+03:00",
"txnId": "4e2b3c60-0eac-4cf6-9619-20550e544616",
"txnType": "BALANCE_INQUIRY",
"actionId": "b026c332-ebcf-40dc-a2ae-97329f4e3624",
"actionType": "BALANCE_INQUIRY",
"actionStatus": "SUCCESS",
"actionStatusDetails": {},
"actionData": {
"cardTokenId": "100079219025",
"clientId": "vgkmnvzrac5063019183",
"transactionAmount": {
"currency": "RUB",
"value": "0.00"
},
"originTransactionAmount": {
"currency": "RUB",
"value": "0.00"
},
"accountBalance": {
"currency": "RUB",
"value": "1.42"
},
"authorizationDateTime": "2021-09-20T14:33:12+03:00",
"retrievalReferenceNumber": "003174424677",
"merchantId": "VB24 ",
"cardAcceptorNameAndLocation": "VB24 >SANKT-PETERBU RU",
"merchantType": "6011",
"terminalId": "99999999",
"acquirerId": "471461",
"correlationId": "d5e30bbb-4e70-4410-81e2-e093e2910287"
}
}
Справочники
Типы уведомлений
Описывает тип события, совершенного в рамках операции с использованием карты.
Наименование | Описание |
---|---|
AUTHORIZATION | Онлайн-авторизация |
CLEARING | Оффлайн-операция |
Типы операций с использованием карты
Тип операции | Описание |
---|---|
PURCHASE_E_POS | Покупка в интернете |
PURCHASE_POS | Покупка посредством наземного эквайринга |
REFUND_E_POS | Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием интернет-эквайринга |
REFUND_POS | Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием наземного эквайринга |
FAST_FUNDS | Пополнение по номеру карты |
LOAN_ISSUE | Выдача займа клиенту |
CASH_WITHDRAWAL_ATM | Снятие наличных в банкомате |
CASH_WITHDRAWAL_CASHIER | Снятие наличных через кассу банка |
REFUND_CASH_WITHDRAWAL_ATM | Возврат средств по операции снятия наличных в банкомате |
REFUND_CASH_WITHDRAWAL_CASHIER | Возврат средств по операции снятия наличных через кассу банка |
BALANCE_INQUIRY | Запрос баланса счета (обычно в банкомате) |
P2P_DEBIT | Списание с карты для перевода на карту или счет (AFT) |
REFUND_P2P_DEBIT | Возврат списания с карты для перевода на карту или счет (AFT) |
Типы действия, которое произошло с операцией
Тип действия | Описание | Тип уведомления, в котором возвращается |
---|---|---|
HOLD | Резервирование денежных средств | AUTHORIZATION |
REVERSAL | Отмена резерва | AUTHORIZATION |
CAPTURE_HOLD | Списание денежных средств | CLEARING |
CAPTURE_REFUND | Зачисление денежных средств по причине возврата от провайдера | CLEARING |
FAST_FUNDS | Пополнение по номеру карты | AUTHORIZATION |
FAST_FUNDS_REVERSAL | Отмена пополнения по номеру карты (техническое событие, инициируется платежной системой) | AUTHORIZATION |
CAPTURE_FAST_FUNDS | Клиринг по операции пополнения по номеру карты | CLEARING |
CAPTURE_FAST_FUNDS_REVERSAL | Клиринг по отмене пополнения по номеру карты | CLEARING |
LOAN_ISSUE | Выдача займа клиенту в ходе авторизации платежа | AUTHORIZATION |
CASH_WITHDRAWAL_HOLD | Авторизация по снятию наличных | AUTHORIZATION |
CASH_WITHDRAWAL_REVERSAL | Отмена авторизация по снятию наличных | AUTHORIZATION |
CAPTURE_CASH_WITHDRAWAL_HOLD | Клиринг по операции снятия наличных | CLEARING |
CAPTURE_CASH_WITHDRAWAL_REFUND | Клиринг по отмене операции снятия наличных | CLEARING |
BALANCE_INQUIRY | Запрос баланса по счету карты |
Статусы действия
Статус | Описание |
---|---|
SUCCESS | Успешно: финальный статус |
FAILED | Неуспешно: финальный статус. В процессе выполнения произошла ошибка |
Справочник кодов ошибок авторизаций
Код | Описание |
---|---|
INTERNAL_ERROR |
Внутренняя/сервисная ошибка |
LIMITS_EXCEEDED |
Лимиты (на оборот, на 1 операцию) нарушены |
ACCOUNT_BALANCE_INSUFFICIENT_FUNDS |
Недостаточно средств |
ACCOUNT_BALANCE_EXCEEDED |
Превышен допустимый лимит остатка на балансе |
CLIENT_BLOCKED |
Пользователь заблокирован |
WRONG_CURRENCY |
Некорректная/неподдерживаемая валюта |
WRONG_IDENTIFICATION |
Некорректный/неподдерживаемый уровень идентификации для совершения данного действия |
REVERSAL_AMOUNT_EXCEEDS_HOLD_AMOUNT |
Сумма отмены превысила сумму захолдированных по операции средств |
FAST_FUNDS_REVERSAL_AMOUNT_NOT_EQUAL_FAST_FUNDS_AMOUNT |
Сумма отмены операции пополнения по номеру карты не соответствует сумме операции пополнения по номеру карты |
LOAN_ISSUE_REJECTED |
Клиенту было отказано в выдаче займа в ходе авторизации платежа |
CASH_WITHDRAWAL_REVERSAL_AMOUNT_NOT_EQUAL_CASH_WITHDRAWAL_HOLD_AMOUNT |
Сумма отмены операции снятия наличных не соответствует сумме операции снятия наличных |
CASH_WITHDRAWAL_CAPTURE_AMOUNT_NOT_EQUAL_CASH_WITHDRAWAL_HOLD_AMOUNT |
Сумма в оригинальной валюте для клиринга операции снятия наличных не соответствует сумме авторизации операции снятия наличных |
Выдача займа клиенту
При авторизации платежа, если у пользователя не хватает средств на карте, ему может быть предоставлен займ на недостающую сумму. Средства списываются со специального счета партнера, чьим клиентом является пользователь. Сервис предоставляется при заключении дополнительного соглашения с партнером.
Поскольку технически выдача займа выполняется в отдельной транзакции, то в такой схеме партнер будет получать по два уведомления об авторизации: одно в рамках собственно авторизационной транзакции (тип операции PURCHASE_POS
или PURCHASE_E_POS
), другое — в рамках транзакции выдачи займа (тип операции LOAN_ISSUE
).
Процесс выдачи займа состоит из следующих шагов:
- Если при авторизации платежа видно, что средств на балансе покупателя недостаточно, сервис проверяет наличие недостающей суммы на балансе специального счета партнера (для займов), включая комиссию, рассчитанную согласно договору с партнером.
- Если средств недостаточно, то авторизация платежа отклоняется с двумя уведомлениями партнеру о неуспешной операции (авторизации/выдачи займа) с кодом ошибки
ACCOUNT_BALANCE_INSUFFICIENT_FUNDS
. - Если средств достаточно, сервис отправляет партнеру запрос на подтверждение выдачи займа покупателю в размере недостающей суммы.
- В ответе от партнера сервис ожидает подтверждение или отказ в выдаче займа. В случае отказа авторизация платежа отклоняется с двумя уведомлениями партнеру о неуспешной операции (авторизации/выдачи займа) с кодом ошибки
LOAN_ISSUE_REJECTED
. В случае подтверждения, необходимая сумма переводится со специального счета партнера на счет покупателя. - Авторизация платежа продолжается. В результате партнер получает два уведомления:
- Уведомление с типом действия
HOLD
об успешности проведения авторизации платежа. - Уведомление с типом действия
LOAN_ISSUE
об успешности операции выдачи займа покупателю. В нем будут присутствовать дополнительные поля:- поле
actionData.partnerTxnId
c идентификатором транзакции из ранее полученного от партнера подтверждения выдачи займа; - поле
actionData.partnerCommission
c суммой комиссии, удержанной с партнера в п. 1.
При получении этого уведомления партнер может принять решение о том, что займ был выдан (или не выдан) его клиенту.
- поле
- Уведомление с типом действия
В запросе на подтверждение выдачи займа покупателю, а также во всех уведомлениях, поступающих в процессе выдачи займа, будет присутствовать поле correlationId
. Значение поля — идентификатор, с помощью которого можно объединить все уведомления и исходный запрос в логически связанную группу операций.
Формат запроса
Пример тела запроса партнеру на выдачу займа
{
"clientId": "1",
"cardTokenId": "100074268301",
"transactionAmount": {
"currency": "RUB",
"value": "53.00"
},
"clientDebtAmount": {
"currency": "RUB",
"value": "15.00"
},
"insufficientAmount": {
"currency": "RUB",
"value": "68.00"
},
"txnId": "8141362354",
"actionId": "hold-8141362354-ZGP638",
"originTransactionAmount": {
"currency": "RUB",
"value": "53.00"
},
"authorizationDateTime": "2020-08-12T13:14:16+03:00",
"retrievalReferenceNumber": "008141362354",
"merchantId": "498750000011107",
"merchantType": "5499",
"cardAcceptorNameAndLocation": "MIKROMARKET>MOSCOW",
"acquirerId": "498750",
"terminalId": "99999999",
"correlationId": "879e12ca-476a-4726-a5fb-e3c4546e47f1"
}
Обработка и формат запроса аналогичны другим уведомлениям. Время ожидания ответа от партнера составляет не более 500 миллисекунд.
Поле запроса | Описание |
---|---|
actionId | Идентификатор действия, которое произошло с операцией |
cardTokenId | Уникальный идентификатор (токен) карты |
clientId | Уникальный идентификатор пользователя, которому принадлежит карта |
transactionAmount | Блок с информацией о сумме операции в валюте счета (рубли) |
value | Значение суммы с двумя десятичными разрядами |
currency | Валюта: RUB |
authorizationDateTime | Дата онлайн-авторизации, которую передала платежная система |
retrievalReferenceNumber | RRN |
merchantId | Идентификатор провайдера, который передала платежная система |
cardAcceptorNameAndLocation | Имя провайдера и локация, которые передала платежная система. |
merchantType | MCC |
terminalId | Идентификатор терминала, который передала платежная система |
acquirerId | Идентификатор эквайера, который передала платежная система |
correlationId | Идентификатор, позволяющий объединить уведомления и запросы в логически связанную группу операций |
originTransactionAmount | Блок с информацией по оригинальной сумме и валюте операции |
currency | Оригинальная валюта операции |
value | Значение оригинальной суммы операции, с двумя десятичными разрядами |
clientDebtAmount | Блок с информацией о сумме задолженности на счету покупателя на момент авторизации платежа. Сумма может быть больше или равна нулю |
currency | Оригинальная валюта суммы задолженности |
value | Значение оригинальной суммы задолженности, с двумя десятичными разрядами |
insufficientAmount | Блок с информацией о сумме, недостающей покупателю для успешного проведения авторизации платежа. Сумма всегда больше нуля |
currency | Оригинальная валюта недостающей суммы |
value | Значение оригинальной недостающей суммы, с двумя десятичными разрядами |
Формат ответа
Пример тела ответа партнера на запрос займа
{
"status": "APPROVED",
"statusDetails": {
"productId": "Prd-123-DEF-456",
"clientId": "1",
"accountId": "Acc-123-DEF-456",
"partnerTxnId": "14e7c47d-8151-48a7-9a4f-d67d2566fec9",
"loanAmount": {
"currency": "RUB",
"value": "68.00"
}
}
}
При получении и обработке запроса сервер партнера должен вернуть HTTP-код в диапазоне от 200 до 299 и JSON со следующей структурой:
Поле ответа | Описание |
---|---|
status | Статус решения партнера о предоставлении займа клиенту: APPROVED или REJECTED |
statusDetails | Блок с дополнительной информацией. При передаче поля "status": "APPROVED" все поля блока должны быть заполнены. В случае передачи "status": "REJECTED" блок не заполняется. |
productId | Идентификатор продукта: выдается партнеру при интеграции |
clientId | Уникальный идентификатор пользователя, которому принадлежит карта. Должен быть идентичен clientId , переданному в запросе |
accountId | Уникальный идентификатор счета клиента в системе партнера; счет должен принадлежать клиенту clientId |
partnerTxnId | Уникальный идентификатор операции выдачи займа, зарегистрированной в системе партнера |
loanAmount | Блок с информацией о сумме выдаваемого займа. Структура и содержание должны быть идентичны блоку insufficientAmount , переданному в запросе |
Уведомления о блокировке карты
Пример уведомления о блокировке карты
{
"type":"CARD_WAS_BLOCKED",
"clientId":"1",
"cardTokenId":"100074269512",
"blockSource":"PARTNER_API",
"blockedAt":"2020-08-24T18:22:34.974+03:00"
}
Поле уведомления | Описание |
---|---|
type | Тип уведомления: CARD_WAS_BLOCKED (блокировка карты) |
clientId | Уникальный идентификатор пользователя, которому принадлежит карта |
cardTokenId | Уникальный идентификатор (токен) карты |
blockSource | Источник блокировки |
blockedAt | Дата блокировки в формате ISO 8601 ±hh:mm с московской Time Zone |
История операций
Метод возвращает список всех операций, совершенных с использованием конкретного счета пользователя. Речь идет как о карточных авторизациях, проведенных платежными системами, так и об операциях, инициированных из интерфейса партнера.
История возвращает перечисленные типы операций.
Запрос → GET
URL /partner/openapi-reports/v1/products/{productId}/operations/history?accountId={accountId}&limit={limit}&cursor={cursor}&dateFrom={dateFrom}&dateTill={dateTill}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-reports/v1/products/best-partner/operations/history?accountId=cdvvgtdiiu6310024653&limit=100 \
-X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
Пример запроса с пагинацией и начальной позицией
curl https://api-test.qiwi.com/partner/openapi-reports/v1/products/best-partner/openapi-reports/v1/products/best-partner/operations/history?accountId=cdvvgtdiiu6310024653&limit=100&cursor=5379a6e7-50c6-48fe-3db4-d10be301f76d \
-X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
Параметр | Описание | REGEX | Пример |
---|---|---|---|
productId | Обязательный параметр URL запроса. Идентификатор продукта: выдается партнеру при интеграции | ^[A-Za-z0-9-]{1,100}$ |
Prd-123-DEF-456 |
accountId | Обязательный параметр URL запроса. Идентификатор счета в системе партнера: партнер передает id счета пользователя, созданного по Clients API, по которому необходимо получить историю операций | ^[A-Za-z0-9-]{1,100}$ |
Acc-123-DEF-456 |
limit | Обязательный параметр URL запроса. Размер выборки. См. подробнее раздел Пагинация | ||
cursor | Параметр URL запроса. Позиция начального элемента списка операций из предыдущего запроса. См. подробнее раздел Пагинация | ||
dateFrom | Параметр URL запроса. Дата начала временного диапазона. Указывается при необходимости ограничить выборку операций определенным временным диапазоном | DateTime в формате ISO 8601 4.3.2 datetime complete extended (Z, ±hh:mm ) |
2017-08-13T14:30:00+03:00 |
dateTill | Параметр URL запроса. Дата окончания временного диапазона. Указывается при необходимости ограничить выборку операций определенным временным диапазоном | DateTime в формате ISO 8601 4.3.2 datetime complete extended (Z, ±hh:mm ) |
2017-08-13T14:30:00+03:00 |
Пагинация
Параметр limit
определяет количество операций, которое необходимо вернуть в одном txnList
. Минимум — 1
, максимум — 200
. Если в запросе будет указан limit
> 200, в txnList
вернется не более 200 операций.
Параметр cursor
определяет позицию, начиная с которой будет произведена выборка операций для выдачи в ответе на запрос истории. Например, если в ответе вернулся "cursor":"5379a6e7-50c6-48fe-3db4-d10be301f76d"
, то последняя операция, полученная в истории, имеет идентификатор "txnHistoryId": "5379a6e7-50c6-48fe-3db4-d10be301f76d"
. Это означает, что следующую выборку нужно делать именно с этой позиции: в нее попадут все операции, которые были совершены после указанной. Сама указанная операция в выборку не попадет.
Ответ ←
Пример ответа: покупка в интернете с использованием карты.
{
"txnList" : [ {
"commonTxnInfo" : {
"txnHistoryId" : "98478192-19a9-decc-092a-468dab0afabb",
"domain" : "CARDS",
"domainTxnId" : "2740a95f-2cfd-49b8-b39f-534a1be4b18d",
"domainTxnStatus" : {
"domainTxnStatusId" : "1",
"name" : "PROCESSING"
},
"txnType" : {
"domainTxnTypeId" : "2",
"name" : "PURCHASE_E_POS"
},
"txnClientBalanceImpact" : "EXPENSE",
"clientId" : "mxmyrdxxxx8585680090",
"accountId" : "xxxxxxzsp7009773700",
"productId" : "best-partner",
"txnCreationDateTime" : "2021-08-13T10:23:11+03:00",
"txnAmount" : {
"value" : "5.15",
"currency" : "RUB"
},
"commissionAmount" : {
"value" : "0.00",
"currency" : "RUB"
},
"txnErrorInfo" : null
},
"cardTxnInfo" : {
"cardTokenId" : "100079217135",
"maskedPan" : "4153****8772",
"merchantType" : "5499",
"merchantId" : "498750000011107",
"merchantName" : "FACEBK ADS>fb.me/adsIE"
}
} ]
}
Пример ответа: возврат средств от провайдера с использованием интернет-эквайринга.
{
"txnList": [
{
"commonTxnInfo" : {
"txnHistoryId" : "e107a317-17eb-7675-9b9b-1e086abf3e5f",
"domain" : "CARDS",
"domainTxnId" : "99ed233c-fa50-4c99-b55c-0bad7f975e5f",
"domainTxnStatus" : {
"domainTxnStatusId" : "2",
"name" : "SUCCESS"
},
"txnType" : {
"domainTxnTypeId" : "4",
"name" : "REFUND_E_POS"
},
"txnClientBalanceImpact" : "INCOME",
"clientId" : "xkyygptxei2154520025",
"accountId" : "katnccfnot1406007604",
"productId" : "best-partner",
"txnCreationDateTime" : "2020-11-30T15:23:05+03:00",
"txnAmount" : {
"value" : "9.13",
"currency" : "RUB"
},
"commissionAmount" : {
"value" : "0.00",
"currency" : "RUB"
},
"txnErrorInfo" : null
},
"cardTxnInfo" : {
"cardTokenId" : "100075721030",
"maskedPan" : "4153****0746",
"merchantType" : "8988",
"merchantId" : "792185921248",
"merchantName" : "FACEBK ADS>fb.me/ads"
}
}
],
"cursor" : "e107a317-17eb-7675-9b9b-1e086abf3e5f"
}
Пример ответа: пополнение счета пользователя с банковской карты, пополнение счета пользователя с другого счета.
{
"txnList": [
{
"commonTxnInfo": {
"txnHistoryId": "034032d3-4d21-da6f-4e81-c218e3f73fd3",
"domain": "PAYMENTS",
"domainTxnId": "20841334328035502954",
"domainTxnStatus": {
"domainTxnStatusId": 60,
"name": "SUCCESS"
},
"txnType": {
"domainTxnTypeId": 5,
"name": "INVOICING_SERVICE"
},
"txnClientBalanceImpact": "INCOME",
"clientId": "ftwoubqzju7006699932",
"accountId": "aclalfffci6896603637",
"productId": "best-partner",
"txnCreationDateTime": "2020-09-24T16:05:21+03:00",
"txnAmount": {
"value": 7.06,
"currency": "RUB"
},
"commissionAmount": {
"value": 100.00,
"currency": "RUB"
},
"txnErrorInfo": null
}
},
{
"commonTxnInfo": {
"txnHistoryId": "5379a6e7-50c6-48fe-3db4-d10be301f76d",
"domain": "PAYMENTS",
"domainTxnId": "74568770091151849147",
"domainTxnStatus": {
"domainTxnStatusId": 60,
"name": "SUCCESS"
},
"txnType": {
"domainTxnTypeId": 3,
"name": "REPLENISHMENT_FROM_FUNDER"
},
"txnClientBalanceImpact": "INCOME",
"clientId": "xizbttxisz9836366129",
"accountId": "cdvvgtdiiu6310024653",
"productId": "best-partner",
"txnCreationDateTime": "2020-09-21T16:24:02+03:00",
"txnAmount": {
"value": 7.96,
"currency": "RUB"
},
"commissionAmount": {
"value": 0.00,
"currency": "RUB"
},
"txnErrorInfo": null
}
}
],
"cursor": "0a58b04f-23e2-ce66-4a93-e8dfdc3094e3"
}
Пример ответа: перевод между счетами пользователей, оплата в пользу провайдера со счета пользователя, перевод средств со счета пользователя на банковскую карту.
{
"txnList": [
{
"commonTxnInfo": {
"txnHistoryId": "7bc9122b-24a9-6fd3-00de-ab5ee29a1ed0",
"domain": "PAYMENTS",
"domainTxnId": "689834129540",
"domainTxnStatus": {
"domainTxnStatusId": 60,
"name": "SUCCESS"
},
"txnType": {
"domainTxnTypeId": 4,
"name": "TRANSFER_BETWEEN_CLIENTS"
},
"txnClientBalanceImpact": "EXPENSE",
"clientId": "fciscvrywl9511144790",
"accountId": "jctfeudxbv9350100550",
"productId": "best-partner",
"txnCreationDateTime": "2020-09-22T01:33:22+03:00",
"txnAmount": {
"value": 2.72,
"currency": "RUB"
},
"commissionAmount": {
"value": 0.00,
"currency": "RUB"
},
"txnErrorInfo": null
},
"transferBetweenClientsTxnInfo": {
"anotherClientId": "dvqpsshreq7474202590",
"anotherAccountId": "colwlksyqr4407625231"
}
},
{
"commonTxnInfo": {
"txnHistoryId": "0a58b04f-23e2-ce66-4a93-e8dfdc3094e3",
"domain": "PAYMENTS",
"domainTxnId": "35215795065636956590",
"domainTxnStatus": {
"domainTxnStatusId": 60,
"name": "SUCCESS"
},
"txnType": {
"domainTxnTypeId": 1,
"name": "PAYMENT"
},
"txnClientBalanceImpact": "EXPENSE",
"clientId": "sjrpngawef8770553957",
"accountId": "bwfefjwtfl3624831470",
"productId": "best-partner",
"txnCreationDateTime": "2020-09-24T10:18:40+03:00",
"txnAmount": {
"value": 9.63,
"currency": "RUB"
},
"commissionAmount": {
"value": 0.00,
"currency": "RUB"
},
"txnErrorInfo": null
},
"providerTxnInfo": {
"providerId": "best-partner",
"providerDisplayName": "Покупка у тестового провайдера"
}
},
{
"commonTxnInfo" : {
"txnHistoryId" : "f6b6be6b-073d-76c0-4b1e-95ed0a2f948c",
"domain" : "PAYMENTS",
"domainTxnId" : "08292288230573782472",
"domainTxnStatus" : {
"domainTxnStatusId" : "60",
"name" : "SUCCESS"
},
"txnType" : {
"domainTxnTypeId" : "8",
"name" : "WITHDRAWAL_TO_CARD"
},
"txnClientBalanceImpact" : "EXPENSE",
"clientId" : "wfdskihzwf6832842867",
"accountId" : "opigfnqcrj2066445848",
"productId" : "best-partner",
"txnCreationDateTime" : "2020-11-10T12:17:41+03:00",
"txnAmount" : {
"value" : "55.67",
"currency" : "RUB"
},
"commissionAmount" : {
"value" : "49.00",
"currency" : "RUB"
},
"txnErrorInfo" : null
}
}
],
"cursor": "0a58b04f-23e2-ce66-4a93-e8dfdc3094e3"
}
Пример ответа: пополнение по номеру карты
{
"txnList" : [ {
"commonTxnInfo" : {
"txnHistoryId" : "a143b835-aaae-33df-f9c0-981b491c5d02",
"domain" : "CARDS",
"domainTxnId" : "a3bed765-3cdd-49bc-b341-7c46c4b4fe51",
"domainTxnStatus" : {
"domainTxnStatusId" : "2",
"name" : "SUCCESS"
},
"txnType" : {
"domainTxnTypeId" : "5",
"name" : "FAST_FUNDS"
},
"txnClientBalanceImpact" : "INCOME",
"clientId" : "tkzqgecfhp6318792298",
"accountId" : "gsttucvuti5446745286",
"productId" : "best-partner",
"txnCreationDateTime" : "2021-09-22T13:04:14+03:00",
"txnAmount" : {
"value" : "9.79",
"currency" : "RUB"
},
"commissionAmount" : {
"value" : "0.00",
"currency" : "RUB"
},
"txnErrorInfo" : null
},
"cardTxnInfo" : {
"cardTokenId" : "100080518948",
"maskedPan" : "4153****2761",
"merchantType" : "4829",
"merchantId" : "SBOL ",
"merchantName" : "VISA MONEY TRANSFER>Visa Direct LU",
"retrievalReferenceNumber": "001877916339"
}
} ]
}
Пример: снятие наличных через банкомат
{
"txnList" : [ {
"commonTxnInfo" : {
"txnHistoryId" : "ae1b63b4-d6b0-5c15-d69a-2d344f36b9b8",
"domain" : "CARDS",
"domainTxnId" : "ef872961-2902-4a6b-97fa-34236b960ad2",
"domainTxnStatus" : {
"domainTxnStatusId" : "2",
"name" : "SUCCESS"
},
"txnType" : {
"domainTxnTypeId" : "6",
"name" : "CASH_WITHDRAWAL_ATM"
},
"txnClientBalanceImpact" : "EXPENSE",
"clientId" : "afcncmtyrs9142907318",
"accountId" : "pextklmxrp7402082649",
"productId" : "best-partner",
"txnCreationDateTime" : "2021-09-22T12:45:24+03:00",
"txnAmount" : {
"value" : "9.67",
"currency" : "RUB"
},
"commissionAmount" : {
"value" : "0.00",
"currency" : "RUB"
},
"txnErrorInfo" : null
},
"cardTxnInfo" : {
"cardTokenId" : "100080522305",
"maskedPan" : "4153****4924",
"merchantType" : "6011",
"merchantId" : "VB24 ",
"merchantName" : "VB24 >SANKT-PETERBU RU",
"retrievalReferenceNumber": "001877916339"
}
} ]
}
Пример: запрос баланса (через банкомат)
{
"txnList" : [ {
"commonTxnInfo": {
"txnHistoryId": "a81fff40-51b2-64e7-d7d2-89690c263a57",
"domain": "CARDS",
"domainTxnId": "1bd51bf1-3b02-4b73-bfbe-f07a39876f6b",
"domainTxnStatus": {
"domainTxnStatusId": 2,
"name": "SUCCESS"
},
"txnType": {
"domainTxnTypeId": 10,
"name": "BALANCE_INQUIRY"
},
"txnClientBalanceImpact": "EXPENSE",
"clientId": "mqyixkhjsr0446961069",
"accountId": "dvdsaqznqh8727979115",
"productId": "best-partner",
"txnCreationDateTime": "2021-09-22T17:07:04+03:00",
"txnAmount": {
"value": 0.00,
"currency": "RUB"
},
"commissionAmount": {
"value": 0.00,
"currency": "RUB"
},
"txnErrorInfo": null
},
"cardTxnInfo": {
"cardTokenId": "100080518560",
"maskedPan": "4153****2630",
"merchantType": "6011",
"merchantId": "VB24 ",
"merchantName": "VB24 >SANKT-PETERBU RU",
"accountBalance": {
"value": 8.11,
"currency": "RUB"
},
"retrievalReferenceNumber": "001877916339"
}
} ]
}
Пример: cписание с карты для перевода на карту или счет (AFT)
{
"txnList" : [ {
"commonTxnInfo" : {
"txnHistoryId" : "693611c8-8b25-e2f9-1895-09fc528bf129",
"domain" : "CARDS",
"domainTxnId" : "a0ca5dfd-bbd8-43f7-ac5d-77159cc6f6b6",
"domainTxnStatus" : {
"domainTxnStatusId" : "2",
"name" : "SUCCESS"
},
"txnType" : {
"domainTxnTypeId" : "12",
"name" : "P2P_DEBIT"
},
"txnClientBalanceImpact" : "EXPENSE",
"clientId" : "xmpukctjq520056273",
"accountId" : "gjvhkvaxw73728124",
"productId" : "b2b2c-test-full-access",
"txnCreationDateTime" : "2022-02-15T16:47:48+03:00",
"txnAmount" : {
"value" : 7.52,
"currency" : "RUB"
},
"commissionAmount" : {
"value" : 0.00,
"currency" : "RUB"
}
},
"cardTxnInfo" : {
"cardTokenId" : "999654310083",
"maskedPan" : "4153****2349",
"merchantType" : "5499",
"merchantId" : "809215 ",
"merchantName" : "CARD2CARD ALFA_MOBILE>MOSCOW RU",
"retrievalReferenceNumber" : "003885464570"
}
} ],
"cursor" : "0e674276-5157-7975-7691-20e1c20c1c28"
}
Успешный ответ содержит список операций в объекте txnList
.
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Параметры, общие для всех типов операций
Параметр | Тип | Описание |
---|---|---|
txnList | Список операций | |
commonTxnInfo | Блок с информацией по одной конкретной операции | |
txnHistoryId | String | Уникальный идентификатор истории одной конкретной операции |
domain | String | Домен, к которому относится операция |
domainTxnId | String | Для домена PAYMENTS — значение transactionId из запроса на совершение платежа, для домена CARDS — значение txnId из уведомления об операции с использованием карты |
domainTxnStatus | Блок с информацией о статусе операции | |
domainTxnStatusId | Код статуса операции | |
name | Статус операции | |
txnType | Блок с описанием типа операции | |
domainTxnTypeId | String | Код типа операции |
name | String | Тип операции |
txnClientBalanceImpact | Признак операции: INCOME - приход, EXPENSE - расход |
|
clientId | String | Уникальный идентификатор пользователя, совершившего операцию |
accountId | String | Идентификатор счета, по которому совершена операция |
productId | String | Идентификатор продукта, в рамках которого совершена операция |
txnCreationDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Для домена PAYMENTS — значение creationDateTime из ответа на платежный запрос, для домена CARDS — значение authorizationDateTime |
txnAmount | Блок с информацией о сумме операции | |
value | Number | Значение с двумя десятичными разрядами |
currency | String | Валюта, ISO 4217: RUB |
commissionAmount | Блок с информацией о комиссии, удержанной с пользователя | |
value | Number | Значение с двумя десятичными разрядами |
currency | String | Валюта, ISO 4217: RUB |
cursor | String | Позиция, начиная с которой будет произведена выборка операций для выдачи в ответе на следующий запрос истории. См. подробнее раздел Пагинация |
Параметры, свойственные операциям домена CARDS
Параметр | Тип | Описание |
---|---|---|
cardTxnInfo | Блок с информацией о карте, по которой была совершена операция, и деталях карточного платежа или запроса баланса | |
cardTokenId | String | Уникальный идентификатор (токен) карты |
maskedPan | String | Маскированный PAN. Пример: 4153****4697 |
merchantType | String | MCC |
merchantId | String | Идентификатор провайдера, который передала платежная система. REGEX: ^([\w\s]{15})?\$ |
merchantName | String | Имя провайдера, которое передала платежная система |
accountBalance | String | Опционально. Блок с информацией о сумме остатка на счете и валюте счета. |
retrievalReferenceNumber | String | Идентификатор банковской транзакции (RRN) |
Параметры, свойственные операции TRANSFER_BETWEEN_CLIENTS
домена PAYMENTS
Параметр | Тип | Описание |
---|---|---|
transferBetweenClientsTxnInfo | Блок с информацией о получателе перевода | |
anotherClientId | String | Идентификатор пользователя. Если "txnClientBalanceImpact": "EXPENSE" - история запрошена по отправителю платежа и в данном параметре вернется уникальный идентификатор пользователя, на счет которого зачислен перевод. Если "txnClientBalanceImpact": "INCOME" - история запрошена по получателю платежа и в данном параметре вернется уникальный идентификатор пользователя, со счета которого совершен перевод. |
anotherAccountId | String | Счет пользователя. Аналогично anotherClientId . |
Параметры, свойственные операции PAYMENT
домена PAYMENT
Параметр | Тип | Описание |
---|---|---|
providerTxnInfo | Блок с информацией о провайдере — получателе платежа | |
providerId | String | Идентификатор провайдера/услуги, в пользу которого совершен платеж |
Параметры, свойственные операциям REPLENISHMENT_FROM_FUNDER
и REPLENISHMENT_FROM_EXTERNAL_PROCESSING_FUNDER
домена PAYMENT
Параметр | Тип | Описание |
---|---|---|
funderTxnInfo | Блок с информацией об источнике денежных средств | |
funderId | String | Идентификатор источника денежных средств |
Домены
Домен | Описание |
---|---|
PAYMENTS | Операции, инициированные из интерфейса партнера |
CARDS | Операции с использованием карты, которые инициированы не из интерфейса партнера и проводились через платежную систему |
Статусы операций
Для домена PAYMENTS
Код | Статус | Описание |
---|---|---|
50 | PROCESSING | В процессе проведения |
60 | SUCCESS | Успешно (финальный статус) |
100 | DECLINED | Неуспешно (финальный статус) |
Для домена CARDS
Код | Статус | Описание |
---|---|---|
1 | PROCESSING | В процессе проведения |
2 | SUCCESS | Успешно (финальный статус). Операция приобретает этот статус, когда платежная система инициировала клиринг. См. процесс проведения покупки с использованием карты. |
3 | FAILED | Неуспешно (финальный статус) |
Типы операций
Для домена PAYMENTS
Код | Операция | Описание |
---|---|---|
1 | PAYMENT | Оплата в пользу провайдера со счета пользователя |
3 | REPLENISHMENT_FROM_FUNDER | Пополнение счета пользователя с другого счета |
4 | TRANSFER_BETWEEN_CLIENTS | Перевод между счетами пользователей |
5 | INVOICING_SERVICE | Пополнение счета пользователя с банковской карты |
8 | WITHDRAWAL_TO_CARD | Перевод со счета пользователя на банковскую карту |
9 | REPLENISHMENT_FROM_EXTERNAL_PROCESSING_FUNDER | Пополнение счета пользователя с другого счета, инициированное через другие протоколы QIWI |
Для домена CARDS
Код | Операция | Описание |
---|---|---|
1 | PURCHASE_POS | Покупка посредством наземного эквайринга |
2 | PURCHASE_E_POS | Покупка с использованием карты в интернете |
3 | REFUND_POS | Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием наземного эквайринга |
4 | REFUND_E_POS | Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием интернет-эквайринга |
5 | FAST_FUNDS | Пополнение по номеру карты |
6 | CASH_WITHDRAWAL_ATM | Снятие наличных в банкомате |
7 | CASH_WITHDRAWAL_CASHIER | Снятие наличных через кассу банка |
8 | REFUND_CASH_WITHDRAWAL_ATM | Возврат по операции снятия наличных в банкомате |
9 | REFUND_CASH_WITHDRAWAL_CASHIER | Возврат по операции снятия наличных через кассира |
10 | BALANCE_INQUIRY | Запрос баланса |
12 | P2P_DEBIT | Списание с карты для перевода на карту или счет (AFT) |
13 | REFUND_P2P_DEBIT | Возврат списания с карты для перевода на карту или счет (AFT) |
Формат ошибок API
Структура ответа на неуспешный запрос:
Пример ответа
{
"serviceName": "openapi-reports",
"errorCode": "openapi.reports.client.not.found",
"dateTime": "2020-07-23T20:13:22.290416+03:00",
"traceId": "67477569e8bc6838"
}
Поле ответа | Описание |
---|---|
serviceName | Имя сервиса, который вернул ошибку |
errorCode | Код ошибки. См. справочник кодов ошибок |
dateTime | Дата и время формирование ответа |
traceId | Параметр, необходимый для анализа логов. Его значение также всегда присутствует в заголовках ответа (response headers) в параметре X-B3-TraceId |
Справочник кодов ошибок
Код | Описание |
---|---|
openapi.reports.client.not.found | Пользователь не найден |
openapi.reports.internal.error | В сервисе истории произошла внутренняя ошибка |
openapi.reports.validation.error | Ошибка валидации, проверьте корректность данных в запросе |
openapi.reports.product.not.found | Продукт не найден |
openapi.reports.invalid.cursor | Некорректный cursor |
openapi.reports.client.blocked | Пользователь заблокирован |