Tabella dei contenuti
Specifiche Integrazione PSP
In questo paragrafo sono presenti le specifiche delle API e delle redirect che il PSP deve mettere a disposizione della piattaforma pagoPA, che si possono sintetizzare nelle seguenti interfacce:
- API recupero URL: esposta su rete pubblica dal PSP ed invocata dalla piattaforma pagoPA per recuperare la URL che il browser dell’utente utilizzerà per atterrare in modalità redirect, veicolando in anticipo al PSP informazioni sul pagamento che sarà effettuato;
- redirect: pagina web ottimizzata per dispositivi mobile su cui l’utente atterra in redirect, che mette a disposizione le funzionalità di autenticazione e autorizzazione del pagamento. A fronte di qualsiasi esito del pagamento o annullo da parte dell’utente deve mandatoriamente scatenare l’API di callback esito e la redirect verso la piattaforma pagoPA all’urlback indicata nell'Api recupero url con il relativo esito;
- API callback esito transazione: API esposta da pagoPA ed invocata dal PSP a fronte di qualsiasi esito del pagamento o annullo da parte dell’utente per permettere di chiudere in modo corretto l’operazione in corso, che, essendo una redirect attraverso il browser dell’utente, per definizione non è di sicuro recapito;
- API storno: API esposta dal PSP ed invocata da pagoPA per richiedere annullo/storno di un pagamento il cui esito non è mai arrivato alla piattaforma oppure per quei casi residuali dove per problemi tecnici il pagamento non venga finalizzato.
La connettività segue le regole standard della piattaforma pagoPA, consultabili nell'ultima versione delle SANP https://docs.pagopa.it/sanp/appendici/connettivita.
API recupero URL
I parametri che devono essere inoltrati tramite metodo POST alla url di redirect indicata dal PSP:
- idTransaction: identificativo univoco dell’operazione di pagamento
- amount: importo dell’operazione di pagamento
- description (opt): causale del pagamento ricevuta dall’ente creditore
- paName (opt): descrizione dell’ente creditore che ha emesso l’avviso di pagamento
- iban (opt): iban del conto corrente dell’utente da cui attingere per il pagamento
- urlBack : url della piattaforma pagoPA verso la quale il PSP indirizza l'utente al completamento della transazione passando, in GET, i parametri di risposta con il risultato della transazione.
Request
Ciascun PSP deve fornire l'url da invocare tramite il backoffice pagoPA per ciascun ambiente (Test e Produzione).
POST PSP url
1{
2 "idTransaction": string - "15448fefsfsr48sr84fser84sdf",
3 "amount": integer - “12500", comprensivo di fee
4 "description": string - (opz.) "TARI 2023",
5 "paName" - string - (opz.) "Comune di Paperopoli",
6 "iban": string - (opz.) “XX79CXXXXX52770100000000001",
7 "urlBack" - string - "https://checkout.pagopa.it/idTransaction"
8}
9Response
In response il PSP deve fornire una url che sarà usata per indirizzare l’utente sul FE del PSP.
1{
2 "url": string - url/idPSPTransaction - id del PSP
3 "idTransaction": string - "15448fefsfsr48sr84fser84sdf",
4 "amount": integer - “12500"
5}
6Redirect
L’utente, tramite GET all’url fornita dal PSP nella response alla chiamata precedente Api recupero url, viene reindirizzato sul FE del PSP per effettuare l’autorizzazione del pagamento.
Il PSP dovrà utilizzare le informazioni relative al pagamento inviate dalla piattaforma pagoPA nella chiamata precedente Api recupero url.
Request
GET url/idPSPTransaction
Esito
Il workflow del pagamento sarà interessato dai seguenti step in base all'esito del pagamento:
- redirect su pagina pagoPA: l’utente, una volta concluso il pagamento, viene reindirizzato direttamente su pagoPA, all’indirizzo indicato nel parametro urlBack della Api recupero url;
- notifica server to server: viene inviata una notifica POST all'Api callback esito transazione all'indirizzo comunicato in fase di setup da pagoPA. Per confermare l'avvenuta ricezione della notifica il messaggio restituito dalla chiamata deve essere un HTTP 200, altrimenti dovrà esser riproposto con una logica di retry.
API callback esito transazione
Come descritto nel paragrafo precedente è l’API server to server che il PSP in tempo reale deve obbligatoriamente invocare per notificare l’esito del pagamento a pagoPA.
L’API ha il fine di fornire un’esito finale anche nel caso in cui fallisca la redirect dal FE del PSP alla piattaforma pagoPA.
Request
POST apiEsitoPagamento/idTransaction
1{
2 "outcomeGateway": {
3 "paymentGatewayType": "PSP", -- identidicativo del PSP
4 "outcome": "OK", -- esito del pagamento OK/KO
5 "authorizationCode": "string",
6 "errorCode": "payment declined because ...." -- solo per esito negativo
7 },
8 "timestampOperation": "2023-08-21T15:33:21.224Z"
9}
10Possibili valori e codifiche
| Obbligatorio | Nome | Descrizione | Tipo |
|---|---|---|---|
| Y | outcome | Esito dell'operazione (Valori possibili OK, KO, ANNULLO e ERRORE) | string |
| Y | paymentGatewayType | Identificativo del PSP | string |
| Y | authorizationCode | codice univoco di autorizzazione del pagamento rilasciato dal PSP | string |
| N | errorCode | motivo del diniego da valorizzare solo in caso negativo | string |
| Y | timestampOperation | data e ora relativa al pagamento | timestamp |
Response
1{
2 "idTransaction": "string",
3 "outcome": "OK",
4}
5API Storno
Questa API deve essere esposta da tutti i PSP per permettere alla piattaforma pagoPA di poter stornare o annullare un pagamento a fronte di errore tecnico.
La piattaforma pagoPA invoca questa API per richiedere annullo/storno di un pagamento il cui esito non è mai arrivato alla piattaforma oppure per quei casi residuali dove per problemi tecnici il pagamento non è finalizzato.
Ciascun PSP deve fornire l'url da invocare tramite il backoffice pagoPA per ciascun ambiente (Test e Produzione).
Request
1{
2 "idTransaction": string - "15448fefsfsr48sr84fser84sdf",
3 "action": "refund"
4}
5Response
A fronte di una mancata risposta con esito 200 è compito di pagoPA riproporre la medesima chiamata con una logica di retry.
L'API ha la caratteristica di essere idempotente e il PSP deve riproporre lo stesso esito anche nel caso in cui abbia già processato precedentemente la stessa richiesta.
Dicci cosa ne pensi
Per chiarimenti sulle specifiche d’implementazione, come SACI e SANP, puoi aprire una segnalazione su GitHub