1 of 1

Implementazione di un proxy

Molti aspetti implementativi dipendono più dalla normativa che da nostre scelte progettuali, in questa pagina si evidenziano gli uni e le altre.

Requisiti funzionali

Sono requisiti che dipendono da nostre scelte implementative, possono cambiare man mano che evolviamo la piattaforma, per supportare nuovi casi d'uso (pagamento dei dovuti) oppure perché ci accorgiamo che abbiamo commesso qualche errore nella progettazione.

Gestione di pagamenti spontanei
Gestione di pagamenti con bilancio
Gestione della notifica dello stato del pagamento da parte dell'IdP - se disponibile - o del polling se non è disponibile la notifica
Se è implementato il polling, questo deve avvenire con un back-off esponenziale che assicuri alcuni check nel giro di pochi minuti e poi si diradi fino a un massimo di un check al giorno fino alla scadenza del pagamento o 1 anno se la scadenza è inferiore.
Gestione delle configurazioni a livello di Tenant e di Servizio

Requisiti normativi

Avere una specifica in formato OpenAPI v3
Rispettare la Linee Guida di interoperabilità: in particolare per quanto riguarda
- il formato dei dati (4.2)
- raccomandazioni sul naming (4.3) optando per la scelta di snake_case per i nomi degli attributi
- logging (4.4)
- risultare valido nel validatore ufficiale OA3

Requisiti per l'ambiente di produzione

