Passer au contenu principal

Documentation Index

Fetch the complete documentation index at: https://developers.ligdicash.com/llms.txt

Use this file to discover all available pages before exploring further.

Après la création de la facture, le champ response_text de la réponse contient l’URL de la page de paiement LigdiCash. C’est cette URL que vous devez ouvrir pour que le client puisse choisir son opérateur et finaliser le paiement. Le mode d’ouverture dépend de votre contexte : application web, mobile natif ou hybride.

​
L’iframe est bloqué

LigdiCash bloque le chargement de sa page de paiement dans un <iframe>. N’intégrez jamais l’URL dans une iframe — la page ne s’affichera pas.Ouvrez toujours le lien dans un contexte de navigation réel : même onglet, nouvel onglet, popup ou WebView native.
Ce blocage est appliqué côté serveur via les en-têtes X-Frame-Options et Content-Security-Policy. Il ne s’agit pas d’un bug — c’est une mesure de sécurité délibérée contre le clickjacking.

​
Les 4 modes d’ouverture

ModeContexte recommandéImplémentation
Même ongletWeb — parcours linéaire sans état à conserverwindow.location.href = url
Nouvel ongletWeb — l’utilisateur garde la page courante ouvertewindow.open(url, '_blank')
PopupWeb — UX modale, retour automatique sur la pagePattern anti-bloqueur (voir ci-dessous)
WebView nativeiOS / Android — application mobile nativeDétecter les URLs de retour pour fermer

​
Pattern popup (web)

Le déclenchement d’un window.open() après une requête réseau est systématiquement bloqué par les navigateurs modernes : il n’est pas considéré comme une action directe de l’utilisateur. La solution en deux étapes :
  1. Ouvrir about:blank de manière synchrone au clic, avant tout await
  2. Naviguer vers l’URL de paiement après avoir reçu la réponse API
JavaScript
async function lancerPaiement(commande) {
  // Étape 1 — ouvrir le popup immédiatement au clic (synchrone)
  const popup = window.open("about:blank", "paiement-ligdicash", "width=500,height=700");

  try {
    // Étape 2 — créer la facture
    const response = await fetch(
      "https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/create",
      {
        method: "POST",
        headers: {
          Apikey: process.env.LIGDICASH_API_KEY,
          Authorization: `Bearer ${process.env.LIGDICASH_API_TOKEN}`,
          Accept: "application/json",
          "Content-Type": "application/json",
        },
        body: JSON.stringify(commande),
      }
    );

    const data = await response.json();

    if (data.response_code === "00") {
      // Étape 3 — naviguer dans le popup déjà ouvert
      popup.location.href = data.response_text;
    } else {
      popup.close();
      console.error("Échec création facture :", data.response_text);
    }
  } catch (err) {
    popup.close();
    throw err;
  }
}
Ce pattern fonctionne sur tous les navigateurs modernes (Chrome, Firefox, Safari, Edge). La clé est que window.open() soit appelé dans le même fil d’exécution synchrone que le gestionnaire de clic.

​
Pattern WebView (mobile natif)

Sur iOS et Android, ouvrez l’URL de paiement dans une WebView native plutôt que dans le navigateur système. Cela vous permet de détecter la fin du flux et de fermer la WebView automatiquement. Principe : interceptez chaque navigation dans la WebView et comparez l’URL avec votre return_url et cancel_url. 
import { WebView } from "react-native-webview";

export function PaiementWebView({ paymentUrl, onSuccess, onCancel }) {
  const handleNavigationChange = (navState) => {
    const { url } = navState;

    if (url.startsWith("https://monapp.com/paiement/succes")) {
      onSuccess(); // toujours confirmer côté serveur ensuite
    } else if (url.startsWith("https://monapp.com/paiement/annule")) {
      onCancel();
    }
  };

  return (
    <WebView
      source={{ uri: paymentUrl }}
      onNavigationStateChange={handleNavigationChange}
    />
  );
}
Pour une implémentation complète incluant React Native et Flutter, consultez Intégration mobile.

​
Détecter le retour utilisateur

Quand LigdiCash redirige le client vers votre return_url ou cancel_url, cela indique que le flux de paiement côté LigdiCash est terminé. Ce n’est pas une preuve de succès du paiement.
Ne considérez jamais un paiement comme validé sur la seule base de la redirection vers return_url. Un client peut modifier l’URL manuellement ou la redirection peut survenir suite à un timeout.Vérifiez systématiquement le statut via l’endpoint confirm ou attendez la notification du callback.
Comportement recommandé à la réception de return_url :
  1. Afficher un écran intermédiaire « Vérification du paiement en cours… »
  2. Appeler votre backend, qui appelle confirm avec le token stocké à la création
  3. Afficher le résultat définitif (succès / échec / en attente)

​
Pages associées