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

Metrica

Labels

Descrizione

oc_payment_validation_errors_total

cluster, env, app_name

la metrica deve misurare gli errori di validazione sull'evento letto (es. l'importo è una stringa invece che un float)

oc_api_requests_total

cluster, env, method, app_name, status_code

la metrica deve monitorare le chiamate http indicandone lo status code

oc_payment_success_events_total

cluster, env, app_name

la metrica deve misurare solo gli eventi per cui il proxy ha una configurazione e che stati processati con successo

oc_payment_failed_events_total

cluster, env, app_name

la metrica deve misurare gli eventi di pagamento validi di cui però è fallito il processing per qualsiasi motivo (escluso il caso in cui non esiste una configurazione per esso)

oc_payment_provider_errors_total

cluster, env, app_name

la metrica deve misurare gli eventi di pagamento validi di cui però è fallito il processing a causa di un errore sul provider

oc_payment_internal_errors_total

cluster, env, app_name

la metrica deve misurare gli eventi di pagamento validi di cui però è fallito il processing per errori interni al codice

oc_payment_provider_latency_bucket

cluster, env, app_name

istogramma che mostra la distribuzione di latenza delle risposte del provider

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

Get Status

get

Get Service Status

Responses

200

Successful Response

application/problem+json

statusstringRequired

422

Validation Error

application/problem+json

503

Service Unavailable

application/problem+json

get

/status

GET /payment-proxy/mypay-trentino/v2/status HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

{
  "status": "text"
}

Get Online Url

get

Path parameters

payment_idstringRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

get

/online-payment/{payment_id}

