Quickstart — Your first payment in 5 minutes

This guide walks you through the full flow of a hosted payin: you create an invoice, redirect your customer to the LigdiCash payment page, receive the callback, and verify the status with the confirm endpoint.

Prerequisites

Your Apikey and API_TOKEN available in your LigdiCash dashboard
A callback_url publicly reachable from the internet (not localhost)

To expose a local server during development, you can use a tool like ngrok.

Step 1 — Create the transaction

Call the create endpoint, passing your transaction_id in custom_data. Store the returned token — you will need it in step 4.

curl -X POST https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/create \
  -H "Apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_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": "ORD-2025-00042"
      }
    }
  }'

const transactionId = "ORD-2025-00042";

// Store transactionId in your database with status "pending" before this call
await db.orders.update({ id: orderId, ligdicash_tx_id: transactionId, status: "pending" });

const response = await fetch(
  "https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/create",
  {
    method: "POST",
    headers: {
      Apikey: process.env.LIGDICASH_API_KEY,
      Authorization: `Bearer ${process.env.LIGDICASH_API_TOKEN}`,
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      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: transactionId },
      },
    }),
  }
);

const data = await response.json();

if (data.response_code !== "00") {
  throw new Error(`LigdiCash error: ${data.response_text}`);
}

// Store the token for re-verification in step 4
await db.orders.update({ ligdicash_tx_id: transactionId, ligdicash_token: data.token });

const paymentUrl = data.response_text;

$transactionId = "ORD-2025-00042";

$payload = [
  "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" => $transactionId],
  ],
];

$ch = curl_init("https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Apikey: " . $_ENV["LIGDICASH_API_KEY"],
  "Authorization: Bearer " . $_ENV["LIGDICASH_API_TOKEN"],
  "Accept: application/json",
  "Content-Type: application/json",
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($data["response_code"] !== "00") {
  throw new Exception("LigdiCash error: " . $data["response_text"]);
}

$paymentUrl = $data["response_text"];

On success, the response includes the payment page URL in response_text:

{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1Qi...",
  "response_text": "https://app.ligdicash.com/pay/invoice/eyJ0eXAiOiJKV1Qi...",
  "wiki": "https://client.ligdicash.com/wiki/createInvoice"
}

Step 2 — Redirect the customer

The payment URL is in response_text. Open it in the same tab or a new tab — never in an iframe.

Node.js

// Same tab
window.location.href = paymentUrl;

// New tab
window.open(paymentUrl, "_blank");

Iframes are blocked by LigdiCash. The payment link must open in the same tab, a new tab, a popup, or a native WebView on mobile.

Once the payment is completed or cancelled, LigdiCash redirects the customer to your return_url or cancel_url.

Step 3 — Receive the callback

LigdiCash sends a POST request to your callback_url when the transaction status changes.

Node.js (Express)

app.post("/api/callback/ligdicash", async (req, res) => {
  // Always respond 200 first as a best practice
  res.status(200).json({ ok: true });

  const payload = req.body;

  // Extract your transaction_id from custom_data
  const entry = payload.custom_data?.find(
    (item) => item.keyof_customdata === "transaction_id"
  );
  const transactionId = entry?.valueof_customdata;

  if (!transactionId) return;

  // Fetch the token stored at creation (step 1)
  const order = await db.orders.findOne({ ligdicash_tx_id: transactionId });
  if (!order) return;

  // Re-verify the status with confirm (step 4)
  await verifyAndUpdateOrder(order);
});

By convention, respond 200 to LigdiCash to acknowledge receipt of the callback.

Step 4 — Verify with confirm

Never trust the callback payload alone. Call confirm with the token stored at creation to validate the status.

curl -X GET "https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken={TOKEN}" \
  -H "Apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Accept: application/json"

async function verifyAndUpdateOrder(order) {
  const response = await fetch(
    `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=${order.ligdicash_token}`,
    {
      headers: {
        Apikey: process.env.LIGDICASH_API_KEY,
        Authorization: `Bearer ${process.env.LIGDICASH_API_TOKEN}`,
        Accept: "application/json",
      },
    }
  );

  const data = await response.json();

  if (data.status === "completed") {
    await db.orders.update({ id: order.id, status: "paid" });
  } else if (data.status === "notcompleted") {
    await db.orders.update({ id: order.id, status: "failed" });
  }
  // If "pending": do nothing, wait for the next callback
}

What’s next?

Your first payment works. To go further:

Direct payin

Initiate the payment directly from your interface, without leaving your app.

Secure the callback

The complete pattern for re-verification and deduplication.

Payout

Send transfers to your customers or partners.

All operators

Orange Money, Moov, MTN, Wave, and more.

​Prerequisites

​Step 1 — Create the transaction

​Step 2 — Redirect the customer

​Step 3 — Receive the callback

​Step 4 — Verify with confirm

​What’s next?

Direct payin

Secure the callback

Payout

All operators

Prerequisites

Step 1 — Create the transaction

Step 2 — Redirect the customer

Step 3 — Receive the callback

Step 4 — Verify with confirm

What’s next?