openapi: 3.1.0
info:
  title: Montran Corporate Payments Portal Account Information Instant 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: Instant Payments
  description: Real-time instant payment processing with guaranteed end-to-end latency of a few seconds
paths:
  /payments/instant:
    post:
      operationId: initiateInstantPayment
      summary: Montran Initiate an instant payment
      description: Initiates a real-time instant payment with guaranteed end-to-end processing latency of a few seconds. The payment is processed using ISO 20022 pacs.008 FIToFICustomerCreditTransfer messaging. Supports credit transfers across instant payment schemes. Returns the payment status synchronously, including confirmation or rejection.
      tags:
      - Instant Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstantPaymentRequest'
      responses:
        '201':
          description: Instant payment successfully processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstantPaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: Service temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /payments/instant/{paymentId}:
    get:
      operationId: getInstantPayment
      summary: Montran Get instant payment details
      description: Retrieves the full details and current status of a specific instant payment. Returns ISO 20022 pacs.002 status information including acceptance or rejection reason codes.
      tags:
      - Instant Payments
      parameters:
      - $ref: '#/components/parameters/PaymentIdParam'
      responses:
        '200':
          description: Successfully retrieved instant payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstantPaymentDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /payments/instant/{paymentId}/return:
    post:
      operationId: returnInstantPayment
      summary: Montran Return an instant payment
      description: Initiates the return of a previously received instant payment. Uses ISO 20022 pacs.004 PaymentReturn messaging. The return must specify a valid reason code.
      tags:
      - Instant Payments
      parameters:
      - $ref: '#/components/parameters/PaymentIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentReturnRequest'
      responses:
        '200':
          description: Payment return successfully initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReturnResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Payment cannot be returned in its current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /payments/bulk:
    post:
      operationId: submitBulkPayment
      summary: Montran Submit a bulk payment
      description: Submits a batch of instant payments for processing. Each payment in the batch is processed individually in real-time. Supports high-volume use cases such as salary payments and batch collections.
      tags:
      - Instant Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPaymentRequest'
      responses:
        '202':
          description: Bulk payment accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkPaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    PaymentReturnResponse:
      type: object
      description: Response for a payment return
      properties:
        returnId:
          type: string
          description: Unique return identifier
        originalPaymentId:
          type: string
          description: Original payment identifier
        status:
          type: string
          enum:
          - PROCESSED
          - REJECTED
        processedAt:
          type: string
          format: date-time
    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
    InstantPaymentResponse:
      type: object
      description: Response for an instant payment including real-time status
      properties:
        paymentId:
          type: string
          description: Unique payment identifier
        messageId:
          type: string
          description: Message identification
        endToEndId:
          type: string
          description: End-to-end identification
        transactionId:
          type: string
          description: Transaction identification
        status:
          type: string
          description: Payment processing status (ISO 20022 status codes)
          enum:
          - ACCP
          - ACSC
          - ACSP
          - RJCT
        reasonCode:
          type: string
          description: Rejection reason code if status is RJCT
        settlementDate:
          type: string
          format: date
          description: Settlement date
        acceptanceDateTime:
          type: string
          format: date-time
          description: Timestamp of payment acceptance
    BulkPaymentResponse:
      type: object
      description: Response for a bulk payment submission
      properties:
        bulkPaymentId:
          type: string
          description: Unique bulk payment identifier
        batchId:
          type: string
          description: Client batch identifier
        status:
          type: string
          enum:
          - ACCEPTED
          - PARTIALLY_ACCEPTED
          - REJECTED
        acceptedCount:
          type: integer
          description: Number of accepted payments
        rejectedCount:
          type: integer
          description: Number of rejected payments
        paymentResults:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: Index of the payment in the original batch
              paymentId:
                type: string
              status:
                type: string
                enum:
                - ACCP
                - RJCT
              reasonCode:
                type: string
    FinancialInstitution:
      type: object
      description: Financial institution identification
      properties:
        bic:
          type: string
          description: Bank Identifier Code (SWIFT/BIC)
          pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
        name:
          type: string
          description: Name of the financial institution
    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}$
    InstantPaymentDetail:
      type: object
      description: Full instant payment details
      properties:
        paymentId:
          type: string
        messageId:
          type: string
        endToEndId:
          type: string
        transactionId:
          type: string
        status:
          type: string
          enum:
          - ACCP
          - ACSC
          - ACSP
          - RJCT
          - CANC
          - RTND
        debtorName:
          type: string
        debtorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        debtorAgent:
          $ref: '#/components/schemas/FinancialInstitution'
        creditorName:
          type: string
        creditorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        creditorAgent:
          $ref: '#/components/schemas/FinancialInstitution'
        amount:
          type: number
          format: double
        currency:
          type: string
        remittanceInformation:
          type: string
        reasonCode:
          type: string
        settlementDate:
          type: string
          format: date
        acceptanceDateTime:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
    BulkPaymentRequest:
      type: object
      description: Bulk payment submission request
      required:
      - payments
      properties:
        batchId:
          type: string
          description: Client-assigned batch identifier
        numberOfTransactions:
          type: integer
          description: Number of payments in the batch
        controlSum:
          type: number
          format: double
          description: Sum of all payment amounts for validation
        payments:
          type: array
          description: List of instant payment requests
          items:
            $ref: '#/components/schemas/InstantPaymentRequest'
          minItems: 1
    PaymentReturnRequest:
      type: object
      description: Payment return request using ISO 20022 pacs.004 PaymentReturn
      required:
      - reasonCode
      properties:
        reasonCode:
          type: string
          description: Return reason code
          enum:
          - AC01
          - AC04
          - AC06
          - AG01
          - AM05
          - BE04
          - DNOR
          - FOCR
          - MD01
          - MS02
          - RR01
        additionalInformation:
          type: string
          description: Additional return reason information
    InstantPaymentRequest:
      type: object
      description: Instant payment initiation request using ISO 20022 pacs.008 FIToFICustomerCreditTransfer structure
      required:
      - debtorAccount
      - creditorAccount
      - amount
      - currency
      properties:
        messageId:
          type: string
          description: Unique message identification
        endToEndId:
          type: string
          description: End-to-end identification assigned by the initiating party
        transactionId:
          type: string
          description: Unique transaction identification
        debtorName:
          type: string
          description: Name of the debtor (payer)
        debtorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        debtorAgent:
          $ref: '#/components/schemas/FinancialInstitution'
        creditorName:
          type: string
          description: Name of the creditor (payee)
        creditorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        creditorAgent:
          $ref: '#/components/schemas/FinancialInstitution'
        amount:
          type: number
          format: double
          description: Payment amount
          minimum: 0.01
        currency:
          type: string
          description: ISO 4217 currency code
          pattern: ^[A-Z]{3}$
        remittanceInformation:
          type: string
          description: Remittance information or payment reference
        purpose:
          type: string
          description: Purpose code for the payment
        chargeBearer:
          type: string
          enum:
          - SLEV
  responses:
    UnprocessableEntity:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required or credentials invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request - invalid parameters or malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Insufficient permissions or invalid consent
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    PaymentIdParam:
      name: paymentId
      in: path
      required: true
      description: Unique identifier of the payment
      schema:
        type: string
  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/