MoMo API Developer Playbook

• 1. Playbook Overview
• Core Principles
• 2. API Capability Map
• 3. Quick Start: First Working Call
• 4. Sandbox Credentials and Authentication
• 5. Environment and Header Standard
• 6. Sandbox Testing Strategy
• Minimum test evidence
• 7. Collections: Request to Pay
• Request to Pay Status
• 8. Callback and Status-Recovery Pattern
• 9. Refunds and Delivery Notifications
• 10. Transfers: Disbursements
• Transfer Status
• 11. Account Validation and Customer Confirmation
• 12. Invoicing
• Invoice Status and Management
• 13. Error Handling and Recovery
• 14. Security, Privacy, and Operational Controls
• 15. Recommended End-to-End Architecture
• 16. Illustrative Journey: Utility Payment
• 17. Reviewer Success Criteria
• 18. Prototype Acceptance Checklist
• 19. Final Playbook Note

1. Playbook Overview

This playbook connects executive intent with developer execution. It explains why the MoMo APIs matter, how teams should build credible prototypes, and what reviewers should look for when assessing business value, technical correctness, journey completeness, and readiness for scale.

Executive lens	Developer lens
Solve a practical customer, merchant, or ecosystem problem.	Use the correct product credentials, headers, endpoints, and environment settings.
Demonstrate adoption potential and clear customer utility.	Implement validation, initiation, asynchronous status handling, recovery, and notifications.
Show a commercially meaningful path beyond the prototype.	Protect secrets and transaction data, and preserve traceability across every request.

Core Principles

• Prototype around a visible customer or merchant outcome.
• Validate the wallet and confirm the intended party before sending a financial instruction.
• Treat transaction initiation and transaction completion as separate events.
• Design explicitly for PENDING, SUCCESSFUL, FAILED, REJECTED, and timeout outcomes.
• Use callbacks where available, but retain GET status as the recovery path.
• Do not expose credentials, access tokens, subscription keys, or customer data in screens, logs, or source repositories.

2. API Capability Map

Business need	Primary capability	Expected outcome
Get paid	Request to Pay	Collect a customer-authorized wallet payment.
Pay out	Transfer / Disbursement	Send rewards, cashback, settlements, or supplier payments.
Verify party	Wallet Validation + Basic User Information	Confirm wallet status and customer details before transacting.
Request later payment	Create Invoice	Create a formal, trackable payment request.
Track progress	Transaction / Invoice Status	Display the true processing state and final outcome.
Communicate completion	Delivery Notification	Inform a customer after the underlying service action completes.
Return funds	Refund + Refund Status	Return funds and verify the refund outcome.

3. Quick Start: First Working Call

Step	Action	Evidence
1	Register on the MoMo Developer Portal.	Active developer account.
2	Subscribe to the required product: Collections and/or	Disbursements. Correct product subscription key.
3	Create an API User and API Key in Sandbox.	Securely stored credentials.
4	Generate an access token.	HTTP 200 and token response.
5	Run account validation for the test MSISDN.	Boolean wallet status.
6	Submit Request to Pay or Transfer with a unique UUID v4	reference. HTTP 202 Accepted.
7	Check callback and/or call the matching GET status endpoint.	HTTP 200 and final business status.
8	Update the customer journey only after the final state is	known. Success, recovery, or clear failure screen.

4. Sandbox Credentials and Authentication

4.1 Create an API User

POST /v1_0/apiuser

Required header	Value
X-Reference-Id	{unique UUID v4}
Ocp-Apim-Subscription-Key	{Collection subscription key}
Content-Type	application/json

{ “providerCallbackHost”: “your-callback-host.example” } Expected response: 201 Created.

4.2 Create an API Key

POST /v1_0/apiuser/{apiUser}/apikey { “apiKey”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” }

4.3 Generate an Access Token

