Montran Account Information API

openapi: 3.2.0
info:
  title: Montran Instant Payments Gateway Account Information API
  description: The Montran Instant Payments Gateway (IPG) enables participants in an instant payments ecosystem to support high volumes of instant payments in a high availability 24x7 environment.
  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
servers:
- url: https://api.montran.com/ipg/v1
  description: Montran Instant Payments Gateway API Server
security:
- oauth2:
  - aisp
  - pisp
- bearerAuth: []
tags:
- name: Account Information
  description: PSD2-compliant account information operations for AISP integration. Provides account details, balances, and transaction history.
paths:
  /accounts:
    get:
      operationId: listAccounts
      summary: Montran List accessible accounts (AISP)
      description: Retrieves a list of payment accounts accessible to the Account Information Service Provider (AISP) under an authorized PSD2 consent. Provides account identification, type, currency, and basic balance information.
      tags:
      - Account Information
      parameters:
      - name: consentId
        in: query
        required: true
        description: PSD2 consent identifier authorizing access
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved list of accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /accounts/{accountId}:
    get:
      operationId: getAccountDetails
      summary: Montran Get account details (AISP)
      description: Retrieves detailed information about a specific payment account including account holder name, IBAN, currency, and product type. Requires valid PSD2 AISP consent.
      tags:
      - Account Information
      parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - name: consentId
        in: query
        required: true
        description: PSD2 consent identifier
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /accounts/{accountId}/balances:
    get:
      operationId: getAccountBalances
      summary: Montran Get account balances (AISP)
      description: Retrieves the current balances for a specific payment account. Returns available balance, booked balance, and expected balance. Requires valid PSD2 AISP consent.
      tags:
      - Account Information
      parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - name: consentId
        in: query
        required: true
        description: PSD2 consent identifier
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved account balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBalances'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /accounts/{accountId}/transactions:
    get:
      operationId: getAccountTransactions
      summary: Montran Get account transactions (AISP)
      description: Retrieves a list of transactions for a specific payment account. Supports filtering by date range, booking status, and amount. Requires valid PSD2 AISP consent.
      tags:
      - Account Information
      parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - name: consentId
        in: query
        required: true
        description: PSD2 consent identifier
        schema:
          type: string
      - name: dateFrom
        in: query
        description: Start date for transaction filter (ISO 8601)
        schema:
          type: string
          format: date
      - name: dateTo
        in: query
        description: End date for transaction filter (ISO 8601)
        schema:
          type: string
          format: date
      - name: bookingStatus
        in: query
        description: Filter by booking status
        schema:
          type: string
          enum:
          - booked
          - pending
          - both
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageSizeParam'
      responses:
        '200':
          description: Successfully retrieved transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /accounts/{accountId}/verification:
    post:
      operationId: verifyAccountBalance
      summary: Montran Verify account balance sufficiency
      description: Performs a balance sufficiency check on a payment account. Returns whether the account has sufficient funds for the specified amount without disclosing the actual balance. Used for pre-payment validation.
      tags:
      - Account Information
      parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BalanceVerificationRequest'
      responses:
        '200':
          description: Balance verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceVerificationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    PageSizeParam:
      name: pageSize
      in: query
      description: Number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    PageParam:
      name: page
      in: query
      description: Page number for pagination
      schema:
        type: integer
        minimum: 1
        default: 1
    AccountIdParam:
      name: accountId
      in: path
      required: true
      description: Unique identifier of the payment account
      schema:
        type: string
  schemas:
    TransactionList:
      type: object
      description: Paginated list of account transactions
      properties:
        accountId:
          type: string
        transactions:
          type: object
          properties:
            booked:
              type: array
              items:
                $ref: '#/components/schemas/Transaction'
            pending:
              type: array
              items:
                $ref: '#/components/schemas/Transaction'
        pagination:
          $ref: '#/components/schemas/Pagination'
    AccountList:
      type: object
      description: List of accessible payment accounts
      properties:
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/AccountDetail'
    BalanceVerificationRequest:
      type: object
      description: Request to verify account balance sufficiency
      required:
      - amount
      - currency
      properties:
        amount:
          type: number
          format: double
          description: Amount to verify against the account balance
          minimum: 0.01
        currency:
          type: string
          description: Currency of the amount
          pattern: ^[A-Z]{3}$
    Error:
      type: object
      description: Standard error response
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
    Transaction:
      type: object
      description: A single account transaction
      properties:
        transactionId:
          type: string
          description: Unique transaction identifier
        endToEndId:
          type: string
        amount:
          type: number
          format: double
        currency:
          type: string
        creditDebitIndicator:
          type: string
          enum:
          - CRDT
          - DBIT
        bookingDate:
          type: string
          format: date
        valueDate:
          type: string
          format: date
        debtorName:
          type: string
        debtorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        creditorName:
          type: string
        creditorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        remittanceInformation:
          type: string
        bankTransactionCode:
          type: string
    BalanceVerificationResponse:
      type: object
      description: Result of account balance verification
      properties:
        sufficient:
          type: boolean
          description: Whether the account has sufficient funds
        verifiedAt:
          type: string
          format: date-time
    AccountDetail:
      type: object
      description: Payment account details
      properties:
        accountId:
          type: string
          description: Unique account identifier
        iban:
          type: string
          description: International Bank Account Number
        currency:
          type: string
          description: Account currency (ISO 4217)
        name:
          type: string
          description: Account name or description
        ownerName:
          type: string
          description: Name of the account owner
        product:
          type: string
          description: Product name of the account
        status:
          type: string
          enum:
          - enabled
          - deleted
          - blocked
    Pagination:
      type: object
      description: Pagination metadata
      properties:
        page:
          type: integer
        pageSize:
          type: integer
        totalItems:
          type: integer
        totalPages:
          type: integer
    AccountBalances:
      type: object
      description: Account balance information
      properties:
        accountId:
          type: string
        balances:
          type: array
          items:
            type: object
            properties:
              balanceType:
                type: string
                enum:
                - closingBooked
                - expected
                - interimAvailable
                - interimBooked
                - openingBooked
              amount:
                type: number
                format: double
              currency:
                type: string
              creditDebitIndicator:
                type: string
                enum:
                - CRDT
                - DBIT
              referenceDate:
                type: string
                format: date
              lastChangeDateTime:
                type: string
                format: date-time
    AccountIdentification:
      type: object
      description: Account identification using IBAN or proprietary identifier
      properties:
        iban:
          type: string
          description: International Bank Account Number
          pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{4,30}$
        accountNumber:
          type: string
          description: Proprietary account number
        currency:
          type: string
          description: Account currency (ISO 4217)
          pattern: ^[A-Z]{3}$
  responses:
    Forbidden:
      description: Insufficient permissions or invalid consent
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required or credentials invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization for PSD2 AISP/PISP access
      flows:
        authorizationCode:
          authorizationUrl: https://auth.montran.com/oauth2/authorize
          tokenUrl: https://auth.montran.com/oauth2/token
          scopes:
            aisp: Account Information Service Provider access
            pisp: Payment Initiation Service Provider access
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT bearer token authentication
externalDocs:
  description: Montran Instant Payments Gateway Documentation
  url: https://www.montran.com/solutions/instant-payments-gateway/