The purpose of this page is to detail the design principles, objects, behaviours and error handling for MTN APIs. The overriding goal of this portal is to enable all parties to implement MTN APIs in a flexible, yet consistent manner. We hope to achieve this by implementing the following principles:
- Use of REST architectural principles and best practices.
- Providing a set of well-defined objects that are abstracted from the underlying object representations held in the various MTN and partner systems. This allows an API client to construct an API message without requiring specific knowledge of the target server implementation.
- Creation of a standard set of transaction types and other key enumerations, removing the need for developers to map for each and every API implementation.
- Use of ISO international standards for enumerators such as currency and country codes.
- Use of supplementary metadata and sub-types to enable use case specific properties to be conveyed where necessary.
- Aligning our resource, entity and object implementations with existing industry guidelines from TM-Forum, GSMA and Open Mobile Alliance whenever possible.
Getting Started
Read the Get Started page which will show you how to Register and create an app.
MTN API supports two Authorisation mechanisms
MTN APIs currently have two authorisation mechanisms: API Key, and OAuth. Most of the MTN APIs use API Key today to support legacy apps, but is switching over to OAuth. Each API products page will specify what authorisation mechanisms each API uses.
- API Key uses the x-api-key header, which you can get from the apps section on your profile, under Consumer Key
- We use a standard OAuth 2.0 scheme for authorization. To make calls, check out our OAuth page to get information on implementing a 2-legged and 3-legged OAuth flow.
The API aims to be a RESTful resource
The MTN API endpoints attempt to conform to the design principles of Representational State Transfer (REST) Level 3. MTN APIS uses HATEOAS links in the response contents so that the client can easily discover and navigate the appropriate resource by traversing the hypermedia links.
JSON Conventions
MTN APIs use the JSON data format for responses (and in some cases, for requests), using the camelCase naming convention for fields. MTN API uses a JSON "data" envelope for most responses. The typical response of MTN APIs, including JSON and HATEOAS links are:
{
"data": {
.........
},
"_links": {
"self": {
"href": "https://api.mtn.com/......"
}
}
}The API is HTTP-based (over SSL)
Methods to retrieve data from the MTN API require a GET request. Methods that submit, change or destroy data require a POST. A DELETE request is also accepted for methods that destroy data. API methods that require a particular HTTP method will return an error if not invoked using the correct style. HTTP Response Codes are meaningful.
Sandbox area to play with the APIs
MTN APIs have a sandbox area on sandbox.api.mtn.com where you can play with the API. It responds with dummy account data so you can interact with the API in a real way
End points
MTN operates in 21 countries across Africa and the Middle East. Not all OpCos support all APIs. Each API Products page indicates which OpCo support which API. To allow clients and developers to easily consume APIs, the MTN Developer Platform exposes APIs on different endpoints. However, irrespective of the endpoint, the API operates and works in the same way, and the base path will be identical across all endpoints.
Endpoints use the <host>/<basePath> format. The <host> portion is defined as either Global or OpCo. However, per API, irrespective of the <host>, the <basePath> will always remain the same. The Global <host> for most APIs and most OpCos is api.mtn.com. For OpCo specific <host>, the format will be {opco}.api.mtn.com, like nigeria.api.mtn.com or southafrica.api.mtn.com
Versions in the URL
MTN APIs use URI namespace versioning, like https://api.mtn.com/v1/customers. For new and breaking changes, new versions will be released, and only 2 versions will be maintained. Versions older than n-1 will NOT be supported, and you will be required to change to a new version.
Various Client Headers are supported
For APIs that use API Keys for authorisation, clients must use the x-api-key header. Various other headers may also be required to be sent by clients - each APIs Product page lists the headers supported. MTN APIs support the transactionID header, generated and sent by the client, to allow for traceability. In most cases its optional, but certain APIs require it in order to trace requests.
Synchronous and Asynchronous Operations and Headers
MTN API will respond synchronously with a HTTP 200 OK header for requests that can be immediately processed (like GET requests). Synchronous POST operations will result in the MTN API responding with a 201 Created, and a copy of the created object in the body. For certain other operations that require asynchronous processing (certain POST methods), MTN API will respond with a HTTP 201 Accepted Header to indicate an asynchronous response, containing a status object in the body.
Callbacks and polling
For asynchronous operations, certain APIs allow clients to either poll for the final response, or the MTN API Platform will callback to the clients end-point with the final result. MTN API does not support this client end-point to have authentication enabled.
Caching is used to speed up certain responses
Certain APIs will return cached responses for data that does not change very frequently, in order to speed up responses
APIs are described using OpenAPI
MTN APIs are written and described using OpenAPI Specification version 2 (Swagger).
Encoding Standards
MTN APIs use E.123 format for telephone MSISDN numbers, and ISO 3166 format for country names and codes, and RFC 3339 for date/time fields
Customer Identities
MTN APIs use E.123 format for telephone MSISDN numbers, to identify a customer. Soon other mechanisms of Identity will be supported