openapi: 3.1.0
info:
  title: Moniepoint POS Push Payment Authentication Verification 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: Verification
  description: Identity, BVN, NIN, and account verification.
paths:
  /api/v1/disbursements/account/validate:
    get:
      summary: Monnify Validate Bank Account
      description: Returns the registered account name for a bank account number and bank code.
      operationId: validateAccount
      tags:
      - Verification
      parameters:
      - name: accountNumber
        in: query
        required: true
        schema:
          type: string
      - name: bankCode
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Account holder name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountValidationEnvelope'
  /api/v1/vas/bvn-account-match:
    post:
      summary: Monnify Match BVN To Bank Account
      description: Verify that a BVN belongs to the owner of a given bank account.
      operationId: matchBvnToAccount
      tags:
      - Verification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - bvn
              - bankCode
              - accountNumber
              properties:
                bvn:
                  type: string
                bankCode:
                  type: string
                accountNumber:
                  type: string
      responses:
        '200':
          description: BVN match result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BvnMatchEnvelope'
  /api/v1/vas/bvn-details/{bvn}:
    get:
      summary: Monnify Get BVN Details
      description: Returns demographic details associated with a BVN.
      operationId: getBvnDetails
      tags:
      - Verification
      parameters:
      - name: bvn
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: BVN details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BvnDetailsEnvelope'
  /api/v1/vas/verify-nin:
    post:
      summary: Monnify Verify NIN
      description: Validate a National Identification Number (NIN) against demographic details.
      operationId: verifyNin
      tags:
      - Verification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - nin
              properties:
                nin:
                  type: string
                dateOfBirth:
                  type: string
                  format: date
                phoneNumber:
                  type: string
      responses:
        '200':
          description: NIN verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NinEnvelope'
components:
  schemas:
    BvnDetailsEnvelope:
      type: object
      properties:
        requestSuccessful:
          type: boolean
        responseMessage:
          type: string
        responseCode:
          type: string
        responseBody:
          type: object
          properties:
            bvn:
              type: string
            firstName:
              type: string
            middleName:
              type: string
            lastName:
              type: string
            dateOfBirth:
              type: string
              format: date
            phoneNumber:
              type: string
            gender:
              type: string
            registrationDate:
              type: string
              format: date
    BvnMatchEnvelope:
      type: object
      properties:
        requestSuccessful:
          type: boolean
        responseMessage:
          type: string
        responseCode:
          type: string
        responseBody:
          type: object
          properties:
            bvn:
              type: string
            accountNumber:
              type: string
            bankCode:
              type: string
            matchStatus:
              type: string
              enum:
              - MATCHED
              - PARTIAL_MATCH
              - NO_MATCH
    NinEnvelope:
      type: object
      properties:
        requestSuccessful:
          type: boolean
        responseMessage:
          type: string
        responseCode:
          type: string
        responseBody:
          type: object
          properties:
            nin:
              type: string
            firstName:
              type: string
            lastName:
              type: string
            dateOfBirth:
              type: string
              format: date
            phoneNumber:
              type: string
            matched:
              type: boolean
    AccountValidationEnvelope:
      type: object
      properties:
        requestSuccessful:
          type: boolean
        responseMessage:
          type: string
        responseCode:
          type: string
        responseBody:
          type: object
          properties:
            accountNumber:
              type: string
            accountName:
              type: string
            bankCode:
              type: string
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: Basic auth using API client id and client secret from the Moniepoint Business dashboard.