API адмін-панелі кешбеку для банків

Зовнішнє API для інтеграції кор-проєкту банку з адмін-панеллю кешбеків Deeployalty. Аналог API адмін-панелі кешбеку для мерчантів, але для банків.

ENV:

	Dev	Prod
	https://admin-panel.dev.deeployalty.io/deeployalty-admin/	https://admin-panel.deeployalty.io/deeployalty-admin/

Swagger (OpenAPI)

Інтерактивна документація зі схемами запитів і відповідей:

	Dev	Prod
Swagger UI	admin-panel.dev.deeployalty.io/deeployalty-admin/swagger	admin-panel.deeployalty.io/deeployalty-admin/swagger

У Swagger шукайте ендпоінти з префіксом /cashbacks/for-bank та підтвердження/відхилення кампаній банком.

Інструкція зі звірки кешбек-кампаній у порталі (звіти банку та мерчанта): звірка кешбек-кампаній.

Авторизація

Авторизація для всіх API відбувається за допомогою Bearer Token.

Як згенерувати Bearer Token

Для генерації токена використовуйте api.

Приклад:

{
  "Authorization": "Bearer {{authToken}}"
}

Зверніть увагу: токен має термін дії.

Отримання списку кешбеків

Метод: GET

Ендпоінт: /cashbacks/for-bank

Query-параметри:

Параметр	Тип	Обов’язковий	Опис
`name`	string	Ні	Назва кешбеку
`sku`	string[]	Ні	SKU товару
`retailerId`	uuid	Ні	ID мерчанта
`status`	string	Ні	Статус кампанії: `active`, `finished`, `approved`, `deleted`
`bankApprovalStatus`	string	Ні	Група статусів кешбеку в банку (див. Статус банку нижче)
`dateFrom`	string (ISO8601)	Ні	Дата початку кешбеку
`dateTo`	string (ISO8601)	Ні	Дата завершення кешбеку

Статус кешбеку

Статус кешбеку	Опис
`active`	кешбек-кампанії розпочато і вони активні
`finished`	кешбек-кампанії завершено (фільтр відповідає статусу `awaitingCompensationConfirmation`)
`approved`	участь у кешбек-кампанії схвалено банком і мерчантом (кампанія ще не стартувала)
`deleted`	кешбек-кампанію видалено

Для інтеграції з адмін-панеллю та отримання всіх кешбек-кампаній, які дійсно схвалені банком і мерчантом і будуть активні на конкретну дату, потрібно брати статус active для всієї кампанії, а не лише active у масиві banks[].

Якщо кампанія активна і мерчант додає ще один термінал, повний список terminal id можна взяти в terminals[]. Наприклад, використовуйте сервіс, який раз на 12 годин перевіряє, чи змінилося це поле; якщо так — оновіть дані у своїй системі.

Статус банку

Статус банку	Опис
`pending`	кешбек-кампанія очікує рішення банку
`approved`	участь у кешбек-кампанії схвалено банком
`declined`	участь у кешбек-кампанії відхилено банком
`expired`	кешбек-кампанія завершилася або мерчант схвалив старт кампанії без цього банку

Успішна відповідь

HTTP-код: 200

Тіло відповіді:

