DevPortalPagoPA

SoluzioniWebinar
Tabella dei contenuti

Pagamento dovuto

Lo scenario descritto in questo use case è quello di un cittadino che accede al sito di un ente creditore EC per scaricare un documento su cui ha necessità di apporre una Marca da Bollo Digitale MBD.
L’EC potrà indirizzare il cittadino sui sistemi PagoPA per il pagamento della MBD. Inoltre, a valle del processo di pagamento, avrà a disposizione due modalità di recupero della ricevuta della MBD con l’identificativo univoco da associare al documento più tutte le informazioni necessarie per poter eventualmente generare una ricevuta da inviare al cittadino.

Come aderire al servizio

L'adesione al servizio @e.bollo 2.0 Pagamento Dovuto avviene mediante l'apertura di un ticket al team Service Management & Operations SMO dell'area pagoPA, nella richiesta deve essere specificato il codice fiscale dell'EC aderente, il segregation code da utilizzare per la creazione delle posizioni debitorie e il servizio a cui si vuole aderire (nel nostro caso @e.bollo 2.0 Pagamento Dovuto).

Flusso di pagamento MBD

Di seguito il diagramma che riporta il flusso completo del pagamento di una MBD:
An image
Il flusso di pagamento parte dal sito dell'EC nel momento in cui si palesa la necessità di far pagare al cittadino una MBD da associare in modo univoco ad un documento digitale.
A tale scopo @e.bollo 2.0 mette a disposizione dell'EC una API che consente predisporre il pagamento sui sistemi PagoPA e di ricevere una URL a cui indirizzare il cittadino per l'acquisto della MBD, di seguito i dettagli:
POST https://api.platform.pagopa.it/pagopa-mbd-service/v1/organizations/{EC_FISCAL_CODE}/mbd
il body della richiesta è di tipo application/json e deve contenere un document con i campi di seguito riportati:
1{
2    "paymentNotices": [
3        {
4            "firstName": "mario",
5            "lastName": "rossi",
6            "fiscalCode": "MRRNSR75R05H501I",
7            "email": "mario.rossi@mydomain.it",
8            "amount": 1600,
9            "province": "RM",
10            "documentHash": "1trA5qyjSZNwiwtGG46dyjRpL16TFgGCFvnfFzQrFHbB"
11        }
12    ],
13    "idCIService": "00005",
14    "returnUrls": {
15        "successUrl": "https://testok",
16        "cancelUrl": "https://testcancel",
17        "errorUrl": "https://testerror"
18    }
19}
20
Dettaglio dei campi di input:
  • paymentNotices.firstName - nome utente
  • paymentNotices.lastName - cognome utente
  • paymentNotices.fiscalCode - codice fiscale utente
  • paymentNotices.email - email utente
  • paymentNotices.amount - importo MBD
  • paymentNotices.province - provincia di riferimento per l'imposta di bollo
  • paymentNotices.documentHash - hash del documento a cui associare/applicare la MBD
  • idCIService - codice identificativo del servizio @e.bollo 2.0 Pagamento Dovuto da valorizzare con 00005
  • returnUrl.successUrl - url scelta dall'EC su cui effettuare la redirect in caso di pagamento eseguito con successo
  • returnUrl.cancelUrl - url scelta dall'EC su cui effettuare la redirect nel caso in cui l'utente cancelli/annulli l'operazione
  • returnUrl.errorUrl - url scelta dall'EC su cui effettuare la redirect in caso di errore durante la fase di pagamento
Il servizio risponde all'EC con un response body del seguente tipo:
1{
2    "checkoutRedirectUrl": "https://api.uat.platform.pagopa.it/ecommerce/checkout/v1/carts/537d6dff-b087-4ff1-96f6-c759a1ff6c3d/redirect?clientId=CHECKOUT_CART",
3    "mbdDownloadLink": "https://api.uat.platform.pagopa.it/pagopa-mbd-service/v1/organizations/99999000013/receipt/348175498304559315",
4    "nav": "348175498304559315"
5}
6
Dettaglio dei campi in output:
  • checkoutRedirectUrl - URL su cui effettuare la redirect per indirizzare il cittadino sul sito Checkout di pagoPA per il pagamento della MBD, l'utente dovrà confermare l'email e procedere con il pagamento:
An image
  • mbdDownloadLink - link per il recupero dell ricevuta MBD (per i dettagli fare riferimento a Servizio MBD receipt)
  • nav - numero avviso afferente al pagamento della MBD

Recupero ricevuta MBD

La ricevuta della MBD è nel formato xml la cui struttura è definita e consultabile sul sito dell'Agenzia delle Entrate, lo schema xsd può essere scaricato dal repository pagoPA.
Per il recupero della ricevuta sono disponibili due modalità descritte di seguito nel documento.

Servizio MBD receipt

E' disponibile un servizio che consente di recuperare il file xml relativo alla ricevuta della MBD:
GET https://api.platform.pagopa.it/pagopa-mbd-service/v1/organizations/{EC_FISCAL_CODE}/receipt/{NAV}
La URL completa da utilizzare è presente all'interno del campo mbdDownloadLink in risposta al servizio di innesco del pagamento descritto in precedenza, in alternativa per costruire la URL si può utilizzare il campo nav che contiene il numero avviso associato al pagamento.
Il servizio risponde con un response body json del seguente tipo:
1{
2    "content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48bWF..."
3}
4
Il campo content contiene il file xml relativo alla ricevuta MBD codificato in Base64.

Stazione di broadcast

Un metodo alternativo per il recupero della receipt consiste nella configurazione di una stazione di broadcast, se presente il Nodo Dei Pagamenti NDP invocherà la primitiva paSendRTV2 utilizzando l'endpoint configurato nella stazione, l'EC potrà recuperare la ricevuta della MBD dal campo MBDAttachment della receipt.

In questa pagina

Come aderire al servizio

Flusso di pagamento MBD

Recupero ricevuta MBD

Serve aiuto?

Apri un ticket utilizzando l’apposita funzione all’interno della tua Area Riservata

Dicci cosa ne pensi

Per chiarimenti sulle specifiche d’implementazione, come SACI e SANP, puoi aprire una segnalazione su GitHub