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





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ů [#list-merchants]

Vypíše obchodníky registrované v této organizaci.

**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>

**Tělo odpovědi:**

```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á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 [#retrieve-payment-history]

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“.

<Callout title="Bez filtrování a stránkování" type="info">
  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](#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>

**Tělo odpovědi:**

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

## Souhrnné statistiky [#aggregated-statistics]

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`

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

**Tělo odpovědi:**

Pole s jednou položkou pro každou měnu, ve které vaše organizace zpracovala platby.

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

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

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

<Callout title="Platba, transakce a charge" type="info">
  **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.
</Callout>

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

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

**Odpovědi:**

| Kód   | Popis                                          |
| ----- | ---------------------------------------------- |
| `200` | Platba nalezena                                |
| `404` | Platba nenalezena nebo nepatří vaší organizaci |

**Tělo odpovědi:**

```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ácení platby [#refund-a-payment]

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`

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

**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:**

```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="Asynchronní zúčtování" type="info">
  `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](#retrieve-payment-details). Historie plateb vrací pouze
  nejnovější platby, takže starší vrácená platba z ní může vypadnout.
</Callout>