Versione 3.0 (Work In Progress)

Interventi principali

Generalizzazione dell'identificativo della configurazione del pagamento

Fino a questo momento questa era denominata service_id, e richiamava una relazione 1 a 1 con l'identificativo del servizio sull'area personale. Data la necessità di configurare più pagamenti sullo stesso servizio, è necessario disaccoppiare ulteriormente la configurazione del pagamento dal servizio, introducendo la remote_collection che definisce una relazione 1 a molti tra servizio dell'area personale e configurazione di pagamento sul payment proxy

{
  …
  "remote_collection": {
    "id": "68dada78-2398-4a11-b80a-98aaede3371c",
    "type": "application"
  }
  …
}

Aumento della molteplicità dei versamenti per ogni pagamento da 1 a un massimo di 5.

{
...  
  "payment": {
    "transaction_id": null,
    "paid_at": null,
    "expire_at": "2023-09-04T11:59:05+02:00",
    "total_amount": 16.34,
    "currency": "EUR",
    "items": [
      {
        "type": "PAGOPA",
        "amount": 0.34,
        "reason": "bla",
        "notice_code": "001550000000024427",
        "iud": "68dada7823984a11b80a98aaede3371c",
        "iuv": "550000000024427",
        "receivers": {
          "tax_identification_number": "777777777",
          "name": "Comune di BlaBla",
          "iban": "IT60X0542811101000000123456",
          "address": "Via Del Campo",
          "building_number": "12",
          "postal_code": "38022",
          "town_name": "Roma",
          "country_subdivision": "RM",
          "country": "IT",
        },
        "due_type": "TARI",
        "pagopa_category": "9/12129/TS",
        "document": null,
        "split": []
      },
      {
        "type": "STAMP",
        "amount": 16,
        "reason": "bla",
        "notice_code": "001550000000024427",
        "iud": "68dada7823984a11b80a98aaede3371c",
        "iuv": "550000000024427",
        "receiver": {
          "tax_identification_number": "777777777",
          "name": "Comune di BlaBla",
          "iban": "IT60X0542811101000000123456",
          "address": "Via Del Campo",
          "building_number": "12",
          "postal_code": "38022",
          "town_name": "Roma",
          "country_subdivision": "RM",
          "country": "IT",
        },
        "due_type": "TARI",
        "pagopa_category": "9/12129/TS",
        "document": {
          "id": "123",
          "url": "http://example.com/api/documents/123",
          "sha256": "12398r4o32kjm534om543523489k23jn"
        },
        "split": []
      }
    ]
  }
...
}

Supporto del pagamento multi-beneficiario

{
...
  "receiver": {
    "tax_identification_number": "777777777",
    "name": "Comune di BlaBla",
    "iban": "IT60X0542811101000000123456",
    "address": "Via Del Campo",
    "building_number": "12",
    "postal_code": "38022",
    "town_name": "Roma",
    "country_subdivision": "RM",
    "country": "IT",
  }
...
}

Supporto del versamento della marca da bollo digitale

{
...  
      {
        "type": "STAMP",
        "amount": 16,
        "reason": "bla",
        "notice_code": "001550000000024427",
        "iud": "68dada7823984a11b80a98aaede3371c",
        "iuv": "550000000024427",
        "receiver": {
          "tax_identification_number": "777777777",
          "name": "Comune di BlaBla",
          "iban": "IT60X0542811101000000123456",
          "address": "Via Del Campo",
          "building_number": "12",
          "postal_code": "38022",
          "town_name": "Roma",
          "country_subdivision": "RM",
          "country": "IT",
        },
        "due_type": "TARI",
        "pagopa_category": "9/12129/TS",
        "document": {
          "id": "123",
          "url": "http://example.com/api/documents/123",
          "sha256": "12398r4o32kjm534om543523489k23jn"
        },
        "split": []
      }
...
}