GET /payment-proxy/mypay-trentino/v2/online-payment/{payment_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

No content

Get Notice Url

get

Path parameters

payment_idstringRequired

Query parameters

offline_urlstringRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

get

/notice/{payment_id}

GET /payment-proxy/mypay-trentino/v2/notice/{payment_id}?offline_url=text HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

No content

Get Receipt Url

get

Path parameters

payment_idstringRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

get

/receipt/{payment_id}

GET /payment-proxy/mypay-trentino/v2/receipt/{payment_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

No content

Check For Updates

get

Path parameters

payment_idstringRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

get

/update/{payment_id}

GET /payment-proxy/mypay-trentino/v2/update/{payment_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

No content

Get Landing Url

get

Path parameters

payment_idanyRequired

Query parameters

idSessionstringOptional

esitostringOptionalDefault: OK

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

get

/landing/{payment_id}

GET /payment-proxy/mypay-trentino/v2/landing/{payment_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

No content

Register Payment

patch

Path parameters

payment_idanyRequired

Body

statusundefined · enumRequired

An enumeration.

Possible values:

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

patch

/payments/{payment_id}

PATCH /payment-proxy/mypay-trentino/v2/payments/{payment_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "status": "CANCELED"
}

No content

Get Tenant Form Schema

get

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

get

/tenants/schema

GET /payment-proxy/mypay-trentino/v2/tenants/schema HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

No content

Get Tenant Configuration

get

Path parameters

tenant_idstring · uuidRequired

Responses

200

Successful Response

application/json

namestringRequired

IPA_codestringRequired

tax_identification_numberstringOptional

passwordstringRequired

cart_passwordstringOptionalDefault: ""

application_codestringOptionalDefault: ""

activebooleanRequired

enable_checkoutbooleanOptionalDefault: false

idstring · uuidRequired

422

Validation Error

application/problem+json

get

/tenants/{tenant_id}

GET /payment-proxy/mypay-trentino/v2/tenants/{tenant_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

{
  "name": "text",
  "IPA_code": "text",
  "tax_identification_number": "text",
  "password": "text",
  "cart_password": "",
  "application_code": "",
  "active": true,
  "enable_checkout": false,
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Update Tenant Configuration

put

Path parameters

tenant_idstring · uuidRequired

Body

namestringRequired

IPA_codestringRequired

tax_identification_numberstringOptional

passwordstringRequired

cart_passwordstringOptionalDefault: ""

application_codestringOptionalDefault: ""

activebooleanRequired

enable_checkoutbooleanOptionalDefault: false

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

put

/tenants/{tenant_id}

PUT /payment-proxy/mypay-trentino/v2/tenants/{tenant_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Content-Type: application/json
Accept: */*
Content-Length: 165

{
  "name": "text",
  "IPA_code": "text",
  "tax_identification_number": "text",
  "password": "text",
  "cart_password": "",
  "application_code": "",
  "active": true,
  "enable_checkout": false
}

No content

Update Existing Tenant Configuration

patch

Path parameters

tenant_idstring · uuidRequired

Body

object · NewConfigurationOptional

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

patch

/tenants/{tenant_id}

PATCH /payment-proxy/mypay-trentino/v2/tenants/{tenant_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

No content

Delete Tenant

delete

Path parameters

tenant_idstring · uuidRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

delete

/tenants/{tenant_id}

DELETE /payment-proxy/mypay-trentino/v2/tenants/{tenant_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

No content

Save Tenant Configuration

post

Body

namestringRequired

IPA_codestringRequired

tax_identification_numberstringOptional

passwordstringRequired

cart_passwordstringOptionalDefault: ""

application_codestringOptionalDefault: ""

activebooleanRequired

enable_checkoutbooleanOptionalDefault: false

idstring · uuidRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

post

/tenants

POST /payment-proxy/mypay-trentino/v2/tenants HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Content-Type: application/json
Accept: */*
Content-Length: 209

{
  "name": "text",
  "IPA_code": "text",
  "tax_identification_number": "text",
  "password": "text",
  "cart_password": "",
  "application_code": "",
  "active": true,
  "enable_checkout": false,
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

No content

Get Service Form Schema

get

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

get

/configs/schema

GET /payment-proxy/mypay-trentino/v2/configs/schema HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

No content

Get Payment Configurations List

get

Query parameters

config_idsstring · uuid[]Optional

Lista id delle configurazioni di pagamento

Responses

200

Successful Response

application/json

tenant_idstring · uuidRequired

activebooleanRequired

idstring · uuidOptional

422

Validation Error

application/problem+json

get

/configs

GET /payment-proxy/mypay-trentino/v2/configs HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

[
  {
    "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
    "remote_collection": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "service"
    },
    "items": [
      {
        "payment_type": "pagopa",
        "management_id": "text",
        "amount": 1,
        "reason": "text",
        "expire_at": 1,
        "collection_data": "text",
        "pagopa_category": "text",
        "split": [
          {
            "id": "text",
            "budget_chapter": "text",
            "office_code": "text",
            "assessment": "text",
            "amount": 1
          }
        ],
        "fixed_expiration_date": "2026-02-27T00:51:01.789Z",
        "receiver": {
          "tax_identification_number": "text",
          "name": "text",
          "iban": "text",
          "address": "text",
          "building_number": "text",
          "postal_code": "text",
          "town_name": "text",
          "country_subdivision": "text",
          "country": "text"
        }
      }
    ],
    "active": true,
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }
]

Save Payment Configuration

post

Body

tenant_idstring · uuidRequired

activebooleanRequired

idstring · uuidOptional

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

post

/configs

POST /payment-proxy/mypay-trentino/v2/configs HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Content-Type: application/json
Accept: */*
Content-Length: 698

{
  "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
  "remote_collection": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "service"
  },
  "items": [
    {
      "payment_type": "pagopa",
      "management_id": "text",
      "amount": 1,
      "reason": "text",
      "expire_at": 1,
      "collection_data": "text",
      "pagopa_category": "text",
      "split": [
        {
          "id": "text",
          "budget_chapter": "text",
          "office_code": "text",
          "assessment": "text",
          "amount": 1
        }
      ],
      "fixed_expiration_date": "2026-02-27T00:51:01.789Z",
      "receiver": {
        "tax_identification_number": "text",
        "name": "text",
        "iban": "text",
        "address": "text",
        "building_number": "text",
        "postal_code": "text",
        "town_name": "text",
        "country_subdivision": "text",
        "country": "text"
      }
    }
  ],
  "active": true,
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

No content

Get Payment Configuration

get

Path parameters

config_idstring · uuidRequired

Responses

200

Successful Response

application/json

tenant_idstring · uuidRequired

activebooleanRequired

idstring · uuidOptional

422

Validation Error

application/problem+json

get

/configs/{config_id}

GET /payment-proxy/mypay-trentino/v2/configs/{config_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

{
  "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
  "remote_collection": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "service"
  },
  "items": [
    {
      "payment_type": "pagopa",
      "management_id": "text",
      "amount": 1,
      "reason": "text",
      "expire_at": 1,
      "collection_data": "text",
      "pagopa_category": "text",
      "split": [
        {
          "id": "text",
          "budget_chapter": "text",
          "office_code": "text",
          "assessment": "text",
          "amount": 1
        }
      ],
      "fixed_expiration_date": "2026-02-27T00:51:01.789Z",
      "receiver": {
        "tax_identification_number": "text",
        "name": "text",
        "iban": "text",
        "address": "text",
        "building_number": "text",
        "postal_code": "text",
        "town_name": "text",
        "country_subdivision": "text",
        "country": "text"
      }
    }
  ],
  "active": true,
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Update Payment Configuration

put

Path parameters

config_idstring · uuidRequired

Body

tenant_idstring · uuidRequired

activebooleanRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

put

/configs/{config_id}

PUT /payment-proxy/mypay-trentino/v2/configs/{config_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Content-Type: application/json
Accept: */*
Content-Length: 654

{
  "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
  "remote_collection": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "service"
  },
  "items": [
    {
      "payment_type": "pagopa",
      "management_id": "text",
      "amount": 1,
      "reason": "text",
      "expire_at": 1,
      "collection_data": "text",
      "pagopa_category": "text",
      "split": [
        {
          "id": "text",
          "budget_chapter": "text",
          "office_code": "text",
          "assessment": "text",
          "amount": 1
        }
      ],
      "fixed_expiration_date": "2026-02-27T00:51:01.789Z",
      "receiver": {
        "tax_identification_number": "text",
        "name": "text",
        "iban": "text",
        "address": "text",
        "building_number": "text",
        "postal_code": "text",
        "town_name": "text",
        "country_subdivision": "text",
        "country": "text"
      }
    }
  ],
  "active": true
}

No content

Delete Service

delete

Path parameters

config_idstring · uuidRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

delete

/configs/{config_id}

DELETE /payment-proxy/mypay-trentino/v2/configs/{config_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

No content

Update Existing Payment Configuration

patch

Path parameters

config_idstring · uuidRequired

Body

object · NewConfigurationOptional

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

patch

/configs/{config_id}

PATCH /payment-proxy/mypay-trentino/v2/configs/{config_id} HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

No content

Update User Dues

post

Body

tax_identification_numberstringRequired

user_idstringRequired

tenant_idstringRequired

job_idstringRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

post

/update-user-dues

POST /payment-proxy/mypay-trentino/v2/update-user-dues HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "tax_identification_number": "text",
  "user_id": "text",
  "tenant_id": "text",
  "job_id": "text"
}

No content

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

PreviousProcesso di sviluppo NextIntegrazione con Protocollo Informatico

Last updated 3 months ago

Was this helpful?

Good night

hashtagRequisiti funzionali

hashtagRequisiti normativi

hashtagRequisiti per l'ambiente di produzione

hashtagDocumentazione API di Esempio - Swagger

hashtagGet Status

hashtagGet Online Url

hashtagGet Notice Url

hashtagGet Receipt Url

hashtagCheck For Updates

hashtagGet Landing Url

hashtagRegister Payment

hashtagGet Tenant Form Schema

hashtagGet Tenant Configuration

hashtagUpdate Tenant Configuration

hashtagUpdate Existing Tenant Configuration

hashtagDelete Tenant

hashtagSave Tenant Configuration

hashtagGet Service Form Schema

hashtagGet Payment Configurations List

hashtagSave Payment Configuration

hashtagGet Payment Configuration

hashtagUpdate Payment Configuration

hashtagDelete Service

hashtagUpdate Existing Payment Configuration

hashtagUpdate User Dues

hashtagEsempi di proxy da cui si può prendere spunto

hashtagAltri riferimenti utili

Requisiti funzionali

Requisiti normativi

Requisiti per l'ambiente di produzione

Documentazione API di Esempio - Swagger

Get Status

Get Online Url

Get Notice Url

Get Receipt Url

Check For Updates

Get Landing Url

Register Payment

Get Tenant Form Schema

Get Tenant Configuration

Update Tenant Configuration

Update Existing Tenant Configuration

Delete Tenant

Save Tenant Configuration

Get Service Form Schema

Get Payment Configurations List

Save Payment Configuration

Get Payment Configuration

Update Payment Configuration

Delete Service

Update Existing Payment Configuration

Update User Dues

Esempi di proxy da cui si può prendere spunto

Altri riferimenti utili