Welcome to the MTN Developer Platform

The MTN Developer Platform is a single point of access to a rich MTN developer ecosystem that brings a number of MTN services within easy reach of partners, startups, independent developers, enterprises, etc. Within this portal you will find access to our Mobile Money, Messaging, Location Services, Payment, Collections, E-Commerce, IoT,  Customer, Offers and Promotions, Digital Subscriptions, Identity and Access, Products and Bundles, and more API products.

We hope that you will join us in developing new and novel customer experiences and solutions. If you see something wrong or think that we are missing an API or service that could make your next app idea rock, please reach out to our team on the forum - it's a great place to rally other developers to make yourself heard. If you are an ISV and are developing a solution for a client or integrating your commercial product to one of our APIs, we'd really like to hear from you too - let's see how we can help you succeed.

As always, everything in life comes with terms and conditions. We have tried to make this portal and the API products freely available for you to try.  Some APIs may be free to use, while some may carry a  prepaid, postpaid or even a pay as you go usage fee. Some APIs may require a formal agreement with MTN, while some may only require the acceptance of the product's terms of service. Some APIs may require your customer's consent, while some may require you to use our identity service. Most APIs will be standardised across all MTN Operating Companies, but there may be some that have country-specific peculiarities. At all times we will highlight these nuances so that you are always aware of them. If anything is not clear please reach out to us through the forum, where the answer to your question may help other developers as well.

Take the time to explore the developer documentation. We have made every effort to explain how the developer site works, how to get started with your first app, some of the overarching design principles you will find in our APIs, our naming standards, and some key definitions. You will also find some examples that will help you through some of the challenges others have experienced, such as implementing some of the security requirements.  Above all... have fun and build exciting new digital experiences. We can't wait to see what you build.

Now check out all the Insights - Get Started, then head over to Things every developer should know.

Things every developer should know

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.

  1. API Key uses the x-api-key header, which you can get from the apps section on your profile, under Consumer Key
  2. 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 HATEOS 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 HATEOS 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

 

Response and Error Codes

The MTN API returns HTTP status codes in addition to JSON-based error codes and messages.

HTTP Status Codes

The MTN API attempts to return appropriate HTTP status codes for every request. Every response will be mapped to an appropriate HTTP Status Code.

Links

MTN API uses HATEOS links in the response contents so that the client can easier discover and navigate to the appropriate resource by traversing the hypermedia links.

 

Errors

 

Response/Error Code Grouping

The JSON-based response have been grouped, so as to ease identification.

Error Group Error Description  Code Range
Customer errors Errors that relate to the Customer/User object, like "User not found", "User ID not found"

0000-1999

Network Errors Errors related to network errors, like "Unreachable" 2000-2999
Server Errors Errors like "path not found", "resource moved" 3000-3999
Authentication Errors like "Access Denied", "Forbidden" 4000-4999
Parameters Errors related to fields or parameters 5000-5999
Billing Billing and Payment related errors like "Insufficient funds" "Billing failed" 6000-6999

 

Error Messages

MTN API error messages are returned in JSON format. For example, a 404 Not Found error might look like this:

HTTP/1.1 404
Date: Tue, 12 Mar 2019 07:24:54 GMT
Content-Type: application/json;charset=UTF-8
Connection: keep-alive
Set-Cookie: 4e67a54a3d6062c6a5e5c4046646604a=f3fa1a3a190f1bcafbe1c9046fcf4e5f; path=/; HttpOnly
Cache-control: private

{
    "timestamp": "2019-03-12T07:21:07.710+0000",
    "status": 404,
    "error": "Not Found",
    "message": "No message available",
    "path": "/customers/278320123456"
}

 

Error Codes

When you request a REST-ful API operation that cannot be executed by the MTN API, you get an error code in the response to let you know where the problem lays. Some of these error codes are mapped to standard HTTP status codes. See the table below to learn more about what each error code means and when it is returned. In addition to descriptive error text, error messages contain machine-parsable codes. While the text for an error message may change, the codes will stay the same. The Response/Error Codes are not to be confused with HTTP Status Codes. HTTP Status Codes appear in the HTTP header, while MTN API Error Codes appear in the JSON body, which is why they have been made 4 digits long.