[
  {
    "cashbackId": "11111111-2222-4333-8444-555555555501",
    "retailerId": "22222222-3333-4333-8444-555555555502",
    "createdByRetailerId": "22222222-3333-4333-8444-555555555502",
    "createdByBankId": null,
    "createdByType": "retailer",
    "banks": [
      {
        "id": "33333333-4444-4333-8444-555555555503",
        "status": "pending",
        "settlementConfirmed": false,
        "bankReportingStatus": null,
        "hasBankReport": false,
        "hasSecondBankReport": false,
        "merchantReportUploadsCount": 0
      }
    ],
    "name": "Кешбек на продукти (приклад)",
    "description": "Опис кампанії (приклад)",
    "participationTerms": "Умови участі (приклад)",
    "bannerSmall": "https://cdn.example.invalid/banners/small.png",
    "bannerBig": "https://cdn.example.invalid/banners/big.png",
    "sku": ["SKU-EXAMPLE-001"],
    "categoryId": ["10", "20"],
    "allProducts": false,
    "purchaseOnline": true,
    "purchaseOffline": true,
    "dateFrom": "2026-01-01T00:00:00.000Z",
    "dateTo": "2026-03-31T23:59:59.999Z",
    "minAmount": 100,
    "maxAmount": 5000,
    "maxBudget": 100000,
    "percentage": 10,
    "expectedCompensation": null,
    "merchantCompensationPercentage": 0,
    "merchantCategoryCode": ["5411"],
    "countryId": "44444444-5555-4333-8444-555555555504",
    "terminals": [
      {
        "terminal_id": "TERM-0001",
        "terminal_name": "Каса №1 (приклад)",
        "terminal_location": "м. Київ, вул. Прикладна, 1"
      }
    ],
    "terminalsDeeployalty": false,
    "paymentSystemsId": [
      "aaaaaaaa-bbbb-4ccc-8ddd-000000000001",
      "aaaaaaaa-bbbb-4ccc-8ddd-000000000002"
    ],
    "status": "awaitingBankApproval",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-01-15T10:00:00.000Z",
    "retailer": {
      "retailerId": "22222222-3333-4333-8444-555555555502",
      "name": "Мерчант (приклад)"
    },
    "country": {
      "id": "44444444-5555-4333-8444-555555555504",
      "name": "Ukraine",
      "code": "UA",
      "currency": {
        "code": "UAH",
        "icon": "",
        "name": "Ukrainian hryvnia",
        "symbol": "₴"
      }
    },
    "segment": {
      "segmentId": "55555555-6666-4333-8444-555555555505",
      "cashbackId": "11111111-2222-4333-8444-555555555501",
      "customersCount": 2,
      "customerIds": [
        "66666666-7777-4333-8444-555555555506",
        "77777777-8888-4333-8444-555555555507"
      ],
      "formedAt": "2026-01-10T12:00:00.000Z",
      "sourceFileName": "segment-upload-example.xlsx"
    }
  }
]

Формат відповіді: масив об’єктів (без пагінації). У кожному елементі — кампанія, до якої ваш банк доданий учасником. Масив banks[] містить лише ваш банк (ідентифікатор з JWT).

Поля кампанії (корінь об’єкта)

Поле	Тип	Опис
`cashbackId`	uuid	Ідентифікатор кешбек-кампанії
`retailerId`	uuid	Мерчант-власник кампанії
`createdByRetailerId`	uuid \| null	Мерчант, який створив кампанію (якщо автор — мерчант)
`createdByBankId`	uuid \| null	Банк, який створив кампанію (якщо автор — банк)
`createdByType`	string	Хто створив кампанію: `bank` або `retailer`
`name`	string	Назва кампанії
`description`	string \| null	Опис для клієнтів / UI
`participationTerms`	string \| null	Умови участі в кампанії
`bannerSmall`	string \| null	URL або data-URI малого банера
`bannerBig`	string \| null	URL або data-URI великого банера
`sku`	string[]	SKU товарів, на які діє кешбек (порожній масив, якщо не застосовується)
`categoryId`	string[]	Ідентифікатори категорій товарів
`allProducts`	boolean	`true` — кешбек на весь асортимент без прив’язки до SKU/категорій
`purchaseOnline`	boolean	Кешбек діє на онлайн-покупки
`purchaseOffline`	boolean	Кешбек діє на офлайн-покупки
`dateFrom`	string (ISO8601)	Початок періоду кампанії (UTC)
`dateTo`	string (ISO8601)	Кінець періоду кампанії (UTC)
`minAmount`	number \| null	Мінімальна сума чека для нарахування
`maxAmount`	number \| null	Максимальна сума чека для нарахування
`maxBudget`	number \| null	Максимальний бюджет кампанії (на банк)
`percentage`	number \| null	Відсоток кешбеку
`expectedCompensation`	number \| null	Очікувана компенсація (якщо задана)
`merchantCompensationPercentage`	number \| null	Частка компенсації мерчанта (0–100), решта — банк
`merchantCategoryCode`	string[] \| null	MCC-коди мерчанта для кампанії
`countryId`	uuid \| null	Країна кампанії
`terminalsDeeployalty`	boolean	`true` — перелік терміналів із довідника Deeployalty
`paymentSystemsId`	uuid[]	Платіжні системи, дозволені для кампанії
`status`	string	Детальний статус кампанії (див. таблицю нижче)
`createdAt`	string (ISO8601)	Час створення
`updatedAt`	string (ISO8601)	Час останнього оновлення

