openapi: 3.1.0
info:
  title: Montran Corporate Payments Portal Account Information Direct Debits 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: Direct Debits
  description: Direct debit payment operations
paths:
  /direct-debits:
    post:
      operationId: initiateDirectDebit
      summary: Montran Initiate a direct debit
      description: Initiates a direct debit collection using ISO 20022 pain.008 CustomerDirectDebitInitiation format. Supports SEPA Direct Debit (Core and B2B schemes) and local ACH direct debit schemes.
      tags:
      - Direct Debits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectDebitInitiation'
      responses:
        '201':
          description: Direct debit successfully initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    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
          description: Detailed error information
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that caused the error
              message:
                type: string
                description: Error detail message
    PaymentResponse:
      type: object
      description: Response returned after successful payment initiation
      properties:
        paymentId:
          type: string
          description: Unique payment identifier assigned by the system
        messageId:
          type: string
          description: Original message identification
        endToEndId:
          type: string
          description: End-to-end identification
        status:
          type: string
          description: Current payment status
          enum:
          - RECEIVED
          - VALIDATED
          - PENDING
        clearingSystem:
          type: string
          description: Assigned clearing and settlement mechanism
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the payment was created
    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
        clearingSystemMemberId:
          type: string
          description: Clearing system member identification
    AccountIdentification:
      type: object
      description: Account identification using IBAN or proprietary account number
      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}$
    DirectDebitInitiation:
      type: object
      description: Direct debit initiation request aligned with ISO 20022 pain.008 CustomerDirectDebitInitiation
      required:
      - creditorAccount
      - debtorAccount
      - amount
      - currency
      - mandateId
      properties:
        messageId:
          type: string
          description: Unique message identification
        creditorName:
          type: string
          description: Name of the creditor (collector)
        creditorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        creditorAgent:
          $ref: '#/components/schemas/FinancialInstitution'
        debtorName:
          type: string
          description: Name of the debtor
        debtorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        debtorAgent:
          $ref: '#/components/schemas/FinancialInstitution'
        amount:
          type: number
          format: double
          description: Instructed amount
          minimum: 0.01
        currency:
          type: string
          description: ISO 4217 currency code
          pattern: ^[A-Z]{3}$
        requestedCollectionDate:
          type: string
          format: date
          description: Requested collection date
        mandateId:
          type: string
          description: Direct debit mandate identification
        mandateDateOfSignature:
          type: string
          format: date
          description: Date the mandate was signed
        sequenceType:
          type: string
          description: Sequence type of the direct debit
          enum:
          - FRST
          - RCUR
          - FNAL
          - OOFF
        schemeType:
          type: string
          description: Direct debit scheme type
          enum:
          - CORE
          - B2B
        endToEndId:
          type: string
          description: End-to-end identification
        remittanceInformation:
          type: string
          description: Remittance information
  responses:
    Unauthorized:
      description: Authentication required or credentials invalid
      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'
    UnprocessableEntity:
      description: Request 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/