openapi: 3.2.0
info:
  title: FlowPay Transfers API
  version: 2.0.0-alpha.4
  description:
    $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
servers:
- url: https://api.flowpay.it/v2
  description: Production server (Not implementend)
- url: https://mock.flowpay.it/v2
  description: Mock server
- 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
- url: http://localhost:5002
  description: Debug
tags:
- name: Transfers
  description: Lifecycle-free documents
paths:
  /transfers:
    get:
      summary: Get transfers
      description: Retrieve transfers document list
      operationId: getTransfers
      security:
      - oAuth2:
        - transfers:read
      parameters:
      - name: from
        in: query
        description: Start date of the period to retrieve transfers for. If not specified, the default value is the first day of the current month
        required: false
        schema:
          type: string
          format: iso8601
        x-faker: date.past
      - name: to
        in: query
        description: End date of the period to retrieve transfers for. If not specified, the default value is the current date
        required: false
        schema:
          type: string
          format: iso8601
        x-faker: date.future
      - name: page
        in: query
        description: Page number to retrieve. If not specified, the default value is 1
        required: false
        schema:
          type: integer
          format: int32
        x-faker: random.number
      - name: size
        in: query
        description: Number of transfers to retrieve. If not specified, the default value is 10
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Transfer documents list
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResult'
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/Transfer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Transfers
    post:
      summary: Create transfer
      description: Create a new transfer document
      operationId: createTransfer
      security:
      - oAuth2:
        - transfers:write
      requestBody:
        description: Transfer details
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  format: float
                  description: Amount of the transfer
                  example: 100.34
                  x-faker: finance.amount
                currency:
                  type: string
                  description: Currency of the transfer
                  example: EUR
                  default: EUR
                  x-faker: finance.currencyCode
                remittance:
                  type: string
                  description: Remittance information of the SEPA Credit Transfer
                  example: Pizza at Pizzeria da Mario. Thank you!
                  x-faker: lorem.sentence
                creditor:
                  oneOf:
                  - $ref: '#/components/schemas/ConsumerNationalID'
                  - $ref: '#/components/schemas/CompanyVATNumber'
                debtor:
                  oneOf:
                  - $ref: '#/components/schemas/ConsumerNationalID'
                  - $ref: '#/components/schemas/CompanyVATNumber'
              required:
              - amount
              - remittance
              - creditor
              - debtor
        required: true
      responses:
        '201':
          description: Transfer created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Transfers
  /transfers/{transferID}:
    get:
      summary: Get transfer details
      description: Retrieve transfer document details
      operationId: getTransfer
      security:
      - oAuth2:
        - transfers:read
      parameters:
      - name: transferID
        in: path
        description: Transfer ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Transfer document details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Transfers
    delete:
      summary: Delete transfer
      description: Delete a transfer document that has not yet been executed
      operationId: deleteTransfer
      security:
      - oAuth2:
        - transfers:write
      parameters:
      - name: transferID
        in: path
        description: Transfer ID
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Transfer document deleted
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Transfers
components:
  responses:
    InternalServerError:
      description: Server encountered an unexpected condition that prevented it from fulfilling the request
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                $ref: '#/components/schemas/StatusCode'
              requestID:
                $ref: '#/components/schemas/RequestID'
            required:
            - statusCode
            - requestID
    Unauthorized:
      description: Client has not provided valid credentials to access the requested resource
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                $ref: '#/components/schemas/StatusCode'
              requestID:
                $ref: '#/components/schemas/RequestID'
              message:
                type: string
                description: Error message
                example: You must provide a valid access token
            required:
            - statusCode
            - requestID
            - message
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                $ref: '#/components/schemas/StatusCode'
              requestID:
                $ref: '#/components/schemas/RequestID'
              message:
                type: string
                description: Error message
                example: Invoice not found
            required:
            - statusCode
            - requestID
            - message
    BadRequest:
      description: Client has provided invalid data
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                $ref: '#/components/schemas/StatusCode'
              requestID:
                $ref: '#/components/schemas/RequestID'
              message:
                type: string
                description: Error message
                example: Proforma invoice can not have a due date later than the invoice date
              additionalInfo:
                type: object
                description: Additional information about the error
                properties:
                  path:
                    type: string
                    description: JSON path of the field that caused the error
                    example: .dueDate
                  key:
                    type: string
                    description: JSON key of the field that caused the error
                    example: dueDate
                  type:
                    type: string
                    description: Expected type of the field that caused the error
                    example: string
                required:
                - path
            required:
            - statusCode
            - requestID
            - message
            - additionalInfo
    Forbidden:
      description: Client is not authorized to access the requested resource
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                $ref: '#/components/schemas/StatusCode'
              requestID:
                $ref: '#/components/schemas/RequestID'
              message:
                type: string
                description: Error message
                example: You can't create a new invoice for this tenant
            required:
            - statusCode
            - requestID
            - message
  schemas:
    Contact:
      type: object
      properties:
        fullName:
          description: Full name of the contact, contains the concatenation of the name and surname of a consumer, or the name of a company.
          oneOf:
          - type: string
            description: Full name of the consumer
            example: Mario Rossi
            x-faker: person.fullName
          - type: string
            description: Company name
            example: Illustrious Company S.p.A.
            x-faker: company.companyName
        fullVat:
          type: string
          description: 'VAT number of the company in full european format or national ID of the consumer '
          oneOf:
          - $ref: '#/components/schemas/ConsumerNationalID'
          - $ref: '#/components/schemas/CompanyVATNumber'
        type:
          type: string
          enum:
          - consumer
          - company
          description: Type of the contact
    PaginatedResult:
      type: object
      properties:
        page:
          type: integer
          description: Current page number
        pageSize:
          type: integer
          description: Number of items per page
        total:
          type: integer
          description: Total number of items
        items:
          type: array
          description: List of items
          items: {}
    RequestID:
      type: string
      description: Unique identifier of the request.<br> It is helpful to identify the request in case of errors, providing it to the support team. Please submit it in the support ticket.
      format: uuid
      x-faker: random.uuid
    ConsumerNationalID:
      type: string
      description: National ID of the consumer, currently only italian format is supported
      pattern: /^([A-Z]{6}\d{2}[A-Z]\d{2}[A-Z]\d{3}[A-Z])$
      example: RSSMRA80A01H501T
    CompanyVATNumber:
      type: string
      description: VAT number of the company, full european format
      pattern: /^((AT)(U\d{8})|(BE)(0\d{9})|(BG)(\d{9,10})|(CY)(\d{8}[LX])|(CZ)(\d{8,10})|(DE)(\d{9})|(DK)(\d{8})|(EE)(\d{9})|(EL|GR)(\d{9})|(ES)([\dA-Z]\d{7}[\dA-Z])|(FI)(\d{8})|(FR)([\dA-Z]{2}\d{9})|(HU)(\d{8})|(IE)(\d{7}[A-Z]{2})|(IT)(\d{11})|(LT)(\d{9}|\d{12})|(LU)(\d{8})|(LV)(\d{11})|(MT)(\d{8})|(NL)(\d{9}(B\d{2}|BO2))|(PL)(\d{10})|(PT)(\d{9})|(RO)(\d{2,10})|(SE)(\d{12})|(SI)(\d{8})|(SK)(\d{10}))$
      example: IT12345678901
      x-faker: finance.vat
    Transfer:
      type: object
      description: 'Kind of document that allow clients to manage payment requests with low constraints. <br> Clients can use transfers to fast prototyping payment initiation use cases or to avoid specific document''s lifecycle managment. <br><b>Note: </b> In order to use transfers in production, a more in-depth due diligence is required.'
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the transfer
          x-faker: random.uuid
        fingerprint:
          $ref: '#/components/schemas/Fingerprint'
        amount:
          type: number
          description: Amount of the transfer
          example: 100.34
          x-faker: finance.amount
        remittance:
          type: string
          description: Remittance information of the transfer
          example: Payment for invoice 123
          x-faker: lorem.sentence
        creditor:
          description: Creditor of this transfer
          $ref: '#/components/schemas/Contact'
        debtor:
          description: Debtor of this transfer
          $ref: '#/components/schemas/Contact'
        createdAt:
          type: string
          format: iso8601
          description: Date and time of the transfer creation
          example: '2020-01-01T00:00:00Z'
          x-faker: date.past
    StatusCode:
      type: integer
      description: HTTP status code
      example: 404
    Fingerprint:
      type: string
      description: Fingerprint of the document
      example: d41d8cd98f00b204e9800998ecf8427e
  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