Come effettuare un pagamento presso frontend dell’EC

Nelle SANP 3.2.0 (ottobre 2022) è stato introdotto il processo Pagamento presso frontend dell’EC, che modifica il workflow nel momento in cui l’operazione di pagamento viene avviata dal frontend di un EC. Con l’uscita delle SANP 3.5.0 (luglio 2023) è stata stabilita anche la deadline per l’adeguamento all’utilizzo di questo processo. Deadline che è stata fissata al 31 dicembre 2023.  

Con tale presupposto l’adeguamento al Pagamento presso frontend dell'EC risulta particolarmente semplificato dalla circostanza che non sarà necessario sviluppare e manutenere nuove primitive specifiche.  Dopo l’adeguamento i processi tecnici che implementeranno i due casi d’uso infatti risulteranno coincidenti, giustificando così il fatto l’uso del termine Modello Unico.

⚠ Questo tutorial è destinato agli Enti Creditori (EC) che si sono già adeguati alle SANP in merito al caso d’uso Pagamento di un avviso presso PSP, con l’intento di fornire indicazioni generali sulle attività di adeguamento da pianificare.

⚠ Il processo descritto in questo tutorial si basa sulle funzionalità della componente Checkout fornito dalla piattaforma pagoPA.

⚠ Checkout renderà disponibili all’utente solo i servizi di pagamento effettivamente utilizzabili, che coincideranno con gli attuali entro Q1 2024.

Ogni EC gestisce i processi che prevedono un pagamento in modo specifico, tuttavia e in generale, tali processi devono propedeuticamente prevedere le seguenti due funzionalità (che non verranno approfondite in questo tutorial):

• la creazione di una posizione debitoria;
• la conseguente determinazione di un avviso di pagamento collegato.

Il processo, indicato nelle SANP e successivamente dettagliato qua di seguito, viene attivato nel momento in cui l'operazione di pagamento è avviata dal frontend di un EC, dopo l’esecuzione delle funzionalità propedeutiche specificate, anche in molteplici occorrenze: 

• quando il frontend dell'EC riceve la richiesta di pagamento di uno o più avvisi la inoltra, con una redirect, alla componente Checkout che rappresenta l'interfaccia di frontend della piattaforma PagoPA;
• l’utente, tramite le funzioni di Checkout, seleziona il servizio di pagamento che vuole utilizzare e, il sistema di Checkout in base al numero di avvisi, chiederà al Nodo di attivare i relativi pagamenti;
• ogni singola richiesta di attivazione di pagamento giunge all’EC per mezzo della paGetPayment.

Con questo passaggio i processi di pagamento si vengono ad unificare.

• Checkout, dopo aver gestito le operazioni di pagamento da parte dell'utente, effettua un redirect verso il frontend dell'EC e invia gli esiti al Nodo che provvede ad inviarli al PSP tramite la pspNotifyPayment vers. 2.  

Il processo non può essere completato se il PSP non è in grado di gestire la pspNotifyPayment vers. 2. 

Nel caso di risposta KO da parte del PSP il processo viene interrotto e il pagamento viene stornato.

• a fronte di eccezioni tecniche durante la chiamata alla pspNotifyPayment vers. 2 che impedissero di ricevere una risposta dal PSP, il Nodo attende il verificarsi del primo dei seguenti eventi:
  • scadenza del payment token: il processo viene interrotto e il pagamento viene stornato;
  • ricezione della sendPaymentOutcome vers. 2: il flusso procede normalmente, considerando che il PSP non può inviare un outcome = KO;
• nel caso il PSP inviasse una sendPaymentOutcome vers. 2 dopo aver risposto con un KO alla pspNotifyPayment vers. 2 il Nodo risponderebbe con un KO per segnalare l'esito discorde; in caso di accettazione della pspNotifyPayment vers. 2 il PSP è tenuto a fornire l'esito del pagamento entro i livelli di servizio previsti attraverso la sendPaymentOutcome vers. 2, che contiene un singolo outcome per tutti i tokens attivati nelle fasi precedenti;
• se il PSP inviasse un outcome = KO dopo aver accettato la pspNotifyPayment vers. 2 il Nodo risponderebbe con un KO per segnalare l'esito discorde;
• in caso di esito positivo, tramite la primitiva paSendRT, viene inoltrata a tutti EC interessati al pagamento la receipt (ricevuta) solo se il pagamento è stato effettuato.

 la receipt è un oggetto generato dalla piattaforma pagoPA.

