# Reportistica e pagamenti (/it/platform-api/reporting) 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 [#list-merchants] Elenca gli esercenti registrati in questa organizzazione. **Endpoint:** `GET /integrator/merchant` cURL ```bash curl -X 'GET' 'https://api.tapaya.com/integrator/merchant' \ -H 'Authorization: REPLACE_ME' ``` **Corpo della risposta:** ```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 } ] ``` 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. ## Recuperare lo storico dei pagamenti [#retrieve-payment-history] Restituisce un elenco degli ultimi 50 pagamenti di tutti gli esercenti della Sua organizzazione. È utile per verificare le transazioni o per creare una vista “Super Admin”. Questo endpoint restituisce sempre gli ultimi 50 pagamenti dell'intera organizzazione; al momento non accetta parametri di query per esercente, stato, intervallo di date o paginazione. Per cercare un pagamento specifico tramite ID, utilizzi l'endpoint [Recuperare i dettagli di un pagamento](#retrieve-payment-details). **Endpoint:** `GET /integrator/organization/payment` cURL ```bash curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment' \ -H 'Authorization: REPLACE_ME' ``` **Corpo della risposta:** ```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": 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" } ] ``` ## Statistiche aggregate [#aggregated-statistics] 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 ```bash 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. ```json [ { "currencyId": 1, "amount": 4582317 } ] ``` ## Recuperare i dettagli di un pagamento [#retrieve-payment-details] 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`. 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/{paymentId}` cURL ```bash curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f' \ -H 'Authorization: REPLACE_ME' ``` **Risposte:** | Codice | Descrizione | | ------ | ---------------------------------------------------------------------- | | `200` | Pagamento trovato | | `404` | Pagamento non trovato, oppure non appartenente alla Sua organizzazione | **Corpo della risposta:** ```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": 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": [] } ``` ## Rimborsare un pagamento [#refund-a-payment] Rimborsa un pagamento, totalmente o parzialmente. Ometta `amount` per rimborsare l'intero importo regolato residuo. **Endpoint:** `POST /integrator/organization/payment/{paymentId}/refund` cURL ```bash 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 }' ``` **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:** ```json { "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 } ``` `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](#retrieve-payment-details) 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ù.