Sappiamo che in molti topic ci sono diversi eventi mal formati, per vari errori e assenza di uno schema registry, quindi è necessario validare gli eventi in input e opzionalmente in output (lo fanno le nostre prime implementazioni in python, ma è un requisito?)
Ci aspettiamo che se di dovesse aggiornare il formato dell'evento nel topic payments gestiremo eventi anche in parallelo con versioni distinte, quindi ogni proxy deve Interpretare solo gli eventi che riportano il formato più recente dell'evento nel topic payments: event_version: 2.0
Integrarsi con sentry per la gestione degli errori
Esporre metriche di monitoraggio in formato prometheus, in particolare:
- counter sul numero di pagamenti creati
- counter sul numero di errori durante il processamento di pagamenti, differenziando gli errori interni (errori di formato dati in ingresso o validazione) da errori esterni (errori di dialogo con l'IdP)
- latenza delle chiamate fatte all'IdP
Di seguito la tabella contenente le specifiche di ogni metrica

Inoltre il servizio deve rispettare gli standard della piattaforma in particolare per quanto riguarda la gestione dello storage: non possiamo avere vendor-lockin sulle tecnologie, quindi dobbiamo essere compatibili con file-system posix tradizionale, NFS share e almeno i due cloud-storage più diffusi S3 e Azure Blob.

Documentazione API di Esempio - Swagger

Esempi di proxy da cui si può prendere spunto

EFIL: http://gitlab.com/opencontent/stanza-del-cittadino/efil-payment-proxy

IRIS: http://gitlab.com/opencontent/stanza-del-cittadino/iris-payment-proxy

MYPAY: http://gitlab.com/opencontent/stanza-del-cittadino/mypay-payment-proxy

PMPAY: http://gitlab.com/opencontent/stanza-del-cittadino/pmpay-payment-proxy

Questi proxy condividono alcune scelte implementative grazie a un apposito python-sdk sviluppato in parallelo ai proxy stessi:

le configurazioni sono salvate su disco locale o s3 secondo un albero ben definito tenant->servizio
i singoli pagamenti vengono salvati su storage fino a che il pagamento è pendente, così da poter fare il polling in autonomia.

Altri riferimenti utili

Implementazione di un proxy

Molti aspetti implementativi dipendono più dalla normativa che da nostre scelte progettuali, in questa pagina si evidenziano gli uni e le altre.

Requisiti funzionali

Gestione di pagamenti spontanei
Gestione di pagamenti con bilancio
Gestione della notifica dello stato del pagamento da parte dell'IdP - se disponibile - o del polling se non è disponibile la notifica
Se è implementato il polling, questo deve avvenire con un back-off esponenziale che assicuri alcuni check nel giro di pochi minuti e poi si diradi fino a un massimo di un check al giorno fino alla scadenza del pagamento o 1 anno se la scadenza è inferiore.
Gestione delle configurazioni a livello di Tenant e di Servizio

Requisiti normativi

Avere una specifica in formato OpenAPI v3
Rispettare la Linee Guida di interoperabilità: in particolare per quanto riguarda
- il formato dei dati (4.2)
- raccomandazioni sul naming (4.3) optando per la scelta di snake_case per i nomi degli attributi
- logging (4.4)
- risultare valido nel validatore ufficiale OA3

Requisiti per l'ambiente di produzione

Sappiamo che in molti topic ci sono diversi eventi mal formati, per vari errori e assenza di uno schema registry, quindi è necessario validare gli eventi in input e opzionalmente in output (lo fanno le nostre prime implementazioni in python, ma è un requisito?)
Ci aspettiamo che se di dovesse aggiornare il formato dell'evento nel topic payments gestiremo eventi anche in parallelo con versioni distinte, quindi ogni proxy deve Interpretare solo gli eventi che riportano il formato più recente dell'evento nel topic payments: event_version: 2.0
Integrarsi con sentry per la gestione degli errori
Esporre metriche di monitoraggio in formato prometheus, in particolare:
- counter sul numero di pagamenti creati
- counter sul numero di errori durante il processamento di pagamenti, differenziando gli errori interni (errori di formato dati in ingresso o validazione) da errori esterni (errori di dialogo con l'IdP)
- latenza delle chiamate fatte all'IdP
Di seguito la tabella contenente le specifiche di ogni metrica

Metrica

Labels

Descrizione

Documentazione API di Esempio - Swagger

Get Status

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/status

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/status', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get Online Url

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/online-payment/{payment_id}

Path parameters

payment_id*Payment Id

Example: "5f99646d-769e-4d73-ba28-cffd30a77e74"

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/online-payment/{payment_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Get Notice File

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/notice/{payment_id}

Path parameters

payment_id*Payment Id

Example: "5f99646d-769e-4d73-ba28-cffd30a77e74"

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/notice/{payment_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Get Receipt File

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/receipt/{payment_id}

Path parameters

payment_id*Payment Id

Example: "5f99646d-769e-4d73-ba28-cffd30a77e74"

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/receipt/{payment_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Check For Updates

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/update/{payment_id}

Path parameters

payment_id*Payment Id

Example: "5f99646d-769e-4d73-ba28-cffd30a77e74"

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/update/{payment_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Get Landing Url

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/landing/{payment_id}

Path parameters

payment_id*Payment Id

Example: "5f99646d-769e-4d73-ba28-cffd30a77e74"

Query parameters

esitoEsito

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/landing/{payment_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Notify Payment

POSThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/notify-payment

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/notify-payment', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Get Tenant Form Schema

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/schema

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/schema', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get Tenant Configuration

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}

Path parameters

tenant_id*Tenant Id

Example: "b212c4b4-db26-4404-8c7c-47dab99dd2e6"

Response

Successful Response

Body

tax_identification_number*Tax Identification Number

nameName

code*Code

e2e_codeE2E Code

sil_id*Sil Id

receiver_codeReceiver Code

e2e_receiver_codeE2E Receiver Code

receiver_sil_idReceiver Sil Id

password*Password

cert*Cert

application_codeApplication Code

active*Active

stamp_codeStamp Code

stamp_passwordStamp Password

id*Id

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "tax_identification_number": "01234567891",
  "name": "Comune di Bugliano",
  "code": "CBugliano",
  "e2e_code": "CBugliano",
  "receiver_code": "RTIRIS",
  "e2e_receiver_code": "RTIRIS",
  "receiver_sil_id": "SIL_IRIS_ITR",
  "sil_id": "SIL_CBUGLIANO_OPEN",
  "password": "76JWL*G6bS!OM2e9*3Fg",
  "cert": "-----BEGIN CERTIFICATE REQUEST-----MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNVBAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl-----END CERTIFICATE REQUEST-----",
  "application_code": "",
  "active": true,
  "id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6"
}

Update Tenant Configuration

PUThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}

Path parameters

tenant_id*Tenant Id

Example: "b212c4b4-db26-4404-8c7c-47dab99dd2e6"

Body

tax_identification_number*Tax Identification Number

nameName

code*Code

e2e_codeE2E Code

sil_id*Sil Id

receiver_codeReceiver Code

e2e_receiver_codeE2E Receiver Code

receiver_sil_idReceiver Sil Id

password*Password

cert*Cert

application_codeApplication Code

active*Active

stamp_codeStamp Code

stamp_passwordStamp Password

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tax_identification_number": "01234567891",
      "name": "Comune di Bugliano",
      "code": "CBugliano",
      "e2e_code": "CBugliano",
      "receiver_code": "RTIRIS",
      "e2e_receiver_code": "RTIRIS",
      "receiver_sil_id": "SIL_IRIS_ITR",
      "password": "76JWL*G6bS!OM2e9*3Fg",
      "stamp_code": "CBugliano_SIL_E_BOLLO",
      "stamp_password": "76JWL*G6bS!OM2e9*3Fg",
      "sil_id": "SIL_CBUGLIANO_OPEN",
      "cert": "-----BEGIN CERTIFICATE REQUEST-----MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNVBAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl-----END CERTIFICATE REQUEST-----",
      "application_code": "",
      "active": true
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Delete Tenant

DELETEhttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}

Path parameters

tenant_id*Tenant Id

Example: "b212c4b4-db26-4404-8c7c-47dab99dd2e6"

Response

Successful Response

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Update Existing Tenant Configuration

PATCHhttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}

Path parameters

tenant_id*Tenant Id

Example: "b212c4b4-db26-4404-8c7c-47dab99dd2e6"

Body

New Configuration

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tax_identification_number": "1234567891"
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Save Tenant Configuration

POSThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants

Body

tax_identification_number*Tax Identification Number

nameName

code*Code

e2e_codeE2E Code

sil_id*Sil Id

receiver_codeReceiver Code

e2e_receiver_codeE2E Receiver Code

receiver_sil_idReceiver Sil Id

password*Password

cert*Cert

application_codeApplication Code

active*Active

stamp_codeStamp Code

stamp_passwordStamp Password

id*Id

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tax_identification_number": "01234567891",
      "name": "Comune di Bugliano",
      "code": "CBugliano",
      "e2e_code": "CBugliano",
      "receiver_code": "RTIRIS",
      "e2e_receiver_code": "RTIRIS",
      "receiver_sil_id": "SIL_IRIS_ITR",
      "sil_id": "SIL_CBUGLIANO_OPEN",
      "password": "76JWL*G6bS!OM2e9*3Fg",
      "cert": "-----BEGIN CERTIFICATE REQUEST-----MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNVBAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl-----END CERTIFICATE REQUEST-----",
      "application_code": "",
      "active": true,
      "id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6"
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Get Service Form Schema

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/schema

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/schema', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get Service Configuration

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}

Path parameters

service_id*Service Id

Example: "23d57b65-5eb9-4f0a-a507-fbcf3057b248"

Response

Successful Response

Body

tenant_id*Tenant Id

payment_typePayment Type

codeCode

descriptionDescription

active*Active

splitSplit

split_id*Split Id

split_typeSplit Type

split_codeSplit Code

split_descriptionSplit Description

split_amount*Split Amount

split_budget_chapterSplit Budget Chapter

split_assessmentSplit Assessment

stampPaymentStamp

items*Items

id*Id

amount*Amount

reasonReason

office_code*Office Code

office_description*Office Description

reference_code*Reference Code

notesNotes

id*Id

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "tenant_id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6",
  "payment_type": "pagopa",
  "code": "CONTR_PRTPM",
  "description": "<p>Abbonamento aree di sosta</p>",
  "active": true,
  "split": [
    {
      "split_id": "c_1",
      "split_type": "Tipo c1",
      "split_code": "Codice c1",
      "split_description": "Descrizione c1",
      "split_amount": 0.5,
      "split_budget_chapter": "Capitolo di bilancio c1",
      "split_assessment": "Accertamento c1"
    }
  ],
  "stamp": {
    "items": [
      {
        "id": "01",
        "amount": 16
      }
    ],
    "office_code": "FSE",
    "office_description": "Fondo Sociale Europeo",
    "reference_code": "BOLLO_TIROCINI",
    "notes": ""
  },
  "id": "23d57b65-5eb9-4f0a-a507-fbcf3057b248",
  "__$markdownParsed": true
}

