LogoLogo
SANPSACITutto il resto
SANP 3.8.0
SANP 3.8.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
      • Stand In
    • 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 touchpoints di PagoPA S.p.A.
      • Integrazione standard per gli strumenti di pagamento
      • Integrazione per strumento di pagamento PayPal
      • Integrazione per strumento di pagamento tramite Redirect
      • Best practice
    • Commissioni
    • Attestazione di pagamento
    • Processo di avvio in Esercizio
    • Quality Improvement
  • 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
    • Posizioni Debitorie
      • Modello Dati
      • Stati della posizione debitoria
      • Pagamenti presso frontend dell'EC in modalità asincrona
      • Gestione Massiva
        • 📄Specifiche tracciato di input
        • ⚙️Gestione massiva tramite API REST
        • 📥Gestione massiva tramite SFTP
      • Operazioni disponibili
    • POS Fisici
  • FAQ
    • Ente Creditore
    • PSP
    • Intermediario tecnologico
Powered by GitBook
On this page
  1. Prestatore di Servizi di Pagamento
  2. Modalità di integrazione

Integrazione per strumento di pagamento tramite Redirect

PreviousIntegrazione per strumento di pagamento PayPalNextBest practice

La modalità di pagamento in redirect verso soluzioni fornite dai singoli PSP o terze parti da loro convenzionate, introdotta per facilitare i pagamenti su conto corrente e similari per i cittadini ed imprese, è studiata secondo le seguenti stelle polari:

  • principio di neutralità: la piattaforma pagoPA deve mettere a disposizione di tutti i PSP le medesime interfacce ed integrazioni tecnologiche senza alcuna customizzazione; é chiesto quindi a tutti i PSP che oggi hanno soluzioni custom di adeguarsi alla nuova modalità, unica disponibile per il modello unico di pagamento obbligatorio sulla piattaforma pagoPA;

  • compliance PSD2: come oggi resta responsabilità del PSP, che mette a disposizione lo strumento di pagamento (direttamente o per il tramite di terzi), garantire il rispetto della normativa vigente in termini di sicurezza, autenticazione (SCA) e best practice bancarie;

  • regole chiare descritte nelle SANP: è scelta della società PagoPA S.p.A. declinare quali modalità di pagamento permettere di veicolare dentro la modalità di redirect, secondo principi che devono essere chiari e descritti nelle SANP.

NB: le modalità di pagamento, anche se per pagamenti su conto corrente (es: mybank, BancomatPay, ...), nativamente integrate con il payment gateway di pagoPA, non possono essere integrate in modalità redirect.

Precondizione del PSP per abilitare tutti gli strumenti di pagamento disponibili, fra cui la redirect, è l’integrazione al Nodo dei Pagamenti secondo le specifiche del modello unico e la valorizzazione del catalogo dati informativo per il tramite del backoffice pagoPA fruibile dall’area riservata.

Il PSP deve mettere a disposizione della piattaforma pagoPA le seguenti interfacce:

  • : esposta su rete pubblica dal PSP ed invocata dalla piattaforma pagoPA per recuperare la URL che il browser dell’utente utilizzerà per atterrare in modalità redirect, veicolando in anticipo al PSP informazioni sul pagamento che sarà effettuato;

  • : pagina web ottimizzata per dispositivi mobile su cui l’utente atterra in redirect, che mette a disposizione le funzionalità di autenticazione e autorizzazione del pagamento. A fronte di qualsiasi esito del pagamento o annullo da parte dell’utente deve mandatoriamente scatenare l’API di callback esito e la redirect verso la piattaforma pagoPA all’urlback indicata nell'API recupero URL con il relativo esito;

  • : API esposta da pagoPA ed invocata dal PSP a fronte di qualsiasi esito del pagamento o annullo da parte dell’utente per permettere di chiudere in modo corretto l’operazione in corso, che, essendo una redirect attraverso il browser dell’utente, per definizione non è di sicuro recapito;

  • : API esposta dal PSP ed invocata da pagoPA per richiedere annullo di un pagamento il cui esito non è mai arrivato alla piattaforma oppure per quei casi residuali dove per problemi tecnici il pagamento non venga finalizzato.

La connettività segue le regole standard della piattaforma pagoPA, consultabili da Connettività.

I campi contrassegnati con﹡sono obbligatori

