openapi: 3.1.0
info:
  title: Montran Corporate Payments Portal Account Information Request to Pay 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: Request to Pay
  description: Request-to-pay initiation and management operations
paths:
  /payments/request-to-pay:
    post:
      operationId: initiateRequestToPay
      summary: Montran Initiate a request to pay
      description: Initiates a request-to-pay (R2P) message to request payment from a debtor. The debtor receives the request and can accept or reject it. Supports person-to-person, person-to-merchant, and business-to-business use cases. Uses ISO 20022 pain.013 CreditorPaymentActivationRequest.
      tags:
      - Request to Pay
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestToPayRequest'
      responses:
        '201':
          description: Request to pay successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestToPayResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /payments/request-to-pay/{requestId}:
    get:
      operationId: getRequestToPay
      summary: Montran Get request-to-pay details
      description: Retrieves the details and current status of a request-to-pay. Shows whether the request has been accepted, rejected, or is still pending.
      tags:
      - Request to Pay
      parameters:
      - name: requestId
        in: path
        required: true
        description: Unique identifier of the request to pay
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved request-to-pay details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestToPayDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '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
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
    RequestToPayResponse:
      type: object
      description: Response for a request-to-pay initiation
      properties:
        requestId:
          type: string
          description: Unique request-to-pay identifier
        status:
          type: string
          enum:
          - CREATED
          - SENT
          - REJECTED
        createdAt:
          type: string
          format: date-time
    RequestToPayDetail:
      type: object
      description: Full request-to-pay details with status
      properties:
        requestId:
          type: string
        messageId:
          type: string
        status:
          type: string
          enum:
          - CREATED
          - SENT
          - ACCEPTED
          - REJECTED
          - EXPIRED
          - CANCELLED
        creditorName:
          type: string
        creditorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        debtorName:
          type: string
        debtorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        amount:
          type: number
          format: double
        currency:
          type: string
        expiryDate:
          type: string
          format: date-time
        resultingPaymentId:
          type: string
          description: Payment ID if the request was accepted and payment initiated
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    RequestToPayRequest:
      type: object
      description: Request-to-pay initiation using ISO 20022 pain.013 CreditorPaymentActivationRequest
      required:
      - creditorAccount
      - debtorAccount
      - amount
      - currency
      properties:
        messageId:
          type: string
          description: Unique message identification
        creditorName:
          type: string
          description: Name of the creditor (requester)
        creditorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        debtorName:
          type: string
          description: Name of the debtor (payer)
        debtorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        amount:
          type: number
          format: double
          description: Requested payment amount
          minimum: 0.01
        currency:
          type: string
          description: ISO 4217 currency code
          pattern: ^[A-Z]{3}$
        expiryDate:
          type: string
          format: date-time
          description: Expiry date/time for the request
        remittanceInformation:
          type: string
          description: Remittance information
        purpose:
          type: string
          description: Purpose of the request
    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:
    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'
    NotFound:
      description: Requested resource not found
      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/