# Reporting & Payments (/platform-api/reporting)





These endpoints provide programmatic access to data and settings that are also available in the Tapaya Platform dashboard. You can use them to build custom dashboards, automate workflows, or pull reporting data, regardless of whether you embed the Accept SDK or drive the Tapaya Terminal app directly. They are authenticated the same way, with your Server Secret Token.

## List Merchants [#list-merchants]

List merchants registered under this organization.

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

**Response body:**

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

The `email` field is the admin / contact email currently stored on the merchant record. This is the value you can
use to reconcile merchant records in your back office without having to fetch each merchant one by one.

`commissionProfileIds` lists the merchant's assigned commission profiles. For members, terminals, onboarding drafts and pricing, see [Merchant Management](/platform-api/merchant_management).

## Retrieve Payment History [#retrieve-payment-history]

List payments across all merchants in your organization, newest first. Without query parameters, you get the latest 50.

**Endpoint:** `GET /integrator/organization/payment`, or `GET /integrator/merchant/{merchantId}/payment` for one 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/organization/payment' \
    -H 'Authorization: REPLACE_ME'
    ```
  </CodeBlockTab>
</CodeBlockTabs>

**Response body:**

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

**Parameters:**

| Parameter          | Description                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------- |
| `fromDate`         | First day to include, as `YYYY-MM-DD` in UTC.                                                 |
| `toDate`           | Last day to include, as `YYYY-MM-DD` in UTC.                                                  |
| `page`             | Page number, starting at 1. Defaults to 1; lower values use page 1.                           |
| `pageSize`         | Rows per page. Defaults to 50 and is limited to 1 through 100.                                |
| `merchantId`       | Organization payment list only. Restrict results to this merchant.                            |
| `paymentMethodId`  | One numeric payment method.                                                                   |
| `paymentMethodIds` | Several payment methods. Repeat the parameter once per method; a payment matches any of them. |
| `statusId`         | One [payment status](#retrieve-payment-details). Unsupported values return `400`.             |
| `includeSummary`   | `true` to return an object with `items`, `summary` and `pageSummary` instead of an array.     |

To get totals with the list, add `includeSummary=true`:

```bash
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'
```

```json
{
  "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` holds the same payments as the array response; it is shortened here.

* `summary` covers every payment that matches the filters. `pageSummary` covers only the returned page, even when it is empty.
* `amountsByCurrency` has one entry per requested currency, in minor units. Never add amounts across currencies.
* `failureRate` is failed payments divided by successful plus failed payments, as a percentage rounded to two decimals. It is `0` when there are neither.

## Aggregated Statistics [#aggregated-statistics]

Get payment statistics aggregated across all merchants in your organization. This endpoint returns total volumes per currency.

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

**Response body:**

An array with one entry per currency your organization has processed payments in.

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

## Read Merchant Payouts [#read-merchant-payouts]

Use this to show a merchant their balance, their payout schedule, and the payouts sent to their bank.

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

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

**Good to know:**

* Returns `404` if the merchant has no processor account yet.
* Money amounts are `{ amount, currency }` in minor units, grouped by currency. `reportedPayouts` and `lastPaidOut`
  are the exception: their `amount` is in major units, as the processor's statement reports it.
* When `balance.isEstimate` is `true`, the balance is Tapaya's estimate, not confirmed by the processor.
* `interval`, `status`, and `method` are numeric enums. See [Merchant Payouts](/financial-guide/merchant-payouts) for
  how payouts work.

**Returns:**

| Field                            | Description                                                                                                                                         |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `balance`                        | `available`, `pending`, `paidOut`, and `instantAvailable` amounts, and `isEstimate`.                                                                |
| `payoutSchedule`                 | `interval` (manual, daily, weekly, or monthly) and `delayDays`.                                                                                     |
| `destination`                    | The payout bank: `bankName` and `bankAccountLast4`.                                                                                                 |
| `recentPayouts`                  | Recent payouts with `amount`, `currency`, `status`, `method` (standard or instant), `created`, `arrivalDate`, and `failureMessage` when one failed. |
| `lastPayout`                     | The latest payout's `amount`, `currency`, and `date`.                                                                                               |
| `totalProcessed`, `totalPaidOut` | Successful payments, and payouts actually sent, per currency.                                                                                       |
| `reportedPayouts`, `lastPaidOut` | Payouts from the processor's statements, with `date`, `amount`, and `reconciliationStatus`.                                                         |
| `latestPostingDate`              | The latest statement date included.                                                                                                                 |

## Retrieve Payment Details [#retrieve-payment-details]

Get full details for a single payment, including its underlying transactions, charges, and any refunds. Scoped to your organization; payments belonging to another organization return `404`.

<Callout title="Payment, transaction, and charge" type="info">
  A **payment** is the purchase request as a whole: one fixed amount for one payment method. It contains one or
  more **transactions**, each representing an attempt to move money through a processor. A transaction contains
  one or more **charges**, each a concrete settlement event against a specific instrument (card, wallet, bank
  account).

  Most payments have exactly one transaction with one charge. A payment can have multiple transactions when a
  card-terminal tap is retried (each tap attempt is paired in as its own transaction). A transaction can have
  multiple charges for asynchronous payment methods like crypto or bank transfer, where the processor reports
  partial or repeated settlement events over time (e.g. an underpaid crypto invoice topped up by a second
  on-chain payment). Refunds reference the payment and charge directly; they are not nested under transactions.
</Callout>

`statusId` (`StatusEnum`) reflects the current state of the payment:

| Value | Name           | Description                                               |
| ----- | -------------- | --------------------------------------------------------- |
| `1`   | `Pending`      | Transaction has been created but not yet finalized.       |
| `2`   | `Success`      | Transaction completed successfully.                       |
| `3`   | `Cancelled`    | Transaction was cancelled before completion.              |
| `4`   | `Refunded`     | Transaction was refunded after completion.                |
| `5`   | `Failed`       | Transaction failed to complete.                           |
| `6`   | `ActionNeeded` | Transaction requires further customer action to complete. |

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

Use the `paymentToken` returned in payment history for both payment details and refunds. The `paymentId` field is the server-generated UUID; it is not the token used in these URLs.

<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/pay_abc123' \
    -H 'Authorization: REPLACE_ME'
    ```
  </CodeBlockTab>
</CodeBlockTabs>

**Responses:**

| Code  | Description                                          |
| ----- | ---------------------------------------------------- |
| `200` | Payment found                                        |
| `404` | Payment not found, or not owned by your organization |

**Response body:**

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

## Refund a Payment [#refund-a-payment]

Refund a payment, in full or in part. Omit `amount` to refund the entire remaining settled amount.

**Endpoint:** `POST /integrator/organization/payment/{paymentToken}/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/pay_abc123/refund' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: REPLACE_ME' \
    -d '{
            "amount": 1999,
            "refundReasonId": 1
        }'
    ```
  </CodeBlockTab>
</CodeBlockTabs>

**Parameters:**

| Field            | Type   | Required | Description                                                                                        |
| ---------------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `amount`         | `long` |          | Amount to refund, in minor currency units. Omit for a full refund of the remaining settled amount. |
| `refundReasonId` | `int`  | ✓        | Reason for the refund (`RefundReasonEnum`).                                                        |

**Responses:**

| Code  | Description                                                                                              |
| ----- | -------------------------------------------------------------------------------------------------------- |
| `200` | Refund initiated                                                                                         |
| `400` | Request validation error                                                                                 |
| `404` | Payment not found, or not owned by your organization                                                     |
| `409` | Payment cannot be refunded in its current state, or the requested amount exceeds what remains refundable |

**Response body:**

```json
{
    "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
}
```

<Callout title="Async settlement" type="info">
  `referralFeeRefund` and `processedAt` are populated asynchronously
  once the processor confirms the refund. They are always `null` in the immediate response; poll
  [Retrieve Payment Details](#retrieve-payment-details) to observe the final state. Payment History returns only
  the latest payments, so an older refunded payment can drop out of it.
</Callout>
