openapi: 3.1.0
info:
  title: Monnify Direct Debit API
  description: >
    Create, activate, and debit recurring NIBSS direct-debit mandates
    against a customer's bank account. Smart routing introduced in
    September 2025 uses TeamApt as the primary processor with NIBSS as
    fallback. As of April 2026 the debit endpoint accepts an incomeSplit
    object to settle a debited amount across multiple sub-accounts.
  version: '1.0'
  contact:
    name: Monnify Developer Support
    url: https://developers.monnify.com
servers:
  - url: https://api.monnify.com
    description: Production
  - url: https://sandbox.monnify.com
    description: Sandbox
security:
  - BearerAuth: []
tags:
  - name: Mandates
    description: Create and manage direct-debit mandates.
  - name: Debits
    description: Initiate debits against an active mandate.
paths:
  /api/v1/direct-debit/mandate:
    post:
      summary: Monnify Create Direct Debit Mandate
      operationId: createMandate
      tags: [Mandates]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMandateRequest'
      responses:
        '200':
          description: Mandate created (pending activation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateEnvelope'
  /api/v1/direct-debit/mandate/{mandateCode}:
    get:
      summary: Monnify Get Direct Debit Mandate
      operationId: getMandate
      tags: [Mandates]
      parameters:
        - name: mandateCode
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Mandate details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateEnvelope'
    delete:
      summary: Monnify Cancel Direct Debit Mandate
      operationId: cancelMandate
      tags: [Mandates]
      parameters:
        - name: mandateCode
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Mandate cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateEnvelope'
  /api/v1/direct-debit/mandate/activation:
    post:
      summary: Monnify Activate Direct Debit Mandate
      description: Submit the activation code to move a mandate from PENDING to ACTIVATED.
      operationId: activateMandate
      tags: [Mandates]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [mandateCode, activationCode]
              properties:
                mandateCode: { type: string }
                activationCode: { type: string }
      responses:
        '200':
          description: Mandate activated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateEnvelope'
  /api/v1/direct-debit/mandate/debit:
    post:
      summary: Monnify Debit Direct Debit Mandate
      description: Debit a configured amount against an active mandate. Supports incomeSplit (April 2026).
      operationId: debitMandate
      tags: [Debits]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DebitMandateRequest'
      responses:
        '200':
          description: Debit accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebitEnvelope'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CreateMandateRequest:
      type: object
      required: [mandateDescription, mandateAmount, customerName, customerAccountNumber, customerBankCode, startDate, endDate]
      properties:
        mandateDescription: { type: string }
        mandateAmount: { type: number }
        customerName: { type: string }
        customerEmail: { type: string, format: email }
        customerPhoneNumber: { type: string }
        customerAccountNumber: { type: string }
        customerBankCode: { type: string }
        startDate: { type: string, format: date }
        endDate: { type: string, format: date }
        frequency: { type: string, enum: [DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY, AD_HOC] }
        amountType: { type: string, enum: [FIXED, VARIABLE] }
        debitReference: { type: string }
        contractCode: { type: string }
    Mandate:
      type: object
      properties:
        mandateCode: { type: string }
        mandateDescription: { type: string }
        mandateAmount: { type: number }
        customerName: { type: string }
        customerAccountNumber: { type: string }
        customerBankCode: { type: string }
        status: { type: string, enum: [PENDING, FAILED, CANCELLED, ACTIVATED, EXPIRED] }
        frequency: { type: string }
        amountType: { type: string }
        startDate: { type: string, format: date }
        endDate: { type: string, format: date }
        dateCreated: { type: string, format: date-time }
    MandateEnvelope:
      type: object
      properties:
        requestSuccessful: { type: boolean }
        responseMessage: { type: string }
        responseCode: { type: string }
        responseBody: { $ref: '#/components/schemas/Mandate' }
    DebitMandateRequest:
      type: object
      required: [mandateCode, amount, debitReference, narration]
      properties:
        mandateCode: { type: string }
        amount: { type: number }
        debitReference: { type: string }
        narration: { type: string }
        incomeSplit:
          type: array
          description: Optional split of the debited amount across sub-accounts (April 2026).
          items:
            type: object
            properties:
              subAccountCode: { type: string }
              splitPercentage: { type: number }
              splitAmount: { type: number }
              feeBearer: { type: boolean }
    DebitEnvelope:
      type: object
      properties:
        requestSuccessful: { type: boolean }
        responseMessage: { type: string }
        responseCode: { type: string }
        responseBody:
          type: object
          properties:
            mandateCode: { type: string }
            debitReference: { type: string }
            amount: { type: number }
            transactionReference: { type: string }
            status: { type: string, enum: [SUCCESS, FAILED, PENDING] }
            dateCreated: { type: string, format: date-time }