Статус кампанії (`status`)

Значення з внутрішнього життєвого циклу кампанії. Для фільтрації в query використовуйте зведені значення з розділу «Статус кешбеку» вище; у відповіді приходить детальний статус, наприклад:

Значення	Коли зустрічається
`awaitingBankApproval`	Очікує рішення банку
`awaitingMerchantApproval`	Очікує рішення мерчанта
`approved`	Схвалено, ще не стартувала
`active`	Кампанія активна
`awaitingCompensationConfirmation`	Період завершено, етап звірки / компенсації
`completed`, `paymentConfirmed`, `awaitingCompensationPayment`, `compensationReceived`	Пізніші етапи після звірки
`declined`, `expired`, `deleted`	Відхилено, прострочено або видалено

Повний перелік також у Swagger.

Участь вашого банку (`banks[]`)

Поле	Тип	Опис
`banks`	array	Завжди один елемент — ваш банк
`banks[].id`	uuid	ID банку (з JWT)
`banks[].status`	string	Рішення банку: `pending`, `approved`, `declined`, `expired` (див. «Статус банку»)
`banks[].settlementConfirmed`	boolean	Чи мерчант підтвердив врегулювання з цим банком
`banks[].bankReportingStatus`	string \| null	Етап звірки після завершення періоду кампанії; `null`, поки період не завершено або банк не `approved`
`banks[].hasBankReport`	boolean	Чи завантажено звіт банку
`banks[].hasSecondBankReport`	boolean	Чи є повторне завантаження звіту банку (після коментарів мерчанта)
`banks[].merchantReportUploadsCount`	number	Скільки разів мерчант завантажував свій звіт

Значення `bankReportingStatus`

Значення	Опис
`awaitingBankReconciliation`	Очікується перший звіт банку
`awaitingMerchantReconciliationConfirmation`	Звіт банку є, очікується дія мерчанта
`awaitingUpdatedBankReconciliation`	Мерчант завантажив звіт, очікується оновлений звіт банку
`awaitingCompensationConfirmation`	Звірка завершена, очікується підтвердження компенсації

Мерчант (`retailer`)

Поле	Тип	Опис
`retailer.retailerId`	uuid	ID мерчанта
`retailer.name`	string	Назва мерчанта

Країна (`country`)

Поле	Тип	Опис
`country.id`	uuid	ID країни
`country.name`	string	Назва країни
`country.code`	string	Код ISO 3166-1 alpha-2
`country.currency.code`	string	Код валюти (наприклад `UAH`)
`country.currency.name`	string	Назва валюти
`country.currency.symbol`	string	Символ валюти
`country.currency.icon`	string	URL іконки валюти (може бути порожнім)

Термінали (`terminals[]`)

Поле	Тип	Опис
`terminals`	array	Термінали, на яких діє кампанія (з деталями зі знімка або довідника)
`terminals[].terminal_id`	string	Ідентифікатор терміналу
`terminals[].terminal_name`	string \| null	Назва (null, якщо невідома)
`terminals[].terminal_location`	string \| null	Локація (null, якщо невідома)
`terminals[].merchant_id`	string \| null	Опційно: ID мерчанта в платіжній системі
`terminals[].merchant_name`	string \| null	Опційно: назва в платіжній системі

Сегмент клієнтів банку (`segment`)