POST /collection/token/ Use HTTP Basic authentication with the API User as the username and API Key as the password. Include the matching product subscription key. { “access_token”: “eyJhbGc…”, “token_type”: “access_token”, “expires_in”: 3600 }

5. Environment and Header Standard

Base URL: https://sandbox.momodeveloper.mtn.com/

Header	When used	Purpose
Authorization: Bearer {access_token}	Protected API calls	Authenticates the API caller.
Ocp-Apim-Subscription-Key	All product APIs	Selects and authorizes the subscribed API product.
X-Target-Environment: sandbox	Sandbox product APIs	Routes the request to the test environment.
Content-Type: application/json	Requests with JSON body	Declares the body format.
X-Reference-Id: {UUID v4}	Create/initiate operations	Provides the unique transaction request identifier.
X-Callback-Url: https://…	Where supported/configured	Receives the asynchronous final transaction result.

6. Sandbox Testing Strategy

Test MSISDN	Expected Sandbox outcome	What to demonstrate
56733123453	Success	Final success screen, fulfilment, and notification.
46733123450	Failed	Failure messaging and safe retry/recovery.
46733123451	Rejected	Customer-declined path without fulfilment.
46733123452	Timeout	Timeout handling and status reconciliation.
46733123454	Pending	Processing state without premature success.

Minimum test evidence

• Request method, endpoint, headers, and sanitized payload.
• Initial HTTP response code.
• The X-Reference-Id used to retrieve status.
• Callback payload or GET status response.
• Customer-facing result for success and each negative scenario.
• Evidence that service fulfilment occurs only after final success.

7. Collections: Request to Pay

Use Request to Pay when a customer authorizes a wallet debit for a service such as utilities, event tickets, school fees, transport, or digital services. POST /collection/v1_0/requesttopay { “amount”: “5000”, “currency”: “EUR”, “externalId”: “INV-1001”, “payer”: {“partyIdType”: “MSISDN”, “partyId”: “56733123453”}, “payerMessage”: “Utility Payment”, “payeeNote”: “Service Purchase” }

Request to Pay Status

GET /collection/v1_0/requesttopay/ {requestId} Use the same request ID that was supplied in X-Reference-Id when the debit was initiated. A successful status query returns HTTP 200 with the current transaction details and status.

State	Platform behaviour	Customer message
PENDING	Do not fulfil. Keep checking through callback or controlled	polling. Payment is being processed. Approve it on your MoMo channel.
SUCCESSFUL	Fulfil once, record result, and notify.	Payment confirmed. Your service is ready.
FAILED	Do not fulfil. Show the reason where safe and provide recovery.	Payment was not completed. Please try again or use another option.
REJECTED	Do not fulfil. Return the customer to payment selection.	Payment was declined.
TIMEOUT	Reconcile status before offering a new attempt.	The request timed out. We are confirming the final result.

8. Callback and Status-Recovery Pattern

Sequence	Platform action
1. Initiate	Generate a unique UUID v4 and persist it before sending the request.
2. Accept	On HTTP 202, mark the transaction as submitted or pending, not successful.
3. Callback	Validate and record the callback when it arrives.
4. Fallback	If the callback is not received, call the matching GET status endpoint.
5. Finalize	Apply fulfilment exactly once after the final successful state.
6. Reconcile	Retain request ID, external ID, financial transaction ID, and final status for support and reconciliation.

9. Refunds and Delivery Notifications

9.1 Refund

POST /disbursement/v1_0/refund { “amount”: “5000”, “currency”: “EUR”, “externalId”: “REF-001”, “payerMessage”: “Refund”, “payeeNote”: “Service Cancellation”, “referenceIdToRefund”: “{request-to-pay-reference}” }

9.2 Refund Status

GET /disbursement/v1_0/refund/{refundRequestId} Do not tell the customer that funds were returned until the refund status confirms the final successful outcome.

9.3 Delivery Notification

