A MTN API that controls the display of the catalog of Products available for a customer to purchase.
swagger: '2.0'
# This is your document metadata
info:
version: "3.0.9"
title: MTN Product API
description: |
A MTN API that controls the display of the catalog of Products available for a customer to purchase.
host: api.mtn.com
basePath: "/v3"
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
security:
- ApiKeyAuth: []
- OAuth2: []
securityDefinitions:
ApiKeyAuth:
type: "apiKey"
name: "X-API-Key"
in: "header"
OAuth2:
type: oauth2
flow: application
tokenUrl: https://api.mtn.com/v1/oauth/access_token
# Describe your paths here
paths:
# This is a path endpoint. Change it.
/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
type: "string"
- name: productProviderId
in: query
type: string
description: This is the id of the service provider
required: false
- name: "credentials"
in: "header"
description: "Base64 encoding of 3rd party username and password"
required: false
type: "string"
- name: "category"
in: "query"
type: "string"
description: "Category of the product to be fetched from that catalogue"
- name: "subCategory"
in: "query"
type: "string"
description: "This can be any of the sub category of the category entered. This may be require only if the category is passed."
- name: "requestType"
in: "query"
type: "string"
description: "This determines the type of request being send. In callertunes, it holds the SOAP Action"
- name: "autoRenewal"
in: "query"
type: "string"
description: "Specify if the product should be auto renewal or not"
enum: [YES,NO]
- name: "serviceClass"
in: "query"
type: "string"
description: "Specify the class of service"
- name: "offerName"
in: "query"
type: "string"
description: "Specify the offer name to be searched"
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."
schema:
$ref: "#/definitions/ProductCatalogue"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
# This is a path endpoint. Change it.
/products/{customerId}:
get:
description: "Retrieves the Catalog of Products available to a customer identified by customerId, out of the catalog of products available to a 3PP identified by nodeId."
summary: "View product Catalog."
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
type: "string"
- name: "nodeId"
in: "query"
description: "3rd party assigned unique id"
required: false
type: "string"
- name: "credentials"
in: "header"
description: "Base64 encoding of 3rd party username and password"
required: false
type: "string"
- name: "offerType"
in: "query"
required: false
type: "string"
enum: [AIRTIME,VOICE,DATA,SMS,ALL,NDAKO]
- name: filterByMABand
in: query
type: boolean
required: false
description: When TRUE, The API shall return only the products that falls within the MSISDN main account balance band.
- name: "category"
in: "query"
type: "string"
description: "Category of the product to be fetched from that catalogue"
- name: "subCategory"
in: "query"
type: "string"
description: "This can be any of the sub category of the category entered. This may be require only if the category is passed."
- name: "productRef"
in: "query"
required: false
type: "string"
description: "This is an external reference number or product code which most have been generated by the provider or consumer"
- name: "channel"
in: "query"
required: false
type: "string"
enum: [USSD,Momo,MTNApp,MTNWeb,SMS,MOD]
- name: "productProviderId"
in: "query"
required: false
type: "string"
enum: [LUMOS,CIS]
description: This is the identifier for the backend system expected to fullfil the request
- in: "query"
name: "pref language"
required: false
description: The language in which the response is required
type: "string"
enum: [En,Fr]
- name: offerQuantity
type: number
description: For Bulk SMS product, this is the number of SMS to get a price quote for.
in: query
- name: "autoRenewal"
in: "query"
type: "string"
description: "Specify if the product should be auto renewal or not"
enum: [YES,NO]
- name: "serviceClass"
in: "query"
type: "string"
description: "Specify the class of service"
- name: "offerName"
in: "query"
type: "string"
description: "Specify the offer name to be searched"
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."
schema:
$ref: "#/definitions/ProductCatalogue"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/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
type: "string"
- name: "productId"
in: "path"
description: "ID of the product"
required: true
type: "string"
- in: query
name: "promotionCode"
type: string
required: false
description: "Promotion code assigned to product"
- in: query
name: "transactionId"
type: string
required: false
description: "Transaction ID"
- name: "credentials"
in: "header"
description: "Base64 encoding of 3rd party username and password"
required: false
type: "string"
responses:
200:
description: "Product Details. For a successful request, the response will contain all the details of the product."
schema:
$ref: "#/definitions/ProductBundlePrice"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Product not found"
schema:
$ref: "#/definitions/Error"
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/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
type: "string"
- name: "productId"
in: "path"
description: "ID of the product"
required: true
type: "string"
- name: "credentials"
in: "header"
description: "Base64 encoding of 3rd party username and password"
required: false
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"
type: "string"
- name: "clientTransactionId"
in: query
type: string
default: 234872789
description: "Client generated Id to include for tracing requests"
- name: "viewType"
in: query
type: string
description: "The view requested"
enum:
- checkOffer
- name: "targetSystem"
in: query
type: string
description: "The target system"
enum:
- AirServer
- CIS
- CLM
- MBAS
- name: "registrationChannel"
in: query
type: string
default: SMS
description: "Channel making request"
- name: "productType"
in: query
type: string
description: "Type of product"
- name: "productCategory"
in: query
type: string
description: "Type of category"
responses:
200:
description: "Details for a successful request."
schema:
$ref: "#/definitions/ProductEligibilityResponse"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Product not found"
schema:
$ref: "#/definitions/Error"
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/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
type: "string"
- name: "productId"
in: "path"
description: "ID of the product"
required: true
type: "string"
- name: transactionId
in: header
description: Client generated Id to include for tracing requests.
type: string
x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
required: false
- name: "targetSystem"
in: query
type: string
description: "The target system"
enum:
- AirServer
- CIS
- CLM
- MBAS
- name: BlacklistRequest
in: body
description: Order details for the payment link that is to be created.
required: true
schema:
$ref: '#/definitions/BlacklistRequest'
responses:
200:
description: "Details for a successful request."
schema:
$ref: "#/definitions/ProductEligibilityResponse"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Product not found"
schema:
$ref: "#/definitions/Error"
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/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
type: "string"
- name: transactionId
in: header
description: Client generated Id to include for tracing requests.
type: string
x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
required: false
- name: "targetSystem"
in: query
type: string
description: "The target system"
enum:
- AirServer
- CIS
- CLM
- MBAS
- name: DormantRequest
in: body
description: Order details for the payment link that is to be created.
required: true
schema:
$ref: '#/definitions/DormantRequest'
responses:
200:
description: "Details for a successful request."
schema:
$ref: "#/definitions/ProductEligibilityResponse"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Product not found"
schema:
$ref: "#/definitions/Error"
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/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
type: string
- name: "targetSystem"
in: header
type: string
description: "Target system"
enum:
- FLYTXT
- name: "productType"
in: "query"
type: "string"
required: true
enum:
- CVMoffer
description: "Specify the type of product request. e.g CVMoffer(Customer Value Management) is a Flytxt product."
- name: "nodeId"
required: true
type: string
in: "query"
description: "Third parties unique identifier. Can also be called channelId or iname"
- name: transactionId
in: header
type: string
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.
responses:
"200":
description: Success
schema:
$ref: '#/definitions/OfferCategoryResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/Error'
"401":
description: Unauthorized
schema:
$ref: '#/definitions/Error'
"403":
description: Forbidden
schema:
$ref: '#/definitions/Error'
"404":
description: Not Found
schema:
$ref: '#/definitions/Error'
"405":
description: Method No Allowed
schema:
$ref: '#/definitions/Error'
"406":
description: Not acceptable
schema:
$ref: '#/definitions/Error'
"415":
description: Unsupported media Type
schema:
$ref: '#/definitions/Error'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/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
type: string
- name: "productType"
in: "query"
type: "string"
required: true
enum:
- CVMoffer
- Normal
- Bundle
description: "Specify the type of product request. e.g CVMoffer(Customer Value Management) is a Flytxt product."
- name: "targetSystem"
in: header
type: string
description: "Target system"
enum:
- FLYTXT
- NEON_FLYTXT
- name: credentials
in: header
type: string
description: "Credentials to be passed by the 3PP"
x-example: "aYxsiUusl878fsx"
- name: "appCpid"
in: query
description: Id of the product to fetch.
required: false
type: string
- name: "category"
in: query
description: Type of offer to fetch.
required: false
type: string
enum:
- Topdeal
- Recharge
- DataBundle
- Combo
- Voice
- VAS
x-example: "product"
- name: "subCategory"
in: query
type: string
required: false
x-example: "MOMO"
- name: "nodeId"
required: false
type: string
in: "query"
description: "Third parties unique identifier. Can also be called channelId or iname"
- name: transactionId
in: header
type: string
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.
- name: limit
in: query
description: "The total number of offers to retrieve"
x-example: 50
type: string
responses:
"200":
description: Success
schema:
$ref: '#/definitions/OfferResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/Error'
"401":
description: Unauthorized
schema:
$ref: '#/definitions/Error'
"403":
description: Forbidden
schema:
$ref: '#/definitions/Error'
"404":
description: Not Found
schema:
$ref: '#/definitions/Error'
"405":
description: Method No Allowed
schema:
$ref: '#/definitions/Error'
"406":
description: Not acceptable
schema:
$ref: '#/definitions/Error'
"415":
description: Unsupported media Type
schema:
$ref: '#/definitions/Error'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/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.'
type: string
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- name: "senderId"
in: query
required: true
type: string
description: 'Provide the channel information'
x-example: 'IVR'
- name: topOffers
description: If true is populated on this field, the service will return all the products where topOffers = true.
required: false
in: query
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
type: integer
- name: limit
description: Requested number of resources to be provided in response
required: false
in: query
type: integer
responses:
'200':
description: Success
schema:
$ref: '#/definitions/Response_ProductOffering'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/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.'
type: string
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- name: "x-origin-channelId"
in: header
type: string
description: 'Provide the channel information'
x-example: 'IVR'
- name: targetSystem
in: header
type: string
description: 'Provide the target system information'
x-example: 'XMF'
- name: productName
description : 'Provide the product name'
in: query
type: string
- name: countryCode
description: 'Provide the country code of the subscriber'
in: query
type: string
x-example: 'CM'
- name: subscriberType
description: 'Provide the subscriber type'
in: query
type: string
x-example: 'P'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/roamingProductOffering'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error400'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error401'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error404'
/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
type: string
description: 'Provide the service information'
x-example: 'IVR'
- name: "transactionId"
in: header
required: false
description: 'Client generated Id to include for tracing requests.'
type: string
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- name: "countryCode"
in: "header"
description: "Country code to include"
required: false
type: "string"
responses:
'200':
description: Success
schema:
$ref: '#/definitions/Response_ProductCatalogue'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/products/productConfiguration/{id}:
get:
tags:
- products
summary: productConfiguration
description: product Configuration of items
operationId: configuration
parameters:
- name: transactionId
in: header
description: Client generated Id to include for tracing requests
type: string
required: true
- name: nodeId
in: query
description: Third parties unique identifier. Can also be called channelId
type: string
required: true
- name: cookie
in: header
required: true
description:
This is unique cookie, used to identify and the maintain session/state towards the backend system.
This value can be obtained from teh GET /session-cookie operation.
Example value - "JSESSIONID=rvUKhWtBRaC3zuyv_KxKQQmFq4tI0wla2D--0OBC46QKBGT4cMwI"
type: string
- name: siteId
in: query
required: true
type: string
description:
ATG is capable of handling multisite operations. Each site can have different catalog data, pricelist etc.
This parameter indicates which site the response must be given. Sample values MTNSite, OnlineStore, EBU_CC, EBU_SME
- name: id
in: path
required: true
type: string
description: This parameter represnts the DEP serviceId which must be queried
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/productConfigurationResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/products/{customerId}/productCheckBalance:
get:
operationId: getAllTypesOfbalances
summary: Get All Type of balance for a subscriber product
description: View the list of all types of product balances for a subscriber.
tags:
- products
parameters:
- name: "customerId"
in: path
description: Customer Msisdn. The format must be E.123 e.g 2319062058464
required: true
type: string
- name: "productType"
in: "query"
type: "string"
required: true
enum:
- Normal
- Bundle
description: "Specify the type of product request. e.g Normal product."
- name: "appCpid"
in: query
description: appId of the product to fetch.
required: false
type: string
- name: "productId"
in: query
description: Id of the product to fetch.
required: false
type: string
- name: "nodeId"
required: false
type: string
# --- truncated at 32 KB (122 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-mtn-product-offering-api-v3.yml