# Reporting a platby (/sk/platform-api/reporting)





Tieto endpointy poskytujú programový prístup k dátam a nastaveniam, ktoré sú dostupné aj v dashboarde Tapaya Platform. Môžete ich využiť na vytvorenie vlastných dashboardov, automatizáciu procesov alebo sťahovanie dát na reporting bez ohľadu na to, či vkladáte Accept SDK, alebo ovládate priamo aplikáciu Tapaya Terminal. Autentifikujú sa rovnakým spôsobom, pomocou vášho tokenu Server Secret Token.

## Výpis obchodníkov [#list-merchants]

Vypíše obchodníkov registrovaných v tejto organizácii.

**Endpoint:** `GET /integrator/merchant`

<CodeBlockTabs defaultValue="curl" groupId="http-client">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      cURL
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X 'GET' 'https://api.tapaya.com/integrator/merchant' \
    -H 'Authorization: REPLACE_ME'
    ```
  </CodeBlockTab>
</CodeBlockTabs>

**Telo odpovede:**

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

Pole `email` je e-mail administrátora / kontaktný e-mail aktuálne uložený v zázname obchodníka. Túto hodnotu môžete
použiť na odsúhlasenie záznamov obchodníkov vo svojom back office bez toho, aby ste museli načítavať každého obchodníka zvlášť.

## Načítanie histórie platieb [#retrieve-payment-history]

Získa zoznam posledných 50 platieb všetkých obchodníkov vo vašej organizácii. Hodí sa na audit transakcií alebo vytvorenie pohľadu „Super Admin“.

<Callout title="Bez filtrovania a stránkovania" type="info">
  Tento endpoint vždy vracia posledných 50 platieb v rámci celej organizácie; zatiaľ neprijíma parametre dopytu pre
  obchodníka, stav, časové obdobie ani stránkovanie. Na vyhľadanie konkrétnej platby podľa ID použite endpoint
  [Načítanie podrobností platby](#retrieve-payment-details).
</Callout>

**Endpoint:** `GET /integrator/organization/payment`

<CodeBlockTabs defaultValue="curl" groupId="http-client">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      cURL
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment' \
    -H 'Authorization: REPLACE_ME'
    ```
  </CodeBlockTab>
</CodeBlockTabs>

**Telo odpovede:**

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

## Súhrnné štatistiky [#aggregated-statistics]

Získa štatistiky platieb súhrnne za všetkých obchodníkov vo vašej organizácii. Tento endpoint vracia celkové objemy podľa meny.

**Endpoint:** `GET /integrator/organization/payment/stats`