API recupero URL

Redirect

L’utente, tramite GET all’url fornita dal PSP nella response alla chiamataAPI recupero URL, viene reindirizzato dalla piattaforma pagoPA sul FE del PSP per effettuare l’autorizzazione del pagamento.

Il PSP, per la corretta gestione, dovrà utilizzare le informazioni relative al pagamento inviate dalla piattaforma pagoPA nella chiamataAPI recupero URL.

Esito

Il workflow del pagamento sarà interessato dai seguenti step in base all'esito del pagamento:

  • redirect su pagina pagoPA: l’utente, una volta concluso il pagamento, viene reindirizzato direttamente su pagoPA, all’indirizzo indicato nel parametro urlBack dellaAPI recupero URL;

API callback esito transazione

Come descritto nel paragrafo precedente è l’API server to server che il PSP, in tempo reale, deve obbligatoriamente invocare per notificare l’esito del pagamento a pagoPA.

L’API ha il fine di fornire un’esito finale anche nel caso in cui fallisca la redirect dal FE del PSP alla piattaforma pagoPA.

API annullo

Questa API deve essere esposta da tutti i PSP per permettere alla piattaforma pagoPA di poter annullare un pagamento a fronte di errore tecnico.

La piattaforma pagoPA invoca questa API per richiedere l’annullo di un pagamento nei seguenti casi:

  1. l’esito (positivo o negativo) non è mai arrivato alla piattaforma pagoPA e, per effetto, neanche all’EC;

  2. per problemi tecnici, dopo che la piattaforma pagoPA ha ricevuto l’esito positivo da parte del PSP, il colloquio telematico tra la piattaforma pagoPA e il PSP non è stato possibile ovvero ha determinato una discordanza con il PSP e a fronte di tale mancato colloquio o discordanza, il PSP non ha acquisito i dati necessari per l’accredito nei confronti degli EC interessati dall’operazione.

Nel caso di cui al punto 1, l’annullo consente di rendere di nuovo disponibile il pagamento dello/degli IUV oggetto dell’annullo.

Nel caso di cui al punto 2, in aggiunta all'effetto di cui sopra, la piattaforma pagoPA annulla l’esito positivo ricevuto dal PSP.

Ciascun PSP deve fornire l'url da invocare tramite il backoffice pagoPA per ciascun ambiente (collaudo e produzione).

A fronte di una mancata risposta con esito HTTP 200 (avente valore di esito positivo della risposta alla chiamata) è compito di pagoPA riproporre la medesima chiamata con una logica di retry.

L'API ha la caratteristica di essere idempotente e il PSP deve riproporre lo stesso esito anche nel caso in cui abbia già processato precedentemente la stessa richiesta.

Fase di pagamento

Fase di annullo

Caso 1 - Mancata ricezione dell’esito del pagamento

La piattaforma pagoPA effettua la chiamata di annullo con logica di retry se non riceve l’esito (positivo o negativo) del pagamento entro il timeout indicato nella response alla API recupero URL dal PSP o il timeout di default di 10 minuti dall'invocazione della redirect verso l'URL del PSP.

Caso 2 - pspNotifyPayment KO

notifica server to server: viene inviata una notifica POST all'API callback esito transazione all'indirizzo comunicato in fase di setup da PagoPA S.p.A.; per ottenere la conferma dell'avvenuta ricezione della notifica il messaggio restituito dalla chiamata deve essere un HTTP 200, altrimenti dovrà esser riproposto con una logica di retry ().

Si precisa nuovamente che autorizzazione e contabilizzazione devono essere gestite contemporaneamente nella stessa fase, come indicato nel workflow in

La piattaforma pagoPA effettua la chiamata di annullo con logica di retry quando il PSP ha risposto KO alla .

API recupero URL
redirect
API callback esito transazione
API annullo

Retrieve redirect URL

post

Retrieve redirect URL to be followed to perform transaction payment

Body

Redirect URL request

idTransactionstring · min: 32 · max: 32Required

Uniquely identify a transaction

Example: 3fa85f6457174562b3fc2c963f66afa6
idPspstringRequired

PSP identifier

amountinteger · int32 · max: 99999999Required

Amount for payments including fee, in euro cents

urlBackstring · uriRequired

pagoPA platform URL where redirect users after payment transaction have been completed

