MoMo Open API - Best Practices

1. Security & Credential Management

1. Gestion de la securite et des identifiants (Security & Credential Management)

MoMo API credentials provide direct access to your wallet and must be protected at all times.

Les identifiants de l'API MoMo donnent un acces direct a votre wallet et doivent etre proteges a tout moment.

Protect Your Credentials

Protegez vos identifiants

• API User
• API User
• API Key
• API Key
• Subscription Keys
• Subscription Keys

Credential Management Best Practices

Bonnes pratiques de gestion des identifiants

• Never hard-code credentials in source code
• Ne codez jamais les identifiants en dur dans le code source
• Store secrets in environment variables or secure key vaults
• Stockez les secrets dans des variables d'environnement ou des coffres-forts securises
• Never commit .env or secret files to version control
• Ne validez jamais les fichiers .env ou les fichiers secrets dans le controle de version
• Use separate credentials for Sandbox, Staging, and Production
• Utilisez des identifiants distincts pour Sandbox, Staging et Production

Credential Rotation

Rotation des identifiants

• Implement periodic credential rotation
• Mettez en place une rotation periodique des identifiants
• Rotate credentials when employees leave or systems are decommissioned
• Effectuez une rotation des identifiants lorsque des employes quittent l'entreprise ou que des systemes sont retires
• Rotate immediately if compromise is suspected
• Effectuez immediatement une rotation si une compromission est suspectee

Access Token Handling

Gestion des tokens d'acces

• Do not reuse access tokens across services
• Ne reutilisez pas les tokens d'acces entre differents services
• Cache tokens only for their valid lifetime
• Mettez les tokens en cache uniquement pendant leur duree de validite
• Never log token values
• N'enregistrez jamais les valeurs des tokens dans les logs
• Logging token expiry timestamps is allowed
• L'enregistrement des dates d'expiration des tokens est autorise

2. Callback Handling & Webhook Security

2. Gestion des callbacks et securite des webhooks (Callback Handling & Webhook Security)

Endpoint Requirements

Exigences des endpoints

• Use HTTPS on port 443
• Utilisez HTTPS sur le port 443
• Use certificates from trusted certificate authorities
• Utilisez des certificats provenant d'autorites de certification approuvees
• Respond within a few seconds
• Repondez dans un delai de quelques secondes
• Always return HTTP 200 OK promptly
• Retournez toujours rapidement HTTP 200 OK

Monitoring & Reliability

Surveillance et fiabilite

• Monitor HTTP response codes
• Surveillez les codes de reponse HTTP
• Track latency and availability
• Surveillez la latence et la disponibilite
• Monitor SSL certificate expiry
• Surveillez l'expiration des certificats SSL

Callback Security

Securite des callbacks

• Never blindly trust callback payloads
• Ne faites jamais confiance aveuglement aux payloads des callbacks
• Validate source IP addresses (MoMo callbacks originate from approved IP ranges)
• Validez les adresses IP source (les callbacks MoMo proviennent de plages IP approuvees)
• Validate transaction reference identifiers
• Validez les identifiants de reference des transactions

High-Scale Callback Processing

Traitement des callbacks a grande echelle

• Queue callback processing internally
• Mettez en file d'attente le traitement des callbacks en interne
• Acknowledge callbacks immediately and process asynchronously
• Accusez reception des callbacks immediatement et traitez-les de maniere asynchrone

Additional Callback Security (Recommended)

Securite supplementaire des callbacks (recommandee)

Include a transaction-specific hash in the callback URL:

Incluez un hash specifique a la transaction dans l'URL de callback :

https://api.momocallbacks.com/disbursement-callbacks/{transactionHash}

https://api.momocallbacks.com/disbursement-callbacks/{transactionHash}

3. Transaction Status Handling

3. Gestion du statut des transactions (Transaction Status Handling)

• Do not rely solely on callbacks
• Ne vous reposez pas uniquement sur les callbacks
• Every transaction has a corresponding Get Transaction Status endpoint
• Chaque transaction dispose d'un endpoint Get Transaction Status correspondant
• Use status checks to handle callback or network failures
• Utilisez les verifications de statut pour gerer les echecs de callback ou de reseau

Polling Strategy

Strategie de polling

• Use exponential backoff
• Utilisez un backoff exponentiel
• Define a maximum polling duration
• Definissez une duree maximale de polling
• Stop polling after reaching a terminal status
• Arretez le polling apres avoir atteint un statut terminal

