openapi: 3.0.1
info:
  title: network_payments API
  description: Merged OpenAPI spec for network_payments domain
  version: 1.0.0
servers:
- description: ''
  url: https://api.uat.btx.fr.banqup.com/network/payments
- description: ''
  url: https://api.uat.btx.eu.banqup.com/network/payments
paths:
  /transaction/v1/spaces/{spaceId}/paymentAccounts/{paymentAccountId}:assignConnections:
    post:
      tags:
      - Payment Accounts
      summary: Assign connection(s) to payment account
      description: 'Assign one or more connections to a payment account <br/> Scope:
        space_write'
      operationId: paymentAccountAssignConnections
      parameters:
      - name: spaceId
        in: path
        description: The space identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: paymentAccountId
        in: path
        description: The payment account uuid identifier
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: List of connection ids to assign
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionsList'
            example:
              connections:
              - 57977521-12cb-4863-91cf-8c171b40a789
        required: true
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllPaymentAccountsResult'
              example:
                paymentAccounts:
                - id: 0ca2797b-6365-4bf2-a490-247075e3cede
                  identifier: BE19519469892112
                  scheme: IBAN
                  country: BE
                  currency: EUR
                  bank:
                    identifier: ABNABE2AIDJ
                    scheme: BIC
                  spaceId: 56079d21-a756-49fb-9286-9859c354aa69
                  connections:
                  - id: 3b0291e3-2a54-487f-8563-57391ef8535e
                    type: person
                    name: John Doe
                    alias: Johnny
                    defaultPaymentAccount: true
                  address:
                    country: BE
                    townName: Gent
                    addressType: BIZZ
                    streetName: Kortrijksesteenweg
                    buildingNumber: '1146'
                    postCode: '9051'
                  createdAt: 2023-10-04 14:20:31.502921+00:00
                  updatedAt: 2023-10-04 14:20:31.502921+00:00
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27 12:34:50+00:00
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27 12:34:50+00:00
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_write
  /transaction/v1/spaces/{spaceId}/paymentAccounts/{paymentAccountId}:unassignConnections:
    post:
      tags:
      - Payment Accounts
      summary: Unassign connection(s) from payment account
      description: 'Unassign one or more connections from a payment account <br/>
        Scope: space_write'
      operationId: paymentAccountUnassignConnections
      parameters:
      - name: spaceId
        in: path
        description: The space identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: paymentAccountId
        in: path
        description: The payment account uuid identifier
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: List of connection ids to unassign
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionsList'
            example:
              connections:
              - 57977521-12cb-4863-91cf-8c171b40a789
        required: true
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllPaymentAccountsResult'
              example:
                paymentAccounts:
                - id: 0ca2797b-6365-4bf2-a490-247075e3cede
                  identifier: BE19519469892112
                  scheme: IBAN
                  country: BE
                  currency: EUR
                  bank:
                    identifier: ABNABE2AIDJ
                    scheme: BIC
                  spaceId: 56079d21-a756-49fb-9286-9859c354aa69
                  connections:
                  - id: 3b0291e3-2a54-487f-8563-57391ef8535e
                    type: person
                    name: John Doe
                    alias: Johnny
                    defaultPaymentAccount: true
                  address:
                    country: BE
                    townName: Gent
                    addressType: BIZZ
                    streetName: Kortrijksesteenweg
                    buildingNumber: '1146'
                    postCode: '9051'
                  createdAt: 2023-10-04 14:20:31.502921+00:00
                  updatedAt: 2023-10-04 14:20:31.502921+00:00
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27 12:34:50+00:00
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27 12:34:50+00:00
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_write
components:
  schemas:
    JsonBMap:
      type: object
      additionalProperties: true
    JsonBMapNullable:
      type: object
      additionalProperties: true
      nullable: true
    PatchRequest:
      type: array
      items:
        $ref: '#/components/schemas/PatchDocument'
    PatchDocument:
      required:
      - op
      - path
      type: object
      properties:
        op:
          type: string
          description: The operation to be performed
          enum:
          - add
          - remove
          - replace
          - move
          - copy
          - test
        path:
          type: string
          description: A JSON-Pointer
        value:
          type: object
          description: The value to be used within the operations.
        from:
          type: string
          description: A string containing a JSON Pointer value.
      description: A JSONPatch document as defined by RFC 6902
    AccountIdentifier:
      type: object
      properties:
        identifier:
          type: string
          description: Account Identifier
          example: BE83504010119715
        scheme:
          type: string
          description: Account Scheme
          example: IBAN
        bank:
          $ref: '#/components/schemas/BankIdentifier'
        country:
          pattern: ^[a-zA-Z]{2}
          type: string
          example: BE
        currency:
          pattern: '[A-Z]{3}'
          type: string
          description: International code ISO 4217 of the currency used
          example: EUR
        parent:
          $ref: '#/components/schemas/AccountIdentifier'
      description: Parent payment account
    AllPaymentAccountsResult:
      type: object
      properties:
        paymentAccounts:
          type: array
          description: List of payment accounts
          items:
            $ref: '#/components/schemas/PaymentAccountResult'
        totalElements:
          type: integer
          description: Total number of items in the database that correspond to this
            search criteria
          format: int64
        currentPage:
          type: integer
          description: Current page
          format: int32
        pageSize:
          type: integer
          description: Response page size
          format: int32
    BankIdentifier:
      type: object
      properties:
        identifier:
          type: string
          description: Bank Identifier
          example: PANXBEB1XXX
        scheme:
          type: string
          description: Bank Identifier Scheme
          example: BIC
          enum:
          - BIC
          - CODE
          - ABA
          - CLABE
          - THIRD_PARTY
      description: Information about the issuer of the account
    Iso20022StructuredAddress:
      type: object
      properties:
        country:
          type: string
          description: Nation with its own government, expressed as a two letter ISO
            3166 code (alpha-2) of the country. The country code is written in upper
            case.
          example: BE
        townName:
          type: string
          description: Name of a built-up area, with defined boundaries, and a local
            government.
          example: La Hulpe
        addressType:
          type: string
          description: Identifies the nature of the postal address.
          example: ADDR
          enum:
          - ADDR
          - PBOX
          - HOME
          - BIZZ
          - MLTO
          - DLVY
        streetName:
          maxLength: 140
          type: string
          description: Name of a street or thoroughfare.
          example: Avenue Reine Astrid
        buildingNumber:
          maxLength: 16
          type: string
          description: A unique number assigned to the building in the street or area
            //Number that identifies the position of a building on a street.
          example: '40'
        careOf:
          maxLength: 140
          type: string
          description: Identifies an addressee that is accepting the correspondence
            for the intended recipient. Using care of ensures the correspondence reaches
            the right recipient rather than getting returned to the sender.
          example: Finance
        department:
          maxLength: 70
          type: string
          description: Identification of a division of a large organisation or building.
          example: Finance
        subDepartment:
          maxLength: 70
          type: string
          description: Identification of a sub-division of a large organisation or
            building.
          example: Accounting
        buildingName:
          maxLength: 140
          type: string
          description: Name of the building or house.
          example: Empire State Building
        floor:
          maxLength: 70
          type: string
          description: Floor or storey within a building.
          example: ground
        unitNumber:
          maxLength: 16
          type: string
          description: Identifies a flat or dwelling within the building.
          example: '2'
        postBox:
          maxLength: 16
          type: string
          description: Numbered box in a post office, assigned to a person or organisation,
            where letters are kept until called for.
          example: '1003'
        room:
          maxLength: 70
          type: string
          description: Building room number.
          example: '2.22'
        postCode:
          maxLength: 16
          type: string
          description: Identifier consisting of a group of letters and/or numbers
            that is added to a postal address to assist the sorting of mail.
          example: '1310'
        townLocationName:
          maxLength: 140
          type: string
          description: Specific location name within the town. eg Borough (USA), Village
            (GB).
          example: Miami Beach
        districtName:
          maxLength: 140
          type: string
          description: Identifies a subdivision within a country sub-division eg County
            (USA), Landkreis (DE).
          example: Miami-Dade, Coburg
        countrySubDivision:
          maxLength: 35
          type: string
          description: Identifies a subdivision of a country such as state (USA),
            Bundesland (DE), region, province,....
          example: Florida, Bayern, Wallonia, Hainaut
      description: Information that locates and identifies a specific address, as
        defined by postal services
      externalDocs:
        description: More about EPC Interbank Structured Address Structure; see also
          PostalAddress27 type in https://www.iso20022.org/message/22905/download
        url: 
          https://www.europeanpaymentscouncil.eu/sites/default/files/kb/file/2022-10/EPC153-22%20EPC%20guidance%20document%20-%20Use%20of%20Structured%20Address%20under%20the%20SEPA%20Payment%20Schemes%20as%20of%20Nov%202025.pdf
    PaymentAccountConnectionDetails:
      type: object
      properties:
        id:
          type: string
          description: Connection ID
          format: uuid
        type:
          type: string
          description: Connection type
          example: person
        name:
          type: string
          description: Connection name
        alias:
          type: string
          description: Connection alias
        defaultPaymentAccount:
          type: boolean
          description: Flag to indicate if paymentAccount is default for this connection
      description: List of associated connection
    PaymentAccountResult:
      type: object
      properties:
        id:
          type: string
          description: Payment account ID
          format: uuid
        identifier:
          type: string
          description: Identifier of the payment account
        scheme:
          type: string
          description: Scheme of the payment account
        country:
          type: string
          description: Country for the payment account
        currency:
          type: string
          description: Currency for the payment account
        bank:
          $ref: '#/components/schemas/BankIdentifier'
        spaceId:
          type: string
          description: Space id
          format: uuid
        ownedBySpace:
          type: boolean
          description: Flag to indicate if the space is the actual holder of the payment
            account.
        active:
          type: boolean
          description: Flag to indicate if the payment account is active or not.
        ownerName:
          type: string
          description: Name of owner.
        address:
          $ref: '#/components/schemas/Iso20022StructuredAddress'
        parent:
          $ref: '#/components/schemas/AccountIdentifier'
        financialPlatformId:
          type: string
          description: Optional identifier of the financial platform.
        connections:
          type: array
          description: List of associated connection
          items:
            $ref: '#/components/schemas/PaymentAccountConnectionDetails'
        createdAt:
          type: string
          description: creation datetime
          format: date-time
        updatedAt:
          type: string
          description: updated datetime
          format: date-time
        entityPaymentAccountId:
          type: string
          description: entityPaymentAccountId in Payment Account
          format: uuid
    ApiErrorProblemDetail:
      required:
      - error
      - requestId
      - timestamp
      type: object
      properties:
        status:
          type: integer
          format: int32
        error:
          type: string
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri
        problems:
          type: array
          items:
            $ref: '#/components/schemas/NestedProblem'
        properties:
          type: object
          additionalProperties:
            type: object
    NestedProblem:
      required:
      - detail
      - error
      - title
      type: object
      properties:
        error:
          type: string
        title:
          type: string
        detail:
          type: string
        type:
          type: string
          format: uri
    ConnectionsList:
      type: object
      properties:
        connections:
          type: array
          description: List of connection ids
          format: uuid
          items:
            type: string
            description: List of connection ids
            format: uuid
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.uat.btx.fr.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.uat.btx.fr.banqup.com/oauth2/auth
          tokenUrl: https://api.uat.btx.fr.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
