Tabella dei contenuti
Integrazione tramite API
Fase di richiesta di creazione della posizione debitoria
La demandPaymentNotice è utilizzabile dai PSP per inviare i dati del servizio specifico inseriti dall'utente, in modo da ricevere in risposta le informazioni necessarie per avviare il processo di pagamento, in particolare:
- il numero avviso;
- il codice fiscale dell'EC da utilizzare nella fase di attivazione;
- l'importo parziale di ogni singolo pagamento;
- il codice fiscale dell’EC beneficiario di ogni singolo pagamento.
Tale fase è obbligatoria nel caso di pagamento spontanei attivati presso i PSP.
I PSP possono recuperare i dati dello specifico servizio tramite il Catalogo dei servizi.
Fase di verifica
La verifyPaymentNotice è utilizzabile dai PSP che avviano il pagamento per mezzo del QR code presente nell'avviso analogico o con l’immissione manuale dei dati, con questa richiesta il PSP richiede le informazioni di pagamento relative ad un numero avviso, in particolare:
- importo parziale;
- codice fiscale dell’EC beneficiario.
La fase di verifica è opzionale per i PSP, se il Nodo riscontra che la posizione è già stata chiusa risponde con un KO per PPT_PAGAMENTO_DUPLICATO.
Fase di verifica da parte di Poste Italiane
.png)
La verificaBollettino è utilizzabile esclusivamente dal PSP Poste Italiane che avvia il pagamento per mezzo del Data Matrix presente nell'avviso analogico, e non per mezzo del QR Code, con questa chiamata vengono richieste le informazioni di pagamento relative ad un numero avviso, in particolare:
- importo parziale;
- codice fiscale dell’EC beneficiario;
- il parametro allCCP indica a Poste Italiane se l’opzione di pagamento è associabile a tutti conti correnti postali o meno
- allCCP = true: l’opzione è associabile a tutti conti correnti postali;
- allCCP = false: l’opzione non è associabile a tutti conti correnti postali.
La fase di verifica è opzionale per i PSP, se il Nodo riscontra che la posizione è già stata chiusa risponde con un KO per PPT_PAGAMENTO_DUPLICATO.
Fase di attivazione
Con l’activatePaymentNotice il PSP chiede al nodo di attivare il pagamento presso l’EC.
Attraverso questa fase il PSP è in grado di aprire una sessione di pagamento, che blocca altri tentativi di pagamento per il medesimo avviso. Attraverso la medesima chiamata, il PSP acquisisce l’importo del pagamento ed i dati necessari per il riversamento della somma, in particolare per ogni versamento:
- importo parziale;
- codice fiscale dell’EC beneficiario;
- IBAN da usare per il riversamento.
La fase di attivazione è obbligatoria per i PSP.
Il Nodo verifica lo stato della posizione:
- se è in corso un'altra sessione di pagamento il Nodo risponde con il faultCode PPT_PAGAMENTO_IN_CORSO;
- se è già stata pagata il Nodo risponde con il faultCode PPT_PAGAMENTO_DUPLICATO.
Il PSP può avviare un processo di retry in caso di mancata ricezione della risposta dal Nodo, a tal proposito si fa presente che per questa chiamata può essere usata una chiave di idempotenza.
Fase di inoltro del pagamento
.png)
I dettagli dei pagamenti eseguiti sui touchpoints di PagoPA S.p.A. vengono inoltrati al PSP tramite la pspNotifyPayment.
In questa fase vengono inviate le informazioni necessarie per poter procedere con invio dell'esito del pagamento e all'eventuale successivo riversamento, in particolare:
- i paymentToken inclusi nella transazione di pagamento;
- gli identificativi della transazione forniti dal PSP in fase di pagamento;
- per ogni versamento:
- importo parziale;
- codice fiscale dell’EC beneficiario;
- IBAN da usare per il riversamento.
Se il PSP invia un KO nella response il processo di pagamento termina e deve essere effettuato uno storno, nel caso il PSP inviasse comunque una sendPaymentOutcome con outcome OK tale esito verrebbe rifiutato dal nodo.
Se il PSP invia un OK nella response deve inviare un outcome OK nella sendPaymentOutcome, nel caso in cui venisse inviato un KO il Nodo risponderà con un faultBean:
- faultCode PPT_SEMANTICA
- faultString Errore semantico
- description Esito discorde
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.
Fase di invio dell'esito del pagamento
Il PSP è tenuto a fornire l'esito del pagamento entro 2sec con la sendPaymentOutcome, sia in caso di pagamento effettuato con successo (outcome = OK), sia in caso di pagamento non effettuato (outcome = KO), l’effetto dell’invio dell’esito del pagamento è quello di “sbloccare” la posizione debitoria sulla piattaforma:
- outcome = OK → posizione debitoria “chiusa”;
- outcome = KO → posizione debitoria nuovamente “aperta”.
Per agevolare l’integrazione dei diversi sistemi di incasso la sessione di pagamento ha una durata limitata (Title text), alla scadenza di tale tempo il pagamento si considererà non avvenuto.
Si osservi che è compito del PSP fare il possibile per notificare alla piattaforma l’esito del pagamento entro la scadenza del token. In particolare si hanno benefici sia per l’utente finale che per l’EC:
- in caso di esito negativo l’utente finale potrà avviare subito una nuova sessione di pagamento;
- in caso di esito positivo si eliminano le possibilità di pagamento doppio.
Il PSP ha quindi l’obbligo, in caso di mancato recapito dell’esito, di avviare un processo di retry, a tal proposito si fa presente che per questa chiamata può essere usata una chiave di idempotenza.
In caso di errori formali o semantici il Nodo risponderà rispettivamente con i faultCode PPT_SINTASSI_EXTRAXSD e PPT_SEMANTICA, indicando nella fault description la motivazione dell'errore, è cura del PSP correggere l'errore e avviare il processo di retry.
Il Nodo potrebbe rispondere con faultCode PPT_SEMANTICA anche per situazioni in cui, per motivi tecnici, lo stato del pagamento sia discorde dall'atteso, in tal caso è cura del PSP avviare il processo di retry.
Una volta ricevuta la chiamata il Nodo verifica se esiste il token ricevuto in request, se non viene trovato il Nodo risponderà con il faultCode PPT_TOKEN_SCONOSCIUTO.
Se non viene usata una chiave di idempotenza ed è già presente un outcome per il pagamento il Nodo risponde con il faultCode PPT_ESITO_GIA_ACQUISITO e nella description del faultBean vengono inseriti i dati precedentemente inviati in formato JSON.
Se la posizione è già stata pagata il Nodo restituisce il faultCode _PPT_PAGAMENTO_DUPLICATO, s_e, invece, non si trova alcun posizione di pagamento attivata il Nodo restituisce il faultCode PPT_PAGAMENTO_SCONOSCIUTO.
Il Nodo verifica lo stato del pagamento per capire se il token sia ancora in corso di validità o meno, nel caso sia scaduto il Nodo risponderà con il faultCode PPT_TOKEN_SCADUTO.
Il PSP dopo avere inviato l'esito per un pagamento non può modificarlo, sia in caso di pagamento effettuato con successo (outcome = OK), sia in caso di pagamento non effettuato (outcome = KO).
L'invio di una sendPaymentOutcome con esito positivo (outcome = OK) è un impegno del PSP a riversare l’importo del pagamento all’EC, al netto dell'eventuali eccezioni con cui può rispondere il Nodo.
Al termine dell’operazione il PSP, in linea con le norme vigenti, consegna un’attestazione di pagamento la quale dovrà contenere (in aggiunta a quanto previsto dalle normative) l’identificativo della sessione di pagamento ottenuto durante le operazioni di pagamento (paymentToken).
Dicci cosa ne pensi
Per chiarimenti sulle specifiche d’implementazione, come SACI e SANP, puoi aprire una segnalazione su GitHub