Guide complet : Intégrer les paiements Mobile Money avec une API

L'intégration des paiements Mobile Money est devenue essentielle pour toute entreprise opérant en Afrique. Ce guide vous accompagne pas à pas dans l'implémentation technique.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Un compte Simiz actif et vérifié
• Vos clés API (mode sandbox puis production)
• Un environnement de développement configuré

Architecture de l'intégration

Flux de paiement typique

1. Votre client initie un paiement sur votre plateforme
2. Vous envoyez une requête à l'API Simiz
3. Simiz contacte l'opérateur Mobile Money
4. Le client reçoit une notification USSD/Push
5. Le client confirme avec son code PIN
6. Simiz vous notifie via webhook
7. Vous mettez à jour le statut de la commande

Étape 1 : Configuration

Installation du SDK (optionnel)

npm install @simiz/sdk

Configuration des clés API

import { Simiz } from '@simiz/sdk';

const simiz = new Simiz({
  apiKey: process.env.SIMIZ_API_KEY,
  secretKey: process.env.SIMIZ_SECRET_KEY,
  sandbox: process.env.NODE_ENV !== 'production'
});

Étape 2 : Initier un paiement

Requête de paiement

const payment = await simiz.payments.create({
  amount: 5000,
  currency: 'XAF',
  phone: '+237691234567',
  provider: 'orange_money', // ou 'mtn_momo'
  reference: 'ORDER-12345',
  description: 'Achat sur MonSite.com',
  callbackUrl: 'https://monsite.com/webhooks/simiz',
  metadata: {
    orderId: '12345',
    customerId: 'CUST-001'
  }
});

console.log(payment.id); // 'pay_abc123...'
console.log(payment.status); // 'pending'

Réponse de l'API

{
  "id": "pay_abc123xyz",
  "status": "pending",
  "amount": 5000,
  "currency": "XAF",
  "phone": "+237691234567",
  "provider": "orange_money",
  "reference": "ORDER-12345",
  "createdAt": "2026-11-20T10:30:00Z",
  "expiresAt": "2026-11-20T10:45:00Z"
}

Étape 3 : Gérer les webhooks

Configuration du endpoint

app.post('/webhooks/simiz', async (req, res) => {
  // Vérifier la signature
  const signature = req.headers['x-simiz-signature'];
  const isValid = simiz.webhooks.verify(req.body, signature);

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = req.body;

  switch (event.type) {
    case 'payment.success':
      await handlePaymentSuccess(event.data);
      break;
    case 'payment.failed':
      await handlePaymentFailed(event.data);
      break;
    case 'payment.expired':
      await handlePaymentExpired(event.data);
      break;
  }

  res.json({ received: true });
});

Types d'événements

Étape 4 : Vérifier le statut

Polling (si les webhooks ne fonctionnent pas)

const checkPaymentStatus = async (paymentId) => {
  const payment = await simiz.payments.retrieve(paymentId);

  if (payment.status === 'success') {
    // Traiter le succès
  } else if (payment.status === 'failed') {
    // Traiter l'échec
  } else {
    // Toujours en attente, réessayer plus tard
  }
};

Bonnes pratiques

Sécurité

• Stockez vos clés API dans des variables d'environnement
• Validez toujours les signatures des webhooks
• Utilisez HTTPS pour tous les endpoints

Gestion des erreurs

try {
  const payment = await simiz.payments.create({ / ... / });
} catch (error) {
  if (error.code === 'invalid_phone') {
    // Numéro de téléphone invalide
  } else if (error.code === 'provider_unavailable') {
    // Opérateur temporairement indisponible
  } else {
    // Erreur générique
  }
}

Idempotence

Utilisez une clé d'idempotence pour éviter les doubles paiements :

const payment = await simiz.payments.create({
  // ...
}, {
  idempotencyKey: 'order-12345-attempt-1'
});

Tests en sandbox

Le mode sandbox vous permet de tester sans frais :

• Utilisez des numéros de test fournis dans la documentation
• Simulez différents scénarios (succès, échec, timeout)
• Testez vos webhooks avec l'outil de simulation

Conclusion

L'intégration des paiements Mobile Money avec Simiz est simple et rapide. Notre API REST et nos SDKs vous permettent d'être opérationnels en quelques heures.

Besoin d'aide ? Notre équipe technique est disponible à developer@simiz.io.