openapi: 3.1.0
info:
  title: Montran Corporate Payments Portal Account Information Beneficiaries API
  description: The Montran Corporate Payments Portal enables corporates to exercise complete control over accounts at their various bank relationships, with the ability to make secure payments over the Internet. It supports SWIFT payments and local clearing delivery through API integration and H2H (Host-to-Host) protocols. Corporates can connect their ERP systems and manually or automatically upload invoices for payments and collections management. The portal provides multi-bank visibility and supports secure payment initiation across multiple currencies and payment types.
  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/corporate/v1
  description: Montran Corporate Payments Portal API Server
security:
- bearerAuth: []
- apiKey: []
tags:
- name: Beneficiaries
  description: Beneficiary management for recurring payments
paths:
  /beneficiaries:
    get:
      operationId: listBeneficiaries
      summary: Montran List beneficiaries
      description: Retrieves the list of registered payment beneficiaries. Beneficiaries store pre-validated account details for recurring payment recipients.
      tags:
      - Beneficiaries
      parameters:
      - 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 beneficiaries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createBeneficiary
      summary: Montran Create a beneficiary
      description: Registers a new payment beneficiary with pre-validated account details for use in future payments.
      tags:
      - Beneficiaries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficiaryCreate'
      responses:
        '201':
          description: Beneficiary successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Beneficiary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    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
    BeneficiaryCreate:
      type: object
      required:
      - name
      - accountIban
      properties:
        name:
          type: string
          description: Beneficiary name
        accountIban:
          type: string
          description: Beneficiary IBAN
        accountNumber:
          type: string
        bankBic:
          type: string
        bankName:
          type: string
        country:
          type: string
        address:
          type: string
    BeneficiaryList:
      type: object
      properties:
        beneficiaries:
          type: array
          items:
            $ref: '#/components/schemas/Beneficiary'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Beneficiary:
      type: object
      properties:
        beneficiaryId:
          type: string
        name:
          type: string
        accountIban:
          type: string
        accountNumber:
          type: string
        bankBic:
          type: string
        bankName:
          type: string
        country:
          type: string
        status:
          type: string
          enum:
          - active
          - inactive
        createdAt:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
externalDocs:
  description: Montran Corporate Payments Portal Documentation
  url: https://www.montran.com/solutions/corporate-payments-portal/