openapi: 3.2.0
info:
  title: FlowPay KYC 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: KYC
  description:
    $ref: docs/kyc_description.md
paths:
  /kyc:
    post:
      summary: Start KYC
      description: Start KYC process for the current user
      operationId: startKyc
      tags:
      - KYC
      security:
      - oAuth2:
        - kyc
      requestBody:
        description: KYC request
        content:
          application/json:
            schema:
              type: object
              properties:
                redirectURL:
                  type: string
                  format: uri
                  description: URL where the user will be redirected after the KYC process is completed. If not specified, user will be redirected to the `/kyc/:identifier` endpoint wich will return the KYC data in JSON format.
                  x-faker: internet.url
                canLogin:
                  type: boolean
                  description: If true, the user will be able to login using one of the supported identity providers and other information that FlowPay has about the user will be used to pre-fill the KYC data. If false, the user must provide all the required information even if FlowPay already has it.
                  default: false
                flow:
                  type: string
                  description: Flow to be used for the KYC process. If not specified, user will be able to choose the flow.
                  enum:
                  - consumer
                  - company
                  - business
                consumer:
                  type: object
                  description: Consumer data to be used to pre-fill the KYC
                  properties:
                    name:
                      type: string
                      description: Consumer name
                      x-faker: person.firstName
                    surname:
                      type: string
                      description: Consumer surname
                      x-faker: person.lastName
                    tin:
                      $ref: '#/components/schemas/ConsumerNationalID'
                    email:
                      type: string
                      format: email
                      description: Consumer email address
                      x-faker: internet.email
                    phone:
                      type: string
                      format: phone
                      description: Consumer phone number
                      x-faker: phone.phoneNumber
                    address:
                      type: string
                      description: Consumer address
                      x-faker: address.streetAddress
                    birthDate:
                      type: string
                      format: datetime
                      description: Consumer birth date
                      x-faker: date.past
                    birthPlace:
                      type: string
                      description: Consumer birth place
                      x-faker: address.city
                    iban:
                      type: string
                      description: Consumer IBAN. If provided, FlowPay will use it to pre-validate ownership of the account, if autonomous IBAN check is not possibile, the IBAN will be used to find the bank where the account is held and the user will be asked to perform a Strong Customer Authentication with the bank.
                      x-faker: finance.iban
                    bank:
                      type: string
                      description: FlowPay identifier of the bank where the consumer holds the account. If provided, FlowPay will use it suggest the bank to the user during the Strong Customer Authentication process.<br> The identifier can be retrieved using the `/banks` endpoint.
                      example: Intesa Sanpaolo
                company:
                  type: object
                  description: Company data to be used to pre-fill the KYC
                  properties:
                    name:
                      type: string
                      description: Company name
                      x-faker: company.companyName
                    tin:
                      $ref: '#/components/schemas/CompanyVATNumber'
                    country:
                      type: string
                      description: Company country
                      x-faker: address.country
                    email:
                      type: string
                      format: email
                      description: Company email address
                      x-faker: internet.email
                    certifiedEmail:
                      type: string
                      format: email
                      description: Company certified email address
                      x-faker: internet.email
                    phone:
                      type: string
                      format: phone
                      description: Company phone number
                      x-faker: phone.phoneNumber
                    address:
                      type: string
                      description: Company address
                      x-faker: address.streetAddress
                    iban:
                      type: string
                      description: Company IBAN. If provided, FlowPay will use it to pre-validate ownership of the account, if autonomous IBAN check is not possibile, the IBAN will be used to find the bank where the account is held and the user will be asked to perform a Strong Customer Authentication with the bank.
                      x-faker: finance.iban
                    bank:
                      type: string
                      description: FlowPay identifier of the bank where the company holds the account. If provided, FlowPay will use it suggest the bank to the user during the Strong Customer Authentication process.<br> The identifier can be retrieved using the `/banks` endpoint.
                      example: Intesa Sanpaolo
              required: []
      responses:
        '201':
          description: KYC started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KYCDossier'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /kyc/{identifier}:
    get:
      summary: Get KYC data
      description: Retrieve KYC data for the specified session
      operationId: getKycStatus
      security:
      - oAuth2:
        - kyc
      parameters:
      - name: identifier
        in: path
        description: KYC session identifier
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: KYC status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KYCDossier'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
      - KYC
