Create an invoice

This endpoint creates a new payment invoice and returns a link to the LigdiCash payment page. It is the first step of the hosted payin flow.

POST https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/create

Headers

string

required

The API key of your LigdiCash project.

string

required

Your API TOKEN prefixed with Bearer . Example: Bearer eyJ0eXAiOiJKV1Qi...

string

required

Must be application/json.

string

required

Must be application/json.

Body

object

required

Root object of the request.

Hide commande fields

object

required

Invoice details.

Hide invoice fields

array

required

List of items. Can be empty ([]) — in that case, only total_amount is taken into account.

Hide Fields of an item

string

required

Item name.

string

Item description.

integer

required

Quantity.

integer

required

Unit price in XOF.

integer

required

Line total (unit_price × quantity) in XOF.

integer

required

Total amount in XOF (integer, no decimals). If items is empty, this field alone defines the amount to collect.

string

required

Currency. Always XOF.

string

required

Order description, displayed on the payment page.

string

required

Must always be empty (""). If a number is provided, LigdiCash filters the page to only show matching operators.

string

Customer first name.

string

Customer last name.

string

Customer email.

string

Alternative merchant identifier. Leave empty ("") if not used. Equivalent of transaction_id in custom_data.

string

Always empty ("") for hosted payin.

object

required

Information about your store.

Hide store fields

string

required

Name of your store or application, displayed on the payment page.

string

required

URL of your website.

object

required

Return and notification URLs.

Hide actions fields

string

required

URL where LigdiCash redirects the customer if they cancel the payment.

string

required

URL where LigdiCash redirects the customer after a successful payment.

string

required

URL of your backend endpoint for status notifications. Must be publicly accessible.

object

Free-form object for your metadata. LigdiCash returns it to you in the callback. Use it to pass your transaction_id.

Request example

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",
            "description": "Premium access for 1 month",
            "quantity": 1,
            "unit_price": 5000,
            "total_price": 5000
          }
        ],
        "total_amount": 5000,
        "devise": "XOF",
        "description": "Pro Subscription — January 2025",
        "customer": "",
        "customer_firstname": "Amadou",
        "customer_lastname": "Diallo",
        "customer_email": "amadou@example.com",
        "external_id": "",
        "otp": ""
      },
      "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 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",
              description: "Premium access for 1 month",
              quantity: 1,
              unit_price: 5000,
              total_price: 5000,
            },
          ],
          total_amount: 5000,
          devise: "XOF",
          description: "Pro Subscription — January 2025",
          customer: "",
          customer_firstname: "Amadou",
          customer_lastname: "Diallo",
          customer_email: "amadou@example.com",
          external_id: "",
          otp: "",
        },
        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 data = await response.json();

$payload = [
  "commande" => [
    "invoice" => [
      "items" => [[
        "name" => "Pro Subscription",
        "description" => "Premium access for 1 month",
        "quantity" => 1,
        "unit_price" => 5000,
        "total_price" => 5000,
      ]],
      "total_amount" => 5000,
      "devise" => "XOF",
      "description" => "Pro Subscription — January 2025",
      "customer" => "",
      "customer_firstname" => "Amadou",
      "customer_lastname" => "Diallo",
      "customer_email" => "amadou@example.com",
      "external_id" => "",
      "otp" => "",
    ],
    "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"],
  ],
];

$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);

Response

string

"00" if the invoice was created successfully, "01" on error.

string

Identifier of the transaction on the LigdiCash side. To be stored in your database — required to call confirm.

string

On success: the URL of the payment page to open for the customer. On failure: the error sub-code in the form Echec (CodeXX).

string

URL to the documentation of error codes for this endpoint. To consult when response_code is "01".

Response example

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

{
  "response_code": "01",
  "token": "",
  "response_text": "Echec (Code00)",
  "wiki": "https://client.ligdicash.com/wiki/createInvoice"
}

Redirect the customer — how to open response_text
Common pitfalls — empty customer, blocked iframe
The transaction_id pattern — best practices for custom_data

Getting started

Core concepts

Payment API

Guides

Error handling

SDKs & Plugins

Other products

AI tools

Resources

Headers

Body

Request example

Response

Response example

​Headers

​Body

​Request example

​Response

​Response example

​Related pages

Headers

Body

Request example

Response

Response example

Related pages