openapi: 3.1.0
info:
  title: Moniepoint POS Push Payment 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: Push Payments
    description: Initiate push payments to a registered POS terminal.
paths:
  /api/v1/push-payment/request:
    post:
      summary: Moniepoint Push Payment Request
      description: >
        Push a payment request to a specific Moniepoint POS terminal. The
        terminal prompts the cashier to confirm and present the card or
        transfer instructions to the customer.
      operationId: pushPaymentRequest
      tags: [Push Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushPaymentRequest'
      responses:
        '200':
          description: Push accepted; terminal awaiting customer action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushPaymentEnvelope'
  /api/v1/push-payment/status/{reference}:
    get:
      summary: Moniepoint Push Payment Status
      operationId: pushPaymentStatus
      tags: [Push Payments]
      parameters:
        - name: reference
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Payment status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushPaymentEnvelope'
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: Basic auth using API client id and client secret from the Moniepoint Business dashboard.
  schemas:
    PushPaymentRequest:
      type: object
      required: [terminalSerialNumber, amount, reference, currency]
      properties:
        terminalSerialNumber: { type: string }
        amount: { type: number }
        reference: { type: string, description: Unique ISV reference. }
        currency: { type: string, default: NGN }
        description: { type: string }
        callbackUrl: { type: string, format: uri }
        expiresIn: { type: integer, description: Seconds before the terminal cancels the request. }
    PushPayment:
      type: object
      properties:
        terminalSerialNumber: { type: string }
        reference: { type: string }
        amount: { type: number }
        currency: { type: string }
        status: { type: string, enum: [PENDING, ACCEPTED, COMPLETED, DECLINED, EXPIRED, FAILED] }
        responseCode: { type: string }
        responseMessage: { type: string }
        paymentMethod: { type: string, enum: [CARD, TRANSFER] }
        dateCreated: { type: string, format: date-time }
        completedAt: { type: string, format: date-time }
    PushPaymentEnvelope:
      type: object
      properties:
        requestSuccessful: { type: boolean }
        responseMessage: { type: string }
        responseCode: { type: string }
        responseBody: { $ref: '#/components/schemas/PushPayment' }