# Reporting und Zahlungen (/de/platform-api/reporting)





Diese Endpoints bieten programmatischen Zugriff auf Daten und Einstellungen, die auch im Dashboard der Tapaya Platform verfügbar sind. Damit können Sie eigene Dashboards erstellen, Abläufe automatisieren oder Reporting-Daten abrufen, unabhängig davon, ob Sie das Accept SDK einbetten oder die App Tapaya Terminal direkt ansteuern. Die Authentifizierung erfolgt auf dieselbe Weise, mit Ihrem Server Secret Token.

## Händler auflisten [#list-merchants]

Listet die Händler auf, die unter dieser Organisation registriert sind.

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

**Antworttext:**

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

Das Feld `email` enthält die Administrator- bzw. Kontakt-E-Mail-Adresse, die aktuell im Händlerdatensatz gespeichert ist. Mit diesem Wert können Sie
Händlerdatensätze in Ihrem Backoffice abgleichen, ohne jeden Händler einzeln abrufen zu müssen.

## Zahlungsverlauf abrufen [#retrieve-payment-history]

Ruft eine Liste der letzten 50 Zahlungen über alle Händler Ihrer Organisation hinweg ab. Das ist nützlich, um Transaktionen zu prüfen oder eine „Super Admin“-Ansicht zu erstellen.

<Callout title="Keine Filterung oder Paginierung" type="info">
  Dieser Endpoint liefert immer die letzten 50 Zahlungen der gesamten Organisation; er akzeptiert derzeit keine Query-Parameter für
  Händler, Status, Zeitraum oder Paginierung. Verwenden Sie den Endpoint [Zahlungsdetails abrufen](#retrieve-payment-details),
  um eine bestimmte Zahlung anhand ihrer ID nachzuschlagen.
</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>

**Antworttext:**

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

## Aggregierte Statistiken [#aggregated-statistics]

Ruft Zahlungsstatistiken ab, die über alle Händler Ihrer Organisation aggregiert sind. Dieser Endpoint liefert die Gesamtvolumina je Währung.

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

**Antworttext:**

Ein Array mit einem Eintrag pro Währung, in der Ihre Organisation Zahlungen abgewickelt hat.

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

## Zahlungsdetails abrufen [#retrieve-payment-details]

Ruft alle Details zu einer einzelnen Zahlung ab, einschließlich der zugrunde liegenden Transaktionen, Belastungen und etwaiger Erstattungen. Der Zugriff ist auf Ihre Organisation beschränkt; für Zahlungen einer anderen Organisation wird `404` zurückgegeben.

<Callout title="Zahlung, Transaktion und Belastung" type="info">
  Eine **Zahlung** ist die Kaufanforderung als Ganzes: ein fester Betrag für eine Zahlungsmethode. Sie enthält eine oder
  mehrere **Transaktionen**, von denen jede einen Versuch darstellt, Geld über einen Zahlungsabwickler zu bewegen. Eine Transaktion enthält
  eine oder mehrere **Belastungen** (Charges), jede ein konkretes Abrechnungsereignis für ein bestimmtes Zahlungsinstrument (Karte, Wallet,
  Bankkonto).

  Die meisten Zahlungen haben genau eine Transaktion mit einer Belastung. Eine Zahlung kann mehrere Transaktionen haben, wenn das
  Vorhalten am Kartenterminal wiederholt wird (jeder Vorhalteversuch wird als eigene Transaktion zugeordnet). Eine Transaktion kann
  bei asynchronen Zahlungsmethoden wie Krypto oder Banküberweisung mehrere Belastungen haben, wenn der Zahlungsabwickler im Lauf der Zeit
  Teil- oder wiederholte Abrechnungsereignisse meldet (z. B. eine zu gering bezahlte Krypto-Rechnung, die durch eine zweite
  On-Chain-Zahlung aufgestockt wird). Erstattungen verweisen direkt auf die Zahlung und die Belastung; sie sind nicht den Transaktionen untergeordnet.
</Callout>

`statusId` (`StatusEnum`) gibt den aktuellen Status der Zahlung wieder:

| Wert | Name           | Beschreibung                                                            |
| ---- | -------------- | ----------------------------------------------------------------------- |
| `1`  | `Pending`      | Die Transaktion wurde erstellt, aber noch nicht abgeschlossen.          |
| `2`  | `Success`      | Die Transaktion wurde erfolgreich abgeschlossen.                        |
| `3`  | `Cancelled`    | Die Transaktion wurde vor dem Abschluss abgebrochen.                    |
| `4`  | `Refunded`     | Die Transaktion wurde nach dem Abschluss erstattet.                     |
| `5`  | `Failed`       | Die Transaktion konnte nicht abgeschlossen werden.                      |
| `6`  | `ActionNeeded` | Die Transaktion erfordert zum Abschluss eine weitere Aktion des Kunden. |

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

**Antworten:**

| Code  | Beschreibung                                                   |
| ----- | -------------------------------------------------------------- |
| `200` | Zahlung gefunden                                               |
| `404` | Zahlung nicht gefunden oder gehört nicht zu Ihrer Organisation |

**Antworttext:**

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

## Zahlung erstatten [#refund-a-payment]

Erstattet eine Zahlung vollständig oder teilweise. Lassen Sie `amount` weg, um den gesamten verbleibenden abgerechneten Betrag zu erstatten.

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

**Parameter:**

| Feld             | Typ    | Erforderlich | Beschreibung                                                                                                                                 |
| ---------------- | ------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`         | `long` |              | Zu erstattender Betrag in der kleinsten Währungseinheit. Weglassen für eine vollständige Erstattung des verbleibenden abgerechneten Betrags. |
| `refundReasonId` | `int`  | ✓            | Grund der Erstattung (`RefundReasonEnum`).                                                                                                   |

**Antworten:**

| Code  | Beschreibung                                                                                                                            |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Erstattung eingeleitet                                                                                                                  |
| `400` | Validierungsfehler der Anfrage                                                                                                          |
| `404` | Zahlung nicht gefunden oder gehört nicht zu Ihrer Organisation                                                                          |
| `409` | Die Zahlung kann in ihrem aktuellen Status nicht erstattet werden, oder der angeforderte Betrag übersteigt den noch erstattbaren Betrag |

**Antworttext:**

```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="Asynchrone Abrechnung" type="info">
  `referralFeeRefund` und `processedAt` werden asynchron befüllt,
  sobald der Zahlungsabwickler die Erstattung bestätigt. In der unmittelbaren Antwort sind sie immer `null`; fragen Sie
  [Zahlungsdetails abrufen](#retrieve-payment-details) regelmäßig ab, um den endgültigen Status zu sehen. Der Zahlungsverlauf liefert nur
  die letzten Zahlungen, daher kann eine ältere erstattete Zahlung daraus herausfallen.
</Callout>