Introduzione campo fault per tracciare eventuali errori dell'intermediario di pagamento

{
...
  "fault": {
    "detail": "string",
    "instance": "string",
    "status": 0,
    "title": "string",
    "type": "string"
  }
...
}

Introduzione dati anagrafici del versante oltre a quelli pagatore

{
...  
  "payer": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "[e-mail]"
  },
  "debtor": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "[e-mail]"
  }
...
}

JSON Evento Pagamento Completo

{
  "id": "4a75de49-0462-4d8f-8f32-b377544faf98",
  "user_id": "f3323b10-db62-4aeb-95de-a87c1f678dad",
  "tenant_id": "60e35f02-1509-408c-b101-3b1a28109329",
  "remote_collection": {
    "id": "68dada78-2398-4a11-b80a-98aaede3371c",
    "type": "application"
  },
  "created_at": "2024-02-19T15:50:23+01:00",
  "updated_at": "2024-02-20T15:05:16+01:00",
  "status": "PAYMENT_PENDING",
  "fault": null,
  "remote_id": "218d7772-a747-4d5f-8c56-bbc7cfeab1a0",
  "payment": {
    "transaction_id": null,
    "paid_at": null,
    "expire_at": "2023-09-04T11:59:05+02:00",
    "total_amount": 17.34,
    "currency": "EUR",
    "items": [
      {
        "type": "PAGOPA",
        "amount": 1,
        "reason": "bla",
        "notice_code": "001550000000024427",
        "iud": "68dada7823984a11b80a98aaede3371c",
        "iuv": "550000000024427",
        "receiver": {
          "tax_identification_number": "777777777",
          "name": "Comune di BlaBla",
          "iban": "IT60X0542811101000000123456",
          "address": "Via Del Campo",
          "building_number": "12",
          "postal_code": "38022",
          "town_name": "Roma",
          "country_subdivision": "RM",
          "country": "IT",
        },
        "due_type": "TARI",
        "pagopa_category": "9/12129/TS",
        "document": null,
        "split": [
          {
            "code": "c_1",
            "amount": 0.5,
            "meta": {}
          },
          {
            "code": "c_2",
            "amount": 0.5,
            "meta": {}
          }
        ]
      },
      {
        "type": "PAGOPA",
        "amount": 0.34,
        "reason": "bla",
        "notice_code": "001550000000024427",
        "iud": "68dada7823984a11b80a98aaede3371c",
        "iuv": "550000000024427",
        "receiver": {
          "tax_identification_number": "777777777",
          "name": "Comune di BlaBla",
          "iban": "IT60X0542811101000000123456",
          "address": "Via Del Campo",
          "building_number": "12",
          "postal_code": "38022",
          "town_name": "Roma",
          "country_subdivision": "RM",
          "country": "IT",
        },
        "due_type": "TARI",
        "pagopa_category": "9/12129/TS",
        "document": null,
        "split": []
      },
      {
        "type": "STAMP",
        "amount": 16,
        "reason": "bla",
        "notice_code": "001550000000024427",
        "iud": "68dada7823984a11b80a98aaede3371c",
        "iuv": "550000000024427",
        "receiver": {
          "tax_identification_number": "777777777",
          "name": "Comune di BlaBla",
          "iban": "IT60X0542811101000000123456",
          "address": "Via Del Campo",
          "building_number": "12",
          "postal_code": "38022",
          "town_name": "Roma",
          "country_subdivision": "RM",
          "country": "IT",
        },
        "due_type": "TARI",
        "pagopa_category": "9/12129/TS",
        "document": {
          "id": "123",
          "url": "http://example.com/api/documents/123",
          "sha256": "12398r4o32kjm534om543523489k23jn"
        },
        "split": []
      }
    ]
  },
  "links": {
    "online_payment_begin": {
      "url": "https://api.qa.stanzadelcittadino.it/payment-proxy/jppa/online-payment/0452545f-40a9-4366-99b6-bbfb2b17b405",
      "last_opened_at": null,
      "method": "GET"
    },
    "online_payment_landing": {
      "url": "https://servizi.comune-qa.bugliano.pi.it/lang/it/pratiche/1a9190cc-25cc-447c-a670-8d828dc0d1ea/detail",
      "last_opened_at": null,
      "method": "GET"
    },
    "offline_payment": {
      "url": "https://api.qa.stanzadelcittadino.it/payment-proxy/jppa/notice/0452545f-40a9-4366-99b6-bbfb2b17b405",
      "last_opened_at": null,
      "method": "GET"
    },
    "receipt": {
      "url": "https://api.qa.stanzadelcittadino.it/payment-proxy/jppa/receipt/0452545f-40a9-4366-99b6-bbfb2b17b405",
      "last_opened_at": null,
      "method": "GET"
    },
    "notify": [
      {
        "url": "https://servizi.comune-qa.bugliano.pi.it/lang/api/applications/1a9190cc-25cc-447c-a670-8d828dc0d1ea/payment",
        "method": "POST",
        "sent_at": null
      }
    ],
    "update": {
      "url": "http://jppa-proxy-qa.boat-backplane.opencontent.io/payment-proxy/jppa/update/0452545f-40a9-4366-99b6-bbfb2b17b405",
      "last_check_at": "2024-02-19T08:37:57.181396519+01:00",
      "next_check_at": "2024-02-19T08:38:57.181404586+01:00",
      "method": "GET"
    }
  },
  "payer": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "[e-mail]"
  },
  "debtor": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "[e-mail]"
  },
  "event_id": "c80a2a33-577a-49a1-b578-0d2267ea5653",
  "event_version": "3.0",
  "event_created_at": "2024-02-20T15:05:16+01:00",
  "app_id": "mypay-payment-proxy:1.8.0"
}

