openapi: 3.0.1
info:
  title: Account TopUp
  description: This API facilitates the management of CustomerAccount capabilities.
    It provides a generic API any client or back-end can call to request a TopUp function
    that allows a reseller to refill/credit a subscriber airtime account from the
    reseller’s account
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: 3.0.0 - Last updated date:2026-09-07 09:17:03
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: AccountTopUp
paths:
  /accounts/{recipientPhoneNumber}/topUp:
    post:
      tags:
      - AccountTopUp
      summary: Provides the ability to request a TopUp on a specified balanceType
      description: "This operation enables clients and integrated back-end systems\
        \ to initiate a secure and auditable top up on a subscriber account by specifying\
        \ the 'recipientPhoneNumber' and a valid request payload, including the requested\
        \ monetary amount, currency, and associated metadata required for processing.\
        \ It ensures that the account balance adjustment is validated, recorded, and\
        \ returned with a canonical response structure for consistent downstream handling."
      operationId: AccountTopUp_post_topUp_accountsrecipientPho
      parameters:
      - name: recipientPhoneNumber
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-channel-id
        in: header
        required: true
        schema:
          type: string
      - name: x-country-code
        in: header
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: BalanceTopUpRequest
              type: object
              properties:
                currency:
                  type: string
                clientReference:
                  type: string
                balanceType:
                  type: string
                senderAccountId:
                  type: string
                amount:
                  title: Amount
                  type: object
                  properties:
                    type:
                      type: string
                    value:
                      type: string
                    unit:
                      type: string
        required: true
      responses:
        "200":
          description: HTTP 200 indicating the request succeeded; the response body
            follows the documented schema for this operation and includes correlation
            identifiers where applicable for traceability across MTN MADAPI account
            topup flows.
          content:
            application/json:
              schema:
                title: BalanceTopUpResponse
                type: object
                properties:
                  statusCode:
                    type: string
                  resultDescription:
                    type: string
                  data:
                    title: BalanceTopUpResponseData
                    type: object
                    properties:
                      requestedTopUpAmount:
                        $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
                      senderInformation:
                        title: SenderInformation
                        type: object
                        properties:
                          senderAccountNumber:
                            type: string
                          senderAccountDescription:
                            type: string
                          senderCreditLimit:
                            $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
                          senderUpdatedBalance:
                            $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
                          senderStatus:
                            type: string
                          senderPhoneNumber:
                            type: string
                      recipientInformation:
                        title: RecipientInformation
                        type: object
                        properties:
                          recipientAccountId:
                            type: string
                          recipientPhoneNumber:
                            type: string
                          recipientUpdatedBalance:
                            $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
                          actualTopUpAmount:
                            $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "400"
                statusMessage: "Bad request. Invalid request parameters, missing required\
                  \ fields, or validation errors."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "502":
          description: Bad gateway. The server acting as a gateway received an invalid
            response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "503":
          description: Service unavailable. The server is temporarily unable to handle
            the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
components:
  schemas:
    com_mtn_aggregator_models_topup_Amount:
      title: Amount
      type: object
      properties:
        type:
          type: string
        value:
          type: string
        unit:
          type: string
    com_mtn_aggregator_models_topup_RecipientInformation:
      title: RecipientInformation
      type: object
      properties:
        recipientAccountId:
          type: string
        recipientPhoneNumber:
          type: string
        recipientUpdatedBalance:
          $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
        actualTopUpAmount:
          $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
    com_mtn_aggregator_models_response_BalanceTopUpResponseData:
      title: BalanceTopUpResponseData
      type: object
      properties:
        requestedTopUpAmount:
          $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
        senderInformation:
          title: SenderInformation
          type: object
          properties:
            senderAccountNumber:
              type: string
            senderAccountDescription:
              type: string
            senderCreditLimit:
              $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
            senderUpdatedBalance:
              $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
            senderStatus:
              type: string
            senderPhoneNumber:
              type: string
        recipientInformation:
          title: RecipientInformation
          type: object
          properties:
            recipientAccountId:
              type: string
            recipientPhoneNumber:
              type: string
            recipientUpdatedBalance:
              $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
            actualTopUpAmount:
              $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
    com_mtn_aggregator_models_request_BalanceTopUpRequest:
      title: BalanceTopUpRequest
      type: object
      properties:
        currency:
          type: string
        clientReference:
          type: string
        balanceType:
          type: string
        senderAccountId:
          type: string
        amount:
          title: Amount
          type: object
          properties:
            type:
              type: string
            value:
              type: string
            unit:
              type: string
    com_mtn_aggregator_models_response_BalanceTopUpResponse:
      title: BalanceTopUpResponse
      type: object
      properties:
        statusCode:
          type: string
        resultDescription:
          type: string
        data:
          title: BalanceTopUpResponseData
          type: object
          properties:
            requestedTopUpAmount:
              $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
            senderInformation:
              title: SenderInformation
              type: object
              properties:
                senderAccountNumber:
                  type: string
                senderAccountDescription:
                  type: string
                senderCreditLimit:
                  $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
                senderUpdatedBalance:
                  $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
                senderStatus:
                  type: string
                senderPhoneNumber:
                  type: string
            recipientInformation:
              title: RecipientInformation
              type: object
              properties:
                recipientAccountId:
                  type: string
                recipientPhoneNumber:
                  type: string
                recipientUpdatedBalance:
                  $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
                actualTopUpAmount:
                  $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
    APIError:
      title: APIError
      required:
      - statusCode
      - statusMessage
      type: object
      properties:
        statusCode:
          type: string
          description: Error status code
        statusMessage:
          type: string
          description: Human-readable error message
        supportMessage:
          type: string
          description: Technical support message or error code for troubleshooting
        transactionId:
          type: string
          description: Transaction identifier for tracking and correlation
        sequenceNo:
          type: string
          description: Sequence number for request tracking
        timestamp:
          type: string
          description: Error timestamp in ISO 8601 format
          format: date-time
        path:
          type: string
          description: API endpoint path where the error occurred
        method:
          type: string
          description: HTTP method of the request that caused the error
        downstreamStatusCode:
          type: string
          description: Downstream service error code if applicable
      description: Generic MADAPI error response structure
    com_mtn_aggregator_models_topup_SenderInformation:
      title: SenderInformation
      type: object
      properties:
        senderAccountNumber:
          type: string
        senderAccountDescription:
          type: string
        senderCreditLimit:
          $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
        senderUpdatedBalance:
          $ref: '#/components/schemas/com_mtn_aggregator_models_topup_Amount'
        senderStatus:
          type: string
        senderPhoneNumber:
          type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.mtn.com/v1/oauth/access_token
          scopes: {}
    Bearer:
      type: http
      description: Bearer token received from OAuth2.0 authentication with the MADAPI
      scheme: bearer
      bearerFormat: JWT