Polling vs callback

Quand utiliser le polling (vérification active) et quand se fier au callback (notification passive) — avantages, limites et pattern hybride recommandé.

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

	Callback	Polling
Latence	Faible — notification quasi-immédiate	Variable — dépend de l’intervalle choisi
Charge serveur	Minimale — un seul appel entrant	Répétée — N appels sortants par transaction
Fiabilité réseau	Fragile — votre serveur doit être accessible	Robuste — vous initiez les appels
Environnement local	Difficile — nécessite un tunnel (ngrok, etc.)	Facile — fonctionne partout
Sécurité	Nécessite re-vérification avec confirm	Natif — vous interrogez directement l’API
Transactions lentes	Idéal — notifié dès que ça bouge	Coû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/?invoiceToken=${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

• Recommandations — intervalles de polling, timeouts, gestion du pending
• Callback — sécurisation — re-vérification avec confirm
• Callback — idempotence — déduplication des deux requêtes
• Codes de réponse et statuts — référence complète des valeurs de status