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.

Il existe deux façons de savoir si une transaction LigdiCash a abouti : attendre que LigdiCash vous notifie (callback), ou interroger l’API à intervalles réguliers (polling). Les deux approches sont complémentaires — l’une sans l’autre laisse un angle mort.

​
Définitions

Callback (notification passive) LigdiCash envoie une requête POST à votre callback_url dès que le statut d’une transaction change. Vous n’avez rien à déclencher : c’est LigdiCash qui vient vous notifier. Polling (vérification active) Votre backend appelle périodiquement l’endpoint confirm avec le token de la transaction jusqu’à obtenir un statut terminal (completed ou notcompleted). Vous interrogez LigdiCash au lieu d’attendre qu’il vous contacte.

​
Avantages et limites

CallbackPolling
LatenceFaible — notification quasi-immédiateVariable — dépend de l’intervalle choisi
Charge serveurMinimale — un seul appel entrantRépétée — N appels sortants par transaction
Fiabilité réseauFragile — votre serveur doit être accessibleRobuste — vous initiez les appels
Environnement localDifficile — nécessite un tunnel (ngrok, etc.)Facile — fonctionne partout
SécuritéNécessite re-vérification avec confirmNatif — vous interrogez directement l’API
Transactions lentesIdéal — notifié dès que ça bougeCoûteux — continue de poller pendant l’attente

​
Recommandations selon le cas d’usage

Utilisez le callback comme stratégie principale Le callback est le mécanisme conçu par LigdiCash pour la notification en production. Il est réactif, peu coûteux, et adapté aux transactions dont le délai de confirmation est variable (quelques secondes à plusieurs minutes selon l’opérateur).
LigdiCash envoie deux requêtes POST pour chaque callback : une en application/x-www-form-urlencoded et une en application/json. Votre handler doit dédupliquer — consultez Idempotence du callback.
Utilisez le polling en développement local En local, votre serveur n’est pas accessible depuis internet. Utilisez le polling pour simuler le comportement de production sans avoir à configurer un tunnel. Utilisez le polling comme filet de sécurité en production Même en production, un callback peut ne pas arriver : votre serveur était temporairement indisponible, le réseau a coupé, ou LigdiCash a rencontré une erreur en envoyant la notification. Un polling de secours déclenché quelques minutes après la création d’une transaction encore pending permet de récupérer ces cas. Ne remplacez pas le callback par du polling Un polling rapide (toutes les secondes) pour remplacer le callback est une mauvaise idée : il multiplie les appels API, augmente la latence perçue, et crée des problèmes de concurrence si deux workers traitent la même transaction.

​
Pattern hybride recommandé

L’architecture la plus robuste combine les deux : callback principal + polling de fallback. 
Transaction créée
       │
       ├─► Stocker le token en base (status = "pending")
       │
       ├─► [Callback] LigdiCash notifie → re-vérifier avec confirm → mettre à jour
       │
       └─► [Fallback] Job planifié après N minutes :
               Si status toujours "pending" → appeler confirm
               Si "completed" ou "notcompleted" → mettre à jour et stopper
               Si toujours "pending" après timeout → marquer comme "expiré" et alerter
JavaScript — polling de fallback
async function verifierTransactionEnAttente(token) {
  const MAX_TENTATIVES = 10;
  const INTERVALLE_MS = 5000; // 5 secondes entre chaque appel

  for (let i = 0; i < MAX_TENTATIVES; i++) {
    const res = await fetch(
      `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm?token=${token}`,
      {
        headers: {
          Apikey: process.env.LIGDICASH_API_KEY,
          Authorization: `Bearer ${process.env.LIGDICASH_API_TOKEN}`,
          Accept: "application/json",
        },
      }
    );
    const data = await res.json();

    if (data.status === "completed" || data.status === "notcompleted") {
      return data; // statut terminal atteint
    }

    await new Promise((r) => setTimeout(r, INTERVALLE_MS));
  }

  // Après MAX_TENTATIVES sans statut terminal
  return { status: "timeout" };
}
En production, déclenchez ce polling depuis un job de fond (cron, worker queue) plutôt que depuis le thread de la requête HTTP. Cela évite de bloquer la réponse à l’utilisateur pendant l’attente.

​
Sécurité : re-vérification obligatoire

Que vous utilisiez le callback ou le polling, n’honorez jamais une commande sans avoir appelé confirm avec le token stocké à la création. Un faux payload de callback peut être envoyé par n’importe qui connaissant votre URL. confirm est la seule source de vérité.
Consultez Sécurisation du callback pour le pattern complet de re-vérification avec gestion de l’idempotence.

​
Pages associées