Montran Virtual Accounts

openapi: 3.1.0
info:
  title: Montran Virtual Accounts API
  description: >-
    The Montran Virtual Account Management (VAM) platform is a bank-agnostic
    solution that enables rapid deployment of virtual account structures for
    POBO/COBO services, in-house banking, treasury centralization, liquidity
    management, and escrow services. It provides full Virtual IBAN Management
    (VIBAN) including 2-way VIBANs, Open Banking capability via PSD2 or
    proprietary API links, and connects to many banks simultaneously. The
    platform supports real-time reconciliation and automatic funds allocation
    with strict segregation of funds in pooled or omnibus accounts. Available
    as SaaS or on-premise deployment.
  version: 1.0.0
  contact:
    name: Montran Corporation
    url: https://www.montran.com/contact-us/
  license:
    name: Proprietary
    url: https://www.montran.com/terms-conditions/
  x-logo:
    url: https://www.montran.com/logo.png
externalDocs:
  description: Montran Virtual Accounts Documentation
  url: https://www.montran.com/solutions/virtual-accounts/
servers:
  - url: https://api.montran.com/vam/v1
    description: Montran Virtual Account Management API Server
tags:
  - name: Account Structures
    description: Virtual account hierarchy and structure management
  - name: Balances
    description: Balance inquiry and reconciliation operations
  - name: Transactions
    description: Transaction processing and allocation
  - name: Virtual Accounts
    description: Virtual account creation, management, and lifecycle operations
  - name: Virtual IBANs
    description: Virtual IBAN issuance and management