POST /collection/v1_0/requesttopay/{requestId}/deliverynotification { “notificationMessage”: “Your service has been completed. Thank you.” }

10. Transfers: Disbursements

Use the Transfer API for customer rewards, cashback, prize payouts, gig-worker payments, merchant settlement, supplier payments, and revenue sharing. POST /disbursement/v1_0/transfer { “amount”: “10000”, “currency”: “EUR”, “externalId”: “PAY-001”, “payee”: {“partyIdType”: “MSISDN”, “partyId”: “56733123453”}, “payerMessage”: “Reward”, “payeeNote”: “Business Activity Prize” }

Transfer Status

GET /disbursement/v1_0/transfer/{requestId} For business-to-business settlement, an approved merchant alias may be used where supported. For customer payouts, use the MSISDN format required by the target environment.

11. Account Validation and Customer Confirmation

11.1 Wallet Validation

GET /disbursement/v1_0/accountholder/msisdn/{MSISDN}/active { “result”: true }

11.2 Basic User Information

GET /disbursement/v1_0/accountholder/msisdn/{MSISDN}/basicuserinfo { “sub”: “0”, “given_name”: “Sand”, “family_name”: “Box” }

Validation result	Next action
Wallet inactive or not found	Stop the journey and request a valid alternative wallet.
Wallet active but name mismatched	Ask the user to review the number. Do not proceed automatically.
Wallet active and name confirmed	Proceed to Request to Pay or Transfer.

12. Invoicing

Use invoicing when the payer can complete payment later through supported MoMo channels or when the business needs a formal, trackable payment request. POST /collection/v2_0/invoice { “externalId”: “INV001”, “amount”: “50000”, “currency”: “EUR”, “validityDuration”: “360”, “intendedPayer”: {“partyIdType”: “MSISDN”, “partyId”: “56733123453”}, “payee”: {“partyIdType”: “MSISDN”, “partyId”: “56733123450”}, “description”: “School Fees” }

Invoice Status and Management

GET /collection/ v2_0/invoice/{invoiceRequestId} DELETE /collection/v2_0/invoice/{invoiceRequestId}

Status question	Platform response
Paid?	Confirm payment reference and enable the promised service.
Pending?	Keep the invoice visible with a pay-now option and expiry information.
Expired?	Disable payment against the old invoice and offer a new invoice if appropriate.
Cancelled/deleted?	Remove it from active payment actions and retain an audit record.

13. Error Handling and Recovery

HTTP code / error	Likely meaning	Developer action
400 Bad Request	Payload or request structure does not match the specification.	Validate required fields, formats, values, and headers before retrying.
401 Invalid subscription key	Wrong, inactive, or mismatched product subscription key.	Use the key for the correct product and environment.
404 Resource not found	The status reference does not exist or the initial request was not	accepted. Confirm the original HTTP 202 and the exact X-Reference-Id.
409 RESOURCE_ALREADY_EXIST	The X-Reference-Id was already used.	Generate a new UUID v4 for a genuinely new request.
NOT_ENOUGH_FUNDS	Payer balance is insufficient.	Inform the payer and allow a different wallet or later retry.
PAYER_NOT_FOUND	The payer wallet does not exist.	Run account-holder validation before initiating debit.
PAYEE_NOT_ALLOWED_TO_RECEIVE	Destination wallet cannot receive funds.	Request another valid recipient wallet.
PAYER_LIMIT_REACHED / PAYEE_LIMIT_REACHED	Wallet transaction limits were reached.	Reduce the amount where appropriate or use another eligible wallet.
COULD_NOT_PERFORM_TRANSACTION	The transaction did not complete.	Retrieve final status and present a controlled retry only after reconciliation.

14. Security, Privacy, and Operational Controls

