Come ricevere e gestire una richiesta di cancellazione

Questo tutorial guida il Service Provider del Debitore attraverso i passaggi necessari per gestire correttamente una richiesta di cancellazione (RfC) in entrata. Questa operazione viene avviata da PagoPA quando un avviso di pagamento è stato annullato o pagato tramite altri canali.

Il processo prevede la ricezione di una richiesta, l'aggiornamento dello stato nei sistemi del Service Provider del Debitore e l'invio di una notifica di conferma asincrona.

Il sistema del Service Provider del Debitore deve esporre un endpoint in grado di ricevere le richieste di cancellazione inviate da PagoPA.

POST /sepa-request-to-pay-requests/{sepaRequestToPayRequestResourceId}/cancellation-requests

Quando si riceve una chiamata su questo endpoint, il corpo della richiesta contiene un oggetto SepaRequestToPayCancellationRequestResource, che incapsula un messaggio camt.055.001.08.

Sarà quindi necessario:

1. Identificare la richiesta originale: Si userà il sepaRequestToPayRequestResourceId ricevuto nel path e i dati di correlazione all'interno del messaggio (es. OrgnlEndToEndId) per individuare la richiesta di pagamento da annullare nel tuo sistema.
2. Aggiornare lo stato: occorre modificare lo stato della richiesta nell'applicazione, mostrandola all'utente come "Annullata" o "Già pagata". Questo è un passaggio cruciale per impedire all'utente di tentare un pagamento non più dovuto.
3. Rispondere alla chiamata: Occorre inviare una risposta sincrona con status code 201 Created per confermare la presa in carico della richiesta di cancellazione.

Dopo aver processato la richiesta, occorrerà inviare una conferma asincrona all'URL di callback del mittente (ricevuto nella richiesta di pagamento originale).

• Correlazione: andranno inclusi gli identificativi della richiesta di cancellazione (camt.055) a cui stai rispondendo.
• Stato: si dovrà impostare il campo Sts.Conf su CNCL (Cancelled) e TxCxlSts su ACCR (AcceptedCancellationRequest) per confermare l'esito positivo.

{
  "resourceId": "string",
  "SepaRequestToPayCancellationResponse": {
    "Document": {
      "RsltnOfInvstgtn": {
        "Assgnmt": {
          "Id": "ID_DELLA_RICHIESTA_DI_CANCELLAZIONE",
          "Assgnr": { /* Dati di chi ha assegnato il task */ },
          "Assgne": { /* Dati di chi ha eseguito il task */ },
          "CreDtTm": "2025-07-28T18:00:00.000Z"
        },
        "Sts": {
          "Conf": "CNCL"
        },
        "CxlDtls": {
          "OrgnlPmtInfAndSts": [
            {
              "TxInfAndSts": [
                {
                  "OrgnlEndToEndId": "IUV_DELLA_RICHIESTA_ORIGINALE",
                  "TxCxlSts": "ACCR"
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Questo payload andrà inviato all'endpoint di callback per completare il processo di cancellazione.