Best practice
Payment Token
L'utilizzo del payment token si prefigge i seguenti due obiettivi:
definire temporalmente una sessione di pagamento;
avere un identificativo generato dalla piattaforma pagoPA che permetta di identificare end to end una sessione di pagamento.
Il valore di default della durata del payment token è una configurazione comune a livello di intera piattaforma pagoPA e non può essere superiore a 30 minuti, tale parametro può essere sovrascritto dal PSP, con un valore inferiore a 30 minuti, tramite il campo expireTime inserito nella request della activatePaymentNotice, il valore deve essere espresso in millisecondi.
E' fondamentale che ciascun PSP individui il migliore valore di scadenza del token rispetto alla tipologia di canale presso cui l'utente si reca a pagare l'avviso.
Il valore di default della durata del payment token potrà essere ridefinito in base ai risultati del monitoraggio, l'aggiornamento verrà comunicato tramite la pubblicazione di una minor version del presente documento.
Il payment token è fornito in response dalla piattaforma pagoPA ad una activatePaymentNotice, deve essere inserito dal PSP in request alla sendPaymentOutcome e assume il significato di identificativoUnivocoRiscossione nei Flussi di Rendicontazione.
Per una corretta gestione di ogni sessione di pagamento ad ogni activatePaymentNotice deve sempre seguire una sendPaymentOutcome sia nel caso di OK che KO, in modalità real time rispetto alle azioni dell'utente presso il touch point del PSP, questo è fondamentale per gestire una buona qualità del servizio lungo tutta la filiera.
Successivamente alla ricezione di una risposta da parte del Nodo la sendPaymentOutcome non deve essere invocata nuovamente, per sopperire ai casi in cui non si riceva una response è necessario usare la Chiave di idempotenza.
sendPaymentOutcome oltre la scadenza del Payment Token
Solo a fronte di eccezioni tecniche la sendPaymentOutcome non viene ricevuta dalla piattaforma simultaneamente al pagamento e quindi nel caso di invio oltre la scadenza del payment token è possibile ricadere nei casi identificati dalle seguenti risposte fornite dalla piattaforma pagoPA
OK
La notifica di esito del pagamento è avvenuta entro la scadenza del token.
PPT_TOKEN_SCADUTO
La notifica di esito del pagamento è avvenuta oltre la scadenza del token e la piattaforma non conosce pagamenti concorrenti.
PPT_PAGAMENTO_DUPLICATO
La notifica di esito del pagamento è avvenuta oltre la scadenza del token e la piattaforma rileva un altro pagamento sulla medesima posizione.
Per quanto riguarda il caso OK non è necessaria alcuna azione correttiva.
Per quanto riguarda il caso PPT_PAGAMENTO_DUPLICATO l’azione corretta da fare lato PSP sarebbe quella di restituire la somma all’utente. In caso di impossibilità di restituzione della somma è necessario comunque rendicontare il pagamento all'EC con codice 9.
Nel caso di PPT_TOKEN_SCADUTO l'azione correttiva da intraprendere da parte del PSP è quella di gestire il flusso in maniera temporalmente compatibile con la durata del payment token.
Chiave di idempotenza
La chiave di idempotenza può essere generata dal PSP per le chiamate:
Lo scopo della chiave di idempotenza è quello di permettere l’invocazione più volte di una chiamata senza avere side effect sullo stato del pagamento, l'inserimento della chiave di idempotenza nelle request delle chiamate che la gestiscono è obbligatorio, lo scopo di tale strumento è circoscritto ai casi in cui non è stata ricevuta una response, per qualsiasi motivo, ad una chiamata idempotente.
Non deve essere associato per nessun motivo alla chiave di idempotenza il concetto di gestione della sessione di pagamento, che, in realtà, deve avvenire tramite il corretto utilizzo del payment token.
Se un PSP, ad esempio, non riceve la response all'attivazione del pagamento potrà rifare la stessa chiamata, avendo cura di utilizzare la stessa chiave di idempotenza, ottenendo i dati che erano a lui destinati durante la prima chiamata. Qualora non utilizzasse la medesima chiave di idempotenza otterrà invece in response “pagamento in corso” e non potrà procedere con il pagamento.
La regola di generazione della chiave di idempotenza è <CF_PSP> + "_" + <RANDOM STRING>.
La durata della chiave di idempotenza è impostata dalla piattaforma pagoPA, in base ad una configurazione comune a tutti i PSP, nel caso della activatePaymentNotice la durata massima non può essere superiore a quella del payment token.
Nel caso di activatePaymentNotice la chiave di idempotenza deve essere invalidata, oltre ovviamente alla scadenza della chiave stessa, anche nel momento di ricezione di un esito per il payment token generato durante l’attivazione.
La chiave di idempotenza una volta scaduta diventa riutilizzabile.
La piattaforma verifica il corretto utilizzo della chiave di idempotenza, vengono verificati i parametri di input secondo la tabella riportata di seguito.
Associabile ad una richiesta originale
Uguali a richiesta originale
No side effect + risposta originale
Associabile ad una richiesta originale
Diversi da richiesta originale
KO: uso improprio della chiave di idempotenza
Non associabile ad una richiesta originale
Indifferente
Si tratta a tutti gli effetti di una nuova richiesta