FlowPay API (v1)

openapi: 3.0.3
info:
  contact:
    email: federico.giuntoli@flowpay.it
    name: Federico Giuntoli
  description: "\nHai uno use case di pagamento complesso come pagamenti massivi, split o pagopa? [chiedi qui](https://meetings.hubspot.com/rmancini)\n# Autenticazione\n​\n\n## Premesse\n ​\nPotete richiedere due tipi diversi di client a seconda delle vostre esigenze di implementazione:\n* Client pubblico: Possiede un `client_id` ma non un `client_secret` ed è pensato per applicativi che non sono in grado di mantenere un `client_secret` al sicuro (e.g. Un applicazione solamente frontend, o mobile).\n* Client confidenziale: Possiede un `client_id` e un `client_secret`ed è in grado di mantenere sicuro il `client_secret` (e.g. Un applicativo server, una combinazione di applicativi frontend + backend dove il backend si occupa delle chiamate API.)\n\n\n## Autenticazione con client credentials\n\nQuesto tipo di autenticazione è riservato per client confidenziali e attualmente permette di ottenere token collegato al vostro client utilizzato (per il momento) solamente presso l'endpoint di\ncreazione\
    \ di un consenso di riconciliazione\n\n```\nPOST https://core.sandbox-new.flowpay.it/api/oauth/token\n```\n\ncon content-type `application/x-www-form-urlencoded`\n| nome | descrizione | esempio |\n|------|-------------|---------|\n| client_id | client ID fornito (il client id è un valore pubblico) | 9a585977-98c1-4f68-a0a5-651a192f7383 |\n| grant_type | Tipo di autenticazione fornita nella richiesta (in questo caso credenziali client) | client_credentials |\n| client_secret | vostro client secret fornito in fase di registrazione | client-secret |\n| scope | Tipi di scope da fornire nel token di risposta (notare che sono diversi da quelli di authorization code) | reconciliation |\n\nesempio di risposta\n\n```json\n    {\n        \"access_token\": \"1234567890-token-1234567890\",\n        \"token_type\": \"bearer\",\n        \"expires_in\": 3600,\n        \"scope\": \"reconciliation\"\n    }\n```\n\n\n## Flusso di autenticazione\n\n### Autorizzazione\n​\nIl flusso di autenticazione si\
    \ basa su un flusso standard OAuth2 di `authorization code` quindi dal vostro applicativo l'utente deve essere rediretto da un browser al seguente link (il link vale per l'ambiente di sandbox):\n```\nhttps://core.sandbox-new.flowpay.it/api/openid/authenticate\n```\n​\nPassando nei query params del redirect i seguenti parametri obbligatori:\n​\n| nome | descrizione | esempio |\n|------|-------------|-----|\n| client_id | client ID fornito (il client id è un valore pubblico) | 9a585977-98c1-4f68-a0a5-651a192f7383  |\n| response_type | tipo di risposta del server (nel vostro caso dovrebbe essere code) | code |\n| scope | lista di scope richiesti separati dal carattere spazio | `invoice:read(spazio)invoice:write` Spazio indica il carattere |\n| redirect_uri | dove effettuare il redirect una volta completato il flusso di autorizzazione. Durante la creazione dell'applicativo è stato possibile (ed è sempre possibile modificarli) indicare le url autorizzate per la vostra applicazione | `https://ex.amp.le/redirect`\
    \ |\n​| request | campo request standard openid si rimanda a **Flusso autorizzativo di riconciliazione** per un esempio | jwt encoded request |\n\nInoltre è possibile indicare un ulteriore parametro:\n​\n`state`: un valore in qualunque formato che verra' ripassato indietro invariato nel redirect al `redirect_uri`\n​\nNel caso il vostro applicativo sia un client pubblico è necesarrio utilizzare l'estensione [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) di Oauth2 ed è quindi necessario passare nella url due ulteriori parametri: `code_challenge` e `code_challenge_method`\n\n**In sandbox sono forniti client confidenziali ma è comunque possibile effettuare un flusso di autenticazione con estensione PKCE per testare la propria implementazione, in ambiente di produzione il tipo di flusso utilizzabile sarà definito dal tipo di client** ​\n\n* `code_challenge`: questo valore corrisponde al BASE64URL(SHA256(`code_verifier`)) dove BASE64URL indica di codificare in base64urlencoded e SHA256\
    \ indica la funzione di hashing. `code_verifier` è una stringa casuale creata dall'applicativo all'inizio della richiesta di lunghezza compresa tra 43 e 128 caratteri\n* `code_challenge_method`: unico valore ammesso `S256`\n​\nUn esempio per generare una code_challenge in js potrebbe essere\n​\n```js\n​\nconst gen_code_challenge = async () => {\n    const buffer = new Uint8Array(64)\n    crypto.getRandomValues(buffer)\n    const code_verifier = btoa(String.fromCharCode(...buffer))\n    //crypto.subtle è presente se la pagina web è caricata su https\n    const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier))\n    const code_challenge = btoa(String.fromCharCode(...new Uint8Array(hash)))\n        .replace(/=/g, '').replace(/\\+/g, '-').replace(/\\//g, '_')\n    return { code_verifier, code_challenge }\n}\n```\n​\nQuindi un esempio di url di redirect finale potrebbe essere\n​\n```\nhttps://core.sandbox-new.flowpay.it/api/openid/authenticate?client_id=9a585977-98c1-4f68-a0a5-651a192f7383&scope=invoice:read\
    \ invoice:write&response_type=code&redirect_uri=https://ex.amp.le/redirect&state=1234567890\n```\n​\n​\nL'utente a questo punto concedera' l'autorizzazione per gli scope richiesti (questa parte di flusso è gestita da FlowPay).\n​\nDopo che l'utente ha autorizzato verra' effettuato il redirect alla url indicata nella richiesta iniziale dove verra' inserito nei queri parameters i seguenti campi:\n​\n* `code`: Codice autorizzativo necessario nel prossimo step, di brevissima vita e mono uso\n* `state`: Se presente nella richiesta originaria, viene reinviato non modificato\n​\nquindi ad esempio\n​\n```\nhttps://ex.amp.le/redirect?code=423as23asdfweqf&state=1234567890\n```\n​\n### Ottenimento dell'Access Token\n​\neffettuato il redirect adesso è possibile scambiare il code ottenuto per access token + refresh token con una chiamata all'access token endpoint:\n​\n```\nPOST https://core.sandbox-new.flowpay.it/api/oauth/token\n```\n​\ncon content-type `application/x-www-form-urlencoded`\n​\ne\
    \ body composto da:\n\n| parametro | valore |\n|--|--|\n| grant_type | authorization_code |\n| client_id | vostro client id |\n| code | codice ottenuto nel redirect |\n| redirect_uri | redirect uri della richiesta iniziale |\n\n\nInoltre nel caso il client sia privato è necessario aggiungere il parametro `client_secret` mentre nel caso di un client pubblico è necessario inviare il parametro `code_verifier` generato prima della richiesta iniziale.\n​\nLa risposta conterra' l'access_token e il refresh_token necessari per interagire con il gateway FlowPay\n\n\n## Flusso autorizzativo per lettura di dati relativi ad un conto\n\nPer poter ottenere un token autorizzativo che permetta di leggere dati sui conti un di un utente (iban, saldo, transazioni) è necessario per motivi di sicurezza essere un client di tipo confidenziale e quindi di avere a disposizione un client id e un client secret.\n\nIl flusso è diviso nei seguenti passaggi\n\n### Ottenimento di un token `client_credential` abilitato\
    \ sullo scope `authorization_intent`\nUn token di questo tipo è collegato al client e non ad un utente e permette di invocare l'endpoint di creazione di un intento di consenso di accesso ai conti di un utente\n\nIn questo caso la chiamata è così composta:\n\n```\nPOST https://core.sandbox-new.flowpay.it/api/oauth/token\n```\n\n| nome | descrizione | esempio |\n|------|-------------|---------|\n| client_id | client ID fornito (il client id è un valore pubblico) | 9a585977-98c1-4f68-a0a5-651a192f7383 |\n| grant_type | Tipo di autenticazione fornita nella richiesta (in questo caso credenziali client) | client_credentials |\n| client_secret | vostro client secret fornito in fase di registrazione | client-secret |\n| scope | Tipi di scope da fornire nel token di risposta (notare che sono diversi da quelli di authorization code) in questo caso siamo interessati allo scope `authorization_intent` | authorization_intent |\n\n\nQuesta chiamata restituirà un access_token in grado di invocare l'endpoint\
    \ di creazione di un consenso di riconciliazione necessario nel passaggio successivo\n\nesempio di risposta\n\n```json\n    {\n        \"access_token\": \"1234567890-token-1234567890\",\n        \"token_type\": \"bearer\",\n        \"expires_in\": 3600,\n        \"scope\": \"authorization_intent\"\n    }\n```\n\n\n### Creazione di un consenso di riconciliazione\n\nCon l'access token ottenuto al passaggio precedente si è in grado di invocare la rotta\n\n```\nPOST /authorization/intent/account\n```\n\nutilizzando tale token come bearer token.\n\nEsempio di body\n\n```json\n{\n    \"transaction\": true,\n    \"balance\": true,\n    \"strict\": false,\n}\n```\n\nNel caso si voglia restringere la richiesta a degli account specifici dell'utente (sempre che si conoscano) è possibile inviare la lista di IBAN sui quale si vuole il consenso direttamente nella chiamata.\nLasciando il parametro a `null` sarà l'utente stesso a decidere su quali conti fornire il consenso.\n\nLa risposta conterrà l'id\
    \ del consenso appena generato necessario nel prossimo passaggio\n\n```json\n{\n    \"transaction\": true,\n    \"balance\": true,\n    \"id\": \"69EA2496-B2D1-4D29-BE22-9C93F2FE1699\"\n}\n```\n\n\n### Autorizzazione del consenso\n\nQuesti step del flusso sono avvenuti senza nessuna interazione con l'utente finale al quale si sta richiedendo il consenso.\nAdesso è necessario collegare il consenso creato ad un utente, per fare ciò il client deve generare un link di autorizzazione come già spiegato nella documentazione del flusso di autenticazione utilizzando un ulteriore parametro da aggiungere a quelli già discussi:\nIl parametro aggiuntivo è il parametro standard `request` nel contesto [OpenID](https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests).\nIl parametro `request` ha il duplice scopo di verificare l'identità del client e di richiedere all'endpoint di autorizzazione ulteriori funzionalità.\nIn questo specifico caso viene richiesto di autorizzare un consenso alla\
    \ lettura dei conti di un utente. \n\n### Generazione del campo request\n\nIl campo request è un JWT formato dai seguenti parametri:\n\n```json\nHEADER:\n{\n    \"typ\": \"JWT\",\n    \"alg\": \"algoritmo di firma applicato al token\",\n    \"kid\": \"id univoco della chiave utilizzata per firmare il jwt\"\n}\nPAYLOAD:\n{\n    \"iss\": \"9a585977-98c1-4f68-a0a5-651a192f7383\", //Issuer del JWT in questo caso voi e quindi il campo corrisponde al vostro client_id\n    \"aud\": \"https://core.sandbox-new.flowpay.it/api/openid/\", //Audience al quale è rivolto il jwk in questo caso il nostro servizio di openid\n    \"redirect_uri\": \"https://ex.amp.le\", //stesso redirect uri passato nel parametro dei query params\n    \"client_id\": \"9a585977-98c1-4f68-a0a5-651a192f7383\", //vostro client_id\n    \"state\": \"123456789\", //se presente, deve essere uguale al parametro nei query params\n    \"scope\": \"openid authorization_intent\", //stessi scope inviati nei query params in questo caso\
    \ lo scope openid è necessario per attivare le funzionalità openid e authorization_intent indica che si vuole attivare l'estensione di autorizzazione di uno specifico consenso\n    \"response_type\": \"id_token code\", //stessi valori passati nel campo dei query params\n    \"claims\": {\n        \"id_token\": {\n            \"account_access_intent\": {\n                \"value\": \"69EA2496-B2D1-4D29-BE22-9C93F2FE1699\", //ID del consenso generato nel passaggio precedente.\n                \"essential\": true\n            }\n        }\n    }\n}\n```\n\nLa richiesta verso l'endpoint di autorizzazione che richiede di concedere il consenso in lettura degli account di un utente passa attraverso l'inserimento dell'id del consenso creato al punto precendete e non ancora speso\nnel campo `claims.id_token.account_access_intent`.\n\nCon un esempio concreto abbiamo:\n\n```json\nHEADER\n{\n    \"typ\": \"JWT\",\n    \"alg\": \"ES256\",\n    \"kid\": \"12345678\"\n}\nPAYLOAD\n{\n    \"iss\": \"\
    9a585977-98c1-4f68-a0a5-651a192f7383\",\n    \"aud\": \"https://core.sandbox-new.flowpay.it/api/openid\",\n    \"redirect_uri\": \"https://ex.amp.le/redirect\",\n    \"client_id\": \"9a585977-98c1-4f68-a0a5-651a192f7383\",\n    \"state\": \"123456789\",\n    \"scope\": \"invoice:read invoice:write openid authorization_intent\",\n    \"response_type\": \"code\",\n    \"claims\": {\n        \"id_token\": {\n            \"account_access_intent\": {\n                \"value\": \"69EA2496-B2D1-4D29-BE22-9C93F2FE1699\",\n                \"essential\": true\n            }\n        }\n    }\n}\n```\n\nfirmando il jwt con la seguente chiave:\n```\nREDACTED_PRIVATE_KEY_EXAMPLE\n```\n\nOtteniamo il seguente risultato:\n```\neyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjEyMzQ1Njc4In0.eyJpc3MiOiI5YTU4NTk3Ny05OGMxLTRmNjgtYTBhNS02NTFhMTkyZjczODMiLCJhdWQiOiJodHRwczovL2NvcmUuc2FuZGJveC1uZXcuZmxvd3BheS5pdC9hcGkvb3BlbmlkIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9leC5hbXAubGUvcmVkaXJlY3QiLCJjbGllbnRfaWQiOiI5YTU4NTk3Ny05OGMxLTRmNjgtYTBhNS02NTFhMTkyZjczODMiLCJzdGF0ZSI6IjEyMzQ1Njc4OSIsInNjb3BlIjoiaW52b2ljZTpyZWFkIGludm9pY2U6d3JpdGUgb3BlbmlkIGF1dGhvcml6YXRpb25faW50ZW50IiwicmVzcG9uc2VfdHlwZSI6ImNvZGUiLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsiYWNjb3VudF9hY2Nlc3NfaW50ZW50Ijp7InZhbHVlIjoiNjlFQTI0OTYtQjJEMS00RDI5LUJFMjItOUM5M0YyRkUxNjk5IiwiZXNzZW50aWFsIjp0cnVlfX19fQ.P0Pqeho32esd2crpw2q-AZoSlIPlZ5xy6w6e7GMBIznAB4ohcYIOquZGNC3f-IwXBGcJow-ZvCH7A6jiYKRLHA\n\
    ```\n\nquesto jwt deve essere incluso nella richiesta di autenticazione nel campo `request`\n\n\n**Notare che in sandbox non viene verificata la firma del jwt ma si consiglia comunque di applicarla in quanto in ambiente di produzione sarà necessaria,\n    Quanto prima verrà fornita un'interfaccia dalla quale sarà possibile caricare la propria chiave pubblica che verrà utilizzata per tale scopo**\n\n**In ambiente di produzione le chiavi e algoritmi utilizzabili per firmare il jwt sono: `PS256` oppure `ES256`**\n\n\nPer quanto riguarda il valore aud in ambiente di sandbox deve essere valorizzato con la stringa\n`https://core.sandbox-new.flowpay.it/api/openid`\n\nPer l'ambiente di produzione invece è richiesta la stringa\n`https://core.flowpay.it/api`\n\nCome esempio la url comprensiva di tutti i parametri per questo flusso autorizzativo è:\nNotare che gli accapo sono stati aggiunti solo per aumentare la leggibilità\n```\nhttps://core.sandbox-new.flowpay.it/api/openid/authenticate\n?client_id=9a585977-98c1-4f68-a0a5-651a192f7383\n\
    &scope=invoice:read invoice:write openid authorization_intent\n&response_type=code\n&redirect_uri=https://ex.amp.le/redirect\n&state=123456789\n&request=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjEyMzQ1Njc4In0.eyJpc3MiOiI5YTU4NTk3Ny05OGMxLTRmNjgtYTBhNS02NTFhMTkyZjczODMiLCJhdWQiOiJodHRwczovL2NvcmUuc2FuZGJveC1uZXcuZmxvd3BheS5pdC9hcGkvb3BlbmlkIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9leC5hbXAubGUvcmVkaXJlY3QiLCJjbGllbnRfaWQiOiI5YTU4NTk3Ny05OGMxLTRmNjgtYTBhNS02NTFhMTkyZjczODMiLCJzdGF0ZSI6IjEyMzQ1Njc4OSIsInNjb3BlIjoiaW52b2ljZTpyZWFkIGludm9pY2U6d3JpdGUgb3BlbmlkIGF1dGhvcml6YXRpb25faW50ZW50IiwicmVzcG9uc2VfdHlwZSI6ImNvZGUiLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsiYWNjb3VudF9hY2Nlc3NfaW50ZW50Ijp7InZhbHVlIjoiNjlFQTI0OTYtQjJEMS00RDI5LUJFMjItOUM5M0YyRkUxNjk5IiwiZXNzZW50aWFsIjp0cnVlfX19fQ.P0Pqeho32esd2crpw2q-AZoSlIPlZ5xy6w6e7GMBIznAB4ohcYIOquZGNC3f-IwXBGcJow-ZvCH7A6jiYKRLHA\n```\n\nA questo punto il flusso rientra nel già documentato flusso di autenticazione.\nIl token ottenuto alla fine di tale flusso potrà essere\
    \ speso per effettuare le chiamate relative agli account\n\n\n# Refresh di un Token\n\nIl refresh token viene dato insieme all'access token in caso di grant_type authorization_code.\n\nNel momento in cui l'access token scade si può richiedere un nuovo access token con il refresh token.\n\nLa chiamata da effettuare in questo caso è simile alla chiamata per ottenere l'access token con le proprie client_credentials:\n\n```\nPOST https://core.sandbox-new.flowpay.it/api/oauth/token\n```\n\ncon content-type `application/x-www-form-urlencoded`\n\n\n| nome | descrizione | esempio |\n|------|-------------|---------|\n| client_id | client ID fornito (il client id è un valore pubblico) | 9a585977-98c1-4f68-a0a5-651a192f7383 |\n| grant_type | Tipo di autenticazione fornita nella richiesta (in questo caso token di refresh) | refresh_token |\n| client_secret | vostro client secret fornito in fase di registrazione | client-secret |\n| refresh_token | Refresh token che vogliamo utilizzare | 1234567890-refresh-1234567890\
    \ |\n\n\nesempio di risposta\n\n```json\n    {\n        \"access_token\": \"0987654321-token-0987654321\",\n        \"token_type\": \"bearer\",\n        \"expires_in\": 3600,\n        \"refresh_token\": \"0987654321-refresh-0987654321\"\n    }\n```\n\nLa risposta conterrà un nuovo access token ed un nuovo refresh token, **il refresh token appena utilizzato non è più valido. Ma è stato sostituito dal nuovo refresh token, ritornato in questo momento**.\n\n\n\n\n## Push Authorization Request\n\n**Questo endpoint è in fase di sviluppo, ma già utilizzabile in ambiente di sandbox**\n\nPer il flusso autorizzativo `authorization_code` è disponibile l'endpoint di par dove è possibile inviare i dati autorizzativi come post per poi essere successivamente utilizzati\nin una richiesta autorizzativa.\n\nL'endpoint di par è conforme alla sua [RFC](https://datatracker.ietf.org/doc/html/rfc9126).\n\nL'endpoint è disponibile al seguente url in produzione: `https://core.flowpay.it/api/oauth/par`\n\nAccetta\
    \ richieste POST con content-type `application/x-www-form-urlencoded` e permette di inviare gli stessi dati che verrebbero inviati in una richiesta di autorizzazione.\nPer i client confidenziali è necessario inviare anche le proprie credenziali in particolare è necessario inviare il parametro `client_secret`\nLa risposta di tale endpoint è nel seguente formato\n\n```\n{\n    \"request_uri\": \"urn:abc:def:123456789\",\n    \"expires_in\": 60\n}\n```\nLa risposta contiene il campo expires_in che indica per quanto tempo il request_uri è valido.\nIl campo `request_uri` invece contiene un url che deve essere utilizzata per effettuare la richiesta di autorizzazione inviandola nel parametro `request_uri` della richiesta autorizzativa.\nTale `request_uri` è valida per un tempo limitato e monouso.\n\n### Esempio\n\nEseguendo la chiamata:\n\n```\nPOST https://core.sandbox-new.flowpay.it/api/oauth/par\nContent-Type: application/x-www-form-urlencoded\nclient_id=12345-6789&\nclient_secret=client-secret&\n\
    scope=invoice:read&\nredirect_uri=https://ex.amp.le/redirect\n```\n\nRiceviamo la risposta:\n\n```\n{\n    \"request_uri\": \"urn:abc:def:123456789\",\n    \"expires_in\": 60\n}\n```\n\nIl `request_uri` ricevuto viene poi utilizzato per comporre la richiesta di autorizzazione:\n\n```\nGET https://core.sandbox-new.flowpay.it/api/openid/authenticate?\nrequest_uri=urn:abc:def:123456789&\nresponse_type=code\n```\n\nIn questo caso la richiesta completa di autorizzazione viene composta con i seguenti parametri:\n\n```\nclient_id=12345-6789\nscope=invoice:read\nredirect_uri=https://ex.amp.le/redirect\nresponse_type=code\n```\n\nche sono sufficienti per effettuare la richiesta di autorizzazione. Se nella get non fosse stato passato oltre al `request_uri` anche il parametro `response_type` allora la richiesta di autorizzazione avrebbe restituito l'errore:\n`missing required parameter 'response_type'`\n\nQuesto endpoint non va a sostituire nessuna delle funzionalità dell'endpoint di autenticazione,\
    \ ma da agli integratori maggiore possibilità di scegliere come meglio gestire i flussi autorizzativi.\n\n### Request e Request uri\n\nIl parametro `request` e `request_uri` sono mutualmente esclusivi e non possono essere utilizzati insieme.\nNel caso si voglia utilizzare una delle funzionalità del campo `request` è possibile inviare il parametro `request` all'endpoint di par. e poi utilizzare il parametro `request_uri` per effettuare la richiesta di autorizzazione.\n\nSe il campo `request` viene inviato all'endpoint di par è possibile omettere il resto dei campi per la richiesta di autorizzazione a patto che il parametro `request` contenga abbastanza informazioni per comporre la richiesta autorizzativa.\n\n\n# Estensioni\n\n\n\n\n## Estensioni OpenID\n\nDurante il flusso autorizzativo è possibile attivare delle estensioni del protocollo OpenID. La prima è già stata documentata e si tratta della estensione per richiedere l'accesso ai conti dell'utente.\n\n\n\n\n### Richiesta esplicita\
    \ di accesso\n\nPer i client che volessero dare agli utenti delle proprie piattaforme un meccanismo di collegamento dell'account FlowPay con meno frizioni possibili è possibile\nutilizzare le seguenti estensioni OpenID. Per l'attivazione di tali estensioni è necessario richiedere esplicitamente questa funzionalità, nel caso non ci sia già una via diretta di comunicazione è possibile [contattarci direttamente](mailto:support@flowpay.it)\n\n### Comunicazione dei dati dell'azienda durante l'accesso\n\nL'estensione OpenID in questo caso permette di comunicare i dati dell'azienda e dell'utente per il quale il client sta richiedendo l'accesso.\nIn questo modo nel caso l'azienda che deve concedere l'autorizzazione non sia già registrata a FlowPay potrà registrarsi utilizzando i dati comunicati dal client.\n\nTale estensione prevede di inviare i dati dell'azienda o del consumer nel jwt del campo `request` della richiesta di autorizzazione.\nIn particolare il campo `claims` del jwt deve contenere\
    \ i seguenti campi per richiedere l'attivazione di tale estensione nel processo autorizzativo.\n\n```json\n{\n    ...\n    \"claims\": {\n        \"userinfo\": {\n            \"business\": { //Si richiede che l'azienda che concede l'autorizzazione rispetti i seguenti requisiti\n                \"value\": {\n                    \"name\": \"Nome Azienda\", //Denominazione dell'azienda\n                    \"vat_code\": \"00000000001\", //Vat code dell'azienda (senza prefisso)\n                    \"vat_country_id\": \"IT\", //Codice nazione dell'azienda\n                    \"certified_email\": \"azienda@pec.com\", //Email certificata dell'azienda\n                    //I seguenti campi sono opzionali\n                    \"email\": \"email@email.com\", //Email di contatto dell'azienda\n                    \"address\": \"via Roma, 1\" //Indirizzo dell'azienda\n                },\n                \"essential\": true\n            },\n            \"user\": {\n                \"value\": {\n\
    \                    \"name\": \"Mario\",\n                    \"surname\": \"Rossi\",\n                    //I seguenti campi sono opzionali\n                    \"vat_code\": \"RSSMRA22A01D612M\", //Codice fiscale dell'utente\n                    \"email\": \"email@email.com\", //Email dell'utente\n                    \"phone_number\": \"+39 123 456 789\", //Numero di telefono dell'utente\n                    \"address\": \"via Roma, 1\" //Indirizzo dell'utente\n                }\n            }\n        }\n    }\n```\n\nPer l'onboarding degli utenti consumer, è necessario valorizzare il campo `tenant_type=consumer` nei parametri query del link oauth, inoltre è necessario aggiungere lo scope `consumer`.\nPer gli utenti consumer il jwt deve contenere:\n\n```json\n{\n    ...\n    \"claims\": {\n        \"userinfo\": {\n            \"consumer\": {\n                \"value\": {\n                    \"name\": \"Mario\",\n                    \"surname\": \"Rossi\",\n                    \"\
    vat_code\": \"RSSMRA22A01D612M\", //Codice fiscale dell'utente\n                    //I seguenti campi sono opzionali\n                    \"email\": \"email@email.com\", //Email dell'utente\n                    \"phone_number\": \"+39 123456789\", //Numero di telefono dell'utente\n                    \"address\": \"via Roma 1, Firenze, Italia\" //Indirizzo dell'utente\n                },\n                \"essential\": true\n            }\n        }\n    }\n```\n\n\n\n## Account Statement\n\nPer casi d'uso dove la terza parte voglia che l'utente attesti l'accesso ad uno o più conti, è possibile utilizzare l'estensione di Account Statement.\nQuesta estensione consente di richiedere, in fase di autorizzazione, che l'utente abbia l'accesso ad uno o più conti indicati dalla terza parte.\n\nIn questo modo la terza parte è in grado di richiedere un servizio equivalente al check iban.\n\nL'account statement è un custom claim che quindi deve essere inviato all'interno del jwt del campo `request`\
    \ della richiesta di autenticazione.\nIl formato del custom claim è\n\nNel caso di singolo conto:\n```\n{\n...\n    \"claims\": {\n        \"id_token\": {\n            \"account_statement\": {\n                \"value\": \"IT43M0300203280178858532758\",\n                \"essential\": true\n            }\n        }\n    }\n...\n}\n```\n\nNel caso di attestazione su più conti:\n```\n{\n...\n    \"claims\": {\n        \"id_token\": {\n            \"account_statement\": {\n                \"values\": [\"IT43M0300203280178858532758\", \"IT56E0300203280397756918554\"],\n                \"essential\": true\n            }\n        }\n    }\n...\n}\n```\n\nPer attivare questa estensione all'interno degli scope richiesti deve essere presente lo scope `openid`.\n\nLa risposta a questo tipo di richiesta di autorizzazione comprenderà un `id_token` firmato da FlowPay al cui interno sarà compreso un campo `account_statement` dove vengono inseriti gli account verificati dall'utente.\n\nEsempio:\n\n\
    ```\n{\n...\n    \"account_statement\": [\n        {\n        \"bankID\": \"flowpay_bank\",\n        \"iban\": \"IT43M0300203280178858532758\"\n        },\n        {\n        \"bankID\": \"flowpay_bank\",\n        \"iban\": \"IT56E0300203280397756918554\"\n        }\n    ],\n...\n}\n```\n\nBasterà verificare l'autenticità dell'`id_token` con i classici metodi di verifica tra cui verifica dell'autenticità della firma e valori `iat` e `exp` conformi.\n\nL'`id_token` viene restituito a seconda del tipo di `response_type` richiesto secondo le normali specifiche OpenID.\n\nIn particolare:\n* nel caso di risposta `id_token` l'id_token viene inviato direttamente durante la redirezione verso la url di risposta.\n* nel caso di risposta `code` l'id_token viene inviato in risposta all'ottenimento dell'access token in un ulteriore campo della risposta `id_token`.\n* nel caso di risposta `code id_token` viene inviato sia nei query params sia a seguito dell'ottenimento dell'access token.\n\n### Spiegazione\
    \ ad alto livello\nRichiedendo questa estensione il processo di autorizzazione renderà esplicito che la terza parte sta richiedendo che l'utente attesti che tali conti gli appartengano.\nNel caso i conti inviati dalla terza parte siano già stati collegati precedentemente dall'utente sarà sufficiente che l'utente autorizzi a condividere tali informazioni alla terza parte.\nPer i conti invece non collegati all'utente, sarà necessario che prima colleghi tali conti a FlowPay (e quindi che provi l'effettivo possesso di essi) per poter soddisfare la richiesta della terza parte.\n\n\n# Webhooks\n\nIn fase sperimentale e soggetta a breaking changes.\n\n\n\n\n## Creazione di un webhook\n\nGli endpoint di webhook permettono di attivare uno o più webhook per un determinato evento, avendo gli scope necessari per farlo.\n\nAd esempio per ricevere la notifica per l'evento **nuovo pagamento per una fattura** è necessario avere gli scope `invoice:read` e `payment:read`\n\nPer ciascun tipo di webhook\
    \ sono definiti gli scope necessari per la sua attivazione.\n\nL'endpoint di attivazione di un webhook in produzione non permette di specificare un webhook che non utilizzi https.\n\n\n\n## Eventi WebHook\n\nL'endpoint di webhook permette di ottenere la lista dei webhook che possono essere attivati, ma forniamo anche qua la lista degli stessi eventi.\n\n* **nuovo pagamento per una fattura**: Nel momento in cui viene autorizzato il pagamento di un termine di pagamento relativo ad una fattura.\n* **nuovo pagamento per un salario**: Nel momento in cui viene autorizzato il pagamento di un termine di pagamento relativo ad un salario.\n* **nuovo pagamento per una ricevuta**: Nel momento in cui viene autorizzato il pagamento di un termine di pagamento relativo ad una ricevuta.\n* **un pagamento cambia stato**: Nel momento in cui un pagamento cambia stato rispetto allo stato precedente.\n\n\n\n## Attivazione di un webhook\n\nPer ciascun webhook creato, deve essere anche impostato un periodo\
    \ di interesse. L'interesse è il periodo di tempo per il quale il webhook rimane attivo.\nNon può superare il mese di tempo, ma è sempre possibile rinnovare il periodo di interesse.\n\nQuesto permette di non sovraccaricare il sistema FlowPay con webhook non più attivi.\n\n\n### Disattivazione di un webhook\n\nSi fa presente che un webhook può essere disattivato contattando il relativo endpoint, ma è anche disattivato nel caso di revoca del token utilizzato per la\ncreazione del webhook, sia che il token venga revocato dall'utente oppure dall'applicazione.\n\n\n\n### Revoca di un token utilizzato per un webhook\n\nNel caso un token utilizzato per creare un webhook venga revocato, i webhook collegati a tale token vengono eliminati. Nel momento in cui vengono eliminati viene effettuata una ultima chiamata verso la url del webhook per indicare la sua disattivazione.\nIl formato della chiamata è il seguente:\n\nmetodo: DELETE\n\nbody:\n\n| parametro | tipo | descrizione |\n| --------- | ----\
    \ | ----------- |\n| `event` | string | Nome dell'evento per il quale è stato disattivato il webhook |\n| `tenantID` | string | ID dell'azienda per il quale è stato disattivato il webhook |\n| `webhookID` | string | ID del webhook per il quale è stato disattivato il webhook |\n\n\n\n## Funzionamento di un WebHook\n\nI WebHook vengono eseguiti con chiamate POST al link ricevuto.\n\nIl content-type della richiesta è `application/json`.\n\nInoltre per permettere al client di verificare la validità della richiesta vengono inclusi due header\n* `X-FlowPay-Timestamp` che contiene il timestamp della richiesta come secondi dal 1/1/1970\n* `X-FlowPay-Raw-Signature` e `X-FlowPay-Der-Signature` che contengono la firma della richiesta.\n\nUn webhook viene considerato consegnato quando la risposta alla richiesta fornisce una risposta con status code 200.\n\nIn tutti gli altri casi viene considerato che il webhook abbia fallito ad essere consegnato.\n\nAttraverso questi due headers è possibile verificare\
    \ che la richiesta sia stata inviata da FlowPay.\n\nI webhook per motivi di sicurezza hanno delle policy restrittive sui tempi di esecuzione.\n\nQuindi è necessario che l'endpoint contattato risponda entro un massimo di 10 secondi.\n\nInoltre in ambiente di produzione, il sistema FlowPay controlla il certificato del server al quale la richiesta viene inviata, quindi non è possibile utilizzare dei certificati self signed in quanto la loro verifica fallirà.\n\nIl webhook in caso di errore verrà riprovato automaticamente più volte fino ad massimo numero di tentativi ad intervalli di tempo casuali con un backup esponenziale\n\n\n## Scadenza di un webhook\n\nUn webhook come già specificato, ha una scadenza, dopo che il webhook è scaduto, non verrà più contattato dal sistema FlowPay.\nPer evitare discontinuità di servizio, si invita ad implementare politiche di refresh del webhook.\n\nPer aiutare in questo compito, il sistema FlowPay effettua esso stesso una chiamata ad ogni webhook la cui\
    \ data di scadenza sia inferiore ad un giorno.\n\nLa chiamata a differenza della richiesta normale, è una chiamata GET. Senza body. Viene firmata come le altre richieste, in questo caso la stringa che genera la firma è:\n`timestamp + '.'`\n\nSe la risposta che FlowPay si aspetta è una risposta con status code 201 (created).\nCon content-type `application/json`:\n\n| parametro | tipo | descrizione |\n| -------- | ---- | ----------- |\n| `expiresAt` | `string` | nuova data di scadenza del webhook in formato ISO 8601 (yyyy-MM-ddTHH:mm:SSZ), (MAX 1 mese rispetto alla chiamata) |\n\nIn questo caso il sistema FlowPay aggiorna la data di scadenza del webhook.\n\nCon qualunque altro tipo di risposta il sistema

# --- truncated at 32 KB (359 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bancomat/refs/heads/main/openapi/bancomat-flowpay-api-v1-openapi.yml