Plans v2

AVAILABLE IN

Ghana Nigeria Eswatini Uganda South Africa

Download

Download Postman collection Download Swagger

Available endpoints

GET v2/customers/{customerId}/plans

Description

Retrieves the Billing Plan and related details of an MTN customer.

Header parameters

x-authorization string
Encrypted ECW credentials
Content-Type application/json

Auth parameters

apikey X-API-Key

Query parameters

fixedLine string
Fixed line whose balances is fetched
plan string
Plan type to filter list of balances
momo boolean
Indicates whether to query balances for a MoMo Customer
includeReservations boolean
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.
quoteid string
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.
200OK
_link
self
href string
The link to retrieve the plans for a customer.
data
type string
The billing type of the plan.
status string
The current status of the plan.
startDate string
The date the customer was created/provisioned
endDate string
The date the plan will be deactivated.
language string
The customers language.
tariffPlan string
The customers active tariff plan.
balance
balanceType string
Identifies the type of balance. A customer plan may have multiple types of balances for different usage, for example, voice, SMS, and game services.
expiryDate string
Expiry date of the wallet's value.
category string
Identifies the category of the balance type.
balanceDetail
type string
This is the type of the value.
activeValue string
This is the aggregated formatted active value of a balance type.
activeUnit string
This is the unit of the aggregated active value.
unusedValue string
This is the aggregated formatted unused value of a balance type.
unusedUnit string
This is the unit of the aggregated unused value.
momoBalanceData
balance
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
positiveReservations
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
negativeReservations
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
loyaltyInformation
generatedAmount
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
consumedAmount
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
newBalance
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
overdraft
balance
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
limit
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
accessFee
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
interest
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
wallets
name string
The name of a wallet account.
status string
The status of a wallet's value.
expiryDate string
Expiry date of the wallet's value.
amount
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
{
    "_link": [],
    "data": []
}
207Multi-Status
400Bad Request
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
401Unauthorized
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
403Forbidden
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
404Not Found
405Method Not Allowed
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
500Internal Server Error
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
GET v2/customers/{customerId}/plans/{productCode}

Description

Retrieves plans for product

Header parameters

Content-Type application/json

Auth parameters

apikey X-API-Key
200OK
_link
self
href string
The link to retrieve the plans for a customer.
data
type string
The billing type of the plan.
status string
The current status of the plan.
startDate string
The date the customer was created/provisioned
endDate string
The date the plan will be deactivated.
language string
The customers language.
tariffPlan string
The customers active tariff plan.
balance
balanceType string
Identifies the type of balance. A customer plan may have multiple types of balances for different usage, for example, voice, SMS, and game services.
expiryDate string
Expiry date of the wallet's value.
category string
Identifies the category of the balance type.
balanceDetail
type string
This is the type of the value.
activeValue string
This is the aggregated formatted active value of a balance type.
activeUnit string
This is the unit of the aggregated active value.
unusedValue string
This is the aggregated formatted unused value of a balance type.
unusedUnit string
This is the unit of the aggregated unused value.
momoBalanceData
balance
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
positiveReservations
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
negativeReservations
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
loyaltyInformation
generatedAmount
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
consumedAmount
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
newBalance
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
overdraft
balance
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
limit
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
accessFee
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
interest
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
wallets
name string
The name of a wallet account.
status string
The status of a wallet's value.
expiryDate string
Expiry date of the wallet's value.
amount
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
{
    "_link": [],
    "data": []
}
207Multi-Status
400Bad Request
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
401Unauthorized
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
403Forbidden
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
POST v2/customers/{customerId}/plans/{productCode}

Description

Requesting a MTN customer's premium per product.

Header parameters

Content-Type application/json

Auth parameters

apikey X-API-Key

FormData parameters

amount object
The amount details for a wallet.
Properties:
    type:
        type: string
        description: This is the type of the wallet value.
        options: CURRENCY, DATA, MINUTES, SMS
    value:
        type: string
        description: This is the value of a balance wallet.
    unit:
        type: string
        description: This is the unit of the wallet value.
        options: ZAR, NGN, GB, MB, MINUTES, SMS, FCFA
        example: NGN
transactionId string required
Internal correlation ID
accountHolderId string
The accountholder's ID to which the sendingCustomerId belong
quoteId string
Can be provided when a quote is associated with the request.
receivingCustomerId string required
The beneficiary's customer ID.
product string required
The product for which the premium is requested
transactionType string required
Different transaction types can have different premiums associated with it.
message string
The calling customer can populate a message intended for the back-end application.
200OK
originReferenceId string
Origin Reference Id
statusCode string
This will have MADAPI response mapping, based on the value received from the downstream system
data
message string
A message send by the back end pertaining to the premium calculation request
premium
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
loyaltyInformation
generatedAmount
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
consumedAmount
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
newBalance
type string
This is the type of the wallet value.
value string
This is the value of a balance wallet.
unit string
This is the unit of the wallet value.
link
self
href string
Hyperlink to access the problem.
{
    "originReferenceId": [],
    "statusCode": [],
    "data": [],
    "link": []
}
207Multi-Status
400Bad Request
statusCode string
This will have MADAPI response mapping, based on the value received from the downstream system
statusMessage string
More details and corrective actions related to the error which can be shown to a client.
supportMessage string
Support Message
transactionId string
Message ID
_links
self
href string
Hyperlink to access the problem.
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "_links": []
}
401Unauthorized
statusCode string
This will have MADAPI response mapping, based on the value received from the downstream system
statusMessage string
More details and corrective actions related to the error which can be shown to a client.
supportMessage string
Support Message
transactionId string
Message ID
_links
self
href string
Hyperlink to access the problem.
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "_links": []
}
403Forbidden
statusCode string
This will have MADAPI response mapping, based on the value received from the downstream system
statusMessage string
More details and corrective actions related to the error which can be shown to a client.
supportMessage string
Support Message
transactionId string
Message ID
_links
self
href string
Hyperlink to access the problem.
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "_links": []
}
404Not Found
405Method Not Allowed
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
500Internal Server Error
statusCode string
This will have MADAPI response mapping, based on the value received from the downstream system
statusMessage string
More details and corrective actions related to the error which can be shown to a client.
supportMessage string
Support Message
transactionId string
Message ID
_links
self
href string
Hyperlink to access the problem.
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "_links": []
}
PATCH v2/customers/{customerId}/plans/refill

Description

Will be used by 3rd-party partners (3PP) for airtime recharge of a prepaid subscriber

Header parameters

transactionId string
Client generated unique Id to include for tracing requests
sourceSystemId string
Source system Id to include for tracing requests
Content-Type application/json

Auth parameters

apikey X-API-Key

FormData parameters

refillType string
Specify the refill type
voucherActivationCode string
Voucher Activation Code, Required if refillType is Voucher Base.
refillProfileId string
Refill Profile ID, Required if refillType is Voucherless.
transactionAmount string
Required if refillType is Voucherless
200OK
statusCode string
HTTP error code extension
statusMessage string
data
amount string
The whole units of the amount. For example if currency is NGN, then 100 unit is
currencyCode string
The 3-letter currency code defined in ISO 4217.
_link
self
href string
{
    "statusCode": [],
    "statusMessage": [],
    "data": [],
    "_link": []
}
400Bad Request
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
401Unauthorized
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
403Forbidden
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
404Not Found
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
500Internal Server Error
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
503Service Unavailable
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
999Unknown Error
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
This is the same transactionId that is sent in the request
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}