API нарахувань кешбеку від банку

Увага: банк має надсилати ці дані в реальному часі для кожної транзакції, де нараховано кешбек (або скасовано нарахування при refund), замість очікування файлу акту звірки.

Два способи запису в ту саму таблицю cashback_bank_accruals:

Версія	Ендпоінт	Що передається
Перша (одна транзакція)	`POST /cashback-bank-accruals`	Один об’єкт: `campaignId`, `bankId` і поля однієї транзакції
Друга (масив)	`POST /v2/cashback-bank-accruals`	`campaignId` і `bankId` один раз, транзакції — у масиві `accruals`

GET /cashback-bank-accruals спільний: у відповіді видно рядки і з першої версії, і з другої. Окремого GET для v2 немає.

У шляху першої версії префікса /v1 немає — це POST /cashback-bank-accruals.

Створення факту нарахування (одна транзакція)

Ендпоінт: /cashback-bank-accruals

Метод: POST

Опис: Перша версія API: один запит — одна транзакція. Фіксує факт нарахування кешбеку від банку по транзакції. На основі цих даних чеки можна знаходити та зіставляти автоматично, не чекаючи файлу звірки від банку. Для кількох транзакцій на одну кампанію і один банк використовуйте пакетне створення.

Заголовки: x-trace-id uuid

Тіло запиту

Поле	Тип	Обов’язковий	Опис
`campaignId`	UUID	Так	ID кампанії (cashback ID), до якої належить нарахування
`bankId`	UUID	Так	Partner ID банку, що передає нарахування
`transactionId`	string	Так	ID транзакції
`cardMask`	string	Так	Маска картки (PAN)
`operationDate`	string (ISO date-time)	Так	Дата операції
`operationAmount`	number	Так	Сума операції
`cashbackAmount`	number	Так	Сума кешбеку, нарахована банком
`rrn`	string	Так	Reference Retrieval Number
`terminalId`	string	Ні	Terminal ID
`terminalAuthCode`	string	Ні	Код авторизації терміналу
`clientId`	string	Ні	Client ID від банку
`orderId`	string	Ні	Order ID (зазвичай банк не передає; може бути заповнений після зіставлення)
`status`	string	Ні	Статус від банку (зберігається як є)
`bankPaymentShare`	number	Ні	Частка банку в розподілі виплати кешбеку
`merchantPaymentShare`	number	Ні	Частка мерчанта в розподілі виплати кешбеку
`purchaseDate`	string (ISO date-time)	Так	Дата покупки

{
  "campaignId": "11111111-2222-4333-8444-555555555501",
  "bankId": "33333333-4444-4333-8444-555555555503",
  "transactionId": "2qtL1H/HGEeJ8iV3eiLwdQ==",
  "cardMask": "464237******1234",
  "operationDate": "2026-09-10T12:00:00Z",
  "operationAmount": 250.50,
  "cashbackAmount": 15.50,
  "rrn": "525609471435",
  "terminalId": "E0197712",
  "terminalAuthCode": "AUTH123",
  "clientId": "6FO09WL12123",
  "status": "approved",
  "bankPaymentShare": 7.50,
  "merchantPaymentShare": 8.00,
  "purchaseDate": "2026-09-10T12:00:00Z"
}

Відповідь

Поле	Тип	Опис
`id`	UUID	Унікальний ідентифікатор факту нарахування
`campaignId`	UUID	ID кампанії (cashback ID)
`bankId`	UUID	ID банку, що передав нарахування
`transactionId`	string	ID транзакції
`cardMask`	string	Маска картки (PAN)
`operationDate`	Date	Дата операції
`operationAmount`	number	Сума операції
`cashbackAmount`	number	Сума кешбеку від банку
`rrn`	string	Reference Retrieval Number
`terminalId`	string	Terminal ID
`terminalAuthCode`	string	Код авторизації терміналу
`clientId`	string	Client ID від банку
`orderId`	string	Order ID, заповнюється після зіставлення
`status`	string	Статус від банку
`bankPaymentShare`	number	Частка банку
`merchantPaymentShare`	number	Частка мерчанта
`purchaseDate`	Date	Дата покупки
`retailerId`	UUID	ID мерчанта, заповнюється після зіставлення з чеком
`createdAt`	Date	Час створення
`updatedAt`	Date	Час останнього оновлення

