Tabella dei contenuti

API Reference - PSP

Versione: 1.3.3
Titolo: PSP Network Testing API - PSP Integration
Contatto: PagoPA S.p.A. - messaggidicortesia@assistenza.pagopa.it

Panoramica

Questa API è dedicata alla verifica della connettività di rete tra il PSP e i sistemi PagoPA nell'ambito del servizio Messaggi di Cortesia. Il suo scopo principale è consentire ai PSP di validare, durante la fase di onboarding e nei collaudi successivi, che l'infrastruttura di rete sia correttamente configurata e che le chiamate verso PagoPA S.p.A. vengano ricevute con successo.

Questa API è utilizzata:

Durante la fase di onboarding del PSP, per verificare la raggiungibilità dell'ambiente target (DEV, UAT, PROD).
Come health check di rete per diagnosticare eventuali problemi di connettività.

Ambienti

Ambiente	URL Base
Development (DEV)	https://api-emd.dev.cstar.pagopa.it/emd/mdc/tpp
User Acceptance Test (UAT)	https://api-emd.uat.cstar.pagopa.it/emd/mdc/tpp
Produzione (PROD)	https://api-emd.cstar.pagopa.it/emd/mdc/tpp

Autenticazione

L'endpoint richiede autenticazione tramite OAuth2 con flusso Client Credentials. Il token JWT (Bearer) deve essere incluso nell'header Authorization di ogni richiesta.

Endpoint

Verifica connessione di rete

GET /network/connection/{tppName}

Verifica che il PSP riesca a raggiungere i sistemi PagoPA S.p.A. In caso di successo, il sistema restituisce un messaggio di conferma che include il nome del PSP passato come parametro.

Parametri di path:

Parametro	Tipo	Obbligatorio	Descrizione
tppName	string	Sì	Nome commerciale o identificativo dell'azienda PSP (1-70 caratteri). Esempio: BancaX

Parametri di header:

Header	Tipo	Obbligatorio	Descrizione
Accept-Language	string	Sì	Lingua della risposta (es. it-IT). Default: it-IT

Risposta di successo (200 OK):

1{
2  "code": "PAGOPA_NETWORK_TEST",
3  "message": "BancaX has reached our systems"
4}
5

Il campo message conterrà il nome del PSP passato nella richiesta, confermando che la connessione è andata a buon fine.

Schemi dei Dati

TppNetworkConnectionResponse

Schema della risposta in caso di connessione verificata con successo.

Campo	Tipo	Obbligatorio	Descrizione
code	string (enum)	Sì	Codice del messaggio. Valore fisso: PAGOPA_NETWORK_TEST
message	string	Sì	Messaggio di conferma, include il nome del PSP. Massimo 250 caratteri

TPPErrorDTO

Schema di risposta in caso di errore.

Campo	Tipo	Obbligatorio	Descrizione
code	string (enum)	Sì	Codice identificativo dell'errore (vedi tabella sotto)
message	string	Sì	Messaggio descrittivo dell'errore. Massimo 250 caratteri

Codici di Errore

In caso di errore, la risposta segue questo formato:

1{
2  "code": "TPP_NOT_ONBOARDED",
3  "message": "Tpp not onboarded"
4}
5

Codice HTTP	Codice Errore	Descrizione
400	TPP_BAD_REQUEST	Richiesta malformata o parametri non validi
401	TPP_AUTHENTICATION_FAILED	Autenticazione fallita o token non valido
404	TPP_NOT_ONBOARDED	Il TPP non è presente o non è stato sottoposto a onboarding
429	TPP_TOO_MANY_REQUESTS	Superato il limite di richieste consentite nel periodo
500	TPP_GENERIC_ERROR	Errore interno del server

Header di Rate Limiting

Ogni risposta include i seguenti header per il controllo del traffico:

Header	Tipo	Descrizione
RateLimit-Limit	integer	Numero massimo di richieste consentite nel periodo corrente (max 240)
RateLimit-Reset	integer	Secondi rimanenti al reset del periodo corrente (max 60)
Retry-After	integer	Secondi da attendere prima di effettuare una nuova richiesta (max 240)
Access-Control-Allow-Origin	string	Indica se la risposta può essere condivisa con l'origine richiedente

Note Operative

Si raccomanda di eseguire questo test su ogni ambiente (DEV, UAT, PROD) prima di procedere con l'integrazione completa, in modo da verificare che le regole firewall, i certificati e le configurazioni di rete siano correttamente predisposte da entrambe le parti.

In questa pagina