paths:
  /virtual-accounts:
    get:
      operationId: listVirtualAccounts
      summary: Montran List virtual accounts
      description: >-
        Retrieves a list of virtual accounts managed on the platform.
        Supports filtering by status, currency, parent account, and
        account holder. Returns account details including virtual IBAN,
        balance, and hierarchy information.
      tags:
        - Virtual Accounts
      parameters:
        - name: status
          in: query
          description: Filter by account status
          schema:
            type: string
            enum:
              - active
              - suspended
              - closed
        - name: currency
          in: query
          description: Filter by ISO 4217 currency code
          schema:
            type: string
            pattern: ^[A-Z]{3}$
        - name: parentAccountId
          in: query
          description: Filter by parent physical account
          schema:
            type: string
        - name: accountHolder
          in: query
          description: Filter by account holder name
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Successfully retrieved virtual accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualAccountList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createVirtualAccount
      summary: Montran Create a virtual account
      description: >-
        Creates a new virtual account mapped to an existing physical bank
        account. The virtual account can optionally be assigned a Virtual
        IBAN for receiving incoming payments. Supports multi-currency
        virtual accounts and can be configured for POBO/COBO, escrow,
        or general segregation purposes.
      tags:
        - Virtual Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualAccountCreate'
      responses:
        '201':
          description: Virtual account successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualAccount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /virtual-accounts/{accountId}:
    get:
      operationId: getVirtualAccount
      summary: Montran Get virtual account details
      description: >-
        Retrieves the full details of a specific virtual account including
        its virtual IBAN, mapped physical account, balance, transaction
        history summary, and position within the account hierarchy.
      tags:
        - Virtual Accounts
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
      responses:
        '200':
          description: Successfully retrieved virtual account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      operationId: updateVirtualAccount
      summary: Montran Update a virtual account
      description: >-
        Updates the configuration of a virtual account including its name,
        metadata, and allocation rules. Cannot change the mapped physical
        account or virtual IBAN.
      tags:
        - Virtual Accounts
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualAccountUpdate'
      responses:
        '200':
          description: Virtual account successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualAccount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /virtual-accounts/{accountId}/close:
    post:
      operationId: closeVirtualAccount
      summary: Montran Close a virtual account
      description: >-
        Closes a virtual account. The account must have a zero balance
        before it can be closed. Any associated virtual IBANs are
        deactivated upon closure.
      tags:
        - Virtual Accounts
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Reason for closing the account
      responses:
        '200':
          description: Virtual account successfully closed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Account cannot be closed (non-zero balance)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /virtual-accounts/{accountId}/balance:
    get:
      operationId: getVirtualAccountBalance
      summary: Montran Get virtual account balance
      description: >-
        Retrieves the current balance of a virtual account including
        available balance, booked balance, and pending transactions.
        Provides real-time reconciliation data.
      tags:
        - Balances
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
      responses:
        '200':
          description: Successfully retrieved balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualAccountBalance'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /virtual-accounts/{accountId}/transactions:
    get:
      operationId: listVirtualAccountTransactions
      summary: Montran List virtual account transactions
      description: >-
        Retrieves transactions for a specific virtual account. Includes
        both automatically allocated incoming payments and manually
        posted internal transfers. Supports date range filtering.
      tags:
        - Transactions
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
        - name: fromDate
          in: query
          schema:
            type: string
            format: date
        - name: toDate
          in: query
          schema:
            type: string
            format: date
        - name: type
          in: query
          description: Filter by transaction type
          schema:
            type: string
            enum:
              - incoming
              - outgoing
              - internal_transfer
              - allocation
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Successfully retrieved transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualTransactionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /virtual-ibans:
    get:
      operationId: listVirtualIbans
      summary: Montran List virtual IBANs
      description: >-
        Retrieves a list of issued virtual IBANs. Supports filtering by
        status and associated virtual account. Virtual IBANs enable
        incoming payments to be automatically routed and allocated to
        the correct virtual account.
      tags:
        - Virtual IBANs
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum:
              - active
              - inactive
        - name: virtualAccountId
          in: query
          description: Filter by associated virtual account
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Successfully retrieved virtual IBANs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualIbanList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: issueVirtualIban
      summary: Montran Issue a virtual IBAN
      description: >-
        Issues a new virtual IBAN and associates it with a virtual account.
        The VIBAN can be used for receiving incoming payments that are
        automatically allocated to the linked virtual account. Supports
        2-way VIBANs for both receiving and sending.
      tags:
        - Virtual IBANs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualIbanCreate'
      responses:
        '201':
          description: Virtual IBAN successfully issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualIban'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /virtual-ibans/{vibanId}:
    get:
      operationId: getVirtualIban
      summary: Montran Get virtual IBAN details
      description: >-
        Retrieves the details of a specific virtual IBAN including its
        associated virtual account, status, and usage statistics.
      tags:
        - Virtual IBANs
      parameters:
        - name: vibanId
          in: path
          required: true
          description: Unique identifier of the virtual IBAN
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved virtual IBAN details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualIban'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /virtual-ibans/{vibanId}/deactivate:
    post:
      operationId: deactivateVirtualIban
      summary: Montran Deactivate a virtual IBAN
      description: >-
        Deactivates a virtual IBAN so it can no longer receive incoming
        payments. The IBAN remains in the system for historical reference
        but new payments referencing it will be rejected.
      tags:
        - Virtual IBANs
      parameters:
        - name: vibanId
          in: path
          required: true
          description: Unique identifier of the virtual IBAN
          schema:
            type: string
      responses:
        '200':
          description: Virtual IBAN successfully deactivated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualIban'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /account-structures:
    get:
      operationId: listAccountStructures
      summary: Montran List account structures
      description: >-
        Retrieves virtual account hierarchy structures. Account structures
        define the organizational grouping of virtual accounts for
        corporate clients, enabling POBO/COBO, in-house banking, and
        treasury centralization use cases.
      tags:
        - Account Structures
      responses:
        '200':
          description: Successfully retrieved account structures
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountStructureList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createAccountStructure
      summary: Montran Create an account structure
      description: >-
        Creates a new virtual account hierarchy structure mapping virtual
        accounts to physical bank accounts. Supports multi-bank, multi-
        currency structures for POBO/COBO, in-house banking, and escrow
        use cases.
      tags:
        - Account Structures
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountStructureCreate'
      responses:
        '201':
          description: Account structure successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountStructure'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /internal-transfers:
    post:
      operationId: createInternalTransfer
      summary: Montran Create an internal transfer
      description: >-
        Creates a transfer between two virtual accounts within the same
        physical account structure. Internal transfers are processed
        instantly as book transfers without requiring external clearing.
      tags:
        - Transactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InternalTransfer'
      responses:
        '201':
          description: Internal transfer successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalTransferResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
  parameters:
    AccountIdParam:
      name: accountId
      in: path
      required: true
      description: Unique identifier of the virtual account
      schema:
        type: string
  schemas:
    VirtualAccountCreate:
      type: object
      description: Virtual account creation request
      required:
        - name
        - physicalAccountId
        - currency
      properties:
        name:
          type: string
          description: Account name or label
        physicalAccountId:
          type: string
          description: ID of the underlying physical bank account
        currency:
          type: string
          description: ISO 4217 currency code
          pattern: ^[A-Z]{3}$
        accountHolder:
          type: string
          description: Name of the virtual account holder
        purpose:
          type: string
          description: Purpose of the virtual account
          enum:
            - GENERAL
            - POBO
            - COBO
            - ESCROW
            - IN_HOUSE_BANK
            - TREASURY
        parentVirtualAccountId:
          type: string
          description: Parent virtual account for hierarchical structures
        autoAllocate:
          type: boolean
          description: Whether incoming payments should be auto-allocated
          default: true
        issueViban:
          type: boolean
          description: Whether to automatically issue a virtual IBAN
          default: false
        metadata:
          type: object
          additionalProperties:
            type: string
    VirtualAccountUpdate:
      type: object
      description: Virtual account update request
      properties:
        name:
          type: string
        accountHolder:
          type: string
        autoAllocate:
          type: boolean
        metadata:
          type: object
          additionalProperties:
            type: string
    VirtualAccount:
      type: object
      description: Virtual account details
      properties:
        accountId:
          type: string
          description: Unique virtual account identifier
        name:
          type: string
        physicalAccountId:
          type: string
        currency:
          type: string
        accountHolder:
          type: string
        purpose:
          type: string
        status:
          type: string
          enum:
            - active
            - suspended
            - closed
        virtualIban:
          type: string
          description: Associated virtual IBAN if issued
        balance:
          type: number
          format: double
          description: Current balance
        parentVirtualAccountId:
          type: string
        autoAllocate:
          type: boolean
        metadata:
          type: object
          additionalProperties:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    VirtualAccountList:
      type: object
      properties:
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/VirtualAccount'
        pagination:
          $ref: '#/components/schemas/Pagination'
    VirtualAccountBalance:
      type: object
      description: Virtual account balance information
      properties:
        accountId:
          type: string
        currency:
          type: string
        availableBalance:
          type: number
          format: double
        bookedBalance:
          type: number
          format: double
        pendingCredits:
          type: number
          format: double
        pendingDebits:
          type: number
          format: double
        asOf:
          type: string
          format: date-time
    VirtualIbanCreate:
      type: object
      description: Virtual IBAN issuance request
      required:
        - virtualAccountId
      properties:
        virtualAccountId:
          type: string
          description: Virtual account to associate the VIBAN with
        twoWay:
          type: boolean
          description: Whether the VIBAN supports both incoming and outgoing
          default: false
        countryCode:
          type: string
          description: Country code for IBAN generation
          pattern: ^[A-Z]{2}$
    VirtualIban:
      type: object
      description: Virtual IBAN details
      properties:
        vibanId:
          type: string
          description: Unique VIBAN identifier
        iban:
          type: string
          description: The virtual IBAN
        virtualAccountId:
          type: string
          description: Associated virtual account
        status:
          type: string
          enum:
            - active
            - inactive
        twoWay:
          type: boolean
        createdAt:
          type: string
          format: date-time
    VirtualIbanList:
      type: object
      properties:
        virtualIbans:
          type: array
          items:
            $ref: '#/components/schemas/VirtualIban'
        pagination:
          $ref: '#/components/schemas/Pagination'
    VirtualTransactionList:
      type: object
      properties:
        transactions:
          type: array
          items:
            type: object
            properties:
              transactionId:
                type: string
              type:
                type: string
                enum:
                  - incoming
                  - outgoing
                  - internal_transfer
                  - allocation
              amount:
                type: number
                format: double
              currency:
                type: string
              creditDebitIndicator:
                type: string
                enum:
                  - CRDT
                  - DBIT
              counterpartyName:
                type: string
              counterpartyAccount:
                type: string
              reference:
                type: string
              bookingDate:
                type: string
                format: date
              valueDate:
                type: string
                format: date
              createdAt:
                type: string
                format: date-time
        pagination:
          $ref: '#/components/schemas/Pagination'
    AccountStructureCreate:
      type: object
      description: Account structure creation request
      required:
        - name
        - physicalAccountId
      properties:
        name:
          type: string
          description: Structure name
        physicalAccountId:
          type: string
          description: Root physical account
        type:
          type: string
          enum:
            - POBO
            - COBO
            - IN_HOUSE_BANK
            - ESCROW
            - GENERAL
        description:
          type: string
    AccountStructure:
      type: object
      description: Account hierarchy structure
      properties:
        structureId:
          type: string
        name:
          type: string
        physicalAccountId:
          type: string
        type:
          type: string
        virtualAccounts:
          type: array
          items:
            $ref: '#/components/schemas/VirtualAccount'
        createdAt:
          type: string
          format: date-time
    AccountStructureList:
      type: object
      properties:
        structures:
          type: array
          items:
            $ref: '#/components/schemas/AccountStructure'
    InternalTransfer:
      type: object
      description: Internal transfer between virtual accounts
      required:
        - sourceAccountId
        - destinationAccountId
        - amount
        - currency
      properties:
        sourceAccountId:
          type: string
          description: Source virtual account ID
        destinationAccountId:
          type: string
          description: Destination virtual account ID
        amount:
          type: number
          format: double
          minimum: 0.01
        currency:
          type: string
          pattern: ^[A-Z]{3}$
        reference:
          type: string
          description: Transfer reference
    InternalTransferResponse:
      type: object
      properties:
        transferId:
          type: string
        sourceAccountId:
          type: string
        destinationAccountId:
          type: string
        amount:
          type: number
          format: double
        currency:
          type: string
        status:
          type: string
          enum:
            - COMPLETED
            - FAILED
        processedAt:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        page:
          type: integer
        pageSize:
          type: integer
        totalItems:
          type: integer
        totalPages:
          type: integer
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
security:
  - bearerAuth: []
  - apiKey: []