LogoLogo
SANPSACITutto il resto
SANP 3.4.0
SANP 3.4.0
  • ⬅️Torna a pagoPA.gov.it
  • Specifiche attuative del nodo dei pagamenti SPC
    • Premessa
    • Changelog
    • Glossario
    • Roadmap
    • Documentazione
    • Funzionamento generale
      • Ruoli
      • Ciclo di vita di un pagamento
      • Processi di pagamento
      • Rendicontazione e Cashflow
      • Overview delle componenti
      • Sicurezza e conservazione
      • L’adesione alla piattaforma pagoPA
      • Utilizzo del marchio pagoPA
    • Erogazione e Livelli di servizio
    • Modello dati
  • Casi d'uso
    • Pagamento di un avviso presso PSP
    • Pagamento spontaneo presso PSP
      • Catalogo dei servizi
      • Bollo auto
    • Pagamento presso frontend dell'EC
    • Pagamento da Touchpoint PagoPA
      • Checkout
      • App IO
  • Ente Creditore
    • Adesione
    • Modalità d'integrazione
      • Integrazione tramite API asincrone
      • Integrazione tramite API sincrone
      • Integrazione touch point dell’EC con Checkout
      • Best practice
    • Generazione dell’Identificativo Univoco di Versamento
    • Tassonomia dei servizi di incasso
    • Tributi multi-beneficiario
    • Attestazione di pagamento
    • Riconciliazione contabile
    • Servizio @e.bollo
    • Stampa avvisi pagoPA
    • Processo di avvio in Esercizio
  • Prestatore di Servizi di Pagamento
    • Adesione
    • Modalità di integrazione
      • Integrazione tramite API
      • Catalogo Dati Informativi
      • Offrire sistemi di pagamento su touch point di PagoPA S.p.A.
      • Gestione strumenti di pagamento
      • Best practice
    • Commissioni
    • Attestazione di pagamento
    • Processo di avvio in Esercizio
  • Esperienza per il Cittadino
    • App IO
      • Carte
      • PayPal
    • Checkout
  • Appendici
    • Connettività
    • Indicatori di qualità per i soggetti aderenti
      • Livelli di Servizio Enti Creditori
      • Livelli di Servizio PSP
    • Giornale degli eventi
    • Generazione e stampa degli avvisi
    • Gestione evoluta commissioni
    • Primitive
    • Funzionalità deprecate
    • Adesione ai servizi con subscription key
    • Posizioni Debitorie
      • Modello Dati
      • Stati della posizione debitoria
      • Operazioni disponibili
    • POS Fisici
  • FAQ
    • Ente Creditore
    • PSP
    • Intermediario tecnologico
Powered by GitBook
On this page
  • Payment Token
  • sendPaymentOutcome oltre la scadenza del Payment Token
  • Chiave di idempotenza
  1. Prestatore di Servizi di Pagamento
  2. Modalità di integrazione

Best practice

PreviousGestione strumenti di pagamentoNextCommissioni

Last updated 2 years ago

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 , 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 , deve essere inserito dal PSP in request alla e assume il significato di identificativoUnivocoRiscossione nei Flussi di Rendicontazione.

Per una corretta gestione di ogni sessione di pagamento ad ogni deve sempre seguire una 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 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 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_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 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

La durata della chiave di idempotenza è impostata dalla piattaforma pagoPA, in base ad una configurazione comune a tutti i PSP, nel caso della la durata massima non può essere superiore a quella del payment token.

Nel caso di 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.

activatePaymentNotice
activatePaymentNotice
sendPaymentOutcome
activatePaymentNotice
sendPaymentOutcome
sendPaymentOutcome
sendPaymentOutcome
activatePaymentNotice
sendPaymentOutcome
activatePaymentNotice
activatePaymentNotice