Update Service Configuration

PUThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}

Path parameters

service_id*Service Id

Example: "23d57b65-5eb9-4f0a-a507-fbcf3057b248"

Body

tenant_id*Tenant Id

payment_typePayment Type

codeCode

descriptionDescription

active*Active

splitSplit

split_id*Split Id

split_typeSplit Type

split_codeSplit Code

split_descriptionSplit Description

split_amount*Split Amount

split_budget_chapterSplit Budget Chapter

split_assessmentSplit Assessment

stampPaymentStamp

items*Items

id*Id

amount*Amount

reasonReason

office_code*Office Code

office_description*Office Description

reference_code*Reference Code

notesNotes

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tenant_id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6",
      "payment_type": "pagopa",
      "code": "CONTR_PRTPM",
      "description": "<p>Abbonamento aree di sosta</p>",
      "active": true,
      "split": [
        {
          "split_id": "c_1",
          "split_type": "Tipo c1",
          "split_code": "Codice c1",
          "split_description": "Descrizione c1",
          "split_amount": 0.5,
          "split_budget_chapter": "Capitolo di bilancio c1",
          "split_assessment": "Accertamento c1"
        }
      ],
      "stamp": {
        "items": [
          {
            "id": "01",
            "amount": 16
          }
        ],
        "office_code": "FSE",
        "office_description": "Fondo Sociale Europeo",
        "reference_code": "BOLLO_TIROCINI",
        "notes": ""
      },
      "__$markdownParsed": true
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Delete Service

DELETEhttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}

Path parameters

service_id*Service Id

Example: "23d57b65-5eb9-4f0a-a507-fbcf3057b248"

Response

Successful Response

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Update Existing Service Configuration

PATCHhttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}

Path parameters

service_id*Service Id

Example: "23d57b65-5eb9-4f0a-a507-fbcf3057b248"

Body

New Configuration

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payment_type": "pagopa",
      "code": "CONTR_PRTPM",
      "description": "<p>Abbonamento aree di sosta</p>",
      "active": true,
      "split": [
        {
          "split_id": "c_1",
          "split_type": "Tipo c1",
          "split_code": "Codice c1",
          "split_description": "Descrizione c1",
          "split_amount": 0.5,
          "split_budget_chapter": "Capitolo di bilancio c1",
          "split_assessment": "Accertamento c1"
        }
      ],
      "__$markdownParsed": true
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Save Service Configuration

POSThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services

Body

tenant_id*Tenant Id

payment_typePayment Type

codeCode

descriptionDescription

active*Active

splitSplit

split_id*Split Id

split_typeSplit Type

split_codeSplit Code

split_descriptionSplit Description

split_amount*Split Amount

split_budget_chapterSplit Budget Chapter

split_assessmentSplit Assessment

stampPaymentStamp

items*Items

id*Id

amount*Amount

reasonReason

office_code*Office Code

office_description*Office Description

reference_code*Reference Code

notesNotes

id*Id

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tenant_id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6",
      "payment_type": "pagopa",
      "code": "CONTR_PRTPM",
      "description": "<p>Abbonamento aree di sosta</p>",
      "active": true,
      "split": [
        {
          "split_id": "c_1",
          "split_type": "Tipo c1",
          "split_code": "Codice c1",
          "split_description": "Descrizione c1",
          "split_amount": 0.5,
          "split_budget_chapter": "Capitolo di bilancio c1",
          "split_assessment": "Accertamento c1"
        }
      ],
      "id": "23d57b65-5eb9-4f0a-a507-fbcf3057b248",
      "__$markdownParsed": true
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Iris Proxy - Swagger UI

Esempi di proxy da cui si può prendere spunto

EFIL: http://gitlab.com/opencontent/stanza-del-cittadino/efil-payment-proxy

IRIS: http://gitlab.com/opencontent/stanza-del-cittadino/iris-payment-proxy

MYPAY: http://gitlab.com/opencontent/stanza-del-cittadino/mypay-payment-proxy

PMPAY: http://gitlab.com/opencontent/stanza-del-cittadino/pmpay-payment-proxy

Questi proxy condividono alcune scelte implementative grazie a un apposito python-sdk sviluppato in parallelo ai proxy stessi:

le configurazioni sono salvate su disco locale o s3 secondo un albero ben definito tenant->servizio
i singoli pagamenti vengono salvati su storage fino a che il pagamento è pendente, così da poter fare il polling in autonomia.

Altri riferimenti utili

Update Existing Tenant Configuration

PATCHhttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}

Path parameters

tenant_id*Tenant Id

Example: "b212c4b4-db26-4404-8c7c-47dab99dd2e6"

Body

New Configuration

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tax_identification_number": "1234567891"
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Update Existing Service Configuration

PATCHhttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}

Path parameters

service_id*Service Id

Example: "23d57b65-5eb9-4f0a-a507-fbcf3057b248"

Body

New Configuration

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payment_type": "pagopa",
      "code": "CONTR_PRTPM",
      "description": "<p>Abbonamento aree di sosta</p>",
      "active": true,
      "split": [
        {
          "split_id": "c_1",
          "split_type": "Tipo c1",
          "split_code": "Codice c1",
          "split_description": "Descrizione c1",
          "split_amount": 0.5,
          "split_budget_chapter": "Capitolo di bilancio c1",
          "split_assessment": "Accertamento c1"
        }
      ],
      "__$markdownParsed": true
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Get Tenant Configuration

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}

Path parameters

tenant_id*Tenant Id

Example: "b212c4b4-db26-4404-8c7c-47dab99dd2e6"

Response

Successful Response

Body

tax_identification_number*Tax Identification Number

nameName

code*Code

e2e_codeE2E Code

sil_id*Sil Id

receiver_codeReceiver Code

e2e_receiver_codeE2E Receiver Code

receiver_sil_idReceiver Sil Id

password*Password

cert*Cert

application_codeApplication Code

active*Active

stamp_codeStamp Code

stamp_passwordStamp Password

id*Id

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "tax_identification_number": "01234567891",
  "name": "Comune di Bugliano",
  "code": "CBugliano",
  "e2e_code": "CBugliano",
  "receiver_code": "RTIRIS",
  "e2e_receiver_code": "RTIRIS",
  "receiver_sil_id": "SIL_IRIS_ITR",
  "sil_id": "SIL_CBUGLIANO_OPEN",
  "password": "76JWL*G6bS!OM2e9*3Fg",
  "cert": "-----BEGIN CERTIFICATE REQUEST-----MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNVBAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl-----END CERTIFICATE REQUEST-----",
  "application_code": "",
  "active": true,
  "id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6"
}

Update Tenant Configuration

PUThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}

Path parameters

tenant_id*Tenant Id

Example: "b212c4b4-db26-4404-8c7c-47dab99dd2e6"

Body

tax_identification_number*Tax Identification Number

nameName

code*Code

e2e_codeE2E Code

sil_id*Sil Id

receiver_codeReceiver Code

e2e_receiver_codeE2E Receiver Code

receiver_sil_idReceiver Sil Id

password*Password

cert*Cert

application_codeApplication Code

active*Active

stamp_codeStamp Code

stamp_passwordStamp Password

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tax_identification_number": "01234567891",
      "name": "Comune di Bugliano",
      "code": "CBugliano",
      "e2e_code": "CBugliano",
      "receiver_code": "RTIRIS",
      "e2e_receiver_code": "RTIRIS",
      "receiver_sil_id": "SIL_IRIS_ITR",
      "password": "76JWL*G6bS!OM2e9*3Fg",
      "stamp_code": "CBugliano_SIL_E_BOLLO",
      "stamp_password": "76JWL*G6bS!OM2e9*3Fg",
      "sil_id": "SIL_CBUGLIANO_OPEN",
      "cert": "-----BEGIN CERTIFICATE REQUEST-----MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNVBAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl-----END CERTIFICATE REQUEST-----",
      "application_code": "",
      "active": true
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Save Tenant Configuration

POSThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants

Body

tax_identification_number*Tax Identification Number

nameName

code*Code

e2e_codeE2E Code

sil_id*Sil Id

receiver_codeReceiver Code

e2e_receiver_codeE2E Receiver Code

receiver_sil_idReceiver Sil Id

password*Password

cert*Cert

application_codeApplication Code

active*Active

stamp_codeStamp Code

stamp_passwordStamp Password

id*Id

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tax_identification_number": "01234567891",
      "name": "Comune di Bugliano",
      "code": "CBugliano",
      "e2e_code": "CBugliano",
      "receiver_code": "RTIRIS",
      "e2e_receiver_code": "RTIRIS",
      "receiver_sil_id": "SIL_IRIS_ITR",
      "sil_id": "SIL_CBUGLIANO_OPEN",
      "password": "76JWL*G6bS!OM2e9*3Fg",
      "cert": "-----BEGIN CERTIFICATE REQUEST-----MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNVBAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl-----END CERTIFICATE REQUEST-----",
      "application_code": "",
      "active": true,
      "id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6"
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Save Service Configuration

POSThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services

Body

tenant_id*Tenant Id

payment_typePayment Type

codeCode

descriptionDescription

active*Active

splitSplit

split_id*Split Id

split_typeSplit Type

split_codeSplit Code

split_descriptionSplit Description

split_amount*Split Amount

split_budget_chapterSplit Budget Chapter

split_assessmentSplit Assessment

stampPaymentStamp

items*Items

id*Id

amount*Amount

reasonReason

office_code*Office Code

office_description*Office Description

reference_code*Reference Code

notesNotes

id*Id

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tenant_id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6",
      "payment_type": "pagopa",
      "code": "CONTR_PRTPM",
      "description": "<p>Abbonamento aree di sosta</p>",
      "active": true,
      "split": [
        {
          "split_id": "c_1",
          "split_type": "Tipo c1",
          "split_code": "Codice c1",
          "split_description": "Descrizione c1",
          "split_amount": 0.5,
          "split_budget_chapter": "Capitolo di bilancio c1",
          "split_assessment": "Accertamento c1"
        }
      ],
      "id": "23d57b65-5eb9-4f0a-a507-fbcf3057b248",
      "__$markdownParsed": true
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Get Service Configuration

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}

Path parameters

service_id*Service Id

Example: "23d57b65-5eb9-4f0a-a507-fbcf3057b248"

Response

Successful Response

Body

tenant_id*Tenant Id

payment_typePayment Type

codeCode

descriptionDescription

active*Active

splitSplit

split_id*Split Id

split_typeSplit Type

split_codeSplit Code

split_descriptionSplit Description

split_amount*Split Amount

split_budget_chapterSplit Budget Chapter

split_assessmentSplit Assessment

stampPaymentStamp

items*Items

id*Id

amount*Amount

reasonReason

office_code*Office Code

office_description*Office Description

reference_code*Reference Code

notesNotes

id*Id

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "tenant_id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6",
  "payment_type": "pagopa",
  "code": "CONTR_PRTPM",
  "description": "<p>Abbonamento aree di sosta</p>",
  "active": true,
  "split": [
    {
      "split_id": "c_1",
      "split_type": "Tipo c1",
      "split_code": "Codice c1",
      "split_description": "Descrizione c1",
      "split_amount": 0.5,
      "split_budget_chapter": "Capitolo di bilancio c1",
      "split_assessment": "Accertamento c1"
    }
  ],
  "stamp": {
    "items": [
      {
        "id": "01",
        "amount": 16
      }
    ],
    "office_code": "FSE",
    "office_description": "Fondo Sociale Europeo",
    "reference_code": "BOLLO_TIROCINI",
    "notes": ""
  },
  "id": "23d57b65-5eb9-4f0a-a507-fbcf3057b248",
  "__$markdownParsed": true
}

Update Service Configuration

PUThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}

Path parameters

service_id*Service Id

Example: "23d57b65-5eb9-4f0a-a507-fbcf3057b248"

Body

tenant_id*Tenant Id

payment_typePayment Type

codeCode

descriptionDescription

active*Active

splitSplit

split_id*Split Id

split_typeSplit Type

split_codeSplit Code

split_descriptionSplit Description

split_amount*Split Amount

split_budget_chapterSplit Budget Chapter

split_assessmentSplit Assessment

stampPaymentStamp

items*Items

id*Id

amount*Amount

reasonReason

office_code*Office Code

office_description*Office Description

reference_code*Reference Code

notesNotes

Response

Successful Response

Body

any

Request

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tenant_id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6",
      "payment_type": "pagopa",
      "code": "CONTR_PRTPM",
      "description": "<p>Abbonamento aree di sosta</p>",
      "active": true,
      "split": [
        {
          "split_id": "c_1",
          "split_type": "Tipo c1",
          "split_code": "Codice c1",
          "split_description": "Descrizione c1",
          "split_amount": 0.5,
          "split_budget_chapter": "Capitolo di bilancio c1",
          "split_assessment": "Accertamento c1"
        }
      ],
      "stamp": {
        "items": [
          {
            "id": "01",
            "amount": 16
          }
        ],
        "office_code": "FSE",
        "office_description": "Fondo Sociale Europeo",
        "reference_code": "BOLLO_TIROCINI",
        "notes": ""
      },
      "__$markdownParsed": true
    }),
});
const data = await response.json();

Response

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}