openapi: 3.2.0 info: contact: email: federico.giuntoli@flowpay.it name: Federico Giuntoli description: Hai uno use case di pagamento complesso come pagamenti massivi, split o pagopa? termsOfService: https://www.flowpay.it/tos title: FlowPay Sessioni di checkout API version: 1.0.0 servers: - url: https://app.flowpay.it/api variables: {} tags: - description: 'Gestione e creazione di un codici di checkout Il codice di checkout permette di far pagare un documento caricato su FlowPay attraverso il nostro flusso di checkout. Il flusso per il checkout passa dall''ottenere il codice di checkout e redirezionare il proprio utente verso la pagina * `https://checkout.flowpay.it/{code}` in produzione * `https://checkout.sandbox-new.flowpay.it/{code}` in sandbox' name: Sessioni di checkout paths: /{tenantID}/checkout: post: description: 'Crea un codice di checkout per il documento identificato da tipo e fingerprint. Nel caso un codice sia già stato creato per il documento, viene restituito un errore.' parameters: - description: ID dell'owner della richiesta example: 84461172-4326-4D6B-AEA7-840ED1372200 in: path name: tenantID required: true schema: example: 84461172-4326-4D6B-AEA7-840ED1372200 format: uuid type: string requestBody: content: application/vnd.api+json; charset=utf-8: example: fingerprint: d41d8cd98f00b204e9800998ecf8427e nokRedirect: https://www.google.com/search?q=nok okRedirect: https://www.google.com/search?q=ok type: invoice schema: $ref: '#/components/schemas/CheckoutRequest' required: true responses: '201': content: application/json; charset=utf-8: example: code: hello expire: null schema: $ref: '#/components/schemas/CheckoutResponse' description: '' '400': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è corretta sintatticamente, body, headers, path o query params non conformi alla documentazione '401': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: Le credenziali fornite non sono sufficienti a completare la richiesta '403': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è autorizzata a procedere con le credenziali fornite '404': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta fa riferimento ad una risorsa inesistente '417': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è corretta semanticamente security: - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyAuthorizationCode: - transfer:write - ThirdPartyAuthorizationCode: - transfer:write - ThirdPartyAuthorizationCode: - transfer:write - ThirdPartyAuthorizationCode: - transfer:write summary: Create by tenant id checkout tags: - Sessioni di checkout x-summary-source: derived operationId: postByTenantIDCheckout x-operation-id-source: derived /{tenantID}/checkout/intents: post: description: '' parameters: - description: ID dell'owner della richiesta example: 84461172-4326-4D6B-AEA7-840ED1372200 in: path name: tenantID required: true schema: example: 84461172-4326-4D6B-AEA7-840ED1372200 format: uuid type: string responses: '201': content: application/json; charset=utf-8: {} description: '' '400': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è corretta sintatticamente, body, headers, path o query params non conformi alla documentazione '401': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: Le credenziali fornite non sono sufficienti a completare la richiesta '403': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è autorizzata a procedere con le credenziali fornite '404': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta fa riferimento ad una risorsa inesistente '417': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è corretta semanticamente security: - ThirdPartyClientCredential: - transfer:write - payment:read - ThirdPartyClientCredential: - transfer:write - payment:read - ThirdPartyClientCredential: - transfer:write - payment:read summary: Create by tenant id checkout intents tags: - Sessioni di checkout x-summary-source: derived operationId: postByTenantIDCheckoutIntents x-operation-id-source: derived /{tenantID}/checkout/{code}: delete: description: Elimina un checkout esistente. parameters: - description: ID dell'owner della richiesta example: 84461172-4326-4D6B-AEA7-840ED1372200 in: path name: tenantID required: true schema: example: 84461172-4326-4D6B-AEA7-840ED1372200 format: uuid type: string - description: code example: LjJ5imbL in: path name: code required: true schema: example: LjJ5imbL type: string responses: '200': content: application/json; charset=utf-8: {} description: '' '400': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è corretta sintatticamente, body, headers, path o query params non conformi alla documentazione '401': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: Le credenziali fornite non sono sufficienti a completare la richiesta '403': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è autorizzata a procedere con le credenziali fornite '404': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta fa riferimento ad una risorsa inesistente '417': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è corretta semanticamente security: - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyAuthorizationCode: - transfer:write - ThirdPartyAuthorizationCode: - transfer:write - ThirdPartyAuthorizationCode: - transfer:write summary: Delete by tenant id checkout by code tags: - Sessioni di checkout x-summary-source: derived operationId: deleteByTenantIDCheckoutByCode x-operation-id-source: derived /{tenantID}/checkout/{code}/preferences: put: summary: Update checkout preferences description: This endpoint allows to update a checkout preferences specifying the code. security: - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyAuthorizationCode: - transfer:write - ThirdPartyAuthorizationCode: - transfer:write - ThirdPartyAuthorizationCode: - transfer:write parameters: - description: ID dell'owner della richiesta example: 84461172-4326-4D6B-AEA7-840ED1372200 in: path name: tenantID required: true schema: example: 84461172-4326-4D6B-AEA7-840ED1372200 format: uuid type: string - description: Checkout code example: LjJ5imbL in: path name: code required: true schema: example: LjJ5imbL type: string requestBody: content: application/vnd.api+json; charset=utf-8: example: allowedMethods: - sct - sctInst schema: $ref: '#/components/schemas/CheckoutPreferences' required: true responses: '200': description: Checkout details content: application/json: schema: $ref: '#/components/schemas/CheckoutPreferencesResponse' '400': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è corretta sintatticamente, body, headers, path o query params non conformi alla documentazione '401': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: Le credenziali fornite non sono sufficienti a completare la richiesta '403': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è autorizzata a procedere con le credenziali fornite '404': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta fa riferimento ad una risorsa inesistente '417': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è corretta semanticamente tags: - Sessioni di checkout operationId: putByTenantIDCheckoutByCodePreferences x-operation-id-source: derived /{tenantID}/checkout/{type}/{fingerprint}: get: description: Restituisce le informazioni sullo stato del checkout identificato da tipo e fingerprint. parameters: - description: ID dell'owner della richiesta example: 84461172-4326-4D6B-AEA7-840ED1372200 in: path name: tenantID required: true schema: example: 84461172-4326-4D6B-AEA7-840ED1372200 format: uuid type: string - description: tipo di documento example: invoice in: path name: type required: true schema: example: invoice format: enum('invoice, 'bill') type: string - description: Identificativo univoco della fattura definito come HEX SHA256 di [numero][anno][partita_iva_mittente] example: '[1][2021][06968160488] -> fe92051fc0d735f31f6e85ae8515838e6540ba994ede74c5cb2f19599e723d49' in: path name: fingerprint required: true schema: example: '[1][2021][06968160488] -> fe92051fc0d735f31f6e85ae8515838e6540ba994ede74c5cb2f19599e723d49' type: string responses: '200': content: application/json; charset=utf-8: example: code: hello expire: null schema: $ref: '#/components/schemas/GetCheckoutResponse' description: '' '400': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è corretta sintatticamente, body, headers, path o query params non conformi alla documentazione '401': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: Le credenziali fornite non sono sufficienti a completare la richiesta '403': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è autorizzata a procedere con le credenziali fornite '404': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta fa riferimento ad una risorsa inesistente '417': content: application/json; charset=utf-8: example: code: 12345678 errorDescription: hello errorURI: null expectedType: null field: null requestID: null service: 12345678 statusCode: 12345678 schema: $ref: '#/components/schemas/ErrorDTO' description: La richiesta non è corretta semanticamente security: - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyClientCredential: - pagopa - ThirdPartyAuthorizationCode: - transfer:read - ThirdPartyAuthorizationCode: - transfer:read - ThirdPartyAuthorizationCode: - transfer:read - ThirdPartyAuthorizationCode: - transfer:read summary: Get by tenant id checkout by type by fingerprint tags: - Sessioni di checkout x-summary-source: derived operationId: getByTenantIDCheckoutByTypeByFingerprint x-operation-id-source: derived components: schemas: CheckoutResponse: properties: code: description: Codice univoco del checkout example: LjJ5imbL type: string expire: description: Data di scadenza del codice di checkout example: '2020-03-03T17:32:28Z' format: date-time type: string payments: items: $ref: '#/components/schemas/PaymentDTO' type: array required: - code - expire - payments type: object CheckoutPreferencesResponse: type: object properties: strict: type: boolean default: false allowedMethods: description: Lista di metodi di pagamento che il debitore puó selezionare, in caso non sia stato indicato un metodo di pagamento specifico type: array items: $ref: '#/components/schemas/CollectionMethodEnum' default: - sct - sctInst - card - ssd canEditRemittance: type: boolean default: true required: - strict - allowedMethods - canEditRemittance CollectionMethodEnum: type: string enum: - sct - sctInst - card - ssd GetCheckoutResponse: properties: code: description: Codice univoco del checkout example: LjJ5imbL type: string expire: description: Data di scadenza del codice di checkout example: '2020-03-03T17:32:28Z' format: date-time type: string required: - code type: object CheckoutPreferences: type: object properties: strict: type: boolean default: false terms: type: array items: type: string format: uuid paymentMethodID: type: string format: uuid connectorMethodID: type: string format: uuid allowedMethods: description: Lista di metodi di pagamento che il debitore puó selezionare, in caso non sia stato indicato un metodo di pagamento specifico type: array items: $ref: '#/components/schemas/CollectionMethodEnum' default: - sct - sctInst - card - ssd canEditRemittance: type: boolean default: true required: - allowedMethods DocumentType: description: Tipo di documento del checkout enum: - invoice - bill type: string CheckoutRequest: properties: fingerprint: description: Fingerprint del documento per il quale si sta creando il checkout example: d41d8cd98f00b204e9800998ecf8427e type: string nokRedirect: description: 'URL di reindirizzamento in caso di checkout fallito. Poiché questa URL deve essere pubblica e raggiungibile dal browser dell''utente si consiglia di inserire al suo interno qualcosa che possa provare la correttezza del redirect. Ad esempio un jwt firmato dall''integratore con al suo interno un id univoco riconoscibile nel momento del redirect.' example: https://www.google.com/search?q=nok type: string okRedirect: description: 'URL di reindirizzamento in caso di checkout andato a buon fine. Poiché questa URL deve essere pubblica e raggiungibile dal browser dell''utente si consiglia di inserire al suo interno qualcosa che possa provare la correttezza del redirect. Ad esempio un jwt firmato dall''integratore con al suo interno un id univoco riconoscibile nel momento del redirect.' example: https://www.google.com/search?q=ok type: string type: $ref: '#/components/schemas/DocumentType' required: - type - fingerprint type: object PaymentMethodInfo: enum: - card type: string PaymentStatusEnum: description: "Stato di un pagamento:\n * `concluded` - Indica che il pagamento è stato addebitato sul conto del debitore\n * `not_concluded` - Indica che il pagamento è stato autorizzato ma ancora non è stato addebitato (ad esempio per un pagamento a data futura)\n * `rejected` - Indica che il pagamento è stato rifiutato (ad esempio il pagamento è stato annullato dal debitore oppure non erano presenti i fondi nel momento di eseguire il pagamento)\n * `not_available` - Indica che è avvenuto un errore di comunicazione con la banca per controllare lo stato del pagamento, riprovando dovrebbe risolversi\n * `outside_flowpay_creditor` - Indica che il pagamento non è avvenuto attraverso il sistema FlowPay, e l'azione di indicare tale pagamento come avvenuto all'esterno di FlowPay è stata fatta dal creditore\n * `outside_flowpay_debtor` - Indica che il pagamento non è avvenuto attraverso il sistema FlowPay, e l'azione di indicare tale pagamento come avvenuto all'esterno di FlowPay è stata fatta dal debitore\n\nGli stati `concluded`, `rejected`, `outside_flowpay_creditor`, `outside_flowpay_debtor` sono stati finali per un pagamento" enum: - concluded - not_concluded - rejected - not_available - outsideFlowPay - outside_flowpay_creditor - outside_flowpay_debtor - forwarded type: string ErrorDTO: description: "Formato errore standard\n \nLista dei possibili codici di errore:\n\n| codice | descrizione |\n| ------ | ----------- |\n| 401 | Errore generale di codifica |\n| 402 | Campo necessario mancante |\n| 403 | Valore di un campo del tipo sbagliato |\n| 404 | Valore di un campo assente |\n| 405 | Errore di codifica sconosciuto |\n| 406 | Null pointer exception |\n| 407 | Campo necessario mancante |\n| 408 | Errore di connessione |\n| 409 | Errore di input output |\n| 410 - 428 | Errore generico con il database |\n| 429, 432, 433 | Errore di logica con il database |\n| 430 | Campo invalido |\n| 431 | Campo assente |\n| 434 | Risultati non trovati |\n| 500 | Errore generico |\n| 2000 | Tenant non specificato |\n| 2001 | Non autorizzato ad operare su questa risorsa |\n| 2002 | Impossibile eliminare il documento poiché sono presente dei pagamenti collegati |\n| 2003 | Non autorizzato a creare la risorsa |\n| 2004 | Non autorizzato ad operare su questa risorsa |\n| 2005 | Si sta provando a modificare un termine non di questo documento |\n| 2006 | Codice istant scaduto |\n| 2007 | Non autorizzato generare un codice instant |\n| 2008 | Codice instant inesistente o non autorizzato a leggerlo |\n| 2012 | Si sta provando a caricare un documento già esistente |\n| 3001 | Tenant non specificato |\n| 4001 | Tenant non specificato |\n| 5001 | Corpo richiesta mancante |\n| 5002 | Corpo richiesta non valido |\n| 5003 | Vatcode del ricevente fattura mancante |\n| 6001 | Tenant non specificato |\n| 6002 | Ricevuta non trovata |\n| 8005 | Non puoi modificare questo conto |\n| 8010 | Troppi risultati ottenuti |\n| 11001 | Non autorizzato ad accedere a questa risorsa |\n| 11002 | Si sta provando a caricare un documento già esistente |\n| 13001 | Azienda non trovata |\n| 13003 | vatcode non è valido |" properties: code: description: Codice errore example: '12345678' format: int64 type: integer errorDescription: description: Descrizione errore example: string type: string errorURI: description: URI dell'errore se presente example: string type: string expectedType: description: Nel caso di un errore di codifica indica il tipo di dato che non si è riuscito a decodificare example: string type: string field: description: Nel caso di un errore di codifica indica il campo che non si è riuscito a decodificare example: string type: string requestID: description: ID della richiesta da comunicare per poter fornire un supporto example: string type: string service: description: ID interno del servizio example: '12345678' format: int64 type: integer statusCode: description: Codice di stato HTTP example: '12345678' format: int64 type: integer required: - service - code - errorDescription - statusCode type: object PaymentDTO: properties: createdAt: description: Data di creazione del pagamento, corrisponde al momento in cui il pagamento è stato autorizzato dal debitore example: '2020-03-03T17:32:28Z' format: date-time type: string creditor: description: Codice fiscale del creditore (vat code in caso di azienda, codice fiscale in caso di privato) example: string type: string debtor: description: Codice fiscale del debitore (vat code in caso di azienda, codice fiscale in caso di privato) example: string type: string debtorIban: example: string type: string fingerprint: description: fingerprint del documento per il quale è stato creato il pagamento example: d41d8cd98f00b204e9800998ecf8427e type: string identifier: description: ID univoco del pagamento example: cb15b52a-91db-41ed-81a0-764a0cc4795d format: uuid type: string method: $ref: '#/components/schemas/PaymentMethodInfo' status: $ref: '#/components/schemas/PaymentStatusEnum' terms: items: description: ID univoco del termine di pagamento del documento al quale questo pagamento si riferisce example: cb15b52a-91db-41ed-81a0-764a0cc4795d format: uuid type: string type: array type: description: Tipo di documento per il quale è stato creato il pagamento example: string type: string required: - identifier - fingerprint - terms - creditor - debtor - status - method type: object securitySchemes: ThirdPartyAuthorizationCode: description: Autorizzazione oauth ottenuta da terze parti con un authorization flow flows: authorizationCode: authorizationUrl: https://core.flowpay.it/api/openid/authenticate refreshUrl: https://core.flowpay.it/api/oauth/token scopes: account:read: Operazioni di lettura sui conti bill:write: Creazione e gestione di ricevute business:read: Operazioni di lettura sulle informazioni della azienda contacts:read: Operazioni di lettura sulla rete aziendale invoice:read: Operazioni di lettura sulle fatture invoice:write: Operazioni di scrittura sulle fatture payment:read: Operazioni di lettura sui pagamenti salary:read: Operazioni di lettura sulle buste paga salary:write: Operazioni di scrittura sui salary statistic:read: Lettura dei dati statistici raggruppati transfer:read: Operazioni di lettura sui trasferimenti transfer:write: Operazioni di scrittura sui trasferimenti tokenUrl: https://core.flowpay.it/api/oauth/token type: oauth2 ThirdPartyClientCredential: description: Autorizzazione oauth ottenuta da terze parti con client credential flow flows: clientCredentials: refreshUrl: https://core.flowpay.it/api/oauth/token scopes: account:read: Operazioni di lettura sui conti account:write: Operazione di modifica sui conti authorization_intent: Creazione di intenti a consensi relativi a risorse di un utente bill: Gestione di ricevute business:read: Operazioni di lettura sulle informazioni della azienda invoice:read: Operazioni di lettura sulle fatture invoice:write: Operazioni di scrittura sulle fatture pagopa: '' payment:read: Operazioni di lettura sui pagamenti salary:read: Operazioni di lettura sulle buste paga salary:write: Operazioni di scrittura sui salary statistic:read: Lettura dei dati statistici raggruppati transfer:read: '' transfer:write: '' tokenUrl: https://core.flowpay.it/api/oauth/token type: oauth2