Documentation
Documentation
https://developers.mtn.com/products/unified-balance-v1
APIReference
https://developers.mtn.com/products/unified-balance-v1
OpenAPI Specification
swagger: '2.0'
info:
description: Api Documentation
version: '1.0'
title: Api Documentation Unified Balance
termsOfService: urn:tos
contact: {}
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0
host: za.api.mtn.com
basePath: /v1
schemes:
- https
securityDefinitions:
ApiKeyAuth:
type: apiKey
name: X-API-Key
in: header
OAuth2:
type: oauth2
flow: application
tokenUrl: 'https://api.mtn.com/v1/oauth/access_token'
security:
- ApiKeyAuth: []
- OAuth2: []
paths:
'/balances':
get:
tags:
- Unified Balance Enquiry
summary: This API gives the Summary balance i.e., shared balances and personal balances of the customer from IBF. It also returns the XtraTime usage and lonable amount details.
operationId: summaryBalance
produces:
- "application/json"
parameters:
- name: transactionId
in: query
description: Transaction ID for the command being executed.
required: true
type: string
- name: sourceIdentifier
in: query
description: Channel name of the source system.
required: true
type: string
- name: msisdn
in: query
description: MSISDN in international format i.e. 27832227009
required: true
type: string
- name: balanceType
in: query
description: 'Indicates the summary balance type that is required. By default all is returned for all non prepaid subscribers and for prepaid subscribers usage limit will not be returned. The service will be enhanced in future to return the YB and MoMo balances as well. The filter can currently be set to one
of the following: "ALL", "Airtime", "Data","Voice","SMS","Usage Limit", "Xtratime"'
type: string
responses:
200:
description: getBalances response
schema:
$ref: '#/definitions/getBalancesResponse'
400:
description: unexpected error
schema:
$ref: '#/definitions/Error'
401:
description: Authentication information is missing or invalid
schema:
$ref: '#/definitions/Error'
500:
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
definitions:
getBalancesResponse:
allOf:
- required:
- subscriberType
- pricePlanId
- pricePlanDescription
- pricePlanActivationDate
- summaryBalanceList
- statusCode
- statusMessage
- supportMessage
- transactionId
- customerSegment
- activationDate
type: object
properties:
statusCode:
type: integer
description: The status code of the transaction.0 for success and 1 for any technical failure. The status code will be mapped as per the backend error codes for any business failure.
format: int32
example: 0000
statusMessage:
type: string
description: Message of the transaction. Either Success or Failure.
supportMessage:
type: string
description: Support message for the transaction. Indicates failure reason in case of failed transactions.
transactionId:
type: string
description: Unique identifier for every request to SOA. Mapped from input request.
subscriberType:
type: string
description: Line subscriber type. It can be one of the following, PREPAID, HYBRID, CONTRACT, CONVERGED, FTTH, or MVNO
activationDate:
type: string
description: User's account activation date.
customerSegment:
type: string
description: customer's account segment.
example: CBU, EBU.
pricePlanId:
type: string
description: The priceplan ID associated to the MSISDN which was queried.
pricePlanDescription:
type: string
description: The description of the price plan associated with priceplan id.
pricePlanActivationDate:
type: string
description: Activation date of the price plan mentioned.
xtraTimeDetails:
description: This array will give the usage value i.e., the xtraTime loan taken. It also gives the lonable amount and service fee. This array will not be retuned in case the XtraTime consent is false.
type: array
items:
required:
- usedValue
- usedValueUOM
- loanableAmount
- lonableAmountUOM
- serviceFee
- serviceFeeUOM
type: object
properties:
usedValue:
type: number
description: Gives the details of the XtraTime loan already taken.
usedValueUOM:
type: string
description: Indicates the unit of measure of the usage value for the dedicated account.
loanableAmount:
type: integer
description: Maximum amount of xtraTime loan that the user will be eligibile for. This value is fetched from MODE.
lonableAmountUOM:
type: integer
description: The unit of measure for the maximum amount of xtraTime loan that the user will be eligible.
serviceFee:
type: number
description: Maximum service fee for the xtraTime loan.
serviceFeeUOM:
type: number
description: The unit if measure for the maximum service fee for the xtraTime loan.
summaryBalanceList:
type: array
items:
required:
- wallet
type: object
properties:
wallet:
type: string
description: Gives the type of wallet. It can be one of the following, Personal, MadeToShare Master, EnterpriseSharing, MadeToShare Member.
threshold:
type: array
description: This array returns the threshold details only in case of made to share master.
items:
required:
- thresholdValue
- thresholdType
- thresholdUOM
type: object
properties:
thresholdValue:
type: string
description: Indicates the threshold value. Made to share Group's upper limit.
thresholdType:
type: string
description: Indicates the Threshold type. i.e Data, Voice.
thresholdUOM:
type: string
description: Indicates the unit of measure for the threshold. Sample values are bytes for data, minutes for Voice.
usage:
type: array
description: This array returns the usage details of the made to share master only.
items:
required:
- usageValue
- usageType
- usageUOM
type: object
properties:
usageValue:
type: string
description: Indicates the usage value of the Master.
usageType:
type: string
description: Indicates the usage type. i.e Data, Voice.
usageUOM:
type: string
description: Indicates the unit of measure for the usage. Sample values are bytes for data, minutes for Voice.
balances:
type: array
items:
required:
- balanceUOM
- balanceType
- balanceValue
type: object
properties:
balanceUOM:
type: string
description: Indicates the unit of measure for the balance time. Sample values are Rands for Airtime, bytes for data, minutes for Voice.
balanceType:
type: string
description: Indicates the summary balance type. i.e Data, Airtime, Voice, SMS, Usage.
balanceValue:
type: number
description: Indicates the summary balance value. Ex - 251:37 for minites, 35939676160 bytes for data and balance for Usage
error:
description: Will returned only if there is error in retruning the balances . In this case balances tag will not be returned.
required:
- errorCode
- errorMessage
type: object
properties:
errorCode:
type: integer
description: Error code.
errorMessage:
type: string
description: Description of the error.
getBalancesResponse2:
allOf:
- required:
- subscriberType
- pricePlanId
- pricePlanDescription
- pricePlanActivationDate
- summaryBalanceList
- statusCode
- statusMessage
- supportMessage
- transactionId
- customerSegment
- activationDate
type: object
properties:
statusCode:
type: integer
description: The status code of the transaction.0 for success and 1 for any technical failure. The status code will be mapped as per the backend error codes for any business failure.
format: int32
statusMessage:
type: string
description: Message of the transaction. Either Success or Failure.
supportMessage:
type: string
description: Support message for the transaction. Indicates failure reason in case of failed transactions.
transactionId:
type: string
description: Unique identifier for every request to SOA. Mapped from input request.
subscriberType:
type: string
description: Line subscriber type. It can be one of the following, PREPAID, HYBRID, CONTRACT, CONVERGED, FTTH, or MVNO
activationDate:
type: string
description: User's account activation date.
customerSegment:
type: string
description: customer's account segment.
example: CBU, EBU.
pricePlanId:
type: string
description: The priceplan ID associated to the MSISDN which was queried.
pricePlanDescription:
type: string
description: The description of the price plan associated with priceplan id.
pricePlanActivationDate:
type: string
description: Activation date of the price plan mentioned.
xtraTimeDetails:
description: This array will give the usage value i.e., the xtraTime loan taken. It also gives the lonable amount and service fee. This array will not be retuned in case the XtraTime consent is false.
type: array
items:
required:
- usedValue
- usedValueUOM
- loanableAmount
- lonableAmountUOM
- serviceFee
- serviceFeeUOM
type: object
properties:
usedValue:
type: number
description: Gives the details of the XtraTime loan already taken.
usedValueUOM:
type: string
description: Indicates the unit of measure of the usage value for the dedicated account.
loanableAmount:
type: integer
description: Maximum amount of xtraTime loan that the user will be eligibile for. This value is fetched from MODE.
lonableAmountUOM:
type: integer
description: The unit of measure for the maximum amount of xtraTime loan that the user will be eligible.
serviceFee:
type: number
description: Maximum service fee for the xtraTime loan.
serviceFeeUOM:
type: number
description: The unit if measure for the maximum service fee for the xtraTime loan.
balanceSummaryList:
type: array
description: This array contains the list of all the different balance summaries for an MSISDN.The array could consist of summary balances for Data, Airtime, Voice, SMS, and Usage Limit. This array will only be returned if there are any balance summaries for a subscriber MSISDN that was queried
items:
required:
- summaryBalanceType
- summaryBalanceUOM
- summaryBalanceValue
type: object
properties:
summaryBalanceUOM:
type: string
description: Indicated the unit of measure for the balance time. Sample values are Rands for Airtime, bytes for data, minutes for Voice
summaryBalanceType:
type: string
description: Indicates the summary balance type. i.e Data, Airtime, Voice, SMS, Usage
summaryBalanceValue:
type: string
description: Indicates the summary balance value. Ex - 251:37 for minites, 35939676160 bytes for data and balance for Usage
Any: {}
Error:
type: "object"
required:
- statusCode
- statusMessage
- supportMessage
- transactionId
properties:
timestamp:
type: "string"
format: "date-time"
description: "Timestamp when the error occured."
example: "2018-05-01T00:00"
statusCode:
type: string
description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client
supportMessage:
type: string
description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId:
type: string
description: This is the same transactionId that is sent in the request