Banking Tech

MTN MoMo API Integration: A Developer's Complete Guide

MTN Mobile Money (MoMo) is the dominant digital financial services platform in Uganda, driving billions of Ugandan Shillings in daily commerce across retail checkout, utility payments, micro-loan disbursements, and peer-to-peer money transfers. For software developers, fintech innovators, and enterprise backend engineers, building seamless MTN MoMo API integrations into mobile and web applications is critical for capturing consumer demand and offering frictionless digital experiences. This complete developer guide provides an end-to-end technical breakdown of the MTN MoMo Open API ecosystem in Uganda—covering sandbox provisioning, OAuth authentication, collection payments, disbursement workflows, asynchronous webhook handling, security standards, and production onboarding requirements.

Understanding the MTN MoMo API Product Architecture

The MTN MoMo API suite is organized into distinct functional products optimized for specific financial workflows:

• Collections API (Request to Pay): Allows businesses to initiate customer payment prompts directly on a user's mobile device. The customer receives an instant USSD popup on their phone prompting them to authorize payment with their MoMo PIN (C2B transaction).
• Disbursements API: Enables businesses to send funds programmatically from a corporate escrow wallet directly to individual mobile wallets. This is ideal for paying contractor salaries, processing loan disbursements, and distributing insurance claims (B2C transaction).
• Remittances API: Designed for international money transfer operators (MTOs) to deposit cross-border funds directly into local MTN MoMo subscriber accounts in Uganda.

Step 1: Sandbox Environment Provisioning and API Keys

Before launching live transactions on MTN Uganda's production network, developers must construct and validate their application within the official MTN MoMo Developer Sandbox environment:

1. Developer Account and API Product Subscription

Create an account on the MTN MoMo Developer Portal and subscribe to your target API product (e.g., Collections). Upon subscription approval, the portal issues a primary and secondary Ocp-Apim-Subscription-Key header key.

2. Programmatic API User and API Key Generation

Unlike standard OAuth flows that use static client secrets, MTN MoMo requires developers to generate a unique API User (a UUID v4 formatted string) and API Key programmatically:

• Generate a valid UUID v4 string (for example, f3b2a890-4c12-11ee-be56-0242ac120002) to serve as your X-Reference-Id.
• Send a POST request to /v1_0/apiuser specifying your callback host domain and subscription key in the headers.
• Send a POST request to /v1_0/apiuser/{X-Reference-Id}/apikey to retrieve your secret apiKey string.

Step 2: Authentication and OAuth Bearer Token Request

With your API User UUID and generated apiKey, you can request an OAuth 2.0 Bearer Access Token. Combine the credentials into a colon-separated string (API_USER:API_KEY), encode it in Base64 format, and post it to the token endpoint:

Endpoint: POST https://sandbox.momodeveloper.mtn.com/collection/token/
Headers:
Authorization: Basic {Base64_Encoded_Credentials}
Ocp-Apim-Subscription-Key: {Subscription_Key}

The API responds with an access_token string valid for 3600 seconds (1 hour) alongside token type Bearer, which must be attached to the Authorization header of all subsequent API interactions.

Step 3: Executing a Collection Payment Request (Request to Pay)

To initiate a collection payment request from an MTN MoMo customer in Uganda, invoke the /requesttopay endpoint with the user's phone number formatted in international standard (e.g., 256770000000):

Endpoint: POST /collection/v1_0/requesttopay
Headers:
Authorization: Bearer {Access_Token}
X-Reference-Id: {Unique_UUID_v4_Per_Transaction}
X-Target-Environment: sandbox (use mtnuganda in production)
Ocp-Apim-Subscription-Key: {Subscription_Key}
Content-Type: application/json

Request JSON Payload Example

{
  "amount": "50000",
  "currency": "UGX",
  "externalId": "INV-2026-9912",
  "payer": {
    "partyIdType": "MSISDN",
    "partyId": "256771234567"
  },
  "payerMessage": "Payment for Course Fee",
  "payeeNote": "DeryCode Web Store"
}

Upon receipt, the gateway responds immediately with HTTP status 202 Accepted, and pushes a USSD PIN prompt directly to the customer's phone screen to authorize transaction settlement.

Step 4: Managing Asynchronous Callbacks and Status Verification

Because mobile money user interactions are inherently asynchronous and dependent on mobile network availability, system architectures must handle transaction status updates reliably:

• Webhook Callbacks: Configure a secure HTTP POST callback endpoint on your web server. When the user enters their PIN or cancels the prompt, MTN posts a status payload (SUCCESSFUL, FAILED, or REJECTED) to your server.
• Transaction Status Polling: As a fail-safe, query GET /collection/v1_0/requesttopay/{X-Reference-Id} using the transaction's unique UUID to confirm payment status before fulfilling orders.

Security Standards and Production Readiness in Uganda

Transitioning from the sandbox to live production with MTN Uganda requires strict compliance with cybersecurity and financial operational standards:

1. TLS Encryption and IP Whitelisting: All production webhooks must operate over TLS 1.3 HTTPS connections, with server firewalls restricting incoming callback traffic strictly to official MTN gateway IP addresses.
2. Strict Transaction Idempotency: Store every transaction X-Reference-Id in a persistent database table to prevent duplicate charges or double order fulfillment during temporary network retries.
3. Secure Key and Secret Management: Never hardcode API keys or subscription tokens inside front-end applications or public git repositories. Use secure environment variables or vault hardware security modules.
4. Automated Ledger Reconciliation: Implement nightly automated reconciliation scripts that compare internal database transaction logs against official MTN merchant balance reports to identify discrepancies.

Build Enterprise Payment Infrastructure with DeryCode Tech

Engineering resilient, high-volume payment processing backends requires expertise in distributed system architecture, financial cryptography, and failover network mechanics. DeryCode Tech, based in Kampala, Uganda and founded by senior software architect Asiimwe Derick, specializes in enterprise mobile money API integrations, custom payment gateways, and scalable fintech software across East Africa.

Do you need expert engineers to build or optimize your mobile money payment backend? Contact the engineering team at DeryCode Tech today to discuss your project requirements.