Поле	Тип	Опис
`segment`	object \| null	Сегмент клієнтів вашого банку для цієї кампанії; `null`, якщо мерчант не формував сегмент
`segment.segmentId`	uuid	ID сегмента
`segment.cashbackId`	uuid	ID кампанії
`segment.customersCount`	number	Кількість клієнтів у сегменті
`segment.customerIds`	string[]	Ідентифікатори клієнтів (внутрішні ID Deeployalty)
`segment.formedAt`	string (ISO8601)	Час формування сегмента
`segment.sourceFileName`	string	Назва файлу, з якого мерчант сформував сегмент

Відповідь з помилкою

HTTP-код: 400

Тіло відповіді:

{
  "statusCode": 400,
  "message": [
    "retailerId must be a UUID",
    "name must be shorter than or equal to 27 characters",
    "merchantCompensationPercentage must be at least 0"
  ],
  "error": "Bad Request"
}

Коди помилок:

400 — помилки валідації (невірний UUID, довжина рядка, діапазон числа)
401 — неавторизовано (відсутній або невірний JWT-токен)
403 — заборонено (недостатньо прав — потрібна роль ADMIN або EDITOR)

Отримання списку мерчантів

Метод: GET

Ендпоінт: /retailers

Успішна відповідь

HTTP-код: 200

Тіло відповіді:

[
  {
    "retailerId": "22222222-3333-4333-8444-555555555502",
    "name": "Мерчант (приклад)",
    "webhookUrl": null,
    "apiUrl": null,
    "description": "Опис мерчанта (приклад)",
    "logoUrl": "https://cdn.example.invalid/merchants/logo.png",
    "iosAppUrl": null,
    "androidAppUrl": null,
    "login": null,
    "urlIdent": "example-merchant",
    "rro": null,
    "nameEn": "Example merchant",
    "cardIssuing": null,
    "cardPresentationId": "88888888-9999-4333-8444-555555555508",
    "isReview": false,
    "isMask": false,
    "dataSaleToWebhook": null,
    "domain": ["merchant.example"],
    "excludedBank": null,
    "merchantCategoryCode": ["5411", "5812"],
    "createdAt": "2026-01-01T10:00:00.000Z",
    "updateAt": "2026-01-15T10:00:00.000Z"
  }
]

Отримання даних мерчанта

Метод: GET

Ендпоінт: /retailers/:id

Параметр	Тип	Обов’язковий	Опис
`id`	uuid	Так	ID мерчанта (`retailerId`)

Успішна відповідь

HTTP-код: 200

Тіло відповіді:

{
  "retailerId": "22222222-3333-4333-8444-555555555502",
  "name": "Мерчант (приклад)",
  "webhookUrl": null,
  "apiUrl": null,
  "description": "Опис мерчанта (приклад)",
  "logoUrl": "https://cdn.example.invalid/merchants/logo.png",
  "iosAppUrl": null,
  "androidAppUrl": null,
  "login": null,
  "urlIdent": "example-merchant",
  "rro": null,
  "nameEn": "Example merchant",
  "cardIssuing": null,
  "cardPresentationId": "88888888-9999-4333-8444-555555555508",
  "isReview": false,
  "isMask": false,
  "dataSaleToWebhook": null,
  "domain": ["merchant.example"],
  "excludedBank": null,
  "merchantCategoryCode": ["5411", "5812"],
  "createdAt": "2026-01-01T10:00:00.000Z",
  "updateAt": "2026-01-15T10:00:00.000Z"
}

Підтвердження кешбек-кампанії банком

Метод: POST

Ендпоінт: /cashbacks/:cashbackId/confirm

Параметри (path):

Параметр	Тип	Обов’язковий	Опис
`cashbackId`	uuid	Так	ID кешбеку

Успішна відповідь

HTTP-код: 201

Тіло відповіді:

{
  "id": "11111111-2222-4333-8444-555555555501",
  "status": "awaitingBankApproval",
  "message": "Cashback confirmed successfully",
  "createdAt": "2026-01-15T10:05:00.000Z",
  "updatedAt": "2026-01-15T10:05:00.000Z"
}

