Tapaya

Звітність і платежі

Отримуйте список мерчантів, історію та деталі платежів, статистику, а також повертайте кошти за платежами.

Ці ендпоінти надають програмний доступ до даних і налаштувань, які також доступні на панелі керування 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.
includeSummarytrue, щоб замість масиву отримати об'єкт з 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) відображає поточний стан платежу:

ЗначенняНазваОпис
1PendingТранзакцію створено, але ще не завершено.
2SuccessТранзакцію успішно завершено.
3CancelledТранзакцію скасовано до завершення.
4RefundedПісля завершення за транзакцією повернуто кошти.
5FailedТранзакцію не вдалося завершити.
6ActionNeededДля завершення транзакції потрібні додаткові дії клієнта.

Ендпоінт: 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
    }'

Параметри:

ПолеТипОбов'язковеОпис
amountlongСума повернення в найменших одиницях валюти. Не вказуйте її для повного повернення залишкової суми, за якою проведено розрахунок.
refundReasonIdint✓Причина повернення коштів (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; щоб побачити остаточний стан, періодично опитуйте Отримання деталей платежу. Історія платежів повертає лише останні платежі, тож старіший платіж із поверненням коштів може з неї випасти.

Чогось бракує на цій сторінці?Надішліть запит на функцію. Ми додамо цю сторінку, щоб команда бачила контекст.