Create a transaction

This endpoint initiates a payment directly from your interface. You provide the customer’s phone number and, depending on the validation mode of the operator, either the OTP or an empty field. LigdiCash returns a token to store and triggers the validation process on the operator’s side.

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

The LigdiCash Wallet uses distinct endpoints (/pay/v02/debitotp and /pay/v02/debitwallet/withotp). See the LigdiCash Wallet page for its specific integration.

Headers

Apikey

string

required

The API key of your LigdiCash project.

Authorization

string

required

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

string

required

Must be application/json.

Content-Type

string

required

Must be application/json.

Body

commande

object

required

Root object of the request.

Hide commande fields

invoice

object

required

Transaction details.

Hide invoice fields

items

array

required

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

Show Fields of an item

name

string

required

Item name.

description

string

Item description.

quantity

integer

required

Quantity.

unit_price

integer

required

Unit price in XOF.

total_price

integer

required

Line total (unit_price × quantity) in XOF.

total_amount

integer

required

Total amount in XOF (integer, no decimals).

devise

string

required

Currency. Always XOF.

description

string

required

Order description.

customer

string

required

Customer’s mobile money phone number, without + or spaces. Format: 22670XXXXXXX.

customer_firstname

string

Customer’s first name.

customer_lastname

string

Customer’s last name.

customer_email

string

Customer’s email.

external_id

string

required

Must always be empty ("").

otp

string

required

OTP code, depending on the operator’s validation mode:

USSD OTP: OTP generated by the customer through their USSD menu, to be filled before the call.
USSD Push, Guided USSD, SMS OTP (1st request): leave empty ("").
SMS OTP (2nd request): OTP received by the customer by SMS.

store

object

required

Information about your store.

Hide store fields

name

string

required

Name of your store or application.

website_url

string

required

URL of your website.

actions

object

required

Return and notification URLs.

Hide actions fields

cancel_url

string

required

Leave empty ("").

return_url

string

required

Leave empty ("").

callback_url

string

required

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

custom_data

object

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

Request examples

The examples below show two cases depending on the validation mode. Only the otp field changes.

curl -X POST https://app.ligdicash.com/pay/v01/straight/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": [],
        "total_amount": 5000,
        "devise": "XOF",
        "description": "Pro Subscription — January 2025",
        "customer": "22670000000",
        "customer_firstname": "Amadou",
        "customer_lastname": "Diallo",
        "customer_email": "amadou@example.com",
        "external_id": "",
        "otp": "123456"
      },
      "store": {
        "name": "MyApp",
        "website_url": "https://myapp.com"
      },
      "actions": {
        "cancel_url": "",
        "return_url": "",
        "callback_url": "https://myapp.com/api/callback/ligdicash"
      },
      "custom_data": {
        "transaction_id": "ORD-2025-00042"
      }
    }
  }'

curl -X POST https://app.ligdicash.com/pay/v01/straight/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": [],
        "total_amount": 5000,
        "devise": "XOF",
        "description": "Pro Subscription — January 2025",
        "customer": "22670000000",
        "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": "",
        "return_url": "",
        "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/straight/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: [],
          total_amount: 5000,
          devise: "XOF",
          description: "Pro Subscription — January 2025",
          customer: "22670000000",
          customer_firstname: "Amadou",
          customer_lastname: "Diallo",
          customer_email: "amadou@example.com",
          external_id: "",
          otp: "", // or the OTP collected for the USSD OTP mode
        },
        store: { name: "MyApp", website_url: "https://myapp.com" },
        actions: {
          cancel_url: "",
          return_url: "",
          callback_url: "https://myapp.com/api/callback/ligdicash",
        },
        custom_data: { transaction_id: "ORD-2025-00042" },
      },
    }),
  }
);

const data = await response.json();

$otp = ""; // or the OTP collected for the USSD OTP mode

$payload = [
  "commande" => [
    "invoice" => [
      "items" => [],
      "total_amount" => 5000,
      "devise" => "XOF",
      "description" => "Pro Subscription — January 2025",
      "customer" => "22670000000",
      "customer_firstname" => "Amadou",
      "customer_lastname" => "Diallo",
      "customer_email" => "amadou@example.com",
      "external_id" => "",
      "otp" => $otp,
    ],
    "store" => ["name" => "MyApp", "website_url" => "https://myapp.com"],
    "actions" => [
      "cancel_url" => "",
      "return_url" => "",
      "callback_url" => "https://myapp.com/api/callback/ligdicash",
    ],
    "custom_data" => ["transaction_id" => "ORD-2025-00042"],
  ],
];

$ch = curl_init("https://app.ligdicash.com/pay/v01/straight/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

response_code

string

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

token

string

Identifier of the transaction on the LigdiCash side. Store it in your database immediately — required to call the confirm endpoint and re-verify the status.

response_text

string

On success: "Votre requête est en cours de traitement". On failure: the error sub-code in the form Echec (CodeXX).

wiki

string

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

Response example

{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1Qi...",
  "response_text": "Votre requête est en cours de traitement",
  "wiki": "https://client.ligdicash.com/wiki/createInvoice"
}

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

Store the token returned at creation. This is the one you will use to call confirm and check the final status — never rely on the token in the callback payload.

Validation modes — choosing the otp value depending on the operator
Verify the status — calling confirm with the creation token
The transaction_id pattern — best practices for custom_data

​Headers

​Body

​Request examples

​Response

​Response example

​Related pages

Headers

Body

Request examples

Response

Response example

Related pages