Reporting a platby
Výpis obchodníků, historie a podrobnosti plateb, statistiky a vracení plateb.
Tyto endpointy poskytují programový přístup k datům a nastavením, která jsou dostupná také v dashboardu Tapaya Platform. Můžete je využít k vytvoření vlastních dashboardů, automatizaci procesů nebo stahování dat pro reporting, bez ohledu na to, zda vkládáte Accept SDK, nebo ovládáte přímo aplikaci Tapaya Terminal. Ověřují se stejným způsobem, pomocí vašeho tokenu Server Secret Token.
Výpis obchodníků
Vypíše obchodníky registrované v této organizaci.
Endpoint: GET /integrator/merchant
curl -X 'GET' 'https://api.tapaya.com/integrator/merchant' \
-H 'Authorization: REPLACE_ME'Tělo odpovědi:
[
{
"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"
}
]Pole email je e-mail administrátora / kontaktní e-mail aktuálně uložený v záznamu obchodníka. Tuto hodnotu můžete
použít k odsouhlasení záznamů obchodníků ve svém back office, aniž byste museli načítat každého obchodníka zvlášť.
commissionProfileIds uvádí cenové profily přiřazené obchodníkovi. Členy, terminály, rozpracovaný onboarding a ceny najdete ve Správě obchodníků.
Načtení historie plateb
Vypíše platby všech obchodníků ve vaší organizaci, od nejnovějších. Bez parametrů dotazu získáte posledních 50.
Endpoint: GET /integrator/organization/payment, nebo GET /integrator/merchant/{merchantId}/payment pro jednoho obchodníka
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment' \
-H 'Authorization: REPLACE_ME'Tělo odpovědi:
[
{
"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"
}
]Parametry:
| Pole | Popis |
|---|---|
fromDate | První zahrnutý den ve formátu YYYY-MM-DD v UTC. |
toDate | Poslední zahrnutý den ve formátu YYYY-MM-DD v UTC. |
page | Číslo stránky počínaje 1. Výchozí hodnota je 1; nižší hodnoty použijí stránku 1. |
pageSize | Počet řádků na stránce. Výchozí hodnota je 50, rozsah je omezen na 1 až 100. |
merchantId | Pouze výpis plateb organizace. Omezí výsledky na tohoto obchodníka. |
paymentMethodId | Jedna číselná platební metoda. |
paymentMethodIds | Více platebních metod. Parametr opakujte jednou pro každou metodu; platba odpovídá, pokud odpovídá kterékoli z nich. |
statusId | Jeden stav platby. Nepodporované hodnoty vracejí 400. |
includeSummary | true vrátí místo pole objekt s items, summary a pageSummary. |
Pro získání součtů spolu s výpisem přidejte 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 obsahuje stejné platby jako odpověď ve formě pole; zde je zkrácené.
summarypokrývá všechny platby odpovídající filtrům.pageSummarypokrývá pouze vrácenou stránku, i když je prázdná.amountsByCurrencyobsahuje jednu položku pro každou požadovanou měnu, v nejmenších jednotkách měny. Částky různých měn nikdy nesčítejte.failureRateje počet neúspěšných plateb dělený součtem úspěšných a neúspěšných plateb, vyjádřený v procentech a zaokrouhlený na dvě desetinná místa. Pokud nejsou žádné z nich, je0.
Souhrnné statistiky
Získá statistiky plateb souhrnně za všechny obchodníky ve vaší organizaci. Tento endpoint vrací celkové objemy podle měny.
Endpoint: GET /integrator/organization/payment/stats
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/stats' \
-H 'Authorization: REPLACE_ME'Tělo odpovědi:
Pole s jednou položkou pro každou měnu, ve které vaše organizace zpracovala platby.
[
{
"currencyId": 1,
"amount": 4582317
}
]Načtení podrobností platby
Získá úplné podrobnosti o jedné platbě, včetně jejích podkladových transakcí, objektů charge a případných vratek. Omezeno na vaši organizaci; platby patřící jiné organizaci vrátí 404.
Platba, transakce a charge
Platba je nákupní požadavek jako celek: jedna pevná částka pro jednu platební metodu. Obsahuje jednu nebo více transakcí, z nichž každá představuje pokus o přesun peněz přes zpracovatele plateb. Transakce obsahuje jeden nebo více objektů charge, z nichž každý je konkrétní událostí zúčtování vůči určitému platebnímu prostředku (karta, peněženka, bankovní účet).
Většina plateb má právě jednu transakci s jedním objektem charge. Platba může mít více transakcí, když se přiložení karty k terminálu opakuje (každý pokus o přiložení je k platbě přiřazen jako samostatná transakce). Transakce může mít více objektů charge u asynchronních platebních metod, jako jsou kryptoměny nebo bankovní převod, kdy zpracovatel hlásí částečné nebo opakované události zúčtování v průběhu času (např. nedoplacená kryptoměnová faktura doplacená druhou platbou na blockchainu). Vratky odkazují přímo na platbu a objekt charge; nejsou vnořené pod transakcemi.
statusId (StatusEnum) vyjadřuje aktuální stav platby:
| Hodnota | Název | Popis |
|---|---|---|
1 | Pending | Transakce byla vytvořena, ale ještě nebyla dokončena. |
2 | Success | Transakce byla úspěšně dokončena. |
3 | Cancelled | Transakce byla zrušena před dokončením. |
4 | Refunded | Transakce byla po dokončení vrácena. |
5 | Failed | Transakci se nepodařilo dokončit. |
6 | ActionNeeded | Transakce k dokončení vyžaduje další akci zákazníka. |
Endpoint: GET /integrator/organization/payment/{paymentToken}
Pro detail platby i refundaci použijte paymentToken z historie plateb. Pole paymentId je UUID vygenerované serverem; není to token používaný v těchto URL.
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/pay_abc123' \
-H 'Authorization: REPLACE_ME'Odpovědi:
| Kód | Popis |
|---|---|
200 | Platba nalezena |
404 | Platba nenalezena nebo nepatří vaší organizaci |
Tělo odpovědi:
{
"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": []
}Vrácení platby
Vrátí platbu, zcela nebo částečně. Pokud vynecháte amount, vrátí se celá zbývající zúčtovaná částka.
Endpoint: 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
}'Parametry:
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
amount | long | Částka k vrácení v nejmenších jednotkách měny. Pro úplnou vratku zbývající zúčtované částky ji vynechte. | |
refundReasonId | int | ✓ | Důvod vratky (RefundReasonEnum). |
Odpovědi:
| Kód | Popis |
|---|---|
200 | Vratka zahájena |
400 | Chyba validace požadavku |
404 | Platba nenalezena nebo nepatří vaší organizaci |
409 | Platbu nelze v jejím aktuálním stavu vrátit nebo požadovaná částka převyšuje zbývající částku, kterou lze vrátit |
Tělo odpovědi:
{
"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
}Asynchronní zúčtování
referralFeeRefund a processedAt se vyplní asynchronně
poté, co zpracovatel plateb vratku potvrdí. V okamžité odpovědi jsou vždy null; konečný stav zjistíte opakovaným voláním endpointu
Načtení podrobností platby. Historie plateb vrací pouze
nejnovější platby, takže starší vrácená platba z ní může vypadnout.