Reportistica e pagamenti
Elencare gli esercenti, recuperare lo storico e i dettagli dei pagamenti, consultare le statistiche e rimborsare i pagamenti.
Questi endpoint forniscono accesso programmatico a dati e impostazioni disponibili anche nella dashboard della Tapaya Platform. Può utilizzarli per creare dashboard personalizzate, automatizzare i processi o recuperare dati di reportistica, sia che incorpori l'Accept SDK sia che controlli direttamente l'app Tapaya Terminal. L'autenticazione avviene allo stesso modo, con il Suo Server Secret Token.
Elencare gli esercenti
Elenca gli esercenti registrati in questa organizzazione.
Endpoint: GET /integrator/merchant
curl -X 'GET' 'https://api.tapaya.com/integrator/merchant' \
-H 'Authorization: REPLACE_ME'Corpo della risposta:
[
{
"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"
}
]Il campo email è l'email dell'amministratore / di contatto attualmente memorizzata nel record dell'esercente. È il valore che può
utilizzare per riconciliare i record degli esercenti nel Suo back office senza dover recuperare ogni esercente singolarmente.
commissionProfileIds elenca i profili di commissione assegnati all'esercente. Per membri, terminali, bozze di onboarding e tariffe, si veda Gestione degli esercenti.
Recuperare lo storico dei pagamenti
Elenca i pagamenti di tutti gli esercenti della Sua organizzazione, dal più recente. Senza parametri di query, ottiene gli ultimi 50.
Endpoint: GET /integrator/organization/payment, oppure GET /integrator/merchant/{merchantId}/payment per un singolo esercente
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment' \
-H 'Authorization: REPLACE_ME'Corpo della risposta:
[
{
"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"
}
]Parametri:
| Campo | Descrizione |
|---|---|
fromDate | Primo giorno da includere, come YYYY-MM-DD in UTC. |
toDate | Ultimo giorno da includere, come YYYY-MM-DD in UTC. |
page | Numero di pagina a partire da 1. Il valore predefinito è 1; valori inferiori utilizzano la pagina 1. |
pageSize | Righe per pagina. Il valore predefinito è 50, limitato all'intervallo da 1 a 100. |
merchantId | Solo elenco dei pagamenti dell'organizzazione. Limita i risultati a questo esercente. |
paymentMethodId | Un metodo di pagamento numerico. |
paymentMethodIds | Più metodi di pagamento. Ripeta il parametro una volta per ciascun metodo; un pagamento corrisponde se ha uno qualsiasi di essi. |
statusId | Uno stato del pagamento. I valori non supportati restituiscono 400. |
includeSummary | true per restituire un oggetto con items, summary e pageSummary invece di un array. |
Per ottenere i totali insieme all'elenco, aggiunga 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 contiene gli stessi pagamenti della risposta come array; qui è abbreviato.
summarycopre tutti i pagamenti che corrispondono ai filtri.pageSummarycopre solo la pagina restituita, anche quando è vuota.amountsByCurrencyha una voce per ciascuna valuta richiesta, in unità minori. Non sommi mai importi di valute diverse.failureRateè il numero di pagamenti falliti diviso per la somma dei pagamenti riusciti e falliti, espresso in percentuale e arrotondato a due decimali. È0quando non ce ne sono né degli uni né degli altri.
Statistiche aggregate
Restituisce le statistiche dei pagamenti aggregate per tutti gli esercenti della Sua organizzazione. Questo endpoint restituisce i volumi totali per valuta.
Endpoint: GET /integrator/organization/payment/stats
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/stats' \
-H 'Authorization: REPLACE_ME'Corpo della risposta:
Un array con una voce per ciascuna valuta in cui la Sua organizzazione ha elaborato pagamenti.
[
{
"currencyId": 1,
"amount": 4582317
}
]Recuperare i dettagli di un pagamento
Restituisce i dettagli completi di un singolo pagamento, incluse le transazioni sottostanti, gli addebiti (charge) e gli eventuali rimborsi. L'ambito è limitato alla Sua organizzazione; i pagamenti che appartengono a un'altra organizzazione restituiscono 404.
Pagamento, transazione e addebito
Un pagamento è la richiesta di acquisto nel suo insieme: un importo fisso per un metodo di pagamento. Contiene una o più transazioni, ciascuna delle quali rappresenta un tentativo di trasferire denaro tramite un processore. Una transazione contiene uno o più addebiti (charge), ciascuno dei quali è un evento di regolamento concreto su uno specifico strumento (carta, wallet, conto bancario).
La maggior parte dei pagamenti ha esattamente una transazione con un addebito. Un pagamento può avere più transazioni quando l'avvicinamento della carta al terminale viene ripetuto (ogni tentativo di avvicinamento viene associato come transazione a sé). Una transazione può avere più addebiti per i metodi di pagamento asincroni come le criptovalute o il bonifico bancario, in cui il processore segnala nel tempo eventi di regolamento parziali o ripetuti (ad es. una fattura in criptovaluta pagata in difetto e integrata da un secondo pagamento on-chain). I rimborsi fanno riferimento direttamente al pagamento e all'addebito; non sono annidati sotto le transazioni.
statusId (StatusEnum) riflette lo stato attuale del pagamento:
| Valore | Nome | Descrizione |
|---|---|---|
1 | Pending | La transazione è stata creata ma non ancora finalizzata. |
2 | Success | La transazione è stata completata correttamente. |
3 | Cancelled | La transazione è stata annullata prima del completamento. |
4 | Refunded | La transazione è stata rimborsata dopo il completamento. |
5 | Failed | Non è stato possibile completare la transazione. |
6 | ActionNeeded | Per essere completata, la transazione richiede un'ulteriore azione del cliente. |
Endpoint: GET /integrator/organization/payment/{paymentToken}
Per i dettagli del pagamento e i rimborsi, utilizzi il paymentToken restituito nella cronologia dei pagamenti. Il campo paymentId è lo UUID generato dal server; non è il token utilizzato in questi URL.
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/pay_abc123' \
-H 'Authorization: REPLACE_ME'Risposte:
| Codice | Descrizione |
|---|---|
200 | Pagamento trovato |
404 | Pagamento non trovato, oppure non appartenente alla Sua organizzazione |
Corpo della risposta:
{
"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": []
}Rimborsare un pagamento
Rimborsa un pagamento, totalmente o parzialmente. Ometta amount per rimborsare l'intero importo regolato residuo.
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
}'Parametri:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
amount | long | Importo da rimborsare, nell'unità minore della valuta. Lo ometta per un rimborso totale dell'importo regolato residuo. | |
refundReasonId | int | ✓ | Motivo del rimborso (RefundReasonEnum). |
Risposte:
| Codice | Descrizione |
|---|---|
200 | Rimborso avviato |
400 | Errore di convalida della richiesta |
404 | Pagamento non trovato, oppure non appartenente alla Sua organizzazione |
409 | Il pagamento non può essere rimborsato nel suo stato attuale, oppure l'importo richiesto supera l'importo ancora rimborsabile |
Corpo della risposta:
{
"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
}Regolamento asincrono
referralFeeRefund e processedAt vengono valorizzati in modo asincrono
dopo che il processore ha confermato il rimborso. Nella risposta immediata sono sempre null; interroghi periodicamente
Recuperare i dettagli di un pagamento per conoscere lo stato finale. Lo storico dei pagamenti restituisce solo
i pagamenti più recenti, quindi un pagamento rimborsato meno recente può non comparirvi più.