Understanding MoMo Open API Keys Sandbox and Production

Understanding MoMo Open API Keys

1. What are the MoMo Open API Keys?

In the MoMo ecosystem, authentication isn't just a single password. It is a trio of credentials that work together to secure your transactions. You will need all three to generate an Access Token , which is then used to authorize your actual payment requests.

• 🔑 Subscription Key:

  • What it is: A long string (e.g., f1db798c...) that identifies which product you are using (e.g., Collections, Disbursements).

  • Where it lives: You get this from your profile on the MoMo Developer Portal immediately after you subscribe to a product.

  • Function: It allows your request to pass through the API Gateway. Without it, you get a 401 Access Denied.

• 👤 API User (X-Reference-Id):

  • What it is: A UUID (Universally Unique Identifier) that identifies you or your system.

  • Function: This acts as your "Username" for generating a token.

• 🗝️ API Key:

  • What it is: A secret string generated specifically for your API User.

  • Function: This acts as your "Password".

2. How to Generate Keys (Sandbox vs. Production)

The process differs significantly between the testing environment (Sandbox) and the live environment (Production).

🏖️ In the Sandbox (Test Environment)

In the sandbox, you are in control. You "provision" your own user and key via API calls. You do not need approval from MTN to do this.

Step 1: Create your API User (UUID) You need to generate a UUID (Version 4) yourself (you can use a tool like uuidgenerator.net or code). Let's say your UUID is c72025f5-5cd1-4630-99e4-8ba4722fad56.

Submit a POST request to create this user:

HTTP

POST /v1_0/apiuser HTTP/1.1
Host: sandbox.momodeveloper.mtn.com
X-Reference-Id: c72025f5-5cd1-4630-99e4-8ba4722fad56
Ocp-Apim-Subscription-Key: <Your_Subscription_Key>
Content-Type: application/json

{
  "providerCallbackHost": "webhook.site" 
}

• Success: You will receive a 201 Created status.

Step 2: Generate the API Key Now that the user exists, ask the system to create a password (API Key) for it.

HTTP

POST /v1_0/apiuser/c72025f5-5cd1-4630-99e4-8ba4722fad56/apikey HTTP/1.1
Host: sandbox.momodeveloper.mtn.com
Ocp-Apim-Subscription-Key: <Your_Subscription_Key>

• Response: The body will contain your actual API Key: {"apiKey": "b09f..."}. Copy this immediately, as you cannot retrieve it later.

🚀 In Production (Live Environment)

You cannot auto-generate users in Production via the API. This ensures security and KYC (Know Your Customer) compliance.

1. Go Live Process: Submit your details on the Developer Portal. MTN will vet your business.

2. Partner Portal: Once approved, you will be given access to the MoMo Partner Portal (a different site from the Developer Portal).

3. Generate Credentials:

   • Log in to the Partner Portal.

   • Navigate to API Access or User Management.

   • Click Create API User.

   • The system will display your API User ID and show a popup with your API Key.

   • Note: This popup appears only once. If you lose this key, you must revoke the user and create a new one.

3. Security Best Practices 🛡️

I cannot stress this enough: Your API Key is as sensitive as your bank PIN.

• Never Hardcode: Do not paste your API Key or Subscription Key directly into your source code (e.g., const apiKey = "..."). If you push this to GitHub, bots will find it.

• Use Environment Variables: Store these values in a .env file on your server (e.g., MOMO_API_KEY=...) and read them into your application at runtime.

• Regenerate if Compromised: If you suspect your Sandbox or Production key has been exposed, generate a new one immediately. In Sandbox, just create a new UUID. In Production, log in to the portal and revoke the old user.

• Validate Callbacks: When MoMo sends a notification to your providerCallbackHost (e.g., telling you a payment succeeded), verify the source. Don't just trust any request hitting your endpoint.