openapi: 3.1.0
info:
  title: Monnify Sub-Accounts API
  description: >
    Create and manage settlement sub-accounts representing third parties
    that should receive a configured share of each collection (marketplaces,
    franchises, multi-tenant platforms). Sub-accounts are referenced from
    Collections (incomeSplitConfig), Reserved Accounts, and Direct Debit
    mandate-debit calls.
  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: Sub-Accounts
    description: Manage settlement sub-accounts.
paths:
  /api/v1/sub-accounts:
    post:
      summary: Monnify Create Sub-Accounts
      description: Create one or more sub-accounts in a single call.
      operationId: createSubAccounts
      tags: [Sub-Accounts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items: { $ref: '#/components/schemas/SubAccount' }
      responses:
        '200':
          description: Sub-accounts created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubAccountListEnvelope'
    put:
      summary: Monnify Update Sub-Account
      operationId: updateSubAccount
      tags: [Sub-Accounts]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SubAccount' }
      responses:
        '200':
          description: Sub-account updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubAccountEnvelope'
    get:
      summary: Monnify List Sub-Accounts
      operationId: listSubAccounts
      tags: [Sub-Accounts]
      responses:
        '200':
          description: Sub-account list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubAccountListEnvelope'
  /api/v1/sub-accounts/{subAccountCode}:
    delete:
      summary: Monnify Delete Sub-Account
      operationId: deleteSubAccount
      tags: [Sub-Accounts]
      parameters:
        - name: subAccountCode
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Sub-account deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestSuccessful: { type: boolean }
                  responseMessage: { type: string }
                  responseCode: { type: string }
                  responseBody: { type: object }
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    SubAccount:
      type: object
      required: [currencyCode, bankCode, accountNumber, email]
      properties:
        subAccountCode: { type: string }
        currencyCode: { type: string, example: NGN }
        bankCode: { type: string }
        accountNumber: { type: string }
        email: { type: string, format: email }
        defaultSplitPercentage:
          type: number
          description: Default share of every collection routed to this sub-account.
        feeBearer: { type: boolean, description: When true the sub-account absorbs Monnify's fee. }
        defaultBearer: { type: boolean }
    SubAccountEnvelope:
      type: object
      properties:
        requestSuccessful: { type: boolean }
        responseMessage: { type: string }
        responseCode: { type: string }
        responseBody: { $ref: '#/components/schemas/SubAccount' }
    SubAccountListEnvelope:
      type: object
      properties:
        requestSuccessful: { type: boolean }
        responseMessage: { type: string }
        responseCode: { type: string }
        responseBody:
          type: array
          items: { $ref: '#/components/schemas/SubAccount' }