Tapaya
PanoramicaPlatform APIReportistica e pagamenti

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:

CampoDescrizione
fromDatePrimo giorno da includere, come YYYY-MM-DD in UTC.
toDateUltimo giorno da includere, come YYYY-MM-DD in UTC.
pageNumero di pagina a partire da 1. Il valore predefinito è 1; valori inferiori utilizzano la pagina 1.
pageSizeRighe per pagina. Il valore predefinito è 50, limitato all'intervallo da 1 a 100.
merchantIdSolo elenco dei pagamenti dell'organizzazione. Limita i risultati a questo esercente.
paymentMethodIdUn metodo di pagamento numerico.
paymentMethodIdsPiù metodi di pagamento. Ripeta il parametro una volta per ciascun metodo; un pagamento corrisponde se ha uno qualsiasi di essi.
statusIdUno stato del pagamento. I valori non supportati restituiscono 400.
includeSummarytrue 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.

  • summary copre tutti i pagamenti che corrispondono ai filtri. pageSummary copre solo la pagina restituita, anche quando è vuota.
  • amountsByCurrency ha 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. È 0 quando 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:

ValoreNomeDescrizione
1PendingLa transazione è stata creata ma non ancora finalizzata.
2SuccessLa transazione è stata completata correttamente.
3CancelledLa transazione è stata annullata prima del completamento.
4RefundedLa transazione è stata rimborsata dopo il completamento.
5FailedNon è stato possibile completare la transazione.
6ActionNeededPer 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:

CodiceDescrizione
200Pagamento trovato
404Pagamento 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:

CampoTipoObbligatorioDescrizione
amountlongImporto da rimborsare, nell'unità minore della valuta. Lo ometta per un rimborso totale dell'importo regolato residuo.
refundReasonIdint✓Motivo del rimborso (RefundReasonEnum).

Risposte:

CodiceDescrizione
200Rimborso avviato
400Errore di convalida della richiesta
404Pagamento non trovato, oppure non appartenente alla Sua organizzazione
409Il 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ù.

Manca qualcosa in questa pagina?Richieda una funzionalità. Alleghiamo questa pagina, così il team vede il contesto.