MTN Group VAS Services API

openapi: 3.2.0
info:
  description: Api Documentation
  version: '1.0'
  title: Documentation Unified Balance VAS Services API
  termsOfService: urn:tos
  contact: {}
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://za.api.mtn.com/VasServices
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: VAS Services
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
      responses:
        200:
          description: PostAssets response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostVASResponseV3'
        400:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Authentication information is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createVASRequestV6'
        description: Request body
        required: true
  /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
      responses:
        200:
          description: PostAssets response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostVASResponseV2'
        400:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Authentication information is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostVASRequestV3'
        description: Request body
        required: true
  /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
        schema:
          type: string
      - name: sourceIdentifier
        in: query
        description: This field denotes the channel that is initiating request to SOA., ex-'Online, USSD, MyMTNApp'
        required: true
        schema:
          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
        schema:
          type: string
      - name: msisdn
        in: query
        description: The MSISDN in international format.
        schema:
          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.
        schema:
          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 '
        schema:
          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
        schema:
          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
        schema:
          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'
        schema:
          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 '
        schema:
          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'.
        schema:
          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'.
        required: true
        schema:
          type: string
      - 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
        schema:
          type: string
      - name: chargingSystemIndicator
        in: query
        description: ''
        required: false
        schema:
          type: string
      responses:
        '200':
          description: VAS services response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VASResponseV9'
        '400':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication information is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      responses:
        200:
          description: PostAssets response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostVASResponseV3'
        400:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Authentication information is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createVASRequestV4'
        description: Request body
        required: true
  /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
      responses:
        200:
          description: PostAssets response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostVASResponseV3'
        400:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Authentication information is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createVASRequestV5'
        description: Request body
        required: true
components:
  schemas:
    PostVASResponseV3:
      allOf:
      - required:
        - statusCode
        - statusMessage
        - supportMessage
        - transactionId
        type: object
        properties:
          statusCode:
            type: integer
            description: Back end status code.
            format: int32
            example: '0000'
          statusMessage:
            type: string
            description: User friendly error message.
            example: success
          supportMessage:
            type: string
            description: Description message for Support teams
            example: success
          transactionId:
            type: string
            description: Unique identifier for the transaction.
            example: 564trgf567ytg
    PostVASRequestV3:
      allOf:
      - required:
        - chargeable
        - msisdn
        - recurring
        - sourceIdentifier
        - transactionId
        - vasCode
        type: object
        properties:
          transactionId:
            type: string
            description: Unique identifier for the transaction.
          msisdn:
            type: string
            description: MSISDN in international format
          sourceIdentifier:
            type: string
            description: Parameter describing which system is calling the service.   Currently it can be set to the following; "myMTN App", or "USSD"
          vasCode:
            type: string
            description: VAS Code that indentifies the VAS service on the back-ends.  This is obtained in the "GET" request.
          recurring:
            type: string
            description: 'Flag indicating the type of provisoning service.  The possible values are "Recurring", "Once-Off", "Auto-renew" and "Micro" '
          chargeable:
            type: string
            description: Flag indicating whether or not there is a charge to deactivate this service.  The information for this parameter is obtained from the "GET" operation.
          activationDate:
            type: string
            description: Date when VAS service should be activated in the the ISO8601 standard, e.g. 2008-09-15T15:53:00.  This field is optional.  If its not sent, the VAS service is activated immediatley.
          notify:
            type: array
            description: List of attributes to be passed for notification. This will be passed where notify parameters will be available in the get request of VAS, currently it is only passed for mymtn offers.
            items:
              type: object
              properties:
                notifyChannel:
                  type: string
                  description: 'This indicates if on succesful purchase of bundle which channel has to notify. '
                offerType:
                  type: string
                  description: This is the type of "offer" being requested by the service.  Currently it can be set to one of the following; "myMTN Offers","Summer Surprise" or "Recharge Rewards".
                offerCategory:
                  type: string
                  description: When "offerType" is set to "myMTN Offers", this value can be one of the following; "All", "myMTN Data", "myMTN Voice" or "myMTN Social".  When its set to "Recharge Rewards"  this value does not have to be passed.  If this value is not passed for any "offerType", its defaulted to "All".If "offerType" is set to "Summer Surprise" than sub type can be "Monthly","Weekly","All" etc.Currently it has been configured for "All" .The summer surprise depends also on the sourceIdentifier as SOA invokes corresponding target system to retreive the product details.
                notify:
                  type: string
                  description: This indicates if on succesful purchase of bundle do we need to notify the target channel.
                offerId:
                  type: string
                  description: This value will be the offer id given for the bundle in the getMTN offer response.
                offerSubCategory:
                  type: string
                  description: Currently this field is optional.  Its a field that can in future be used to filter the offers that you get back. In case of "Summer Surprise" the subType could be "CVM","Wave" and "Others", Currently target channel has catered for "CVM" and "Wave" This field is only mandatory if the offer type is "Summer Surprise".
    Notify:
      type: object
      properties:
        notifyChannel:
          type: string
          description: 'This indicates if on succesful purchase of bundle which channel has to notify. '
        offerType:
          type: string
          description: This is the type of "offer" being requested by the service.  Currently it can be set to one of the following; "myMTN Offers","Summer Surprise" or "Recharge Rewards".
        offerCategory:
          type: string
          description: When "offerType" is set to "myMTN Offers", this value can be one of the following; "All", "myMTN Data", "myMTN Voice" or "myMTN Social".  When its set to "Recharge Rewards"  this value does not have to be passed.  If this value is not passed for any "offerType", its defaulted to "All".If "offerType" is set to "Summer Surprise" than sub type can be "Monthly","Weekly","All" etc.Currently it has been configured for "All" .The summer surprise depends also on the sourceIdentifier as SOA invokes corresponding target system to retreive the product details.
        notify:
          type: string
          description: This indicates if on succesful purchase of bundle do we need to notify the target channel.
        offerId:
          type: string
          description: This value will be the offer id given for the bundle in the getMTN offer response.
        offerSubCategory:
          type: string
          description: Currently this field is optional.  Its a field that can in future be used to filter the offers that you get back. In case of "Summer Surprise" the subType could be "CVM","Wave" and "Others", Currently target channel has catered for "CVM" and "Wave" This field is only mandatory if the offer type is "Summer Surprise".
    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 b

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-vas-services-api-openapi.yml