История платежей¶

Партнёр может получить список совершённых клиентом платежей, выполнив запрос истории к API Reports. Под платежами понимаются финансовые операции, которые приводят к движению денежных средств — пополнение с банковской карты, перевод на банковскую карту и др.

Обратите внимание

В данной статье термины «платёж» и «операция» имеют одинаковое значения и подразумевают исключительно финансовую операцию.

Ответ на запрос истории представляет собой JSON-объект и содержит:

txnList — список платежей;
cursor — позицию, на которой остановилась выборка платежей в момент запроса. Подробности см. в разделе «Пагинация».

Список платежей¶

Список (txnList) содержит данные каждого отдельного платежа (data). Платёж может относиться к домену PAYMENTS или CARDS и быть одного из задокументированных типов (txnType).

Примечание

Операция домена PAYMENTS выполняется из авторизованной зоны, домена CARDS — из неавторизованной зоны. Описание доменов см. в статье «Термины и бизнес-сущности».

Платежи разных типов имеют разный сценарий проведения и по этому признаку распределяются между доменами.

Пример

Операция типа INVOICING_SERVICE (пополнение счёта с банковской карты с помощью API BaaS) относится к домену PAYMENTS, т.к. совершается без использования карты QIWI и поступает в BaaS из авторизованной зоны. Подробности см. здесь.
Операция типа FAST_FUNDS (пополнение по номеру карты) относится к домену CARDS, т.к. совершается с помощью карты QIWI и поступает в BaaS из неавторизованной зоны. Подробности см. здесь.

В момент получения истории платёж может находиться в одном из задокументированных статусов. Список поддерживаемых типов и описание статусов платежей в разрезе домена см. в документации History&Notifications API.

Обратите внимание

Операция типа BALANCE_INQUIRY (запрос баланса) может выполняться с взиманием комиссии, т.е. приводить к движению денежных средств. По данному признаку тип BALANCE_INQUIRY поддерживается API Reports.

Список платежей содержит:

обязательные параметры — присутствуют всегда (независимо от того, к какому домену относится операция);
опциональные параметры — могут присутствовать для операции конкретного домена (PAYMENTS или CARDS).

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

Домен PAYMENTSДомен CARDS

{
  "txnList": [
    {
    //Обязательные поля (присутствуют для всех типов операций, независимо от домена)
      "commonTxnInfo": {
        "txnHistoryId": "0a58b04f-23e2-ce66-4a93-e8dfdc3094e3",
        "domain": "PAYMENTS",
        "domainTxnId": "35215795065636956590",
        "domainTxnStatus": {
          "domainTxnStatusId": 60,
          "name": "SUCCESS"
        },
        "txnType": {
          "domainTxnTypeId": 1,
          "name": "XXX"
        },
        "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
      },
      //Опциональные поля (могут присутствовать для операции домена PAYMENTS)
      "providerTxnInfo": {
        "providerId": "best-partner",
        "providerDisplayName": "Покупка у тестового провайдера"
      }
    }
  ]
}

{
  "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" : "XXX"
        },
        "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
      },
      //Опциональные поля (могут присутствовать для операции домена CARDS)
      "cardTxnInfo" : {
        "cardTokenId" : "100079217135",
        "maskedPan" : "4153****8772",
        "merchantType" : "5499",
        "merchantId" : "498750000011107",
        "merchantName" : "FACEBK ADS>fb.me/adsIE",
        "retrievalReferenceNumber": "001877916339"
      }
    }
  ]
}

Набор опциональных полей для операции домена PAYMENTS зависит от типа операции (оплата провайдера, перевод между кошельками и др.). Отличие наборов полей можно увидеть ниже на примере двух разных типов операций.

domain: PAYMENTS, txnType: PAYMENTdomain: PAYMENTS, txnType: TRANSFER_BETWEEN_CLIENTS

{
  "txnList": [
    {
      "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": "Покупка у тестового провайдера"
      }
    }
  ]
}

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

Набор опциональных полей для операций домена CARDS можно условно разделить на две группы:

постоянные — всегда присутствуют в data операций домена CARDS.
дополнительные — могут присутствовать для конкретного типа операции домена CARDS (запрос баланса в банкомате и др.).

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

domain: CARDS, txnType: PURCHASE_E_POSdomain: CARDS, txnType: BALANCE_INQUIRY

{
  "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
      },
      //Постоянные для операций домена CARDS поля
      "cardTxnInfo" : {
        "cardTokenId" : "100079217135",
        "maskedPan" : "4153****8772",
        "merchantType" : "5499",
        "merchantId" : "498750000011107",
        "merchantName" : "FACEBK ADS>fb.me/adsIE",
        "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
    },
    //Постоянные для операций домена CARDS поля
    "cardTxnInfo": {
        "cardTokenId": "100080518560",
        "maskedPan": "4153****2630",
        "merchantType": "6011",
        "merchantId": "VB24           ",
        "merchantName": "VB24           >SANKT-PETERBU         RU",
        "retrievalReferenceNumber": "001877916339",
    //Дополнительные поля — присутствуют для операции запроса баланса в банкомате
        "accountBalance": {
            "value": 8.11,
            "currency": "RUB"
        }
      }
    }
  ]
}

Пагинация¶

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

Поле cursor в ответе на запрос истории платежей определяет позицию, на которой остановилась выборка в момент запроса. Например, если в ответе вернулся cursor:txn4, то последняя операция, полученная в истории, имеет идентификатор txnHistoryId:txn4. Полученное значение cursorследует использовать в следующем запросе истории платежей — передать в качестве значения одноимённого входящего параметра.

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

   https://api.qiwi.com/partner/openapi-reports/v1/products/best-partner/openapi-reports/v1/products/best-partner/operations/history?accountId=acc1&limit=50&cursor=txn4

Значение входящего параметра cursor определяет позицию, начиная с которой будет произведена выборка операций для выдачи в ответе на запрос истории. Например, если в запросе указан cursor:txn4, в выборку попадут совершённые после txn4 операции — операции, начиная с tnx5и далее в пределах limit.

Пример

BaaS последовательно провёл 4 операции с идентификаторами:
- txn1;
- txn2;
- txn3;
- txn4.
Партнёр совершил свой первый запрос истории операций (без указания cursor).
BaaS вернул в txnList все операции из п.1. и cursor:txn4
BaaS последовательно провёл две новые операции с идентификаторами:
- txn5;
- txn6;
Партнёр совершил повторный запрос истории операций и указал cursor:txn4.
BaaS вернул в txnList операции с txn5, txn6 и cursor:txn6.

Если в ответе на запрос истории список платежей вернулся пустым, значит на момент совершения запроса вся имеющаяся в BaaS история по указанному счёту клиента уже получена.

Пример пустого txnList

    {
      "txnList": []
    }

Тестирование¶

Общие правила тестирования описаны в статье BaaS → «Тестирование». Здесь мы расскажем об особенностях тестирования сценариев получения истории платежей.

Особенности

Операции домена CARDS, относящиеся к домену CARDS, не могут быть совершены в тестовой среде. Чтобы протестировать получение таких операций в истории платежей, направьте запрос представителям BaaS. Канал общения определяется для каждого партнёра индивидуально.