MTN Group Balance Buckets Methods API

openapi: 3.2.0
info:
  description: This is a sample representation of the Prepay Balance Management TMForum API. It is important to bear in mind that swagger 2.0 does not properly support polymorphism, so the link between the payment method details and its data types should be looked up in the API specification pdf file.
  title: Prepay Balance Management Balance Buckets Methods API
  version: 2.0.4
servers:
- url: https://api.mtn.com/tmf-api/prepaybalancemanagement/v1/
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: Balance Buckets Methods
paths:
  /bucket:
    get:
      operationId: retrieveBuckets
      parameters:
      - name: relatedParty.id
        required: true
        in: query
        description: customer identification ID eg MSISDN
        schema:
          type: string
      responses:
        '200':
          description: Balance information was returned successfully
          headers:
            X-Total-Count:
              description: Total results
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BucketBalance'
        '400':
          description: Request Error
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '405':
          description: Method not Allowed
        '500':
          description: The server encountered an unexpected condition which prevented it from fulfilling the request
      summary: Retrieve balance information stored in the server that can be filtered for specific criteria.
      tags:
      - Balance Buckets Methods
components:
  schemas:
    RelatedPartyRefType:
      description: Information about an associated entity and its role
      properties:
        id:
          type: string
          description: Unique identifier for the account entity
        href:
          type: string
          description: A resource URI pointing to the resource in the OB that stores the account information
        name:
          type: string
          description: Name of the account
        role:
          type: string
          description: Role describing the relationship with the related element
      required:
      - role
      - name
    PartyAccountRefType:
      description: Information about a resource that holds information about the account that owns the bucket
      properties:
        id:
          type: string
          description: Unique identifier for the account entity
        href:
          type: string
          description: A resource URI pointing to the resource in the OB that stores the account information
        name:
          type: string
          description: Name of the account
      required:
      - id
      - href
    QuantityType:
      description: Representation of a quantity of something. I can also be used to represent a quantity range
      properties:
        amount:
          format: decimal
          type: number
          description: Measured amount
        units:
          type: string
          description: Units the quantity is measured in
      required:
      - units
      - amount
    BucketBalance:
      description: Represents and tracks the amount remained or owed for a certain type of service by certain customer
      properties:
        id:
          type: string
          description: Unique Identifier within the server for the bucket
        href:
          type: string
          description: A resource URI pointing to the resource in the OB that stores the detailed information for the bucket
        name:
          type: string
          description: Friendly name to identify the bucket
        description:
          type: string
          description: Text describing the contents of the balance managed by the bucket
        bucketType:
          type: string
          description: 'Type of prepay balance bucket (e.g.: promotion, deposit, bonus, data, voice, or any other service type)'
        remainedAmount:
          $ref: '#/components/schemas/QuantityType'
          description: Amount remained in the bucket
        reservedAmount:
          $ref: '#/components/schemas/QuantityType'
          description: Indicate the reserved amount on the bucket
        validFor:
          $ref: '#/components/schemas/TimePeriodType'
          description: The period for which the balance in the bucket is valid
        status:
          type: string
          description: Status for the balance (active, expired, suspended)
        product:
          type: array
          items:
            $ref: '#/components/schemas/ProductRefType'
          description: A reference to the product whose consumption is managed by the bucket. This is an array to allow scenarios where a given bucket is shared between different products.
        partyAccount:
          $ref: '#/components/schemas/PartyAccountRefType'
          description: A reference to the account that owns the bucket
        realizingResource:
          type: array
          items:
            $ref: '#/components/schemas/RealizingResourceRefType'
          description: A reference to the resource that realizes a product. This is an array to allow scenarios where a given bucket is shared between different resources.
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedPartyRefType'
          description: 'Used to provide information about any other entity with relation to the balance, for instance to define customer hierarchy for the balance (e.g.: customerId, userId, )'
      required:
      - id
      - href
      - bucketType
      - validFor
      - status
      - product
    TimePeriodType:
      description: Representation of a time period
      properties:
        startDateTime:
          format: date-time
          type: string
          description: Start date of the period
        endDateTime:
          format: date-time
          type: string
          description: End date of the period
      required:
      - startDateTime
    ProductRefType:
      description: Representation of a resource that holds information about the product that is linked to the bucket balance.
      properties:
        id:
          type: string
          description: Unique identifier for the product entity
        href:
          type: string
          description: A resource URI pointing to the resource in the OB that stores the product information
        name:
          type: string
          description: Name of the product
      required:
      - id
      - href
    RealizingResourceRefType:
      description: Information about a resource that holds realizes the product that is linked to the bucket balance
      properties:
        id:
          type: string
          description: Unique identifier of the related party
        href:
          type: string
          description: Reference to the party
        name:
          type: string
          description: Name of the resource
        '@Type':
          type: string
          description: Indicates the type of resource
        value:
          type: string
          description: 'The resource value that can be used to identify a resource with a public key (e.g.: a tel nr, an msisdn)'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.mtn.com/v1/oauth/access_token