openapi: 3.1.0
info:
  title: Moniepoint POS Push Payment Authentication Reserved Accounts API
  description: 'Push payment-request flow for Moniepoint POS terminals. ISV partners push an authenticated payment request to a registered terminal serial number; the merchant taps to accept and the terminal completes a card or bank-transfer collection routed through Moniepoint''s acquiring rails. API client credentials (client id and client secret) are issued from the Moniepoint Business dashboard.

    '
  version: '1.0'
  contact:
    name: Moniepoint POS Developer Support
    url: https://teamapt.atlassian.net/wiki/spaces/EI
servers:
- url: https://pos.moniepoint.com
  description: Production
security:
- BasicAuth: []
tags:
- name: Reserved Accounts
  description: Manage dedicated and invoice reserved NUBAN accounts.
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'
components:
  schemas:
    UpdateKycRequest:
      type: object
      properties:
        accountReference:
          type: string
        bvn:
          type: string
        nin:
          type: string
    ReservedAccountEnvelope:
      type: object
      properties:
        requestSuccessful:
          type: boolean
        responseMessage:
          type: string
        responseCode:
          type: string
        responseBody:
          $ref: '#/components/schemas/ReservedAccount'
    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
    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
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: Basic auth using API client id and client secret from the Moniepoint Business dashboard.