MTN MoMo Api dictionary for developers

MTN MoMo (Mobile Money) API provides a set of tools and resources for developers to easily integrate MTN MoMo services into their applications. These tools can be used to build applications that leverage the MTN MoMo platform to enable digital payments, manage bill payments, financial transactions, and more.

MTN MoMo API is a system that allows developers to integrate MTN mobile money services into their own applications. MTN Mobile Money is a digital wallet service that enables users to send and receive money, pay bills, buy airtime and data, and make other transactions using their mobile phones. By integrating the MTN MoMo API into your own applications, developers can offer these mobile money services to their users without the need for the users to leave the application or use a separate mobile money app.

The MTN MoMo API is available to developers across several markets and is designed to be easy to use, with clear documentation and resources available to get started. The API is accessible through a RESTful web service, and developers can make requests using HTTP methods such as GET, POST, PUT, or DELETE to interact with the API.

Common Error Codes

HTTP CodeError Response CodeDescriptionAction
409RESOURCE_ALREADY_EXISTDuplicated Reference ID. Every request must have a unique reference ID; using an ID of the previous request will result in this error response.Check X-Reference ID used is unique and is in UUID V4 format
401ACCESS DENIED DUE TO INVALID SUBSCRIPTION KEYAuthentication failed.Credentials invalid.Header Ocp-APIM-Subscription-Key value is incorrect.Check the User Profile Section to verify the related product subscription key is used. Collection, Disbursement and Remittance have different subscription keys. If the primary key doesn’t work, try the secondary key. Contact MTN support if both provided keys aren’t working. Sandbox subscription key are located in Production subscription key are located in
404RESOURCE NOT FOUNDReference ID not found. Requested resource does not exist. Predominantly occurs with Get Status API and implies that the requested reference ID does not exist. This results in the Request to Debit or Transfer transaction being unsuccessful.Check if the original request to pay or the transfer (disbursement) operation was successful with response code 202.
400REQUEST REJECTED/ BAD REQUESTBad request. Request does not follow the specification.This relates to any of the below scenarios:
– Incorrect/wrong values in the headers, and/or the X-ref ID does not meet UUID Version 4.
– Inputting a Body in an API that is not supported e.g. /Token API
– Having unsupported special characters in the Body request for example an apostrophe (‘).
– Invalid currency – needs to match the target environment currency.
– More than 160 characters in the note and message; explore utilizing the notification API for increased number of characters.
– The URL posted to needs to reviewed e.g. incorrect number of forward slashes (///).
403FORBIDDEN IPAuthorization failed. IP not authorized to utilize Disbursement API.Share your originating Public IP from which the APIs are called with your MTN Account Manager.
500NOT_ALLOWEDAuthorization failed. User does not have permission.The account authenticated with the Request via Token is restricted.Contact your MTN Account Manager.
500NOT_ALLOWED_TARGET_ENVIRONMENTValue passed in header X-Target-Environment is incorrectUse the correct X-targetenvironment corresponding to below country:
– MTN Uganda= mtnuganda
– MTN Ghana= mtnghana
– MTN Ivory Coast= mtnivorycoast
– MTN Zambia= mtnzambia
– MTN Cameroon= mtncameroon
– MTN Benin= mtnbenin
– MTN Congo= mtncongo
– MTN Swaziland= mtnswaziland
– MTN GuineaConakry= mtnguineaconakry
– MTN SouthAfrica= mtnsouthafrica
– MTN Liberia= mtnliberia
For Test Environment = sandbox
500INVALID_CALLBACK_URL_HOSTCallback URL with different host name to configured for API User.
Check the Host of the Call Back URL in the request header; this needs to match what was configured on the partner portal when creating the API user and Key.
Host needs to be configured using Hostname and not IP address.
500INVALID_CURRENCYCurrency not supported on the requested accountUse Currency Code specific to the Country.
503SERVICE_UNAVAILABLEService temporary unavailable, try again laterEnquire with MTN Support.

Error Responses

Common Error Responses with Action

INTERNAL_PROCESSING_ERRORDefault or Generic error code used when there is no specific error mapping. This predominantly occurs due to insufficient customer funds to complete the transaction.
Also related to service denied or Wallet Platform is not reachable.
Advice customer to ensure they have sufficient funds to complete the transaction. Also request the customer to retry the transaction. If the problem still occurs with sufficient customer funds, please contact your MTN Account Manager for further investigation.
PAYEE_NOT_FOUNDThe MSISDN being paid to is invalid.MSISDN format must include country code. MSISDN is not registered for Mobile Money Service.
PAYER_NOT_FOUNDMSISDN of the number from whom the money was requested in invalid.MSISDN format must include country code.MSISDN is not registered for Mobile Money Service.
COULD_NOT_PERFORM_TRANSACTIONThis can be attributed to transaction timeout. This predominantly occurs with a delay to approve a transaction within the given time frame (5 minutes).Advise customer to try again and approve transaction within 5 minutes.

Other Error Responses

NOT_ALLOWEDAuthorization failed. Insufficient permissions
NOT_ALLOWED_TARGET_ENVIRONMENTAccess to target environment is forbidden
INVALID_CALLBACK_URL_HOSTCallback URL does not match the configured value
INVALID_CURRENCYCurrency not supported
SERVICE_UNAVAILABLEService temporarily unavailable, try again later
NOT_ENOUGH_FUNDSThe payer does not have enough funds
PAYER_LIMIT_REACHEDThe payer’s limit has been breached
PAYEE_NOT_ALLOWED_TO_RECEIVEThe payee is unable to receive funds
PAYMENT_NOT_APPROVEDPayment was not approved
RESOURCE_NOT_FOUNDRequested resource was not found
APPROVAL_REJECTEDThe approval was rejected
EXPIREDThe requested resource has expired
TRANSACTION_CANCELEDThe transaction was canceled by the initiator
RESOURCE_ALREADY_EXISTDuplicated reference id. Creation of resource failed
TRANSACTION_NOT_COMPLETEDTransaction is pending and not completed
TRANSACTION_NOT_FOUNDThe transaction could not be found
INFORMATIONAL_SCOPE_INSTRUCTIONInformational scopes shall not have scope instructions
MISSING_SCOPE_INSTRUCTIONMissing scope instruction
MORE_THAN_ONE_FINANCIAL_SCOPE_NOT_SUPPORTEDMore than one financial scope is not supported
UNSUPPORTED_SCOPE_COMBINATIONThe combination of scope types are not supported
CONSENT_MISMATCHA value in request mismatch with a value in consent
UNSUPPORTED_SCOPEThe scope is not supported
NOT_FOUNDRequested resource was not found

MTN MoMo API supports several products, including:

  • Collections: Enables merchants to accept mobile money payments from their customers.
  • Disbursements: Enables companies to send payments to their employees or customers directly to their mobile money wallets.
  • Remittances: Enables individuals to send money directly to other individuals or companies across borders through mobile money.

To use the MTN MoMo API, developers need to obtain authentication details, consisting of an API key and API secret, which they will use to authorize requests to the API. Additionally, developers need to specify the product-specific variables and parameters that will enable them to interact with the API.

Overall, the MTN MoMo API provides developers with a convenient and secure way to integrate mobile money services from MTN into their own applications, helping to increase the reach and adoption of these services in their markets.

Integrating with MTN Momo API

MTN MoMo API Tutorial
More Information ℹ

Inspiring readers to expound the possibilities of the unfolding World