openapi: 3.1.0
info:
  title: Monnify Wallets API
  description: >
    Create wallets and sub-wallets, query main and disbursement balances,
    list transactions, and pull statements. Used to fund disbursement
    operations and to model end-user wallets in business-management
    products.
  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: Wallets
    description: Manage wallets and sub-wallets.
paths:
  /api/v1/disbursements/wallet:
    post:
      summary: Monnify Create Wallet
      operationId: createWallet
      tags: [Wallets]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [walletReference, walletName, customerEmail, bvnDetails]
              properties:
                walletReference: { type: string }
                walletName: { type: string }
                customerName: { type: string }
                customerEmail: { type: string, format: email }
                bvnDetails:
                  type: object
                  properties:
                    bvn: { type: string }
                    bvnDateOfBirth: { type: string, format: date }
      responses:
        '200':
          description: Wallet created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletEnvelope'
    get:
      summary: Monnify List Wallets
      operationId: listWallets
      tags: [Wallets]
      parameters:
        - name: customerEmail
          in: query
          schema: { type: string, format: email }
      responses:
        '200':
          description: Wallet list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestSuccessful: { type: boolean }
                  responseMessage: { type: string }
                  responseCode: { type: string }
                  responseBody:
                    type: array
                    items: { $ref: '#/components/schemas/Wallet' }
  /api/v1/disbursements/wallet-balance:
    get:
      summary: Monnify Get Wallet Balance
      operationId: getWalletBalance
      tags: [Wallets]
      parameters:
        - name: accountNumber
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Available and ledger balance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestSuccessful: { type: boolean }
                  responseMessage: { type: string }
                  responseCode: { type: string }
                  responseBody:
                    type: object
                    properties:
                      availableBalance: { type: number }
                      ledgerBalance: { type: number }
  /api/v1/disbursements/wallet/transactions:
    get:
      summary: Monnify List Wallet Transactions
      operationId: listWalletTransactions
      tags: [Wallets]
      parameters:
        - name: walletReference
          in: query
          required: true
          schema: { type: string }
        - name: pageNo
          in: query
          schema: { type: integer, default: 0 }
        - name: pageSize
          in: query
          schema: { type: integer, default: 20 }
      responses:
        '200':
          description: Wallet 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: { $ref: '#/components/schemas/WalletTransaction' }
                      totalElements: { type: integer }
                      totalPages: { type: integer }
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Wallet:
      type: object
      properties:
        walletReference: { type: string }
        walletName: { type: string }
        accountNumber: { type: string }
        accountName: { type: string }
        bankCode: { type: string }
        bankName: { type: string }
        customerName: { type: string }
        customerEmail: { type: string }
        dateCreated: { type: string, format: date-time }
    WalletTransaction:
      type: object
      properties:
        transactionReference: { type: string }
        amount: { type: number }
        type: { type: string, enum: [CREDIT, DEBIT] }
        narration: { type: string }
        balanceAfter: { type: number }
        dateCreated: { type: string, format: date-time }
    WalletEnvelope:
      type: object
      properties:
        requestSuccessful: { type: boolean }
        responseMessage: { type: string }
        responseCode: { type: string }
        responseBody: { $ref: '#/components/schemas/Wallet' }