MTN MoMo API Tutorial for Beginners in Uganda (Step-by-Step)

This tutorial assumes you can write basic JavaScript or Python. You do not need to know anything about payment APIs or mobile money. If you have ever made an HTTP request using fetch, axios, or the requests library in Python, you have enough background.

You will need:

• A computer with Node.js (v18+) or Python (3.8+) installed
• A code editor (VS Code is the most common choice)
• An internet connection (for API calls to the MoMo sandbox)
• ngrok or a similar tunneling tool (free tier is fine) to expose your local server for callbacks

You do not need an MTN MoMo account with money in it. You do not need a Ugandan phone number. You do not need a registered business. The sandbox is completely free and works from anywhere.

Go to the MTN MoMo Developer Portal.

1. Create an account. Use your email and set a password. You will receive a verification email.
2. Subscribe to the Collections API product. On the portal dashboard, find the API products section and subscribe to "Collections." This is the API that lets you receive payments from customers.
3. Note your subscription key. After subscribing, the portal provides a primary key and secondary key. You will use the primary key in your API calls. Keep both keys safe.

Next, you need to create a sandbox API user. The MoMo sandbox has a provisioning endpoint for this:

1. Generate a UUID v4. This will be your API User reference ID. You can generate one at any UUID generator site or in code.
2. POST to the sandbox provisioning endpoint with your UUID as the X-Reference-Id header and your subscription key as the Ocp-Apim-Subscription-Key header. The body should contain a providerCallbackHost (your callback domain).
3. Create an API key by POSTing to the API key creation endpoint with your UUID. The response contains your apiKey.
4. You now have three credentials: your subscription key, your API User ID (the UUID), and your API key. These are your sandbox credentials.

This provisioning step trips up many beginners because it is a multi-step process just to get credentials. Do not skip any step. If you get a 401 or 404 error, double-check that you are using the sandbox URL, not the production URL.

With your sandbox credentials ready, here is the flow to collect a payment:

1. Get an access token. POST to the token endpoint with your API User ID and API Key as Basic Auth credentials (Base64-encoded). Include your subscription key in the Ocp-Apim-Subscription-Key header. The response gives you an access_token valid for a limited time (usually 3600 seconds).
2. Send a Request to Pay. POST to the /collection/v1_0/requesttopay endpoint with:
   • Authorization: Bearer {access_token}
   • X-Reference-Id: a new UUID v4 (unique for each transaction)
   • X-Target-Environment: sandbox
   • Ocp-Apim-Subscription-Key: your subscription key
   • Body: amount (e.g., "5000"), currency ("UGX"), externalId, payer.partyIdType ("MSISDN"), payer.partyId ("256771234567"), payerMessage, payeeNote
3. Check the response. A 202 Accepted means MoMo received your request. It does not mean the payment succeeded. The actual result comes via callback or status polling.

In the sandbox, the payment is automatically approved. In production, the customer would see a USSD prompt on their phone and enter their PIN to confirm. The sandbox skips this step and simulates a successful payment.

The most common beginner mistakes here: using the wrong Content-Type (must be application/json), forgetting the X-Reference-Id header, or sending the phone number without the country code (256).

After the customer confirms (or the sandbox auto-approves), MoMo sends a POST request to your callback URL with the transaction result. Your server needs to be ready for this.

Set up a simple Express server (Node.js) or Flask server (Python) with a POST endpoint at your callback path. The callback body contains:

• The transaction reference ID
• The status (SUCCESSFUL, FAILED, PENDING, etc.)
• The amount and currency
• Error information if the payment failed

For local development, your server runs on localhost, which MoMo cannot reach. Use ngrok to create a public URL that tunnels to your local server:

1. Start your server (e.g., on port 3000)
2. Run ngrok: ngrok http 3000
3. Use the ngrok HTTPS URL as your callback URL in the Request to Pay

As a fallback (and a good practice), always implement status polling. After sending a Request to Pay, you can GET the transaction status using the reference ID. This protects you against missed callbacks due to network issues, server downtime, or timeout problems.

Log every callback you receive. In the early days of your integration, these logs will be your primary debugging tool. See our common MoMo and Airtel Money API errors guide for the error codes you will encounter.

Your sandbox code is 90% of your production code. The things that change:

• Environment: X-Target-Environment changes from "sandbox" to "production" (or the specific MTN market identifier for Uganda).
• Credentials: You get new production credentials through the approval process with MTN Uganda. These are different from your sandbox keys.
• Base URL: The API base URL changes from the sandbox URL to the production URL.
• Real customer interaction: Payments are no longer auto-approved. Real customers see a real USSD prompt and must enter their real PIN.
• Real money: Successful transactions move actual UGX between accounts.

Structure your code so that the base URL, credentials, and target environment are loaded from environment variables. This way, switching between sandbox and production is a configuration change, not a code change.

For a deeper guide on sandbox testing strategies, read our testing mobile money in sandbox guide. For the production deployment process, our Deployment and Going Live course (KES 4,999, approximately UGX 140,000) walks through the full flow from working code to live product.

You have the basics of MoMo API integration. Here is what to learn next, in order of practical value:

1. Add Airtel Money. Many Ugandan users are on Airtel, not MTN. Supporting both providers covers the vast majority of your addressable market. Our Airtel Money API integration guide covers the specifics.
2. Build a real checkout flow. Connecting the API to a frontend with a proper UX (loading states, error messages, confirmation screens). Our e-commerce checkout guide walks through this.
3. Handle edge cases. Timeouts, duplicate transactions, partial failures, refunds. The common errors guide covers what goes wrong and how to handle it.
4. Consider an aggregator. If managing two separate API integrations feels heavy, aggregators like Flutterwave, EasyPay, or Beyonic handle both MoMo and Airtel Money through one API. Our comparison article breaks down the trade-offs.

If you want structured instruction on mobile money integration with mentorship and feedback, McTaba's M-Pesa Integration course (KES 9,999, approximately UGX 280,000) teaches the request-callback architecture, sandbox-to-production workflow, and error handling patterns. The course uses M-Pesa and Airtel Money as the teaching vehicle, but the architecture you learn applies directly to MoMo.