Поле	Тип	Опис
`id`	uuid	ID кешбек-кампанії (`cashbackId`)
`status`	string	Статус кампанії після підтвердження (детальний lifecycle, див. `GET /cashbacks/for-bank`)
`message`	string	Текст результату; для кампанії, створеної банком, може бути `Cashback confirmed successfully and campaign auto-approved`
`createdAt`	string (ISO8601)	Час створення кампанії
`updatedAt`	string (ISO8601)	Час останнього оновлення

Відповідь з помилкою

HTTP-код: 400

Тіло відповіді:

{
  "statusCode": 400,
  "message": "Cashback not found",
  "error": "Bad Request"
}

Коди помилок:

400 — Bad Request (кешбек не знайдено, невірний ID кешбеку)
401 — неавторизовано (відсутній або невірний JWT-токен)
403 — заборонено (недостатньо прав — потрібна роль ADMIN або EDITOR, або користувач не є банком)

Відхилення кешбек-кампанії банком

Метод: POST

Ендпоінт: /cashbacks/:cashbackId/reject

Параметри (path):

Параметр	Тип	Обов’язковий	Опис
`cashbackId`	uuid	Так	ID кешбеку

Тіло запиту:

Параметр	Тип	Обов’язковий	Опис
`comment`	string	Ні	Коментар із причиною відхилення

{
  "comment": "Campaign does not meet our requirements"
}

Успішна відповідь

HTTP-код: 201

{
  "id": "11111111-2222-4333-8444-555555555501",
  "status": "awaitingBankApproval",
  "message": "Cashback rejected successfully",
  "createdAt": "2026-01-15T10:05:00.000Z",
  "updatedAt": "2026-01-15T10:05:00.000Z"
}

Поле	Тип	Опис
`id`	uuid	ID кешбек-кампанії (`cashbackId`)
`status`	string	Статус кампанії після відхилення. Для кампанії, створеної банком, зазвичай `declined`. Для кампанії мерчанта статус кампанії може не змінитися (наприклад `awaitingBankApproval`) — відхилення вашого банку видно в `banks[].status` = `declined` у `GET /cashbacks/for-bank`
`message`	string	Завжди `Cashback rejected successfully` при успіху
`createdAt`	string (ISO8601)	Час створення кампанії
`updatedAt`	string (ISO8601)	Час останнього оновлення

Відповідь з помилкою

HTTP-код: 400

Тіло відповіді:

{
  "statusCode": 400,
  "message": "Cashback not found",
  "error": "Bad Request"
}

Коди помилок:

400 — Bad Request (кешбек не знайдено, невірний ID кешбеку)
401 — неавторизовано (відсутній або невірний JWT-токен)
403 — заборонено (недостатньо прав — потрібна роль ADMIN або EDITOR, або користувач не є банком)

API адмін-панелі кешбеку для банків

ENV:

Swagger (OpenAPI)

Авторизація

Як згенерувати Bearer Token

Отримання списку кешбеків

Статус кешбеку

Статус банку

Успішна відповідь

Поля кампанії (корінь об’єкта)

Статус кампанії (status)

Участь вашого банку (banks[])

Значення bankReportingStatus

Мерчант (retailer)

Країна (country)

Термінали (terminals[])

Сегмент клієнтів банку (segment)

Відповідь з помилкою

Отримання списку мерчантів

Успішна відповідь

Отримання даних мерчанта

Успішна відповідь

Підтвердження кешбек-кампанії банком

Параметри (path):

Успішна відповідь

Відповідь з помилкою

Відхилення кешбек-кампанії банком

Параметри (path):

Тіло запиту:

Успішна відповідь

Відповідь з помилкою

Статус кампанії (`status`)

Участь вашого банку (`banks[]`)

Значення `bankReportingStatus`

Мерчант (`retailer`)

Країна (`country`)

Термінали (`terminals[]`)

Сегмент клієнтів банку (`segment`)