MTN Group Products API

openapi: 3.2.0
info:
  title: Mtn Group Products API
  version: '1.0'
  description: 'Operations tagged products across 2 of this provider''s published API definitions: mtn-group-mtn-product-offering-api-v2.yml, mtn-group-mtn-product-offering-api-v3.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.api.mtn.com
- url: https://api.mtn.com/v3
tags:
- name: products
paths:
  /products/{customerId}:
    get:
      description: Retrieves the catalogue of Products available for purchase.
      summary: View product catalogue.
      tags:
      - products
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier
        required: true
        schema:
          type: string
      responses:
        200:
          description: Product Catalogue object. For a successfull request, the response will contain all the products available. If a product type does not have any requested data, then those fields will be null. E.g. if the product type (e.g. Data) does not have products, then the data field will be an empty list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCatalogue'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDefault'
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDefault'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDefault'
        404:
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        405:
          description: Method Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://www.api.mtn.com
  /products:
    get:
      description: Retrieves the Catalog of Products available to a 3PP identified by the nodeId.
      summary: View product Catalog
      tags:
      - products
      parameters:
      - name: nodeId
        in: query
        description: 3rd party assigned unique id
        required: true
        schema:
          type: string
      - name: productProviderId
        in: query
        description: This is the id of the service provider
        required: false
        schema:
          type: string
      - name: credentials
        in: header
        description: Base64 encoding of 3rd party username and password
        required: false
        schema:
          type: string
      - name: category
        in: query
        description: Category of the product to be fetched from that catalogue
        schema:
          type: string
      - name: subCategory
        in: query
        description: This can be any of the sub category of the category entered. This may be require only if the category is passed.
        schema:
          type: string
      - name: requestType
        in: query
        description: This determines the type of request being send. In callertunes, it holds the SOAP Action
        schema:
          type: string
      - name: autoRenewal
        in: query
        description: Specify if the product should be auto renewal or not
        schema:
          type: string
          enum:
          - true
          - false
      - name: serviceClass
        in: query
        description: Specify the class of service
        schema:
          type: string
      - name: offerName
        in: query
        description: Specify the offer name to be searched
        schema:
          type: string
      responses:
        200:
          description: Product Catalog object. For a successful request, the response will contain all the products available. If a product type does not have any requested data, then those fields will be null. E.g. if the product type (e.g. Data) does not have products, then the data field will be an empty list.
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ProductCatalogue_2'
        400:
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        401:
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        403:
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        404:
          description: Customer not found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        405:
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        500:
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v3
  /products/{customerId}/{productId}:
    get:
      description: Retrieve the details of a given product, most especially it's price. If nodeId is passed to this request, the returned price will be the price of the product as listed with the 3PP identified by nodeId.
      summary: Retrieve the details of a given product - Query bundle price
      tags:
      - products
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier
        required: true
        schema:
          type: string
      - name: productId
        in: path
        description: ID of the product
        required: true
        schema:
          type: string
      - in: query
        name: promotionCode
        required: false
        description: Promotion code assigned to product
        schema:
          type: string
      - in: query
        name: transactionId
        required: false
        description: Transaction ID
        schema:
          type: string
      - name: credentials
        in: header
        description: Base64 encoding of 3rd party username and password
        required: false
        schema:
          type: string
      responses:
        200:
          description: Product Details. For a successful request, the response will contain all the details of the product.
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ProductBundlePrice'
        400:
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        401:
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        403:
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        404:
          description: Product not found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        405:
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        500:
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v3
  /products/{customerId}/eligibility/{productId}:
    get:
      description: Check customer eligibility for product
      summary: Check the eligibility of a customer to buy a product
      tags:
      - products
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier
        required: true
        schema:
          type: string
      - name: productId
        in: path
        description: ID of the product
        required: true
        schema:
          type: string
      - name: credentials
        in: header
        description: Base64 encoding of 3rd party username and password
        required: false
        schema:
          type: string
      - name: nodeId
        in: query
        description: 3rd party assigned unique id. iname of the 3PPs which can call these service and must be whitelisted first
        schema:
          type: string
      - name: clientTransactionId
        in: query
        description: Client generated Id to include for tracing requests
        schema:
          type: string
          default: 234872789
      - name: viewType
        in: query
        description: The view requested
        schema:
          type: string
          enum:
          - checkOffer
      - name: targetSystem
        in: query
        description: The target system
        schema:
          type: string
          enum:
          - AirServer
          - CIS
          - CLM
          - MBAS
      - name: registrationChannel
        in: query
        description: Channel making request
        schema:
          type: string
          default: SMS
      - name: productType
        in: query
        description: Type of product
        schema:
          type: string
      - name: productCategory
        in: query
        description: Type of category
        schema:
          type: string
      responses:
        200:
          description: Details for a successful request.
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ProductEligibilityResponse'
        400:
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        401:
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        403:
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        404:
          description: Product not found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        405:
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        500:
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v3
  /products/{customerId}/blacklist/{productId}:
    post:
      description: Blacklist customer for product/service
      summary: Blacklist the customer to consume a product
      tags:
      - products
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier
        required: true
        schema:
          type: string
      - name: productId
        in: path
        description: ID of the product
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        required: false
        schema:
          type: string
      - name: targetSystem
        in: query
        description: The target system
        schema:
          type: string
          enum:
          - AirServer
          - CIS
          - CLM
          - MBAS
      responses:
        200:
          description: Details for a successful request.
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ProductEligibilityResponse'
        400:
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        401:
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        403:
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        404:
          description: Product not found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        405:
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        500:
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/BlacklistRequest'
        description: Order details for the payment link that is to be created.
        required: true
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v3
  /products/{customerId}/dormant:
    post:
      description: Make a customer dormant for product/service
      summary: Make a customer dormant in relation to a to a product
      tags:
      - products
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        required: false
        schema:
          type: string
      - name: targetSystem
        in: query
        description: The target system
        schema:
          type: string
          enum:
          - AirServer
          - CIS
          - CLM
          - MBAS
      responses:
        200:
          description: Details for a successful request.
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ProductEligibilityResponse'
        400:
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        401:
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        403:
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        404:
          description: Product not found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        405:
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        500:
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/DormantRequest'
        description: Order details for the payment link that is to be created.
        required: true
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v3
  /products/{customerId}/category:
    get:
      operationId: getProductCategory
      summary: Get product Category
      description: View the list of products Category for a subscriber.
      tags:
      - products
      parameters:
      - name: customerId
        in: path
        description: Customer Msisdn. The format must be E.123 e.g 2349062058464
        required: true
        schema:
          type: string
      - name: targetSystem
        in: header
        description: Target system
        schema:
          type: string
          enum:
          - FLYTXT
      - name: productType
        in: query
        required: true
        description: Specify the type of product request. e.g CVMoffer(Customer Value Management) is a Flytxt product.
        schema:
          type: string
          enum:
          - CVMoffer
      - name: nodeId
        required: true
        in: query
        description: Third parties unique identifier. Can also be called channelId or iname
        schema:
          type: string
      - name: transactionId
        in: header
        description: Client generated Id to include for tracing requests, so that the API can easily trace the HTTP request all the way from a client to MTNs backend processes (via our proxies). Each time a request is made to an MTN API the client should include a unique request reference in the HTTP Header. The value must be between 5 and 20 characters, and consist of ASCII letters, digits, or the characters. Invalid or blank IDs will be ignored and replaced with generated ones. MTN may use this to detect duplicate transactions from the client, but this functionality is not always guaranteed, so clients must make their own efforts to prevent duplicate transactions. MTN will also log the transactionId in order to assist with debugging and to correlate transactions processed by the API to requests from the client.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/OfferCategoryResponse'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '405':
          description: Method No Allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '406':
          description: Not acceptable
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '415':
          description: Unsupported media Type
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v3
  /products/{customerId}/eligible:
    get:
      operationId: getOffers
      summary: Get list of eligible Offers
      description: View the list of eligible products offers applicable for a subscriber.
      tags:
      - products
      parameters:
      - name: customerId
        in: path
        description: Customer Msisdn. The format must be E.123 e.g 2349062058464
        required: true
        schema:
          type: string
      - name: productType
        in: query
        required: true
        description: Specify the type of product request. e.g CVMoffer(Customer Value Management) is a Flytxt product.
        schema:
          type: string
          enum:
          - CVMoffer
          - Normal
          - Bundle
      - name: targetSystem
        in: header
        description: Target system
        schema:
          type: string
          enum:
          - FLYTXT
          - NEON_FLYTXT
      - name: credentials
        in: header
        description: Credentials to be passed by the 3PP
        x-example: aYxsiUusl878fsx
        schema:
          type: string
      - name: appCpid
        in: query
        description: Id of the product to fetch.
        required: false
        schema:
          type: string
      - name: category
        in: query
        description: Type of offer to fetch.
        required: false
        x-example: product
        schema:
          type: string
          enum:
          - Topdeal
          - Recharge
          - DataBundle
          - Combo
          - Voice
          - VAS
      - name: subCategory
        in: query
        required: false
        x-example: MOMO
        schema:
          type: string
      - name: nodeId
        required: false
        in: query
        description: Third parties unique identifier. Can also be called channelId or iname
        schema:
          type: string
      - name: transactionId
        in: header
        description: Client generated Id to include for tracing requests, so that the API can easily trace the HTTP request all the way from a client to MTNs backend processes (via our proxies). Each time a request is made to an MTN API the client should include a unique request reference in the HTTP Header. The value must be between 5 and 20 characters, and consist of ASCII letters, digits. Invalid or blank IDs will be ignored and replaced with generated ones. MTN may use this to detect duplicate transactions from the client, but this functionality is not always guaranteed, so clients must make their own efforts to prevent duplicate transactions. MTN will also log the transactionId in order to assist with debugging and to correlate transactions processed by the API to requests from the client.
        schema:
          type: string
      - name: limit
        in: query
        description: The total number of offers to retrieve
        x-example: 50
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/OfferResponse'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '405':
          description: Method No Allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '406':
          description: Not acceptable
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '415':
          description: Unsupported media Type
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v3
  /products/productOffering:
    get:
      operationId: listProductOffering
      summary: List or find ProductOffering objects
      description: This operation list or find ProductOffering entities
      tags:
      - products
      parameters:
      - name: transactionId
        in: header
        required: false
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        schema:
          type: string
      - name: senderId
        in: query
        required: true
        description: Provide the channel information
        x-example: IVR
        schema:
          type: string
      - name: topOffers
        description: If true is populated on this field, the service will return all the products where topOffers = true.
        required: false
        in: query
        schema:
          type: boolean
          default: 'false'
      - name: yelloTraderId
        description: Either one or multiple yelloTraderIds (deal code) separated with comma can be passed to fetch the offers associated. example - 2020710 CT 00350,2019711 CT 00351,2019713 CT 00352
        required: false
        in: query
        schema:
          type: integer
      - name: limit
        description: Requested number of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response_ProductOffering'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v3
  /products/productOffering/roaming:
    get:
      operationId: listofRoamingproducts
      summary: List of roaming ProductOffering objects
      description: This operation list or find all the roaming bundles that are available for the country and subscriber type
      tags:
      - products
      parameters:
      - name: transactionId
        in: header
        required: false
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        schema:
          type: string
      - name: x-origin-channelId
        in: header
        description: Provide the channel information
        x-example: IVR
        schema:
          type: string
      - name: targetSystem
        in: header
        description: Provide the target system information
        x-example: XMF
        schema:
          type: string
      - name: productName
        description: Provide the product name
        in: query
        schema:
          type: string
      - name: countryCode
        description: Provide the country code of the subscriber
        in: query
        x-example: CM
        schema:
          type: string
      - name: subscriberType
        description: Provide the subscriber type
        in: query
        x-example: P
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/roamingProductOffering'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v3
  /products/{id}/comvCatalogue:
    get:
      operationId: listProductCatalogue
      summary: List or find ProductCatalogue objects
      description: This operation list or find ProductCatalogue entities
      tags:
      - products
      parameters:
      - name: id
        in: path
        required: true
        description: Provide the service information
        x-example: IVR
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        schema:
          type: string
      - name: countryCode
        in: header
        description: Country code to include
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response_ProductCatalogue'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error_2'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
         

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