Modes de validation

Les six modes de validation du payin sans redirection : OTP USSD, USSD Push, USSD guidé, OTP SMS, Redirection LigdiCash, Redirection opérateur. Comprendre les flux et adapter votre UX.

Avec le payin sans redirection, c’est l’opérateur qui décide comment le client confirme son paiement. Ce mécanisme s’appelle le mode de validation. Il détermine le flux exact que vous devez implémenter côté interface : quand collecter un OTP, quand afficher un message d’attente, quand soumettre une seconde requête, ou quand rediriger le client vers une page externe.

Ces six modes sont indépendants. Chaque opérateur en utilise un (parfois deux en cas de fallback). Vous n’implémentez que le mode correspondant à l’opérateur que vous intégrez. Consultez la page dédiée à chaque opérateur pour savoir quel mode appliquer.

Tous les modes utilisent le même endpoint POST /pay/v01/straight/checkout-invoice/create. La différence se joue côté UX et flux : OTP à collecter ou non, message d’attente, redirection éventuelle vers une URL retournée dans response_text. Ne confondez pas avec le payin avec redirection qui utilise un endpoint distinct (/redirect/...) et expose une page de paiement LigdiCash multi-opérateurs.

​

Détail de chaque mode

OTP USSD

Le client génère lui-même un code OTP en composant un code USSD sur son téléphone, avant que vous n’appeliez l’API. Vous collectez le numéro et l’OTP en même temps dans votre formulaire, puis soumettez une seule requête avec les deux.

Flux :

