Passer au contenu principal
Lorsque vous créez une transaction via l’API LigdiCash, vous recevez un token en retour. Ce token n’est pas stable : sa valeur dans le callback diffère de celle obtenue à la création. Si vous vous appuyez sur lui pour identifier vos transactions, vous perdrez le fil entre ce que vous avez initié et ce que vous avez confirmé. La solution est simple : générez votre propre identifiant côté marchand, stockez-le avant d’appeler l’API, et passez-le dans le champ custom_data. LigdiCash vous le renverra intact dans le callback, et l’affichera dans votre dashboard.

​
Le problème : le token change entre création et callback

À la création d’une transaction, l’API retourne un token : 
{
  "response_code": "00",
  "token": "abc123-creation",
  ...
}
Lorsque LigdiCash vous notifie du résultat via le callback, ce même champ contient une valeur différente : 
{
  "token": "xyz789-callback",
  ...
}
Les deux tokens désignent la même transaction, mais vous ne pouvez pas les relier directement. Sans identifiant propre à votre système, la réconciliation est impossible.

​
La solution : injecter votre transaction_id dans custom_data

Le champ custom_data de chaque requête est un objet JSON dont vous définissez librement les clés. C’est ici que vous injectez votre identifiant : 
"custom_data": {
  "transaction_id": "COMMANDE-20240815-00042"
}
Dans le callback, LigdiCash transforme cet objet en un tableau. Votre transaction_id y apparaît sous cette forme : 
"custom_data": [
  {
    "keyof_customdata": "transaction_id",
    "valueof_customdata": "COMMANDE-20240815-00042",
    "datecreation_customdata": "2026-02-17 06:56:46.55245"
  }
]
Filtrez sur keyof_customdata pour extraire votre valeur — ne vous fiez pas à la position dans le tableau, d’autres entrées peuvent être présentes.

​
Format du transaction_id

Vous êtes libre de choisir le format qui correspond à votre métier :
FormatExempleUsage typique
Référence commandeORD-2026-00042E-commerce — affiché au client
Code court lisiblePAY-8KXZSupport client, mémorisable
UUID v4f47ac10b-58cc-4372-a567-0e02b2c3d479Systèmes distribués, usage interne
Timestamp + aléatoire1723718400-a3f9File de jobs
ID interneorder_8821Application existante
Si vous affichez le transaction_id à vos clients — par exemple sur le reçu ou dans l’interface de suivi — privilégiez un format court et lisible comme ORD-2026-00042. Cela facilite les échanges avec votre support : le client peut le dicter ou le recopier sans erreur.
Si le transaction_id reste purement interne, un UUID v4 est un bon choix par défaut : garanti unique sans coordination entre serveurs.
Évitez les identifiants purement séquentiels exposés côté client (ex : order_1, order_2) — ils révèlent votre volume de transactions. Préférez un préfixe + compteur non trivial, ou un identifiant aléatoire.

​
Cycle de vie recommandé

1

Générez le transaction_id

Avant d’appeler l’API, générez votre identifiant unique côté serveur.
2

Persistez-le en base

Enregistrez-le en base de données avec le statut pending avant d’appeler l’API. Si l’appel échoue, vous avez quand même la trace.
3

Passez-le dans custom_data

Incluez-le dans le tableau custom_data de votre requête de création.
4

Stockez le token de création

Conservez également le token retourné par l’API — il sera nécessaire pour appeler l’endpoint confirm lors de la re-vérification du callback.
5

Retrouvez-le dans le callback

Quand LigdiCash vous notifie, extrayez votre transaction_id depuis custom_data et mettez à jour le statut en base.

​
Retrouver le transaction_id dans le callback

Le payload du callback contient un champ custom_data. Sa forme varie selon le flux (voir Parser custom_data), mais pour un payin il s’agit d’un tableau : 
function extractTransactionId(customData) {
  if (!Array.isArray(customData)) return null;
  const entry = customData.find(
    (item) => item.keyof_customdata === "transaction_id"
  );
  return entry?.valueof_customdata ?? null;
}
Le callback contient aussi un champ transaction_id à la racine du payload. LigdiCash le construit en concaténant les valueof_customdata de toutes les entrées dont la clé contient id (ex : transaction_id, partner_id, event_id…), séparés par ;. Si vous avez injecté plusieurs champs de ce type, cette valeur racine sera un mélange — pas votre identifiant seul. Préférez toujours l’extraction depuis le tableau custom_data.

​
Visibilité dans le dashboard LigdiCash

Le transaction_id que vous injectez dans custom_data est affiché dans le dashboard LigdiCash, dans le tableau des transactions — aussi bien pour les payin que pour les payout. Cela vous permet de réconcilier visuellement vos transactions sans avoir à interroger votre propre base de données.

​
Exemple de requête complet

curl -X POST https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/create \
  -H "Apikey: {API_KEY}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "commande": {
      "invoice": {
        "items": [{ "name": "Abonnement Pro", "price": 5000, "quantity": 1 }],
        "total_amount": 5000,
        "devise": "XOF",
        "description": "Abonnement Pro — Janvier 2025",
        "customer": "",
        "customer_firstname": "Amadou",
        "customer_lastname": "Diallo",
        "customer_email": "amadou@exemple.com"
      },
      "store": {
        "name": "MonApp",
        "website_url": "https://monapp.com"
      },
      "actions": {
        "cancel_url": "https://monapp.com/paiement/annule",
        "return_url": "https://monapp.com/paiement/succes",
        "callback_url": "https://monapp.com/api/callback/ligdicash"
      },
      "custom_data": {
        "transaction_id": "COMMANDE-20240815-00042"
      }
    }
  }'

​
Pages associées