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:
| 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. 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:
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.
summarycovers every payment that matches the filters.pageSummarycovers only the returned page, even when it is empty.amountsByCurrencyhas one entry per requested currency, in minor units. Never add amounts across currencies.failureRateis failed payments divided by successful plus failed payments, as a percentage rounded to two decimals. It is0when 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
404if the merchant has no processor account yet. - Money amounts are
{ amount, currency }in minor units, grouped by currency.reportedPayoutsandlastPaidOutare the exception: theiramountis in major units, as the processor's statement reports it. - When
balance.isEstimateistrue, the balance is Tapaya's estimate, not confirmed by the processor. interval,status, andmethodare numeric enums. See 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
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:
| 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.
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/pay_abc123' \
-H 'Authorization: REPLACE_ME'Responses:
| Code | Description |
|---|---|
200 | Payment found |
404 | Payment 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:
| 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:
{
"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.