Skip to main content

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.

When you create a transaction through the LigdiCash API, you receive a token in return. This token is not stable: its value in the callback differs from the one obtained at creation. If you rely on it to identify your transactions, you will lose the thread between what you initiated and what you confirmed. The solution is simple: generate your own identifier on the merchant side, store it before calling the API, and pass it in the custom_data field. LigdiCash will return it intact in the callback, and display it in your dashboard.

​
The problem: the token changes between creation and callback

When a transaction is created, the API returns a token: 
{
  "response_code": "00",
  "token": "abc123-creation",
  ...
}
When LigdiCash notifies you of the result via the callback, this same field contains a different value: 
{
  "token": "xyz789-callback",
  ...
}
Both tokens point to the same transaction, but you cannot link them directly. Without an identifier of your own, reconciliation is impossible.

​
The solution: inject your transaction_id into custom_data

The custom_data field of each request is a JSON object whose keys you define freely. This is where you inject your identifier: 
"custom_data": {
  "transaction_id": "ORDER-20240815-00042"
}
In the callback, LigdiCash transforms this object into an array. Your transaction_id appears in this form: 
"custom_data": [
  {
    "keyof_customdata": "transaction_id",
    "valueof_customdata": "ORDER-20240815-00042",
    "datecreation_customdata": "2026-02-17 06:56:46.55245"
  }
]
Filter on keyof_customdata to extract your value — do not rely on the position in the array, other entries may be present.

​
transaction_id format

You are free to choose the format that fits your business:
FormatExampleTypical use
Order referenceORD-2026-00042E-commerce — displayed to the customer
Short readable codePAY-8KXZCustomer support, memorable
UUID v4f47ac10b-58cc-4372-a567-0e02b2c3d479Distributed systems, internal use
Timestamp + random1723718400-a3f9Job queue
Internal IDorder_8821Existing application
If you display the transaction_id to your customers — for example on the receipt or in a tracking UI — prefer a short, readable format like ORD-2026-00042. It makes exchanges with your support easier: the customer can dictate or copy it without error.
If the transaction_id stays purely internal, a UUID v4 is a good default: guaranteed unique without coordination between servers.
Avoid purely sequential identifiers exposed to the customer (e.g. order_1, order_2) — they reveal your transaction volume. Prefer a prefix + non-trivial counter, or a random identifier.
1

Generate the transaction_id

Before calling the API, generate your unique identifier server-side.
2

Persist it in your database

Save it in your database with the pending status before calling the API. If the call fails, you still have a trace.
3

Pass it in custom_data

Include it in the custom_data array of your create request.
4

Store the creation token

Also store the token returned by the API — it will be needed to call the confirm endpoint when re-verifying the callback.
5

Retrieve it in the callback

When LigdiCash notifies you, extract your transaction_id from custom_data and update the status in your database.

​
Retrieving the transaction_id in the callback

The callback payload contains a custom_data field. Its shape varies depending on the flow (see Parsing custom_data), but for a payin it is an array: 
function extractTransactionId(customData) {
  if (!Array.isArray(customData)) return null;
  const entry = customData.find(
    (item) => item.keyof_customdata === "transaction_id"
  );
  return entry?.valueof_customdata ?? null;
}
The callback also contains a transaction_id field at the root of the payload. LigdiCash builds it by concatenating the valueof_customdata of all entries whose key contains id (e.g. transaction_id, partner_id, event_id…), separated by ;. If you injected several fields of this type, this root value will be a mix — not your identifier alone. Always prefer extraction from the custom_data array.

​
Visibility in the LigdiCash dashboard

The transaction_id you inject in custom_data is displayed in the LigdiCash dashboard, in the transaction table — for both payin and payout. This lets you reconcile your transactions visually without having to query your own database.

​
Complete request example

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": "Pro Subscription", "price": 5000, "quantity": 1 }],
        "total_amount": 5000,
        "devise": "XOF",
        "description": "Pro Subscription — January 2025",
        "customer": "",
        "customer_firstname": "Amadou",
        "customer_lastname": "Diallo",
        "customer_email": "amadou@example.com"
      },
      "store": {
        "name": "MyApp",
        "website_url": "https://myapp.com"
      },
      "actions": {
        "cancel_url": "https://myapp.com/payment/cancel",
        "return_url": "https://myapp.com/payment/success",
        "callback_url": "https://myapp.com/api/callback/ligdicash"
      },
      "custom_data": {
        "transaction_id": "ORDER-20240815-00042"
      }
    }
  }'