From b349857a7cbe4ad3fb593f5dba8d3903706b678b Mon Sep 17 00:00:00 2001 From: Federico Giuntoli Date: Fri, 18 Apr 2025 11:31:54 +0200 Subject: [PATCH 1/3] Edit fingerprint --- openapi.json | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/openapi.json b/openapi.json index 9c0e061..f741018 100644 --- a/openapi.json +++ b/openapi.json @@ -660,7 +660,9 @@ "Fingerprint": { "type": "string", "description": "Fingerprint of the document", - "example": "d41d8cd98f00b204e9800998ecf8427e" + "maxLength": 64, + "minLength": 64, + "pattern": "\b[a-fA-F0-9]{64}\b" }, "Invoice": { "type": "object", @@ -6459,14 +6461,7 @@ ], "responses": { "204": { - "description": "Transfer document deleted", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } + "description": "Transfer document deleted" }, "400": { "$ref": "#/components/responses/BadRequest" From b0fe8ca502c75f86740f0158f9d437a8e099ac4f Mon Sep 17 00:00:00 2001 From: Federico Giuntoli Date: Tue, 3 Jun 2025 10:35:09 +0200 Subject: [PATCH 2/3] fix: Rename 'fullVat' to 'tin' in schema for clarity --- openapi.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.json b/openapi.json index f741018..b8bb0e5 100644 --- a/openapi.json +++ b/openapi.json @@ -495,7 +495,7 @@ } ] }, - "fullVat": { + "tin": { "type": "string", "description": "VAT number of the company in full european format or national ID of the consumer ", "oneOf": [ From 597b338d7f4ed459e888358f5fae9f64d29b6989 Mon Sep 17 00:00:00 2001 From: Federico Giuntoli Date: Thu, 12 Jun 2025 16:42:37 +0200 Subject: [PATCH 3/3] Aggiunta bozza nuova architettura Co-authored-by: Marco Casaglia --- docs/description_ultimate_debtor.md | 18 + docs/general.md | 68 +- docs/invoice_lifecycle.md | 25 - openapi.json | 7804 ++++++--------------------- redocly.yaml | 47 +- theme/components.html | 57 + theme/darkmode.css | 0 theme/messages.css | 185 + 8 files changed, 1913 insertions(+), 6291 deletions(-) create mode 100644 docs/description_ultimate_debtor.md delete mode 100644 docs/invoice_lifecycle.md create mode 100644 theme/components.html create mode 100644 theme/darkmode.css create mode 100644 theme/messages.css diff --git a/docs/description_ultimate_debtor.md b/docs/description_ultimate_debtor.md new file mode 100644 index 0000000..562a263 --- /dev/null +++ b/docs/description_ultimate_debtor.md @@ -0,0 +1,18 @@ +Determina chi compare come ordinante sul conto o sulla ricevuta. + + + +Nel caso di pagamento PagoPA, questo valore viene utilizzato per generare la ricevuta. + + + +
+
⚠️Attenzione
+
Se diverso da debtor, il pagamento viene dirottato su un conto tecnico e riemesso dopo la ricezione dei fondi.
+
\ No newline at end of file diff --git a/docs/general.md b/docs/general.md index 7f614cb..03129b0 100644 --- a/docs/general.md +++ b/docs/general.md @@ -1,3 +1,7 @@ + + + + [![Run in Postman](https://run.pstmn.io/button.svg)](/postman_collection)


If you can't find what you're looking for, it doesn't mean we can't do it. Write to us and tell us about your idea. @@ -6,7 +10,7 @@ If you can't find what you're looking for, it doesn't mean we can't do it. Write If you have any questions or need help with the APIs, you can open a ticket on our support portal. Click on the button below to open a ticket. - +
@@ -24,9 +28,7 @@ If you have any questions or need help with the APIs, you can open a ticket on o # FlowPay's commitment to the payments ecosystem -FlowPay is both a payment institution and a start-up. - -As a Payment Service Provider (PSP), we are regulated by the Bank of Italy and we are authorised to provide payment services to our customers. As a start-up, we are always looking for new ideas and new ways to improve our services and help you grow your business. +As a Payment Service Provider (PSP), FlowPay is regulated by the Bank of Italy and we are authorised to provide payment services to our customers. We believe that the best API a payment institution can provide is one that is tailored to the payment use case, **allowing customers to focus on their business and not the payment process**. @@ -34,10 +36,7 @@ On the end user side, FlowPay ensures that **users own their data, can access it # Introduction -FlowPay's services compose a multi-tenant platform, where each tenant is a user of FlowPay and can be a legal entity or an individual. -Users can delegate third-party applications, called _clients_, to act on their behalf using the OAuth2 protocol. - -The APIs provided are REST and accessible via HTTPS, some endpoints are protected by the OAuth2, so you need to register your application and obtain a valid access token to use them. +The APIs provided are REST and accessible via HTTPS, some endpoints are restricted, so you need to register your application and obtain a valid access token to use them. ## Account Information Service (AIS) @@ -59,7 +58,6 @@ APIs allow users to initiate any traditional payment type: - Simple account-to-account payment: user can initiate a SEPA Credit Transfer (SCT) payment from one of its bank accounts. - Future date payment: the payer can schedule a payment for a future date. -- Recurring payment: the payer can schedule a recurring payment with a fixed frequency. In addition, FlowPay extends traditional payment methods by providing value-added services such as @@ -67,12 +65,10 @@ In addition, FlowPay extends traditional payment methods by providing value-adde - **Payment chain**: user can authorise a payment to be executed when a previous payment has been successfully received. - **Locked payment**: the user can authorise a payment to be executed if a previous payment has been successfully received. The check is performed by the client application that initiated the payment request. -Each of these services uses the FlowPay technical account, but the payment retains the original payer and payee information. +Each of these services uses a FlowPay technical account, but the payment retains the original payer and payee information. # Onboarding -Tenants can share their FlowPay resources with third-party applications by simply granting permission based on the OAuth2 protocol. - A partner who intends to develop an integration to access tenants' data must first register its application and obtain the `client_id` and `client_secret` pair. The developer portal can be reached at https://developer.flowpay.it, to access it's necessary to have a company account registered with FlowPay services. @@ -105,18 +101,15 @@ Within the developer portal access the "Applications" section and press the "+" ## Be enabled as a third-party application -Once the application has been created, it is already enabled for the sandbox environment but is not yet able to act as a third-party application for the production environment. It is however possible to use client credentials to access the APIs for your own tenant in production. +Once the application has been created, it is already enabled for the sandbox environment but is not yet able to act as a third-party application for the production environment. # Sandbox environment -The sandbox is a shared environment where it is possible to test most of the basic flows and functionalities of the APIs, without using real data and accounts. -We enable you to test the authentication as a third party by providing you with two fake businesses, each with a fake bank account and fake account data, so you can test AIS and PIS flows. +#TODO: add sandbox description ## Limitations of the public sandbox environment -The sandbox uses sandbox open banking APIs and doesn't have access to the FlowPay technical account, so some features are not available or are limited. - -Open banking sandbox APIs don't allow us to monitor the status of the payment, so the webhook for the payment status change is not triggered, and the payment status is not updated. +Open banking sandbox APIs don't allow us to monitor the status of the payment, so the callback for the payment status change is not triggered, and the payment status is not updated. In addition, AIS data is not provided by the bank in the sandbox environment, so if you try to complete the AIS flow, you will be able to connect the bank account, but won't receive any balance and transactions data from it. We do however provide fake AIS data on the fake bank accounts that come with the sandbox users. It is not possible to use the bulk payment service, as it requires the FlowPay technical account to be used. @@ -129,38 +122,6 @@ Onboarding users isn't allowed in the sandbox environment also. If you need to test the full functionality of the APIs, you can request a dedicated sandbox environment, and test all the features of the APIs, including the onboarding flow. -# Oauth2 authentication flows - -FlowPay uses the OAuth2 protocol to authenticate third-party applications and users. -Oauth2 is the industry standard for authentication and authorization, and is used by most of the major companies in the world. - -The scopes - -FlowPay supports the following authentication flows: - -## Authorization code flow - -## Client credentials flow - -The Client Credentials grant type is used by clients to obtain an access token outside of the context of a user. - -This is typically used by clients to access resources about themselves rather than to access a user's resources. - -The client makes a request to the token endpoint by sending the following parameters using the "application/x-www-form-urlencoded" format per Appendix B with a character encoding of UTF-8 in the HTTP request entity-body: - -- grant_type - - REQUIRED. Value MUST be set to "client_credentials". -- scope - - OPTIONAL. The scope of the access request as described by Section 3.3. -- client_id - - REQUIRED. The client identifier as described by Section 2.2. -- client_secret - - REQUIRED. The client secret as described by Section 2.3.1. - -## How token works and tenant filtering - -(negli header ) - # Pagination # Rate limits @@ -168,10 +129,3 @@ The client makes a request to the token endpoint by sending the following parame Requests are limited to 100 requests per minute per source IP, if you exceed this limit you will receive a 429 error. There is also a burst limit of 10 requests per second. - -

Tenant

- -

A tenant can be a company or a single person, is identified by a unique identifier (tenant ID ) and owns its data, - for transparency and security reasons each tenant can manage its data via the dedicated Account portal -

diff --git a/docs/invoice_lifecycle.md b/docs/invoice_lifecycle.md deleted file mode 100644 index c8f3f85..0000000 --- a/docs/invoice_lifecycle.md +++ /dev/null @@ -1,25 +0,0 @@ -# Invoice lifecycle - -This endpoint allows you to create, update, and retrieve invoices. It also allows you to manage each step of the invoice lifecycle, from draft to get paid. - -## Invoice - -An invoice is a commercial document that itemizes a transaction between a buyer and a seller. It serves as a request for payment from the seller to the buyer, indicating the products or services provided, their quantities, prices, and any applicable taxes or discounts. Invoices typically include payment terms, such as due dates and accepted payment methods. -Only legal entities can issue invoices. - -In order to work seamlessly with real customers' invoice management, we provide also API to manage proforma and credit notes. - -## Proforma invoice - -A proforma invoice is a preliminary invoice that is issued before the completion of a transaction. It provides an estimate of the costs and terms of a potential sale, allowing the buyer to review and approve them before proceeding. Proforma invoices are often used in international trade to facilitate customs procedures, as they provide a detailed breakdown of the expected costs, including shipping charges, taxes, and duties. They are also used to provide a quote for potential buyers or to seek approval for a budgeted purchase. -In common practice, payments are often collected against proforma invoices and then the final invoice is issued, FlowPay supports this scenario. -Creating a checkout for a proforma invoice is allowed, but it's necessary to provide the final invoice details when it's issued and link it to the original proforma invoice. -Linking a proforma invoice to a paid invoice is also supported, this can be useful to keep track of the entire invoicing process. - -When linked, the invoice replaces previously created proforma checkout and the payment status of each document is updated accordingly. - -## Credit note - -A credit note, also known as a credit memo or credit memo invoice, is a document issued by a seller to a buyer to indicate a reduction in the amount owed. It is essentially a negative invoice that reflects a credit or refund due to various reasons, such as product returns, billing errors, or pricing adjustments. Credit notes help maintain accurate accounting records and allow for the reconciliation of accounts between buyers and sellers. -You can also create a checkout for a credit note to refund the customer, but it's necessary to provide the original invoice and link it to the original invoice. -Linking a credit note to an invoice will automatically update the invoice status and amount due. diff --git a/openapi.json b/openapi.json index b8bb0e5..a4c86b2 100644 --- a/openapi.json +++ b/openapi.json @@ -1,5850 +1,866 @@ { "openapi": "3.1.0", "info": { - "title": "FlowPay API", - "version": "2.0.0-alpha.4", + "title": "Payment Gateway API", + "version": "2.0.0+S", "description": { - "$ref": "docs/general.md" + "$ref": "./docs/general.md" }, - "termsOfService": "https://developer.flowpay.it/tos", "license": { - "name": "FlowPay SRL", - "url": "https://developer.flowpay.it/tos" - }, - "x-logo": { - "url": "https://images.flowpay.it/logo", - "altText": "FlowPay" - }, - "contact": { - "name": "API Support", - "url": "https://developer.flowpay.it", - "email": "api-support@flowpay.it" - }, - "x-json-schema-faker": { - "locale": "it-IT", - "omitNulls": true, - "fillProperties": true, - "reuseProperties": true + "name": "MIT", + "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { - "url": "https://api.flowpay.it/v2", - "description": "Production server (Not implementend)" + "url": "https://api.flowpay.it/v3", + "description": "Server di produzione" + } + ], + "security": [ + { + "basicAuth": [] + } + ], + "tags": [ + { + "name": "Request To Pay", + "description": "Operazioni relative alla creazione e gestione di richieste di pagamento." }, { - "url": "https://mock.flowpay.it/v2", - "description": "Mock server" + "name": "Payment Method", + "description": "Operazioni relative alla gestione dei metodi di pagamento tokenizzati." }, { - "url": "https://sandbox.{customerID}.flowpay.it/v2", - "description": "Customer-assigned sandbox server", - "variables": { - "customerID": { - "default": "00000000-00000000-00000000-00000000", - "description": "Unique customer identifier assigned after contract signature" - } - } + "name": "Payments", + "description": "Operazioni di pagamento generiche come rimborsi e transazioni." + }, + { + "name": "Wallet", + "description": "Operazioni relative al wallet del cliente e gestione dei fondi." }, { - "url": "http://localhost:5002", - "description": "Debug" + "name": "Customers", + "description": "Operazioni relative ai clienti registrati." } ], - "components": { - "securitySchemes": { - "oAuth2": { - "type": "oauth2", - "description": "OAuth2 flow", - "flows": { - "authorizationCode": { - "authorizationUrl": "/openid/authenticate", - "tokenUrl": "/oauth/token", - "refreshUrl": "/oauth/token", - "scopes": { - "accounts:read": "Allow to read accounts", - "accounts:write": "Allow to mediate accounts creation and open banking consent renewal", - "invoices:read": "Allow to read invoices", - "invoices:write": "Allow to create invoices and manage lifecycle", - "bills:read": "Allow to read bills", - "bills:write": "Allow to create bills and manage lifecycle", - "constructions:read": "Allow to read information about construction sites", - "constructions:write": "Allow to create construction sites and manage the lifecycle", - "openid": "Allow to read user profile", - "pagopa:read": "Allow to retrieve users' PagoPA payment notices", - "pagopa:write": "Allow to create PagoPA payment notices", - "transfers:read": "Allow to read transfers", - "transfers:write": "Allow to create transfers and manage lifecycle", - "wallet:`document_type`": "Allow to manage wallet for the specified use case" - } - }, - "clientCredentials": { - "tokenUrl": "/oauth/token", - "scopes": { - "ade": "Allow to interact with Agenzia delle Entrate services", - "accounts:read": "Allow to read accounts", - "accounts:write": "Allow to mediate accounts creation and open banking consent renewal", - "invoices:read": "Allow to read invoices", - "invoices:write": "Allow to create invoices and manage lifecycle", - "bills:read": "Allow to read bills", - "bills:write": "Allow to create bills and manage lifecycle", - "constructions:read": "Allow to read information about construction sites", - "constructions:write": "Allow to create construction sites and manage the lifecycle", - "openid": "Allow to read user profile", - "pagopa:read": "Allow to retrieve users' PagoPA payment notices", - "pagopa:write": "Allow to create PagoPA payment notices", - "transfers:read": "Allow to read transfers", - "transfers:write": "Allow to create transfers and manage lifecycle", - "wallet:`document_type`": "Allow to manage wallet for the specified use case" - } + "paths": { + "/payment-requests": { + "get": { + "summary": "Elenca tutte le richieste di pagamento create", + "description": "Restituisce un elenco paginato di tutte le richieste di pagamento create.", + "operationId": "listPaymentRequests", + "tags": [ + "Request To Pay", + "Payments" + ], + "security": [ + { + "basicAuth": [] } - } - } - }, - "schemas": { - "Address": { - "type": "object", - "properties": { - "city": { - "type": "string", - "description": "Name of the city where the property is located." - }, - "street": { - "type": "string", - "description": "This field contains the name of the street where the property is located. It must include the name with a type (e.g., Avenue, Street, Road, etc.) but not the number or any other information." - }, - "number": { - "type": "string", - "description": "This field refers to the numeric or alphanumeric value assigned to a property on a street." - }, - "unitNumber": { - "type": "string", - "description": "his field is used when a single property has multiple units, such as apartments or office suites. It differentiates one unit from another within the same property." - }, - "postalCode": { - "type": "string", - "description": "Also known as ZIP code (or CAP in Italy)" - }, - "province": { - "type": "string", - "description": "It refers to the name of the state or province where the property is located." + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20 + }, + "description": "Numero massimo di elementi per pagina." }, - "country": { - "type": "string", - "description": "The name of the country where the property is located." + { + "name": "offset", + "in": "query", + "schema": { + "type": "integer", + "default": 0 + }, + "description": "Numero di elementi da saltare." } - }, - "required": [ - "city", - "street", - "postalCode", - "province", - "country" - ] - }, - "Bank": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the bank", - "example": "Intesa Sanpaolo", - "x-faker": "Company.companyName" - }, - "nationalID": { - "type": "string", - "description": "National identifier of the bank", - "example": "03999", - "x-faker": "finance.bic" - }, - "id": { - "type": "string", - "description": "Unique identifier of the bank", - "example": "intesa_sanpaolo" - }, - "countries": { - "type": "array", - "items": { - "type": "string", - "description": "Countries where the bank operates in ISO 3166-1 alpha-2 format", - "example": "IT", - "x-faker": "address.countryCode" - } - }, - "logo": { - "type": "string", - "description": "URL of the bank logo", - "example": "https://flowpayproduction.blob.core.windows.net/img/84036981-d004-40c4-a872-c81dd37e4acc.png", - "x-faker": "image.imageUrl" - }, - "features": { - "type": "object", - "description": "Features supported by the bank", - "properties": { - "futurePayments": { - "type": "boolean", - "description": "True if the bank supports future payments", - "example": true - }, - "sct": { - "type": "array", - "description": "List of SCT payment types supported by the bank", - "items": { - "type": "string", - "enum": [ - "standard", - "instant" - ], - "description": "SCT payment type" - } - }, - "recurringPayments": { - "type": "array", - "description": "List of recurring payment types supported by the bank", - "items": { - "type": "string", - "enum": [ - "monthly", - "everyTwoMonths", - "quarterly", - "semiAnnual", - "daily", - "everyFourMonths", - "weekly", - "everyTwoWeeks", - "annual" - ], - "description": "Recurring payment frequency" + ], + "responses": { + "200": { + "description": "Elenco paginato delle richieste di pagamento.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/PaginatedResult" + }, + { + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PaymentRequest" + } + } + } + } + ] } } } - } - } - }, - "BankAccount": { - "type": "object", - "properties": { - "owner": { - "type": "string", - "format": "uuid", - "description": "Identifier of the owner of the bank account" }, - "iban": { - "type": "string", - "description": "International Bank Account Number", - "x-faker": "finance.iban", - "example": "IT60X0542811101000000123456" - }, - "currencies": { - "type": "array", - "items": { - "type": "string", - "description": "Currencies supported by the bank account", - "x-faker": "finance.currencyCode" - }, - "example": [ - "EUR", - "CHF", - "GBP" - ] - }, - "bankName": { - "type": "string", - "description": "Identifier of the bank", - "example": "intesa_sanpaolo" - }, - "owners": { - "type": "array", - "description": "List of owners of the bank account", - "items": { - "type": "string", - "description": "Name of the owner of the bank account", - "x-faker": "person.fullName" - }, - "example": [ - "Maria Fumagalli", - "Luigi Verdi" - ] + "400": { + "$ref": "#/components/responses/BadRequest" }, - "consentStatus": { - "$ref": "#/components/schemas/ConsentStatusEnum" + "default": { + "$ref": "#/components/responses/DefaultError" } } }, - "Bulk": { - "type": "object", - "properties": { - "fingerprint": { - "$ref": "#/components/schemas/Fingerprint" - }, - "amount": { - "type": "number", - "format": "double", - "example": 48223.07, - "description": "Total amount of the bulk" - }, - "allowWireTranfersAggregation": { - "type": "boolean", - "example": true, - "description": "Indicate if the wire transfers to the same beneficiary can be aggregated" - }, - "documents": { - "type": "object", - "description": "Dictionary of documents related to the bulk. Keys are the document type, values are the fingerprints of the documents.", - "additionalProperties": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Fingerprint" + "post": { + "summary": "Crea una nuova richiesta di pagamento", + "description": "Endpoint per creare una richiesta di pagamento tra due attori, specificando dati di pagatore e beneficiario.", + "operationId": "createPaymentRequest", + "tags": [ + "Request To Pay", + "Payments" + ], + "security": [ + { + "basicAuth": [] + } + ], + "requestBody": { + "description": "Oggetto contenente informazioni su debitore, creditore e dettagli di pagamento.", + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "payer": { + "description": "Informazioni sul payer del pagamento. Può essere un numero di telefono o un oggetto Consumer.", + "oneOf": [ + { + "$ref": "#/components/schemas/PhoneNumber" + }, + { + "$ref": "#/components/schemas/Consumer" + }, + { + "title": "UUID del customer pagatore.", + "type": "string", + "format": "uuid", + "description": "UUID del customer che effettua il pagamento." + } + ] + }, + "debtor": { + "description": "Informazioni sul debitore effettivo del pagamento. Se non valorizzato, verrà utilizzato il valore di `payer`.", + "oneOf": [ + { + "$ref": "#/components/schemas/ConsumerTIN" + }, + { + "$ref": "#/components/schemas/BusinessTIN" + }, + { + "title": "UUID del customer debitore.", + "type": "string", + "format": "uuid", + "description": "UUID del customer debitore." + } + ] + }, + "ultimateDebtor": { + "type": "string", + "enum": [ + "debtor", + "payee", + "payer", + "tenant", + "anonymous" + ], + "description": { + "$ref": "./docs/description_ultimate_debtor.md" + }, + "default": "debtor" + }, + "attachments": { + "type": "array", + "items": { + "type": "string", + "format": "uuid", + "description": "Identificativo univoco del file allegato al pagamento." + }, + "description": "Elenco di UUID dei file allegati al pagamento che verranno mostrati nel checkout. Questi file devono essere stati precedentemente caricati utilizzando l'endpoint `/files`." + }, + "privateAttachments": { + "type": "array", + "items": { + "type": "string", + "format": "uuid", + "description": "Identificativo univoco del file." + }, + "description": "Elenco di UUID dei file allegati al pagamento che saranno visibili solo a FlowPay per i controlli di conformità. Questi file non saranno mostrati al pagatore durante il processo di pagamento." + }, + "title": { + "type": "string", + "minLength": 3, + "maxLength": 50, + "description": "Titolo esemplicativo del pagamento. Verrà mostrato al pagatore durante il processo di pagamento." + }, + "description": { + "type": "string", + "minLength": 5, + "maxLength": 255, + "description": "Descrizione del pagamento, visibile al pagatore." + }, + "remittanceInformation": { + "type": "string", + "minLength": 5, + "maxLength": 100, + "description": "Informazioni di rimessa per il pagamento, visibili al pagatore e al beneficiario all'accredito sul conto." + }, + "allowRemittanceChange": { + "type": "boolean", + "default": false, + "description": "Indica se il pagatore può modificare le informazioni di rimessa durante il pagamento." + }, + "email": { + "type": "string", + "format": "email", + "description": "Indirizzo email a cui verrà inviata la ricevuta del pagamento. Obbligatorio nel caso di PagoPA." + }, + "redirectUrl": { + "type": "string", + "format": "uri", + "description": "URL di redirect a cui l'utente verrà reindirizzato con query parameter status che può valere `success`, `error` o `cancel`." + }, + "callbackUrl": { + "type": "string", + "format": "uri", + "description": "URL di callback singolo per il pagamento." + } + }, + "required": [], + "oneOf": [ + { + "title": "Pagamento standard", + "properties": { + "amount": { + "type": "number", + "format": "decimal", + "minimum": 0.01, + "description": "Importo del pagamento in formato decimale (es. 10.50)." + }, + "payee": { + "description": "Informazioni sul payee del pagamento. Se non specificato, di default verrà utilizzato il partner associato al client e l'IBAN configurato per il client.", + "oneOf": [ + { + "$ref": "#/components/schemas/PhoneNumber" + }, + { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Nome del beneficiario." + }, + "iban": { + "description": "IBAN del conto del beneficiario.", + "$ref": "#/components/schemas/IBAN" + } + }, + "required": [ + "name", + "iban" + ] + } + ] + }, + "allowPartialPayments": { + "type": "boolean", + "description": "Indica se accettare pagamenti parziali. Se true, `amount` deve essere valorizzato e `additionalPayees` non deve essere valorizzato." + } + }, + "required": [], + "allOf": [ + { + "if": { + "title": "Pagamento intero", + "properties": { + "allowPartialPayments": { + "const": false + } + } + }, + "then": { + "properties": { + "additionalPayees": { + "type": "array", + "description": "Elenco di beneficiari aggiuntivi a cui destinare parte dell'importo del pagamento. La somma degli importi specificati in `additionalPayees` non può essere maggiore di `amount`; la differenza tra `amount` e la somma degli `additionalPayees` verrà inviata al `payee`.", + "items": { + "oneOf": [ + { + "type": "object", + "title": "Pagamento verso cellulare", + "description": "Pagamento a un numero di telefono.", + "properties": { + "amount": { + "type": "number", + "format": "decimal", + "minimum": 0.01, + "description": "Importo del pagamento in formato decimal" + }, + "phoneNumber": { + "$ref": "#/components/schemas/PhoneNumber" + } + }, + "required": [ + "phoneNumber", + "amount" + ] + }, + { + "type": "object", + "title": "Pagamento verso IBAN", + "description": "Pagamento a un beneficiario con IBAN.", + "properties": { + "amount": { + "type": "number", + "format": "decimal", + "minimum": 0.01, + "description": "Importo del pagamento in formato decimal" + }, + "name": { + "type": "string", + "description": "Nome del beneficiario." + }, + "iban": { + "description": "IBAN del conto del beneficiario.", + "$ref": "#/components/schemas/IBAN" + } + }, + "required": [ + "name", + "iban" + ] + }, + { + "title": "Pagamento verso customer", + "type": "string", + "format": "uuid", + "description": "UUID del customer da utilizzare come payee addizionale." + } + ] + } + }, + "lockedUntil": { + "type": "string", + "format": "date-time", + "description": "Se valorizzato, i fondi di questo pagamento verranno dirottati su un conto tecnico FlowPay fino alla data specificata. Entro tale data sarà possibile sbloccare i fondi verso il payee o restituirli al payer. Se i fondi saranno ancora presenti alla scadenza, verranno restituiti automaticamente al payer." + }, + "savePaymentMethod": { + "type": "boolean", + "default": false, + "description": "Indica se salvare il metodo di pagamento per futuri utilizzi." + }, + "executionDate": { + "type": "string", + "format": "date-time", + "description": "Data e ora di esecuzione del pagamento in formato ISO 8601. Se non valorizzato, il pagamento verrà eseguito immediatamente." + } + } + }, + "else": { + "title": "Pagamento parziale", + "required": [ + "amount" + ] + } + } + ] + }, + { + "title": "PagoPA", + "properties": { + "pagopaEcFiscalCode": { + "type": "string", + "description": "Codice fiscale della persona per PagoPA." + }, + "pagopaPaymentNotice": { + "type": "string", + "description": "Codice di avviso pagamento PagoPA." + } + }, + "required": [ + "pagopaEcFiscalCode", + "pagopaPaymentNotice", + "email" + ] + } + ] } } } - } - }, - "Chain": { - "description": "Chain of documents", - "type": "object", - "properties": { - "fingerprint": { - "$ref": "#/components/schemas/Fingerprint" + }, + "responses": { + "201": { + "description": "Richiesta di pagamento creata con successo.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PaymentRequest" + } + } + } }, - "targetType": { - "$ref": "#/components/schemas/DocumentKindEnum" + "400": { + "$ref": "#/components/responses/BadRequest" }, - "targetFingerprint": { - "$ref": "#/components/schemas/Fingerprint" - }, - "triggerType": { - "$ref": "#/components/schemas/DocumentKindEnum" - }, - "triggerFingerprint": { - "$ref": "#/components/schemas/Fingerprint" + "default": { + "$ref": "#/components/responses/DefaultError" } } - }, - "Checkout": { - "type": "object", - "properties": { - "code": { - "type": "string", - "pattern": "^[a-zA-Z\\d]{8}$", - "description": "Unique identifier of the checkout session. This code is secret and should never be shared with anyone who is not the payer." - }, - "fingerprint": { - "$ref": "#/components/schemas/Fingerprint" - }, - "type": { - "$ref": "#/components/schemas/DocumentKindEnum" - }, - "creditor": { - "type": "string", - "format": "uuid", - "description": "Identifier of the creditor", - "x-faker": "datatype.uuid" - }, - "debtor": { - "type": "string", - "format": "uuid", - "description": "Identifier of the debtor", - "x-faker": "datatype.uuid" - }, - "collectionMethods": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CollectionMethodEnum" + } + }, + "/payment-requests/{requestId}": { + "get": { + "summary": "Recupera lo stato di una richiesta di pagamento", + "description": "Restituisce dettagli e stato della richiesta di pagamento specificata.
Il documento PDF che include i dettagli della richiesta di pagamento e un QR code per apertura mobile. Se la richiesta è stata pagata, contiene anche le informazioni di pagamento e funge da ricevuta.", + "operationId": "getPaymentRequest", + "tags": [ + "Request To Pay", + "Payments" + ], + "security": [ + { + "basicAuth": [] + } + ], + "parameters": [ + { + "name": "requestId", + "in": "path", + "required": true, + "schema": { + "type": "string" }, - "description": "Collection methods enabled for the payment.
Note that collection methods are the intersection of the collection methods techologies enabled for the creditor and the collection methods allowed by the client for checkout." + "description": "Identificativo della richiesta di pagamento di cui recuperare lo stato." }, - "payments": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Payment" + { + "name": "Accept", + "in": "header", + "required": false, + "schema": { + "type": "string", + "enum": [ + "application/json", + "application/pdf" + ], + "default": "application/json" }, - "description": "List of payments related to the checkout" + "description": "Specifica il formato di risposta desiderato; usare application/pdf per ottenere un documento PDF." } - }, - "required": [ - "code", - "fingerprint", - "type", - "creditor", - "debtor", - "collectionMethods" - ] - }, - "ConsentStatusEnum": { - "type": "string", - "enum": [ - "not_granted", - "granted", - "revoked", - "expired", - "all" - ], - "default": "all", - "description": "Status of the account information service (AIS) consent granted by account owner to FlowPay.
- `not_granted`: owner has never granted a consent
- `granted`: consent granted by account owner
- `revoked`: consent revoked by account owner
- `expired`: consent expired
- `all`: all types of consent" - }, - "CollectionMethodEnum": { - "type": "string", - "enum": [ - "sct", - "sct-inst", - "sdd", - "card", - "custom/