• quando l'EC riceve la receipt deve chiudere la posizione debitoria e considerarla interamente saldata.

⚠ Il workflow presentato consente il pagamento di tutte le posizioni debitorie disponibili tramite i relativi avvisi.

Per l’EC le attività di adeguamento si concentrano nello sviluppo della paGetPaymnet vers. 2, che differisce dalla precedente per un set metadata arricchito. 

Per il PSP le attività di adeguamento si concentrano nello sviluppo della pspNotifyPayment vers. 2, che differisce dalla precedente per un set metadata arricchito. 

Per un corretto e standardizzato utilizzo dei metadata è stato creato un apposito Dizionario dei metadata, in cui è presente una sezione dedicata alle informazioni del canale di pagamento presenti in additionalPaymentInformations della pspNotifyPayment vers. 2. 

⚠ La pspNotifyPayment vers. 2 è totalmente retrocompatibile e quindi può essere utilizzata in tutti i workflow di pagamento, economizzando notevolmente le attività di gestione e manutenzione dei sistemi informativi.

Con l’adeguamento al modello unico potranno essere gestiti tutte le tipologie di avviso previste dalla piattaforma pagoPA. In particolare, sarà possibile poter gestire con un unico avviso anche i casi in cui l’importo pagato debba essere accreditato, in quota parte, su conti di diversi Enti beneficiari (i.e, pagamento multi-beneficiario).

⚠ In caso di pagamento multi-beneficiario, a tutti gli Enti Beneficiari interessati sarà fornito lo stesso set di informazioni e notifiche.

A puro titolo indicativo e non esaustivo si indicano, qui di seguiti, gli avvisi pagabili con il presente processo:

• pagamento mono-beneficiario mono-versamento: avviso il cui importo sia accreditato totalmente su un solo conto dell’Ente beneficiario che gestisce la posizione debitoria;
• ente mono-beneficiario multi-versamento multi-taxonomy: avviso il cui importo sia accreditato su un unico conto dello stesso Ente beneficiario che gestisce la posizione debitoria, suddiviso in molteplici accrediti specificato dalla response della paGetPayment;
• pagamento mono-beneficiario multi-versamento multi-iban: avviso il cui importo sia accreditato, in quota parte, su conti diversi dello stesso Ente beneficiario che gestisce la posizione debitoria;
• caso SUAP mono-beneficiario: avviso il cui importo sia accreditato totalmente su un solo conto dell'Ente beneficiario, diverso dall'Ente che ha creato la posizione debitoria;
• caso SUAP multi-beneficiario: unico avviso il cui importo sia accreditato, in quota parte, su conti di diversi Enti beneficiari, tra cui non figura l'Ente che ha creato la posizione debitoria.

1. Implementare l’ultima versione delle primitive (non inferiore a 3.8.0)
2. In ambiente di Collaudo
   1. Essere connessi su Connettività via Internet
   2. Aver configurato almeno una stazione sull’End-Point modello unico
   3. Aver associato almeno un ente sulla stazione
   4. Eseguire i Test del test case in UAT
   5. Inviare attraverso apertura ticket gli esiti del piano di test eseguito con esito positivo
3. Attendere approvazione da parte di pagoPA
4. In ambiente di Produzione
   1. Essere connessi su Connettività via Internet
   2. Aver configurato la nuova stazione sull’End-Point modello unico 
   3. Aver associato almeno un ente pilota sulla stazione
   4. Inviare attraverso apertura ticket il piano di migrazione
   5. Eseguire un penny test in produzione
   6. Completare la migrazione passando le configurazioni delle altre stazioni al modello unico
   7. Rimuovere la stazione pilota
5. Inviare attraverso apertura ticket “l’avviso di avvenuta migrazione”