swagger: '2.0'
info:
version: v.2.3
title: MTN Customer Plans API
contact:
name: MTN API Support
email: developer-support@mtn.com
description: |-
An API to retrieve the Plan details of an MTN customer and calculate aYo premiums. Can also be used by 3rd-party partners (3PP) for airtime recharge of a prepaid subscriber
**24-June-21: ChangeID: c835ca3**
- Added an optional channel parameter on the /customers/{customerId}/plans/refill endpoint
**09-August-21: ChangeID: 87f0b10**
- Added optional UC/UT objects in the wallet response
**07-February-22: ChangeID : 1122**
Added query parm for getFRI integration and accountholderid list . as well as FinancialResourceInformation object in the response(Joli)
**01-June-2023: New request used to initiate block/unblock for FRI
host: api.mtn.com
basePath: /v2
schemes:
- https
consumes:
- application/json
produces:
- application/json
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:
/customers/{id}/plans/FRI:
get:
tags:
- Customers
summary: Retrieves a customers FRI
description: Retrieves FRI for MTN customer.
operationId: getFRIUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: FRI
description: Financial Resource Information
required: true
schema:
$ref: '#/definitions/GetFRIRequest'
- name: id
in: path
description: id
required: true
type: string
- name: targetSystem
in: header
description: Target System
required: true
type: string
- name: transactionId
in: header
description: transactionId
required: true
type: string
- name: x-country-code
in: header
description: x-country-code
required: true
type: string
responses:
'200':
description: OK
schema:
$ref: '#/definitions/GetFRIResponse'
'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
examples:
The data object/envelope will be null:
data: null
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
'/customers/{id}/plans/FRI/state':
patch:
tags:
- Customers
summary: Block and Unblock operations are initiated on Customer FRI
description: By Interpreting value for 'state' MADAPI initiates Block and Unblock requests on Customer FRI
operationId: UpdateFRIUsingPATCH
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: FRI
description: Financial Resource Identifier
required: true
schema:
$ref: '#/definitions/UpdateFRIRequest'
- name: id
in: path
description: ID of the customer. It could be MSISDN, email etc. combination of id and idType defines accountHolderId which will be sent to ECW System as identity
required: true
type: string
- name: idType
in: header
description: idtype defines the identification type being sent by the 3pp like MSISDN, customer id etc
enum: [MSISDN]
type: string
- name: targetSystem
in: header
description: Target System is the backend to which MADAPI Sends th request
type: string
required: true
- name: transactionId
in: header
description: transactionId is unique identifier for every request, it is sent by source system like SAS to MADAPI
type: string
- name: x-origin-channelId
in: header
description: Source System Details like SAS etc
type: string
- name: x-authorization
in: header
description: 'Encrypted ECW credentials'
type: string
required: true
responses:
'200':
description: OK
schema:
$ref: '#/definitions/UpdateFRIResponse'
'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
examples:
The data object/envelope will be null:
data: null
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
'/customers/{customerId}/plans':
get:
description: Retrieves the Billing Plan and related details of an MTN customer.
summary: View customer plans
tags:
- Customers
parameters:
- name: customerId
in: path
description: 'ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be Eg.123'
required: true
type: string
- name: fixedLine
in: query
description: Fixed line whose balances is fetched
required: false
type: string
- name: plan
in: query
description: Plan type to filter list of balances
required: false
type: string
enum:
- VOICE
- DATA
- SMS
- name: momo
in: query
description: Indicates whether to query balances for a MoMo Customer
required: false
type: boolean
- name: includeReservations
in: query
description: Indicates whether reservations should be included in the response. This parameter goes hand in hand with the momo query parameter and will have no use if supplied when momo is not true. Default is false.
required: false
type: boolean
- name: referenceid
in: query
description: This is required to handle the correlation between the 2 systems
required: false
type: string
- name: quoteid
in: query
description: Indicates whether a corresponding quote should be considered. This parameter goes hand-in-hand with the momo query parameter and will have no use if supplied when momo is not true.
required: false
type: string
- name: targetSystem
type: string
in: query
description: "Name of the backend system"
x-example: "EWP"
- name: segment
type: string
in: query
required: false
description: This is the type of customer doing the transaction. This can be agent, admin , merchant or subscriber
enum:
- subscriber
- admin
- agent
- merchant
- name: idType
type: string
in: query
required: false
description: Type of the customerId in the path.
enum: [MSISDN, USER]
- in: "query"
name: "prefLanguage"
required: false
description: The language in which the response is required
type: "string"
enum: [En,Fr]
- in: "query"
name: "amount"
required: false
description: The threshold amount against which the actual balance will be compared
type: "integer"
- name: transactionId
in: header
description: unique ID generated for each transaction
required: false
type: string
- name: usageType
type: number
in: query
required: false
description: Type of usage to be fetched. 1 – All, 2 – Active, 3 – Inactive
enum: [1, 2, 3]
- name: extRequest
type: string
in: query
required: false
description: Define if the request is external or not.
enum: [YES, NO]
responses:
'200':
description: 'Customer Plans object. For a successful request, the response will contain all the customers details. If the customer does not have any requested data, then those fields will be null. E.g. if the customer does not have a startDate set, then it will be null. If the customer does not have any Balance set, then the Balance array will be null.'
schema:
$ref: '#/definitions/CustomerPlans'
'207':
description: 'If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving Balance information, then the balance object will be empty'
examples:
'Partially Successfuls Response, showing valid plan data, but balance object is null':
data:
type: Postpaid
status: Active
startDate: '2019-04-12T14:31:21.810Z'
endDate: '2021-04-12T14:31:21.810Z'
language: '1'
balance: null
'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
examples:
The data object/envelope will be null:
data: null
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
patch:
tags:
- "Customers"
summary: "Tariff plan migration"
description: "Migrate the customer from one tariff plan to another"
operationId: "trariffMigration"
security:
- ApiKeyAuth : []
parameters :
- name : "customerId"
in : "path"
description: "ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123"
type : "string"
required : true
- name: transactionId
in: header
description: Client generated unique Id to include for tracing requests
type: string
required: false
- name: "body"
in: "body"
required: true
schema:
type : "object"
required:
- planId
properties:
planId:
type: string
example: NACT_NG_others_2
providerId:
type: string
enum:
- CIS
description: "Target system meant to process the request"
responses :
"200" :
description : "OK"
schema :
type: object
properties:
statusCode:
type: string
description: HTTP error code extension
example: "0000"
statusMessage:
type: string
example: "Success"
sequenceNo:
type: string
description: A unique identifier for tracking all requests
example: "1239848898"
data:
type : "object"
properties:
responseType:
example: "PRODUCT"
action:
example: "PRODUCT_BUY"
planId:
example: "NACT_NG_others_2"
productId:
example: "2"
productName:
example: "Change Plan"
productType:
example: "others"
amount:
type: string
description: "The whole units of the amount."
example: "100"
country:
type: string
example: "NG"
notification:
type: string
example: "You are successfully migrated to xyz paln."
_link:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: "https://api.mtn.com/v1/customers/2348064816493/plans/trariff"
"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"
"500" :
description : "Internal Server Error"
schema :
$ref : "#/definitions/Error"
"503" :
description : "Service Unavailable"
schema :
$ref : "#/definitions/Error"
"999" :
description : "Unknown Error"
schema :
$ref : "#/definitions/Error"
post:
description: Requesting a MTN customer's premium per product.
summary: Request Premium
tags:
- Premiums
parameters:
- name: customerId
in: path
description: 'ID of the customer who is sending the transaction. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123'
required: true
type: string
- in: body
name: body
description: Request body
required: true
schema:
$ref: '#/definitions/PremiumRequest'
responses:
'200':
description: 'Customer Plans Premium object. For a successful request, the response will contain all the customers Premium details. If the customer does not have any requested data, then those fields will be null."'
schema:
$ref: '#/definitions/CustomerPremium'
'207':
description: 'If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded.'
'400':
description: Bad Request
schema:
$ref: '#/definitions/PremiumError'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/PremiumError'
'403':
description: Forbidden
schema:
$ref: '#/definitions/PremiumError'
'404':
description: Customer not found
examples:
The data object/envelope will be null:
data: null
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/PremiumError'
'/customers/{customerId}/plans/{productCode}':
get:
description: Retrieves plans for product
summary: View customer plans for product
tags:
- Customers
security:
- ApiKeyAuth: []
parameters:
- name: customerId
in: path
description: 'ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123'
required: true
type: string
- name: productCode
in: path
description: Product code for data package
required: true
type: string
responses:
'200':
description: 'Customer Plans object. For a successful request, the response will contain all the plans details. If the customer does not have any requested data, then those fields will be null. E.g. if the customer does not have a startDate set, then it will be null. If the customer does not have any Balance set, then the Balance array will be null.'
schema:
$ref: '#/definitions/CustomerPlans'
'207':
description: 'If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving Balance information, then the balance object will be empty'
examples:
'Partially Successfuls Response, showing valid plan data, but balance object is null':
data:
type: Postpaid
status: Active
startDate: '2019-04-12T14:31:21.810Z'
endDate: '2021-04-12T14:31:21.810Z'
language: '1'
balance: null
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'/customers/{customerId}/plans/refill':
patch:
tags:
- Customers
summary: Airtime Refill
description: Will be used by 3rd-party partners (3PP) for airtime recharge of a prepaid subscriber
operationId: refillAccount
security:
- ApiKeyAuth: []
parameters:
- name: customerId
in: path
description: 'ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123'
type: string
required: true
- name: transactionId
in: header
description: Client generated unique Id to include for tracing requests
type: string
required: false
- name: sourceSystemId
in: header
description: Source system Id to include for tracing requests
type: string
required: false
- name : "channel"
in : "header"
type: 'string'
enum:
- MyMTNApp
- MOD
- name: partnerName
in: header
type: string
description: Partner Name
- name: refillRequest
in: body
required: true
schema:
type: object
required:
- refillType
properties:
refillType:
type: string
description: Specify the refill type
enum:
- voucher
- voucherless
voucherActivationCode:
type: string
description: 'Voucher Activation Code, Required if refillType is Voucher Base.'
refillProfileId:
type: string
description: 'Refill Profile ID, Required if refillType is Voucherless.'
transactionAmount:
type: string
description: Required if refillType is Voucherless
targetSystem:
type: string
description: Backend system expected to fulfil the request
enum: [PPMS, AIR]
serialNumber:
type: string
description: Serial number of the voucher incase the refill is voucher
responses:
'200':
description: OK
schema:
type: object
properties:
statusCode:
type: string
description: HTTP error code extension
statusMessage:
type: string
sequenceNo:
type: string
description: A unique identifier for tracking all requests
example: "1239948893"
data:
type: object
properties:
amount:
type: string
description: 'The whole units of the amount. For example if currency is NGN, then 100 unit is'
currencyCode:
type: string
description: The 3-letter currency code defined in ISO 4217.
serialStatus:
type: string
description: Status of the voucher being loaded
actionStatus:
type: string
description: Status of the action being taken
status:
type: string
description: Status of the refill
addtionalInformation:
type: object
properties:
name:
type: string
description: Additional information name
description:
type: string
description: Description of the additional information
_link:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.mtn.com/v1/customers/2348064816493/refill
'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'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Error'
'999':
description: Unknown Error
schema:
$ref: '#/definitions/Error'
'/customers/{id}/plans/provision':
post:
tags:
- Customers
summary: Provision the customer and return customer details along with MSISDN
description: Provision the customer and returns customer details along with MSISDN with SIM number as input.
operationId: getCustomerDetails
parameters:
- name: id
in: path
description: This could be either MSISDN or Serial number of the SIM of the customer for who the provision request is raised.
required: true
type: string
- name: transactionId
in: header
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, Payjoy'
required: false
type: string
- name: idType
in: query
type: string
description: Mention the type of id- MSISDN or Serial number of the SIM.
enum: ['MSISDN', 'SerialNumber']
required: true
- name: body
in: body
required: true
schema:
$ref: '#/definitions/customerDetails_Request'
responses:
'200':
description: IBF Provision Response
schema:
$ref: '#/definitions/provisionResponse'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error400'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error401'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error404'
'415':
description: Unsupported Media Type
schema:
$ref: '#/definitions/Error415'
'500':
description: Unsupported Media Type
schema:
$ref: '#/definitions/Error500'
definitions:
FinancialResourceInformationRequest:
type: object
required:
- accountholderId
properties:
additionalRequestInformation:
type: string
description: Any additional information the consumer might want to send to the backend, as per agreement with the backend. This is nto validated by MADAPI and will be sent thru as-is to the backend
accountholderId:
type: string
description: The account holder who initiated the request
example: ID:245966601404/MSISDN
currency:
type: string
description: Currency passed from the engagement layer enumerated field
enum:
- ZAR
- NGN
- GB
- MB
- MINUTES
- SMS
- FCFA
- CDF
- GNF
FinancialResourceInformationResponse:
type: object
properties:
message:
type: string
description: Any message the backend would like tot return to the consumer
sequenceNo:
type: string
description: A unique identifier for tracking all requests
example: "12345433"
additionalInformation:
type: string
description: Any additional information the backend might want to return, as per agreement with the consumer. This is nto validated by MADAPI and will be sent thru as-is to the consumer
friLoyaltyInfo:
$ref: '#/definitions/LoyaltyBalances'
PremiumRequest:
type: object
required:
- receivingCustomerId
- transactionId
- product
- amount
- transactionType
properties:
amount:
type: string
$ref: "#/definitions/Amount"
transactionId:
type: string
description: Internal correlation ID
accountHolderId:
type: string
description: The accountholder's ID to which the sendingCustomerId belong
quoteId:
type: string
description: Can be provided when a quote is associated with the request.
receivingCustomerId:
type: string
description: The beneficiary's customer ID.
product:
type: string
description: The product for which the premium is requested
transactionType:
type: string
description: Different transaction types can have different premiums associated with it.
message:
type: string
description: The calling customer can populate a message intended for the back-end application.
CustomerPremium:
type: object
required:
- originReferenceId
properties:
originReferenceId:
type: string
description: Origin Reference Id
statusCode:
type: string
description: 'This will have MADAPI response mapping, based on the value received from the downstream system'
data:
$ref: '#/definitions/PremiumData'
PremiumData:
type: object
description: Contains response information pertaining to the premium request.
properties:
message:
type: string
description: A message send by the back end pertaining to the premium calculation request
premium:
$ref: '#/definitions/Amount'
loyaltyInformation:
$ref: '#/definitions/LoyaltyBalances'
LoyaltyBalances:
type: object
description: Contains all the loyalty balances associated with a customer.
properties:
generatedAmount:
$ref: '#/definitions/Amount'
consumedAmount:
$ref: '#/definitions/Amount'
newBalance:
$ref: '#/definitions/Amount'
CustomerPlans:
type: object
required:
- _link
properties:
statusCode:
type: string
example: "0000"
transactionId:
type: string
example: "21136326455582"
statusMessage:
type: string
example: "Successfully Processed"
supportMessage:
type: string
example: "Successfully Processed request"
sequenceNo:
type: string
description: A unique identifier for tracking all requests
example: "123433"
fttxError:
type: string
example: null
data:
$ref: '#/definitions/Plans'
OfferDetails:
type: object
description: The Offer Details per customer.
properties:
offerId:
type: string
example: 123456
description: The Offer ID
offerType:
type: string
example: 2
description: The type of offer
startDate:
type: string
format: dateTime
example: "20210205T16:08:08+0530"
description: The start date of offer
expiryDate:
type: string
format: dateTime
example: "20210205T16:08:08+0530"
description: Date at which offer will expire
expiryDateValue:
type: string
example: 53402237800000
description: Value of the expiry date
MomoBalanceDetail:
type: object
description: The MoMo Balance details for a requested customer.
properties:
status:
type: boolean
description: status of the user balance compared with threshold amount passed in request. FALSE if balance >= Amount sent in request. TRUE if balance <Amount sent in request
default: false
balance:
$ref: '#/definitions/Amount'
positiveReservations:
$ref: '#/definitions/Amount'
negativeReservations:
$ref: '#/definitions/Amount'
loyaltyInformation:
$ref: '#/definitions/LoyaltyBalances'
overdraft:
$ref: '#/definitions/OverdraftInformation'
OverdraftInformation:
type: object
description: Contains overdraft balances if available
properties:
balance:
$ref: '#/definitions/Amount'
limit:
$ref: '#/definitions/Amount'
accessFee:
$ref: '#/definitions/Amount'
interest:
$ref: '#/definitions/Amount'
Plans:
type: object
required:
- type
- status
- startDate
- endDate
- language
- tariffPlan
- balance
description: The plan details for the customer.
properties:
offers:
$ref: '#/definitions/OfferDetails'
type:
type: string
description: The billing type of the plan.
enum:
- Prepaid
- Postpaid
- Hybrid
status:
type: string
description: The current status of the plan.
enum:
- Active
- Suspended
- Inactive
- RICA Barred
- Blacklisted
startDate:
type: string
description: The date the customer was created/provisioned
format: date-time
customerType:
type: string
description: To return the customer type of the number. E.g Staff, Contractor, etc.
example: "Staff"
endDate:
type: string
description: The date the plan will be deactivated.
format: date-time
language:
type: string
description: The customers language.
tariffPlan:
type: string
de
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-mtn-customer-plans-api-v2.yml