UX Considerations

Considerations UX

• Handle pending and delayed confirmations gracefully
• Gerez correctement les confirmations en attente et retardees
• Never assume immediate transaction success
• Ne supposez jamais un succes immediat de la transaction

4. IP Whitelisting

4. Liste blanche des IP (IP Whitelisting)

• Communicate in advance when adding or changing IP addresses
• Communiquez a l'avance lors de l'ajout ou de la modification d'adresses IP
• Ensure whitelisted IPs are stable and monitored
• Assurez-vous que les IP autorisees sont stables et surveillees

Services Requiring IP Whitelisting

Services necessitant une liste blanche IP

• Disbursements / Transfers
• Disbursements / Transfers
• Remittances / Transfers
• Remittances / Transfers
• Collections / Pre-Approval
• Collections / Pre-Approval
• Dynamic Journey Services
• Dynamic Journey Services

5. Customer Consent for Debits

5. Consentement du client pour les debits (Customer Consent for Debits)

Customer consent is mandatory for debit operations.

Le consentement du client est obligatoire pour les operations de debit.

• Verify that the MSISDN belongs to the requesting user
• Verifiez que le MSISDN appartient a l'utilisateur demandeur
• Implement explicit confirmation logic
• Mettez en oeuvre une logique de confirmation explicite

Recommended Approach

Approche recommandee

• Send an OTP to the MSISDN during registration
• Envoyez un OTP au MSISDN lors de l'enregistrement
• Require OTP verification when using a new or unverified MSISDN
• Exigez une verification OTP lors de l'utilisation d'un MSISDN nouveau ou non verifie

6. Idempotency & Transaction Safety

6. Idempotence et securite des transactions (Idempotency & Transaction Safety)

• Generate X-Reference-Id server-side using UUIDs
• Generez X-Reference-Id cote serveur en utilisant des UUID
• Persist transaction state before initiating MoMo requests
• Conservez l'etat de la transaction avant d'initier les requetes MoMo
• Never reuse X-Reference-Id across different operations
• Ne reutilisez jamais X-Reference-Id entre differentes operations
• Ensure retry logic is idempotent
• Assurez-vous que la logique de retry est idempotente

7. Error Handling & Response Interpretation

7. Gestion des erreurs et interpretation des reponses (Error Handling & Response Interpretation)

• Do not treat HTTP 202 Accepted as success
• Ne considerez pas HTTP 202 Accepted comme un succes
• Always poll for final transaction status
• Verifiez toujours le statut final de la transaction
• Centralize error handling logic
• Centralisez la logique de gestion des erreurs
• Log correlation identifiers for support investigations
• Enregistrez les identifiants de correlation pour les investigations du support

8. Logging, Monitoring & Auditing

8. Journalisation, surveillance et audit (Logging, Monitoring & Auditing)

Logging

Journalisation

• Mask sensitive fields such as tokens and MSISDNs
• Masquez les champs sensibles tels que les tokens et les MSISDN
• Log timestamps, transaction IDs, and status changes
• Enregistrez les horodatages, les ID de transaction et les changements de statut

Monitoring

Surveillance

• Alert on abnormal failure rates
• Declenchez des alertes en cas de taux d'echec anormaux
• Monitor callback delays and API error spikes
• Surveillez les retards de callback et les pics d'erreurs API

Auditing

Audit

• Retain logs according to regulatory requirements
• Conservez les logs conformement aux exigences reglementaires
• Ensure logs are tamper-resistant
• Assurez-vous que les logs sont resistants aux alterations

9. Financial Reconciliation & Reporting

9. Rapprochement financier et reporting (Financial Reconciliation & Reporting)

• Perform financial reconciliation daily
• Effectuez un rapprochement financier quotidiennement
• Do not wait for monthly close or audits
• N'attendez pas la cloture mensuelle ou les audits
• Investigate discrepancies immediately
• Examinez immediatement les ecarts

10. Support & Escalation Readiness

10. Preparation du support et des escalades (Support & Escalation Readiness)

When reporting issues to MoMo support, always provide:

Lors du signalement de problemes au support MoMo, fournissez toujours :

• MSISDN
• MSISDN
• X-Reference-Id
• X-Reference-Id
• Transaction timestamp
• Horodatage de la transaction
• Operation type (Debit, Transfer, Disbursement)
• Type d'operation (Debit, Transfer, Disbursement)