openapi: 3.1.0
info:
  title: Montran Corporate Portal Account Information Payments 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: Payments
  description: Corporate payment initiation and management
paths:
  /payments:
    get:
      operationId: listCorporatePayments
      summary: Montran List corporate payments
      description: Retrieves a list of payments initiated through the corporate portal. Supports filtering by payment type, status, bank relationship, currency, and date range. Provides multi-bank payment visibility across all connected bank relationships.
      tags:
      - Payments
      parameters:
      - name: status
        in: query
        description: Filter by payment status
        schema:
          type: string
          enum:
          - draft
          - pending_approval
          - approved
          - submitted
          - accepted
          - rejected
          - settled
          - cancelled
      - name: paymentType
        in: query
        description: Filter by payment type
        schema:
          type: string
          enum:
          - domestic
          - cross_border
          - swift
          - sepa
          - ach
      - name: bankId
        in: query
        description: Filter by bank relationship
        schema:
          type: string
      - name: currency
        in: query
        schema:
          type: string
          pattern: ^[A-Z]{3}$
      - name: fromDate
        in: query
        schema:
          type: string
          format: date
      - name: toDate
        in: query
        schema:
          type: string
          format: date
      - 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 payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorporatePaymentList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createCorporatePayment
      summary: Montran Create a corporate payment
      description: Creates a new payment through the corporate portal. The payment is routed through the appropriate bank relationship and clearing system based on the payment type, destination, and currency. Supports domestic payments, cross-border SWIFT payments, SEPA transfers, and local ACH payments. The payment enters the approval workflow if configured.
      tags:
      - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CorporatePaymentCreate'
      responses:
        '201':
          description: Payment successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorporatePayment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /payments/{paymentId}:
    get:
      operationId: getCorporatePayment
      summary: Montran Get payment details
      description: Retrieves the full details of a corporate payment including its approval status, bank submission status, and settlement information.
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/PaymentIdParam'
      responses:
        '200':
          description: Successfully retrieved payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorporatePayment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /payments/{paymentId}/cancel:
    post:
      operationId: cancelPayment
      summary: Montran Cancel a payment
      description: Requests cancellation of a payment that has not yet been settled. Generates an ISO 20022 camt.056 FIToFIPaymentCancellationRequest message. Cancellation availability depends on the payment status and the clearing system rules.
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/PaymentIdParam_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCancellationRequest'
      responses:
        '200':
          description: Cancellation request successfully submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentCancellationResponse'
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '404':
          $ref: '#/components/responses/NotFound_2'
        '409':
          description: Payment cannot be cancelled in its current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    PaymentIdParam_2:
      name: paymentId
      in: path
      required: true
      description: Unique identifier of the payment
      schema:
        type: string
    PaymentIdParam:
      name: paymentId
      in: path
      required: true
      description: Unique payment identifier
      schema:
        type: string
  responses:
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound_2:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
    Unauthorized_2:
      description: Authentication required or credentials invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
    BadRequest_2:
      description: Bad request - invalid parameters or malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      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'
  schemas:
    PaymentCancellationResponse:
      type: object
      description: Response to a payment cancellation request
      properties:
        paymentId:
          type: string
          description: Payment identifier
        cancellationStatus:
          type: string
          description: Status of the cancellation request
          enum:
          - ACCEPTED
          - PENDING
          - REJECTED
        reasonCode:
          type: string
          description: Reason code if cancellation was rejected
        processedAt:
          type: string
          format: date-time
    CorporatePaymentList:
      type: object
      properties:
        payments:
          type: array
          items:
            $ref: '#/components/schemas/CorporatePayment'
        pagination:
          $ref: '#/components/schemas/Pagination'
    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
    CorporatePayment:
      type: object
      description: Corporate payment details
      properties:
        paymentId:
          type: string
        paymentType:
          type: string
        status:
          type: string
          enum:
          - draft
          - pending_approval
          - approved
          - submitted
          - accepted
          - rejected
          - settled
          - cancelled
        debitAccountId:
          type: string
        beneficiaryName:
          type: string
        beneficiaryAccount:
          type: object
          properties:
            iban:
              type: string
            accountNumber:
              type: string
            bankBic:
              type: string
        amount:
          type: number
          format: double
        currency:
          type: string
        valueDate:
          type: string
          format: date
        reference:
          type: string
        approvalStatus:
          type: object
          properties:
            requiredApprovals:
              type: integer
            currentApprovals:
              type: integer
            approvers:
              type: array
              items:
                type: object
                properties:
                  userId:
                    type: string
                  approvedAt:
                    type: string
                    format: date-time
                  comment:
                    type: string
        bankReference:
          type: string
          description: Reference assigned by the bank
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PaymentCancellationRequest:
      type: object
      description: Payment cancellation request aligned with ISO 20022 camt.056 FIToFIPaymentCancellationRequest
      required:
      - reason
      properties:
        reason:
          type: string
          description: Cancellation reason code
          enum:
          - DUPL
          - AGNT
          - CURR
          - CUST
          - UPAY
          - FRAD
          - TECH
        additionalInformation:
          type: string
          description: Additional information about the cancellation request
    Pagination:
      type: object
      properties:
        page:
          type: integer
        pageSize:
          type: integer
        totalItems:
          type: integer
        totalPages:
          type: integer
    CorporatePaymentCreate:
      type: object
      description: Corporate payment creation request
      required:
      - debitAccountId
      - beneficiaryAccount
      - amount
      - currency
      - paymentType
      properties:
        paymentType:
          type: string
          enum:
          - domestic
          - cross_border
          - swift
          - sepa
          - ach
        debitAccountId:
          type: string
          description: Debit account identifier
        beneficiaryId:
          type: string
          description: Registered beneficiary ID (if using saved beneficiary)
        beneficiaryName:
          type: string
          description: Beneficiary name
        beneficiaryAccount:
          type: object
          properties:
            iban:
              type: string
            accountNumber:
              type: string
            bankBic:
              type: string
            bankName:
              type: string
            country:
              type: string
        amount:
          type: number
          format: double
          minimum: 0.01
        currency:
          type: string
          pattern: ^[A-Z]{3}$
        valueDate:
          type: string
          format: date
        reference:
          type: string
          description: Payment reference
        remittanceInformation:
          type: string
        chargeBearer:
          type: string
          enum:
          - OUR
          - BEN
          - SHA
        urgency:
          type: string
          enum:
          - NORMAL
          - URGENT
    Error_2:
      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
          description: Detailed error information
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that caused the error
              message:
                type: string
                description: Error detail message
  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/