> ## 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.

# 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).

<Warning>
  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](/api-paiement/callback/idempotence).
</Warning>

**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 JavaScript — polling de fallback theme={null}
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" };
}
```

<Tip>
  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.
</Tip>

## 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é.

<Note>
  Consultez [Sécurisation du callback](/api-paiement/callback/securisation) pour le pattern complet de re-vérification avec gestion de l'idempotence.
</Note>

## Pages associées

* [Recommandations](/api-paiement/verification-statut/recommandations) — intervalles de polling, timeouts, gestion du pending
* [Callback — sécurisation](/api-paiement/callback/securisation) — re-vérification avec `confirm`
* [Callback — idempotence](/api-paiement/callback/idempotence) — déduplication des deux requêtes
* [Codes de réponse et statuts](/concepts/codes-reponse-statuts) — référence complète des valeurs de `status`