> ## 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.

# Créer une facture

> Endpoint POST /pay/v01/redirect/checkout-invoice/create — paramètres, exemple complet et réponse.

Cet endpoint crée une nouvelle facture de paiement et retourne un lien vers la page de paiement LigdiCash. C'est la première étape du flux payin avec redirection.

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

## Headers

<ParamField header="Apikey" type="string" required>
  La clé API de votre projet LigdiCash.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Votre API TOKEN précédé de `Bearer `. Exemple : `Bearer eyJ0eXAiOiJKV1Qi...`
</ParamField>

<ParamField header="Accept" type="string" required>
  Doit être `application/json`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Doit être `application/json`.
</ParamField>

## Body

<ParamField body="commande" type="object" required>
  Objet racine de la requête.

  <Expandable title="Champs de commande" defaultOpen={true}>
    <ParamField body="invoice" type="object" required>
      Détails de la facture.

      <Expandable title="Champs de invoice" defaultOpen={true}>
        <ParamField body="items" type="array" required>
          Liste des articles. Peut être vide (`[]`) — dans ce cas, seul `total_amount` est pris en compte.

          <Expandable title="Champs d'un item" defaultOpen={true}>
            <ParamField body="name" type="string" required>Nom de l'article.</ParamField>
            <ParamField body="description" type="string">Description de l'article.</ParamField>
            <ParamField body="quantity" type="integer" required>Quantité.</ParamField>
            <ParamField body="unit_price" type="integer" required>Prix unitaire en XOF.</ParamField>
            <ParamField body="total_price" type="integer" required>Prix total de la ligne (`unit_price × quantity`) en XOF.</ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="total_amount" type="integer" required>Montant total en XOF (entier, sans décimales). Si `items` est vide, ce champ seul définit le montant à collecter.</ParamField>
        <ParamField body="devise" type="string" required>Devise. Toujours `XOF`.</ParamField>
        <ParamField body="description" type="string" required>Description de la commande, affichée sur la page de paiement.</ParamField>
        <ParamField body="customer" type="string" required>Doit toujours être vide (`""`). Si un numéro est fourni, LigdiCash filtre la page pour n'afficher que les opérateurs correspondants.</ParamField>
        <ParamField body="customer_firstname" type="string">Prénom du client.</ParamField>
        <ParamField body="customer_lastname" type="string">Nom du client.</ParamField>
        <ParamField body="customer_email" type="string">Email du client.</ParamField>
        <ParamField body="external_id" type="string">Identifiant marchand alternatif. Laisser vide (`""`) si non utilisé. Équivalent du `transaction_id` dans `custom_data`.</ParamField>
        <ParamField body="otp" type="string">Toujours vide (`""`) pour le payin avec redirection.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="store" type="object" required>
      Informations sur votre boutique.

      <Expandable title="Champs de store" defaultOpen={true}>
        <ParamField body="name" type="string" required>Nom de votre boutique ou application, affiché sur la page de paiement.</ParamField>
        <ParamField body="website_url" type="string" required>URL de votre site.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="actions" type="object" required>
      URLs de retour et de notification.

      <Expandable title="Champs de actions" defaultOpen={true}>
        <ParamField body="cancel_url" type="string" required>URL vers laquelle LigdiCash redirige le client s'il annule le paiement.</ParamField>
        <ParamField body="return_url" type="string" required>URL vers laquelle LigdiCash redirige le client après un paiement réussi.</ParamField>
        <ParamField body="callback_url" type="string" required>URL de votre endpoint backend pour les notifications de statut. Doit être accessible publiquement.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="custom_data" type="object">
      Objet libre pour vos métadonnées. LigdiCash vous le retourne dans le callback. Utilisez-le pour passer votre `transaction_id`.
    </ParamField>
  </Expandable>
</ParamField>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro",
              "description": "Accès premium 1 mois",
              "quantity": 1,
              "unit_price": 5000,
              "total_price": 5000
            }
          ],
          "total_amount": 5000,
          "devise": "XOF",
          "description": "Abonnement Pro — Janvier 2025",
          "customer": "",
          "customer_firstname": "Amadou",
          "customer_lastname": "Diallo",
          "customer_email": "amadou@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "https://monapp.com/paiement/annule",
          "return_url": "https://monapp.com/paiement/succes",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00042"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro",
                description: "Accès premium 1 mois",
                quantity: 1,
                unit_price: 5000,
                total_price: 5000,
              },
            ],
            total_amount: 5000,
            devise: "XOF",
            description: "Abonnement Pro — Janvier 2025",
            customer: "",
            customer_firstname: "Amadou",
            customer_lastname: "Diallo",
            customer_email: "amadou@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "https://monapp.com/paiement/annule",
            return_url: "https://monapp.com/paiement/succes",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00042" },
        },
      }),
    }
  );

  const data = await response.json();
  ```

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [[
          "name" => "Abonnement Pro",
          "description" => "Accès premium 1 mois",
          "quantity" => 1,
          "unit_price" => 5000,
          "total_price" => 5000,
        ]],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "",
        "customer_firstname" => "Amadou",
        "customer_lastname" => "Diallo",
        "customer_email" => "amadou@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "https://monapp.com/paiement/annule",
        "return_url" => "https://monapp.com/paiement/succes",
        "callback_url" => "https://monapp.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);
  ```
</CodeGroup>

## Réponse

<ResponseField name="response_code" type="string">
  `"00"` si la facture a été créée avec succès, `"01"` en cas d'erreur.
</ResponseField>

<ResponseField name="token" type="string">
  Identifiant de la transaction côté LigdiCash. À stocker en base — nécessaire pour appeler `confirm`.
</ResponseField>

<ResponseField name="response_text" type="string">
  En cas de succès : l'URL de la page de paiement à ouvrir pour le client. En cas d'échec : le sous-code d'erreur au format `Echec (CodeXX)`.
</ResponseField>

<ResponseField name="wiki" type="string">
  URL vers la documentation des codes d'erreur de cet endpoint. À consulter quand `response_code` vaut `"01"`.
</ResponseField>

## Exemple de réponse

<CodeGroup>
  ```json Succès theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "https://app.ligdicash.com/pay/invoice/eyJ0eXAiOiJKV1Qi...",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

  ```json Échec theme={null}
  {
    "response_code": "01",
    "token": "",
    "response_text": "Echec (Code00)",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```
</CodeGroup>

## Pages associées

* [Rediriger le client](/api-paiement/payin-redirect/rediriger-client) — comment ouvrir `response_text`
* [Pièges courants](/api-paiement/payin-redirect/pieges-courants) — `customer` vide, iframe bloqué
* [Le pattern transaction\_id](/concepts/transaction-id-pattern) — bonnes pratiques pour `custom_data`