MTN MoMo · Error reference
MTN MoMo reports problems in two places: HTTP errors when your request is rejected outright, and a failure reason when a payment is accepted but doesn't complete.
Have a response you don't understand? Paste it into the Payment Error Code Lookup and it finds every known code inside.
Each code below is labelled by how well it is documented. Of the 29 codes on this page: 14 are in MTN MoMo's own documentation, 14 are confirmed by several independent sources, and 1 are reported by only one source. Treat codes marked "Reported by one source" as a strong hint, and log the full response so you can check.
The status values that tell you whether the customer paid.
PaidSeen in: Status / callbackRetry: not neededIn the provider's docs
The customer approved the payment and the money moved.
What to do
WaitingSeen in: Status / callbackRetry: Check the status before retryingIn the provider's docs
The prompt was sent and the customer hasn't approved or declined yet.
What to do
Why a payment did not go through.
Not paidSeen in: Status / callbackRetry: Yes, as a new requestIn the provider's docs
The payment failed. The "reason" field says why.
How to fix it
Not paidSeen in: Status / callbackRetry: Yes, as a new requestConfirmed by several sources
The customer declined the payment prompt on their phone.
How to fix it
What to tell the customer
You cancelled the payment on your phone. You can try again whenever you are ready.
Not paidSeen in: Status / callbackRetry: Yes, as a new requestConfirmed by several sources
The customer did not approve the prompt before it timed out (about 5 minutes).
How to fix it
What to tell the customer
The payment request timed out. Please try again and approve the prompt on your phone.
Not paidSeen in: Status / callbackRetry: Yes, as a new requestIn the provider's docs
The payer does not have enough money in their MoMo wallet, including fees.
How to fix it
What to tell the customer
Your MoMo balance is too low for this payment. Top up and try again.
One MTN page writes this as "NOT ENOUGH_FUNDS" with a space. Normalise spaces to underscores before comparing.
Sources: MTN MoMo Developer Community: failure reasons · MTN MoMo developer portal: error codes
Not paidSeen in: Status / callbackRetry: Yes, as a new requestIn the provider's docs
The payer's transaction limit has been reached. Limits vary by country and account level.
How to fix it
What to tell the customer
This payment is above your MoMo limit. Try a smaller amount or a different MoMo number.
Sources: MTN MoMo Developer Community: failure reasons · MTN MoMo developer portal: error codes
Not paidSeen in: Status / callbackRetry: Later, it is temporaryIn the provider's docs
The receiving account's limit has been reached. Limits vary by country.
How to fix it
What to tell the customer
This payment could not be completed right now. Please try a smaller amount or try later.
MTN's list writes this as "PAYEE LIMIT_REACHED" with a space. Normalise spaces to underscores before comparing.
Sources: MTN MoMo Developer Community: failure reasons · MTN MoMo developer portal: error codes
Not paidSeen in: Status / callbackRetry: Yes, as a new requestIn the provider's docs
The phone number is not a registered, active MoMo account.
How to fix it
What to tell the customer
We could not find a MoMo account for this number. Check the number and try again.
Sources: MTN MoMo Developer Community: failure reasons · MTN MoMo developer portal: error codes
Not paidSeen in: Status / callbackRetry: No, fix the cause firstIn the provider's docs
Your merchant (payee) account is not active — for debits this usually means the business account is blocked.
How to fix it
What to tell the customer
We cannot take MoMo payments right now. Please try another payment method.
Sources: MTN MoMo Developer Community: failure reasons · MTN MoMo developer portal: error codes
Not paidSeen in: Status / callbackRetry: No, fix the cause firstIn the provider's docs
The receiving wallet is not allowed to receive funds (for example, it is not active).
How to fix it
What to tell the customer
This payment could not be completed. Please try another payment method.
Sources: MTN MoMo Developer Community: failure reasons · MTN MoMo developer portal: error codes
Not paidSeen in: Status / callbackRetry: Yes, as a new requestIn the provider's docs
The transaction was not completed. Often the approval window passed or the network failed mid-way.
How to fix it
What to tell the customer
The payment did not go through. Please try again.
Sources: MTN MoMo Developer Community: failure reasons · MTN MoMo developer portal: error codes
Not paidSeen in: Status / callbackRetry: Yes, as a new requestConfirmed by several sources
The transaction was cancelled before completion.
How to fix it
What to tell the customer
The payment was cancelled. You can try again.
Not paidSeen in: Status / callbackRetry: Yes, as a new requestConfirmed by several sources
The payment was not approved by the payer.
How to fix it
What to tell the customer
The payment was not approved. You can try again.
Not paidSeen in: Status / callbackRetry: Later, it is temporaryConfirmed by several sources
A generic error inside MTN's system.
How to fix it
What to tell the customer
MoMo had a temporary problem. Please try again in a few minutes.
Not paidSeen in: Status / callbackRetry: No, fix the cause firstConfirmed by several sources
Your API user is not authorised for this operation.
How to fix it
What to tell the customer
This payment could not be completed. Please try another payment method.
Not paidSeen in: Status / callbackRetry: No, fix the cause firstConfirmed by several sources
Your credentials are not valid for the X-Target-Environment you sent (e.g. sandbox keys with mtnuganda).
How to fix it
What to tell the customer
This payment could not be completed. Please try again later.
Not paidSeen in: Status / callbackRetry: No, fix the cause firstConfirmed by several sources
The X-Callback-Url host does not match the providerCallbackHost registered for your API user.
How to fix it
What to tell the customer
This payment could not be completed. Please try again later.
Not paidSeen in: Status / callbackRetry: No, fix the cause firstConfirmed by several sources
The currency is not supported for this target environment (the sandbox only accepts EUR).
How to fix it
What to tell the customer
This payment could not be completed. Please try again later.
Not paidSeen in: Status / callbackRetry: Yes, as a new requestIn the provider's docs
The X-Reference-Id was already used. Every request needs a new UUID v4.
How to fix it
What to tell the customer
This payment could not be completed. Please try again.
Sources: MTN MoMo Developer Community: failure reasons · MTN MoMo developer portal: error codes
Not paidSeen in: Status / callbackRetry: Yes, as a new requestConfirmed by several sources
MTN could not find the resource you referred to.
How to fix it
What to tell the customer
This payment could not be completed. Please try again.
Not paidSeen in: Status / callbackRetry: Yes, as a new requestIn the provider's docs
The transaction could not be found.
How to fix it
What to tell the customer
We could not find this payment. Please try again.
Sources: MTN MoMo Developer Community: failure reasons · MTN MoMo developer portal: error codes
Not paidSeen in: Status / callbackRetry: No, fix the cause firstIn the provider's docs
The request failed validation: wrong data types, unsupported decimals, empty fields, or notes over 128 characters.
How to fix it
What to tell the customer
This payment could not be completed. Please try again later.
Sources: MTN MoMo Developer Community: failure reasons · MTN MoMo developer portal: error codes
Returned straight away when the API rejects your request.
Request errorSeen in: API responseRetry: No, fix the cause firstConfirmed by several sources
MTN rejected the request because a header or the body is malformed.
How to fix it
Request errorSeen in: API responseRetry: Yes, as a new requestConfirmed by several sources
The access token is missing, expired, or doesn't match the subscription key or product.
How to fix it
Request errorSeen in: API responseRetry: Yes, as a new requestIn the provider's docs
You reused an X-Reference-Id. Every API user and every transaction needs its own UUID.
How to fix it
Request errorSeen in: API responseRetry: Yes, as a new requestReported by one source
An empty POST (create API key, get token) was sent without a Content-Length header.
How to fix it
Request errorSeen in: API responseRetry: Check the status before retryingConfirmed by several sources
Something failed on MTN's side, or your target environment doesn't match your credentials (the body then often names NOT_ALLOWED_TARGET_ENVIRONMENT).
How to fix it
Sources: MTN MoMo Developer Community: sandbox 400 errors · MTN MoMo developer portal: sandbox use cases
Map each outcome code to one of four actions. Unknown codes fall back to "check the status", so a new or misspelled code never fulfils or cancels an order by accident.
// What to do with each MTN MoMo outcome code.
// Unknown codes fall back to "check_status": never fulfil or fail an order on a code you don't recognise.
const ACTIONS = {
"SUCCESSFUL": "fulfil", // Payment completed
"PENDING": "wait", // Waiting for the customer
"FAILED": "mark_failed", // Payment did not complete
"APPROVAL_REJECTED": "mark_failed", // Approval rejected
"EXPIRED": "mark_failed", // Expired
"NOT_ENOUGH_FUNDS": "mark_failed", // Not enough funds
"PAYER_LIMIT_REACHED": "mark_failed", // Payer limit reached
"PAYEE_LIMIT_REACHED": "mark_failed", // Payee limit reached
"PAYER_NOT_FOUND": "mark_failed", // Payer not found
"PAYEE_NOT_FOUND": "mark_failed", // Payee not found
"PAYEE_NOT_ALLOWED_TO_RECEIVE": "mark_failed", // Payee not allowed to receive
"COULD_NOT_PERFORM_TRANSACTION": "mark_failed", // Could not perform transaction
"TRANSACTION_CANCELED": "mark_failed", // Transaction canceled
"PAYMENT_NOT_APPROVED": "mark_failed", // Payment not approved
"INTERNAL_PROCESSING_ERROR": "mark_failed", // Internal processing error
"SERVICE_UNAVAILABLE": "mark_failed", // Service unavailable
"NOT_ALLOWED": "mark_failed", // Not allowed
"NOT_ALLOWED_TARGET_ENVIRONMENT": "mark_failed", // Not allowed target environment
"INVALID_CALLBACK_URL_HOST": "mark_failed", // Invalid callback url host
"INVALID_CURRENCY": "mark_failed", // Invalid currency
"RESOURCE_ALREADY_EXIST": "mark_failed", // Resource already exist
"RESOURCE_NOT_FOUND": "mark_failed", // Resource not found
"TRANSACTION_NOT_FOUND": "mark_failed", // Transaction not found
"VALIDATION_ERROR": "mark_failed", // Validation error
};
export function momoNextStep(code) {
const key = String(code ?? "").trim().toUpperCase().replace(/[\s-]+/g, "_");
return ACTIONS[key] ?? "check_status";
}
// Example:
// switch (momoNextStep(payment.reason?.code ?? payment.reason ?? payment.status)) {
// case "fulfil": // verify amount, then mark the order paid (idempotently)
// case "mark_failed": // mark unpaid, show a retry button
// case "wait": // do nothing yet; a callback or your poller will follow
// case "check_status": // ask the status endpoint before deciding
// }
PAYER_NOT_FOUND (Payer not found): The phone number is not a registered, active MoMo account. Check the number format (country code, no leading 0). Use "Validate account holder status" before charging.
NOT_ENOUGH_FUNDS (Not enough funds): The payer does not have enough money in their MoMo wallet, including fees. Show the total amount including any fees before you send the request, so customers can top up first.
APPROVAL_REJECTED (Approval rejected): The customer declined the payment prompt on their phone. Mark the order unpaid. Offer a "Try again" button; send a new Request to Pay with a new X-Reference-Id.
HTTP 401 (Unauthorized): The access token is missing, expired, or doesn't match the subscription key or product. Fetch a new token. Tokens expire, so cache them and refresh before expires_in runs out.
HTTP 400 (Bad Request): MTN rejected the request because a header or the body is malformed. X-Reference-Id must be a fresh UUID v4.
Full MTN MoMo integrations that handle these codes: Node.js, Laravel, Django, Disbursements (payouts) in Node.js.
Checked October 2026. Error codes change. If you see one that's missing or wrong, please let me know.
I integrate MTN MoMo, M-Pesa and Airtel Money into Laravel / PHP, Python / Django, Node.js / Next.js apps: payments, callbacks, payouts and go-live, with tests.