openapi: 3.1.0
info:
  title: Monnify Invoices API
  description: >
    Create static and dynamic invoices that generate hosted payment pages
    and unique reserved accounts. Static invoices have a fixed amount and
    description; dynamic invoices let the customer pay any amount within a
    configured range.
  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: Invoices
    description: Create, list, and manage invoices.
paths:
  /api/v1/invoice/create:
    post:
      summary: Monnify Create Invoice
      operationId: createInvoice
      tags: [Invoices]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateInvoiceRequest' }
      responses:
        '200':
          description: Invoice created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceEnvelope'
  /api/v1/invoice/{invoiceReference}/details:
    get:
      summary: Monnify Get Invoice Details
      operationId: getInvoice
      tags: [Invoices]
      parameters:
        - name: invoiceReference
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Invoice details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceEnvelope'
  /api/v1/invoice/all:
    get:
      summary: Monnify List Invoices
      operationId: listInvoices
      tags: [Invoices]
      responses:
        '200':
          description: Invoice list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestSuccessful: { type: boolean }
                  responseMessage: { type: string }
                  responseCode: { type: string }
                  responseBody:
                    type: array
                    items: { $ref: '#/components/schemas/Invoice' }
  /api/v1/invoice/{invoiceReference}/cancel:
    delete:
      summary: Monnify Cancel Invoice
      operationId: cancelInvoice
      tags: [Invoices]
      parameters:
        - name: invoiceReference
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Invoice cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceEnvelope'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CreateInvoiceRequest:
      type: object
      required: [amount, invoiceReference, description, currencyCode, contractCode, customerEmail, customerName, expiryDate]
      properties:
        amount: { type: number }
        invoiceReference: { type: string }
        description: { type: string }
        currencyCode: { type: string, default: NGN }
        contractCode: { type: string }
        customerEmail: { type: string, format: email }
        customerName: { type: string }
        expiryDate: { type: string, format: date-time }
        paymentMethods:
          type: array
          items: { type: string, enum: [CARD, ACCOUNT_TRANSFER] }
        redirectUrl: { type: string, format: uri }
        incomeSplitConfig:
          type: array
          items:
            type: object
            properties:
              subAccountCode: { type: string }
              feePercentage: { type: number }
              splitPercentage: { type: number }
              feeBearer: { type: boolean }
    Invoice:
      type: object
      properties:
        invoiceReference: { type: string }
        amount: { type: number }
        currencyCode: { type: string }
        customerEmail: { type: string }
        customerName: { type: string }
        checkoutUrl: { type: string, format: uri }
        accountNumber: { type: string }
        accountName: { type: string }
        bankCode: { type: string }
        bankName: { type: string }
        status: { type: string, enum: [PENDING, PAID, OVERPAID, PARTIALLY_PAID, EXPIRED, CANCELLED] }
        expiryDate: { type: string, format: date-time }
        dateCreated: { type: string, format: date-time }
    InvoiceEnvelope:
      type: object
      properties:
        requestSuccessful: { type: boolean }
        responseMessage: { type: string }
        responseCode: { type: string }
        responseBody: { $ref: '#/components/schemas/Invoice' }