<CodeBlockTabs defaultValue="curl" groupId="http-client">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      cURL
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/stats' \
    -H 'Authorization: REPLACE_ME'
    ```
  </CodeBlockTab>
</CodeBlockTabs>

**Telo odpovede:**

Pole s jednou položkou pre každú menu, v ktorej vaša organizácia spracovala platby.

```json
[
    {
        "currencyId": 1,
        "amount": 4582317
    }
]
```

## Načítanie podrobností platby [#retrieve-payment-details]

Získa úplné podrobnosti o jednej platbe vrátane jej podkladových transakcií, strhnutí (charges) a prípadných refundácií. Obmedzené na vašu organizáciu; platby patriace inej organizácii vrátia `404`.

<Callout title="Platba, transakcia a strhnutie" type="info">
  **Platba** je nákupná požiadavka ako celok: jedna pevná suma pre jednu platobnú metódu. Obsahuje jednu alebo
  viac **transakcií**, z ktorých každá predstavuje pokus o presun peňazí cez spracovateľa platieb. Transakcia obsahuje
  jedno alebo viac &#x2A;*strhnutí (charges)**, z ktorých každé je konkrétnou udalosťou zúčtovania voči určitému platobnému prostriedku (karta, peňaženka, bankový
  účet).

  Väčšina platieb má práve jednu transakciu s jedným strhnutím. Platba môže mať viac transakcií, keď sa
  priloženie karty k terminálu opakuje (každý pokus o priloženie je k platbe priradený ako samostatná transakcia). Transakcia môže mať
  viac strhnutí pri asynchrónnych platobných metódach, ako sú kryptomeny alebo bankový prevod, keď spracovateľ hlási
  čiastočné alebo opakované udalosti zúčtovania v priebehu času (napr. nedoplatená kryptomenová faktúra doplatená druhou
  platbou na blockchaine). Refundácie odkazujú priamo na platbu a strhnutie; nie sú vnorené pod transakciami.
</Callout>

`statusId` (`StatusEnum`) vyjadruje aktuálny stav platby:

| Hodnota | Názov          | Popis                                                     |
| ------- | -------------- | --------------------------------------------------------- |
| `1`     | `Pending`      | Transakcia bola vytvorená, ale ešte nebola dokončená.     |
| `2`     | `Success`      | Transakcia bola úspešne dokončená.                        |
| `3`     | `Cancelled`    | Transakcia bola zrušená pred dokončením.                  |
| `4`     | `Refunded`     | Transakcia bola po dokončení refundovaná.                 |
| `5`     | `Failed`       | Transakciu sa nepodarilo dokončiť.                        |
| `6`     | `ActionNeeded` | Transakcia na dokončenie vyžaduje ďalšiu akciu zákazníka. |

**Endpoint:** `GET /integrator/organization/payment/{paymentId}`

<CodeBlockTabs defaultValue="curl" groupId="http-client">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      cURL
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f' \
    -H 'Authorization: REPLACE_ME'
    ```
  </CodeBlockTab>
</CodeBlockTabs>

**Odpovede:**

| Kód   | Popis                                             |
| ----- | ------------------------------------------------- |
| `200` | Platba sa našla                                   |
| `404` | Platba sa nenašla alebo nepatrí vašej organizácii |

**Telo odpovede:**

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

## Vrátenie platby [#refund-a-payment]

Vráti platbu, úplne alebo čiastočne. Ak vynecháte `amount`, vráti sa celá zostávajúca zúčtovaná suma.

**Endpoint:** `POST /integrator/organization/payment/{paymentId}/refund`

<CodeBlockTabs defaultValue="curl" groupId="http-client">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      cURL
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="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
        }'
    ```
  </CodeBlockTab>
</CodeBlockTabs>

**Parametre:**

| Pole             | Typ    | Povinné | Popis                                                                                                           |
| ---------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- |
| `amount`         | `long` |         | Suma na vrátenie v najmenších jednotkách meny. Pre úplnú refundáciu zostávajúcej zúčtovanej sumy ju vynechajte. |
| `refundReasonId` | `int`  | ✓       | Dôvod refundácie (`RefundReasonEnum`).                                                                          |

**Odpovede:**

| Kód   | Popis                                                                                                            |
| ----- | ---------------------------------------------------------------------------------------------------------------- |
| `200` | Refundácia sa začala                                                                                             |
| `400` | Chyba validácie požiadavky                                                                                       |
| `404` | Platba sa nenašla alebo nepatrí vašej organizácii                                                                |
| `409` | Platbu nemožno v jej aktuálnom stave vrátiť alebo požadovaná suma prevyšuje zostávajúcu sumu, ktorú možno vrátiť |

**Telo odpovede:**

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

<Callout title="Asynchrónne zúčtovanie" type="info">
  `referralFeeRefund` a `processedAt` sa vyplnia asynchrónne
  potom, ako spracovateľ platieb refundáciu potvrdí. V okamžitej odpovedi sú vždy `null`; konečný stav zistíte opakovaným volaním endpointu
  [Načítanie podrobností platby](#retrieve-payment-details). História platieb vracia iba
  najnovšie platby, takže staršia refundovaná platba z nej môže vypadnúť.
</Callout>