components:
  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
    KYCBankAccountDossier:
      type: object
      properties:
        iban:
          type: string
          description: IBAN of the bank account
          x-faker: finance.iban
        label:
          type: string
          description: Label of the bank account
          example: My bank account
        verified:
          type: boolean
          description: True if the ownership of the bank account has been verified
        consentExpiresAt:
          type: string
          format: date-time
          description: Date and time of the bank account PSD2 consent expiration
          example: '2020-01-01T00:00:00Z'
          x-faker: date.future
    KYCFlow:
      type: string
      description: KYC flow
      enum:
      - consumer
      - company
      - business
    KYCCompanyDossier:
      type: object
      description: Company information
      properties:
        name:
          type: string
          description: Name of the company
          example: Illustrious Company S.p.A.
          x-faker: company.companyName
        vat:
          $ref: '#/components/schemas/CompanyVATNumber'
          description: VAT number of the company
        address:
          $ref: '#/components/schemas/Address'
          description: Address of the company
        email:
          type: string
          format: email
          description: Email of the company
          x-faker: internet.email
        phone:
          type: string
          description: Phone number of the company
          example: '+393331234567'
          x-faker: phone.phoneNumber
        sanctioned:
          type: boolean
          description: True if the company is present in the list of sanctioned subjects
        verified:
          type: boolean
          description: True if the company information has been verified
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/KYCBankAccountDossier'
          description: List of bank accounts of the company
    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
    KYCDossier:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the KYC session
          x-faker: datatype.uuid
        createdAt:
          type: string
          format: date-time
          description: Date and time of the KYC session creation
          example: '2020-01-01T00:00:00Z'
          x-faker: date.past
        updatedAt:
          type: string
          format: date-time
          description: Date and time of the last KYC session update
          example: '2020-01-01T00:00:00Z'
          x-faker: date.past
        lastAccessAt:
          type: string
          format: date-time
          description: Date and time of the last KYC session access
          example: '2020-01-01T00:00:00Z'
          x-faker: date.past
        kind:
          $ref: '#/components/schemas/KYCFlow'
        canLogin:
          type: boolean
          description: True if the user can login to the KYC session. If true, the user can retrieve data verified in previous sessions and can skip some steps of the KYC flow.
          default: false
        consumer:
          $ref: '#/components/schemas/KYCConsumerDossier'
          description: Consumer information
        company:
          $ref: '#/components/schemas/KYCCompanyDossier'
          description: Company information
    KYCConsumerDossier:
      type: object
      properties:
        name:
          type: string
          description: Name of the consumer
          example: Mario
          x-faker: person.firstName
        surname:
          type: string
          description: Surname of the consumer
          example: Rossi
          x-faker: person.lastName
        tin:
          $ref: '#/components/schemas/ConsumerNationalID'
          description: National ID of the consumer
        birthDate:
          type: string
          format: date
          description: Date of birth of the consumer
          example: '1980-01-01'
          x-faker: date.past
        birthPlace:
          type: string
          description: Place of birth of the consumer
          example: Milano
          x-faker: address.city
        birthCountry:
          type: string
          description: Country of birth of the consumer
          example: IT
          x-faker: address.countryCode
        address:
          $ref: '#/components/schemas/Address'
          description: Address of the consumer
        email:
          type: string
          format: email
          description: Email of the consumer
          x-faker: internet.email
        phone:
          type: string
          description: Phone number of the consumer
          example: '+393331234567'
          x-faker: phone.phoneNumber
        sanctioned:
          type: boolean
          description: True if the consumer is present in the list of sanctioned subjects
        verified:
          type: boolean
          description: True if the consumer information has been verified
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/KYCBankAccountDossier'
          description: List of bank accounts of the consumer
    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
    StatusCode:
      type: integer
      description: HTTP status code
      example: 404
  responses:
    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
    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
    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
  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