openapi: 3.0.1
info:
  title: TMF654 Prepay Balance Management
  description: "Used for querying and sharing bucket balances,  A bucket is an entity\
    \ that keeps track of the balance available to use services. Every bucket will\
    \ measure balance in different units, it can be monetary or non-monetary (e.g.:\
    \ number of sms that are available, number of GB of data available etc.)"
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: 3.0.0 - Last updated date:2026-08-18 13:49:12
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: Tmf654PrepayBalanceManagement
paths:
  /balanceTransfer:
    post:
      tags:
      - Tmf654PrepayBalanceManagement
      summary: Enables transfer of a subscriber balances
      description: "This Post operation method is utilized for Sharing balances like\
        \ bonuses, voice, sms, data and the main balance with other subscribers."
      operationId: PrepayBalanceManagementAggregatorService_post_balanceTransfer
      parameters:
      - name: auth
        in: header
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: usageType
        in: query
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: TransferRequest
              type: object
              properties:
                direction:
                  type: string
                channel:
                  title: RequestChannel
                  type: object
                  properties:
                    id:
                      type: string
                    href:
                      type: string
                    name:
                      type: string
                amount:
                  title: Amount
                  type: object
                  properties:
                    amount:
                      type: string
                    units:
                      type: string
                partyAccount:
                  title: Account
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    role:
                      type: string
                    status:
                      type: string
                    bucket:
                      type: array
                      items:
                        title: Bucket
                        type: object
                        properties:
                          id:
                            type: string
                          name:
                            type: string
                          usageType:
                            type: string
                          activationDate:
                            type: string
                          expiryDate:
                            type: string
                          balance:
                            $ref: '#/components/schemas/com_mtn_aggregator_models_request_Amount'
                receiver:
                  $ref: '#/components/schemas/com_mtn_aggregator_models_request_Account'
                transferCost:
                  $ref: '#/components/schemas/com_mtn_aggregator_models_request_Amount'
        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 Tmf654
            prepay balance management flows.
          content:
            application/json:
              schema:
                title: TransferApiResponse
                type: object
                properties:
                  transactionId:
                    type: string
                  resultCode:
                    type: string
                  resultDescription:
                    type: string
                  id:
                    type: string
                  transferCost:
                    $ref: '#/components/schemas/com_mtn_aggregator_models_request_Amount'
                  channel:
                    $ref: '#/components/schemas/com_mtn_aggregator_models_request_RequestChannel'
                  amount:
                    $ref: '#/components/schemas/com_mtn_aggregator_models_request_Amount'
                  partyAccount:
                    $ref: '#/components/schemas/com_mtn_aggregator_models_request_Account'
                  receiver:
                    $ref: '#/components/schemas/com_mtn_aggregator_models_request_Account'
        "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
  /bucket:
    get:
      tags:
      - Tmf654PrepayBalanceManagement
      summary: Enables the querying of airtime or data balances for a bucket
      description: "This operation is used to query for the available bucket balances,\
        \ A bucket is an entity that keeps track of the balance available to use services.\
        \ Every bucket will measure balance in different units, it can be monetary\
        \ or non-monetary (e.g.: number of sms that are available, number of GB of\
        \ data available etc.)"
      operationId: PrepayBalanceManagementAggregatorService_get_queryBundles_bucket
      parameters:
      - name: auth
        in: header
        required: false
        schema:
          type: string
      - name: relatedParty.id
        in: query
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: type
        in: query
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: true
        schema:
          type: string
      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 Tmf654
            prepay balance management flows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/com_mtn_aggregator_models_response_TransferApiResponse'
        "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_request_RequestChannel:
      title: RequestChannel
      type: object
      properties:
        id:
          type: string
        href:
          type: string
        name:
          type: string
    com_mtn_aggregator_models_request_TransferRequest:
      title: TransferRequest
      type: object
      properties:
        direction:
          type: string
        channel:
          title: RequestChannel
          type: object
          properties:
            id:
              type: string
            href:
              type: string
            name:
              type: string
        amount:
          title: Amount
          type: object
          properties:
            amount:
              type: string
            units:
              type: string
        partyAccount:
          title: Account
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            role:
              type: string
            status:
              type: string
            bucket:
              type: array
              items:
                title: Bucket
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  usageType:
                    type: string
                  activationDate:
                    type: string
                  expiryDate:
                    type: string
                  balance:
                    $ref: '#/components/schemas/com_mtn_aggregator_models_request_Amount'
        receiver:
          $ref: '#/components/schemas/com_mtn_aggregator_models_request_Account'
        transferCost:
          $ref: '#/components/schemas/com_mtn_aggregator_models_request_Amount'
    com_mtn_aggregator_models_response_TransferApiResponse:
      title: TransferApiResponse
      type: object
      properties:
        transactionId:
          type: string
        resultCode:
          type: string
        resultDescription:
          type: string
        id:
          type: string
        transferCost:
          $ref: '#/components/schemas/com_mtn_aggregator_models_request_Amount'
        channel:
          $ref: '#/components/schemas/com_mtn_aggregator_models_request_RequestChannel'
        amount:
          $ref: '#/components/schemas/com_mtn_aggregator_models_request_Amount'
        partyAccount:
          $ref: '#/components/schemas/com_mtn_aggregator_models_request_Account'
        receiver:
          $ref: '#/components/schemas/com_mtn_aggregator_models_request_Account'
    com_mtn_aggregator_models_request_Bucket:
      title: Bucket
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        usageType:
          type: string
        activationDate:
          type: string
        expiryDate:
          type: string
        balance:
          $ref: '#/components/schemas/com_mtn_aggregator_models_request_Amount'
    com_mtn_aggregator_models_request_Amount:
      title: Amount
      type: object
      properties:
        amount:
          type: string
        units:
          type: string
    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_request_Account:
      title: Account
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        role:
          type: string
        status:
          type: string
        bucket:
          type: array
          items:
            title: Bucket
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              usageType:
                type: string
              activationDate:
                type: string
              expiryDate:
                type: string
              balance:
                $ref: '#/components/schemas/com_mtn_aggregator_models_request_Amount'
  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