The following table describes the codes which may appear when working with the API. They have been mapped to the HTTP status codes in order to determine the best way to address the issue.

Error Code Error Description  HTTP Status code
0000 Success 200
1000 User not found 404
1001 Request error 400
1002 Already subscribed 400
1003 Already un-subscribed 400
1004 Request pending 102
1005 Retry 500
1007 Operation timeout 500
1012 Timeout 408
1013 Request rate exceeded 429
2000 Connection error 400
3000 Service not available 503
3001 System error 500
3003 Timeout 408
3006 Rate exceeded 429
4000 Unauthorised 401
4001 Not allowed 405
5000 Invalid Parameters 400
5001 Request failed 400
6000 Billing failed 403
6001 Insufficient funds 403

For a successful request, the response will contain the requested object. But we differentiate between:##Multi-Status Responses

  1. When the request was successful, but there was no data. If the customer does not have any requested data, then it will be null. E.g. if the customer does not have a MoMo account, then the momo resource object will be null:
"momo": null,
  "_links": {
    "self": {
      "href": "https://api.mtn.com/v1/customers/2783200000/momo"
    }
  }

If the customer does not have any location set, then Country and Operator will be null.

"data": {
    "country": "null",
    "operator": "null"
    }
  1. Where there was a failure in retrieving some of the data, which is when it wil be a multi-status response. In this case, the client needs to examine the HTTP Status Code, and check the JSON body to determine which part failed. If there was an error retrieving some part of the request, then the HTTP Status Code will be set to 207, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving location, then the data object will be empty, and will not contain Country or Operator properties"

    "data": { }

If all of the service providers are not available, then it will be a multi-status response, containing only some of the requested service providers. In this, the HTTP Status Code will be set to 207, and the systems array will contain an Inactive system. E.g

HTTP/1.1 207
...

{
            "systemId": "RBT",
            "status": "Inactive",
            "statusCode": 200,
            "message": "Request timed out."
        },

OAuth 2.0

Access to all MTN APIs is based on the OAuth 2.0 framework, so developers are required to obtain an OAuth access token in order to make successful API calls. To obtain an OAuth access token, a developer shall register their app and obtain Consumer Key and Consumer Secret. To retrieve an OAuth access token, a request to the token endpoint will be made using the Consumer Key and Secret, and specifying the "client credentials" grant type. The sequence diagram below illustrates the implemented flow.

 

OAuth Flow

 

Get Access Token

The first action is to get an access token. This requires calling the token endpoint using your App credentials--the consumer key and secret that are generated when registering the App. The endpoint that is called is:

https://api.mtn.com/oauth

And it can be called as follows:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" https://api.mtn.com/oauth/client_credential/accesstoken?grant_type=client_credentials -d 'client_id={consumer-key}&client_secret={consumer-secret}'

 

After firing the request above, a successful response should look like the one below.

HTTP/1.1 200 OK

Content-Type: application/json { "issued_at" : "1466025123306", "application_name" : "716bbe61-f14a-4e45-9b56-a62ff8e0d347", "scope" : "", "status" : "approved", "api_product_list" : "[sms-product, vpn-product]", "expires_in" : "1800", //--in seconds "developer.email" : "nerd@mtn.com", "token_type" : "BearerToken", "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1rtp", "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0utR0", "organization_name" : "MTN Production", "refresh_token_expires_in" : "0", //--in seconds "refresh_count" : "0" }

 

Make an API call

From the response returned when calling the token endpoint, the access_token must be extracted and used to make an API call. It's mandatory that the access token be used as the header Authorization parameter.

Header Authorization parameter:

Authorization: Bearer GTPY9VUHCqKVMRB0cHxnmAp0utR0

 

Using the OAuth access token, an API call to our subscription API would look like:

curl https://api.mtn.com/customers/27811111111/subscriptions -H "Authorization: Bearer {access_token}"

Getting help with the MTN API developer platform

If you already using the platform, and need to verify if the MTN API Platform is up and responsive, or perhaps down due to maintenance, then check out the status page.

After having read all the documents listed on the MTN Developer Platform site, you can get assistance from MTN Developer Hub community Q&A site.  Sign up, browse the existing Questions to see if someone else has already had the same question, or ask a new Question