openapi: 3.1.0
info:
  title: Monnify Reserved Accounts API
  description: >
    Provision permanent NUBAN virtual accounts (dedicated and invoice
    variants) for customers and merchants. V2 endpoints replace earlier
    /api/v1 routes for new integrations; transaction listing remains under
    /api/v1.
  version: '2.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: Reserved Accounts
    description: Manage dedicated and invoice reserved NUBAN accounts.
  - name: Limit Profiles
    description: Per-account transaction limit profiles.
paths:
  /api/v2/bank-transfer/reserved-accounts:
    post:
      summary: Monnify Reserve A Customer Account (V2)
      description: Create a permanent NUBAN virtual account for a customer.
      operationId: reserveAccountV2
      tags: [Reserved Accounts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReserveAccountRequest'
      responses:
        '200':
          description: Reserved account created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservedAccountEnvelope'
    put:
      summary: Monnify Update Reserved Account KYC
      description: Update BVN, NIN, or customer details for a reserved account.
      operationId: updateReservedAccountKyc
      tags: [Reserved Accounts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateKycRequest'
      responses:
        '200':
          description: KYC updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservedAccountEnvelope'
  /api/v2/bank-transfer/reserved-accounts/{accountReference}:
    get:
      summary: Monnify Get Reserved Account Details (V2)
      description: Fetch a single reserved account by accountReference.
      operationId: getReservedAccountV2
      tags: [Reserved Accounts]
      parameters:
        - name: accountReference
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Reserved account details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservedAccountEnvelope'
    delete:
      summary: Monnify Deallocate Reserved Account
      description: Permanently deallocate a reserved account.
      operationId: deallocateReservedAccount
      tags: [Reserved Accounts]
      parameters:
        - name: accountReference
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Account deallocated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservedAccountEnvelope'
  /api/v1/bank-transfer/reserved-accounts/transactions:
    get:
      summary: Monnify List Reserved Account Transactions
      description: Paginated list of inbound transactions to a reserved account.
      operationId: listReservedAccountTransactions
      tags: [Reserved Accounts]
      parameters:
        - name: accountReference
          in: query
          required: true
          schema: { type: string }
        - name: page
          in: query
          schema: { type: integer, default: 0 }
        - name: size
          in: query
          schema: { type: integer, default: 10 }
      responses:
        '200':
          description: Transaction page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestSuccessful: { type: boolean }
                  responseMessage: { type: string }
                  responseCode: { type: string }
                  responseBody:
                    type: object
                    properties:
                      content:
                        type: array
                        items: { type: object }
                      totalElements: { type: integer }
                      totalPages: { type: integer }
  /api/v1/bank-transfer/reserved-accounts/limit:
    post:
      summary: Monnify Reserve Account With Limit
      description: Create a reserved account with a pre-assigned limit profile.
      operationId: reserveAccountWithLimit
      tags: [Reserved Accounts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ReserveAccountRequest'
                - type: object
                  properties:
                    limitProfileCode: { type: string }
      responses:
        '200':
          description: Reserved account with limit created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservedAccountEnvelope'
    put:
      summary: Monnify Update Reserved Account Limit
      description: Assign or change the limit profile on an existing reserved account.
      operationId: updateReservedAccountLimit
      tags: [Reserved Accounts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountReference, limitProfileCode]
              properties:
                accountReference: { type: string }
                limitProfileCode: { type: string }
      responses:
        '200':
          description: Reserved account limit updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservedAccountEnvelope'
  /api/v1/limit-profiles:
    post:
      summary: Monnify Create Limit Profile
      description: Define a per-transaction and daily cap profile to apply to reserved accounts.
      operationId: createLimitProfile
      tags: [Limit Profiles]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LimitProfile'
      responses:
        '200':
          description: Limit profile created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestSuccessful: { type: boolean }
                  responseMessage: { type: string }
                  responseCode: { type: string }
                  responseBody: { $ref: '#/components/schemas/LimitProfile' }
    get:
      summary: Monnify List Limit Profiles
      description: Paginated list of limit profiles for the merchant.
      operationId: listLimitProfiles
      tags: [Limit Profiles]
      responses:
        '200':
          description: Limit profiles page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestSuccessful: { type: boolean }
                  responseMessage: { type: string }
                  responseCode: { type: string }
                  responseBody:
                    type: object
                    properties:
                      content:
                        type: array
                        items: { $ref: '#/components/schemas/LimitProfile' }
    put:
      summary: Monnify Update Limit Profile
      operationId: updateLimitProfile
      tags: [Limit Profiles]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LimitProfile' }
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestSuccessful: { type: boolean }
                  responseMessage: { type: string }
                  responseCode: { type: string }
                  responseBody: { $ref: '#/components/schemas/LimitProfile' }
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ReserveAccountRequest:
      type: object
      required: [accountReference, accountName, currencyCode, contractCode, customerEmail]
      properties:
        accountReference: { type: string }
        accountName: { type: string }
        currencyCode: { type: string, example: NGN }
        contractCode: { type: string }
        customerEmail: { type: string, format: email }
        customerName: { type: string }
        bvn: { type: string, description: Customer BVN (11 digits). }
        nin: { type: string, description: Customer NIN (11 digits). }
        getAllAvailableBanks: { type: boolean }
        preferredBanks:
          type: array
          items: { type: string, description: Bank code. }
        restrictPaymentSource: { type: boolean }
        allowedPaymentSources:
          type: object
          properties:
            bvns:
              type: array
              items: { type: string }
            accountNumbers:
              type: array
              items:
                type: object
                properties:
                  accountNumber: { type: string }
                  bankCode: { type: string }
            accountNames:
              type: array
              items: { type: string }
        incomeSplitConfig:
          type: array
          items:
            type: object
            properties:
              subAccountCode: { type: string }
              feePercentage: { type: number }
              splitPercentage: { type: number }
              feeBearer: { type: boolean }
    UpdateKycRequest:
      type: object
      properties:
        accountReference: { type: string }
        bvn: { type: string }
        nin: { type: string }
    ReservedAccount:
      type: object
      properties:
        accountReference: { type: string }
        accountName: { type: string }
        currencyCode: { type: string }
        customerEmail: { type: string }
        customerName: { type: string }
        bvn: { type: string }
        nin: { type: string }
        status: { type: string, enum: [ACTIVE, INACTIVE, DEALLOCATED] }
        accounts:
          type: array
          items:
            type: object
            properties:
              bankCode: { type: string }
              bankName: { type: string }
              accountNumber: { type: string }
              accountName: { type: string }
    ReservedAccountEnvelope:
      type: object
      properties:
        requestSuccessful: { type: boolean }
        responseMessage: { type: string }
        responseCode: { type: string }
        responseBody: { $ref: '#/components/schemas/ReservedAccount' }
    LimitProfile:
      type: object
      properties:
        limitProfileCode: { type: string }
        limitProfileName: { type: string }
        singleTransactionValue: { type: number }
        dailyTransactionVolume: { type: integer }
        dailyTransactionValue: { type: number }