Accepter le mobile money ?

Le mobile money permet d'accepter des paiements depuis les portefeuilles mobiles des clients. C'est un moyen rapide, sécurisé et pratique qui ne nécessite pas de compte bancaire.

Étape mobile money sur le checkout hébergé lomi.

Pour la couverture pays et canaux, voir Canaux de paiement.

Prérequis

Avant d'intégrer le mobile money :

Un compte lomi. avec des clés API test ou live: voir Clés API.
Un URL webhook HTTPS pour le statut final en mode live, voir Webhooks.
Numéro de téléphone client au format E.164 (par exemple +2250707070707).

Fonctionnement des paiements mobile money

Quand un client choisit le mobile money, il reçoit généralement une notification sur son appareil enregistré. Pour finaliser :

Ouvrir la notification ou l'écran de paiement sur l'appareil mobile.
Autoriser le paiement en saisissant le PIN ou en suivant l'authentification du prestataire.
Une fois autorisé, le paiement est traité et client et marchand reçoivent une confirmation.

Après autorisation :

Le portefeuille mobile money du client est débité.
lomi. envoie un webhook à votre serveur quand la transaction atteint un état final.

Le mobile money est asynchrone en mode live. Affichez toujours un état en attente dans votre UI et vérifiez avec les webhooks ou GET /transactions/{id}.

Chemins recommandés

Chemin	À utiliser quand
Checkout hébergé	Votre app crée la commande et redirige le client
Liens de paiement	Vous voulez une URL partageable pour factures, services ou ventes simples
Demandes de paiement	Votre backend crée une demande pour un flux dans votre app
API de charge directe	Vous avez besoin d'un contrôle bas niveau et comprenez l'UX prestataire

La plupart des marchands devraient commencer par le checkout hébergé ou les liens de paiement.

Trois recettes

Chaque recette se termine de la même façon : attendre le webhook, puis GET /transactions/{id}. Voir Vérifier les paiements.

Wave hébergé

Créez une session checkout avec currency_code: "XOF".
Redirigez le client vers checkout_url.
Le client choisit Wave et approuve dans l’app Wave.
Traitez PAYMENT_SUCCEEDED / PAYMENT_FAILED, puis GET /transactions/{id} avant de livrer.

Wave direct (URL de lancement)

POST /charge/wave avec XOF et name plus phoneNumber.
Redirigez ou deep-link vers wave_launch_url ou checkout_url (next_action.type: redirect).
En live, le statut reste en attente jusqu’au paiement dans Wave.
Webhook plus GET /transactions/{id} avant de livrer.

MTN direct (push)

POST /charge/mtn avec montant, devise, countryCode et MSISDN.
Le client reçoit une invite sur le téléphone (next_action.type: await_webhook). Pas de redirection.
En live, le statut reste PENDING jusqu’à l’approbation PIN.
Webhook plus GET /transactions/{id} avant de livrer.

POST /charge/wave avec montant XOF et détails client. Redirigez vers wave_launch_url ou checkout_url dans la réponse, ou lisez le champ normalisé next_action (type: redirect avec url).

curl -sS -X POST "https://sandbox.api.lomi.africa/charge/wave" \
  -H "X-API-KEY: $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "XOF",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phoneNumber": "+2250707070707"
    },
    "description": "Facture #42",
    "successUrl": "https://example.com/success",
    "errorUrl": "https://example.com/error"
  }'

API directe: MTN

POST /charge/mtn avec montant, devise, countryCode et numéro de téléphone client. La réponse inclut next_action (type: await_webhook avec status) ainsi que data.status.

curl -sS -X POST "https://sandbox.api.lomi.africa/charge/mtn" \
  -H "X-API-KEY: $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "XOF",
    "countryCode": "CI",
    "customer": {
      "name": "Jane Doe",
      "phoneNumber": "+2250707070707"
    }
  }'

Vérifier le paiement

Avant de fournir la valeur au client, confirmez le statut final et le montant :

Webhooks: enregistrez votre endpoint et traitez PAYMENT_SUCCEEDED / PAYMENT_FAILED. Voir Recevoir les webhooks.
Récupérer la transaction: GET /transactions/{id} avec le transaction_id de la réponse charge.

Test vs live

	Clé API test	Clé API live
Charge directe MTN	`status: completed` immédiatement ; solde test crédité	`status: PENDING` jusqu'à approbation client
Wave	Le solde test peut être crédité à la création de session	Attendre webhook ou poll transaction
Vrai portefeuille débité	Jamais	Oui

Instructions complètes : Paiements sandbox: mobile money.