Tapaya

Reporting & Payments

List merchants, retrieve payment history and details, read statistics, and refund payments.

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 registered under this organization.

Endpoint: GET /integrator/merchant

curl -X 'GET' 'https://api.tapaya.com/integrator/merchant' \
-H 'Authorization: REPLACE_ME'

Response body:

[
    {
        "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.

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

curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment' \
-H 'Authorization: REPLACE_ME'

Response body:

[
    {
        "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:

ParameterDescription
fromDateFirst day to include, as YYYY-MM-DD in UTC.
toDateLast day to include, as YYYY-MM-DD in UTC.
pagePage number, starting at 1. Defaults to 1; lower values use page 1.
pageSizeRows per page. Defaults to 50 and is limited to 1 through 100.
merchantIdOrganization payment list only. Restrict results to this merchant.
paymentMethodIdOne numeric payment method.
paymentMethodIdsSeveral payment methods. Repeat the parameter once per method; a payment matches any of them.
statusIdOne payment status. Unsupported values return 400.
includeSummarytrue to return an object with items, summary and pageSummary instead of an array.

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

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'
{
  "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

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

Endpoint: GET /integrator/organization/payment/stats

curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/stats' \
-H 'Authorization: REPLACE_ME'

Response body:

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

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

Read Merchant Payouts

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

curl "https://api.tapaya.com/integrator/merchant/$MERCHANT_ID/payout-state" \
-H 'Authorization: REPLACE_ME'

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 for how payouts work.

Returns:

FieldDescription
balanceavailable, pending, paidOut, and instantAvailable amounts, and isEstimate.
payoutScheduleinterval (manual, daily, weekly, or monthly) and delayDays.
destinationThe payout bank: bankName and bankAccountLast4.
recentPayoutsRecent payouts with amount, currency, status, method (standard or instant), created, arrivalDate, and failureMessage when one failed.
lastPayoutThe latest payout's amount, currency, and date.
totalProcessed, totalPaidOutSuccessful payments, and payouts actually sent, per currency.
reportedPayouts, lastPaidOutPayouts from the processor's statements, with date, amount, and reconciliationStatus.
latestPostingDateThe latest statement date included.

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.

Payment, transaction, and charge

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.

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

ValueNameDescription
1PendingTransaction has been created but not yet finalized.
2SuccessTransaction completed successfully.
3CancelledTransaction was cancelled before completion.
4RefundedTransaction was refunded after completion.
5FailedTransaction failed to complete.
6ActionNeededTransaction 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.

curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/pay_abc123' \
-H 'Authorization: REPLACE_ME'

Responses:

CodeDescription
200Payment found
404Payment not found, or not owned by your organization

Response body:

{
    "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, in full or in part. Omit amount to refund the entire remaining settled amount.

Endpoint: POST /integrator/organization/payment/{paymentToken}/refund

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

Parameters:

FieldTypeRequiredDescription
amountlongAmount to refund, in minor currency units. Omit for a full refund of the remaining settled amount.
refundReasonIdint✓Reason for the refund (RefundReasonEnum).

Responses:

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

Response body:

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

Async settlement

referralFeeRefund and processedAt are populated asynchronously once the processor confirms the refund. They are always null in the immediate response; poll 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.

Missing something on this page?Request a feature. We attach this page so the team sees the context.