MTN Group Balance Transfer 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 Transfer API
  version: 2.0.4
servers:
- url: https://api.mtn.com/tmf-api/prepaybalancemanagement/v1/
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: BalanceTransfer
paths:
  /balanceTransfer:
    post:
      operationId: createTransfer
      parameters:
      - name: transactionId
        in: header
        required: true
        description: unique identifier f the transaction generated by Apigee
        schema:
          type: string
      - name: UsageType
        in: query
        description: type of the balance to be transferred
        required: true
        schema:
          type: string
          enum:
          - Main balance
          - Bonus
          - SMS
          - Data
          - Voice
      responses:
        '201':
          description: Transfer operation successful (resource created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferBalance'
      summary: request a new transfer operation for a given product (or commercial id reference to a product instance consuming the credit held in a bucket for a specific service).
      tags:
      - BalanceTransfer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BalanceTransferBody'
        description: The Transfer to be modify.
components:
  schemas:
    BalanceTransferBody:
      properties:
        direction:
          type: string
          description: 0-from outside system to OCS,1- from OCS to external system, 3- from OCS to OCS
        channel:
          $ref: '#/components/schemas/ChannelRefType'
          description: Indicator for the channel used to request the top-up operation. Structure including at least attribute �name�
        amount:
          $ref: '#/components/schemas/QuantityType'
          description: Amount (can be monetary or non-monetary) to be transferred
        partyAccount:
          $ref: '#/components/schemas/RelatedParty'
          description: A reference to the product related to the bucket that is impacted by the balance related operation
        receiver:
          $ref: '#/components/schemas/RelatedParty'
          description: A reference to the product related
        transferCost:
          $ref: '#/components/schemas/Money'
          description: A reference to the product related
      required:
      - channel
      - amount
      - type
    ContactMediumCharacteristic:
      type: object
      properties:
        emailAddress:
          type: string
          example: exampl@example.com
          description: Contact email address
    RelatedParty:
      type: object
      description: Related Entity reference. A related party defines party or party role linked to a specific entity.
      properties:
        id:
          type: string
          description: Unique identifier
        name:
          type: string
          description: Name or ID of the related entity.
        role:
          type: string
          description: Role played by the related party.
        status:
          type: string
          description: Status of the related party.
        href:
          type: string
          description: Link
          example: link://something-here.send
        description:
          type: string
          description: Description of the related party
        bucket:
          type: array
          items:
            $ref: '#/components/schemas/BucketRef'
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    BucketRef:
      type: object
      required:
      - id
      description: link to the resource that holds bucket information
      properties:
        id:
          type: string
          description: Unique identifier. This can be bucket id or wallet id etc.
        name:
          type: string
          description: Name of the related entity.
        role:
          type: string
          description: Role of the activity
        href:
          type: string
          description: Link
        usageType:
          $ref: '#/components/schemas/UsageType'
          description: Defines the type of the underlying balance e.g. data,voice, monetary etc.
        balance:
          $ref: '#/components/schemas/Quantity'
        activationDate:
          type: string
          format: date-time
          description: Activation date of the bucket.
        expiryDate:
          type: string
          format: date-time
          description: Expiry date of the bucket.
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
        '@type':
          example: LogicalResourceSpecification
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
    TimePeriod:
      type: object
      description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
      properties:
        endDateTime:
          example: '1985-04-12T23:20:50.52Z'
          type: string
          format: date-time
          description: End of the time period, using IETC-RFC-3339 format
        startDateTime:
          example: '1985-04-12T23:20:50.52Z'
          type: string
          format: date-time
          description: Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    ChannelRef:
      type: object
      description: The channel to which the resource reference to. e.g. channel for selling product offerings, channel for opening a trouble ticket etc..
      properties:
        id:
          type: string
          description: Unique identifier. This can be channel id , reference id etc
        name:
          type: string
          description: Name of the channel. This can be channel short code or shrot name etc.
        href:
          type: string
          description: channel url.
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
      required:
      - name
    ChannelRefType:
      description: link to the resource that holds information about the channel used to initiate the topup operation request
      properties:
        id:
          type: string
          description: Unique identifier for the channel entity
        href:
          type: string
          description: A resource URI pointing to the resource in the OB that stores the channel information
        name:
          type: string
          description: Name of the channel
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
      - href
    Quantity:
      type: object
      description: An amount in a given unit
      properties:
        amount:
          default: 1
          type: number
          format: float
          description: Numeric value in a given unit
        units:
          type: string
          description: Unit
    TransferBalance:
      type: object
      description: The TransferBalance resource is a detailed description of credit transfer operation requested between two buckets (reference to products owned by customers and consuming credit when using a service).
      required:
      - referenceNumber
      - channel
      - status
      properties:
        id:
          type: string
          description: Unique Identifier for the resource
        type:
          type: string
          description: Type of the identifier
        referenceNumber:
          type: string
          description: Reference number generated by provider system
        externalTransactionId:
          type: string
          description: Transaction id generated by MADapi.
        direction:
          type: string
          description: A direction
          example: inbound
        confirmationDate:
          type: string
          format: date-time
          description: Date when the deduction was confirmed in the server
        status:
          type: string
          description: Status of the operation
        description:
          type: string
          description: Description of the recharge operation
        reason:
          type: string
          description: Text describing the reason for the action/task
        href:
          type: string
          description: An href
        requestedDate:
          type: string
          format: date-time
          description: Date when the deduction request was received in the server
        amount:
          $ref: '#/components/schemas/Money'
          description: Indicate the amount on the bucket
        channel:
          $ref: '#/components/schemas/ChannelRef'
          description: Indicator for the channel used to request the transfer operation.
        partyAccount:
          $ref: '#/components/schemas/RelatedParty'
          description: Reference to the sender used to request the transfer operation. Structure including at least attribute name
        contact:
          type: array
          items:
            $ref: '#/components/schemas/ContactItem'
        product:
          type: array
          items:
            $ref: '#/components/schemas/ProductRef'
        receiver:
          $ref: '#/components/schemas/RelatedParty'
          description: Identifier for the user/customer/entity that receives the transfer when it is required to indicate additional customer hierarchy information regarding the entity receiving the balance transfer Structure including at least attributes “role” and “name”
        receiverLogicalResource:
          $ref: '#/components/schemas/LogicalResourceRef'
          description: A reference to the logical resource that can be used to identify the bucket balance for example where product ids are not unique.
        receiverBucket:
          $ref: '#/components/schemas/BucketRef'
        logicalResource:
          type: array
          items:
            $ref: '#/components/schemas/LogicalResourceRef'
        transferFee:
          $ref: '#/components/schemas/Money'
          description: Associated cost to be charged for the transfer operation (can be monetary or non-monetary)
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which the balance in the bucket is valid
        '@baseType':
          example: ResourceSpecification
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          example: LogicalResourceSpecification
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        recurring:
          type: boolean
          description: Whether the activity should be  a recurring event
          example: true
        recurringCount:
          type: number
          description: Number of times the recurring event should happen
          example: 2
    Money:
      type: object
      description: A base / value business entity used to represent money
      properties:
        units:
          type: string
          description: Currency (ISO4217 norm uses 3 letters to define the currency)
        amount:
          type: number
          format: float
          description: A positive floating point number
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    ContactMedium:
      type: object
      properties:
        preferred:
          type: boolean
          example: false
          description: Whether this should be the preferred contact or not
        isEnabled:
          type: boolean
          example: false
        mediumType:
          type: string
          description: Medium type
          example: example@email.com
        characteristic:
          $ref: '#/components/schemas/ContactMediumCharacteristic'
    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
    ProductRef:
      type: object
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          description: Hyperlink reference
        name:
          type: string
          description: Name of the related entity.
        amount:
          type: object
          properties:
            value:
              type: number
              example: 90
        taxAmount:
          type: object
          properties:
            value:
              type: number
              example: 20
        '@baseType':
          example: ResourceSpecification
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          example: LogicalResourceSpecification
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
    LogicalResourceRef:
      type: object
      description: reference to the LogicalResource eg MSISDN
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          description: Hyperlink reference
        name:
          type: string
          description: Name of the related entity.
        '@baseType':
          example: ResourceSpecification
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          example: LogicalResourceSpecification
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
    ContactItem:
      type: object
      properties:
        contactType:
          type: string
          description: The contact type
          example: EmailAddress, PhoneNumber etc
        contactMedium:
          type: array
          items:
            $ref: '#/components/schemas/ContactMedium'
    UsageType:
      type: string
      description: Valid values for the usage type are
      enum:
      - monetary
      - voice
      - data
      - sms
  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