Le champ wiki

Comment utiliser le champ wiki retourné par chaque endpoint pour décoder les sous-codes d’erreur Echec (CodeXX) en messages lisibles.

Chaque réponse de l’API LigdiCash — qu’elle soit un succès ou un échec — contient un champ wiki avec une URL vers la documentation des sous-codes de l’endpoint appelé. Ce champ est votre point d’entrée principal pour comprendre la cause exacte d’un response_code: "01".

​

Les URLs wiki par endpoint

Endpoint	URL wiki
POST /pay/v01/redirect/checkout-invoice/create	https://client.ligdicash.com/wiki/createInvoice
GET /pay/v01/redirect/checkout-invoice/confirm	https://client.ligdicash.com/wiki/confirmInvoice
POST /pay/v01/straight/checkout-invoice/create	https://client.ligdicash.com/wiki/createInvoice
POST /pay/v01/withdrawal/create	https://client.ligdicash.com/wiki/createWithdrawal
POST /pay/v01/straight/payout	https://client.ligdicash.com/wiki/createStraightWithdrawal
POST /pay/v01/withdrawal/confirm	https://client.ligdicash.com/wiki/confirmInvoice

L’URL wiki est toujours retournée dans la réponse, même en cas de succès. Vous n’avez pas besoin de la coder en dur dans votre application — lisez-la directement depuis le champ wiki de la réponse.

​

Format de la page wiki

La page wiki retourne une structure de données au format var_dump PHP listant tous les sous-codes possibles pour cet endpoint :

array:2 [▼
  0 => array:2 [▶]
  1 => array:3 [▼
    "code" => "01"
    "description" => "There is an error"
    "subcodes" => array:N [▼
      0 => array:2 [▼
        "code" => "Echec (Code00)"
        "description" => "Authentification failure"
      ]
      1 => array:2 [▼
        "code" => "Echec (Code01)"
        "description" => "Merchant Payout not activated"
      ]
      ...
    ]
  ]
]

Chaque entrée de subcodes correspond à une valeur possible de response_text et sa signification en anglais.

​

Pattern d’utilisation côté backend

L’approche recommandée est de fetch la page wiki uniquement quand response_code === "01", pour enrichir vos logs et construire un message adapté à votre utilisateur.

Node.js

async function handleLigdicashError(data) {
  if (data.response_code !== "01") return;

  // Fetch la page wiki pour décoder le sous-code
  let wikiDescription = data.response_text; // fallback
  try {
    const wikiRes = await fetch(data.wiki);
    const wikiText = await wikiRes.text();
    // Extraire la description du sous-code (parsing selon votre besoin)
    // Exemple : chercher la ligne contenant data.response_text
    wikiDescription = parseWikiDescription(wikiText, data.response_text);
  } catch (e) {
    // La wiki est optionnelle — ne pas bloquer si indisponible
  }

  logger.error({
    event: "ligdicash_error",
    subcode: data.response_text,       // ex: "Echec (Code00)"
    description: wikiDescription,      // ex: "Authentification failure"
    wiki_url: data.wiki,
  });

  return {
    userMessage: buildUserMessage(data.response_text),
    technicalCode: data.response_text,
  };
}

function handleLigdicashError(array $data): array {
    if ($data['response_code'] !== '01') {
        return [];
    }

    $wikiDescription = $data['response_text']; // fallback
    try {
        $wikiContent = file_get_contents($data['wiki']);
        // Parser le contenu pour trouver la description du sous-code
        // $wikiDescription = parseWikiDescription($wikiContent, $data['response_text']);
    } catch (\Exception $e) {
        // La wiki est optionnelle — ne pas bloquer
    }

    error_log(json_encode([
        'event'       => 'ligdicash_error',
        'subcode'     => $data['response_text'],
        'description' => $wikiDescription,
        'wiki_url'    => $data['wiki'],
    ]));

    return [
        'userMessage'   => buildUserMessage($data['response_text']),
        'technicalCode' => $data['response_text'],
    ];
}

import requests
import logging

def handle_ligdicash_error(data: dict) -> dict:
    if data.get("response_code") != "01":
        return {}

    wiki_description = data["response_text"]  # fallback
    try:
        wiki_res = requests.get(data["wiki"], timeout=3)
        # Parser le contenu pour trouver la description du sous-code
        # wiki_description = parse_wiki_description(wiki_res.text, data["response_text"])
    except Exception:
        pass  # La wiki est optionnelle

    logging.error({
        "event": "ligdicash_error",
        "subcode": data["response_text"],
        "description": wiki_description,
        "wiki_url": data["wiki"],
    })

    return {
        "user_message": build_user_message(data["response_text"]),
        "technical_code": data["response_text"],
    }

​

Construire des messages utilisateur

Le response_text (Echec (CodeXX)) est un code technique à ne jamais afficher directement à l’utilisateur final. Construisez un mapping dans votre application :

Node.js

const USER_MESSAGES = {
  "Echec (Code00)": "Vos identifiants API sont invalides. Vérifiez votre Apikey et votre token d'autorisation.",
  "Echec (Code01)": "Cette opération n'est pas activée sur votre compte. Contactez le support LigdiCash.",
  // Ajoutez les autres sous-codes selon la page /erreurs/sous-codes
};

function buildUserMessage(subcode) {
  return USER_MESSAGES[subcode] ?? "Une erreur est survenue. Veuillez réessayer ou contacter le support.";
}

Maintenez ce mapping dans une configuration externe (base de données, fichier JSON) plutôt qu’en dur dans le code, afin de pouvoir le mettre à jour sans redéploiement si LigdiCash ajoute de nouveaux sous-codes.

​

Intégration dans votre monitoring

En production, enrichissez vos alertes avec le sous-code wiki :

Node.js

// Exemple avec un système de monitoring type Sentry / Datadog
if (data.response_code === "01") {
  monitoring.captureEvent({
    message: `LigdiCash payment rejected: ${data.response_text}`,
    level: "error",
    tags: {
      ligdicash_subcode: data.response_text,
      ligdicash_wiki: data.wiki,
      endpoint: "createInvoice",
    },
  });
}

---

​

Pages associées

• Liste des sous-codes — référence de tous les Echec (CodeXX) par endpoint
• Erreurs courantes — causes, solutions et sous-codes associés
• Codes de réponse et statuts — vue d’ensemble de response_code