Validazione campi

Payment

Campo	Tipo	Obbligatorio	Validazione
id	UUID
user_id	UUID
tenant_id	UUID
remote_collection	RemoteCollectionType
created_at	Datetime		ISO8601
updated_at	Datetime		ISO8601
status	Enum		Valori permessi: CREATION_PENDING CREATION_FAILED PAYMENT_PENDING PAYMENT_STARTED PAYMENT_CONFIRMED PAYMENT_FAILED NOTIFICATION_PENDING COMPLETE EXPIRED
fault	object		Da valorizzare con l'errore ritornato dal provider nel caso in cui una delle fasi del pagamento fallisca. L'errore dovrà essere descritto secondo l'RFC7807.
remote_id	UUID
payment	PaymentData
links	Links
payer	Payer		Soggetto Versante
debtor	Debtor		Soggetto Pagatore
event_id	UUID
event_version	string(10)		L'attuale versione dell'evento deve essere "3.0". Ogni proxy deve validare la versione dell'evento in modo da sapere se processarlo o meno.
event_created_at	Datetime		ISO8601
app_id	string(100)		Valorizzarlo nel formato <nome-proxy>:<versione-proxy> Es. iris-payment-proxy:1.3.0

RemoteCollectionType

Campo	Tipo	Obbligatorio	Validazione
id	UUID		Identificativo della collection
type	string		tipo di collection (application, service, message ecc.)

Fault

Campo	Tipo	Obbligatorio	Validazione
detail	string		dettaglio dell'errore
instance	string
status	int
title	string		titolo dell'errore
type	string		categoria dell'errore

PaymentData

Campo	Tipo	Obbligatorio	Validazione
transaction_id	string(255)		Fornito dall'intermediario di pagamento. La lunghezza dunque può essere variabile
paid_at	Datetime		ISO8601
expire_at	Datetime		ISO8601 E' già valorizzato a priori, quindi non viene gestito dal proxy
total_amount	float		Importo totale del pagamento
currency	string(3)		ISO4217
items	List[PaymentDataItem]		La lista può avere un massimo di 5 elementi

