Documentation
Documentation
https://developers.mtn.com/products/provisioning
APIReference
https://developers.mtn.com/products/provisioning
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: /VasServices
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:
/v2/offer-provision:
post:
tags:
- VAS Services
summary: This is used to provision Variable VAS servcies.
description: This service is used to provision variable VAS bundles.This version
of the service does the variable provisiong along with the promotions that
are combined with the rewards and enables notification to the target channel.
This service will also have the recurrence of the offers that are configured
on Neon that will be provisioned.
operationId: offerProvisionv2
parameters:
- in: body
name: body
description: Request body
required: true
schema:
$ref: '#/definitions/createVASRequestV6'
responses:
200:
description: PostAssets response
schema:
$ref: '#/definitions/PostVASResponseV3'
400:
description: unexpected error
schema:
$ref: '#/definitions/Error'
401:
description: Authentication information is missing or invalid
schema:
$ref: '#/definitions/Error'
/v2/vas:
post:
tags:
- VAS Services
summary: Provision VAS services (applicable to prepaid and postpaid customers).
description: Function used to provision a VAS service on a customer's account. This
version of the service does the provisoning for autorenew and micro bundles;
it also aligns the interface to the current CAMEL case standard being followed.
operationId: postVASV3
parameters:
- in: body
name: body
description: Request body
required: true
schema:
$ref: '#/definitions/PostVASRequestV3'
responses:
200:
description: PostAssets response
schema:
$ref: '#/definitions/PostVASResponseV2'
400:
description: unexpected error
schema:
$ref: '#/definitions/Error'
401:
description: Authentication information is missing or invalid
schema:
$ref: '#/definitions/Error'
/v9/vas:
get:
tags:
- VAS Services
summary: Returns a list of applicable VAS services for subscribers.
description: Returns a list of applicable VAS services for a customer to provision on their account. Current source systems is IBF and SAAE for this i.e. you can do "Card" and "Airtime" purchases. In this version additional feilds have been added to support simple, complex and extreme cards for the UI/UX i.e. to cater for different naming standards, and to return the SAAE ID where configured.V9 Vas service retruns standard VAS , top selling and personalised.
operationId: getCatalogueV9
parameters:
- name: transactionId
in: query
description: Unique ID for the transaction.
required: true
type: string
- name: sourceIdentifier
in: query
description: This field denotes the channel that is initiating request to SOA., ex-'Online, USSD, MyMTNApp'
required: true
type: string
- name: vasType
in: query
description: This parameter indicates the type of vas that is requested It can be set to "Personalised", "Standard", "Combined", "Augmented".Personalised flag returns Only personalised offers object. Standard flag only returns the standard VAS offers.Combined flag returns VAS list has both the standard VAS and personalised offers. Augmented flag returns personalised and standard objects in the VAS list.In this scenario though, the standard offers in the "VAS list" are
replaced by personalised ones if they exist.Combined flag returns the standard XDR offers and also the CVM upsell offers. The upsell bundles of Neon will be returned for all vasTypes in a different array of myMTNOffers
required: true
type: string
- name: msisdn
in: query
description: The MSISDN in international format.
type: string
- name: pricePlanId
in: query
description: >-
The priceplan ID associated to the MSISDN entered above. Bundles
that are not applicable to this price plan are excluded from the
response based on this parameter and also bundles only applicable
for the price plan is returned.
type: string
- name: subscriberType
in: query
description: >-
The subscriber type associated to the MSISDN entered above. The
field can be one of the following values: 'Converged','Prepaid',
'MVNO', 'Contract', 'Hybrid', 'EBU', 'FTTH' .The Neon offers will be
returned irrespective of the subtye
type: string
- name: channel
in: query
description: >-
This parameter indicates which channel the response is for. This is
so that a requesting system can get bundles that are specific to its
platform. For example, there maybe some bundles that are only
applicable to the App or the IVR. This flag can currently be set to
one of the following values: "All", "IVR", "App", "USSD", "Portal"
required: true
type: string
- name: platformType
in: query
description: >-
This flag correlates to the allPlatforms flag in the response. In
essence, its a ‘Flag’ indicating which platform the bundles is being
requested for. "All" - Indicates that all bundles should be
returned. ‘Self Service’ - Indicates the bundles are being
requested for self-service platforms ‘Assisted Sales’ - Indicates
the bundles are being requested for assisted sales channels ‘CSR
Only’ - Indicates the bundles are being requested for CSR agents and
‘Agents’ - Indicates the bundles are being requested for physical
stores. So if for example the channel is a "Portal" and this flag
has been set to "Self Service" all bundles that have the
allPlatforms flag set to "Yes" shall be returned, and then only the
"Self Service" bundles shall be returned and not for example the CSR
specific ones
required: true
type: string
- name: bundleType
in: query
description: >-
This parameter is optional. If it is passed through, the response
will only return bundles of the type specified here. If its not
passed through, all bundle types are returned by default. Currently
the parameter .pass the values using pipe delimeter e.g
Data|voice|SMS etc can be set to one of the following: SMS, Voice,
Data, Social, Mixed, Digital or All. Neon offers will be returned
irrespective of the bearer type
type: string
- name: bundleCategory
in: query
description: >-
This parameter defines what type of bundles to be displayed to the
subscriber. This is mandatory if vasType is Combined or Upsell. The
values are Daily, Weekly,Monthly .To accept value All since we are
interested in all bundles This can be set to All
type: string
- name: purchaseMedium
in: query
description: >-
When passed in input ,helps to return only the matched
bundles.Suppose if user tries to buy via Airtime this parameter
takes value as 'Airtime' and those applicable bundles are
returned.Allowed values 'Card','Airtime','Momo','Loyalty'
and 'All'.
type: string
- name: bundleState
in: query
description: >-
When passed in input ,helps to return only the 'Active' or
'Inactive' or 'All' the bundles . Allowed values 'Active' ,
'Inactive' and 'All'.
type: string
required: true
- name: topSeller
in: query
description: >-
When set to 'Yes' output contains both the top selling and regular
bundles. When set to 'No' the output contains only the regular
bundles. When set to 'All' returns both the top selling and regular
bundles .Allowed values 'Yes','No','All'
type: string
required: true
type: string
- name: chargingSystemIndicator
in: query
description: ''
type: string
required: false
responses:
'200':
description: VAS services response
schema:
$ref: '#/definitions/VASResponseV9'
'400':
description: unexpected error
schema:
$ref: '#/definitions/Error'
'401':
description: Authentication information is missing or invalid
schema:
$ref: '#/definitions/Error'
/v4/variable-vas:
post:
tags:
- VAS Services
summary: This is used to provision Variable VAS servcies.
description: This service is used to provision variable VAS bundles.This version
of the service does the variable provisiong along with the promotions that
are combined with the rewards and enables notification to the target channel.
This service will also have the recurrence of the offers that are configured
on Neon that will be provisioned.
operationId: createVarVASV3
parameters:
- in: body
name: body
description: Request body
required: true
schema:
$ref: '#/definitions/createVASRequestV4'
responses:
200:
description: PostAssets response
schema:
$ref: '#/definitions/PostVASResponseV3'
400:
description: unexpected error
schema:
$ref: '#/definitions/Error'
401:
description: Authentication information is missing or invalid
schema:
$ref: '#/definitions/Error'
/v5/variable-vas:
post:
tags:
- VAS Services
summary: This is used to provision Variable VAS servcies.
description: This service is used to provision variable VAS bundles.This version
of the service does the variable provisiong along with the promotions that
are combined with the rewards and enables notification to the target channel.
This service will also have the recurrence of the offers that are configured
on Neon that will be provisioned.
operationId: vasVariableSubscriptionV5
parameters:
- in: body
name: body
description: Request body
required: true
schema:
$ref: '#/definitions/createVASRequestV5'
responses:
200:
description: PostAssets response
schema:
$ref: '#/definitions/PostVASResponseV3'
400:
description: unexpected error
schema:
$ref: '#/definitions/Error'
401:
description: Authentication information is missing or invalid
schema:
$ref: '#/definitions/Error'
definitions:
VASResponseV9:
allOf:
- required:
- statusCode
- statusMessage
- supportMessage
- transactionId
- vas
type: object
properties:
statusCode:
type: integer
description: Status code for transaction
format: int32
statusMessage:
type: string
description: 'User friendly error message. '
supportMessage:
type: string
description: Description message for Support teams
transactionId:
type: string
description: Unique identifier for the transaction.
vas:
type: array
description: Array housing the VAS values for the respective customer MSISDN.
items:
required:
- bundleType
- vasServices
type: object
properties:
bundleType:
type: string
description: >-
Indicates the type of bundle that this is. For example it
can be SMS, Voice, Data, Social, Mixed or Micro
vasServices:
type: array
description: >-
Array housing the VAS services that the customer can
subscribe to
items:
required:
- allPlatforms
- bundleCardType
- bundleCategory
- bundleDescription
- chargeable
- cost
- costUom
- bundleUom
- customerFacingName
- me2uAllowed
- period
- purchaseMedium
- recurance
- shareable
- value
- isTopSeller
type: object
properties:
shareable:
type: string
description: >-
Flag indicating if the bundle can be shared in the
context of a priceplan such as Multi-line. It can
have a value of "Y" for yes, and a value of "N" for
no.
isPersonalised:
type: boolean
description: >-
Flag indicating if the bundle is a personalised
bundle.It can have a value of "Y" for yes, and a
value of "N" for no.
bundleCardType:
type: string
description: >-
Used to determine the Card structure .Possible
values 'Simple', 'Advanced' , 'Complex' ,'Extreme'
and 'Combo'
productPrompt:
type: string
description: >-
This field is used during Confirmation step in
channel like 'USSD'.
chargeable:
type: string
description: >-
Flag indicating whether or not there is a charge to
activate this service. It can have a value of "Y"
for yes, and a value of "N" for no.
periodExtension:
type: string
description: >-
Used to tell the about the validity in
cases like when additional expiry
information is added. E.g., 'Expires Midnight'
chargeType:
type: string
description: >-
'Flag' indicating if the VAS service is available
as "Recurring", "Once-Off", "Auto-renew"
intellectualProperty:
type: string
description: >-
Used to show product specific classifications .
E.g,. 'Rush Hour' , 'Made for Home' and 'Video
Streaming'
me2uAllowed:
type: string
description: >-
Field indicating if a me2u can be performed with
this VAS service. It can have a value of "Y" for
yes, and a value of "N" for no.
recurringVasCode:
type: string
description: >-
Code used to identify the recurring VAS service on
the backends. Its only returned if the VAS is
available as ao recurring VAS service
isTopSeller:
type: string
description: >-
Tells whether the bundles is top selling or regular
bundle. Allowed values 'Yes', 'No'
purchaseMedium:
type: string
description: >-
Medium through which the bundle can be purchased.
Values are as follows Card, Airtime, Momo, Loyalty
or All
bundleDescription:
type: string
description: 'This is the bundle description '
expandedDescription:
type: string
description: >-
Used for Extreme Card when panel is expanded to
reveal all details. Needs to support individual
points; which will be pipe delimited.
allPlatforms:
type: string
description: >-
'Flag' indicating on which platforms the VAS
services can be sold on. It can be one of the
following values: 'Yes' - Can be sold on any
platform 'Self Service' - Can be sold only via
self-service platforms 'Assisted Sales' - Can only
be sold via assisted sales channels 'CSR Only' - Can
only be sold via CSR agents 'Agents' - Can only be
sold via physical stores
imageUrl:
type: string
description: >-
This represent the image that can be used when
showing the bundle on a Portal/App. It is used for
example in the case of social bundles, where a
watsapp image is shown for the applicable watsapp
social bundle. Parameter is only returned if an
image has been configured for the respective bundle.
value:
type: string
description: >-
The value of the VAS service. This is the bundle
size, for example 20MB or unlimited
collapsedDescription:
type: string
description: >-
This field is used for Extreme Card when panel is
collapsed
period:
type: string
description: >-
This field indicates the period that the VAS service
is valid for. It can for example be 30 Days
cost:
type: number
format: integer
description: >-
The cost the VAS service including VAT. This is
shown to the customer on the front-ends.
costUom:
type: string
description: Unit of measure for the cost of the VAS service .
example: Rands
specification:
type: string
description: >-
In case of complex bundle this field is used to show
the time period in which the recurrance occurs.
E.g., for Onetime bundles to show 100MB every month
for 6 months.
bundleIndicator:
type: string
description: >-
This flag indicates if the bundle is a night or Sky
bundle. If its a night bundle, the value "Night" is
returned, and for Sky, the value "Sky" is returned.
This field can be used for any new type of bundle
indicator in future
customerFacingName:
type: string
description: >-
Field that is presented to the customer i.e. the
"friendly name for customers". This can be seen as
the "Bundle Name"
topSellerOn:
type: string
description: >-
Used to indicated if it's a top Seller. Channel
name(s) with pipe separated will be indicated here
E.g., USSD|myMTN App
onceOffVasCode:
type: string
description: >-
Code used to identify the once off VAS service on
the backends. Its only returned if the VAS is
available as ao once off VAS service
bundleUOM:
type: string
description: >-
Unit of Measure of the 'bundleValue' E.g.'GB' or
'MB'
saeeId:
type: string
description: SAEE Identifier of the bundle
extraInfo:
type: string
description: >-
for Advanced Card to explain extra information about
the bundle such as type of minutes are off-net only
or on-net.
partnerId:
type: string
description: >-
Applicable for digital products. Partner id of the
product that belongs to
partnerPlatform:
type: string
description: >-
Platform name where the digital products are to be
provisioned on.
example: 'DEP,SDP'
salesMenu:
type: string
topSellingBundles:
type: array
description: Array housing the VAS values for the respective customer MSISDN.
items:
required:
- bundleType
- vasServices
type: object
properties:
bundleType:
type: string
description: >-
Indicates the type of bundle that this is. For example it
can be SMS, Voice, Data, Social, Mixed or Micro
vasServices:
type: array
description: >-
Array housing the VAS services that the customer can
subscribe to
items:
required:
- allPlatforms
- bundleCardType
- bundleCategory
- bundleDescription
- chargeable
- cost
- customerFacingName
- me2uAllowed
- period
- purchaseMedium
- recurance
- shareable
- value
type: object
properties:
shareable:
type: string
description: >-
Flag indicating if the bundle can be shared in the
context of a priceplan such as Multi-line. It can
have a value of "Y" for yes, and a value of "N" for
no.
isPersonalised:
type: boolean
description: >-
Flag indicating if the bundle is a personalised
bundle.It can have a value of "Y" for yes, and a
value of "N" for no.
bundleCardType:
type: string
description: >-
Used to determine the Card structure .Possible
values 'Simple', 'Advanced' , 'Complex' ,'Extreme'
and 'Combo'
productPrompt:
type: string
description: >-
This field is used during Confirmation step in
channel like 'USSD'.
chargeable:
type: string
description: >-
Flag indicating whether or not there is a charge to
activate this service. It can have a value of "Y"
for yes, and a value of "N" for no.
periodExtension:
type: string
description: >-
Used to tell the about the validity in
cases like when additional expiry
information is added. E.g., 'Expires Midnight'
chargeType:
type: string
description: >-
'Flag' indicating if the VAS service is available
as "Recurring", "Once-Off", "Auto-renew"
intellectualProperty:
type: string
description: >-
Used to show product specific classifications .
E.g,. 'Rush Hour' , 'Made for Home' and 'Video
Streaming'
me2uAllowed:
type: string
description: >-
Field indicating if a me2u can be performed with
this VAS service. It can have a value of "Y" for
yes, and a value of "N" for no.
recurringVasCode:
type: string
description: >-
Code used to identify the recurring VAS service on
the backends. Its only returned if the VAS is
available as ao recurring VAS service
purchaseMedium:
type: string
description: >-
Medium through which the bundle can be purchased.
Values are as follows Card, Airtime, Momo, Loyalty
or All
bundleDescription:
type: string
description: 'This is the bundle description '
expandedDescription:
type: string
description: >-
Used for Extreme Card when panel is expanded to
reveal all details. Needs to support individual
points; which will be pipe delimited.
allPlatforms:
type: string
description: >-
'Flag' indicating on which platforms the VAS
services can be sold on. It can be one of the
following values: 'Yes' - Can be sold on any
platform 'Self Service' - Can be sold only via
self-service platforms 'Assisted Sales' - Can only
be sold via assisted sales channels 'CSR Only' - Can
only be sold via CSR agents 'Agents' - Can only be
sold via physical stores
imageUrl:
type: string
description: >-
This represent the image that can be used when
showing the bundle on a Portal/App. It is used for
example in the case of social bundles, where a
watsapp image is shown for the applicable watsapp
social bundle. Parameter is only returned if an
image has been configured for the respective bundle.
value:
type: string
description: >-
The value of the VAS service. This is the bundle
size, for example 20MB or unlimited
collapsedDescription:
type: string
description: >-
This field is used for Extreme Card when panel is
collapsed
period:
type: string
description: >-
This field indicates the period that the VAS service
is valid for. It can for example be 30 Days
cost:
type: number
format: integer
description: >-
The cost the VAS service including VAT. This is
shown to the customer on the front-ends.
costUom:
type: string
description: Unit of measure for the cost of the VAS service .
example: Rands
specification:
type: string
description: >-
In case of complex bundle this field is used to show
the time period in which the recurrance occurs.
E.g., for Onetime bundles to show 100MB every month
for 6 months.
bundleIndicator:
type: string
# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-provisioning.yml