Gestion des erreurs — Vue d'ensemble

Comprendre les deux niveaux d’erreur de l’API LigdiCash : rejet de la requête (response_code) et échec de la transaction (callback/confirm).

L’API LigdiCash distingue deux niveaux d’erreur qu’il est essentiel de ne pas confondre : le rejet immédiat d’une requête malformée, et l’échec d’une transaction pourtant bien initiée. Ce guide explique comment traiter chacun.

​

Les deux niveaux d’erreur

​

Niveau 1 — Rejet de la requête (response_code)

Survient immédiatement à l’appel HTTP. LigdiCash a lu votre payload et le rejette.

response_code	Signification
00	Payload valide — la transaction est initiée
01	Payload invalide ou erreur d’authentification — rien n’a été créé

Quand response_code vaut 01, le champ response_text contient un sous-code technique de la forme Echec (CodeXX). Consultez le champ wiki pour en obtenir la description lisible.

response_code: "00" ne garantit pas que le paiement aboutira. C’est uniquement la confirmation que votre requête était syntaxiquement correcte et que la transaction a été mise en file d’attente. Le résultat réel du paiement est communiqué via le callback ou l’endpoint confirm.

​

Niveau 2 — Échec de la transaction (callback / confirm)

Survient après response_code: "00". La transaction a été initiée mais n’a pas abouti côté opérateur.

Champ	Valeur en cas d’échec
status dans le callback	notcompleted
response_code de confirm	01 avec sous-code dans response_text

Ces échecs indiquent des problèmes métier : solde insuffisant, OTP incorrect, numéro non éligible, etc.

---

​

Les catégories d’erreur

Catégorie	Quand	Exemples
Authentification	Immédiat	Apikey invalide, token expiré
Payload invalide	Immédiat	Champ manquant, format de numéro incorrect, montant non entier
Erreur opérateur	Différé (callback)	Annulation
Erreur métier marchand	Immédiat	Payout non activé sur le compte, plafond dépassé
Erreur technique	Immédiat	Timeout, service indisponible

---

​

Stratégie générale de traitement

1. Vérifier response_code immédiatement

   Si response_code === "01" : loggez response_text, consultez l’URL dans wiki pour la description lisible. Ne pas lancer de retry immédiat — corriger d’abord la cause.

2. Stocker le token de création

   Si response_code === "00" : stocker le token retourné dans votre base de données, associé à votre transaction_id. Vous en aurez besoin pour re-vérifier le callback.

3. Traiter le callback de façon défensive

   Ne jamais faire confiance au payload callback seul. Toujours appeler confirm avec le token stocké à l’étape précédente pour valider l’issue réelle.

---

​

Exemple de traitement complet

Node.js

async function initierPaiement(payload) {
  const res = await fetch("https://app.ligdicash.com/pay/v01/straight/checkout-invoice/create", {
    method: "POST",
    headers: {
      "Apikey": process.env.LIGDICASH_API_KEY,
      "Authorization": `Bearer ${process.env.LIGDICASH_AUTH_TOKEN}`,
      "Accept": "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  const data = await res.json();

  if (data.response_code === "01") {
    // Niveau 1 — rejet immédiat
    logger.error({
      event: "ligdicash_request_rejected",
      subcode: data.response_text,  // ex: "Echec (Code00)"
      wiki: data.wiki,              // URL pour la description lisible
    });
    throw new Error(`Requête rejetée : ${data.response_text}`);
  }

  // response_code === "00" : transaction initiée
  // Stocker le token pour la re-vérification callback
  await db.transactions.create({
    transaction_id: payload.custom_data[0].valueof_customdata,
    ligdicash_token: data.token,
    status: "pending",
  });

  return data;
}

---

​

Pages associées

• Le champ wiki — comment décoder Echec (CodeXX) en message lisible
• Liste des sous-codes — référence complète par endpoint
• Erreurs courantes — causes et solutions
• Codes de réponse et statuts — référence complète de response_code
• Sécurisation du callback — re-vérification via confirm