PaymentDataItem

Campo	Tipo	Obbligatorio	Validazione
type	Enum		Valori permessi: PAGOPA nel caso in cui si tratto di un dovuto standard STAMP nel caso in cui si tratta di un dovuto di tipo marca da bollo digitale
amount	float		Importo del singolo versamento/dovuto. Inserito dal proxy a partire dalla configurazione del pagamento.
reason	string(140)		Causale del pagamento. Non può eccedere i 140 caratteri.
notice_code	string(50)		Numero avviso, generalmente di 18 caratteri di lunghezza
iud	string(50)		Identificativo univoco del dovuto
iuv	string(50)		Identificativo univoco del versamento
receiver	Receiver		Destinatario o beneficiario del versamento/dovuto
due_type	string(256)		Tipo di dovuto secondo la classificazione dell'intermediario di riferiemento
pagopa_category	string(12)		Tipo di dovuto secondo la tassonomia ufficiale di pagoPA
document	Document		Contiene le informazioni riguardanti il documento informatico o la segnatura di protocollo cui è associata la marca da bollo digitale
split	List[PaymentDataSplit]		Bilancio / Contabilità del versamento

Receiver

Campo	Tipo	Obbligatorio	Validazione
tax_identification_number	string(255)
name	string(255)
iban	string(34)		ISO 13616 (obbligatorio solo dal secondo beneficiario in poi)
street_name	string(255)
building_number	string(255)
postal_code	string(255)
town_name	string(255)
country_subdivision	string(2)		ISO 3166-2
country	string(2)		ISO 3166-1 alpha-2

Document

Campo	Tipo	Obbligatorio	Validazione
id	UUID		Identificativo del documento
url	string		Url per scaricare il documento
sha256	string(64)		Hash digest del documento informatico codificato con algoritmo sha256

PaymentDataSplit

Campo	Tipo	Obbligatorio	Validazione
code	string(50)
amount	float
meta	json

Links

Campo	Tipo	Obbligatorio	Validazione
online_payment_begin	UrlData
online_payment_landing	UrlData
offline_payment	UrlData
receipt	UrlData
notify	List[Notify]
update	Update

UrlData

Campo	Tipo	Obbligatorio	Validazione
url	string
last_opened_at	Datetime		ISO8601
method	Enum		Valori permessi: GET POST

Notify

Campo	Tipo	Obbligatorio	Validazione
url	string
method	Enum		Valori permessi: GET POST
sent_at	Datetime		ISO8601

Update

Campo	Tipo	Obbligatorio	Validazione
url	string
last_check_at	Datetime		ISO8601
next_check_at	Datetime		ISO8601
method	Enum		Valori permessi: GET POST

Payer

Campo	Tipo	Obbligatorio	Validazione
type	Enum		Valori permessi: human legal
tax_identification_number	string(255)
name	string(255)
family_name	string(255)
street_name	string(255)
building_number	string(255)
postal_code	string(255)
town_name	string(255)
country_subdivision	string(2)		ISO 3166-2
country	string(2)		ISO 3166-1 alpha-2
email	string(255)

Debtor

Campo	Tipo	Obbligatorio	Validazione
type	Enum		Valori permessi: human legal
tax_identification_number	string(255)
name	string(255)
family_name	string(255)
street_name	string(255)
building_number	string(255)
postal_code	string(255)
town_name	string(255)
country_subdivision	string(2)		ISO 3166-2
country	string(2)		ISO 3166-1 alpha-2
email	string(255)

{
  ...
  "fault": {
    "type": "/errors/provider-error",
    "title": "Il tipo tributo non esiste",
    "status": null,
    "detail": "Il tipo tributo non esiste",
    "instance": "/online-payment/4a75de49-0462-4d8f-8f32-b377544faf98"
  }
  ...
}