openapi: 3.0.1
info:
  title: TMF_654_tmf-madapi-prepay-balance-management-aggregator-v1
  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: 1.0.0
servers:
- url: https://api.mtn.com/
  description: Generated server url
paths:
  /balanceTransfer:
    post:
      tags:
      - prepay-balance-management-aggregator-service-controller
      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: balanceTransfer
      parameters:
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
          default: ""
      - name: usageType
        in: query
        required: false
        schema:
          type: string
          default: ""
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
          default: ""
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferRequest'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferApiResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponses'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
        "404":
           description: Not Found
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/NotFoundResponse'
  /bucket:
    get:
      tags:
      - prepay-balance-management-aggregator-service-controller
      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: queryBundles
      parameters:
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
          default: ""
      - name: relatedParty.id
        in: query
        required: true
        schema:
          type: string
      - name: type
        in: query
        required: false
        schema:
          type: string
          default: DATA
          enum:
          - DATA
          - AIRTIME
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
          default: ""
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferApiResponse'
components:
  schemas:
    Account:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        role:
          type: string
        status:
          type: string
        bucket:
          type: array
          items:
            $ref: '#/components/schemas/Bucket'
    Amount:
      type: object
      properties:
        amount:
          type: string
        units:
          type: string
    Bucket:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        usageType:
          type: string
        activationDate:
          type: string
        expiryDate:
          type: string
        balance:
          $ref: '#/components/schemas/Amount'
    RequestChannel:
      type: object
      properties:
        id:
          type: string
        href:
          type: string
        name:
          type: string
    TransferApiResponse:
      type: object
      properties:
        transactionId:
          type: string
        resultCode:
          type: string
        resultDescription:
          type: string
        id:
          type: string
        transferCost:
          $ref: '#/components/schemas/Amount'
        channel:
          $ref: '#/components/schemas/RequestChannel'
        amount:
          $ref: '#/components/schemas/Amount'
        partyAccount:
          $ref: '#/components/schemas/Account'
        receiver:
          $ref: '#/components/schemas/Account'
    TransferRequest:
      type: object
      properties:
        direction:
          type: string
        channel:
          $ref: '#/components/schemas/RequestChannel'
        amount:
          $ref: '#/components/schemas/Amount'
        partyAccount:
          $ref: '#/components/schemas/Account'
        receiver:
          $ref: '#/components/schemas/Account'
        transferCost:
          $ref: '#/components/schemas/Amount'
    BadRequestErrorResponse:
      type: object
      properties:
        statusCode:
          type: string
          example: "5000"
        statusMessage:
          type: string
          example: INVALID_INPUT_PARAMETERS
        supportMessage:
          type: string
          example: The input parameters provided are invalid.
        httpStatus;:
          type: object
          example:
            code: 400
            series: CLIENT_ERROR
            reason: Bad Request
        timestamp:
          type: string
          example: 2025-08-05T20:57:21Z
    UnauthorizedErrorResponse:
      type: object
      properties:
        statusCode:
          type: string
          example: "4000"
        statusMessage:
          type: string
          example: Unauthorized
        supportMessage:
          type: string
          example: The supplied authentication is invalid.
        httpStatus;:
          type: object
          example:
            code: 401
            series: CLIENT_ERROR
            reason: Unauthorized
        timestamp:
          type: string
          example: 2025-08-05T20:57:21Z
    ServerErrorResponse:
      type: object
      properties:
        statusCode:
          type: string
          example: "3001"
        statusMessage:
          type: string
          example: INTERNAL_SERVER_ERROR
        supportMessage:
          type: string
          example: An internal server error occurred and processing could not be completed.
        httpStatus;:
          type: array
          example:
            code: 500
            series: SERVER_ERROR
            reason: Internal Server Error
        timestamp:
          type: string
          example: 2025-08-05T20:57:21Z