Control	Minimum implementation
Secrets	Keep subscription keys, API keys, and tokens in secure environment variables or a secret manager.
Transport	Use HTTPS endpoints and secure callback URLs.
Logging	Mask tokens, subscription keys, API keys, and personal data. Log reference IDs and technical status safely.
Authorization	Request only the product access required by the use case.
Reference integrity	Create a unique UUID v4 per initiation and persist it before the outbound request.
Idempotency	Apply fulfilment, rewards, and settlement once for each final successful reference.
Privacy	Show and retain only the data required for identity confirmation, support, and reconciliation.
Environment separation	Use different credentials and configuration for Sandbox and production.
Monitoring	Track acceptance, pending age, final success/failure, callback receipt, and reconciliation exceptions.

15. Recommended End-to-End Architecture

Layer	Responsibility	Key evidence
Business Platform UI	Capture service, amount, and party details; show processing and	final states. Complete screens for success, pending, timeout, rejection, and failure.
Orchestration service	Validate, generate references, call APIs, persist state, and enforce	idempotency. Traceable transaction record.
MoMo API integration	Authenticate and call validation, collections, disbursement,	invoice, and status endpoints. Correct headers, payloads, and response handling.
Callback receiver	Receive and record asynchronous final results.	Secure endpoint and mapped reference.
Fulfilment service	Issue token, ticket, order, reward, or settlement after final	success. Exactly-once fulfilment.
Monitoring and support	Reconcile statuses and surface exceptions.	Operational dashboard or support view.

16. Illustrative Journey: Utility Payment

Step	Customer experience	API / platform action
1	Select utility and enter account details.	Validate the service input.
2	Enter paying MSISDN.	Call wallet validation and basic user information.
3	Confirm customer name and amount.	Generate external ID and UUID v4.
4	Approve payment.	POST Request to Pay; expect HTTP 202.
5	See a processing state.	Wait for callback or GET Request to Pay status.
6	Receive the token or service confirmation.	Only after SUCCESSFUL, fulfil exactly once.
7	Receive a completion message.	Send delivery notification after fulfilment.
8	If unsuccessful, receive a clear recovery option.	Map the final state to a safe retry, alternative wallet, or support path.

17. Reviewer Success Criteria

Category	Weight	Observable evidence
Business value	25%	Clear problem, target user, value proposition, practical utility, and adoption path.
API implementation	25%	Correct products, endpoints, credentials, headers, environment, request IDs, and status APIs.
Journey completeness	25%	Validation, initiation, pending state, final status, failure recovery, fulfilment, and notification.
Scalability and readiness	25%	Security, idempotency, observability, reconciliation, partner integration, and measurable adoption signals.

18. Prototype Acceptance Checklist

Area	Acceptance statement	Result
Business	Problem, target customer, and value proposition are clear.	[ ] Pass [ ] Gap
Business	The platform demonstrates a complete service outcome, not only an	API response. [ ] Pass [ ] Gap
Technical	Correct Collections or Disbursement subscription key is used.	[ ] Pass [ ] Gap
Technical	A unique UUID v4 is generated for each new initiation.	[ ] Pass [ ] Gap
Technical	HTTP 202 is treated as accepted, not completed.	[ ] Pass [ ] Gap
Technical	The correct GET status endpoint is implemented.	[ ] Pass [ ] Gap
Technical	Callback handling and GET fallback are demonstrated.	[ ] Pass [ ] Gap
Journey	Success, failed, rejected, timeout, and pending scenarios are	shown. [ ] Pass [ ] Gap
Journey	No service is fulfilled before final success.	[ ] Pass [ ] Gap
Journey	Refund status is confirmed before claiming funds were returned.	[ ] Pass [ ] Gap
Security	Credentials and customer data are masked in code, logs, and	screenshots. [ ] Pass [ ] Gap
Operations	References and final statuses can be reconciled and supported.	[ ] Pass [ ] Gap
Readiness	Production configuration differences are explicitly identified.	[ ] Pass [ ] Gap

19. Final Playbook Note

---

Sensitivity: MTN Group – Internal