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: []