Звітність і платежі
Отримуйте список мерчантів, історію та деталі платежів, статистику, а також повертайте кошти за платежами.
Ці ендпоінти надають програмний доступ до даних і налаштувань, які також доступні на панелі керування Tapaya Platform. Ви можете використовувати їх для створення власних панелей керування, автоматизації процесів або отримання даних для звітності, незалежно від того, чи вбудовуєте ви Accept SDK, чи керуєте застосунком Tapaya Terminal безпосередньо. Вони автентифікуються так само, за допомогою вашого Server Secret Token.
Список мерчантів
Отримайте список мерчантів, зареєстрованих у цій організації.
Ендпоінт: GET /integrator/merchant
curl -X 'GET' 'https://api.tapaya.com/integrator/merchant' \
-H 'Authorization: REPLACE_ME'Тіло відповіді:
[
{
"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,
"mcc": "5411",
"commissionProfileId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a",
"commissionProfileIds": [
"018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a"
],
"createdAt": "2026-07-01T10:00:00Z",
"updatedAt": "2026-07-15T12:00:00Z"
}
]Поле email містить адресу електронної пошти адміністратора / контактної особи, що наразі збережена в записі мерчанта. Це значення
можна використовувати для звірки записів мерчантів у вашому бек-офісі, не отримуючи кожного мерчанта окремо.
commissionProfileIds перелічує комісійні профілі, призначені мерчанту. Учасники, термінали, чернетки онбордингу й тарифи описані в розділі Керування мерчантами.
Отримання історії платежів
Отримайте платежі всіх мерчантів вашої організації, від найновіших. Без параметрів запиту ви отримаєте останні 50.
Ендпоінт: GET /integrator/organization/payment або GET /integrator/merchant/{merchantId}/payment для одного мерчанта
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment' \
-H 'Authorization: REPLACE_ME'Тіло відповіді:
[
{
"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": 978,
"settlementAmount": 1999,
"settlementCurrencyId": 978,
"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"
}
]Параметри:
| Поле | Опис |
|---|---|
fromDate | Перший день, який слід включити, у форматі YYYY-MM-DD в UTC. |
toDate | Останній день, який слід включити, у форматі YYYY-MM-DD в UTC. |
page | Номер сторінки, починаючи з 1. За замовчуванням 1; менші значення використовують сторінку 1. |
pageSize | Кількість рядків на сторінці. За замовчуванням 50, обмежено діапазоном від 1 до 100. |
merchantId | Лише список платежів організації. Обмежує результати цим мерчантом. |
paymentMethodId | Один числовий спосіб оплати. |
paymentMethodIds | Кілька способів оплати. Повторіть параметр для кожного способу; платіж відповідає, якщо збігається з будь-яким із них. |
statusId | Один статус платежу. Непідтримувані значення повертають 400. |
includeSummary | true, щоб замість масиву отримати об'єкт з items, summary і pageSummary. |
Щоб разом зі списком отримати підсумки, додайте includeSummary=true:
curl 'https://api.sandbox.tapaya.com/integrator/organization/payment?fromDate=2026-10-01&toDate=2026-10-31&page=1&pageSize=25&includeSummary=true' \
-H 'Authorization: REPLACE_ME'{
"items": [],
"summary": {
"failureRate": 4.76,
"totalCount": 44,
"totalCountPending": 1,
"totalCountSuccess": 40,
"totalCountCancelled": 1,
"totalCountRefunded": 0,
"totalCountFailed": 2,
"totalCountActionNeeded": 0,
"amountsByCurrency": [
{
"currencyId": 978,
"totalAmount": 87956,
"totalAmountPending": 1999,
"totalAmountSuccess": 79960,
"totalAmountCancelled": 1999,
"totalAmountRefunded": 0,
"totalAmountFailed": 3998,
"totalAmountActionNeeded": 0
}
]
},
"pageSummary": {
"failureRate": 0,
"totalCount": 25,
"totalCountPending": 1,
"totalCountSuccess": 24,
"totalCountCancelled": 0,
"totalCountRefunded": 0,
"totalCountFailed": 0,
"totalCountActionNeeded": 0,
"amountsByCurrency": [
{
"currencyId": 978,
"totalAmount": 49975,
"totalAmountPending": 1999,
"totalAmountSuccess": 47976,
"totalAmountCancelled": 0,
"totalAmountRefunded": 0,
"totalAmountFailed": 0,
"totalAmountActionNeeded": 0
}
]
}
}items містить ті самі платежі, що й відповідь у вигляді масиву; тут його скорочено.
summaryохоплює всі платежі, що відповідають фільтрам.pageSummaryохоплює лише повернуту сторінку, навіть якщо вона порожня.amountsByCurrencyмістить один запис для кожної запитаної валюти, у найменших одиницях. Ніколи не додавайте суми різних валют.failureRateдорівнює кількості невдалих платежів, поділеній на суму успішних і невдалих платежів, у відсотках з округленням до двох десяткових знаків. Якщо немає ні тих, ні інших, значення дорівнює0.
Агрегована статистика
Отримайте статистику платежів, агреговану за всіма мерчантами вашої організації. Цей ендпоінт повертає загальні обсяги для кожної валюти.
Ендпоінт: GET /integrator/organization/payment/stats
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/stats' \
-H 'Authorization: REPLACE_ME'Тіло відповіді:
Масив з одним записом для кожної валюти, у якій ваша організація обробляла платежі.
[
{
"currencyId": 1,
"amount": 4582317
}
]Отримання деталей платежу
Отримайте повні відомості про один платіж, зокрема про пов'язані з ним транзакції, списання (charges) і повернення коштів. Доступ обмежено вашою організацією; для платежів, що належать іншій організації, повертається 404.
Платіж, транзакція та списання
Платіж (payment) означає запит на покупку в цілому: одна фіксована сума для одного способу оплати. Він містить одну або кілька транзакцій (transactions), кожна з яких є спробою переказати гроші через процесор. Транзакція містить одне або кілька списань (charges), кожне з яких є конкретною подією розрахунку за певним платіжним інструментом (картка, гаманець, банківський рахунок).
Більшість платежів мають рівно одну транзакцію з одним списанням. Платіж може мати кілька транзакцій, коли прикладання картки до терміналу повторюється (кожна спроба прикладання додається як окрема транзакція). Транзакція може мати кілька списань для асинхронних способів оплати, як-от криптовалюта або банківський переказ, коли процесор з часом повідомляє про часткові або повторні події розрахунку (наприклад, недоплачений криптовалютний рахунок, доплачений другим ончейн-платежем). Повернення коштів посилаються безпосередньо на платіж і списання; вони не вкладені в транзакції.
statusId (StatusEnum) відображає поточний стан платежу:
| Значення | Назва | Опис |
|---|---|---|
1 | Pending | Транзакцію створено, але ще не завершено. |
2 | Success | Транзакцію успішно завершено. |
3 | Cancelled | Транзакцію скасовано до завершення. |
4 | Refunded | Після завершення за транзакцією повернуто кошти. |
5 | Failed | Транзакцію не вдалося завершити. |
6 | ActionNeeded | Для завершення транзакції потрібні додаткові дії клієнта. |
Ендпоінт: GET /integrator/organization/payment/{paymentToken}
Для деталей платежу та повернення коштів використовуйте paymentToken з історії платежів. Поле paymentId є UUID, згенерованим сервером; це не токен, який використовується в цих URL.
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/pay_abc123' \
-H 'Authorization: REPLACE_ME'Відповіді:
| Код | Опис |
|---|---|
200 | Платіж знайдено |
404 | Платіж не знайдено або він не належить вашій організації |
Тіло відповіді:
{
"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": 978,
"settlementAmount": 1999,
"settlementCurrencyId": 978,
"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": 978,
"settlementAmount": 1999,
"settlementCurrencyId": 978,
"fxRate": 1.0,
"createdAt": "2026-07-15T12:00:03Z"
}
]
}
],
"refunds": []
}Повернення коштів за платежем
Поверніть кошти за платежем повністю або частково. Не вказуйте amount, щоб повернути всю залишкову суму, за якою проведено розрахунок.
Ендпоінт: POST /integrator/organization/payment/{paymentToken}/refund
curl -X 'POST' 'https://api.tapaya.com/integrator/organization/payment/pay_abc123/refund' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
"amount": 1999,
"refundReasonId": 1
}'Параметри:
| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
amount | long | Сума повернення в найменших одиницях валюти. Не вказуйте її для повного повернення залишкової суми, за якою проведено розрахунок. | |
refundReasonId | int | ✓ | Причина повернення коштів (RefundReasonEnum). |
Відповіді:
| Код | Опис |
|---|---|
200 | Повернення коштів ініційовано |
400 | Помилка валідації запиту |
404 | Платіж не знайдено або він не належить вашій організації |
409 | За платежем не можна повернути кошти в його поточному стані, або запитана сума перевищує залишок, доступний для повернення |
Тіло відповіді:
{
"refundId": "018f8f2a-9b7e-7c8a-df7d-8ecf7bd2a91e",
"refundToken": "refund_abc123",
"statusId": 1,
"refundReasonId": 1,
"requestedAmount": 1999,
"requestedCurrencyId": 978,
"settlementAmount": 1999,
"settlementCurrencyId": 978,
"fxRate": 1.0,
"authorizationReference": null,
"referralFeeRefund": null,
"createdAt": "2026-07-15T12:05:00Z",
"processedAt": null
}Асинхронний розрахунок
referralFeeRefund і processedAt заповнюються асинхронно
після того, як процесор підтвердить повернення коштів. У негайній відповіді вони завжди мають значення null; щоб побачити остаточний стан, періодично опитуйте
Отримання деталей платежу. Історія платежів повертає лише
останні платежі, тож старіший платіж із поверненням коштів може з неї випасти.