{
  "id": "44444444-5555-4333-8444-555555555504",
  "campaignId": "11111111-2222-4333-8444-555555555501",
  "bankId": "33333333-4444-4333-8444-555555555503",
  "transactionId": "2qtL1H/HGEeJ8iV3eiLwdQ==",
  "cardMask": "464237******1234",
  "operationDate": "2026-09-10T12:00:00Z",
  "operationAmount": 250.50,
  "cashbackAmount": 15.50,
  "rrn": "525609471435",
  "terminalId": "E0197712",
  "terminalAuthCode": "AUTH123",
  "clientId": "6FO09WL12123",
  "orderId": null,
  "status": "approved",
  "bankPaymentShare": 7.50,
  "merchantPaymentShare": 8.00,
  "purchaseDate": "2026-09-10T12:00:00Z",
  "retailerId": null,
  "createdAt": "2026-09-10T12:00:05.000Z",
  "updatedAt": "2026-09-10T12:00:05.000Z"
}

Помилки

HTTP-код	Тип помилки	Опис
400	BadRequestException	Невалідні дані запиту або помилка валідації
404	NotFoundException	Банк з указаним `bankId` або кампанія з указаним `campaignId` не знайдені
500	DatabaseException	Помилка бази даних

Пакетне створення (масив транзакцій)

Ендпоінт: /v2/cashback-bank-accruals

Метод: POST

Опис: Друга версія API: банк одним запитом надсилає кілька транзакцій на одну кампанію і один банк. campaignId і bankId передаються один раз на рівні кореня. Кожна транзакція — окремий об’єкт у масиві accruals (ті самі поля, що в тілі одиночного POST /cashback-bank-accruals, крім campaignId і bankId).

Кожен елемент зберігається окремим рядком у таблиці cashback_bank_accruals у тій самій формі, що й одиночний POST. Весь масив пишеться однією транзакцією: якщо будь-який елемент невалідний або немає банку чи кампанії, не зберігається нічого.

Прочитати збережені рядки можна тим самим GET /cashback-bank-accruals.

Заголовки: x-trace-id uuid

Тіло запиту

Поле	Тип	Обов’язковий	Опис
`campaignId`	UUID	Так	ID кампанії (cashback ID), спільний для всіх елементів
`bankId`	UUID	Так	Partner ID банку, спільний для всіх елементів
`accruals`	array	Так	Щонайменше одна транзакція. Верхньої межі розміру немає
`accruals[].transactionId`	string	Так	ID транзакції
`accruals[].cardMask`	string	Так	Маска картки (PAN)
`accruals[].operationDate`	string (ISO date-time)	Так	Дата операції
`accruals[].operationAmount`	number	Так	Сума операції
`accruals[].cashbackAmount`	number	Так	Сума кешбеку, нарахована банком
`accruals[].rrn`	string	Так	Reference Retrieval Number
`accruals[].terminalId`	string	Ні	Terminal ID
`accruals[].terminalAuthCode`	string	Ні	Код авторизації терміналу
`accruals[].clientId`	string	Ні	Client ID від банку
`accruals[].orderId`	string	Ні	Order ID (зазвичай банк не передає)
`accruals[].status`	string	Ні	Статус від банку (зберігається як є)
`accruals[].bankPaymentShare`	number	Ні	Частка банку в розподілі виплати кешбеку
`accruals[].merchantPaymentShare`	number	Ні	Частка мерчанта в розподілі виплати кешбеку
`accruals[].purchaseDate`	string (ISO date-time)	Так	Дата покупки

{
  "campaignId": "11111111-2222-4333-8444-555555555501",
  "bankId": "33333333-4444-4333-8444-555555555503",
  "accruals": [
    {
      "transactionId": "TXN-EXAMPLE-1",
      "cardMask": "464237******1234",
      "operationDate": "2026-09-10T12:00:00Z",
      "operationAmount": 250.5,
      "cashbackAmount": 12.5,
      "rrn": "525609471435",
      "terminalId": "TERM-0001",
      "terminalAuthCode": "AUTH123",
      "clientId": "CLIENT-EXAMPLE-1",
      "status": "approved",
      "bankPaymentShare": 7.5,
      "merchantPaymentShare": 5,
      "purchaseDate": "2026-09-10T12:00:00Z"
    },
    {
      "transactionId": "TXN-EXAMPLE-2",
      "cardMask": "464237******5678",
      "operationDate": "2026-09-10T13:00:00Z",
      "operationAmount": 100,
      "cashbackAmount": 5,
      "rrn": "525609471436",
      "purchaseDate": "2026-09-10T13:00:00Z"
    }
  ]
}

