LogoLogo
SANPSACITutto il resto
SANP 3.3.0
SANP 3.3.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 sincrone
      • Integrazione tramite API asincrone
      • 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
  • Fase di richiesta di creazione della posizione debitoria
  • Fase di verifica
  • Fase di verifica da parte di Poste Italiane
  • Fase di attivazione
  • Fase di inoltro del pagamento
  • Fase di invio dell'esito del pagamento
  1. Prestatore di Servizi di Pagamento
  2. Modalità di integrazione

Integrazione tramite API

PreviousModalità di integrazioneNextCatalogo Dati Informativi

Last updated 2 years ago

Per la gestione degli errori fare riferimento a

Fase di richiesta di creazione della posizione debitoria

  • 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

  • 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

  • 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

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.

Fase di inoltro del pagamento

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.

  • faultCode PPT_SEMANTICA

  • faultString Errore semantico

  • description Esito discorde

Fase di invio dell'esito del pagamento

  • outcome = OK → posizione debitoria “chiusa”;

  • outcome = KO → posizione debitoria nuovamente “aperta”.

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.

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, se, 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).

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

La è 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:

La è 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:

La è 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:

Con l’ il PSP chiede al nodo di attivare il pagamento presso l’EC.

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 .

I dettagli dei pagamenti eseguiti sui touchpoints di PagoPA S.p.A. vengono inoltrati al PSP tramite la .

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 con outcome OK tale esito verrebbe rifiutato dal nodo.

Se il PSP invia un OK nella response deve inviare un outcome OK nella , nel caso in cui venisse inviato un KO il Nodo risponderà con un faultBean:

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

Il PSP è tenuto a fornire l'esito del pagamento entro 2sec con la , 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:

Per agevolare l’integrazione dei diversi sistemi di incasso la sessione di pagamento ha una durata limitata (), alla scadenza di tale tempo il pagamento si considererà non avvenuto.

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 .

L'invio di una 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.

Dizionario dei metadata
Gestione degli errori
Payment Token
idempotenza
idempotenza
demandPaymentNotice
verifyPaymentNotice
verificaBollettino
activatePaymentNotice
pspNotifyPayment
sendPaymentOutcome
sendPaymentOutcome
pspNotifyPayment vers. 2
sendPaymentOutcome
sendPaymentOutcome