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.
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.
sendPaymentOutcome oltre la scadenza del Payment Token
A fronte di una sendPaymentOutcome è 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_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'utilizzo è sempre opzionale e circoscritto ai casi in cui non è stata ricevuta una response, per qualsiasi motivo, ad una chiamata idempotente.
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.
| 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 |
Last updated