Відповідь

HTTP-код: 200

Тіло — масив збережених рядків. Кожен елемент має ті самі поля, що й відповідь одиночного POST /cashback-bank-accruals (id, campaignId, bankId, поля транзакції, createdAt, updatedAt). campaignId і bankId повторюються в кожному рядку.

Помилки

HTTP-код	Тип помилки	Опис
400	BadRequestException	Невалідні дані запиту або елемент масиву. Нічого не збережено
404	NotFoundException	Банк з указаним `bankId` або кампанія з указаним `campaignId` не знайдені. Нічого не збережено
500	DatabaseException	Помилка бази даних. Нічого не збережено

Отримання списку нарахувань

Ендпоінт: /cashback-bank-accruals

Метод: GET

Опис: Повертає сторінковий список фактів нарахування з фільтрами за періодом, кампанією, банком та/або мерчантом. У списку є рядки, створені і одиночним POST /cashback-bank-accruals, і пакетним POST /v2/cashback-bank-accruals.

Заголовки: x-trace-id uuid

Query-параметри

Поле	Тип	Обов’язковий	Опис
`page`	number	Ні	Номер сторінки (за замовчуванням: 1)
`pageSize`	number	Ні	Розмір сторінки (за замовчуванням: 10)
`campaignId`	UUID	Ні	Фільтр за ID кампанії (cashback ID)
`bankId`	UUID	Ні	Фільтр за ID банку
`retailerId`	UUID	Ні	Фільтр за ID мерчанта
`dateFrom`	string (ISO date)	Ні	Початок діапазону дати покупки
`dateTo`	string (ISO date)	Ні	Кінець діапазону дати покупки

GET /cashback-bank-accruals?bankId=33333333-4444-4333-8444-555555555503&dateFrom=2026-09-01&dateTo=2026-09-30&page=1&pageSize=10

Відповідь

Поле	Тип	Опис
`data`	array	Список записів (та сама структура, що в `POST`)
`pagination.page`	number	Поточна сторінка
`pagination.pageSize`	number	Розмір сторінки
`pagination.totalPages`	number	Усього сторінок
`pagination.totalItems`	number	Усього записів
`pagination.hasNextPage`	boolean	Чи є наступна сторінка
`pagination.hasPrevPage`	boolean	Чи є попередня сторінка

{
  "data": [
    {
      "id": "44444444-5555-4333-8444-555555555504",
      "campaignId": "11111111-2222-4333-8444-555555555501",
      "bankId": "33333333-4444-4333-8444-555555555503",
      "transactionId": "2qtL1H/HGEeJ8iV3eiLwdQ==",
      "cardMask": "464237******1234",
      "operationDate": "2026-09-10T12:00:00Z",
      "operationAmount": 250.50,
      "cashbackAmount": 15.50,
      "rrn": "525609471435",
      "orderId": null,
      "status": "approved",
      "bankPaymentShare": 7.50,
      "merchantPaymentShare": 8.00,
      "purchaseDate": "2026-09-10T12:00:00Z",
      "retailerId": null,
      "createdAt": "2026-09-10T12:00:05.000Z",
      "updatedAt": "2026-09-10T12:00:05.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalPages": 1,
    "totalItems": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

Помилки

HTTP-код	Тип помилки	Опис
400	BadRequestException	Невалідні query-параметри
500	DatabaseException	Помилка бази даних

Примітки

Перша версія (POST /cashback-bank-accruals) — одна транзакція в тілі запиту. Друга (POST /v2/cashback-bank-accruals) — масив транзакцій accruals на одну кампанію і один банк.
Для refund передавайте від’ємну cashbackAmount (аналогічно до попереднього API відповідей банку) і в одиночному POST, і в елементах accruals.
Доступ до API — на рівні інфраструктури (JWT, IP allow-list); див. JWT авторизація.