# Звітність і платежі (/uk/platform-api/reporting) Ці ендпоінти надають програмний доступ до даних і налаштувань, які також доступні на панелі керування Tapaya Platform. Ви можете використовувати їх для створення власних панелей керування, автоматизації процесів або отримання даних для звітності, незалежно від того, чи вбудовуєте ви Accept SDK, чи керуєте застосунком Tapaya Terminal безпосередньо. Вони автентифікуються так само, за допомогою вашого Server Secret Token. ## Список мерчантів [#list-merchants] Отримайте список мерчантів, зареєстрованих у цій організації. **Ендпоінт:** `GET /integrator/merchant` cURL ```bash curl -X 'GET' 'https://api.tapaya.com/integrator/merchant' \ -H 'Authorization: REPLACE_ME' ``` **Тіло відповіді:** ```json [ { "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e", "merchantToken": "unique_merchant_id_from_your_db", "name": "Acme Corp", "email": "admin@acme.com", "businessType": 1, "city": "Prague", "country": 203, "onboarded": true, "isActive": true } ] ``` Поле `email` містить адресу електронної пошти адміністратора / контактної особи, що наразі збережена в записі мерчанта. Це значення можна використовувати для звірки записів мерчантів у вашому бек-офісі, не отримуючи кожного мерчанта окремо. ## Отримання історії платежів [#retrieve-payment-history] Отримайте список останніх 50 платежів усіх мерчантів вашої організації. Це корисно для аудиту транзакцій або створення подання «Super Admin». Цей ендпоінт завжди повертає останні 50 платежів у межах усієї організації; наразі він не приймає параметрів запиту для мерчанта, статусу, діапазону дат чи пагінації. Щоб знайти конкретний платіж за ID, використовуйте ендпоінт [Отримання деталей платежу](#retrieve-payment-details). **Ендпоінт:** `GET /integrator/organization/payment` cURL ```bash curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment' \ -H 'Authorization: REPLACE_ME' ``` **Тіло відповіді:** ```json [ { "paymentId": "018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f", "paymentToken": "pay_abc123", "paymentProcessorId": 1, "paymentMethodId": 1, "terminalId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a", "locationId": "018f8f2a-6e4b-7f5d-ac4a-5b9d4eaf7a6b", "requestedAmount": 1999, "requestedCurrencyId": 1, "settlementAmount": 1999, "settlementCurrencyId": 1, "statusId": 2, "instrumentLabel": "VISA •••• 4242", "instrumentIdentifier": "4242", "createdAt": "2026-07-15T12:00:00Z", "processedAt": "2026-07-15T12:00:03Z", "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e", "merchantName": "Acme Corp" } ] ``` ## Агрегована статистика [#aggregated-statistics] Отримайте статистику платежів, агреговану за всіма мерчантами вашої організації. Цей ендпоінт повертає загальні обсяги для кожної валюти. **Ендпоінт:** `GET /integrator/organization/payment/stats` cURL ```bash curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/stats' \ -H 'Authorization: REPLACE_ME' ``` **Тіло відповіді:** Масив з одним записом для кожної валюти, у якій ваша організація обробляла платежі. ```json [ { "currencyId": 1, "amount": 4582317 } ] ``` ## Отримання деталей платежу [#retrieve-payment-details] Отримайте повні відомості про один платіж, зокрема про пов'язані з ним транзакції, списання (charges) і повернення коштів. Доступ обмежено вашою організацією; для платежів, що належать іншій організації, повертається `404`. **Платіж (payment)** означає запит на покупку в цілому: одна фіксована сума для одного способу оплати. Він містить одну або кілька **транзакцій (transactions)**, кожна з яких є спробою переказати гроші через процесор. Транзакція містить одне або кілька **списань (charges)**, кожне з яких є конкретною подією розрахунку за певним платіжним інструментом (картка, гаманець, банківський рахунок). Більшість платежів мають рівно одну транзакцію з одним списанням. Платіж може мати кілька транзакцій, коли прикладання картки до терміналу повторюється (кожна спроба прикладання додається як окрема транзакція). Транзакція може мати кілька списань для асинхронних способів оплати, як-от криптовалюта або банківський переказ, коли процесор з часом повідомляє про часткові або повторні події розрахунку (наприклад, недоплачений криптовалютний рахунок, доплачений другим ончейн-платежем). Повернення коштів посилаються безпосередньо на платіж і списання; вони не вкладені в транзакції. `statusId` (`StatusEnum`) відображає поточний стан платежу: | Значення | Назва | Опис | | -------- | -------------- | --------------------------------------------------------- | | `1` | `Pending` | Транзакцію створено, але ще не завершено. | | `2` | `Success` | Транзакцію успішно завершено. | | `3` | `Cancelled` | Транзакцію скасовано до завершення. | | `4` | `Refunded` | Після завершення за транзакцією повернуто кошти. | | `5` | `Failed` | Транзакцію не вдалося завершити. | | `6` | `ActionNeeded` | Для завершення транзакції потрібні додаткові дії клієнта. | **Ендпоінт:** `GET /integrator/organization/payment/{paymentId}` cURL ```bash curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f' \ -H 'Authorization: REPLACE_ME' ``` **Відповіді:** | Код | Опис | | ----- | -------------------------------------------------------- | | `200` | Платіж знайдено | | `404` | Платіж не знайдено або він не належить вашій організації | **Тіло відповіді:** ```json { "paymentId": "018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f", "paymentToken": "pay_abc123", "paymentProcessorId": 1, "paymentMethodId": 1, "terminalId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a", "locationId": "018f8f2a-6e4b-7f5d-ac4a-5b9d4eaf7a6b", "requestedAmount": 1999, "requestedCurrencyId": 1, "settlementAmount": 1999, "settlementCurrencyId": 1, "referralFee": 30, "statusId": 2, "terminalName": "Front Counter", "locationName": "Acme Corp, Prague", "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e", "merchantName": "Acme Corp", "createdAt": "2026-07-15T12:00:00Z", "processedAt": "2026-07-15T12:00:03Z", "transactions": [ { "transactionId": "018f8f2a-7f5c-7a6e-bd5b-6cae5fb0879c", "statusId": 2, "referenceInfo": null, "fxRate": 1.0, "createdAt": "2026-07-15T12:00:00Z", "processedAt": "2026-07-15T12:00:03Z", "cancelledAt": null, "charges": [ { "chargeId": "018f8f2a-8a6d-7b7f-ce6c-7dbf6ac1980d", "chargeToken": "charge_abc123", "statusId": 2, "instrumentLabel": "VISA •••• 4242", "instrumentIdentifier": "4242", "authorizationReference": "123456", "requestedAmount": 1999, "requestedCurrencyId": 1, "settlementAmount": 1999, "settlementCurrencyId": 1, "fxRate": 1.0, "createdAt": "2026-07-15T12:00:03Z" } ] } ], "refunds": [] } ``` ## Повернення коштів за платежем [#refund-a-payment] Поверніть кошти за платежем повністю або частково. Не вказуйте `amount`, щоб повернути всю залишкову суму, за якою проведено розрахунок. **Ендпоінт:** `POST /integrator/organization/payment/{paymentId}/refund` cURL ```bash curl -X 'POST' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/refund' \ -H 'Content-Type: application/json' \ -H 'Authorization: REPLACE_ME' \ -d '{ "amount": 1999, "refundReasonId": 1 }' ``` **Параметри:** | Поле | Тип | Обов'язкове | Опис | | ---------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | | `amount` | `long` | | Сума повернення в найменших одиницях валюти. Не вказуйте її для повного повернення залишкової суми, за якою проведено розрахунок. | | `refundReasonId` | `int` | ✓ | Причина повернення коштів (`RefundReasonEnum`). | **Відповіді:** | Код | Опис | | ----- | -------------------------------------------------------------------------------------------------------------------------- | | `200` | Повернення коштів ініційовано | | `400` | Помилка валідації запиту | | `404` | Платіж не знайдено або він не належить вашій організації | | `409` | За платежем не можна повернути кошти в його поточному стані, або запитана сума перевищує залишок, доступний для повернення | **Тіло відповіді:** ```json { "refundId": "018f8f2a-9b7e-7c8a-df7d-8ecf7bd2a91e", "refundToken": "refund_abc123", "statusId": 1, "refundReasonId": 1, "requestedAmount": 1999, "requestedCurrencyId": 1, "settlementAmount": 1999, "settlementCurrencyId": 1, "fxRate": 1.0, "authorizationReference": null, "referralFeeRefund": null, "createdAt": "2026-07-15T12:05:00Z", "processedAt": null } ``` `referralFeeRefund` і `processedAt` заповнюються асинхронно після того, як процесор підтвердить повернення коштів. У негайній відповіді вони завжди мають значення `null`; щоб побачити остаточний стан, періодично опитуйте [Отримання деталей платежу](#retrieve-payment-details). Історія платежів повертає лише останні платежі, тож старіший платіж із поверненням коштів може з неї випасти.