Best practice

Payment Token

L'utilizzo del payment token si prefigge i seguenti due obiettivi:

1. definire temporalmente una sessione di pagamento;

2. 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

Risposta piattaforma	Significato
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_TOKEN_SCADUTO_KO	La notifica con esito KO del pagamento è avvenuta oltre la scadenza del token, in tal caso il Nodo non verifica lo stato della posizione debitoria.
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 è quella di restituire la somma all’utente.

Per quanto riguarda l'errore di PPT_TOKEN_SCADUTO le azioni da intraprendere da parte del PSP sono diverse a seconda delle casistiche:

• in caso di Pagamento presso frontend dell'EC oPagamento da Touchpoint PagoPA, l'errore indica che il pagamento non è andato a buon fine e l’azione corretta da fare lato PSP è quella di restituire la somma all’utente;

• in caso di Pagamento di un avviso presso PSP, la piattaforma non è in grado di rilevare eventuali pagamenti concorrenti e l’azione corretta da fare lato PSP è quella di rendicontare il pagamento all'EC con codice 9, nel caso il processo di pagamento sia stato gestito in modalità Stand Indeve essere usato il codice 8.

Nel caso di PPT_TOKEN_SCADUTO_KO l'azione correttiva da intraprendere da parte del PSP è quella di gestire il flusso in maniera temporalmente compatibile con la durata del payment token.

sendPaymentOutcome OK

A fronte di un esito OK alla sendPaymentOutcome il PSP è tenuto a specificare i seguenti campi che quindi risultano obbligatori in caso di risposta affermativa:

• paymentMethod: specifica il metodo di pagamento utilizzato;

• fee: indica l'importo della commissione pagata in euro;

• entityUniqueIdentifierType: identifica la tipologia della persona che effettua il pagamento (G o F);

• entityUniqueIdentifierValue: indica il codice fiscale o partita IVA della persona che effettua il pagamento, nel caso non siano disponibili è possibile utilizzare 'ANONIMO';

• fullName: nome completo del pagatore;

• applicationDate: data applicativa del pagamento;

• transferDate: data del riversamento verso l'EC.

Chiave di idempotenza

La chiave di idempotenza può essere generata dal PSP per le chiamate:

• activatePaymentNotice

• sendPaymentOutcome

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, in caso di errore viene restituito il fault code PPT_ERRORE_IDEMPOTENZA, vengono verificati i parametri di input secondo la tabella riportata di seguito.

Chiave di idempotenza	Altri parametri	Azione
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