1. Le client compose le code USSD

   Avant de remplir votre formulaire, le client compose le code USSD de son opérateur sur son téléphone (ex. *144*4*6# pour Orange Burkina Faso). Un OTP à usage unique s’affiche sur son écran.

2. Le client saisit ses informations

   Votre formulaire collecte le numéro de téléphone et l’OTP en même temps.

3. Vous soumettez la requête API

   Une seule requête avec le numéro dans customer et l’OTP dans otp. Aucun second appel nécessaire.

4. Confirmation par callback

   LigdiCash vous notifie du résultat via votre callback_url.

UX recommandée : affichez le code USSD à composer avec des instructions claires avant que le client ne remplisse le formulaire.

L’OTP généré via USSD a une durée de validité courte. Invitez le client à saisir son OTP immédiatement après l’avoir généré.

Opérateurs utilisant ce mode : Orange Burkina Faso.

USSD Push

Après votre requête API, l’opérateur envoie directement un écran USSD push sur le téléphone du client. Le client valide avec son code PIN sur cet écran. Vous n’avez pas besoin de re-soumettre de requête.

Flux :

1. Le client saisit son numéro

   Votre formulaire collecte uniquement le numéro de téléphone. Aucun OTP à collecter.

2. Vous soumettez la requête API

   Requête avec le numéro dans customer et otp: "".

3. L'opérateur envoie le push USSD

   Un menu USSD apparaît automatiquement sur le téléphone du client. Il valide le paiement avec son code PIN.

4. Confirmation par callback

   LigdiCash vous notifie du résultat via votre callback_url.

UX recommandée : après la soumission de la requête API, affichez un message demandant au client de valider sur son téléphone. Mettez en place un indicateur d’attente et basculez sur le résultat à la réception du callback (ou via polling sur l’endpoint confirm).

Opérateurs utilisant ce mode : Moov Africa Burkina Faso, Moov Africa Bénin, MTN Mobile Money Bénin, Moov Africa Côte d’Ivoire, Vodacom RDC, Airtel RDC, Africell RDC, Airtel Niger, Moov Africa Niger, YAS Togo, Moov Africa Togo.

USSD guidé

Après votre requête API, l’opérateur envoie un SMS au client contenant les instructions et le code USSD à composer. Le client compose ce code sur son téléphone pour valider. Vous n’avez pas besoin de re-soumettre de requête.

Flux :

1. Le client saisit son numéro

   Votre formulaire collecte uniquement le numéro de téléphone.

2. Vous soumettez la requête API

   Requête avec le numéro dans customer et otp: "".

3. L'opérateur envoie un SMS

   Le client reçoit un SMS contenant les instructions et le code USSD à composer.

4. Le client compose le USSD

   Le client suit les instructions du SMS et valide le paiement depuis son menu USSD.

5. Confirmation par callback

   LigdiCash vous notifie du résultat via votre callback_url.

UX recommandée : après la soumission de la requête API, affichez un message indiquant au client qu’il va recevoir un SMS avec les instructions à suivre.

Exemples de SMS reçus par le client :

MTN Côte d'Ivoire

Vous avez recu une demande de debit avec la reference 1692100357.
Tapez *133# puis choisissez l option retrait pour approuver.

Ce mode est parfois utilisé en fallback du USSD Push quand le push n’aboutit pas (ex. Moov Africa Burkina Faso, Moov Africa Côte d’Ivoire).

Opérateurs utilisant ce mode : MTN Côte d’Ivoire (principal), Zamani Niger (principal), Moov Africa Burkina Faso (fallback), Moov Africa Côte d’Ivoire (fallback).

OTP SMS

Après votre première requête API, l’opérateur envoie un code OTP par SMS au client. Le client vous communique ce code, et vous soumettez une seconde requête API avec l’OTP.

Flux :

1. Le client saisit son numéro

   Votre formulaire collecte le numéro de téléphone. Aucun OTP à ce stade.

2. Première requête API

   Requête avec le numéro dans customer et otp: "". LigdiCash déclenche l’envoi de l’OTP par SMS.

3. Le client reçoit l'OTP

   L’opérateur envoie un code OTP par SMS sur le numéro du client.

4. Le client saisit l'OTP

   Votre interface affiche un second champ de saisie pour l’OTP reçu par SMS.

5. Seconde requête API

   Vous soumettez à nouveau la requête, cette fois avec l’OTP dans le champ otp.

6. Confirmation par callback

   LigdiCash vous notifie du résultat via votre callback_url.

UX recommandée : adoptez un formulaire en deux étapes — d’abord le numéro, puis l’OTP après réception du SMS. Prévoyez un bouton « Renvoyer le code » avec une temporisation.

Ce mode nécessite deux appels API distincts. Attendez que le client ait saisi l’OTP reçu par SMS avant d’envoyer la seconde requête.

Opérateurs utilisant ce mode : Wallet LigdiCash.

Redirection LigdiCash

Pour certains opérateurs, l’intégration LigdiCash passe actuellement par une page web LigdiCash dédiée plutôt que par un traitement direct via l’API. Vous appelez le même endpoint /straight/checkout-invoice/create en préremplissant customer avec le numéro du client. LigdiCash répond avec une URL de page de paiement où seul l’opérateur du numéro est proposé et le numéro est prérempli. Vous redirigez le client vers cette URL — il confirme depuis la page LigdiCash et le paiement procède selon le mode propre à l’opérateur.

Le préremplissage de customer est obligatoire pour ces opérateurs. Sans customer, le filtrage par numéro ne fonctionne pas et la page de paiement n’affiche pas le bon opérateur. Ne pas confondre avec les autres modes du payin sans redirection, où customer est toujours fourni mais sert simplement à initier la transaction sans filtrage.

Flux :

1. Le client saisit son numéro

   Votre formulaire collecte uniquement le numéro de téléphone. Aucun OTP à collecter.

2. Vous soumettez la requête API

   Requête sur POST /pay/v01/straight/checkout-invoice/create avec customer rempli avec le numéro du client et otp: "".

3. LigdiCash retourne une URL de page de paiement

   La réponse contient le token de transaction et le champ response_text rempli avec l’URL de la page de paiement LigdiCash dédiée à cette transaction.

4. Vous redirigez le client

   Redirigez le navigateur du client vers l’URL reçue. La page de paiement LigdiCash affiche le numéro prérempli et l’opérateur déjà sélectionné — le client ne peut ni changer de numéro ni d’opérateur.

5. Confirmation par callback

   Le client confirme depuis la page LigdiCash et le paiement procède selon le mode propre à l’opérateur (USSD push, OTP, etc.). LigdiCash vous notifie le résultat final via votre callback_url.

UX recommandée : redirigez immédiatement le client vers l’URL retournée dans response_text. Déclenchez en parallèle un état d’attente côté backend et basculez vers la confirmation à la réception du callback.

Ce mode utilise bien l’endpoint /straight/checkout-invoice/create (payin sans redirection). Ne pas confondre avec le payin avec redirection, qui utilise un endpoint distinct (/redirect/...) et expose une page de paiement multi-opérateurs où le client choisit son moyen de paiement.

Opérateurs utilisant ce mode : Orange Money RD Congo, Orange Money Guinée Conakry, MTN Mobile Money Guinée Conakry, Orange Money Sénégal, Wave Sénégal, Free Sénégal.

Redirection opérateur

Pour certains opérateurs, l’intégration LigdiCash passe par le portail web de l’opérateur pour authentifier le client. Après votre requête API, LigdiCash répond avec l’URL d’un portail externe (Orange Money, par exemple). Vous redirigez le client vers cette URL — il s’y authentifie et confirme le paiement. Le résultat final arrive par callback.

Flux :

1. Le client saisit son numéro

   Votre formulaire collecte uniquement le numéro de téléphone. Aucun OTP à collecter.

2. Vous soumettez la requête API

   Requête sur POST /pay/v01/straight/checkout-invoice/create avec le numéro dans customer et otp: "".

3. LigdiCash retourne une URL de portail

   La réponse contient le token de transaction et le champ response_text rempli avec l’URL du portail de l’opérateur (ex. https://mpayment.orange-money.com/...).

4. Vous redirigez le client

   Redirigez le navigateur du client vers l’URL reçue. Le client s’authentifie sur le portail de l’opérateur et confirme le paiement.

5. Confirmation par callback

   À l’issue du parcours sur le portail, LigdiCash vous notifie du résultat via votre callback_url. Le retour navigateur du client peut être asynchrone — fiez-vous au callback, pas au retour utilisateur.

Exemple de réponse de création :

{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "response_text": "https://mpayment.orange-money.com/ml/mpayment/abstract/v1nd8lrkjniiezp3gus76kvmlgztvuylkcs2y5kiir6stko13emvuabrv95oaufb",
  "description": "",
  "custom_data": {
    "transaction_id": "59257c61dab04a70a009af019cd34040",
    "logfile": "202605111744086a021568f2037"
  },
  "wiki": "https://client.ligdicash.com/wiki/createInvoice"
}

UX recommandée : redirigez immédiatement le client vers l’URL retournée dans response_text. Côté backend, déclenchez en parallèle un état d’attente sur la transaction et basculez vers la confirmation à la réception du callback.

Le retour navigateur du client après le portail de l’opérateur n’est pas garanti — l’utilisateur peut fermer l’onglet, perdre le réseau, ou ne jamais revenir. Le callback reste la seule source de vérité, comme pour les autres modes. Ne validez jamais le paiement uniquement sur le retour du client.

Ce mode utilise bien l’endpoint /straight/checkout-invoice/create (payin sans redirection), mais le parcours utilisateur inclut une redirection externe. Ne pas confondre avec le payin avec redirection, qui utilise un endpoint distinct et expose la page de paiement LigdiCash.

Opérateurs utilisant ce mode : Orange Money Côte d’Ivoire, Orange Money Mali.

​

Récapitulatif

Mode	Requêtes API	OTP collecté	Ce que fait le client
OTP USSD	1	Avant d’appeler l’API (via USSD)	Compose un USSD, donne l’OTP au marchand
USSD Push	1	Aucun	Valide sur le push USSD reçu
USSD guidé	1	Aucun	Compose un USSD après réception d’un SMS
OTP SMS	2	Après la première requête API (via SMS)	Reçoit un OTP par SMS, le communique au marchand
Redirection LigdiCash	1	Aucun	Est redirigé vers une page LigdiCash pré-filtrée et y confirme
Redirection opérateur	1	Aucun	Est redirigé vers le portail de l’opérateur et y confirme

Pour connaître le mode de validation de chaque opérateur, consultez sa page dédiée dans la section Intégration par opérateur.