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.

There are two ways to know whether a LigdiCash transaction succeeded: wait for LigdiCash to notify you (callback), or query the API at regular intervals (polling). Both approaches are complementary — using one without the other leaves a blind spot.

​
Definitions

Callback (passive notification) LigdiCash sends a POST request to your callback_url as soon as the status of a transaction changes. You do not have to trigger anything: LigdiCash comes to notify you. Polling (active checking) Your backend periodically calls the confirm endpoint with the transaction’s token until it obtains a terminal status (completed or notcompleted). You query LigdiCash instead of waiting for it to reach out.

​
Benefits and limits

CallbackPolling
LatencyLow — near-instant notificationVariable — depends on the chosen interval
Server loadMinimal — one incoming callRepeated — N outgoing calls per transaction
Network reliabilityFragile — your server must be reachableRobust — you initiate the calls
Local environmentDifficult — requires a tunnel (ngrok, etc.)Easy — works anywhere
SecurityRequires re-verification with confirmNative — you query the API directly
Slow transactionsIdeal — notified as soon as something changesCostly — keeps polling during the wait

​
Recommendations by use case

Use the callback as the primary strategy The callback is the mechanism designed by LigdiCash for production notification. It is reactive, low-cost, and suited to transactions whose confirmation delay is variable (from a few seconds to several minutes depending on the operator).
LigdiCash sends two POST requests for each callback: one in application/x-www-form-urlencoded and one in application/json. Your handler must deduplicate — see Callback idempotency.
Use polling in local development Locally, your server is not reachable from the internet. Use polling to simulate production behavior without having to set up a tunnel. Use polling as a safety net in production Even in production, a callback may not arrive: your server was temporarily unavailable, the network dropped, or LigdiCash encountered an error sending the notification. A fallback polling triggered a few minutes after the creation of a still pending transaction lets you catch these cases. Do not replace the callback with polling Fast polling (every second) to replace the callback is a bad idea: it multiplies API calls, increases perceived latency, and creates concurrency issues if two workers process the same transaction. The most robust architecture combines the two: primary callback + fallback polling. 
Transaction created
       │
       ├─► Store the token in DB (status = "pending")
       │
       ├─► [Callback] LigdiCash notifies → re-verify with confirm → update
       │
       └─► [Fallback] Job scheduled after N minutes:
               If status is still "pending" → call confirm
               If "completed" or "notcompleted" → update and stop
               If still "pending" after timeout → mark as "expired" and alert
JavaScript — fallback polling
async function checkPendingTransaction(token) {
  const MAX_ATTEMPTS = 10;
  const INTERVAL_MS = 5000; // 5 seconds between calls

  for (let i = 0; i < MAX_ATTEMPTS; 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; // terminal status reached
    }

    await new Promise((r) => setTimeout(r, INTERVAL_MS));
  }

  // After MAX_ATTEMPTS without a terminal status
  return { status: "timeout" };
}
In production, trigger this polling from a background job (cron, worker queue) rather than from the HTTP request thread. This avoids blocking the response to the user during the wait.

​
Security: mandatory re-verification

Whether you use the callback or polling, never fulfill an order without calling confirm with the token stored at creation. A forged callback payload can be sent by anyone who knows your URL. confirm is the only source of truth.
See Securing the callback for the full re-verification pattern with idempotency handling.