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.

The LigdiCash JavaScript SDK works in Node.js and TypeScript environments. Every network call is asynchronous (async/await). TypeScript types are bundled with the package.

​
Installation

npm install ligdicash
Requirements: Node.js. The cross-fetch dependency is installed automatically.

​
Initialization

import Ligdicash from "ligdicash";

const client = new Ligdicash({
  apiKey: "{API_KEY}",
  authToken: "{AUTH_TOKEN}",
  platform: "live",
  baseUrl: "https://app.ligdicash.com",
});
Get your apiKey and authToken from the LigdiCash dashboard by creating an API project.

​
Hosted payin

The customer is redirected to the LigdiCash-hosted payment page. This is the recommended flow for online stores.
TypeScript
// 1. Create the invoice
const invoice = client.Invoice({
  currency: "xof",
  description: "Order #ORD-20240512",
  customer_firstname: "Amadou",
  customer_lastname: "Ouedraogo",
  customer_email: "amadou@example.com",
  store_name: "MySuperStore",
  store_website_url: "https://mysuperstore.com",
});

// 2. Add items
invoice.addItem({ name: "Kente shirt", description: "Size M", quantity: 2, unit_price: 15000 });
invoice.addItem({ name: "Shipping fee", description: "", quantity: 1, unit_price: 1500 });

// 3. Start the payment
const response = await invoice.payWithRedirection({
  return_url: "https://mysuperstore.com/order/success",
  cancel_url: "https://mysuperstore.com/order/cancel",
  callback_url: "https://backend.mysuperstore.com/ligdicash/callback",
  custom_data: { transaction_id: "ORD-20240512" },
});

// 4. Redirect the customer
const paymentUrl = response.response_text;
Every network call (payWithRedirection, payWithoutRedirection, send, getTransaction) returns a Promise. A missing await causes a silent comparison against a Promise object instead of the real result.
Never open paymentUrl in an iframe — LigdiCash blocks it. Redirect in the same tab, a new tab, or a popup. On native mobile, use a WebView.
Popup pattern that bypasses blockers: open window.open("about:blank") on the user click (before the await), then navigate to paymentUrl once the response is received. This sidesteps browser popup blockers.

​
Direct payin

The customer pays directly from your interface. You must collect their phone number and, depending on the operator, their OTP code.
TypeScript
// 1. Create the invoice
const invoice = client.Invoice({
  currency: "xof",
  description: "Order #ORD-20240512",
  customer_firstname: "Amadou",
  customer_lastname: "Ouedraogo",
  customer_email: "amadou@example.com",
  store_name: "MySuperStore",
  store_website_url: "https://mysuperstore.com",
});
invoice.addItem({ name: "Kente shirt", description: "Size M", quantity: 2, unit_price: 15000 });

// 2. Start the payment (with OTP provided by the customer)
const response = await invoice.payWithoutRedirection({
  otp: "123456",            // OTP code entered by the customer
  customer: "22670123456",  // Customer phone number, no + or spaces
  callback_url: "https://backend.mysuperstore.com/ligdicash/callback",
  custom_data: { transaction_id: "ORD-20240512" },
});

// 3. Store the token for later verification
const token = response.token;
The OTP mode varies by operator. For example, with a USSD operator, the customer generates the OTP on their phone before you submit. For an approval-mode operator (e.g. Moov Africa), send otp: "" — the customer approves directly in their app. See the operator page for details.

​
Payout

Send money to a customer — refund, salary, payout.

​
To the customer’s LigdiCash wallet

TypeScript
const withdrawal = client.Withdrawal(5000, "Refund for order ORD-20240510", "22670123456");

const response = await withdrawal.send({
  type: "client",
  to_wallet: false,  // false = automatic transfer to the linked mobile money account
  callback_url: "https://backend.mysuperstore.com/ligdicash/callback-payout",
  custom_data: { transaction_id: "REFUND-20240512" },
});

const token = response.token;

​
Directly to mobile money

TypeScript
const response = await withdrawal.send({
  type: "merchant",  // Direct payout, no intermediate wallet
  callback_url: "https://backend.mysuperstore.com/ligdicash/callback-payout",
  custom_data: { transaction_id: "PAY-20240512" },
});
type: "client" uses POST /pay/v01/withdrawal/create (via the LigdiCash wallet). type: "merchant" uses POST /pay/v01/straight/payout (direct mobile money, slower). See Payout — Introduction.

​
Status verification

Call getTransaction with the token stored at creation (not the callback token, which is different).
TypeScript
const token = "eyJ0eXAiOiJ...";  // Token returned at creation

// Payin
const transaction = await client.getTransaction(token, "payin");

// Client payout (withdrawal/create)
// const transaction = await client.getTransaction(token, "client_payout");

// Merchant payout (straight/payout)
// const transaction = await client.getTransaction(token, "merchant_payout");

if (transaction.status === "completed") {
  // Deliver the order / validate the payment
} else if (transaction.status === "pending") {
  // Payment in progress — retry in a few seconds
} else {
  // Payment failed or cancelled
}
Fields available on transaction:
PropertyTypeDescription
statusstring"completed", "pending", "cancelled"
response_codestring"00" success, "01" failure
amountnumberTransaction amount
operator_idstringOperator identifier
operator_namestringOperator name
customerstringCustomer phone number
tokenstringTransaction token
custom_dataobjectCustom data sent at creation
wikistring[]Links to the endpoint’s error codes
Never deliver an order solely based on an incoming callback. Always call getTransaction with the token stored at creation to confirm the status on the LigdiCash server side. See Callback security.

​
TypeScript types

The SDK exports the following types for your function signatures and interfaces:
TypeScript
import type {
  InvoiceParam,
  InvoiceItemParam,
  PayWithRedirectionParam,
  PayWithoutRedirectionParam,
  BaseResponseType,
} from "ligdicash";
TypeUse
InvoiceParamParameters of the Invoice constructor
InvoiceItemParamParameters of addItem
PayWithRedirectionParamParameters of payWithRedirection
PayWithoutRedirectionParamParameters of payWithoutRedirection
BaseResponseTypeResponse returned by payin/payout calls

​
Error handling

TypeScript
try {
  const response = await invoice.payWithRedirection({
    return_url: "https://mysuperstore.com/success",
    cancel_url: "https://mysuperstore.com/cancel",
    callback_url: "https://backend.mysuperstore.com/callback",
    custom_data: { transaction_id: "ORD-20240512" },
  });
} catch (error) {
  // The SDK throws on HTTP errors or API errors
  console.error(error);
}
Also check response.response_code after every call: "00" indicates success, "01" an error. On error, read response.wiki to get the URL with sub-code details.