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
}
]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
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”.
Nessun filtro né paginazione
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.
Endpoint: GET /integrator/organization/payment
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": 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
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/{paymentId}
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:
{
"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
Rimborsa un pagamento, totalmente o parzialmente. Ometta amount per rimborsare l'intero importo regolato residuo.
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
}'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": 1,
"settlementAmount": 1999,
"settlementCurrencyId": 1,
"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ù.
Merchant Onboarding API
Creare esercenti e inviarne l'onboarding, oppure invitarli a completarlo, tramite la Tapaya Platform API.
Panoramica
Accetti pagamenti con carta ovunque i Suoi esercenti incontrino i loro clienti, dal bancone del negozio al tavolo del ristorante fino alla colonnina di ricarica per veicoli elettrici, sugli smartphone e sui tablet che già utilizzano.