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 2edce01..a4c86b2 100644 --- a/openapi.json +++ b/openapi.json @@ -1,4160 +1,87 @@ { "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" - } - } - } - } - }, - "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." - }, - "country": { - "type": "string", - "description": "The name of the country where the property is located." - } - }, - "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" - } - } - } - } - } - }, - "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" - ] - }, - "consentStatus": { - "$ref": "#/components/schemas/ConsentStatusEnum" - } - } - }, - "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" - } - } - } - } - }, - "Chain": { - "description": "Chain of documents", - "type": "object", - "properties": { - "fingerprint": { - "$ref": "#/components/schemas/Fingerprint" - }, - "targetType": { - "$ref": "#/components/schemas/DocumentKindEnum" - }, - "targetFingerprint": { - "$ref": "#/components/schemas/Fingerprint" - }, - "triggerType": { - "$ref": "#/components/schemas/DocumentKindEnum" - }, - "triggerFingerprint": { - "$ref": "#/components/schemas/Fingerprint" - } - } - }, - "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" - }, - "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." - }, - "payments": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Payment" - }, - "description": "List of payments related to the checkout" - } - }, - "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/