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
}
]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.
Retrieve Payment History
Get a list of the latest 50 payments across all merchants in your organization. This is useful for auditing transactions or building a "Super Admin" view.
No filtering or pagination
This endpoint always returns the latest 50 payments org-wide; it does not currently accept query parameters for merchant, status, date range, or pagination. Use the Retrieve Payment Details endpoint to look up a specific payment by ID.
Endpoint: GET /integrator/organization/payment
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": 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"
}
]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
}
]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/{paymentId}
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f' \
-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": 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": []
}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/{paymentId}/refund
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
}'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": 1,
"settlementAmount": 1999,
"settlementCurrencyId": 1,
"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.