tags:
- name: Spaces
  description: "Spaces are virtual environments (work spaces) where all relevant resources
    of an entity are managed.  Spaces can also facilitate document exchange and communication
    among entities, depending on the space type.\nThe role of spaces is to gather
    all relevant data of an entity into one accessible setting.  Such data can include:
    invoices, connections, cards, clients, payments, users, installed apps etc.  The
    capabilities offered by a space depends on the space type and the active subscription."
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Files
  description: A file refers to the digital container that stores the data of one
    or more documents.  Files are the medium through which electronic documents are
    stored, transmitted, and accessed.
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Documents
  description: "A document in e-invoicing refers to a formal, structured piece of
    information that contains details  related to invoicing: e.g financial data, payment
    details, tax information etc. or any other information  relevant to the company's
    operations, services, or interactions with clients and partners.\nEvery Banqup
    document is associated with a unique UUID that is stored in the Banqup database
    as documentId.  The UUID is generated when a new file is received/uploaded into
    Banqup and is necessary when performing  document actions via the Banqup APIs."
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Connections
  description: 'Connections are business and persons in the private address book of
    a space and they represent the actors involved  in document exchange, such as:
    customers, suppliers, accountants, partners, groups.'
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Payments
  description: A payment is a generic term for the business event of transferring
    funds from one party to another.
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Payment Accounts
  description: "Payment accounts are bank or financial accounts used for managing
    payments, deposits, withdrawals, and transfers. \nThe Payment Accounts of a space
    are all bank or financial account the business represented by the space interacts
    with via e-invoicing or payments."
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Payment Information
  description: "Payment Information representing some sort of evidence related to
    a Payment.\nThis evidence could be in different forms :\n  - PaymentTransaction
    : information related to a payment of which the transaction (initiation) \n  \
    \                       was started on platform.\n  - BookedPaymentMovement :
    information imported from your own account indicating a payment movement was booked.
    \n  - PlannedPaymentMovement : information imported from your own account indicating
    an amount was reserved \n                         for a future payment.\n  - ManualPaymentInformation
    : information about a payment that was manually entered by a user of the platform.\n\
    \  - CounterpartyPaymentInformation : information added to your space about a
    payment which was based on the \n                         PaymentInformation the
    counter party of the payment indicated on BTX platform."
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Internal Payments
  description: "This is a set of internal API call only intended to be used by BTX
    Payment Service or Aggregation Service. They are restricted to ensure that updates
    on payments, payment information and links to documents (BalanceOffset)  are done
    in consistent way.  \nThe higher level public APIs for adding payment, payment
    information and linking payments to documents  will be provided by the BTX Payment
    Service or Aggregation Service."
  x-BTX:
    unDocumented: 'false'
    internal: 'true'
- name: Internal
  description: This is a set of pure internal API.  It contains for example callback
    endpoints that get registered to receive messages.
  x-BTX:
    unDocumented: 'true'
    internal: 'true'
