JavaScript / TypeScript SDK

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",
});

const Ligdicash = require("ligdicash").default;

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:

Property	Type	Description
`status`	`string`	`"completed"`, `"pending"`, `"cancelled"`
`response_code`	`string`	`"00"` success, `"01"` failure
`amount`	`number`	Transaction amount
`operator_id`	`string`	Operator identifier
`operator_name`	`string`	Operator name
`customer`	`string`	Customer phone number
`token`	`string`	Transaction token
`custom_data`	`object`	Custom data sent at creation
`wiki`	`string[]`	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";

Type	Use
`InvoiceParam`	Parameters of the `Invoice` constructor
`InvoiceItemParam`	Parameters of `addItem`
`PayWithRedirectionParam`	Parameters of `payWithRedirection`
`PayWithoutRedirectionParam`	Parameters of `payWithoutRedirection`
`BaseResponseType`	Response 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.

​Installation

​Initialization

​Hosted payin

​Direct payin

​Payout

​To the customer’s LigdiCash wallet

​Directly to mobile money

​Status verification

​TypeScript types

​Error handling

​Useful links

Installation

Initialization

Hosted payin

Direct payin

Payout

To the customer’s LigdiCash wallet

Directly to mobile money

Status verification

TypeScript types

Error handling

Useful links