Вопросы
baas_support@qiwi.com
NAV Navbar
shell

HISTORY&NOTIFICATIONS API

Последнее обновление: 17-06-2021 |

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

Здесь и далее по тексту:

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

Авторизация

Поддерживаются только HTTPS-запросы. HTTP-запросы по нешифрованному каналу не поддерживаются. Схема аутентификации - Bearer. В заголовках запроса передаётся bearer-токен в поле Authorization

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

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

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

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

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

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

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

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

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

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

Уведомления

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

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

Адрес URL строго соответствует продукту productID: для каждого 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 Тип уведомления
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 Пополнение счета пользователя с банковской карты
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
txnType Тип операции, для которой сформировано уведомление
actionId Идентификатор действия, которое произошло с операцией
actionType Тип действия, которое произошло с операцией
actionStatus Статус действия, которое произошло с авторизацией
actionStatusDetails Пустой объект {}, если "actionStatus": "SUCCESS"
Объект c полем failureCode, если "actionStatus": "FAILED". Это значит, что в момент проведения операции возникла ошибка. Например:
"actionStatus":"FAILED",
"actionStatusDetails":
{"failureCode":"ACCOUNT_BALANCE_INSUFFICIENT_FUNDS"}
actionData Блок с описанием деталей операции
cardTokenId Уникальный идентификатор (токен) карты
clientId Уникальный идентификатор пользователя, которому принадлежит карта
transactionAmount Блок с информацией о сумме операции в валюте счета (рубли)
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 — денежные средства были зачислены на счет пользователя в рамках этой оффлайн-операции (онлайн-операции пополнения карты не было).

Возврат

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

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

Тип уведомления

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

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

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

Наименование Описание
PURCHASE_E_POS Покупка в интернете
PURCHASE_POS Покупка посредством наземного эквайринга
REFUND_E_POS Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием интернет-эквайринга
REFUND_POS Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием наземного эквайринга
FAST_FUNDS Пополнение по номеру карты

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

Действие Описание
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

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

Статус Описание
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 Сумма отмены операции пополнения по номеру карты не соответствует сумме операции пополнения по номеру карты

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

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

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

Запрос → 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***********************'
Параметр Описание Тип 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 -

Ответ ←

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

{
    "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" : "b2b2c-test-full",
      "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 String Уникальный идентификатор истории одной конкретной операции
domain String Домен, к которому относится операция: PAYMENTS, CARDS.
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 См. раздел Пагинация

Параметры, свойственные типам PURCHASE_POS, PURCHASE_E_POS, REFUND_POS, REFUND_E_POS домена CARD

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

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

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

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

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

Пагинация

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

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

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

Домены

Статус Описание
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 Перевод со счета пользователя на банковскую карту

Для вида операции CARDS

Код Операция Описание
1 PURCHASE_POS Покупка посредством наземного эквайринга
2 PURCHASE_E_POS Покупка с использованием карты в интернете
3 REFUND_POS Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием наземного эквайринга
4 REFUND_E_POS Возврат средств от провайдера (поставщика услуг, участника платежной системы) с использованием интернет-эквайринга

Ошибки

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

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

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