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
    }
]

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ášť.

Načtení historie plateb

Získá seznam posledních 50 plateb napříč všemi obchodníky ve vaší organizaci. Hodí se pro audit transakcí nebo vytvoření pohledu „Super Admin“.

Bez filtrování a stránkování

Tento endpoint vždy vrací posledních 50 plateb v rámci celé organizace; zatím nepřijímá parametry dotazu pro obchodníka, stav, časové období ani stránkování. Ke konkrétní platbě podle ID použijte endpoint Načtení podrobností platby.

Endpoint: GET /integrator/organization/payment

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": 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"
    }
]

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/{paymentId}

curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f' \
-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": 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": []
}

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/{paymentId}/refund

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
    }'

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": 1,
    "settlementAmount": 1999,
    "settlementCurrencyId": 1,
    "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.

Chybí vám něco na této stránce?Navrhněte funkci. Připojíme tuto stránku, aby tým viděl souvislosti.

Reporting a platby

Výpis obchodníků

Načtení historie plateb

Souhrnné statistiky

Načtení podrobností platby

Vrácení platby

Na této stránce