descriptionstringRequired

Payment description

idPaymentMethodstringRequired

Redirect payment method type

touchpointstring · enumRequired

Touchpoint used to initiate the transaction

Possible values:
paNamestring · min: 1 · max: 70Optional

Name of the payment notice issuer

paymentMethodstringOptional

Description of the payment method chosen by the user

emailstringOptional

Email to which send the pagoPA payment receipt

Responses
200
Redirect url response
application/json
400
Formally invalid input
application/json
401
Unauthorized
application/json
500
Internal server error
application/json
post
POST /redirections HTTP/1.1
Host: ${host}
Content-Type: application/json
Accept: */*
Content-Length: 275

{
  "idTransaction": "3fa85f6457174562b3fc2c963f66afa6",
  "idPsp": "idPsp",
  "amount": 99999999,
  "urlBack": "https://psp.site/payment",
  "description": "payment description",
  "idPaymentMethod": "RBPR",
  "touchpoint": "CHECKOUT",
  "paName": "paName",
  "paymentMethod": "Poste addebito in conto Retail"
}
{
  "url": "text",
  "idTransaction": "3fa85f6457174562b3fc2c963f66afa6",
  "idPSPTransaction": "text",
  "amount": 1,
  "timeout": 1
}
  • API recupero URL
  • POSTRetrieve redirect URL
  • Redirect
  • Esito
  • API callback esito transazione
  • POSTCallback API for communicate authorization outcome
  • API annullo
  • POSTApi for refund
  • Fase di pagamento
  • Fase di annullo
  • Caso 1 - Mancata ricezione dell’esito del pagamento
  • Caso 2 - pspNotifyPayment KO

Callback API for communicate authorization outcome

post

Communicate the outcome for the authorization process

Authorizations
Path parameters
idTransactionstring · min: 32 · max: 32Required

Uniquely identify a transaction

Example: 3fa85f6457174562b3fc2c963f66afa6
Body

Callback api transaction outcome request body

idPspstringRequired

PSP identifier as received in redirections url request

idPSPTransactionstringRequired

Unique PSP transaction identifier

outcomestring · enumRequired

Transaction outcome enumeration. The outcome can assume the following values:

  • OK -> Authorization completed successfully
  • KO -> Authorization KO (for example missing funds for transaction)
  • CANCELED -> User canceled the authorization process
  • EXPIRED -> Authorization process has not been completed before timeout set for the operation
  • ERROR -> An unexpected error occurred during authorization process
Possible values:
detailsone ofOptional
or
Responses
200
Outcome response
application/json
400
Formally invalid input
application/json
401
Unauthorized
application/json
404
Not found
application/json
500
Internal server error
application/json
post
POST /redirections/{idTransaction}/outcomes HTTP/1.1
Host: ${host}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 170

{
  "idPsp": "idPsp",
  "idPSPTransaction": "idPSPTransaction",
  "outcome": "OK",
  "details": {
    "timestampOperation": "2024-01-12T11:59:40.873Z",
    "authorizationCode": "authorizationCode"
  }
}
{
  "idTransaction": "3fa85f6457174562b3fc2c963f66afa6",
  "outcome": "OK"
}

Api for refund

post

Perform a refund for a transaction. Semantically this endpoint is a DELETE with body (HTTP requests with the DELETE method should not have a body as per RFC 9110, section 9.3.5, paragraph 5).

Body
idTransactionstring · min: 32 · max: 32Required

Uniquely identify a transaction

Example: 3fa85f6457174562b3fc2c963f66afa6
idPSPTransactionstringRequired

PSP transaction id

actionstringRequired

Requested action (i.e. refund)

Responses
200
Successful refund response
application/json
400
Formally invalid input
application/json
401
Unauthorized
application/json
404
Not found
application/json
500
Internal server error
application/json
post
POST /redirections/refunds HTTP/1.1
Host: ${host}
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "idTransaction": "3fa85f6457174562b3fc2c963f66afa6",
  "idPSPTransaction": "idPSPTransaction",
  "action": "refund"
}
{
  "idTransaction": "3fa85f6457174562b3fc2c963f66afa6",
  "outcome": "OK"
}
Processi di retry
Integrazione e workflow per PSP/Strumento di Pagamento integrato con Payment Gateway
pspNotifyPayment