# Claude Code
Source: https://developers.ligdicash.com/ai-tools/claude-code

Configurer Claude Code pour générer du code d'intégration LigdiCash correct dès le premier essai

Claude Code est l'outil CLI d'Anthropic. En ajoutant un fichier `CLAUDE.md` à la racine de votre projet, vous lui transmettez le contexte LigdiCash une seule fois — il respectera ensuite les conventions API dans chaque réponse.

## Skill LigdiCash

<Card title="Skill LigdiCash pour Claude Code" icon="brain-circuit" href="/sdk/skill-ia">
  Installez le skill pour que Claude Code connaisse l'API LigdiCash dès le départ — téléchargement ZIP, installation via `npx skills` et prompts prêts à l'emploi.
</Card>

## Pré-requis

* [Claude Code installé](https://docs.anthropic.com/fr/claude-code) (`npm install -g @anthropic-ai/claude-code`)
* Un abonnement Claude Pro, Max ou un accès API Anthropic

## Fichier `CLAUDE.md` à créer

Créez un fichier `CLAUDE.md` à la racine de votre projet avec le contenu suivant :

````markdown theme={null}
# Intégration LigdiCash

## Contexte

LigdiCash est un agrégateur de paiement mobile money en Afrique de l'Ouest.
API base URL : https://app.ligdicash.com

## Headers obligatoires sur chaque requête

```
Apikey: {API_KEY}
Authorization: Bearer {AUTH_TOKEN}
Accept: application/json
Content-Type: application/json
```

## Format des données

- Numéros de téléphone : format E.164 sans `+` ni espaces — ex. `22670000000`
- Montants : entiers (XOF n'a pas de décimales) — ex. `5000`
- Devise : `XOF` exclusivement
- Clés API dans les exemples : toujours `{API_KEY}` et `{AUTH_TOKEN}`, jamais de vraies valeurs

## Règle d'or — identification des transactions

Le `token` retourné à la création est différent du `token` reçu dans le callback.
Ne jamais utiliser ce token pour identifier une transaction.

Toujours passer un identifiant marchand dans `custom_data` à la création :
```json
"custom_data": { "transaction_id": "ORD-2025-00042" }
```

Dans le callback, `custom_data` revient sous forme de tableau d'objets. LigdiCash y ajoute ses propres champs (`hash`, `logfile`). Extraire avec :
```javascript
const entry = custom_data.find(e => e.keyof_customdata === "transaction_id");
const transactionId = entry?.valueof_customdata;
```

## Payin avec redirection — pièges

- `customer` doit rester `""` — sinon LigdiCash filtre les opérateurs visibles
- Ne jamais ouvrir l'URL de paiement dans un `<iframe>` — utiliser le même onglet, un nouvel onglet, un popup ou une WebView native
- Popup : ouvrir `about:blank` avant le `await fetch`, puis naviguer après réception de l'URL

## Callback

- LigdiCash envoie deux POST : un `application/x-www-form-urlencoded` + un `application/json`. Dédupliquer.
- Re-vérifier chaque callback en appelant l'endpoint `confirm` avec le token stocké à la création. Ne jamais faire confiance au payload reçu.
````

## Prompts prêts à l'emploi

Copiez-collez ces messages dans Claude Code pour les cas d'usage les plus fréquents.

<AccordionGroup>
  <Accordion title="Payin avec redirection (checkout-invoice)">
    ```
    Implémente un payin LigdiCash avec redirection en [langage].

    - Endpoint : POST https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/create
    - Montant : variable (paramètre de la fonction)
    - customer doit rester "" (vide)
    - Passer transaction_id dans custom_data (objet) : { "transaction_id": "..." }
    - Ouvrir l'URL retournée dans un nouvel onglet (pas d'iframe)
    - Gérer les erreurs HTTP et les response_code != "00"

    Retourner l'URL de paiement ou lever une exception.
    ```
  </Accordion>

  <Accordion title="Handler de callback sécurisé">
    ```
    Écris un handler de callback LigdiCash en [langage/framework].

    Comportement requis :
    1. Accepter POST en application/json ET application/x-www-form-urlencoded
    2. Dédupliquer par token (idempotence)
    3. Re-vérifier le statut en appelant l'endpoint confirm avec le token stocké en base
    4. custom_data dans le callback est un tableau d'objets — extraire via keyof_customdata === "transaction_id"
    5. Mettre à jour la commande en base seulement si le statut confirm est "00"
    ```
  </Accordion>

  <Accordion title="Payout vers mobile money">
    ```
    Implémente un payout LigdiCash direct vers mobile money en [langage].

    - Endpoint : POST https://app.ligdicash.com/pay/v01/straight/payout
    - Paramètres : montant, numéro de téléphone (format 22670XXXXXXX), description
    - Passer transaction_id dans custom_data (objet) : { "transaction_id": "..." }
    - Gérer les erreurs et logger la wiki URL en cas d'échec
    ```
  </Accordion>

  <Accordion title="Payin sans redirection (OTP USSD)">
    ```
    Implémente un payin LigdiCash sans redirection (mode OTP USSD) en [langage].

    - Endpoint : POST https://app.ligdicash.com/pay/v01/straight/checkout-invoice/create
    - external_id doit rester "" (vide)
    - L'utilisateur génère son OTP via le menu USSD de son opérateur AVANT la soumission
    - Passer transaction_id dans custom_data (objet) : { "transaction_id": "..." }
    - La confirmation définitive passe par le callback (ne pas implémenter de polling)
    ```
  </Accordion>
</AccordionGroup>

## Bonnes pratiques

<Tip>
  Lancez `claude` à la racine de votre projet — Claude Code lit automatiquement `CLAUDE.md` au démarrage et connaît d'emblée les conventions LigdiCash.
</Tip>


# Cursor
Source: https://developers.ligdicash.com/ai-tools/cursor

Configurer Cursor pour générer du code d'intégration LigdiCash correct dès le premier essai

Cursor peut générer du code d'intégration LigdiCash en quelques secondes. En ajoutant un fichier de règles à votre projet, vous lui transmettez les conventions de l'API une seule fois.

## Skill LigdiCash

<Card title="Skill LigdiCash — téléchargement et installation" icon="brain-circuit" href="/sdk/skill-ia">
  Téléchargez le ZIP ou installez via `npx skills`. Les fichiers `references/` peuvent être glissés directement dans le chat Cursor comme contexte de session.
</Card>

## Pré-requis

* [Cursor](https://cursor.sh) installé
* Accès au projet à intégrer

## Fichier de règles à créer

Cursor supporte deux emplacements pour les règles de projet :

* **Cursor ≥ 0.45** : créez `.cursor/rules/ligdicash.mdc` à la racine
* **Ancienne version** : créez `.cursorrules` à la racine

Ajoutez le contenu suivant :

````markdown theme={null}
# Intégration LigdiCash

## Contexte

LigdiCash est un agrégateur de paiement mobile money en Afrique de l'Ouest.
API base URL : https://app.ligdicash.com

## Headers obligatoires sur chaque requête

```
Apikey: {API_KEY}
Authorization: Bearer {AUTH_TOKEN}
Accept: application/json
Content-Type: application/json
```

## Format des données

- Numéros de téléphone : format E.164 sans `+` ni espaces — ex. `22670000000`
- Montants : entiers (XOF n'a pas de décimales) — ex. `5000`
- Devise : `XOF` exclusivement
- Clés API dans les exemples : toujours `{API_KEY}` et `{AUTH_TOKEN}`, jamais de vraies valeurs

## Règle d'or — identification des transactions

Le `token` retourné à la création est différent du `token` reçu dans le callback.
Ne jamais utiliser ce token pour identifier une transaction.

Toujours passer un identifiant marchand dans `custom_data` à la création :
```json
"custom_data": { "transaction_id": "ORD-2025-00042" }
```

Dans le callback, `custom_data` revient sous forme de tableau d'objets. LigdiCash y ajoute ses propres champs (`hash`, `logfile`). Extraire avec :
```javascript
const entry = custom_data.find(e => e.keyof_customdata === "transaction_id");
const transactionId = entry?.valueof_customdata;
```

## Payin avec redirection — pièges

- `customer` doit rester `""` — sinon LigdiCash filtre les opérateurs visibles
- Ne jamais ouvrir l'URL de paiement dans un `<iframe>` — utiliser le même onglet, un nouvel onglet, un popup ou une WebView native

## Callback

- LigdiCash envoie deux POST : un `application/x-www-form-urlencoded` + un `application/json`. Dédupliquer.
- Re-vérifier chaque callback en appelant l'endpoint `confirm` avec le token stocké à la création. Ne jamais faire confiance au payload reçu.
````

## Prompts prêts à l'emploi

Utilisez ces prompts dans le chat Cursor (Cmd+L ou Ctrl+L).

<AccordionGroup>
  <Accordion title="Payin avec redirection (checkout-invoice)">
    ```
    Implémente un payin LigdiCash avec redirection en [langage].

    - Endpoint : POST https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/create
    - Montant : variable (paramètre de la fonction)
    - customer doit rester "" (vide)
    - Passer transaction_id dans custom_data (objet) : { "transaction_id": "..." }
    - Ouvrir l'URL retournée dans un nouvel onglet (pas d'iframe)
    - Gérer les erreurs HTTP et les response_code != "00"

    Retourner l'URL de paiement ou lever une exception.
    ```
  </Accordion>

  <Accordion title="Handler de callback sécurisé">
    ```
    Écris un handler de callback LigdiCash en [langage/framework].

    Comportement requis :
    1. Accepter POST en application/json ET application/x-www-form-urlencoded
    2. Dédupliquer par token (idempotence)
    3. Re-vérifier le statut en appelant l'endpoint confirm avec le token stocké en base
    4. custom_data dans le callback est un tableau d'objets — extraire via keyof_customdata === "transaction_id"
    5. Mettre à jour la commande en base seulement si le statut confirm est "00"
    ```
  </Accordion>

  <Accordion title="Payout vers mobile money">
    ```
    Implémente un payout LigdiCash direct vers mobile money en [langage].

    - Endpoint : POST https://app.ligdicash.com/pay/v01/straight/payout
    - Paramètres : montant, numéro de téléphone (format 22670XXXXXXX), description
    - Passer transaction_id dans custom_data (objet) : { "transaction_id": "..." }
    - Gérer les erreurs et logger la wiki URL en cas d'échec
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  Activez **Codebase indexing** dans les paramètres Cursor pour qu'il analyse automatiquement vos fichiers existants et génère du code cohérent avec votre architecture.
</Tip>


# Windsurf
Source: https://developers.ligdicash.com/ai-tools/windsurf

Configurer Windsurf (Cascade) pour générer du code d'intégration LigdiCash correct dès le premier essai

Windsurf et son assistant Cascade peuvent générer du code d'intégration LigdiCash. En ajoutant un fichier de règles à votre projet, Cascade connaît les conventions de l'API dès le départ.

## Skill LigdiCash

<Card title="Skill LigdiCash — téléchargement et installation" icon="brain-circuit" href="/sdk/skill-ia">
  Téléchargez le ZIP ou installez via `npx skills`. Les fichiers `references/` peuvent être ajoutés via **Add Context** dans Cascade pour enrichir chaque session.
</Card>

## Pré-requis

* [Windsurf](https://codeium.com/windsurf) installé
* Accès au projet à intégrer

## Fichier de règles à créer

Créez `.windsurf/rules.md` à la racine de votre projet :

````markdown theme={null}
# Intégration LigdiCash

## Contexte

LigdiCash est un agrégateur de paiement mobile money en Afrique de l'Ouest.
API base URL : https://app.ligdicash.com

## Headers obligatoires sur chaque requête

```
Apikey: {API_KEY}
Authorization: Bearer {AUTH_TOKEN}
Accept: application/json
Content-Type: application/json
```

## Format des données

- Numéros de téléphone : format E.164 sans `+` ni espaces — ex. `22670000000`
- Montants : entiers (XOF n'a pas de décimales) — ex. `5000`
- Devise : `XOF` exclusivement
- Clés API dans les exemples : toujours `{API_KEY}` et `{AUTH_TOKEN}`, jamais de vraies valeurs

## Règle d'or — identification des transactions

Le `token` retourné à la création est différent du `token` reçu dans le callback.
Ne jamais utiliser ce token pour identifier une transaction.

Toujours passer un identifiant marchand dans `custom_data` à la création :
```json
"custom_data": { "transaction_id": "ORD-2025-00042" }
```

Dans le callback, `custom_data` revient sous forme de tableau d'objets. LigdiCash y ajoute ses propres champs (`hash`, `logfile`). Extraire avec :
```javascript
const entry = custom_data.find(e => e.keyof_customdata === "transaction_id");
const transactionId = entry?.valueof_customdata;
```

## Payin avec redirection — pièges

- `customer` doit rester `""` — sinon LigdiCash filtre les opérateurs visibles
- Ne jamais ouvrir l'URL de paiement dans un `<iframe>` — utiliser le même onglet, un nouvel onglet, un popup ou une WebView native

## Callback

- LigdiCash envoie deux POST : un `application/x-www-form-urlencoded` + un `application/json`. Dédupliquer.
- Re-vérifier chaque callback en appelant l'endpoint `confirm` avec le token stocké à la création. Ne jamais faire confiance au payload reçu.
````

## Prompts prêts à l'emploi

Utilisez ces prompts dans le chat Cascade (Cmd+L ou Ctrl+L).

<AccordionGroup>
  <Accordion title="Payin avec redirection (checkout-invoice)">
    ```
    Implémente un payin LigdiCash avec redirection en [langage].

    - Endpoint : POST https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/create
    - Montant : variable (paramètre de la fonction)
    - customer doit rester "" (vide)
    - Passer transaction_id dans custom_data (objet) : { "transaction_id": "..." }
    - Ouvrir l'URL retournée dans un nouvel onglet (pas d'iframe)
    - Gérer les erreurs HTTP et les response_code != "00"

    Retourner l'URL de paiement ou lever une exception.
    ```
  </Accordion>

  <Accordion title="Handler de callback sécurisé">
    ```
    Écris un handler de callback LigdiCash en [langage/framework].

    Comportement requis :
    1. Accepter POST en application/json ET application/x-www-form-urlencoded
    2. Dédupliquer par token (idempotence)
    3. Re-vérifier le statut en appelant l'endpoint confirm avec le token stocké en base
    4. custom_data dans le callback est un tableau d'objets — extraire via keyof_customdata === "transaction_id"
    5. Mettre à jour la commande en base seulement si le statut confirm est "00"
    ```
  </Accordion>

  <Accordion title="Payout vers mobile money">
    ```
    Implémente un payout LigdiCash direct vers mobile money en [langage].

    - Endpoint : POST https://app.ligdicash.com/pay/v01/straight/payout
    - Paramètres : montant, numéro de téléphone (format 22670XXXXXXX), description
    - Passer transaction_id dans custom_data (objet) : { "transaction_id": "..." }
    - Gérer les erreurs et logger la wiki URL en cas d'échec
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  Cascade comprend le contexte de vos fichiers ouverts. Ouvrez le fichier où vous intégrez LigdiCash avant de lancer un prompt — la réponse sera directement adaptée à votre code existant.
</Tip>


# Configurer l'URL de callback
Source: https://developers.ligdicash.com/api-paiement/callback/configuration

Comment définir une URL de callback fiable, accessible publiquement et prête à recevoir les notifications LigdiCash.

Votre URL de callback est l'adresse à laquelle LigdiCash envoie les notifications de résultat. Vous la fournissez dans le champ `callback_url` de chaque requête de création de transaction.

## Exigences techniques

| Critère          | Requis                                                    |
| ---------------- | --------------------------------------------------------- |
| Protocole        | HTTP ou HTTPS                                             |
| Accessibilité    | Publiquement accessible depuis Internet                   |
| Authentification | Pas de basic auth ni de token dans l'URL                  |
| Méthode acceptée | POST                                                      |
| Formats acceptés | `application/json` et `application/x-www-form-urlencoded` |

<Note>
  En production, préférez HTTPS pour protéger les données en transit — même si HTTP est techniquement accepté par LigdiCash.
</Note>

## Définir le callback à la création

Selon le type de transaction, la `callback_url` est passée à deux endroits différents dans le corps de la requête.

**Dans l'objet `commande`** — pour le Payout :

```json theme={null}
{
  "commande": {
    "callback_url": "https://backend.masuperboutique.com/callback",
    ...
  }
}
```

**Dans l'objet `actions`** — pour le Payin :

```json theme={null}
{
  "commande": { 
    ...
    "actions": {
      "cancel_url": "https://masuperboutique.com/cancel",
      "return_url": "https://masuperboutique.com/success",
      "callback_url": "https://backend.masuperboutique.com/callback"
    }
    ...
  },
}
```

Vous pouvez utiliser une URL différente par type de transaction ou une URL unique qui dispatche selon le contenu du payload.

## Développement local

Votre machine locale n'est pas accessible depuis Internet. Pour tester le callback en local, utilisez un tunnel comme [ngrok](https://ngrok.com) ou [Expose](https://expose.dev) qui crée une URL publique HTTPS pointant vers votre serveur local.

```bash theme={null}
# Exemple avec ngrok
ngrok http 3000
# → https://abc123.ngrok.io reçoit les POST et les redirige vers localhost:3000
```

<Note>
  L'URL ngrok change à chaque démarrage sur le plan gratuit. Utilisez un sous-domaine fixe ou déployez sur un environnement de staging pour des tests plus stables.
</Note>

## Pages associées

* [Payload Payin](/api-paiement/callback/payload-payin) — contenu des notifications payin
* [Payload Payout](/api-paiement/callback/payload-payout) — contenu des notifications payout
* [Idempotence](/api-paiement/callback/idempotence) — gérer les deux requêtes par événement


# Exemples par framework
Source: https://developers.ligdicash.com/api-paiement/callback/exemples-frameworks

Implémentations complètes du callback LigdiCash en PHP, Laravel, Node.js Express et Python.

Ces exemples montrent un handler de callback complet : déduplication, re-vérification et traitement métier. Adaptez les détails (nom de table, logique métier) à votre application.

<Tabs>
  <Tab title="PHP">
    ```php theme={null}
    <?php

    $rawBody = file_get_contents('php://input');
    $contentType = $_SERVER['CONTENT_TYPE'] ?? '';

    // Supporter JSON et form-urlencoded
    if (str_contains($contentType, 'application/json')) {
        $payload = json_decode($rawBody, true);
    } else {
        parse_str($rawBody, $payload);
        // custom_data arrive en JSON stringifié en form-urlencoded
        if (isset($payload['custom_data']) && is_string($payload['custom_data'])) {
            $payload['custom_data'] = json_decode($payload['custom_data'], true) ?? $payload['custom_data'];
        }
    }

    $transactionId = null;
    foreach ($payload['custom_data'] ?? [] as $entry) {
        if (($entry['keyof_customdata'] ?? null) === 'transaction_id') {
            $transactionId = $entry['valueof_customdata'] ?? null;
            break;
        }
    }
    if (!$transactionId) {
        http_response_code(400);
        exit;
    }

    // Déduplication
    try {
        $pdo->exec("INSERT INTO processed_callbacks (transaction_id) VALUES ('$transactionId')");
    } catch (PDOException $e) {
        // Déjà traité — doublon LigdiCash
        http_response_code(200);
        exit;
    }

    // Retrouver le token stocké à la création
    $stmt = $pdo->prepare('SELECT token FROM transactions WHERE transaction_id = ?');
    $stmt->execute([$transactionId]);
    $row = $stmt->fetch();

    if (!$row) {
        http_response_code(404);
        exit;
    }

    // Re-vérification
    $params = http_build_query(['invoiceToken' => $row['token']]);
    $ch = curl_init("https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm?$params");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Apikey: ' . $_ENV['LIGDICASH_API_KEY'],
            'Authorization: Bearer ' . $_ENV['LIGDICASH_AUTH_TOKEN'],
        ],
    ]);
    $result = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if (($result['status'] ?? '') === 'completed') {
        // Traitement métier
        $pdo->exec("UPDATE orders SET status = 'paid' WHERE transaction_id = '$transactionId'");
    }

    http_response_code(200);
    ```
  </Tab>

  <Tab title="Laravel">
    ```php theme={null}
    <?php

    namespace App\Http\Controllers;

    use Illuminate\Http\Request;
    use Illuminate\Support\Facades\DB;
    use Illuminate\Support\Facades\Http;

    class LigdicashCallbackController extends Controller
    {
        public function handle(Request $request)
        {
            $transactionId = collect($request->input('custom_data', []))
                ->firstWhere('keyof_customdata', 'transaction_id')['valueof_customdata'] ?? null;

            if (!$transactionId) {
                return response()->noContent(400);
            }

            // Déduplication atomique
            $inserted = DB::table('processed_callbacks')->insertOrIgnore([
                'transaction_id' => $transactionId,
                'created_at' => now(),
            ]);

            if (!$inserted) {
                return response()->noContent(200);
            }

            // Retrouver le token stocké
            $transaction = DB::table('transactions')
                ->where('transaction_id', $transactionId)
                ->first();

            if (!$transaction) {
                return response()->noContent(404);
            }

            // Re-vérification
            $result = Http::withHeaders([
                'Apikey' => config('ligdicash.api_key'),
                'Authorization' => 'Bearer ' . config('ligdicash.auth_token'),
            ])->get('https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm', [
                'invoiceToken' => $transaction->token,
            ])->json();

            if (($result['status'] ?? '') === 'completed') {
                DB::table('orders')
                    ->where('transaction_id', $transactionId)
                    ->update(['status' => 'paid']);
            }

            return response()->noContent(200);
        }
    }
    ```
  </Tab>

  <Tab title="Node.js / Express">
    ```javascript theme={null}
    import express from 'express';

    const app = express();
    app.use(express.json());
    app.use(express.urlencoded({ extended: true }));

    app.post('/callback', async (req, res) => {
      const payload = req.body;
      const customData = Array.isArray(payload.custom_data) ? payload.custom_data : [];
      const entry = customData.find((item) => item.keyof_customdata === 'transaction_id');
      const transactionId = entry?.valueof_customdata;

      if (!transactionId) {
        return res.sendStatus(400);
      }

      // Déduplication atomique
      try {
        await db.query(
          'INSERT INTO processed_callbacks (transaction_id) VALUES ($1)',
          [transactionId]
        );
      } catch {
        // Contrainte d'unicité — doublon LigdiCash
        return res.sendStatus(200);
      }

      // Retrouver le token stocké
      const row = await db.query(
        'SELECT token FROM transactions WHERE transaction_id = $1',
        [transactionId]
      ).then(r => r.rows[0]);

      if (!row) return res.sendStatus(404);

      // Re-vérification
      const params = new URLSearchParams({ invoiceToken: row.token });
      const verify = await fetch(
        `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm?${params}`,
        {
          headers: {
            Apikey: process.env.LIGDICASH_API_KEY,
            Authorization: `Bearer ${process.env.LIGDICASH_AUTH_TOKEN}`,
          },
        }
      );
      const result = await verify.json();

      if (result.status === 'completed') {
        await db.query(
          "UPDATE orders SET status = 'paid' WHERE transaction_id = $1",
          [transactionId]
        );
      }

      res.sendStatus(200);
    });
    ```
  </Tab>

  <Tab title="Python / Django">
    ```python theme={null}
    import json
    import os
    import requests
    from django.db import IntegrityError
    from django.http import HttpResponse
    from django.views.decorators.csrf import csrf_exempt
    from django.views.decorators.http import require_POST


    @csrf_exempt
    @require_POST
    def ligdicash_callback(request):
        content_type = request.content_type or ""

        if "application/json" in content_type:
            payload = json.loads(request.body)
        else:
            payload = request.POST.dict()
            # custom_data arrive en JSON stringifié en form-urlencoded
            if isinstance(payload.get("custom_data"), str):
                try:
                    payload["custom_data"] = json.loads(payload["custom_data"])
                except (json.JSONDecodeError, TypeError):
                    pass

        custom_data = payload.get("custom_data") or []
        entry = next(
            (e for e in custom_data if e.get("keyof_customdata") == "transaction_id"),
            None,
        )
        transaction_id = entry.get("valueof_customdata") if entry else None
        if not transaction_id:
            return HttpResponse(status=400)

        # Déduplication atomique
        try:
            ProcessedCallback.objects.create(transaction_id=transaction_id)
        except IntegrityError:
            return HttpResponse(status=200)

        # Retrouver le token stocké
        try:
            transaction = Transaction.objects.get(transaction_id=transaction_id)
        except Transaction.DoesNotExist:
            return HttpResponse(status=404)

        # Re-vérification
        result = requests.get(
            "https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm",
            params={"invoiceToken": transaction.token},
            headers={
                "Apikey": os.environ["LIGDICASH_API_KEY"],
                "Authorization": f"Bearer {os.environ['LIGDICASH_AUTH_TOKEN']}",
            },
        ).json()

        if result.get("status") == "completed":
            Order.objects.filter(transaction_id=transaction_id).update(status="paid")

        return HttpResponse(status=200)
    ```
  </Tab>
</Tabs>

<Note>
  Les exemples ci-dessus utilisent l'endpoint de confirmation payin redirect. Pour un payout, remplacez l'endpoint par `GET /pay/v01/withdrawal/confirm/?withdrawalToken={token}`. Voir [Vérifier le statut d'un payout](/api-paiement/payout/verifier-statut).
</Note>

## Pages associées

* [Sécurisation du callback](/api-paiement/callback/securisation)
* [Idempotence et déduplication](/api-paiement/callback/idempotence)
* [Parser custom\_data](/api-paiement/callback/parser-custom-data)


# Idempotence et déduplication
Source: https://developers.ligdicash.com/api-paiement/callback/idempotence

LigdiCash envoie deux requêtes POST par événement. Comment garantir que votre traitement n'est exécuté qu'une seule fois.

Pour chaque événement de transaction, LigdiCash envoie **deux requêtes POST** à votre `callback_url` :

* Une en `application/x-www-form-urlencoded`
* Une en `application/json`

Les deux contiennent exactement les mêmes données. Votre serveur va donc recevoir deux appels pour un seul événement. Sans déduplication, vous risquez de traiter la même transaction deux fois — livrer une commande en double, déclencher deux remboursements, créditer un compte deux fois.

## Stratégie de déduplication

La méthode la plus simple consiste à marquer chaque transaction traitée dans votre base de données et à ignorer les appels suivants pour la même transaction.

<Steps>
  <Step title="Extraire votre transaction_id">
    Parsez `custom_data` pour extraire votre `transaction_id` via `keyof_customdata`. Voir [Parser custom\_data](/api-paiement/callback/parser-custom-data).
  </Step>

  <Step title="Vérifier si déjà traité">
    Avant tout traitement, cherchez si cet identifiant existe déjà dans votre table de transactions traitées.
  </Step>

  <Step title="Traiter et marquer atomiquement">
    Si non traité, effectuez votre traitement et marquez la transaction comme traitée dans la même transaction de base de données. L'atomicité évite les race conditions si les deux requêtes arrivent simultanément.
  </Step>
</Steps>

## Implémentation

```javascript theme={null}
app.post('/callback', async (req, res) => {
  const entry = req.body.custom_data?.find(
    (item) => item.keyof_customdata === 'transaction_id'
  );
  const transactionId = entry?.valueof_customdata;
  if (!transactionId) return res.sendStatus(400);

  // Insertion avec contrainte d'unicité — échoue si déjà traité
  const inserted = await db.query(
    'INSERT INTO processed_callbacks (transaction_id) VALUES (?) ON CONFLICT DO NOTHING',
    [transactionId]
  );

  if (inserted.rowCount === 0) {
    // Déjà traité — deuxième requête du doublon LigdiCash
    return res.sendStatus(200);
  }

  // Première réception — traitement métier
  await processPayment(transactionId);

  res.sendStatus(200);
});
```

```php theme={null}
// Avec une contrainte UNIQUE sur transaction_id en base
try {
    $db->insert('processed_callbacks', ['transaction_id' => $transactionId]);
} catch (UniqueConstraintException $e) {
    // Déjà traité
    http_response_code(200);
    exit;
}

// Première réception — traitement métier
processPayment($transactionId);
```

<Note>
  La contrainte d'unicité en base de données est plus fiable qu'un simple `SELECT` suivi d'un `INSERT` — deux requêtes simultanées peuvent passer le `SELECT` en même temps avant que l'une des deux n'ait effectué son `INSERT`.
</Note>

## Pages associées

* [Introduction au callback](/api-paiement/callback/introduction)
* [Parser custom\_data](/api-paiement/callback/parser-custom-data)
* [Exemples par framework](/api-paiement/callback/exemples-frameworks)


# Le callback (webhook) — Introduction
Source: https://developers.ligdicash.com/api-paiement/callback/introduction

LigdiCash envoie un POST sur votre URL de callback à chaque événement de paiement. Le mécanisme central pour la fiabilité de votre intégration.

Le callback est une notification HTTP que LigdiCash envoie à votre serveur lorsqu'une transaction change de statut — paiement complété, paiement échoué, payout finalisé. C'est le mécanisme principal pour connaître le résultat d'une transaction en temps réel, sans interroger l'API en boucle.

## Comment ça fonctionne

Vous fournissez une `callback_url` lors de chaque requête de création de transaction. Quand LigdiCash dispose d'un résultat, il envoie un POST à cette URL avec les détails de la transaction.

## Les deux requêtes envoyées

<Warning>
  LigdiCash envoie **deux requêtes POST** pour chaque événement : une en `application/x-www-form-urlencoded` et une en `application/json`. Les deux contiennent les mêmes informations. Votre serveur recevra donc deux appels par événement — prévoyez une logique de déduplication.
</Warning>

## Ce que le callback ne garantit pas

* **Le payload reçu ne doit jamais être considéré comme source de vérité.** N'importe qui connaissant votre URL de callback peut envoyer un faux payload. Toujours re-vérifier via l'endpoint `confirm` avec le token stocké à la création avant d'agir.

## Dans cette section

<CardGroup>
  <Card title="Configuration" icon="gear" href="/api-paiement/callback/configuration">
    Définir une URL de callback fiable et accessible publiquement.
  </Card>

  <Card title="Payload Payin" icon="arrow-down-to-line" href="/api-paiement/callback/payload-payin">
    Anatomie complète du payload reçu lors d'un paiement entrant.
  </Card>

  <Card title="Payload Payout" icon="arrow-up-from-line" href="/api-paiement/callback/payload-payout">
    Différences du payload pour un payout.
  </Card>

  <Card title="Sécurisation" icon="shield-check" href="/api-paiement/callback/securisation">
    Le pattern de re-vérification avant tout traitement.
  </Card>

  <Card title="Parser custom_data" icon="code" href="/api-paiement/callback/parser-custom-data">
    Extraire votre transaction\_id selon le type de flux.
  </Card>

  <Card title="Idempotence" icon="arrows-rotate" href="/api-paiement/callback/idempotence">
    Dédupliquer les deux requêtes reçues par événement.
  </Card>

  <Card title="Exemples par framework" icon="laptop-code" href="/api-paiement/callback/exemples-frameworks">
    Implémentations complètes en PHP, Laravel, Node.js, Python.
  </Card>
</CardGroup>


# Parser custom_data dans le callback
Source: https://developers.ligdicash.com/api-paiement/callback/parser-custom-data

Comment extraire votre transaction_id depuis custom_data et pourquoi external_id est le raccourci recommandé.

Le champ `custom_data` dans le callback est un tableau d'objets. Chaque entrée correspond à un champ que vous avez passé à la création de la transaction. LigdiCash y ajoute automatiquement ses propres champs — filtrez toujours par `keyof_customdata` pour extraire les vôtres.

## Structure de custom\_data

```json theme={null}
"custom_data": [
  {
    "keyof_customdata": "transaction_id",
    "valueof_customdata": "ART5A7044E5",
    "datecreation_customdata": "2026-05-09 07:20:23.362788"
  },
  {
    "keyof_customdata": "hash",
    "valueof_customdata": "f918c54d54cdc334ade09f8c228a224b1d3df646250c84dcdd99af528ddcd450",
    "datecreation_customdata": "2026-05-09 07:20:23.362788"
  },
  {
    "keyof_customdata": "logfile",
    "valueof_customdata": "2026050907202369fee03756652",
    "datecreation_customdata": "2026-05-09 07:20:23.362788"
  }
]
```

LigdiCash ajoute systématiquement `hash` et `logfile` à votre tableau. Ne vous appuyez pas sur l'index ou l'ordre des entrées — filtrez toujours par `keyof_customdata`.

## Extraire votre transaction\_id

```javascript theme={null}
function getCustomValue(customData, key) {
  const entry = customData.find(e => e.keyof_customdata === key);
  return entry ? entry.valueof_customdata : null;
}

const transactionId = getCustomValue(payload.custom_data, 'transaction_id');
```

```php theme={null}
function getCustomValue(array $customData, string $key): ?string {
    foreach ($customData as $entry) {
        if ($entry['keyof_customdata'] === $key) {
            return $entry['valueof_customdata'];
        }
    }
    return null;
}

$transactionId = getCustomValue($payload['custom_data'], 'transaction_id');
```

## Le champ external\_id

`external_id` est une concaténation des valeurs de tous les champs de `custom_data` dont la clé contient `"id"`. Si votre `custom_data` ne contient qu'un seul champ avec `"id"` dans le nom (ex : `transaction_id`), `external_id` correspondra à sa valeur. Mais si plusieurs clés contiennent `"id"`, leurs valeurs seront concaténées — ce qui le rend peu fiable pour identifier la transaction.

<Warning>
  Ne vous fiez pas à `external_id` comme identifiant unique. Parsez toujours `custom_data` directement avec `keyof_customdata` pour extraire votre `transaction_id` de manière fiable.
</Warning>

## Pages associées

* [Payload Payin](/api-paiement/callback/payload-payin)
* [Sécurisation du callback](/api-paiement/callback/securisation)
* [Le pattern transaction\_id](/concepts/transaction-id-pattern)


# Anatomie du payload — Payin
Source: https://developers.ligdicash.com/api-paiement/callback/payload-payin

Détail de chaque champ du payload reçu lors d'un paiement entrant. Exemple réel et explication champ par champ.

Lors d'un paiement entrant, LigdiCash envoie deux requêtes POST à votre `callback_url` — une en `application/json`, une en `application/x-www-form-urlencoded`. Les deux contiennent les mêmes données. Cette page détaille la structure JSON.

## Exemple complet

```json theme={null}
{
  "date": "2026-05-09 07:20:23+00",
  "wiki": "https://client.ligdicash.com/wiki/confirmInvoice",
  "token": "",
  "amount": 4200,
  "status": "completed",
  "montant": 4200,
  "customer": "22676275726",
  "oreference": "",
  "request_id": "P2777636082026",
  "custom_data": [
    {
      "keyof_customdata": "transaction_id",
      "valueof_customdata": "ART5A7044E5",
      "datecreation_customdata": "2026-05-09 07:20:23.362788"
    },
    {
      "keyof_customdata": "hash",
      "valueof_customdata": "f918c54d54cdc334ade09f8c228a224b1d3df646250c84dcdd99af528ddcd450",
      "datecreation_customdata": "2026-05-09 07:20:23.362788"
    },
    {
      "keyof_customdata": "logfile",
      "valueof_customdata": "2026050907202369fee03756652",
      "datecreation_customdata": "2026-05-09 07:20:23.362788"
    }
  ],
  "description": "",
  "external_id": "ART5A7044E5",
  "operator_id": "11",
  "operator_name": "ORANGE BURKINA",
  "response_code": "00",
  "response_text": "",
  "customer_details": {
    "email": "prenom.nom@example.com",
    "phone": "22676275726",
    "details": "",
    "lastname": "NOM",
    "firstname": "Prénom"
  }
}
```

## Champs principaux

<ResponseField name="date" type="string">
  Horodatage de l'événement au format `YYYY-MM-DD HH:MM:SS+TZ`.
</ResponseField>

<ResponseField name="response_code" type="string">
  Code de résultat. `"00"` = succès. Toute autre valeur indique une erreur — consultez `wiki` pour le détail.
</ResponseField>

<ResponseField name="status" type="string">
  Statut de la transaction : `"completed"`, `"pending"` ou `"notcompleted"`. Basez votre logique métier sur ce champ.
</ResponseField>

<ResponseField name="amount" type="integer">
  Montant de la transaction en XOF.
</ResponseField>

<ResponseField name="montant" type="integer">
  Identique à `amount`. Les deux champs coexistent dans toutes les réponses LigdiCash.
</ResponseField>

<ResponseField name="customer" type="string">
  Numéro de téléphone du payeur, avec indicatif pays, sans `+` ni espaces.
</ResponseField>

<ResponseField name="request_id" type="string">
  Identifiant unique de la requête généré par LigdiCash. Utilisez-le pour la déduplication lorsque `custom_data` est vide ou inaccessible.
</ResponseField>

<ResponseField name="external_id" type="string">
  Concaténation des valeurs de tous les champs de `custom_data` dont la clé contient `"id"`. Peut être fiable si vous n'avez qu'un seul champ avec `"id"` dans le nom — mais parsez `custom_data` directement pour un résultat garanti.
</ResponseField>

<ResponseField name="token" type="string">
  Toujours vide (`""`). Ce champ n'est pas utilisable pour la vérification — utilisez le token stocké à la création de la transaction.
</ResponseField>

<ResponseField name="operator_id" type="string">
  Identifiant de l'opérateur qui a traité le paiement (ex : `"11"` pour Orange Burkina).
</ResponseField>

<ResponseField name="operator_name" type="string">
  Nom de l'opérateur (ex : `"ORANGE BURKINA"`).
</ResponseField>

<ResponseField name="description" type="string">
  Description de la transaction. Peut être vide.
</ResponseField>

<ResponseField name="oreference" type="string">
  Référence opérateur. Peut être vide.
</ResponseField>

<ResponseField name="response_text" type="string">
  Libellé textuel du résultat. Peut être vide.
</ResponseField>

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

## Le tableau custom\_data

<ResponseField name="custom_data" type="array">
  Tableau des données personnalisées associées à la transaction. Contient vos champs marchands **plus** les champs ajoutés automatiquement par LigdiCash.

  <Expandable title="Structure d'un élément">
    <ResponseField name="keyof_customdata" type="string">
      Clé de la donnée.
    </ResponseField>

    <ResponseField name="valueof_customdata" type="string">
      Valeur de la donnée.
    </ResponseField>

    <ResponseField name="datecreation_customdata" type="string">
      Horodatage de création de la donnée.
    </ResponseField>
  </Expandable>
</ResponseField>

LigdiCash ajoute systématiquement deux entrées à votre `custom_data` :

| `keyof_customdata` | Origine   | Description                                 |
| ------------------ | --------- | ------------------------------------------- |
| `hash`             | LigdiCash | Hash de la transaction généré par LigdiCash |
| `logfile`          | LigdiCash | Référence de log interne LigdiCash          |

Filtrez toujours sur `keyof_customdata` pour extraire vos propres champs. Voir [Parser custom\_data](/api-paiement/callback/parser-custom-data).

## Les informations client

<ResponseField name="customer_details" type="object">
  Informations du payeur si disponibles.

  <Expandable title="Champs">
    <ResponseField name="firstname" type="string">Prénom.</ResponseField>
    <ResponseField name="lastname" type="string">Nom.</ResponseField>
    <ResponseField name="email" type="string">Adresse email.</ResponseField>
    <ResponseField name="phone" type="string">Numéro de téléphone.</ResponseField>
    <ResponseField name="details" type="string">Informations complémentaires. Généralement vide.</ResponseField>
  </Expandable>
</ResponseField>

## Pages associées

* [Sécurisation du callback](/api-paiement/callback/securisation)
* [Parser custom\_data](/api-paiement/callback/parser-custom-data)
* [Idempotence et déduplication](/api-paiement/callback/idempotence)


# Anatomie du payload — Payout
Source: https://developers.ligdicash.com/api-paiement/callback/payload-payout

Détail du payload reçu lors d'un callback payout : structure, champs et différences avec le payload payin.

Lors d'un payout (sortie d'argent vers un wallet client ou un compte mobile money), LigdiCash envoie deux requêtes POST à votre `callback_url` — une en `application/json`, une en `application/x-www-form-urlencoded`. Les deux contiennent les mêmes données. Cette page détaille la structure JSON et les différences avec le [payload payin](/api-paiement/callback/payload-payin).

## Exemple complet

```json theme={null}
{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZF9maW5hbmNlIjoiMTIzNTU4NDgxIiwic3RhcnRfZGF0ZSI6IjIwMjYtMDUtMTEgMTY6Mjc6MzUrMDAiLCJleHBpcnlfZGF0ZSI6MTc3ODYwMzI1NX0.FTaklFJy5DmovqVuwQz6avjNpJuzoh-XehziELBrh84",
  "response_text": "",
  "status": "completed",
  "custom_data": [],
  "operator_id": 12,
  "operator_name": "MOOV AFRICA BURKINA",
  "url": "https://monapp.com/api/callback/ligdicash",
  "url_method": "",
  "transaction_id": "502d36d2086249118198d06780b1c9fd",
  "external_id": "502d36d2086249118198d06780b1c9fd",
  "montant": "100",
  "amount": "100"
}
```

## Champs principaux

<ResponseField name="response_code" type="string">
  Code de résultat. `"00"` = succès. Toute autre valeur indique une erreur.
</ResponseField>

<ResponseField name="status" type="string">
  Statut du payout : `"completed"`, `"pending"` ou `"notcompleted"`. Basez votre logique métier sur ce champ — voir [Codes de réponse et statuts](/concepts/codes-reponse-statuts).
</ResponseField>

<ResponseField name="token" type="string">
  Jeton JWT lié à ce callback payout. **Ne vous y fiez pas** pour identifier la transaction — utilisez le token stocké à la création du payout pour appeler [Vérifier le statut](/api-paiement/payout/verifier-statut).
</ResponseField>

<ResponseField name="amount" type="string">
  Montant du payout en XOF, encodé en **chaîne de caractères** (ex : `"100"`).
</ResponseField>

<ResponseField name="montant" type="string">
  Identique à `amount`. Les deux champs coexistent dans toutes les réponses LigdiCash.
</ResponseField>

<ResponseField name="transaction_id" type="string">
  Identifiant racine du payout. Égal à l'`external_id` que vous avez fourni à la création — utilisez-le pour rapprocher le callback de votre transaction métier.
</ResponseField>

<ResponseField name="external_id" type="string">
  Identifiant fourni par le marchand à la création du payout. Reflète la valeur que vous avez passée dans le corps de la requête `/withdrawal/create` ou `/straight/payout`.
</ResponseField>

<ResponseField name="operator_id" type="integer">
  Identifiant numérique de l'opérateur destinataire du payout (ex : `12` pour Moov Africa Burkina).
</ResponseField>

<ResponseField name="operator_name" type="string">
  Nom de l'opérateur destinataire (ex : `"MOOV AFRICA BURKINA"`). Pour un payout vers wallet LigdiCash, ce champ est préfixé par `"LigdiCash "` (ex : `"LigdiCash ORANGE BURKINA"`).
</ResponseField>

<ResponseField name="url" type="string">
  URL de votre `callback_url` qui reçoit ce payload. LigdiCash y inscrit l'URL de destination — utile pour les diagnostics.
</ResponseField>

<ResponseField name="url_method" type="string">
  Méthode HTTP utilisée pour la livraison du callback. Généralement vide.
</ResponseField>

<ResponseField name="response_text" type="string">
  Libellé textuel du résultat. Vide en cas de succès.
</ResponseField>

<ResponseField name="custom_data" type="array">
  Données personnalisées du payout. Souvent vide (`[]`) — voir la section suivante. Si peuplé, suit la même structure que dans le payin : tableau d'objets `{ keyof_customdata, valueof_customdata, datecreation_customdata }`.
</ResponseField>

## Le champ custom\_data en payout

Contrairement au payin, le `custom_data` du payout est **souvent vide** (`[]`). Vous ne devez donc pas vous appuyer dessus pour rapprocher le callback de votre transaction métier — utilisez `transaction_id` ou `external_id` à la racine du payload.

<Note>
  Si vous avez fourni un `custom_data` à la création du payout, il sera renvoyé sous la forme d'un tableau peuplé d'objets `{ keyof_customdata, valueof_customdata, datecreation_customdata }`, exactement comme pour le payin. Voir [Parser custom\_data](/api-paiement/callback/parser-custom-data).
</Note>

## Différences avec le payload payin

| Champ                                                     | Payin                                         | Payout                     |
| --------------------------------------------------------- | --------------------------------------------- | -------------------------- |
| `token`                                                   | Toujours vide (`""`)                          | **Rempli** (JWT du payout) |
| `amount` / `montant`                                      | Entier (`4200`)                               | **Chaîne** (`"100"`)       |
| `operator_id`                                             | Chaîne (`"11"`)                               | **Entier** (`12`)          |
| `customer`                                                | Numéro du payeur                              | **Absent**                 |
| `customer_details`                                        | Renseigné (firstname, lastname, email, phone) | **Absent**                 |
| `custom_data`                                             | Tableau peuplé (vos champs + LigdiCash)       | Souvent vide (`[]`)        |
| `transaction_id` à la racine                              | Concaténation des `valueof_customdata`        | Égal à `external_id`       |
| `date`, `wiki`, `request_id`, `oreference`, `description` | Présents                                      | **Absents**                |
| `url`, `url_method`                                       | Absents                                       | **Présents**               |

<Warning>
  Le format des champs `amount`, `montant` et `operator_id` diffère entre payin et payout. Si vous parsez le payload avec un schéma typé, prévoyez ces différences ou caster les valeurs côté serveur.
</Warning>

## Statuts possibles

| `status`       | Signification               | Action recommandée                                                   |
| -------------- | --------------------------- | -------------------------------------------------------------------- |
| `completed`    | Payout finalisé avec succès | Confirmer côté métier, notifier l'utilisateur                        |
| `pending`      | Traitement en cours         | Patienter, attendre un nouveau callback ou interroger `confirm`      |
| `notcompleted` | Payout échoué               | Consulter la réponse `confirm` pour le détail, notifier le demandeur |

## Pages associées

* [Payload Payin](/api-paiement/callback/payload-payin) — anatomie complète du payload payin
* [Parser custom\_data](/api-paiement/callback/parser-custom-data) — gérer le tableau quand il est peuplé
* [Sécurisation du callback](/api-paiement/callback/securisation) — re-vérification avec `confirm`
* [Vérifier le statut payout](/api-paiement/payout/verifier-statut) — endpoint de re-vérification


# Sécuriser le callback
Source: https://developers.ligdicash.com/api-paiement/callback/securisation

Pourquoi ne jamais faire confiance au payload reçu, et comment re-vérifier chaque callback avec le token stocké à la création.

Votre URL de callback est une route POST publique. N'importe qui connaissant cette URL peut envoyer un faux payload — avec un `status: "completed"` et un montant de son choix. Si vous traitez ce payload sans vérification, vous livrez une commande ou déclenchez un payout sur la base d'un paiement qui n'a jamais eu lieu.

**La règle d'or : ne jamais agir sur le payload reçu. Toujours re-vérifier.**

## Le pattern de re-vérification

<Steps>
  <Step title="À la création — stocker le token">
    Lors de la création d'une transaction (payin ou payout), stockez le `token` retourné par l'API dans votre base de données, associé à votre `transaction_id`.

    ```json theme={null}
    // Réponse de création — à stocker
    {
      "response_code": "00",
      "token": "{INVOICE_TOKEN}"
    }
    ```
  </Step>

  <Step title="À la réception du callback — extraire l'identifiant">
    Recevez le callback. Extrayez votre `transaction_id` depuis le tableau `custom_data` en filtrant sur `keyof_customdata`.

    ```javascript theme={null}
    const entry = payload.custom_data?.find(
      (item) => item.keyof_customdata === "transaction_id"
    );
    const transactionId = entry?.valueof_customdata;
    ```
  </Step>

  <Step title="Retrouver le token stocké">
    Cherchez dans votre base de données le token associé à ce `transaction_id`. Si aucun enregistrement ne correspond, ignorez le callback — il est probablement frauduleux.

    ```javascript theme={null}
    const stored = await db.transactions.findOne({ transaction_id: transactionId });
    if (!stored) return; // callback non sollicité
    ```
  </Step>

  <Step title="Appeler l'endpoint confirm avec le token stocké">
    Appelez l'endpoint de vérification de LigdiCash avec le token que **vous** avez stocké — pas celui du callback (qui est toujours vide).

    ```javascript theme={null}
    // Pour un payin redirect
    const params = new URLSearchParams({ invoiceToken: stored.token });
    const verify = await fetch(
      `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm?${params}`,
      { headers: { Apikey: API_KEY, Authorization: `Bearer ${AUTH_TOKEN}` } }
    );
    const result = await verify.json();
    ```
  </Step>

  <Step title="Agir sur le résultat de confirm, pas sur le payload">
    Utilisez uniquement le `status` retourné par `confirm` pour décider de votre action.

    ```javascript theme={null}
    if (result.status === 'completed') {
      await db.orders.markAsPaid(transactionId);
    }
    ```
  </Step>
</Steps>

```mermaid theme={null}
flowchart TD
    A["Callback reçu — POST /callback_url"] --> B["Extraire transaction_id\ndepuis custom_data"]
    B --> C{transaction_id\ntrouvé en DB ?}
    C -->|Non| D["Ignorer\ncallback non sollicité"]
    C -->|Oui| E{Statut en DB ?}
    E -->|"completed / notcompleted"| F["Ignorer\ndoublon déjà traité"]
    E -->|pending| G["GET /confirm\navec le token stocké à la création"]
    G --> H{Statut retourné\npar confirm ?}
    H -->|completed| I["Confirmer la commande\nMettre à jour la DB"]
    H -->|notcompleted| J["Annuler la commande\nMettre à jour la DB"]
    H -->|pending| K["Ne rien faire\nAttendre le prochain callback"]
```

## Ce qu'il ne faut pas faire

```javascript theme={null}
// DANGEREUX — traitement direct du payload sans vérification
app.post('/callback', (req, res) => {
  const { status, amount, external_id } = req.body;

  if (status === 'completed') {
    // N'importe qui peut envoyer ce payload
    markOrderAsPaid(external_id, amount);
  }
});
```

```javascript theme={null}
// CORRECT — re-vérification systématique
app.post('/callback', async (req, res) => {
  const entry = req.body.custom_data?.find(
    (item) => item.keyof_customdata === 'transaction_id'
  );
  const transactionId = entry?.valueof_customdata;
  if (!transactionId) return res.sendStatus(400);

  const stored = await db.transactions.findOne({ transaction_id: transactionId });
  if (!stored) return res.sendStatus(404);

  const result = await confirmWithLigdicash(stored.token);

  if (result.status === 'completed') {
    await markOrderAsPaid(transactionId);
  }

  res.sendStatus(200);
});
```

## Pages associées

* [Payload Payin](/api-paiement/callback/payload-payin)
* [Parser custom\_data](/api-paiement/callback/parser-custom-data)
* [Exemples par framework](/api-paiement/callback/exemples-frameworks)


# 3D Secure
Source: https://developers.ligdicash.com/api-paiement/cartes-visa/3d-secure

Le 3D Secure est obligatoire pour tout paiement par carte Visa via LigdiCash — ce que c'est, comment ça fonctionne et que faire en cas d'échec.

Le 3D Secure (3DS) est un protocole d'authentification forte imposé par les réseaux bancaires pour les paiements en ligne. LigdiCash l'applique **obligatoirement** sur tous les paiements par carte Visa.

## Pourquoi le 3DS est obligatoire

Le 3D Secure protège à la fois le porteur de carte et le marchand contre la fraude. LigdiCash ne peut pas accepter un paiement par carte sans cette couche d'authentification. Si la carte du client n'a pas le 3DS activé, **la transaction sera refusée** — indépendamment de la validité du numéro, de la date d'expiration ou du CVV.

<Warning>
  La carte doit avoir le **3D Secure activé auprès de la banque émettrice** avant de pouvoir être utilisée. Si un client rencontre un échec, la première cause à vérifier est l'activation du 3DS sur sa carte.
</Warning>

## Comment activer le 3DS sur une carte

L'activation du 3D Secure est à la charge du porteur de carte, pas du marchand. Le client doit contacter sa banque pour :

1. Vérifier que sa carte supporte le 3D Secure.
2. Activer l'option si elle ne l'est pas encore (parfois via l'application bancaire, parfois sur demande au guichet).
3. S'assurer que son numéro de téléphone enregistré auprès de la banque est à jour (pour recevoir les codes SMS de validation).

## Ce que vit le client pendant le flux 3DS

Après avoir saisi ses informations de carte sur la page LigdiCash :

<Steps>
  <Step title="Déclenchement 3DS">
    LigdiCash soumet la transaction au réseau Visa, qui déclenche le processus 3DS auprès de la banque émettrice de la carte.
  </Step>

  <Step title="Authentification bancaire">
    Le client est redirigé vers la page d'authentification de sa banque. Selon la banque, cette authentification peut prendre plusieurs formes :

    * Code envoyé par SMS
    * Validation via l'application mobile bancaire
    * Code envoyé par email
    * Question secrète préenregistrée
  </Step>

  <Step title="Retour sur LigdiCash">
    Après validation réussie, le client revient automatiquement sur la page LigdiCash, qui finalise la transaction.
  </Step>

  <Step title="Retour sur votre site">
    Le client est redirigé vers votre `return_url` ou `cancel_url` selon le résultat.
  </Step>
</Steps>

## Que faire en cas d'échec 3DS

Si un client signale un échec lors du paiement par carte, voici les causes les plus fréquentes et les actions à recommander :

| Cause probable                       | Action recommandée pour le client                                     |
| ------------------------------------ | --------------------------------------------------------------------- |
| 3DS non activé sur la carte          | Contacter sa banque pour activer le 3DS                               |
| Code SMS non reçu                    | Vérifier le numéro enregistré auprès de la banque, redemander le code |
| Délai d'authentification dépassé     | Recommencer le paiement depuis le début                               |
| Carte non supportée par LigdiCash    | Essayer avec une autre carte Visa 3DS activée                         |
| Limite de paiement en ligne atteinte | Contacter sa banque pour relever la limite                            |

<Note>
  En tant que marchand, vous n'avez pas de visibilité directe sur la raison d'un échec 3DS. Le client doit résoudre le problème avec sa banque. Votre rôle est de lui proposer de réessayer ou de passer à un autre moyen de paiement (mobile money par exemple).
</Note>

## Côté marchand — aucune action requise

Le déclenchement et la gestion du 3DS sont entièrement pris en charge par LigdiCash. Vous n'avez pas à intégrer de SDK 3DS, à gérer des redirections bancaires, ni à modifier votre code existant. Un paiement Visa refusé pour cause de 3DS vous parvient avec un `status` à `notcompleted` dans la réponse `confirm` et dans le callback.

## Pages associées

* [Flux de paiement Visa](/api-paiement/cartes-visa/flux-paiement) — le déroulement complet du flux
* [Activer Visa sur votre projet](/api-paiement/cartes-visa/activation) — conditions contractuelles d'activation
* [Vérifier le statut](/api-paiement/payin-redirect/verifier-statut) — lire `status` après un paiement


# Activer Visa sur votre projet
Source: https://developers.ligdicash.com/api-paiement/cartes-visa/activation

Conditions contractuelles et démarches pour activer l'acceptation des paiements par carte Visa sur votre projet LigdiCash.

L'acceptation des paiements par carte Visa n'est pas activée par défaut sur un projet LigdiCash. Elle nécessite la signature d'un **contrat spécifique**, distinct du contrat d'accès à l'API mobile money.

## Prérequis contractuels

<Warning>
  Visa requiert un **contrat dédié** avec LigdiCash. Votre contrat d'accès à l'API mobile money ne couvre pas l'acceptation des paiements par carte. Vous devez initier une demande d'activation séparée.
</Warning>

Ce contrat additionnel implique des conditions propres au traitement des paiements par carte bancaire : conformité PCI-DSS, conditions tarifaires spécifiques, et engagement sur les délais de retrait applicables aux fonds Visa (jusqu'à 14 jours).

## Faire une demande d'activation

Contactez l'équipe LigdiCash pour initier la démarche :

* **Support technique** : [developper@ligdicash.com](mailto:developper@ligdicash.com)
* **Partner Manager** : consultez les [contacts par pays](/ressources/support#contacts-par-pays)

Précisez dans votre demande que vous souhaitez activer l'acceptation des **paiements par carte Visa** sur votre projet.

## Ce qui change sur votre intégration après activation

Une fois le contrat signé et l'activation confirmée par LigdiCash :

* La page de paiement avec redirection affichera une option de paiement par carte Visa en plus des opérateurs mobile money.
* Aucune modification technique n'est nécessaire côté marchand : vous utilisez le même endpoint de création de facture (`POST /pay/v01/redirect/checkout-invoice/create`) et le même mécanisme de callback.

<Note>
  Le paiement Visa est **uniquement disponible avec la méthode de redirection**. Si vous utilisez uniquement le payin sans redirection, vous ne pourrez pas proposer Visa à vos clients.
</Note>

## Délai de retrait des fonds Visa

Les fonds collectés via des paiements Visa sont soumis à des vérifications supplémentaires avant d'être disponibles au retrait. Ce délai peut aller jusqu'à **14 jours** à compter de la date du paiement.

Ce délai est documenté dans le contrat dédié Visa. Il est distinct des délais de retrait applicables aux fonds mobile money.

## Pages associées

* [Introduction Visa](/api-paiement/cartes-visa/introduction) — contraintes et vue d'ensemble
* [Flux de paiement Visa](/api-paiement/cartes-visa/flux-paiement) — comment se déroule un paiement après activation
* [Créer une facture](/api-paiement/payin-redirect/creer-facture) — l'endpoint de création, commun au mobile money et à Visa


# Flux de paiement Visa
Source: https://developers.ligdicash.com/api-paiement/cartes-visa/flux-paiement

Comment se déroule un paiement par carte Visa via LigdiCash — de la création de facture à la confirmation.

Un paiement Visa sur LigdiCash suit le **même flux technique qu'un payin avec redirection**. La différence est côté client : au lieu de choisir un opérateur mobile money et de saisir un numéro de téléphone, le client saisit ses informations de carte bancaire et valide via le 3D Secure.

<Note>
  Le flux Visa n'est pas disponible en mode sans redirection. La page de paiement hébergée par LigdiCash est obligatoire pour gérer la saisie sécurisée des informations de carte.
</Note>

## Vue d'ensemble du flux

<Steps>
  <Step title="Créer la facture">
    Votre backend appelle `POST /pay/v01/redirect/checkout-invoice/create` avec les paramètres habituels — c'est exactement le même endpoint que pour le mobile money.

    LigdiCash retourne un `token` et un `payment_url`.
  </Step>

  <Step title="Rediriger le client">
    Ouvrez `payment_url` dans le même onglet, un nouvel onglet, ou un popup. Le client arrive sur la page de paiement LigdiCash, qui affiche les méthodes disponibles sur votre compte — dont Visa si l'activation est en place.

    <Warning>
      L'iframe est bloqué pour ce flux. N'intégrez pas `payment_url` dans une iframe — le paiement ne fonctionnera pas. Consultez [Rediriger le client](/api-paiement/payin-redirect/rediriger-client) pour les méthodes d'ouverture supportées.
    </Warning>
  </Step>

  <Step title="Le client saisit ses informations de carte">
    Sur la page LigdiCash, le client sélectionne Visa et saisit :

    * Numéro de carte
    * Date d'expiration
    * CVV

    <Warning>
      La carte doit avoir le **3D Secure activé**. Si ce n'est pas le cas, le paiement sera refusé. Le client doit contacter sa banque pour activer cette option.
    </Warning>
  </Step>

  <Step title="Authentification 3D Secure">
    LigdiCash déclenche automatiquement le processus 3D Secure. Le client est redirigé vers la page d'authentification de sa banque (code SMS, application bancaire, etc.) pour confirmer la transaction.

    Consultez [3D Secure](/api-paiement/cartes-visa/3d-secure) pour le détail de cette étape.
  </Step>

  <Step title="Retour sur votre site">
    Après validation (ou échec), le client est redirigé vers votre `return_url` (succès ou annulation) ou `cancel_url`.

    Appelez `confirm` depuis votre backend avec le token stocké à la création pour vérifier le statut réel avant d'honorer la commande.
  </Step>

  <Step title="Callback">
    LigdiCash envoie un callback à votre `callback_url` dès que le statut est finalisé. Re-vérifiez toujours le statut avec `confirm` avant de déclencher votre logique métier.
  </Step>
</Steps>

## Côté marchand — aucune modification technique

Le flux Visa utilise exactement les mêmes appels API que le payin redirect mobile money :

| Étape              | Endpoint                                                               |
| ------------------ | ---------------------------------------------------------------------- |
| Créer la facture   | `POST /pay/v01/redirect/checkout-invoice/create`                       |
| Vérifier le statut | `GET /pay/v01/redirect/checkout-invoice/confirm/?invoiceToken={TOKEN}` |

Les headers, le body, et le format de réponse sont identiques. Visa apparaît automatiquement comme option de paiement sur la page LigdiCash si votre compte l'a activé.

## Côté client — expérience attendue

Le client voit sur la page LigdiCash une option « Carte Visa » en plus des opérateurs mobile money disponibles. Après saisie des données de carte, il est redirigé vers sa banque pour le 3D Secure, puis revient sur votre site.

L'ensemble du flux dure typiquement 1 à 2 minutes si le client a ses informations de carte à portée de main et que le 3D Secure se déroule normalement.

## Callback Visa

Le payload du callback est identique au callback d'un payin mobile money. Le champ `operator_name` indiquera `"VISA"`.

Consultez [Payload du callback payin](/api-paiement/callback/payload-payin) pour la structure complète.

## Pages associées

* [Créer une facture](/api-paiement/payin-redirect/creer-facture) — endpoint et paramètres complets
* [Rediriger le client](/api-paiement/payin-redirect/rediriger-client) — méthodes d'ouverture du lien de paiement
* [3D Secure](/api-paiement/cartes-visa/3d-secure) — détail de l'étape d'authentification
* [Vérifier le statut](/api-paiement/payin-redirect/verifier-statut) — appeler `confirm` après paiement
* [Callback — sécurisation](/api-paiement/callback/securisation) — re-vérification obligatoire


# Cartes Visa — Introduction
Source: https://developers.ligdicash.com/api-paiement/cartes-visa/introduction

Acceptez les paiements par carte Visa via LigdiCash — prérequis, contraintes et différences avec le mobile money.

LigdiCash permet d'accepter les paiements par carte Visa en plus du mobile money. Cette fonctionnalité est soumise à des conditions d'activation spécifiques et présente des contraintes techniques importantes à connaître avant d'intégrer.

## Contraintes essentielles

<Warning>
  Le paiement par carte Visa est **uniquement disponible avec la méthode de paiement avec redirection**. Il n'existe pas de flux Visa sans redirection — le client est obligatoirement redirigé vers la page de paiement hébergée par LigdiCash pour saisir ses informations de carte.
</Warning>

<Warning>
  **Le 3D Secure est obligatoire.** La carte utilisée par le client doit avoir le 3D Secure activé auprès de sa banque. Un paiement tenté avec une carte sans 3D Secure sera refusé. Consultez [3D Secure](/api-paiement/cartes-visa/3d-secure) pour les détails.
</Warning>

## Activation — contrat dédié requis

Le paiement par carte Visa ne s'active pas simplement depuis le dashboard. Il nécessite la **signature d'un contrat spécifique** avec LigdiCash, distinct du contrat d'accès à l'API mobile money. Consultez [Activer Visa sur votre projet](/api-paiement/cartes-visa/activation) pour les démarches.

## Délai de retrait des fonds

Les fonds collectés via des paiements Visa sont soumis à des **délais de retrait plus longs** que pour le mobile money. Des vérifications supplémentaires sont requises côté LigdiCash et ses partenaires bancaires. Ces délais peuvent aller de quelques jours jusqu'à **14 jours maximum**.

<Note>
  Ce délai est propre aux retraits depuis un compte marchand alimenté par des paiements Visa. Les paiements mobile money ne sont pas affectés.
</Note>

## Différences avec le mobile money

|                     | Mobile money                     | Carte Visa               |
| ------------------- | -------------------------------- | ------------------------ |
| Méthode de paiement | Redirect ou sans redirect        | **Redirect uniquement**  |
| 3D Secure           | Non applicable                   | **Obligatoire**          |
| Activation          | Incluse dans le contrat standard | **Contrat dédié requis** |
| Délai de retrait    | Standard                         | **Jusqu'à 14 jours**     |
| Devise              | XOF                              | XOF                      |

## Pages de cette section

<CardGroup>
  <Card title="Activer Visa" icon="file-signature" href="/api-paiement/cartes-visa/activation">
    Conditions contractuelles et démarches d'activation
  </Card>

  <Card title="Flux de paiement" icon="credit-card" href="/api-paiement/cartes-visa/flux-paiement">
    Comment se déroule un paiement Visa de bout en bout
  </Card>

  <Card title="3D Secure" icon="shield-check" href="/api-paiement/cartes-visa/3d-secure">
    Pourquoi le 3DS est obligatoire et ce que vit le client
  </Card>
</CardGroup>


# Créer une facture
Source: https://developers.ligdicash.com/api-paiement/payin-redirect/creer-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 type="string">
  La clé API de votre projet LigdiCash.
</ParamField>

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

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

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

## Body

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

  <Expandable title="Champs de commande">
    <ParamField type="object">
      Détails de la facture.

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

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

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

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

      <Expandable title="Champs de store">
        <ParamField type="string">Nom de votre boutique ou application, affiché sur la page de paiement.</ParamField>
        <ParamField type="string">URL de votre site.</ParamField>
      </Expandable>
    </ParamField>

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

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

    <ParamField 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`


# Intégration mobile native
Source: https://developers.ligdicash.com/api-paiement/payin-redirect/integration-mobile

Intégrer le payin avec redirection dans une app iOS, Android, React Native ou Flutter : WebView, détection du retour et confirmation du paiement.

Sur mobile, ouvrir l'URL de paiement dans le navigateur système fait quitter l'application et rend le retour utilisateur difficile à gérer. La WebView native maintient l'utilisateur dans l'app, permet de détecter automatiquement la fin du flux de paiement et de déclencher la vérification sans action supplémentaire de l'utilisateur.

## WebView native vs navigateur externe

| Approche                                    | Retour automatique         | UX                       | Recommandé |
| ------------------------------------------- | -------------------------- | ------------------------ | ---------- |
| WebView native                              | Oui — détection par URL    | Fluide, reste dans l'app | ✅          |
| SFSafariViewController / Chrome Custom Tabs | Partiel — deep link requis | Sort brièvement de l'app | Acceptable |
| Navigateur système                          | Non                        | Quitte l'app             | ✗          |

<Note>
  `SFSafariViewController` (iOS) et Chrome Custom Tabs (Android) ne permettent pas d'intercepter les redirections vers vos URLs de retour. Ils ne conviennent pas pour ce cas d'usage sans mettre en place un deep link.
</Note>

## React Native

**Dépendance :** [`react-native-webview`](https://github.com/react-native-webview/react-native-webview)

```bash theme={null}
npm install react-native-webview
# iOS uniquement
npx pod-install
```

```jsx React Native theme={null}
import { useState } from "react";
import { ActivityIndicator, StyleSheet, View } from "react-native";
import { WebView } from "react-native-webview";

export function PaiementWebView({ paymentUrl, onSuccess, onCancel, onError }) {
  const [loading, setLoading] = useState(true);

  const handleNavigationChange = (navState) => {
    const { url } = navState;

    if (url.startsWith("https://monapp.com/paiement/succes")) {
      onSuccess();
    } else if (url.startsWith("https://monapp.com/paiement/annule")) {
      onCancel();
    }
  };

  return (
    <View style={styles.container}>
      <WebView
        source={{ uri: paymentUrl }}
        onNavigationStateChange={handleNavigationChange}
        onLoadStart={() => setLoading(true)}
        onLoadEnd={() => setLoading(false)}
        onError={() => onError?.()}
        javaScriptEnabled
      />
      {loading && (
        <ActivityIndicator style={styles.loader} size="large" color="#0066cc" />
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  loader: { position: "absolute", alignSelf: "center", top: "50%" },
});
```

<Tip>
  Remplacez `https://monapp.com/paiement/succes` et `https://monapp.com/paiement/annule` par vos `return_url` et `cancel_url` exactes passées à la création de la facture.
</Tip>

## Flutter

**Dépendance :** [`webview_flutter`](https://pub.dev/packages/webview_flutter)

```yaml pubspec.yaml theme={null}
dependencies:
  webview_flutter: ^4.0.0
```

```dart Flutter theme={null}
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

class PaiementWebView extends StatefulWidget {
  final String paymentUrl;
  final VoidCallback onSuccess;
  final VoidCallback onCancel;

  const PaiementWebView({
    required this.paymentUrl,
    required this.onSuccess,
    required this.onCancel,
    super.key,
  });

  @override
  State<PaiementWebView> createState() => _PaiementWebViewState();
}

class _PaiementWebViewState extends State<PaiementWebView> {
  late final WebViewController _controller;
  bool _loading = true;

  @override
  void initState() {
    super.initState();
    _controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..setNavigationDelegate(NavigationDelegate(
        onPageStarted: (_) => setState(() => _loading = true),
        onPageFinished: (_) => setState(() => _loading = false),
        onNavigationRequest: (request) {
          final url = request.url;

          if (url.startsWith("https://monapp.com/paiement/succes")) {
            widget.onSuccess();
            return NavigationDecision.prevent;
          } else if (url.startsWith("https://monapp.com/paiement/annule")) {
            widget.onCancel();
            return NavigationDecision.prevent;
          }
          return NavigationDecision.navigate;
        },
      ))
      ..loadRequest(Uri.parse(widget.paymentUrl));
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        WebViewWidget(controller: _controller),
        if (_loading)
          const Center(child: CircularProgressIndicator()),
      ],
    );
  }
}
```

## iOS (Swift / WKWebView)

```swift iOS (Swift) theme={null}
import UIKit
import WebKit

class PaiementViewController: UIViewController, WKNavigationDelegate {

    private var webView: WKWebView!
    var paymentUrl: URL!
    var onSuccess: (() -> Void)?
    var onCancel: (() -> Void)?

    override func viewDidLoad() {
        super.viewDidLoad()

        webView = WKWebView(frame: view.bounds)
        webView.navigationDelegate = self
        webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(webView)

        webView.load(URLRequest(url: paymentUrl))
    }

    func webView(
        _ webView: WKWebView,
        decidePolicyFor navigationAction: WKNavigationAction,
        decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
    ) {
        let url = navigationAction.request.url?.absoluteString ?? ""

        if url.hasPrefix("https://monapp.com/paiement/succes") {
            decisionHandler(.cancel)
            dismiss(animated: true) { self.onSuccess?() }
        } else if url.hasPrefix("https://monapp.com/paiement/annule") {
            decisionHandler(.cancel)
            dismiss(animated: true) { self.onCancel?() }
        } else {
            decisionHandler(.allow)
        }
    }
}
```

**Présenter le ViewController :**

```swift iOS (Swift) theme={null}
let vc = PaiementViewController()
vc.paymentUrl = URL(string: data.response_text)!
vc.onSuccess = {
    // fermeture effectuée automatiquement, lancer la vérification
    self.verifierPaiement()
}
vc.onCancel = {
    self.afficherMessageAnnulation()
}
present(vc, animated: true)
```

## Android (Kotlin / WebView)

```kotlin Android (Kotlin) theme={null}
import android.os.Bundle
import android.webkit.WebResourceRequest
import android.webkit.WebView
import android.webkit.WebViewClient
import androidx.appcompat.app.AppCompatActivity

class PaiementActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val paymentUrl = intent.getStringExtra("payment_url") ?: return finish()

        val webView = WebView(this).apply {
            settings.javaScriptEnabled = true
            webViewClient = object : WebViewClient() {
                override fun shouldOverrideUrlLoading(
                    view: WebView,
                    request: WebResourceRequest
                ): Boolean {
                    val url = request.url.toString()

                    return when {
                        url.startsWith("https://monapp.com/paiement/succes") -> {
                            setResult(RESULT_OK)
                            finish()
                            true
                        }
                        url.startsWith("https://monapp.com/paiement/annule") -> {
                            setResult(RESULT_CANCELED)
                            finish()
                            true
                        }
                        else -> false
                    }
                }
            }
            loadUrl(paymentUrl)
        }

        setContentView(webView)
    }
}
```

**Démarrer l'Activity et récupérer le résultat :**

```kotlin Android (Kotlin) theme={null}
val launcher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    when (result.resultCode) {
        Activity.RESULT_OK -> verifierPaiement()
        Activity.RESULT_CANCELED -> afficherMessageAnnulation()
    }
}

val intent = Intent(this, PaiementActivity::class.java).apply {
    putExtra("payment_url", data.response_text)
}
launcher.launch(intent)
```

N'oubliez pas de déclarer `PaiementActivity` dans votre `AndroidManifest.xml` :

```xml AndroidManifest.xml theme={null}
<activity android:name=".PaiementActivity" />
```

## Après la détection du retour

Le flux est identique quelle que soit la plateforme :

<Steps>
  <Step title="Fermer la WebView">
    Dépiler ou dismisser le composant WebView pour revenir à l'écran précédent.
  </Step>

  <Step title="Afficher un écran de vérification">
    Montrez un indicateur de chargement — « Vérification du paiement en cours… » — le temps d'interroger votre backend.
  </Step>

  <Step title="Appeler votre backend">
    Votre backend appelle l'endpoint `confirm` avec le token stocké à la création de la facture.
  </Step>

  <Step title="Afficher le résultat">
    Selon le `status` retourné : confirmez la commande (`completed`), informez l'utilisateur (`notcompleted`) ou invitez-le à patienter (`pending`).
  </Step>
</Steps>

<Warning>
  La détection de `return_url` est un signal d'interface, pas une preuve de paiement. Un utilisateur peut naviguer manuellement vers cette URL. Confirmez toujours le paiement côté serveur avant d'honorer la commande.
</Warning>

## Pages associées

* [Rediriger le client](/api-paiement/payin-redirect/rediriger-client) — pattern popup web et vue d'ensemble des modes d'ouverture
* [Vérifier le statut](/api-paiement/payin-redirect/verifier-statut) — appeler `confirm` après la redirection
* [Pièges courants](/api-paiement/payin-redirect/pieges-courants) — iframe bloqué et autres erreurs fréquentes


# Payin avec redirection
Source: https://developers.ligdicash.com/api-paiement/payin-redirect/introduction

Le client est redirigé vers la page de paiement LigdiCash. La méthode la plus simple à intégrer, compatible avec tous les opérateurs supportés.

Le payin avec redirection est la méthode d'intégration la plus rapide. Vous créez une facture via l'API, récupérez un lien de paiement, et redirigez votre client vers la page hébergée par LigdiCash. Le client choisit son opérateur, effectue son paiement, et est renvoyé vers votre site. Vous n'avez pas à gérer l'interface de paiement.

Cette méthode fonctionne aussi bien sur le web que dans les **applications mobiles natives** : le lien de paiement s'ouvre dans une WebView, et vous détectez le retour du client en écoutant les changements d'URL.

## Comment ça fonctionne

<Steps>
  <Step title="Créer la facture">
    Vous appelez `POST /pay/v01/redirect/checkout-invoice/create` avec les détails de la commande. LigdiCash vous retourne un `token` et un lien de paiement dans `response_text`.
  </Step>

  <Step title="Rediriger le client">
    Vous ouvrez le lien de paiement dans le même onglet, un nouvel onglet ou un popup. Le client arrive sur la page de paiement LigdiCash où il choisit son opérateur mobile money.
  </Step>

  <Step title="Le client paie">
    Le client saisit son numéro et valide le paiement selon les instructions de son opérateur. LigdiCash gère entièrement cette étape.
  </Step>

  <Step title="Notification et redirection">
    LigdiCash envoie un callback à votre `callback_url` et redirige le client vers votre `return_url` (succès) ou `cancel_url` (annulation).
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    actor Client
    participant Frontend as Votre frontend
    participant Backend as Votre backend
    participant LC as LigdiCash

    Client->>Frontend: Déclenche un paiement
    Frontend->>Backend: POST /api/paiement/initier
    Backend->>LC: POST /checkout-invoice/create
    LC-->>Backend: token + pay_url
    Backend->>Backend: Stocke le token en DB
    Backend-->>Frontend: pay_url
    Frontend->>Client: Ouvre pay_url

    Note over Client,LC: Le client choisit son opérateur et paie sur la page LigdiCash

    par Simultanément
        LC-->>Client: Redirige vers return_url
    and
        LC->>Backend: POST /callback_url
    end
    Backend->>LC: GET /confirm/?invoiceToken={token_stocké}
    LC-->>Backend: status
    Backend->>Backend: Met à jour la commande
```

## Contraintes importantes

<Warning>
  L'iframe est bloqué par LigdiCash. Le lien de paiement doit s'ouvrir dans le même onglet, un nouvel onglet, un popup, ou une WebView native sur mobile — jamais dans une iframe.
</Warning>

<Warning>
  Le champ `customer` doit rester vide (`""`). Si vous y renseignez un numéro de téléphone, LigdiCash filtre la page de paiement pour n'afficher que les opérateurs correspondant à ce numéro, masquant les autres.
</Warning>

## Dans cette section

<CardGroup>
  <Card title="Créer une facture" icon="file-invoice" href="/api-paiement/payin-redirect/creer-facture">
    Paramètres, payload complet et réponse de l'endpoint de création
  </Card>

  <Card title="Rediriger le client" icon="arrow-up-right" href="/api-paiement/payin-redirect/rediriger-client">
    Ouvrir le lien de paiement : même onglet, popup, WebView
  </Card>

  <Card title="Vérifier le statut" icon="circle-check" href="/api-paiement/payin-redirect/verifier-statut">
    Appeler l'endpoint confirm avec le token de création
  </Card>

  <Card title="Intégration mobile" icon="mobile" href="/api-paiement/payin-redirect/integration-mobile">
    Ouvrir le lien dans une WebView native et détecter le retour
  </Card>

  <Card title="Pièges courants" icon="triangle-exclamation" href="/api-paiement/payin-redirect/pieges-courants">
    Iframe, customer vide, popup bloqué — les erreurs fréquentes
  </Card>
</CardGroup>


# Pièges courants — payin avec redirection
Source: https://developers.ligdicash.com/api-paiement/payin-redirect/pieges-courants

Les erreurs classiques à éviter avec le payin redirect LigdiCash : iframe bloqué, customer non vide, popup bloqué, validation côté client, et plus.

Page de référence recensant les erreurs les plus fréquentes rencontrées lors de l'intégration du payin avec redirection. Chaque piège décrit le symptôme observé, la cause et la correction à appliquer.

<AccordionGroup>
  <Accordion title="customer non vide — opérateurs masqués sur la page de paiement">
    **Symptôme** : la page de paiement LigdiCash n'affiche qu'un seul opérateur, ou aucun, alors que plusieurs sont disponibles dans votre région.

    **Cause** : si le champ `customer` contient un numéro de téléphone, LigdiCash filtre la page pour n'afficher que les opérateurs compatibles avec ce numéro. Les autres opérateurs sont masqués.

    **Correction** : toujours envoyer `customer: ""` dans la requête de création de facture.

    ```json theme={null}
    {
      "commande": {
        "invoice": {
          "customer": "",
          ...
        }
      }
    }
    ```

    <Note>
      Les champs `customer_firstname`, `customer_lastname` et `customer_email` peuvent être renseignés sans impact sur l'affichage des opérateurs. Seul `customer` (le numéro de téléphone) est concerné.
    </Note>
  </Accordion>

  <Accordion title="Iframe bloqué — page blanche ou erreur console">
    **Symptôme** : l'iframe reste vide, ou la console du navigateur affiche une erreur du type `Refused to display … in a frame because it set 'X-Frame-Options' to 'SAMEORIGIN'`.

    **Cause** : LigdiCash bloque délibérément le chargement de sa page de paiement dans un `<iframe>`. Il s'agit d'une mesure de sécurité contre le clickjacking, pas d'un bug.

    **Correction** : ouvrir l'URL de paiement dans un contexte de navigation réel.

    | Mode          | Implémentation                          |
    | ------------- | --------------------------------------- |
    | Même onglet   | `window.location.href = url`            |
    | Nouvel onglet | `window.open(url, '_blank')`            |
    | Popup         | Pattern `about:blank` (voir ci-dessous) |
    | Mobile natif  | WebView native iOS / Android            |

    Consultez [Rediriger le client](/api-paiement/payin-redirect/rediriger-client) pour les implémentations complètes.
  </Accordion>

  <Accordion title="Popup bloqué par le navigateur — window.open() retourne null">
    **Symptôme** : `window.open()` retourne `null` et rien ne s'ouvre. Aucune erreur visible pour l'utilisateur.

    **Cause** : les navigateurs bloquent les appels à `window.open()` qui ne sont pas directement déclenchés par un geste utilisateur. Un appel effectué après un `await fetch(...)` est considéré comme asynchrone et bloqué.

    **Correction** : ouvrir `about:blank` de manière synchrone au clic, puis naviguer vers l'URL une fois la réponse API reçue.

    ```javascript JavaScript theme={null}
    element.addEventListener("click", async () => {
      // Synchrone — avant tout await
      const popup = window.open("about:blank", "paiement", "width=500,height=700");

      const data = await creerFacture();

      if (data.response_code === "00") {
        popup.location.href = data.response_text;
      } else {
        popup.close();
      }
    });
    ```

    Consultez [Rediriger le client](/api-paiement/payin-redirect/rediriger-client) pour le pattern complet.
  </Accordion>

  <Accordion title="Valider le paiement sur la base de return_url ou cancel_url seulement">
    **Symptôme** : des commandes sont honorées sans paiement réel, ou l'état de la commande est incorrect après annulation.

    **Cause** : `return_url` et `cancel_url` sont de simples redirections navigateur. N'importe qui connaissant l'URL peut y accéder directement — elles ne constituent pas une preuve de statut de paiement.

    **Correction** : dans les deux cas (`return_url` et `cancel_url`), toujours vérifier le statut réel de la transaction en appelant `confirm` côté serveur avant de prendre toute décision métier.

    ```javascript JavaScript theme={null}
    // Que l'on arrive via return_url ou cancel_url
    const confirmation = await appellerBackend("/verifier-paiement", { token });

    if (confirmation.status === "completed") {
      afficherSucces();
    } else {
      afficherEchec();
    }
    ```

    <Warning>
      Ne jamais déduire le statut d'un paiement depuis l'URL de redirection. Le seul statut fiable est celui retourné par l'endpoint `confirm`.
    </Warning>
  </Accordion>

  <Accordion title="Utiliser le token du callback pour appeler confirm">
    **Symptôme** : la réconciliation avec votre commande échoue, ou vous confirmez la mauvaise transaction.

    **Cause** : le `token` présent dans le payload du callback est différent du token retourné à la création de la facture. Les deux permettent d'appeler `confirm`, mais seul le token de création permet de relier la réponse à votre commande côté marchand.

    **Correction** : stocker le token retourné par l'endpoint `create` en base de données dès la création de la facture, et le préférer pour appeler `confirm`.

    ```javascript JavaScript theme={null}
    // À la création
    const { token, response_text } = await creerFacture(commande);
    await db.save({ orderId, token, paymentUrl: response_text });

    // Dans le handler callback ou après return_url
    const { token } = await db.findByOrderId(orderId);
    const confirmation = await confirmerPaiement(token);
    ```

    Consultez [Le pattern transaction\_id](/concepts/transaction-id-pattern) pour la stratégie de réconciliation recommandée.
  </Accordion>

  <Accordion title="cancel_url et return_url inversées">
    **Symptôme** : l'utilisateur atterrit sur la page de succès après avoir annulé, ou sur la page d'annulation après un paiement réussi.

    **Cause** : les deux champs sont souvent confondus. L'ancienne documentation LigdiCash les avait d'ailleurs inversés dans ses exemples.

    **Correction** :

    * `return_url` → URL vers laquelle LigdiCash redirige après un **paiement réussi**
    * `cancel_url` → URL vers laquelle LigdiCash redirige après une **annulation**

    ```json theme={null}
    {
      "actions": {
        "return_url": "https://monapp.com/paiement/succes",
        "cancel_url": "https://monapp.com/paiement/annule",
        "callback_url": "https://monapp.com/api/callback/ligdicash"
      }
    }
    ```

    <Warning>
      Quelle que soit l'URL d'atterrissage, vérifiez toujours le statut réel avec `confirm` côté serveur avant d'afficher un résultat définitif à l'utilisateur.
    </Warning>
  </Accordion>
</AccordionGroup>

## Pages associées

* [Rediriger le client](/api-paiement/payin-redirect/rediriger-client) — patterns d'ouverture et popup anti-bloqueur
* [Vérifier le statut](/api-paiement/payin-redirect/verifier-statut) — appeler `confirm` correctement
* [Callback — sécurisation](/api-paiement/callback/securisation) — re-vérification et protection du handler
* [Le pattern transaction\_id](/concepts/transaction-id-pattern) — réconciliation côté marchand


# Rediriger le client vers la page de paiement
Source: https://developers.ligdicash.com/api-paiement/payin-redirect/rediriger-client

Comment ouvrir le lien de paiement LigdiCash : même onglet, nouvel onglet, popup ou WebView native. Contraintes et patterns recommandés.

Après la création de la facture, le champ `response_text` de la réponse contient l'URL de la page de paiement LigdiCash. C'est cette URL que vous devez ouvrir pour que le client puisse choisir son opérateur et finaliser le paiement. Le mode d'ouverture dépend de votre contexte : application web, mobile natif ou hybride.

## L'iframe est bloqué

<Warning>
  LigdiCash bloque le chargement de sa page de paiement dans un `<iframe>`. N'intégrez jamais l'URL dans une iframe — la page ne s'affichera pas.

  Ouvrez toujours le lien dans un contexte de navigation réel : même onglet, nouvel onglet, popup ou WebView native.
</Warning>

Ce blocage est appliqué côté serveur via les en-têtes `X-Frame-Options` et `Content-Security-Policy`. Il ne s'agit pas d'un bug — c'est une mesure de sécurité délibérée contre le clickjacking.

## Les 4 modes d'ouverture

| Mode           | Contexte recommandé                                | Implémentation                          |
| -------------- | -------------------------------------------------- | --------------------------------------- |
| Même onglet    | Web — parcours linéaire sans état à conserver      | `window.location.href = url`            |
| Nouvel onglet  | Web — l'utilisateur garde la page courante ouverte | `window.open(url, '_blank')`            |
| Popup          | Web — UX modale, retour automatique sur la page    | Pattern anti-bloqueur (voir ci-dessous) |
| WebView native | iOS / Android — application mobile native          | Détecter les URLs de retour pour fermer |

## Pattern popup (web)

Le déclenchement d'un `window.open()` après une requête réseau est systématiquement bloqué par les navigateurs modernes : il n'est pas considéré comme une action directe de l'utilisateur.

**La solution en deux étapes :**

1. Ouvrir `about:blank` **de manière synchrone** au clic, avant tout `await`
2. Naviguer vers l'URL de paiement **après** avoir reçu la réponse API

```javascript JavaScript theme={null}
async function lancerPaiement(commande) {
  // Étape 1 — ouvrir le popup immédiatement au clic (synchrone)
  const popup = window.open("about:blank", "paiement-ligdicash", "width=500,height=700");

  try {
    // Étape 2 — créer la facture
    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),
      }
    );

    const data = await response.json();

    if (data.response_code === "00") {
      // Étape 3 — naviguer dans le popup déjà ouvert
      popup.location.href = data.response_text;
    } else {
      popup.close();
      console.error("Échec création facture :", data.response_text);
    }
  } catch (err) {
    popup.close();
    throw err;
  }
}
```

<Tip>
  Ce pattern fonctionne sur tous les navigateurs modernes (Chrome, Firefox, Safari, Edge). La clé est que `window.open()` soit appelé dans le même fil d'exécution synchrone que le gestionnaire de clic.
</Tip>

## Pattern WebView (mobile natif)

Sur iOS et Android, ouvrez l'URL de paiement dans une **WebView native** plutôt que dans le navigateur système. Cela vous permet de détecter la fin du flux et de fermer la WebView automatiquement.

**Principe :** interceptez chaque navigation dans la WebView et comparez l'URL avec votre `return_url` et `cancel_url`.

<CodeGroup>
  ```jsx React Native theme={null}
  import { WebView } from "react-native-webview";

  export function PaiementWebView({ paymentUrl, onSuccess, onCancel }) {
    const handleNavigationChange = (navState) => {
      const { url } = navState;

      if (url.startsWith("https://monapp.com/paiement/succes")) {
        onSuccess(); // toujours confirmer côté serveur ensuite
      } else if (url.startsWith("https://monapp.com/paiement/annule")) {
        onCancel();
      }
    };

    return (
      <WebView
        source={{ uri: paymentUrl }}
        onNavigationStateChange={handleNavigationChange}
      />
    );
  }
  ```

  ```dart Flutter theme={null}
  import 'package:webview_flutter/webview_flutter.dart';

  class PaiementWebView extends StatefulWidget {
    final String paymentUrl;
    final VoidCallback onSuccess;
    final VoidCallback onCancel;

    const PaiementWebView({
      required this.paymentUrl,
      required this.onSuccess,
      required this.onCancel,
      super.key,
    });

    @override
    State<PaiementWebView> createState() => _PaiementWebViewState();
  }

  class _PaiementWebViewState extends State<PaiementWebView> {
    late final WebViewController _controller;

    @override
    void initState() {
      super.initState();
      _controller = WebViewController()
        ..setNavigationDelegate(NavigationDelegate(
          onNavigationRequest: (request) {
            final url = request.url;

            if (url.startsWith("https://monapp.com/paiement/succes")) {
              widget.onSuccess(); // toujours confirmer côté serveur ensuite
              return NavigationDecision.prevent;
            } else if (url.startsWith("https://monapp.com/paiement/annule")) {
              widget.onCancel();
              return NavigationDecision.prevent;
            }
            return NavigationDecision.navigate;
          },
        ))
        ..loadRequest(Uri.parse(widget.paymentUrl));
    }

    @override
    Widget build(BuildContext context) {
      return WebViewWidget(controller: _controller);
    }
  }
  ```

  ```swift iOS (Swift) theme={null}
  func webView(_ webView: WKWebView,
               decidePolicyFor action: WKNavigationAction,
               decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {

      let url = action.request.url?.absoluteString ?? ""

      if url.hasPrefix("https://monapp.com/paiement/succes") {
          decisionHandler(.cancel)
          dismissWebView()
          verifierStatutPaiement() // toujours confirmer côté serveur
      } else if url.hasPrefix("https://monapp.com/paiement/annule") {
          decisionHandler(.cancel)
          dismissWebView()
      } else {
          decisionHandler(.allow)
      }
  }
  ```

  ```kotlin Android (Kotlin) theme={null}
  webView.webViewClient = object : WebViewClient() {
      override fun shouldOverrideUrlLoading(
          view: WebView,
          request: WebResourceRequest
      ): Boolean {
          val url = request.url.toString()

          return when {
              url.startsWith("https://monapp.com/paiement/succes") -> {
                  dismissWebView()
                  verifierStatutPaiement() // toujours confirmer côté serveur
                  true
              }
              url.startsWith("https://monapp.com/paiement/annule") -> {
                  dismissWebView()
                  true
              }
              else -> false
          }
      }
  }
  ```
</CodeGroup>

<Note>
  Pour une implémentation complète incluant React Native et Flutter, consultez [Intégration mobile](/api-paiement/payin-redirect/integration-mobile).
</Note>

## Détecter le retour utilisateur

Quand LigdiCash redirige le client vers votre `return_url` ou `cancel_url`, cela indique que le flux de paiement côté LigdiCash est terminé. Ce n'est pas une preuve de succès du paiement.

<Warning>
  Ne considérez jamais un paiement comme validé sur la seule base de la redirection vers `return_url`. Un client peut modifier l'URL manuellement ou la redirection peut survenir suite à un timeout.

  Vérifiez systématiquement le statut via l'endpoint [confirm](/api-paiement/payin-redirect/verifier-statut) ou attendez la notification du [callback](/api-paiement/callback/introduction).
</Warning>

**Comportement recommandé à la réception de `return_url` :**

1. Afficher un écran intermédiaire « Vérification du paiement en cours… »
2. Appeler votre backend, qui appelle `confirm` avec le token stocké à la création
3. Afficher le résultat définitif (succès / échec / en attente)

## Pages associées

* [Créer une facture](/api-paiement/payin-redirect/creer-facture) — obtenir l'URL de paiement
* [Vérifier le statut](/api-paiement/payin-redirect/verifier-statut) — confirmer le paiement après redirection
* [Pièges courants](/api-paiement/payin-redirect/pieges-courants) — iframe, customer vide et autres erreurs fréquentes
* [Intégration mobile](/api-paiement/payin-redirect/integration-mobile) — React Native, Flutter, iOS, Android


# Vérifier le statut d'une transaction
Source: https://developers.ligdicash.com/api-paiement/payin-redirect/verifier-statut

Endpoint GET /pay/v01/redirect/checkout-invoice/confirm — comment vérifier qu'une facture a bien été payée après redirection ou callback.

L'endpoint `confirm` permet de vérifier le statut d'une facture à partir du `token` obtenu à la création. Appelez-le depuis votre **backend** — après la redirection vers `return_url`, ou depuis votre handler de callback avant d'honorer la commande.

```
GET https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm
```

## Headers

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

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

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

## Paramètres

<ParamField type="string">
  Le token retourné par l'endpoint `create` au moment de la création de la facture.
</ParamField>

<Warning>
  Le `token` reçu dans le payload du callback est **différent** du token de création. Les deux permettent d'appeler `confirm`, mais seul le token de création vous permet de faire la réconciliation avec votre commande côté marchand.
</Warning>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken={TOKEN}" \
    -H "Apikey: {API_KEY}" \
    -H "Authorization: Bearer {API_TOKEN}" \
    -H "Accept: application/json"
  ```

  ```javascript Node.js theme={null}
  const token = "eyJ0eXAiOiJKV1Qi..."; // token stocké à la création

  const response = await fetch(
    `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=${token}`,
    {
      method: "GET",
      headers: {
        Apikey: process.env.LIGDICASH_API_KEY,
        Authorization: `Bearer ${process.env.LIGDICASH_API_TOKEN}`,
        Accept: "application/json",
      },
    }
  );

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

  ```php PHP theme={null}
  $token = "eyJ0eXAiOiJKV1Qi..."; // token stocké à la création

  $ch = curl_init(
    "https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=" . urlencode($token)
  );
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Apikey: " . $_ENV["LIGDICASH_API_KEY"],
    "Authorization: Bearer " . $_ENV["LIGDICASH_API_TOKEN"],
    "Accept: application/json",
  ]);

  $data = json_decode(curl_exec($ch), true);
  curl_close($ch);
  ```
</CodeGroup>

## Champs de réponse

<ResponseField name="response_code" type="string">
  `"00"` si l'appel API a abouti, `"01"` en cas d'erreur technique. Ce champ indique le succès de la requête `confirm`, pas le résultat du paiement — utilisez `status` pour cela.
</ResponseField>

<ResponseField name="status" type="string">
  Statut du paiement. Voir le tableau ci-dessous.
</ResponseField>

<ResponseField name="token" type="string">
  Peut être vide dans la réponse `confirm`.
</ResponseField>

<ResponseField name="response_text" type="string">
  Message complémentaire ou sous-code d'erreur au format `Echec (CodeXX)`. Consulter `wiki` pour la description. Vide si aucune erreur.
</ResponseField>

<ResponseField name="description" type="string">
  Description libre de la transaction. Peut être vide.
</ResponseField>

<ResponseField name="operator_id" type="string">
  Identifiant numérique de l'opérateur utilisé pour le paiement. Exemple : `"14"` pour Moov CI. Vide si le statut est `pending`.
</ResponseField>

<ResponseField name="operator_name" type="string">
  Nom de l'opérateur. Exemple : `"MOOV CI"`. Vide si le statut est `pending`.
</ResponseField>

<ResponseField name="customer" type="string | null">
  Numéro de téléphone du payeur au format `226XXXXXXXXX`. Peut être `null` si le paiement est encore en attente.
</ResponseField>

<ResponseField name="montant" type="integer">
  Montant de la transaction en XOF.
</ResponseField>

<ResponseField name="amount" type="integer">
  Identique à `montant`. Les deux champs sont toujours présents et ont la même valeur.
</ResponseField>

<ResponseField name="date" type="string">
  Date et heure de la transaction au format `YYYY-MM-DD HH:MM:SS+TZ`. Exemple : `"2026-04-15 11:19:28+00"`.
</ResponseField>

<ResponseField name="external_id" type="string">
  Concaténation des `valueof_customdata` dont la clé (`keyof_customdata`) contient `"id"`, séparés par `;`. Correspond à la valeur de votre `transaction_id` si vous suivez le pattern recommandé.
</ResponseField>

<ResponseField name="oreference" type="string">
  Référence opérateur. Peut être vide.
</ResponseField>

<ResponseField name="request_id" type="string">
  Identifiant unique de la requête côté LigdiCash. Utile pour le support.
</ResponseField>

<ResponseField name="custom_data" type="array">
  Vos métadonnées telles que transmises à la création, enrichies par LigdiCash (qui y ajoute notamment `logfile`). Chaque entrée contient :

  <Expandable title="Champs d'une entrée custom_data">
    <ResponseField name="keyof_customdata" type="string">La clé. Exemple : `"transaction_id"`. LigdiCash y ajoute ses propres entrées (`logfile`).</ResponseField>
    <ResponseField name="valueof_customdata" type="string">La valeur associée.</ResponseField>
    <ResponseField name="datecreation_customdata" type="string">Date de création de l'entrée au format `YYYY-MM-DD HH:MM:SS.microseconds`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customer_details" type="object">
  Informations du client saisies lors du paiement.

  <Expandable title="Champs de customer_details">
    <ResponseField name="firstname" type="string">Prénom.</ResponseField>
    <ResponseField name="lastname" type="string">Nom.</ResponseField>
    <ResponseField name="email" type="string">Email. Peut être vide.</ResponseField>
    <ResponseField name="phone" type="string">Numéro de téléphone. Peut être vide si statut `pending`.</ResponseField>
    <ResponseField name="details" type="string">Informations complémentaires. Peut être vide.</ResponseField>
  </Expandable>
</ResponseField>

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

## Valeurs de `status`

| `status`       | Signification                          | Action recommandée                         |
| -------------- | -------------------------------------- | ------------------------------------------ |
| `completed`    | Paiement confirmé                      | Honorer la commande                        |
| `pending`      | En attente de confirmation opérateur   | Patienter, recheck ou attendre le callback |
| `notcompleted` | Paiement non abouti (annulé ou échoué) | Proposer de réessayer                      |

## Exemple de réponse

<CodeGroup>
  ```json Succès (completed) theme={null}
  {
    "response_code": "00",
    "token": "",
    "response_text": "",
    "description": "",
    "custom_data": [
      {
        "keyof_customdata": "transaction_id",
        "valueof_customdata": "BPBF-1776251968907",
        "datecreation_customdata": "2026-04-15 11:19:28.977757"
      },
      {
        "keyof_customdata": "logfile",
        "valueof_customdata": "2026041511192869df7440ed917",
        "datecreation_customdata": "2026-04-15 11:19:28.977757"
      }
    ],
    "status": "completed",
    "operator_id": "14",
    "operator_name": "MOOV CI",
    "customer": "2250171584035",
    "wiki": "https://client.ligdicash.com/wiki/confirmInvoice",
    "montant": 100,
    "amount": 100,
    "date": "2026-04-15 11:19:28+00",
    "external_id": "BPBF-1776251968907",
    "oreference": "",
    "customer_details": {
      "firstname": "ClémenceIlaria",
      "lastname": "Ouedraogo",
      "email": "clemenceilaria369@gmail.com",
      "phone": "2250171584035",
      "details": ""
    },
    "request_id": "P2771491712026"
  }
  ```

  ```json En attente (pending) theme={null}
  {
    "response_code": "00",
    "token": "",
    "response_text": "",
    "description": "",
    "custom_data": [
      {
        "keyof_customdata": "transaction_id",
        "valueof_customdata": "BPBF-1776876662551",
        "datecreation_customdata": "2026-04-22 16:51:02.660483"
      },
      {
        "keyof_customdata": "logfile",
        "valueof_customdata": "2026042216510269e8fc76a0292",
        "datecreation_customdata": "2026-04-22 16:51:02.660483"
      }
    ],
    "status": "pending",
    "operator_id": "",
    "operator_name": "",
    "customer": null,
    "wiki": "https://client.ligdicash.com/wiki/confirmInvoice",
    "montant": 100,
    "amount": 100,
    "date": "2026-04-22 16:51:02+00",
    "external_id": "BPBF-1776876662551",
    "oreference": "",
    "customer_details": {
      "firstname": "Ousmane",
      "lastname": "Konaté",
      "email": "",
      "phone": "",
      "details": ""
    },
    "request_id": "P2773475652026"
  }
  ```

  ```json Non abouti (notcompleted) theme={null}
  {
    "response_code": "00",
    "token": "",
    "response_text": "",
    "description": "",
    "custom_data": [
      {
        "keyof_customdata": "transaction_id",
        "valueof_customdata": "BPBF-1776876662551",
        "datecreation_customdata": "2026-04-22 16:51:02.660483"
      }
    ],
    "status": "notcompleted",
    "operator_id": "",
    "operator_name": "",
    "customer": null,
    "wiki": "https://client.ligdicash.com/wiki/confirmInvoice",
    "montant": 100,
    "amount": 100,
    "date": "2026-04-22 16:51:02+00",
    "external_id": "BPBF-1776876662551",
    "oreference": "",
    "customer_details": {
      "firstname": "",
      "lastname": "",
      "email": "",
      "phone": "",
      "details": ""
    },
    "request_id": "P2773475652026"
  }
  ```

  ```json Erreur API theme={null}
  {
    "response_code": "01",
    "token": "",
    "response_text": "Echec (Code01)",
    "description": "",
    "custom_data": [],
    "status": "",
    "operator_id": "",
    "operator_name": "",
    "customer": null,
    "wiki": "https://client.ligdicash.com/wiki/confirmInvoice",
    "montant": 0,
    "amount": 0,
    "date": "",
    "external_id": "",
    "oreference": "",
    "customer_details": {
      "firstname": "",
      "lastname": "",
      "email": "",
      "phone": "",
      "details": ""
    },
    "request_id": ""
  }
  ```
</CodeGroup>

## Lire `custom_data` dans la réponse

`custom_data` retourne un tableau de vos métadonnées enrichi par LigdiCash (qui y ajoute notamment `logfile`). Pour retrouver votre `transaction_id` :

```javascript JavaScript theme={null}
const entry = data.custom_data.find(
  (item) => item.keyof_customdata === "transaction_id"
);
const transactionId = entry?.valueof_customdata;
```

<Tip>
  Consultez [Parser custom\_data](/api-paiement/callback/parser-custom-data) pour le traitement complet, notamment les cas où `custom_data` est un tableau vide ou une chaîne vide.
</Tip>

## Quand appeler `confirm` ?

**1. Après la redirection vers `return_url`**

Depuis votre frontend, déclenchez un appel à votre backend, qui appelle `confirm` avec le token stocké. N'appelez jamais `confirm` directement depuis le navigateur — vos clés API seraient exposées.

**2. Dans votre handler de callback**

Avant d'honorer une commande suite à un callback, re-vérifiez toujours le statut avec `confirm`. Un faux payload peut être envoyé par n'importe qui connaissant l'URL de votre endpoint.

## Pattern de polling

Si le callback n'est pas disponible ou tarde à arriver, interrogez `confirm` à intervalles réguliers :

```javascript JavaScript theme={null}
async function attendreConfirmation(token, { intervalle = 4000, maxTentatives = 10 } = {}) {
  for (let i = 0; i < maxTentatives; i++) {
    const data = await appellerConfirm(token);

    if (data.status === "completed") return { success: true, data };
    if (data.status === "notcompleted") return { success: false, data };

    await new Promise((r) => setTimeout(r, intervalle));
  }
  return { success: false, reason: "timeout" };
}
```

<Note>
  Le polling est un filet de sécurité, pas la stratégie principale. Privilégiez toujours le callback. Consultez [Polling vs callback](/api-paiement/verification-statut/polling-vs-callback) pour les arbitrages.
</Note>

## Pages associées

* [Rediriger le client](/api-paiement/payin-redirect/rediriger-client) — obtenir le token de création
* [Callback — sécurisation](/api-paiement/callback/securisation) — pourquoi toujours re-vérifier
* [Parser custom\_data](/api-paiement/callback/parser-custom-data) — lire les métadonnées en toute sécurité
* [Polling vs callback](/api-paiement/verification-statut/polling-vs-callback) — choisir la bonne stratégie
* [Codes de réponse et statuts](/concepts/codes-reponse-statuts) — référence complète


# Créer une transaction
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/creer-transaction

Endpoint POST /pay/v01/straight/checkout-invoice/create — paramètres, exemples par mode de validation et réponse.

Cet endpoint initie un paiement directement depuis votre interface. Vous fournissez le numéro de téléphone du client et, selon le [mode de validation](/api-paiement/payin-sans-redirect/modes-validation) de l'opérateur, l'OTP ou un champ vide. LigdiCash retourne un token à stocker et déclenche le processus de validation côté opérateur.

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

<Note>
  Le Wallet LigdiCash utilise des endpoints distincts (`/pay/v02/debitotp` et `/pay/v02/debitwallet/withotp`). Consultez la [page dédiée au Wallet LigdiCash](/api-paiement/payin-sans-redirect/operateurs/wallet-ligdicash) pour son intégration spécifique.
</Note>

## Headers

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

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

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

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

## Body

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

  <Expandable title="Champs de commande">
    <ParamField type="object">
      Détails de la transaction.

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

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

        <ParamField type="integer">
          Montant total en XOF (entier, sans décimales).
        </ParamField>

        <ParamField type="string">
          Devise. Toujours `XOF`.
        </ParamField>

        <ParamField type="string">
          Description de la commande.
        </ParamField>

        <ParamField type="string">
          Numéro de téléphone mobile money du client, sans `+` ni espaces. Format : `22670XXXXXXX`.
        </ParamField>

        <ParamField type="string">
          Prénom du client.
        </ParamField>

        <ParamField type="string">
          Nom du client.
        </ParamField>

        <ParamField type="string">
          Email du client.
        </ParamField>

        <ParamField type="string">
          Doit toujours être vide (`""`).
        </ParamField>

        <ParamField type="string">
          Code OTP selon le mode de validation de l'opérateur :

          * **OTP USSD** : OTP généré par le client via son menu USSD, à renseigner avant l'appel.
          * **USSD Push**, **USSD guidé**, **OTP SMS (1ère requête)** : laisser vide (`""`).
          * **OTP SMS (2ème requête)** : OTP reçu par SMS par le client.
        </ParamField>
      </Expandable>
    </ParamField>

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

      <Expandable title="Champs de store">
        <ParamField type="string">Nom de votre boutique ou application.</ParamField>
        <ParamField type="string">URL de votre site.</ParamField>
      </Expandable>
    </ParamField>

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

      <Expandable title="Champs de actions">
        <ParamField type="string">Laisser vide (`""`).</ParamField>
        <ParamField type="string">Laisser vide (`""`).</ParamField>

        <ParamField type="string">
          URL de votre endpoint backend pour les notifications de statut. Doit être accessible publiquement.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField 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>

## Exemples de requête

Les exemples ci-dessous montrent deux cas selon le mode de validation. Seul le champ `otp` change.

<CodeGroup>
  ```bash cURL — OTP USSD (otp renseigné) theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22670000000",
          "customer_firstname": "Amadou",
          "customer_lastname": "Diallo",
          "customer_email": "amadou@exemple.com",
          "external_id": "",
          "otp": "123456"
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00042"
        }
      }
    }'
  ```

  ```bash cURL — USSD Push / USSD guidé / OTP SMS 1ère requête (otp vide) theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22670000000",
          "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": "",
          "return_url": "",
          "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/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: "Abonnement Pro — Janvier 2025",
            customer: "22670000000",
            customer_firstname: "Amadou",
            customer_lastname: "Diallo",
            customer_email: "amadou@exemple.com",
            external_id: "",
            otp: "", // ou l'OTP collecté pour le mode OTP USSD
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00042" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $otp = ""; // ou l'OTP collecté pour le mode OTP USSD

  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "22670000000",
        "customer_firstname" => "Amadou",
        "customer_lastname" => "Diallo",
        "customer_email" => "amadou@exemple.com",
        "external_id" => "",
        "otp" => $otp,
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.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);
  ```
</CodeGroup>

## Réponse

<ResponseField name="response_code" type="string">
  `"00"` si la transaction 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 immédiatement** — nécessaire pour appeler l'endpoint `confirm` et re-vérifier le statut.
</ResponseField>

<ResponseField name="response_text" type="string">
  En cas de succès : `"Votre requête est en cours de traitement"`. 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": "Votre requête est en cours de traitement",
    "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>

<Warning>
  Stockez le `token` retourné dès la création. C'est lui que vous utiliserez pour appeler `confirm` et vérifier le statut final — ne vous fiez jamais au token présent dans le payload du callback.
</Warning>

## Pages associées

* [Modes de validation](/api-paiement/payin-sans-redirect/modes-validation) — choisir la valeur du champ `otp` selon l'opérateur
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` avec le token de création
* [Le pattern transaction\_id](/concepts/transaction-id-pattern) — bonnes pratiques pour `custom_data`


# Payin sans redirection
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/introduction

Collectez des paiements directement dans votre interface, sans rediriger votre client vers LigdiCash. Vous gérez l'UX, LigdiCash gère l'opérateur.

Le payin sans redirection vous permet d'intégrer le formulaire de paiement directement dans votre application. Votre client ne quitte pas votre interface : il saisit son numéro de téléphone, valide le paiement selon les instructions de son opérateur, et la transaction est confirmée par callback. Vous avez le contrôle total de l'expérience utilisateur.

Cette méthode demande plus de travail d'intégration que le payin avec redirection : le mode de validation varie selon l'opérateur, et votre UX doit s'y adapter.

## Comment ça fonctionne

Le flux général comporte quatre étapes, dont l'étape 3 varie selon le [mode de validation](/api-paiement/payin-sans-redirect/modes-validation) de l'opérateur choisi.

<Steps>
  <Step title="Collecter le numéro du client">
    Votre interface recueille le numéro de téléphone mobile money du client, au format sans `+` ni espaces (`22670XXXXXXX`). Selon l'opérateur, vous déterminez le mode de validation à appliquer.
  </Step>

  <Step title="Initier la transaction">
    Vous appelez `POST /pay/v01/straight/checkout-invoice/create` (ou les endpoints spécifiques pour le Wallet LigdiCash) avec le numéro du client et, selon le mode, l'OTP déjà collecté ou un champ `otp` vide.
  </Step>

  <Step title="Validation par le client">
    Le client valide le paiement selon son opérateur : en répondant à un push USSD, en composant un code USSD, ou en communiquant un OTP reçu par SMS. Dans ce dernier cas uniquement (OTP SMS), vous re-soumettez une seconde requête avec le code.
  </Step>

  <Step title="Confirmation">
    LigdiCash envoie un callback à votre `callback_url`. Vous re-vérifiez le statut via l'endpoint `confirm` avec le token stocké à la création avant de finaliser la commande.
  </Step>
</Steps>

## Modes de validation

Le comportement de l'étape 3 dépend de l'opérateur. Quatre modes existent :

| Mode           | Déclenchement    | Résumé                                                                                    |
| -------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| **OTP USSD**   | Avant soumission | Le client compose un USSD → génère un OTP → vous soumettez avec cet OTP                   |
| **USSD Push**  | Après soumission | L'opérateur envoie un push USSD → le client valide avec son PIN                           |
| **USSD guidé** | Après soumission | L'opérateur envoie un SMS avec un code USSD → le client compose le USSD                   |
| **OTP SMS**    | Après soumission | L'opérateur envoie un OTP par SMS → le client vous communique le code → vous re-soumettez |

```mermaid theme={null}
flowchart TD
    A[Client saisit son numéro] --> B{Mode de validation\nde l'opérateur}

    B -->|OTP USSD| C["Client compose le USSD\net obtient son OTP"]
    C --> D["Backend soumet\notp: {code OTP}"]

    B -->|USSD Push| E["Backend soumet\notp: ''"]
    E --> F["Opérateur envoie\nun push USSD"]
    F --> G["Client valide\navec son PIN"]

    B -->|USSD guidé| H["Backend soumet\notp: ''"]
    H --> I["Opérateur envoie un SMS\navec code USSD"]
    I --> J["Client compose\nle code USSD"]

    B -->|OTP SMS| K["Backend soumet\notp: ''"]
    K --> L["Opérateur envoie\nun OTP par SMS"]
    L --> M["Client communique\nl'OTP au marchand"]
    M --> N["Backend re-soumet\notp: {code OTP}"]

    D --> Z["LigdiCash envoie le callback\nBackend re-vérifie via confirm"]
    G --> Z
    J --> Z
    N --> Z
```

<Card title="Modes de validation — guide complet" icon="list-check" href="/api-paiement/payin-sans-redirect/modes-validation">
  Comprendre les quatre modes et adapter votre UX à chaque opérateur
</Card>

## Contraintes importantes

<Warning>
  Le champ `external_id` doit toujours être vide (`""`) dans toutes les requêtes payin sans redirection.
</Warning>

<Note>
  Le token retourné à la création est différent du token présent dans le payload du callback. Stockez toujours le token de création côté marchand et utilisez-le pour appeler `confirm` — ne faites pas confiance au token du callback seul.
</Note>

## Dans cette section

<CardGroup>
  <Card title="Modes de validation" icon="list-check" href="/api-paiement/payin-sans-redirect/modes-validation">
    OTP USSD, USSD Push, USSD guidé, OTP SMS — comprendre et adapter l'UX
  </Card>

  <Card title="Créer une transaction" icon="file-invoice" href="/api-paiement/payin-sans-redirect/creer-transaction">
    Paramètres, payload complet et réponse de l'endpoint de création
  </Card>

  <Card title="Vérifier le statut" icon="circle-check" href="/api-paiement/payin-sans-redirect/verifier-statut">
    Appeler l'endpoint confirm avec le token de création
  </Card>

  <Card title="Opérateurs supportés" icon="mobile" href="/api-paiement/payin-sans-redirect/operateurs/orange-burkina">
    Une page dédiée par opérateur avec les identifiants, le mode et les exemples
  </Card>
</CardGroup>


# Modes de validation
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/modes-validation

Les six modes de validation du payin sans redirection : OTP USSD, USSD Push, USSD guidé, OTP SMS, Redirection LigdiCash, Redirection opérateur. Comprendre les flux et adapter votre UX.

Avec le payin sans redirection, c'est l'opérateur qui décide comment le client confirme son paiement. Ce mécanisme s'appelle le **mode de validation**. Il détermine le flux exact que vous devez implémenter côté interface : quand collecter un OTP, quand afficher un message d'attente, quand soumettre une seconde requête, ou quand rediriger le client vers une page externe.

**Ces six modes sont indépendants.** Chaque opérateur en utilise un (parfois deux en cas de fallback). Vous n'implémentez que le mode correspondant à l'opérateur que vous intégrez. Consultez la [page dédiée à chaque opérateur](/api-paiement/payin-sans-redirect/operateurs/orange-burkina) pour savoir quel mode appliquer.

<Note>
  Tous les modes utilisent **le même endpoint** `POST /pay/v01/straight/checkout-invoice/create`. La différence se joue côté UX et flux : OTP à collecter ou non, message d'attente, redirection éventuelle vers une URL retournée dans `response_text`. Ne confondez pas avec le [payin avec redirection](/api-paiement/payin-redirect/introduction) qui utilise un endpoint distinct (`/redirect/...`) et expose une page de paiement LigdiCash multi-opérateurs.
</Note>

## Détail de chaque mode

<Tabs>
  <Tab title="OTP USSD">
    Le client génère lui-même un code OTP en composant un code USSD sur son téléphone, **avant que vous n'appeliez l'API**. Vous collectez le numéro et l'OTP en même temps dans votre formulaire, puis soumettez une seule requête avec les deux.

    **Flux :**

    <Steps>
      <Step title="Le client compose le code USSD">
        Avant de remplir votre formulaire, le client compose le code USSD de son opérateur sur son téléphone (ex. `*144*4*6#` pour Orange Burkina Faso). Un OTP à usage unique s'affiche sur son écran.
      </Step>

      <Step title="Le client saisit ses informations">
        Votre formulaire collecte le numéro de téléphone et l'OTP en même temps.
      </Step>

      <Step title="Vous soumettez la requête API">
        Une seule requête avec le numéro dans `customer` et l'OTP dans `otp`. Aucun second appel nécessaire.
      </Step>

      <Step title="Confirmation par callback">
        LigdiCash vous notifie du résultat via votre `callback_url`.
      </Step>
    </Steps>

    ```mermaid theme={null}
    sequenceDiagram
        actor Client
        participant UI as Votre interface
        participant Backend as Votre backend
        participant LC as LigdiCash

        Client->>Client: Compose le code USSD (*144*4*6# pour Orange BF)
        Client->>Client: Obtient un OTP à usage unique
        Client->>UI: Saisit numéro + OTP dans le formulaire
        UI->>Backend: numéro + OTP
        Backend->>LC: POST /create — customer: numéro, otp: code
        LC-->>Backend: token (transaction pending)
        LC->>Backend: POST /callback_url (résultat final)
    ```

    **UX recommandée :** affichez le code USSD à composer avec des instructions claires avant que le client ne remplisse le formulaire.

    <Note>
      L'OTP généré via USSD a une durée de validité courte. Invitez le client à saisir son OTP immédiatement après l'avoir généré.
    </Note>

    **Opérateurs utilisant ce mode :** Orange Burkina Faso.
  </Tab>

  <Tab title="USSD Push">
    Après votre requête API, l'opérateur envoie directement un écran USSD push sur le téléphone du client. Le client valide avec son code PIN sur cet écran. Vous n'avez pas besoin de re-soumettre de requête.

    **Flux :**

    <Steps>
      <Step title="Le client saisit son numéro">
        Votre formulaire collecte uniquement le numéro de téléphone. Aucun OTP à collecter.
      </Step>

      <Step title="Vous soumettez la requête API">
        Requête avec le numéro dans `customer` et `otp: ""`.
      </Step>

      <Step title="L'opérateur envoie le push USSD">
        Un menu USSD apparaît automatiquement sur le téléphone du client. Il valide le paiement avec son code PIN.
      </Step>

      <Step title="Confirmation par callback">
        LigdiCash vous notifie du résultat via votre `callback_url`.
      </Step>
    </Steps>

    ```mermaid theme={null}
    sequenceDiagram
        actor Client
        participant UI as Votre interface
        participant Backend as Votre backend
        participant LC as LigdiCash

        Client->>UI: Saisit son numéro de téléphone
        UI->>Backend: numéro
        Backend->>LC: POST /create — customer: numéro, otp: ""
        LC-->>Backend: token (transaction pending)
        LC->>Client: Push USSD sur le téléphone du client
        Client->>Client: Valide avec son code PIN
        LC->>Backend: POST /callback_url (résultat final)
    ```

    **UX recommandée :** après la soumission de la requête API, affichez un message demandant au client de valider sur son téléphone. Mettez en place un indicateur d'attente et basculez sur le résultat à la réception du callback (ou via polling sur l'endpoint `confirm`).

    **Opérateurs utilisant ce mode :** Moov Africa Burkina Faso, Moov Africa Bénin, MTN Mobile Money Bénin, Moov Africa Côte d'Ivoire, Vodacom RDC, Airtel RDC, Africell RDC, Airtel Niger, Moov Africa Niger, YAS Togo, Moov Africa Togo.
  </Tab>

  <Tab title="USSD guidé">
    Après votre requête API, l'opérateur envoie un SMS au client contenant les instructions et le code USSD à composer. Le client compose ce code sur son téléphone pour valider. Vous n'avez pas besoin de re-soumettre de requête.

    **Flux :**

    <Steps>
      <Step title="Le client saisit son numéro">
        Votre formulaire collecte uniquement le numéro de téléphone.
      </Step>

      <Step title="Vous soumettez la requête API">
        Requête avec le numéro dans `customer` et `otp: ""`.
      </Step>

      <Step title="L'opérateur envoie un SMS">
        Le client reçoit un SMS contenant les instructions et le code USSD à composer.
      </Step>

      <Step title="Le client compose le USSD">
        Le client suit les instructions du SMS et valide le paiement depuis son menu USSD.
      </Step>

      <Step title="Confirmation par callback">
        LigdiCash vous notifie du résultat via votre `callback_url`.
      </Step>
    </Steps>

    ```mermaid theme={null}
    sequenceDiagram
        actor Client
        participant UI as Votre interface
        participant Backend as Votre backend
        participant LC as LigdiCash

        Client->>UI: Saisit son numéro de téléphone
        UI->>Backend: numéro
        Backend->>LC: POST /create — customer: numéro, otp: ""
        LC-->>Backend: token (transaction pending)
        LC->>Client: SMS avec instructions + code USSD à composer
        Client->>Client: Compose le code USSD reçu par SMS
        LC->>Backend: POST /callback_url (résultat final)
    ```

    **UX recommandée :** après la soumission de la requête API, affichez un message indiquant au client qu'il va recevoir un SMS avec les instructions à suivre.

    **Exemples de SMS reçus par le client :**

    <CodeGroup>
      ```text MTN Côte d'Ivoire theme={null}
      Vous avez recu une demande de debit avec la reference 1692100357.
      Tapez *133# puis choisissez l option retrait pour approuver.
      ```

      ```text Moov Côte d'Ivoire (fallback) theme={null}
      Vous avez une transaction 0000000433 - LIGDICASH_CI en attente.
      Faites *155*15# pour payer.
      ```
    </CodeGroup>

    <Note>
      Ce mode est parfois utilisé en fallback du USSD Push quand le push n'aboutit pas (ex. Moov Africa Burkina Faso, Moov Africa Côte d'Ivoire).
    </Note>

    **Opérateurs utilisant ce mode :** MTN Côte d'Ivoire (principal), Zamani Niger (principal), Moov Africa Burkina Faso (fallback), Moov Africa Côte d'Ivoire (fallback).
  </Tab>

  <Tab title="OTP SMS">
    Après votre première requête API, l'opérateur envoie un code OTP par SMS au client. Le client vous communique ce code, et vous soumettez une seconde requête API avec l'OTP.

    **Flux :**

    <Steps>
      <Step title="Le client saisit son numéro">
        Votre formulaire collecte le numéro de téléphone. Aucun OTP à ce stade.
      </Step>

      <Step title="Première requête API">
        Requête avec le numéro dans `customer` et `otp: ""`. LigdiCash déclenche l'envoi de l'OTP par SMS.
      </Step>

      <Step title="Le client reçoit l'OTP">
        L'opérateur envoie un code OTP par SMS sur le numéro du client.
      </Step>

      <Step title="Le client saisit l'OTP">
        Votre interface affiche un second champ de saisie pour l'OTP reçu par SMS.
      </Step>

      <Step title="Seconde requête API">
        Vous soumettez à nouveau la requête, cette fois avec l'OTP dans le champ `otp`.
      </Step>

      <Step title="Confirmation par callback">
        LigdiCash vous notifie du résultat via votre `callback_url`.
      </Step>
    </Steps>

    ```mermaid theme={null}
    sequenceDiagram
        actor Client
        participant UI as Votre interface
        participant Backend as Votre backend
        participant LC as LigdiCash

        Client->>UI: Saisit son numéro de téléphone
        UI->>Backend: numéro
        Backend->>LC: POST /create — customer: numéro, otp: ""
        LC-->>Backend: token (transaction pending)
        LC->>Client: SMS avec code OTP
        Client->>UI: Saisit le code OTP reçu par SMS
        UI->>Backend: OTP
        Backend->>LC: POST /create — customer: numéro, otp: code
        LC-->>Backend: confirmation
        LC->>Backend: POST /callback_url (résultat final)
    ```

    **UX recommandée :** adoptez un formulaire en deux étapes — d'abord le numéro, puis l'OTP après réception du SMS. Prévoyez un bouton « Renvoyer le code » avec une temporisation.

    <Warning>
      Ce mode nécessite deux appels API distincts. Attendez que le client ait saisi l'OTP reçu par SMS avant d'envoyer la seconde requête.
    </Warning>

    **Opérateurs utilisant ce mode :** Wallet LigdiCash.
  </Tab>

  <Tab title="Redirection LigdiCash">
    Pour certains opérateurs, l'intégration LigdiCash passe actuellement par une **page web LigdiCash dédiée** plutôt que par un traitement direct via l'API. Vous appelez le même endpoint `/straight/checkout-invoice/create` en préremplissant `customer` avec le numéro du client. LigdiCash répond avec une URL de page de paiement où **seul l'opérateur du numéro est proposé** et le numéro est prérempli. Vous redirigez le client vers cette URL — il confirme depuis la page LigdiCash et le paiement procède selon le mode propre à l'opérateur.

    <Warning>
      Le préremplissage de `customer` est **obligatoire** pour ces opérateurs. Sans `customer`, le filtrage par numéro ne fonctionne pas et la page de paiement n'affiche pas le bon opérateur. Ne pas confondre avec les autres modes du payin sans redirection, où `customer` est toujours fourni mais sert simplement à initier la transaction sans filtrage.
    </Warning>

    **Flux :**

    <Steps>
      <Step title="Le client saisit son numéro">
        Votre formulaire collecte uniquement le numéro de téléphone. Aucun OTP à collecter.
      </Step>

      <Step title="Vous soumettez la requête API">
        Requête sur `POST /pay/v01/straight/checkout-invoice/create` avec `customer` rempli avec le numéro du client et `otp: ""`.
      </Step>

      <Step title="LigdiCash retourne une URL de page de paiement">
        La réponse contient le token de transaction et le champ `response_text` rempli avec l'URL de la page de paiement LigdiCash dédiée à cette transaction.
      </Step>

      <Step title="Vous redirigez le client">
        Redirigez le navigateur du client vers l'URL reçue. La page de paiement LigdiCash affiche le numéro prérempli et l'opérateur déjà sélectionné — le client ne peut ni changer de numéro ni d'opérateur.
      </Step>

      <Step title="Confirmation par callback">
        Le client confirme depuis la page LigdiCash et le paiement procède selon le mode propre à l'opérateur (USSD push, OTP, etc.). LigdiCash vous notifie le résultat final via votre `callback_url`.
      </Step>
    </Steps>

    ```mermaid theme={null}
    sequenceDiagram
        actor Client
        participant UI as Votre interface
        participant Backend as Votre backend
        participant LC as LigdiCash
        participant LCWeb as Page LigdiCash

        Client->>UI: Saisit son numéro de téléphone
        UI->>Backend: numéro
        Backend->>LC: POST /straight/create — customer: numéro, otp: ""
        LC-->>Backend: token + response_text (URL page LigdiCash)
        Backend-->>UI: URL page LigdiCash
        UI->>LCWeb: Redirection du client
        Client->>LCWeb: Confirme le paiement (numéro et opérateur préremplis)
        LCWeb-->>LC: Validation
        LC->>Backend: POST /callback_url (résultat final)
    ```

    **UX recommandée :** redirigez immédiatement le client vers l'URL retournée dans `response_text`. Déclenchez en parallèle un état d'attente côté backend et basculez vers la confirmation à la réception du callback.

    <Note>
      Ce mode utilise bien l'endpoint `/straight/checkout-invoice/create` (payin sans redirection). Ne pas confondre avec le [payin avec redirection](/api-paiement/payin-redirect/introduction), qui utilise un endpoint distinct (`/redirect/...`) et expose une page de paiement multi-opérateurs où le client choisit son moyen de paiement.
    </Note>

    **Opérateurs utilisant ce mode :** Orange Money RD Congo, Orange Money Guinée Conakry, MTN Mobile Money Guinée Conakry, Orange Money Sénégal, Wave Sénégal, Free Sénégal.
  </Tab>

  <Tab title="Redirection opérateur">
    Pour certains opérateurs, l'intégration LigdiCash passe par **le portail web de l'opérateur** pour authentifier le client. Après votre requête API, LigdiCash répond avec l'URL d'un portail externe (Orange Money, par exemple). Vous redirigez le client vers cette URL — il s'y authentifie et confirme le paiement. Le résultat final arrive par callback.

    **Flux :**

    <Steps>
      <Step title="Le client saisit son numéro">
        Votre formulaire collecte uniquement le numéro de téléphone. Aucun OTP à collecter.
      </Step>

      <Step title="Vous soumettez la requête API">
        Requête sur `POST /pay/v01/straight/checkout-invoice/create` avec le numéro dans `customer` et `otp: ""`.
      </Step>

      <Step title="LigdiCash retourne une URL de portail">
        La réponse contient le token de transaction et le champ `response_text` rempli avec l'URL du portail de l'opérateur (ex. `https://mpayment.orange-money.com/...`).
      </Step>

      <Step title="Vous redirigez le client">
        Redirigez le navigateur du client vers l'URL reçue. Le client s'authentifie sur le portail de l'opérateur et confirme le paiement.
      </Step>

      <Step title="Confirmation par callback">
        À l'issue du parcours sur le portail, LigdiCash vous notifie du résultat via votre `callback_url`. Le retour navigateur du client peut être asynchrone — fiez-vous au callback, pas au retour utilisateur.
      </Step>
    </Steps>

    ```mermaid theme={null}
    sequenceDiagram
        actor Client
        participant UI as Votre interface
        participant Backend as Votre backend
        participant LC as LigdiCash
        participant Portail as Portail opérateur

        Client->>UI: Saisit son numéro de téléphone
        UI->>Backend: numéro
        Backend->>LC: POST /create — customer: numéro, otp: ""
        LC-->>Backend: token + response_text (URL portail)
        Backend-->>UI: URL portail
        UI->>Portail: Redirection du client
        Client->>Portail: S'authentifie et confirme
        Portail-->>LC: Résultat du paiement
        LC->>Backend: POST /callback_url (résultat final)
    ```

    **Exemple de réponse de création :**

    ```json theme={null}
    {
      "response_code": "00",
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
      "response_text": "https://mpayment.orange-money.com/ml/mpayment/abstract/v1nd8lrkjniiezp3gus76kvmlgztvuylkcs2y5kiir6stko13emvuabrv95oaufb",
      "description": "",
      "custom_data": {
        "transaction_id": "59257c61dab04a70a009af019cd34040",
        "logfile": "202605111744086a021568f2037"
      },
      "wiki": "https://client.ligdicash.com/wiki/createInvoice"
    }
    ```

    **UX recommandée :** redirigez immédiatement le client vers l'URL retournée dans `response_text`. Côté backend, déclenchez en parallèle un état d'attente sur la transaction et basculez vers la confirmation à la réception du callback.

    <Warning>
      Le retour navigateur du client après le portail de l'opérateur n'est pas garanti — l'utilisateur peut fermer l'onglet, perdre le réseau, ou ne jamais revenir. **Le callback reste la seule source de vérité**, comme pour les autres modes. Ne validez jamais le paiement uniquement sur le retour du client.
    </Warning>

    <Note>
      Ce mode utilise bien l'endpoint `/straight/checkout-invoice/create` (payin sans redirection), mais le parcours utilisateur inclut une redirection externe. Ne pas confondre avec le [payin avec redirection](/api-paiement/payin-redirect/introduction), qui utilise un endpoint distinct et expose la page de paiement LigdiCash.
    </Note>

    **Opérateurs utilisant ce mode :** Orange Money Côte d'Ivoire, Orange Money Mali.
  </Tab>
</Tabs>

## Récapitulatif

| Mode                      | Requêtes API | OTP collecté                            | Ce que fait le client                                          |
| ------------------------- | ------------ | --------------------------------------- | -------------------------------------------------------------- |
| **OTP USSD**              | 1            | Avant d'appeler l'API (via USSD)        | Compose un USSD, donne l'OTP au marchand                       |
| **USSD Push**             | 1            | Aucun                                   | Valide sur le push USSD reçu                                   |
| **USSD guidé**            | 1            | Aucun                                   | Compose un USSD après réception d'un SMS                       |
| **OTP SMS**               | 2            | Après la première requête API (via SMS) | Reçoit un OTP par SMS, le communique au marchand               |
| **Redirection LigdiCash** | 1            | Aucun                                   | Est redirigé vers une page LigdiCash pré-filtrée et y confirme |
| **Redirection opérateur** | 1            | Aucun                                   | Est redirigé vers le portail de l'opérateur et y confirme      |

Pour connaître le mode de validation de chaque opérateur, consultez sa page dédiée dans la section [Intégration par opérateur](/api-paiement/payin-sans-redirect/operateurs/orange-burkina).


# Africell — RD Congo
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/africell-rdc

Intégrer Africell Money RD Congo avec l'API LigdiCash. Mode de validation : USSD Push.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | RD Congo                                         |
| Opérateur          | Africell RDC (Africell Money)                    |
| `operator_id`      | `38`                                             |
| `operator_name`    | `AFRICELL RDC CONGO`                             |
| Indicatif          | +243                                             |
| Format du numéro   | `243XXXXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD Push                                        |

## Mode de validation : USSD Push

Après votre requête, l'opérateur envoie un push USSD directement sur le téléphone du client. Le client valide avec son code PIN Africell Money. Aucune saisie supplémentaire côté marchand — le callback reste la source de vérité.

<Note>
  Affichez un message d'attente clair après soumission. Le push USSD arrive sur le téléphone du client en quelques secondes, mais le callback peut prendre de quelques secondes à plusieurs minutes selon l'opérateur.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Africell. Aucun OTP à collecter.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez :

    > *« Validez le paiement sur votre téléphone. Vous allez recevoir une demande USSD à approuver avec votre code PIN Africell Money. »*

    Maintenez l'état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "243990000000",
          "customer_firstname": "Patrick",
          "customer_lastname": "Lumumba",
          "customer_email": "patrick@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00052"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "243990000000",
            customer_firstname: "Patrick",
            customer_lastname: "Lumumba",
            customer_email: "patrick@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00052" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "243990000000",
        "customer_firstname" => "Patrick",
        "customer_lastname" => "Lumumba",
        "customer_email" => "patrick@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00052"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur  |
| ------------------ | ------- |
| Montant minimum    | 100 XOF |
| Montant maximum    | --      |
| Limite quotidienne | --      |

## Pages associées

* [Modes de validation — USSD Push](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Airtel — Niger
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/airtel-niger

Intégrer Airtel Money Niger avec l'API LigdiCash. Mode de validation : USSD Push.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Niger                                            |
| Opérateur          | Airtel Niger (Airtel Money)                      |
| `operator_id`      | `27`                                             |
| `operator_name`    | `AIRTEL NIGER`                                   |
| Indicatif          | +227                                             |
| Format du numéro   | `22790XXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD Push                                        |

## Mode de validation : USSD Push

Après votre requête, l'opérateur envoie un push USSD directement sur le téléphone du client. Le client valide avec son code PIN Airtel Money. Aucune saisie supplémentaire côté marchand — le callback reste la source de vérité.

<Note>
  Affichez un message d'attente clair après soumission. Le push USSD arrive sur le téléphone du client en quelques secondes, mais le callback peut prendre de quelques secondes à plusieurs minutes selon l'opérateur.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Airtel. Aucun OTP à collecter.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez :

    > *« Validez le paiement sur votre téléphone. Vous allez recevoir une demande USSD à approuver avec votre code PIN Airtel Money. »*

    Maintenez l'état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22790000000",
          "customer_firstname": "Hassane",
          "customer_lastname": "Issoufou",
          "customer_email": "hassane@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00063"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "22790000000",
            customer_firstname: "Hassane",
            customer_lastname: "Issoufou",
            customer_email: "hassane@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00063" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "22790000000",
        "customer_firstname" => "Hassane",
        "customer_lastname" => "Issoufou",
        "customer_email" => "hassane@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00063"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur |
| ------------------ | ------ |
| Montant minimum    | 10 XOF |
| Montant maximum    | --     |
| Limite quotidienne | --     |

## Pages associées

* [Modes de validation — USSD Push](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Airtel — RD Congo
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/airtel-rdc

Intégrer Airtel Money RD Congo avec l'API LigdiCash. Mode de validation : USSD Push.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | RD Congo                                         |
| Opérateur          | Airtel RDC (Airtel Money)                        |
| `operator_id`      | `37`                                             |
| `operator_name`    | `AIRTEL RDC CONGO`                               |
| Indicatif          | +243                                             |
| Format du numéro   | `243XXXXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD Push                                        |

## Mode de validation : USSD Push

Après votre requête, l'opérateur envoie un push USSD directement sur le téléphone du client. Le client valide avec son code PIN Airtel Money. Aucune saisie supplémentaire côté marchand — le callback reste la source de vérité.

<Note>
  Affichez un message d'attente clair après soumission. Le push USSD arrive sur le téléphone du client en quelques secondes, mais le callback peut prendre de quelques secondes à plusieurs minutes selon l'opérateur.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Airtel. Aucun OTP à collecter.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez :

    > *« Validez le paiement sur votre téléphone. Vous allez recevoir une demande USSD à approuver avec votre code PIN Airtel Money. »*

    Maintenez l'état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "243970000000",
          "customer_firstname": "David",
          "customer_lastname": "Kasongo",
          "customer_email": "david@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00051"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "243970000000",
            customer_firstname: "David",
            customer_lastname: "Kasongo",
            customer_email: "david@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00051" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "243970000000",
        "customer_firstname" => "David",
        "customer_lastname" => "Kasongo",
        "customer_email" => "david@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00051"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur |
| ------------------ | ------ |
| Montant minimum    | 10 XOF |
| Montant maximum    | --     |
| Limite quotidienne | --     |

## Pages associées

* [Modes de validation — USSD Push](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Free — Sénégal
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/free-senegal

Intégrer Free Sénégal avec l'API LigdiCash. Mode de validation : Redirection LigdiCash (page de paiement pré-filtrée).

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Sénégal                                          |
| Opérateur          | Free Sénégal                                     |
| `operator_id`      | `32`                                             |
| `operator_name`    | `FREE SENEGAL`                                   |
| Indicatif          | +221                                             |
| Format du numéro   | `221XXXXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | Redirection LigdiCash                            |

## Mode de validation : Redirection LigdiCash

Pour Free Sénégal, l'intégration LigdiCash passe actuellement par une **page web LigdiCash dédiée**, plutôt que par un traitement direct via l'API. Le flux est le suivant :

1. Vous appelez `/pay/v01/straight/checkout-invoice/create` avec le numéro du client dans `customer` et `otp: ""`.
2. LigdiCash répond avec le `token` de transaction et un champ `response_text` qui contient **l'URL d'une page de paiement LigdiCash** où le numéro est prérempli et où seul Free Sénégal est proposé.
3. Vous redirigez le navigateur du client vers cette URL.
4. Le client confirme le paiement depuis la page LigdiCash et le paiement procède selon le flux propre à l'opérateur.
5. LigdiCash vous notifie le résultat final via votre `callback_url`.

<Warning>
  Le préremplissage de `customer` avec le numéro du client est **obligatoire**. Sans `customer`, le filtrage par numéro ne fonctionne pas et la page de paiement n'affichera pas Free Sénégal correctement.
</Warning>

<Note>
  Ce mode utilise bien l'endpoint `/straight/checkout-invoice/create` (payin sans redirection). Ne pas confondre avec le [payin avec redirection](/api-paiement/payin-redirect/introduction), qui utilise un endpoint distinct et expose une page de paiement multi-opérateurs.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille le numéro de téléphone Free Sénégal.
  </Step>

  <Step title="Soumettre la requête">
    Requête sur `POST /pay/v01/straight/checkout-invoice/create` avec `customer` rempli et `otp: ""`.
  </Step>

  <Step title="Récupérer l'URL de la page LigdiCash">
    Dans la réponse, le champ `response_text` contient l'URL de la page de paiement LigdiCash dédiée.
  </Step>

  <Step title="Rediriger le client">
    Redirigez le navigateur du client vers cette URL. La page affiche le numéro prérempli et Free Sénégal pré-sélectionné.
  </Step>

  <Step title="Attendre le callback">
    Le résultat final arrive via votre `callback_url`. Affichez un état d'attente — ne vous fiez pas au retour navigateur.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "221760000000",
          "customer_firstname": "Oumar",
          "customer_lastname": "Sow",
          "customer_email": "oumar@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00066"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "221760000000",
            customer_firstname: "Oumar",
            customer_lastname: "Sow",
            customer_email: "oumar@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00066" },
        },
      }),
    }
  );

  const data = await response.json();
  // Redirigez le client vers la page de paiement LigdiCash
  window.location.href = data.response_text;
  ```

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "221760000000",
        "customer_firstname" => "Oumar",
        "customer_lastname" => "Sow",
        "customer_email" => "oumar@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00066"],
    ],
  ];

  $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);
  // Redirigez le client vers la page de paiement LigdiCash
  header("Location: " . $data["response_text"]);
  ```
</CodeGroup>

## Réponse attendue

```json theme={null}
{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1Qi...",
  "response_text": "https://app.ligdicash.com/pay/.../checkout/...",
  "description": "",
  "custom_data": {
    "transaction_id": "ORD-2025-00066"
  },
  "wiki": "https://client.ligdicash.com/wiki/createInvoice"
}
```

Redirigez le client vers l'URL contenue dans `response_text`. La page de paiement n'affichera que Free Sénégal avec le numéro prérempli.

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur |
| ------------------ | ------ |
| Montant minimum    | --     |
| Montant maximum    | --     |
| Limite quotidienne | --     |

## Pages associées

* [Modes de validation — Redirection LigdiCash](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Moov Africa — Bénin
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/moov-benin

Intégrer Moov Africa Bénin avec l'API LigdiCash. Mode de validation : USSD Push.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Bénin                                            |
| Opérateur          | Moov Africa Bénin (Moov Money)                   |
| `operator_id`      | `2`                                              |
| `operator_name`    | `MOOV BENIN`                                     |
| Indicatif          | +229                                             |
| Format du numéro   | `229XXXXXXXX` (sans `+` ni espaces)              |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD Push                                        |

## Mode de validation : USSD Push

Après votre requête, l'opérateur envoie un push USSD directement sur le téléphone du client. Le client valide avec son code PIN Moov Money. Aucune saisie supplémentaire côté marchand — le callback reste la source de vérité.

<Note>
  Affichez un message d'attente clair après soumission. Le push USSD arrive sur le téléphone du client en quelques secondes, mais le callback peut prendre de quelques secondes à plusieurs minutes selon l'opérateur.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Moov. Aucun OTP à collecter.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez :

    > *« Validez le paiement sur votre téléphone. Vous allez recevoir une demande USSD à approuver avec votre code PIN Moov Money. »*

    Maintenez l'état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22990000000",
          "customer_firstname": "Sefiou",
          "customer_lastname": "Adekambi",
          "customer_email": "sefiou@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00067"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "22990000000",
            customer_firstname: "Sefiou",
            customer_lastname: "Adekambi",
            customer_email: "sefiou@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00067" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "22990000000",
        "customer_firstname" => "Sefiou",
        "customer_lastname" => "Adekambi",
        "customer_email" => "sefiou@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00067"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur  |
| ------------------ | ------- |
| Montant minimum    | 100 XOF |
| Montant maximum    | --      |
| Limite quotidienne | --      |

## Pages associées

* [Modes de validation — USSD Push](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Moov Africa — Burkina Faso
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/moov-burkina

Intégrer Moov Africa Burkina Faso avec l'API LigdiCash. Mode de validation : USSD Push avec fallback USSD guidé.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Burkina Faso                                     |
| Opérateur          | Moov Africa Burkina                              |
| `operator_id`      | `12`                                             |
| `operator_name`    | `MOOV AFRICA BURKINA`                            |
| Indicatif          | +226                                             |
| Format du numéro   | `226XXXXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD Push (fallback : USSD guidé)                |

## Modes de validation

Moov Africa Burkina Faso utilise deux modes selon la disponibilité réseau au moment de la transaction. Vous soumettez la même requête dans les deux cas — c'est l'opérateur qui décide du mode côté réseau.

**Mode principal — USSD Push :** après votre requête, l'opérateur envoie directement un écran USSD push sur le téléphone du client. Le client valide avec son code PIN. Aucune saisie supplémentaire côté marchand.

**Mode fallback — USSD guidé :** si le push n'aboutit pas, l'opérateur envoie un SMS contenant les instructions et le code USSD à composer. Le client compose le USSD pour valider.

<Note>
  Votre UX doit anticiper les deux cas. Affichez un message qui couvre les deux : le client recevra soit un push USSD à valider directement, soit un SMS avec les instructions à suivre.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Moov. Aucun OTP à collecter.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez un message du type :

    > *« Validez le paiement sur votre téléphone. Vous allez recevoir une demande de validation USSD, ou un SMS avec les instructions à suivre. »*

    Maintenez cet état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22660000000",
          "customer_firstname": "Aminata",
          "customer_lastname": "Sawadogo",
          "customer_email": "aminata@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00043"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "22660000000",
            customer_firstname: "Aminata",
            customer_lastname: "Sawadogo",
            customer_email: "aminata@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00043" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "22660000000",
        "customer_firstname" => "Aminata",
        "customer_lastname" => "Sawadogo",
        "customer_email" => "aminata@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00043"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur        |
| ------------------ | ------------- |
| Montant minimum    | 100 XOF       |
| Montant maximum    | 2 000 000 XOF |
| Limite quotidienne | --            |

## Pages associées

* [Modes de validation — USSD Push](/api-paiement/payin-sans-redirect/modes-validation) — détail des flux USSD Push et USSD guidé
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Moov Africa — Côte d'Ivoire
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/moov-cote-divoire

Intégrer Moov Africa Côte d'Ivoire avec l'API LigdiCash. Mode de validation : USSD Push avec fallback USSD guidé.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Côte d'Ivoire                                    |
| Opérateur          | Moov Africa Côte d'Ivoire (Moov Money)           |
| `operator_id`      | `14`                                             |
| `operator_name`    | `MOOV CI`                                        |
| Indicatif          | +225                                             |
| Format du numéro   | `225XXXXXXXXXX` (sans `+` ni espaces)            |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD Push (fallback : USSD guidé)                |

## Modes de validation

Moov Côte d'Ivoire utilise deux modes selon la disponibilité réseau au moment de la transaction. Vous soumettez la même requête dans les deux cas — c'est l'opérateur qui décide du mode côté réseau.

**Mode principal — USSD Push :** après votre requête, l'opérateur envoie directement un écran USSD push sur le téléphone du client. Le client valide avec son code PIN Moov Money. Aucune saisie supplémentaire côté marchand.

**Mode fallback — USSD guidé :** si le push n'aboutit pas, l'opérateur envoie un SMS contenant la référence de transaction et le code USSD à composer. Le client compose le USSD pour valider.

**Exemple de SMS reçu en mode fallback :**

```text theme={null}
Vous avez une transaction 0000000433 - LIGDICASH_CI en attente.
Faites *155*15# pour payer.
```

<Note>
  Votre UX doit anticiper les deux cas. Affichez un message qui couvre les deux : le client recevra soit un push USSD à valider directement, soit un SMS avec les instructions à suivre.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Moov. Aucun OTP à collecter.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez un message du type :

    > *« Validez le paiement sur votre téléphone. Vous allez recevoir une demande de validation USSD, ou un SMS avec les instructions à suivre. »*

    Maintenez cet état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "2250101000000",
          "customer_firstname": "Adama",
          "customer_lastname": "Koffi",
          "customer_email": "adama@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00055"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "2250101000000",
            customer_firstname: "Adama",
            customer_lastname: "Koffi",
            customer_email: "adama@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00055" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "2250101000000",
        "customer_firstname" => "Adama",
        "customer_lastname" => "Koffi",
        "customer_email" => "adama@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00055"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur  |
| ------------------ | ------- |
| Montant minimum    | 100 XOF |
| Montant maximum    | --      |
| Limite quotidienne | --      |

## Pages associées

* [Modes de validation — USSD Push & USSD guidé](/api-paiement/payin-sans-redirect/modes-validation) — détail des deux flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Moov Africa — Niger
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/moov-niger

Intégrer Moov Africa Niger avec l'API LigdiCash. Mode de validation : USSD Push.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Niger                                            |
| Opérateur          | Moov Africa Niger (Moov Money)                   |
| `operator_id`      | `29`                                             |
| `operator_name`    | `MOOV AFRICA NIGER`                              |
| Indicatif          | +227                                             |
| Format du numéro   | `22790XXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD Push                                        |

## Mode de validation : USSD Push

Après votre requête, l'opérateur envoie un push USSD directement sur le téléphone du client. Le client valide avec son code PIN Moov Money. Aucune saisie supplémentaire côté marchand — le callback reste la source de vérité.

<Note>
  Affichez un message d'attente clair après soumission. Le push USSD arrive sur le téléphone du client en quelques secondes, mais le callback peut prendre de quelques secondes à plusieurs minutes selon l'opérateur.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Moov. Aucun OTP à collecter.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez :

    > *« Validez le paiement sur votre téléphone. Vous allez recevoir une demande USSD à approuver avec votre code PIN Moov Money. »*

    Maintenez l'état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22790000002",
          "customer_firstname": "Idrissa",
          "customer_lastname": "Souley",
          "customer_email": "idrissa@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00069"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "22790000002",
            customer_firstname: "Idrissa",
            customer_lastname: "Souley",
            customer_email: "idrissa@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00069" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "22790000002",
        "customer_firstname" => "Idrissa",
        "customer_lastname" => "Souley",
        "customer_email" => "idrissa@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00069"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur |
| ------------------ | ------ |
| Montant minimum    | --     |
| Montant maximum    | --     |
| Limite quotidienne | --     |

## Pages associées

* [Modes de validation — USSD Push](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Moov Africa — Togo
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/moov-togo

Intégrer Moov Africa Togo avec l'API LigdiCash. Mode de validation : USSD Push.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Togo                                             |
| Opérateur          | Moov Africa Togo                                 |
| `operator_id`      | `4`                                              |
| `operator_name`    | `MOOV TOGO`                                      |
| Indicatif          | +228                                             |
| Format du numéro   | `228XXXXXXXX` (sans `+` ni espaces)              |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD Push                                        |

## Mode de validation : USSD Push

Après votre requête, l'opérateur envoie un push USSD directement sur le téléphone du client. Le client valide avec son code PIN Moov Money. Aucune saisie supplémentaire côté marchand — le callback reste la source de vérité.

<Note>
  Affichez un message d'attente clair après soumission. Le push USSD arrive sur le téléphone du client en quelques secondes, mais le callback peut prendre de quelques secondes à plusieurs minutes selon l'opérateur.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Moov. Aucun OTP à collecter.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez :

    > *« Validez le paiement sur votre téléphone. Vous allez recevoir une demande USSD à approuver avec votre code PIN Moov Money. »*

    Maintenez l'état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22870000000",
          "customer_firstname": "Komi",
          "customer_lastname": "Agbeko",
          "customer_email": "komi@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00054"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "22870000000",
            customer_firstname: "Komi",
            customer_lastname: "Agbeko",
            customer_email: "komi@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00054" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "22870000000",
        "customer_firstname" => "Komi",
        "customer_lastname" => "Agbeko",
        "customer_email" => "komi@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00054"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur  |
| ------------------ | ------- |
| Montant minimum    | 100 XOF |
| Montant maximum    | --      |
| Limite quotidienne | --      |

## Pages associées

* [Modes de validation — USSD Push](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# MTN Mobile Money — Bénin
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/mtn-benin

Intégrer MTN Mobile Money Bénin avec l'API LigdiCash. Mode de validation : USSD Push.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Bénin                                            |
| Opérateur          | MTN Mobile Money Bénin                           |
| `operator_id`      | `1`                                              |
| `operator_name`    | `MTN BENIN`                                      |
| Indicatif          | +229                                             |
| Format du numéro   | `229XXXXXXXX` (sans `+` ni espaces)              |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD Push                                        |

## Mode de validation : USSD Push

Après votre requête, l'opérateur envoie un push USSD directement sur le téléphone du client. Le client valide avec son code PIN MoMo. Aucune saisie supplémentaire côté marchand — le callback reste la source de vérité.

<Note>
  Affichez un message d'attente clair après soumission. Le push USSD arrive sur le téléphone du client en quelques secondes, mais le callback peut prendre de quelques secondes à plusieurs minutes selon l'opérateur.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone MTN. Aucun OTP à collecter.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez :

    > *« Validez le paiement sur votre téléphone. Vous allez recevoir une demande USSD à approuver avec votre code PIN MoMo. »*

    Maintenez l'état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22996000000",
          "customer_firstname": "Mawuena",
          "customer_lastname": "Kpodo",
          "customer_email": "mawuena@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00068"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "22996000000",
            customer_firstname: "Mawuena",
            customer_lastname: "Kpodo",
            customer_email: "mawuena@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00068" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "22996000000",
        "customer_firstname" => "Mawuena",
        "customer_lastname" => "Kpodo",
        "customer_email" => "mawuena@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00068"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur  |
| ------------------ | ------- |
| Montant minimum    | 100 XOF |
| Montant maximum    | --      |
| Limite quotidienne | --      |

## Pages associées

* [Modes de validation — USSD Push](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# MTN Mobile Money — Côte d'Ivoire
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/mtn-cote-divoire

Intégrer MTN Mobile Money Côte d'Ivoire avec l'API LigdiCash. Mode de validation : USSD guidé.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Côte d'Ivoire                                    |
| Opérateur          | MTN Mobile Money Côte d'Ivoire                   |
| `operator_id`      | `15`                                             |
| `operator_name`    | `MTN CI`                                         |
| Indicatif          | +225                                             |
| Format du numéro   | `225XXXXXXXXXX` (sans `+` ni espaces)            |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD guidé                                       |

## Mode de validation : USSD guidé

Après votre requête, MTN envoie un SMS au client contenant la référence de la transaction et le code USSD à composer pour approuver le paiement. Le client compose ce code sur son téléphone — il accède à un menu USSD qui lui demande de confirmer avec son code PIN MoMo. Aucune saisie supplémentaire côté marchand : le callback reste la source de vérité.

**Exemple de SMS reçu par le client :**

```text theme={null}
Vous avez reçu une demande de débit avec la référence 1692100357.
Tapez *133# puis choisissez l'option retrait pour approuver.
```

<Note>
  Le SMS arrive en quelques secondes mais le client peut prendre plusieurs minutes pour le lire et composer le USSD. Conservez l'état d'attente jusqu'à la réception du callback.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone MTN. Aucun OTP à collecter à ce stade.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez :

    > *« Vous allez recevoir un SMS sur votre téléphone avec les instructions pour valider le paiement. Composez le code USSD indiqué et confirmez avec votre code PIN MoMo. »*

    Maintenez l'état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "2250505000000",
          "customer_firstname": "Aïssata",
          "customer_lastname": "Bamba",
          "customer_email": "aissata@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00056"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "2250505000000",
            customer_firstname: "Aïssata",
            customer_lastname: "Bamba",
            customer_email: "aissata@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00056" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "2250505000000",
        "customer_firstname" => "Aïssata",
        "customer_lastname" => "Bamba",
        "customer_email" => "aissata@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00056"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur |
| ------------------ | ------ |
| Montant minimum    | 10 XOF |
| Montant maximum    | --     |
| Limite quotidienne | --     |

## Pages associées

* [Modes de validation — USSD guidé](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# MTN Mobile Money — Guinée Conakry
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/mtn-guinee

Intégrer MTN Mobile Money Guinée Conakry avec l'API LigdiCash. Mode de validation : Redirection LigdiCash (page de paiement pré-filtrée).

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Guinée Conakry                                   |
| Opérateur          | MTN Mobile Money Guinée                          |
| `operator_id`      | `51`                                             |
| `operator_name`    | `MTN GUINEE`                                     |
| Indicatif          | +224                                             |
| Format du numéro   | `224XXXXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | Redirection LigdiCash                            |

## Mode de validation : Redirection LigdiCash

Pour MTN Mobile Money Guinée, l'intégration LigdiCash passe actuellement par une **page web LigdiCash dédiée**, plutôt que par un traitement direct via l'API. Le flux est le suivant :

1. Vous appelez `/pay/v01/straight/checkout-invoice/create` avec le numéro du client dans `customer` et `otp: ""`.
2. LigdiCash répond avec le `token` de transaction et un champ `response_text` qui contient **l'URL d'une page de paiement LigdiCash** où le numéro est prérempli et où seul MTN Guinée est proposé.
3. Vous redirigez le navigateur du client vers cette URL.
4. Le client confirme le paiement depuis la page LigdiCash et le paiement procède selon le flux propre à l'opérateur.
5. LigdiCash vous notifie le résultat final via votre `callback_url`.

<Warning>
  Le préremplissage de `customer` avec le numéro du client est **obligatoire**. Sans `customer`, le filtrage par numéro ne fonctionne pas et la page de paiement n'affichera pas MTN Guinée correctement.
</Warning>

<Note>
  Ce mode utilise bien l'endpoint `/straight/checkout-invoice/create` (payin sans redirection). Ne pas confondre avec le [payin avec redirection](/api-paiement/payin-redirect/introduction), qui utilise un endpoint distinct et expose une page de paiement multi-opérateurs.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille le numéro de téléphone MTN Guinée.
  </Step>

  <Step title="Soumettre la requête">
    Requête sur `POST /pay/v01/straight/checkout-invoice/create` avec `customer` rempli et `otp: ""`.
  </Step>

  <Step title="Récupérer l'URL de la page LigdiCash">
    Dans la réponse, le champ `response_text` contient l'URL de la page de paiement LigdiCash dédiée.
  </Step>

  <Step title="Rediriger le client">
    Redirigez le navigateur du client vers cette URL. La page affiche le numéro prérempli et MTN Guinée pré-sélectionné.
  </Step>

  <Step title="Attendre le callback">
    Le résultat final arrive via votre `callback_url`. Affichez un état d'attente — ne vous fiez pas au retour navigateur.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "224620000000",
          "customer_firstname": "Mamadou",
          "customer_lastname": "Bah",
          "customer_email": "mamadou@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00058"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "224620000000",
            customer_firstname: "Mamadou",
            customer_lastname: "Bah",
            customer_email: "mamadou@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00058" },
        },
      }),
    }
  );

  const data = await response.json();
  // Redirigez le client vers la page de paiement LigdiCash
  window.location.href = data.response_text;
  ```

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "224620000000",
        "customer_firstname" => "Mamadou",
        "customer_lastname" => "Bah",
        "customer_email" => "mamadou@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00058"],
    ],
  ];

  $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);
  // Redirigez le client vers la page de paiement LigdiCash
  header("Location: " . $data["response_text"]);
  ```
</CodeGroup>

## Réponse attendue

```json theme={null}
{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1Qi...",
  "response_text": "https://app.ligdicash.com/pay/.../checkout/...",
  "description": "",
  "custom_data": {
    "transaction_id": "ORD-2025-00058"
  },
  "wiki": "https://client.ligdicash.com/wiki/createInvoice"
}
```

Redirigez le client vers l'URL contenue dans `response_text`. La page de paiement n'affichera que MTN Mobile Money Guinée avec le numéro prérempli.

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur  |
| ------------------ | ------- |
| Montant minimum    | 200 XOF |
| Montant maximum    | --      |
| Limite quotidienne | --      |

## Pages associées

* [Modes de validation — Redirection LigdiCash](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Orange Money — Burkina Faso
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/orange-burkina

Intégrer Orange Money Burkina Faso avec l'API LigdiCash. Mode de validation : OTP USSD.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Burkina Faso                                     |
| Opérateur          | Orange Burkina                                   |
| `operator_id`      | `11`                                             |
| `operator_name`    | `ORANGE BURKINA`                                 |
| Indicatif          | +226                                             |
| Format du numéro   | `22670XXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | OTP USSD                                         |

## Mode de validation : OTP USSD

Le client génère son OTP en composant le code USSD `*144*4*6#` sur son téléphone **avant de vous le communiquer**. Vous soumettez une seule requête avec le numéro et l'OTP. L'opérateur valide la transaction côté réseau — ce traitement peut prendre quelques secondes à plusieurs minutes. Le callback est la source de vérité.

<Note>
  Affichez le code USSD à composer (`*144*4*6#`) avec des instructions claires avant que le client ne remplisse le formulaire. L'OTP généré a une durée de validité courte — invitez le client à le saisir immédiatement.
</Note>

## UX recommandée

<Steps>
  <Step title="Afficher les instructions USSD">
    Avant tout formulaire, indiquez au client de composer `*144*4*6#` sur son téléphone Orange. Un code OTP à usage unique s'affiche sur son écran.
  </Step>

  <Step title="Collecter le numéro et l'OTP">
    Votre formulaire recueille en même temps :

    * le numéro de téléphone Orange au format `22670XXXXXXX`
    * le code OTP reçu via USSD
  </Step>

  <Step title="Soumettre la requête">
    Une seule requête API avec `customer` et `otp` renseignés.
  </Step>

  <Step title="Afficher un indicateur d'attente">
    La validation par l'opérateur peut prendre de quelques secondes à plusieurs minutes. Affichez un état d'attente et attendez le callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22670000000",
          "customer_firstname": "Amadou",
          "customer_lastname": "Diallo",
          "customer_email": "amadou@exemple.com",
          "external_id": "",
          "otp": "123456"
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "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/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: "Abonnement Pro — Janvier 2025",
            customer: "22670000000",
            customer_firstname: "Amadou",
            customer_lastname: "Diallo",
            customer_email: "amadou@exemple.com",
            external_id: "",
            otp: "123456",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            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" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "22670000000",
        "customer_firstname" => "Amadou",
        "customer_lastname" => "Diallo",
        "customer_email" => "amadou@exemple.com",
        "external_id" => "",
        "otp" => "123456",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur        |
| ------------------ | ------------- |
| Montant minimum    | 10 XOF        |
| Montant maximum    | 2 000 000 XOF |
| Limite quotidienne | --            |

## Pages associées

* [Modes de validation — OTP USSD](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Orange Money — Côte d'Ivoire
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/orange-cote-divoire

Intégrer Orange Money Côte d'Ivoire avec l'API LigdiCash. Mode de validation : Redirection opérateur (portail Orange Money).

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Côte d'Ivoire                                    |
| Opérateur          | Orange Money Côte d'Ivoire                       |
| `operator_id`      | `16`                                             |
| `operator_name`    | `ORANGE CI`                                      |
| Indicatif          | +225                                             |
| Format du numéro   | `225XXXXXXXXXX` (sans `+` ni espaces)            |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | Redirection opérateur                            |

## Mode de validation : Redirection opérateur

Pour Orange Money Côte d'Ivoire, l'intégration LigdiCash passe par **le portail web d'Orange Money** pour authentifier le client. Le flux est le suivant :

1. Vous appelez `/pay/v01/straight/checkout-invoice/create` avec le numéro du client.
2. LigdiCash répond avec le `token` de transaction et un champ `response_text` qui contient **l'URL du portail Orange Money** (`https://mpayment.orange-money.com/ci/...`).
3. Vous redirigez le navigateur du client vers cette URL.
4. Le client s'authentifie et confirme le paiement sur le portail Orange.
5. LigdiCash vous notifie le résultat final via votre `callback_url`.

<Warning>
  Le retour navigateur du client après le portail Orange n'est pas garanti — l'utilisateur peut fermer l'onglet, perdre le réseau, ou ne jamais revenir. **Le callback reste la seule source de vérité.** Ne validez jamais le paiement uniquement sur le retour du client.
</Warning>

<Note>
  Ce mode utilise bien l'endpoint `/straight/checkout-invoice/create` (payin sans redirection), mais le parcours utilisateur inclut une redirection externe vers le portail de l'opérateur. Ne pas confondre avec le [payin avec redirection](/api-paiement/payin-redirect/introduction), qui utilise l'endpoint `/redirect/checkout-invoice/create` et expose la page de paiement LigdiCash.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Orange Money CI.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Récupérer l'URL du portail">
    Dans la réponse, le champ `response_text` contient l'URL du portail Orange Money (`https://mpayment.orange-money.com/ci/...`).
  </Step>

  <Step title="Rediriger le client">
    Redirigez le navigateur du client vers cette URL. Le client s'authentifie sur le portail Orange et confirme le paiement.
  </Step>

  <Step title="Attendre le callback">
    Le résultat final arrive via votre `callback_url`. Affichez un état d'attente jusqu'à réception du callback — ne vous fiez pas au retour navigateur.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "2250707000000",
          "customer_firstname": "Aya",
          "customer_lastname": "Kouassi",
          "customer_email": "aya@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00061"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "2250707000000",
            customer_firstname: "Aya",
            customer_lastname: "Kouassi",
            customer_email: "aya@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00061" },
        },
      }),
    }
  );

  const data = await response.json();
  // Redirigez le client vers le portail Orange
  window.location.href = data.response_text;
  ```

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "2250707000000",
        "customer_firstname" => "Aya",
        "customer_lastname" => "Kouassi",
        "customer_email" => "aya@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00061"],
    ],
  ];

  $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);
  // Redirigez le client vers le portail Orange
  header("Location: " . $data["response_text"]);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "response_text": "https://mpayment.orange-money.com/ci/mpayment/abstract/v1nd8lrkjniiezp3gus76kvmlgztvuylkcs2y5kiir6stko13emvuabrv95oaufb",
    "description": "",
    "custom_data": {
      "transaction_id": "ORD-2025-00061",
      "logfile": "202605111744086a021568f2037"
    },
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur |
| ------------------ | ------ |
| Montant minimum    | 10 XOF |
| Montant maximum    | --     |
| Limite quotidienne | --     |

## Pages associées

* [Modes de validation — Redirection opérateur](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Orange Money — Guinée Conakry
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/orange-guinee

Intégrer Orange Money Guinée Conakry avec l'API LigdiCash. Mode de validation : Redirection LigdiCash (page de paiement pré-filtrée).

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Guinée Conakry                                   |
| Opérateur          | Orange Money Guinée                              |
| `operator_id`      | `33`                                             |
| `operator_name`    | `ORANGE GUINEE`                                  |
| Indicatif          | +224                                             |
| Format du numéro   | `224XXXXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | Redirection LigdiCash                            |

## Mode de validation : Redirection LigdiCash

Pour Orange Money Guinée, l'intégration LigdiCash passe actuellement par une **page web LigdiCash dédiée**, plutôt que par un traitement direct via l'API. Le flux est le suivant :

1. Vous appelez `/pay/v01/straight/checkout-invoice/create` avec le numéro du client dans `customer` et `otp: ""`.
2. LigdiCash répond avec le `token` de transaction et un champ `response_text` qui contient **l'URL d'une page de paiement LigdiCash** où le numéro est prérempli et où seul Orange Guinée est proposé.
3. Vous redirigez le navigateur du client vers cette URL.
4. Le client confirme le paiement depuis la page LigdiCash et le paiement procède selon le flux propre à l'opérateur.
5. LigdiCash vous notifie le résultat final via votre `callback_url`.

<Warning>
  Le préremplissage de `customer` avec le numéro du client est **obligatoire**. Sans `customer`, le filtrage par numéro ne fonctionne pas et la page de paiement n'affichera pas Orange Guinée correctement.
</Warning>

<Note>
  Ce mode utilise bien l'endpoint `/straight/checkout-invoice/create` (payin sans redirection). Ne pas confondre avec le [payin avec redirection](/api-paiement/payin-redirect/introduction), qui utilise un endpoint distinct et expose une page de paiement multi-opérateurs.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille le numéro de téléphone Orange Money Guinée.
  </Step>

  <Step title="Soumettre la requête">
    Requête sur `POST /pay/v01/straight/checkout-invoice/create` avec `customer` rempli et `otp: ""`.
  </Step>

  <Step title="Récupérer l'URL de la page LigdiCash">
    Dans la réponse, le champ `response_text` contient l'URL de la page de paiement LigdiCash dédiée.
  </Step>

  <Step title="Rediriger le client">
    Redirigez le navigateur du client vers cette URL. La page affiche le numéro prérempli et Orange Guinée pré-sélectionné.
  </Step>

  <Step title="Attendre le callback">
    Le résultat final arrive via votre `callback_url`. Affichez un état d'attente — ne vous fiez pas au retour navigateur.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "224660000000",
          "customer_firstname": "Fatoumata",
          "customer_lastname": "Diallo",
          "customer_email": "fatoumata@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00059"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "224660000000",
            customer_firstname: "Fatoumata",
            customer_lastname: "Diallo",
            customer_email: "fatoumata@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00059" },
        },
      }),
    }
  );

  const data = await response.json();
  // Redirigez le client vers la page de paiement LigdiCash
  window.location.href = data.response_text;
  ```

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "224660000000",
        "customer_firstname" => "Fatoumata",
        "customer_lastname" => "Diallo",
        "customer_email" => "fatoumata@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00059"],
    ],
  ];

  $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);
  // Redirigez le client vers la page de paiement LigdiCash
  header("Location: " . $data["response_text"]);
  ```
</CodeGroup>

## Réponse attendue

```json theme={null}
{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1Qi...",
  "response_text": "https://app.ligdicash.com/pay/.../checkout/...",
  "description": "",
  "custom_data": {
    "transaction_id": "ORD-2025-00059"
  },
  "wiki": "https://client.ligdicash.com/wiki/createInvoice"
}
```

Redirigez le client vers l'URL contenue dans `response_text`. La page de paiement n'affichera que Orange Money Guinée avec le numéro prérempli.

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur  |
| ------------------ | ------- |
| Montant minimum    | 200 XOF |
| Montant maximum    | --      |
| Limite quotidienne | --      |

## Pages associées

* [Modes de validation — Redirection LigdiCash](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Orange Money — Mali
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/orange-mali

Intégrer Orange Money Mali avec l'API LigdiCash. Mode de validation : Redirection opérateur (portail Orange Money).

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Mali                                             |
| Opérateur          | Orange Money Mali                                |
| `operator_id`      | `18`                                             |
| `operator_name`    | `ORANGE MALI`                                    |
| Indicatif          | +223                                             |
| Format du numéro   | `223XXXXXXXX` (sans `+` ni espaces)              |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | Redirection opérateur                            |

## Mode de validation : Redirection opérateur

Pour Orange Money Mali, l'intégration LigdiCash passe par **le portail web d'Orange Money** pour authentifier le client. Le flux est le suivant :

1. Vous appelez `/pay/v01/straight/checkout-invoice/create` avec le numéro du client.
2. LigdiCash répond avec le `token` de transaction et un champ `response_text` qui contient **l'URL du portail Orange Money** (`https://mpayment.orange-money.com/ml/...`).
3. Vous redirigez le navigateur du client vers cette URL.
4. Le client s'authentifie et confirme le paiement sur le portail Orange.
5. LigdiCash vous notifie le résultat final via votre `callback_url`.

<Warning>
  Le retour navigateur du client après le portail Orange n'est pas garanti — l'utilisateur peut fermer l'onglet, perdre le réseau, ou ne jamais revenir. **Le callback reste la seule source de vérité.** Ne validez jamais le paiement uniquement sur le retour du client.
</Warning>

<Note>
  Ce mode utilise bien l'endpoint `/straight/checkout-invoice/create` (payin sans redirection), mais le parcours utilisateur inclut une redirection externe vers le portail de l'opérateur. Ne pas confondre avec le [payin avec redirection](/api-paiement/payin-redirect/introduction), qui utilise l'endpoint `/redirect/checkout-invoice/create` et expose la page de paiement LigdiCash.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Orange Money Mali.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Récupérer l'URL du portail">
    Dans la réponse, le champ `response_text` contient l'URL du portail Orange Money (`https://mpayment.orange-money.com/ml/...`).
  </Step>

  <Step title="Rediriger le client">
    Redirigez le navigateur du client vers cette URL. Le client s'authentifie sur le portail Orange et confirme le paiement.
  </Step>

  <Step title="Attendre le callback">
    Le résultat final arrive via votre `callback_url`. Affichez un état d'attente jusqu'à réception du callback — ne vous fiez pas au retour navigateur.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22370000000",
          "customer_firstname": "Ibrahim",
          "customer_lastname": "Traoré",
          "customer_email": "ibrahim@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00062"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "22370000000",
            customer_firstname: "Ibrahim",
            customer_lastname: "Traoré",
            customer_email: "ibrahim@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00062" },
        },
      }),
    }
  );

  const data = await response.json();
  // Redirigez le client vers le portail Orange
  window.location.href = data.response_text;
  ```

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "22370000000",
        "customer_firstname" => "Ibrahim",
        "customer_lastname" => "Traoré",
        "customer_email" => "ibrahim@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00062"],
    ],
  ];

  $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);
  // Redirigez le client vers le portail Orange
  header("Location: " . $data["response_text"]);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "response_text": "https://mpayment.orange-money.com/ml/mpayment/abstract/v1nd8lrkjniiezp3gus76kvmlgztvuylkcs2y5kiir6stko13emvuabrv95oaufb",
    "description": "",
    "custom_data": {
      "transaction_id": "ORD-2025-00062",
      "logfile": "202605111744086a021568f2037"
    },
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur  |
| ------------------ | ------- |
| Montant minimum    | 100 XOF |
| Montant maximum    | --      |
| Limite quotidienne | --      |

## Pages associées

* [Modes de validation — Redirection opérateur](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Orange Money — RD Congo
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/orange-rdc

Intégrer Orange Money RD Congo avec l'API LigdiCash. Mode de validation : Redirection LigdiCash (page de paiement pré-filtrée).

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | RD Congo                                         |
| Opérateur          | Orange Money RD Congo                            |
| `operator_id`      | `34`                                             |
| `operator_name`    | `ORANGE RDC CONGO`                               |
| Indicatif          | +243                                             |
| Format du numéro   | `243XXXXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | Redirection LigdiCash                            |

## Mode de validation : Redirection LigdiCash

Pour Orange Money RD Congo, l'intégration LigdiCash passe actuellement par une **page web LigdiCash dédiée**, plutôt que par un traitement direct via l'API. Le flux est le suivant :

1. Vous appelez `/pay/v01/straight/checkout-invoice/create` avec le numéro du client dans `customer` et `otp: ""`.
2. LigdiCash répond avec le `token` de transaction et un champ `response_text` qui contient **l'URL d'une page de paiement LigdiCash** où le numéro est prérempli et où seul Orange RDC est proposé.
3. Vous redirigez le navigateur du client vers cette URL.
4. Le client confirme le paiement depuis la page LigdiCash et le paiement procède selon le flux propre à l'opérateur.
5. LigdiCash vous notifie le résultat final via votre `callback_url`.

<Warning>
  Le préremplissage de `customer` avec le numéro du client est **obligatoire**. Sans `customer`, le filtrage par numéro ne fonctionne pas et la page de paiement n'affichera pas Orange RDC correctement.
</Warning>

<Note>
  Ce mode utilise bien l'endpoint `/straight/checkout-invoice/create` (payin sans redirection). Ne pas confondre avec le [payin avec redirection](/api-paiement/payin-redirect/introduction), qui utilise un endpoint distinct et expose une page de paiement multi-opérateurs.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille le numéro de téléphone Orange Money RDC.
  </Step>

  <Step title="Soumettre la requête">
    Requête sur `POST /pay/v01/straight/checkout-invoice/create` avec `customer` rempli et `otp: ""`.
  </Step>

  <Step title="Récupérer l'URL de la page LigdiCash">
    Dans la réponse, le champ `response_text` contient l'URL de la page de paiement LigdiCash dédiée.
  </Step>

  <Step title="Rediriger le client">
    Redirigez le navigateur du client vers cette URL. La page affiche le numéro prérempli et Orange RDC pré-sélectionné.
  </Step>

  <Step title="Attendre le callback">
    Le résultat final arrive via votre `callback_url`. Affichez un état d'attente — ne vous fiez pas au retour navigateur.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "243850000000",
          "customer_firstname": "Joseph",
          "customer_lastname": "Mwamba",
          "customer_email": "joseph@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00057"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "243850000000",
            customer_firstname: "Joseph",
            customer_lastname: "Mwamba",
            customer_email: "joseph@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00057" },
        },
      }),
    }
  );

  const data = await response.json();
  // Redirigez le client vers la page de paiement LigdiCash
  window.location.href = data.response_text;
  ```

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "243850000000",
        "customer_firstname" => "Joseph",
        "customer_lastname" => "Mwamba",
        "customer_email" => "joseph@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00057"],
    ],
  ];

  $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);
  // Redirigez le client vers la page de paiement LigdiCash
  header("Location: " . $data["response_text"]);
  ```
</CodeGroup>

## Réponse attendue

```json theme={null}
{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1Qi...",
  "response_text": "https://app.ligdicash.com/pay/.../checkout/...",
  "description": "",
  "custom_data": {
    "transaction_id": "ORD-2025-00057"
  },
  "wiki": "https://client.ligdicash.com/wiki/createInvoice"
}
```

Redirigez le client vers l'URL contenue dans `response_text`. La page de paiement n'affichera que Orange Money RDC avec le numéro prérempli.

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur |
| ------------------ | ------ |
| Montant minimum    | 10 XOF |
| Montant maximum    | --     |
| Limite quotidienne | --     |

## Pages associées

* [Modes de validation — Redirection LigdiCash](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Orange Money — Sénégal
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/orange-senegal

Intégrer Orange Money Sénégal avec l'API LigdiCash. Mode de validation : Redirection LigdiCash (page de paiement pré-filtrée).

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Sénégal                                          |
| Opérateur          | Orange Money Sénégal                             |
| `operator_id`      | `31`                                             |
| `operator_name`    | `ORANGE SENEGAL`                                 |
| Indicatif          | +221                                             |
| Format du numéro   | `221XXXXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | Redirection LigdiCash                            |

## Mode de validation : Redirection LigdiCash

Pour Orange Money Sénégal, l'intégration LigdiCash passe actuellement par une **page web LigdiCash dédiée**, plutôt que par un traitement direct via l'API. Le flux est le suivant :

1. Vous appelez `/pay/v01/straight/checkout-invoice/create` avec le numéro du client dans `customer` et `otp: ""`.
2. LigdiCash répond avec le `token` de transaction et un champ `response_text` qui contient **l'URL d'une page de paiement LigdiCash** où le numéro est prérempli et où seul Orange Sénégal est proposé.
3. Vous redirigez le navigateur du client vers cette URL.
4. Le client confirme le paiement depuis la page LigdiCash et le paiement procède selon le flux propre à l'opérateur.
5. LigdiCash vous notifie le résultat final via votre `callback_url`.

<Warning>
  Le préremplissage de `customer` avec le numéro du client est **obligatoire**. Sans `customer`, le filtrage par numéro ne fonctionne pas et la page de paiement n'affichera pas Orange Sénégal correctement.
</Warning>

<Note>
  Ce mode utilise bien l'endpoint `/straight/checkout-invoice/create` (payin sans redirection). Ne pas confondre avec le [payin avec redirection](/api-paiement/payin-redirect/introduction), qui utilise un endpoint distinct et expose une page de paiement multi-opérateurs.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille le numéro de téléphone Orange Money Sénégal.
  </Step>

  <Step title="Soumettre la requête">
    Requête sur `POST /pay/v01/straight/checkout-invoice/create` avec `customer` rempli et `otp: ""`.
  </Step>

  <Step title="Récupérer l'URL de la page LigdiCash">
    Dans la réponse, le champ `response_text` contient l'URL de la page de paiement LigdiCash dédiée.
  </Step>

  <Step title="Rediriger le client">
    Redirigez le navigateur du client vers cette URL. La page affiche le numéro prérempli et Orange Sénégal pré-sélectionné.
  </Step>

  <Step title="Attendre le callback">
    Le résultat final arrive via votre `callback_url`. Affichez un état d'attente — ne vous fiez pas au retour navigateur.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "221770000000",
          "customer_firstname": "Awa",
          "customer_lastname": "Ndiaye",
          "customer_email": "awa@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00060"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "221770000000",
            customer_firstname: "Awa",
            customer_lastname: "Ndiaye",
            customer_email: "awa@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00060" },
        },
      }),
    }
  );

  const data = await response.json();
  // Redirigez le client vers la page de paiement LigdiCash
  window.location.href = data.response_text;
  ```

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "221770000000",
        "customer_firstname" => "Awa",
        "customer_lastname" => "Ndiaye",
        "customer_email" => "awa@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00060"],
    ],
  ];

  $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);
  // Redirigez le client vers la page de paiement LigdiCash
  header("Location: " . $data["response_text"]);
  ```
</CodeGroup>

## Réponse attendue

```json theme={null}
{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1Qi...",
  "response_text": "https://app.ligdicash.com/pay/.../checkout/...",
  "description": "",
  "custom_data": {
    "transaction_id": "ORD-2025-00060"
  },
  "wiki": "https://client.ligdicash.com/wiki/createInvoice"
}
```

Redirigez le client vers l'URL contenue dans `response_text`. La page de paiement n'affichera que Orange Money Sénégal avec le numéro prérempli.

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur |
| ------------------ | ------ |
| Montant minimum    | --     |
| Montant maximum    | --     |
| Limite quotidienne | --     |

## Pages associées

* [Modes de validation — Redirection LigdiCash](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Vodacom — RD Congo
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/vodacom-rdc

Intégrer Vodacom RD Congo (M-Pesa) avec l'API LigdiCash. Mode de validation : USSD Push.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | RD Congo                                         |
| Opérateur          | Vodacom RDC (M-Pesa)                             |
| `operator_id`      | `36`                                             |
| `operator_name`    | `VODACOM RDC CONGO`                              |
| Indicatif          | +243                                             |
| Format du numéro   | `243XXXXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD Push                                        |

## Mode de validation : USSD Push

Après votre requête, l'opérateur envoie un push USSD directement sur le téléphone du client. Le client valide avec son code PIN. Aucune saisie supplémentaire côté marchand — le callback reste la source de vérité.

<Note>
  Affichez un message d'attente clair après soumission. Le push USSD arrive sur le téléphone du client en quelques secondes, mais le callback peut prendre de quelques secondes à plusieurs minutes selon l'opérateur.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Vodacom. Aucun OTP à collecter.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez :

    > *« Validez le paiement sur votre téléphone. Vous allez recevoir une demande USSD à approuver avec votre code PIN M-Pesa. »*

    Maintenez l'état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "243810000000",
          "customer_firstname": "Jean",
          "customer_lastname": "Mukendi",
          "customer_email": "jean@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00050"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "243810000000",
            customer_firstname: "Jean",
            customer_lastname: "Mukendi",
            customer_email: "jean@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00050" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "243810000000",
        "customer_firstname" => "Jean",
        "customer_lastname" => "Mukendi",
        "customer_email" => "jean@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00050"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur |
| ------------------ | ------ |
| Montant minimum    | 10 XOF |
| Montant maximum    | --     |
| Limite quotidienne | --     |

## Pages associées

* [Modes de validation — USSD Push](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Wallet LigdiCash
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/wallet-ligdicash

Intégrer le paiement via wallet LigdiCash. Mode de validation : OTP SMS. Deux endpoints distincts : /v02/debitotp et /v02/debitwallet/withotp.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Opérateur          | Wallet LigdiCash                                 |
| `operator_id`      | -                                                |
| `operator_name`    | LIGDICASH \[NOM\_OPERATEUR]                      |
| Format du numéro   | `indicatif` + numéro local (sans `+` ni espaces) |
| Mode de validation | OTP SMS                                          |

<Note>
  Le Wallet LigdiCash utilise deux endpoints distincts des autres opérateurs (`/v02`). Le flux est différent : un premier appel déclenche l'envoi de l'OTP, un second appel soumet la transaction avec l'OTP.
</Note>

## Mode de validation : OTP SMS

Le client reçoit un code OTP sur son application ou par SMS LigdiCash après votre première requête. Il vous communique ce code. Vous soumettez ensuite une seconde requête avec l'OTP pour finaliser la transaction.

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille le numéro de téléphone associé au compte LigdiCash du client.
  </Step>

  <Step title="Envoyer l'OTP — première requête">
    Appelez `GET /pay/v02/debitotp/{phone_number}/{amount}`. LigdiCash envoie un OTP au client.
  </Step>

  <Step title="Afficher le champ OTP">
    Après confirmation de l'envoi (`"error": false`), affichez un champ de saisie pour l'OTP. Indiquez au client de vérifier son application ou ses SMS LigdiCash.
  </Step>

  <Step title="Soumettre avec l'OTP — seconde requête">
    Appelez `POST /pay/v02/debitwallet/withotp` avec le numéro dans `customer` et l'OTP dans `otp`.
  </Step>

  <Step title="Attendre le callback">
    Affichez un indicateur d'attente. La confirmation arrive via votre `callback_url`.
  </Step>
</Steps>

## Étape 1 — Envoyer l'OTP

```
GET https://app.ligdicash.com/pay/v02/debitotp/{phone_number}/{amount}
```

Les paramètres `phone_number` et `amount` sont des **paramètres de chemin** (path parameters), pas un body JSON.

### Headers

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

<ParamField type="string">
  Votre API TOKEN précédé de `Bearer `.
</ParamField>

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

### Paramètres de chemin

<ParamField type="string">
  Numéro de téléphone du client au format `indicatif` + numéro local, sans `+` ni espaces.
</ParamField>

<ParamField type="integer">
  Montant en XOF (entier, sans décimales).
</ParamField>

### Exemple

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.ligdicash.com/pay/v02/debitotp/22670000000/5000" \
    -H "Apikey: {API_KEY}" \
    -H "Authorization: Bearer {API_TOKEN}" \
    -H "Accept: application/json"
  ```

  ```javascript Node.js theme={null}
  const phone = "22670000000";
  const amount = 5000;

  const response = await fetch(
    `https://app.ligdicash.com/pay/v02/debitotp/${phone}/${amount}`,
    {
      method: "GET",
      headers: {
        Apikey: process.env.LIGDICASH_API_KEY,
        Authorization: `Bearer ${process.env.LIGDICASH_API_TOKEN}`,
        Accept: "application/json",
      },
    }
  );

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

  ```php PHP theme={null}
  $phone = "22670000000";
  $amount = 5000;

  $ch = curl_init("https://app.ligdicash.com/pay/v02/debitotp/{$phone}/{$amount}");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Apikey: " . $_ENV["LIGDICASH_API_KEY"],
    "Authorization: Bearer " . $_ENV["LIGDICASH_API_TOKEN"],
    "Accept: application/json",
  ]);

  $data = json_decode(curl_exec($ch), true);
  curl_close($ch);
  ```
</CodeGroup>

### Réponse

```json Succès theme={null}
{
  "error": false,
  "message": "OTP sent. Please check your phone."
}
```

<Warning>
  Vérifiez que `error` vaut `false` avant d'afficher le champ OTP. Si `error` est `true`, affichez un message d'erreur et ne proposez pas la saisie de l'OTP.
</Warning>

***

## Étape 2 — Valider avec l'OTP

```
POST https://app.ligdicash.com/pay/v02/debitwallet/withotp
```

### Headers

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

<ParamField type="string">
  Votre API TOKEN précédé de `Bearer `.
</ParamField>

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

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

### Body

Même structure que l'endpoint `/pay/v01/straight/checkout-invoice/create`, avec `customer` renseigné et `otp` contenant le code reçu par le client.

### Exemple

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.ligdicash.com/pay/v02/debitwallet/withotp \
    -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": "22670000000",
          "customer_firstname": "Amadou",
          "customer_lastname": "Diallo",
          "customer_email": "amadou@exemple.com",
          "external_id": "",
          "otp": "123456"
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "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/v02/debitwallet/withotp",
    {
      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: "22670000000",
            customer_firstname: "Amadou",
            customer_lastname: "Diallo",
            customer_email: "amadou@exemple.com",
            external_id: "",
            otp: "123456",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            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" => "22670000000",
        "customer_firstname" => "Amadou",
        "customer_lastname" => "Diallo",
        "customer_email" => "amadou@exemple.com",
        "external_id" => "",
        "otp" => "123456",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00042"],
    ],
  ];

  $ch = curl_init("https://app.ligdicash.com/pay/v02/debitwallet/withotp");
  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 attendue

<CodeGroup>
  ```json Succès theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "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>

<Warning>
  Stockez le `token` retourné par `/debitwallet/withotp`. C'est lui que vous utiliserez pour appeler `confirm` à la réception du callback.
</Warning>

## Limites

| Paramètre          | Valeur        |
| ------------------ | ------------- |
| Montant minimum    | 10 XOF        |
| Montant maximum    | 2 000 000 XOF |
| Limite quotidienne | --            |

## Pages associées

* [Modes de validation — OTP SMS](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux deux requêtes
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Wave — Sénégal
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/wave-senegal

Intégrer Wave Sénégal avec l'API LigdiCash. Mode de validation : Redirection LigdiCash (page de paiement pré-filtrée).

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Sénégal                                          |
| Opérateur          | Wave Sénégal                                     |
| `operator_id`      | `39`                                             |
| `operator_name`    | `WAVE SENEGAL`                                   |
| Indicatif          | +221                                             |
| Format du numéro   | `221XXXXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | Redirection LigdiCash                            |

## Mode de validation : Redirection LigdiCash

Pour Wave Sénégal, l'intégration LigdiCash passe actuellement par une **page web LigdiCash dédiée**, plutôt que par un traitement direct via l'API. Le flux est le suivant :

1. Vous appelez `/pay/v01/straight/checkout-invoice/create` avec le numéro du client dans `customer` et `otp: ""`.
2. LigdiCash répond avec le `token` de transaction et un champ `response_text` qui contient **l'URL d'une page de paiement LigdiCash** où le numéro est prérempli et où seul Wave Sénégal est proposé.
3. Vous redirigez le navigateur du client vers cette URL.
4. Le client confirme le paiement depuis la page LigdiCash et le paiement procède selon le flux propre à l'opérateur.
5. LigdiCash vous notifie le résultat final via votre `callback_url`.

<Warning>
  Le préremplissage de `customer` avec le numéro du client est **obligatoire**. Sans `customer`, le filtrage par numéro ne fonctionne pas et la page de paiement n'affichera pas Wave Sénégal correctement.
</Warning>

<Note>
  Ce mode utilise bien l'endpoint `/straight/checkout-invoice/create` (payin sans redirection). Ne pas confondre avec le [payin avec redirection](/api-paiement/payin-redirect/introduction), qui utilise un endpoint distinct et expose une page de paiement multi-opérateurs.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille le numéro de téléphone Wave Sénégal.
  </Step>

  <Step title="Soumettre la requête">
    Requête sur `POST /pay/v01/straight/checkout-invoice/create` avec `customer` rempli et `otp: ""`.
  </Step>

  <Step title="Récupérer l'URL de la page LigdiCash">
    Dans la réponse, le champ `response_text` contient l'URL de la page de paiement LigdiCash dédiée.
  </Step>

  <Step title="Rediriger le client">
    Redirigez le navigateur du client vers cette URL. La page affiche le numéro prérempli et Wave Sénégal pré-sélectionné.
  </Step>

  <Step title="Attendre le callback">
    Le résultat final arrive via votre `callback_url`. Affichez un état d'attente — ne vous fiez pas au retour navigateur.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "221770000000",
          "customer_firstname": "Aminata",
          "customer_lastname": "Diop",
          "customer_email": "aminata@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00065"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "221770000000",
            customer_firstname: "Aminata",
            customer_lastname: "Diop",
            customer_email: "aminata@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00065" },
        },
      }),
    }
  );

  const data = await response.json();
  // Redirigez le client vers la page de paiement LigdiCash
  window.location.href = data.response_text;
  ```

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "221770000000",
        "customer_firstname" => "Aminata",
        "customer_lastname" => "Diop",
        "customer_email" => "aminata@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00065"],
    ],
  ];

  $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);
  // Redirigez le client vers la page de paiement LigdiCash
  header("Location: " . $data["response_text"]);
  ```
</CodeGroup>

## Réponse attendue

```json theme={null}
{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1Qi...",
  "response_text": "https://app.ligdicash.com/pay/.../checkout/...",
  "description": "",
  "custom_data": {
    "transaction_id": "ORD-2025-00065"
  },
  "wiki": "https://client.ligdicash.com/wiki/createInvoice"
}
```

Redirigez le client vers l'URL contenue dans `response_text`. La page de paiement n'affichera que Wave Sénégal avec le numéro prérempli.

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur |
| ------------------ | ------ |
| Montant minimum    | --     |
| Montant maximum    | --     |
| Limite quotidienne | --     |

## Pages associées

* [Modes de validation — Redirection LigdiCash](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# YAS — Togo
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/yas-togo

Intégrer YAS Togo (ex-Togocom Mixx by Yas) avec l'API LigdiCash. Mode de validation : USSD Push.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Togo                                             |
| Opérateur          | YAS Togo (Mixx by Yas, ex-Togocom)               |
| `operator_id`      | `3`                                              |
| `operator_name`    | `YAS TOGO`                                       |
| Indicatif          | +228                                             |
| Format du numéro   | `228XXXXXXXX` (sans `+` ni espaces)              |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD Push                                        |

## Mode de validation : USSD Push

Après votre requête, l'opérateur envoie un push USSD directement sur le téléphone du client. Le client valide avec son code PIN Mixx by Yas. Aucune saisie supplémentaire côté marchand — le callback reste la source de vérité.

<Note>
  Affichez un message d'attente clair après soumission. Le push USSD arrive sur le téléphone du client en quelques secondes, mais le callback peut prendre de quelques secondes à plusieurs minutes selon l'opérateur.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone YAS. Aucun OTP à collecter.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez :

    > *« Validez le paiement sur votre téléphone. Vous allez recevoir une demande USSD à approuver avec votre code PIN Mixx by Yas. »*

    Maintenez l'état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22890000000",
          "customer_firstname": "Kossi",
          "customer_lastname": "Amah",
          "customer_email": "kossi@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00053"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "22890000000",
            customer_firstname: "Kossi",
            customer_lastname: "Amah",
            customer_email: "kossi@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00053" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "22890000000",
        "customer_firstname" => "Kossi",
        "customer_lastname" => "Amah",
        "customer_email" => "kossi@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00053"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur  |
| ------------------ | ------- |
| Montant minimum    | 100 XOF |
| Montant maximum    | --      |
| Limite quotidienne | --      |

## Pages associées

* [Modes de validation — USSD Push](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Zamani — Niger
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/operateurs/zamani-niger

Intégrer Zamani Telecom Niger (Zamani Money) avec l'API LigdiCash. Mode de validation : USSD guidé.

## Identité

| Champ              | Valeur                                           |
| ------------------ | ------------------------------------------------ |
| Pays               | Niger                                            |
| Opérateur          | Zamani Niger (Zamani Money)                      |
| `operator_id`      | `28`                                             |
| `operator_name`    | `ORANGE/ZAMANI NIGER`                            |
| Indicatif          | +227                                             |
| Format du numéro   | `22790XXXXXXX` (sans `+` ni espaces)             |
| Endpoint           | `POST /pay/v01/straight/checkout-invoice/create` |
| Mode de validation | USSD guidé                                       |

## Mode de validation : USSD guidé

Après votre requête, Zamani envoie un SMS au client contenant le montant du paiement et le code USSD à composer pour approuver. Le client compose ce code sur son téléphone — il accède à un menu USSD qui lui demande de confirmer avec son code PIN Zamani Money. Aucune saisie supplémentaire côté marchand : le callback reste la source de vérité.

**Exemple de SMS reçu par le client :**

```text theme={null}
Vous allez faire un retrait de 103.00 FCFA. Veuillez entrer le #146# et suivre les instructions
```

<Note>
  Le SMS arrive en quelques secondes mais le client peut prendre plusieurs minutes pour le lire et composer le USSD. Conservez l'état d'attente jusqu'à la réception du callback.
</Note>

## UX recommandée

<Steps>
  <Step title="Collecter le numéro du client">
    Votre formulaire recueille uniquement le numéro de téléphone Zamani. Aucun OTP à collecter à ce stade.
  </Step>

  <Step title="Soumettre la requête">
    Requête avec le numéro dans `customer` et `otp: ""`.
  </Step>

  <Step title="Afficher un message d'attente">
    Après soumission, affichez :

    > *« Vous allez recevoir un SMS sur votre téléphone avec les instructions pour valider le paiement. Composez le code USSD indiqué et confirmez avec votre code PIN Zamani Money. »*

    Maintenez l'état d'attente jusqu'à la réception du callback.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  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": "Abonnement Pro — Janvier 2025",
          "customer": "22790000001",
          "customer_firstname": "Mariama",
          "customer_lastname": "Soumana",
          "customer_email": "mariama@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "MonApp",
          "website_url": "https://monapp.com"
        },
        "actions": {
          "cancel_url": "",
          "return_url": "",
          "callback_url": "https://monapp.com/api/callback/ligdicash"
        },
        "custom_data": {
          "transaction_id": "ORD-2025-00064"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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: "Abonnement Pro — Janvier 2025",
            customer: "22790000001",
            customer_firstname: "Mariama",
            customer_lastname: "Soumana",
            customer_email: "mariama@exemple.com",
            external_id: "",
            otp: "",
          },
          store: { name: "MonApp", website_url: "https://monapp.com" },
          actions: {
            cancel_url: "",
            return_url: "",
            callback_url: "https://monapp.com/api/callback/ligdicash",
          },
          custom_data: { transaction_id: "ORD-2025-00064" },
        },
      }),
    }
  );

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

  ```php PHP theme={null}
  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "22790000001",
        "customer_firstname" => "Mariama",
        "customer_lastname" => "Soumana",
        "customer_email" => "mariama@exemple.com",
        "external_id" => "",
        "otp" => "",
      ],
      "store" => ["name" => "MonApp", "website_url" => "https://monapp.com"],
      "actions" => [
        "cancel_url" => "",
        "return_url" => "",
        "callback_url" => "https://monapp.com/api/callback/ligdicash",
      ],
      "custom_data" => ["transaction_id" => "ORD-2025-00064"],
    ],
  ];

  $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);
  ```
</CodeGroup>

## Réponse attendue

<CodeGroup>
  ```json Succès (create) theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

<Warning>
  Stockez le `token` immédiatement après la création. Utilisez-le pour appeler `confirm` à la réception du callback — ne vous fiez pas au token présent dans le payload du callback.
</Warning>

## Limites

| Paramètre          | Valeur |
| ------------------ | ------ |
| Montant minimum    | 10 XOF |
| Montant maximum    | --     |
| Limite quotidienne | --     |

## Pages associées

* [Modes de validation — USSD guidé](/api-paiement/payin-sans-redirect/modes-validation) — détail du flux
* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — référence complète de l'endpoint
* [Vérifier le statut](/api-paiement/payin-sans-redirect/verifier-statut) — appeler `confirm` après le callback


# Vérifier le statut
Source: https://developers.ligdicash.com/api-paiement/payin-sans-redirect/verifier-statut

Comment et quand appeler l'endpoint confirm après un payin sans redirection. Stratégies de polling selon le mode de validation.

L'endpoint `confirm` est identique à celui du payin avec redirection. La différence est dans **le moment où vous l'appelez** : sans redirection, il n'y a pas de `return_url` pour déclencher une vérification depuis le frontend. Vous devez attendre le callback — c'est lui qui signale la fin du traitement côté opérateur.

```
GET https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken={TOKEN}
```

Pour la référence complète (headers, champs de réponse, payloads réels), consultez [Vérifier le statut — payin avec redirection](/api-paiement/payin-redirect/verifier-statut).

## Quand appeler `confirm`

**Toujours à la réception du callback.** Quel que soit le mode de validation, la confirmation de l'opérateur peut prendre un temps variable — quelques secondes à plusieurs minutes, même quand le client a déjà saisi son OTP. Le callback est le seul signal fiable indiquant que l'opérateur a traité la transaction.

Appelez `confirm` depuis votre handler de callback, avec le token stocké à la création, avant d'honorer la commande.

<Warning>
  Appelez toujours `confirm` avec le **token stocké à la création**, pas celui reçu dans le callback. Les deux tokens permettent d'appeler l'endpoint, mais seul le token de création vous permet de faire la réconciliation avec votre commande.
</Warning>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken={TOKEN}" \
    -H "Apikey: {API_KEY}" \
    -H "Authorization: Bearer {API_TOKEN}" \
    -H "Accept: application/json"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=${token}`,
    {
      method: "GET",
      headers: {
        Apikey: process.env.LIGDICASH_API_KEY,
        Authorization: `Bearer ${process.env.LIGDICASH_API_TOKEN}`,
        Accept: "application/json",
      },
    }
  );

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

  ```php PHP theme={null}
  $ch = curl_init(
    "https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=" . urlencode($token)
  );
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Apikey: " . $_ENV["LIGDICASH_API_KEY"],
    "Authorization: Bearer " . $_ENV["LIGDICASH_API_TOKEN"],
    "Accept: application/json",
  ]);

  $data = json_decode(curl_exec($ch), true);
  curl_close($ch);
  ```
</CodeGroup>

## Valeurs de `status`

| `status`       | Signification                          | Action recommandée                           |
| -------------- | -------------------------------------- | -------------------------------------------- |
| `completed`    | Paiement confirmé                      | Honorer la commande                          |
| `pending`      | En attente de validation par le client | Continuer le polling ou attendre le callback |
| `notcompleted` | Paiement non abouti                    | Proposer de réessayer                        |

## Polling — filet de sécurité uniquement

Si le callback tarde ou n'est pas disponible dans votre environnement, vous pouvez interroger `confirm` à intervalles réguliers. Le statut sera `pending` tant que l'opérateur n'a pas finalisé la transaction :

```javascript JavaScript theme={null}
async function attendreConfirmation(token, { intervalle = 4000, maxTentatives = 15 } = {}) {
  for (let i = 0; i < maxTentatives; i++) {
    const res = await fetch(
      `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=${token}`,
      {
        headers: {
          Apikey: process.env.LIGDICASH_API_KEY,
          Authorization: `Bearer ${process.env.LIGDICASH_API_TOKEN}`,
          Accept: "application/json",
        },
      }
    );
    const data = await res.json();

    if (data.status === "completed") return { success: true, data };
    if (data.status === "notcompleted") return { success: false, data };

    await new Promise((r) => setTimeout(r, intervalle));
  }
  return { success: false, reason: "timeout" };
}
```

<Note>
  Le polling est un filet de sécurité, pas un remplacement du callback. Basez toujours votre logique métier sur le callback. Consultez [Polling vs callback](/api-paiement/verification-statut/polling-vs-callback) pour les arbitrages.
</Note>

## Pages associées

* [Vérifier le statut — référence complète](/api-paiement/payin-redirect/verifier-statut) — champs de réponse détaillés et payloads réels
* [Modes de validation](/api-paiement/payin-sans-redirect/modes-validation) — quand le statut devient `pending`
* [Callback — sécurisation](/api-paiement/callback/securisation) — pourquoi toujours re-vérifier avec `confirm`
* [Polling vs callback](/api-paiement/verification-statut/polling-vs-callback) — choisir la bonne stratégie


# Cas d'usage du payout
Source: https://developers.ligdicash.com/api-paiement/payout/cas-usage

Remboursements, salaires, gains, paiement de prestataires — choisir la bonne méthode payout selon le contexte.

Le choix entre Payout Client et Payout Marchand dépend du destinataire et de la destination finale des fonds. Cette page présente les cas d'usage les plus courants et la méthode recommandée pour chacun.

## Remboursement de commande

Un client demande un remboursement après une annulation ou un retour produit. Vous devez lui reverser le montant payé.

**Méthode recommandée :** Payout Marchand (`/pay/v01/straight/payout`)

Le client n'a pas nécessairement un compte LigdiCash. Le Payout Marchand envoie directement vers son numéro mobile money, sans prérequis de son côté.

<Warning>
  Les frais contractuels LigdiCash s'appliquent à tout payout, y compris les remboursements. Le client ne recevra pas nécessairement le montant exact qu'il a payé. Anticipez cette différence dans votre politique de remboursement.
</Warning>

<Steps>
  <Step title="Récupérer le numéro mobile money du client">
    Utilisez le numéro que le client a fourni lors de son paiement — il est disponible dans le callback du payin d'origine via `operator_id` et `customer`.
  </Step>

  <Step title="Initier le payout">
    Appelez `POST /pay/v01/straight/payout` avec le montant à rembourser et un `transaction_id` lié à la commande d'origine.
  </Step>

  <Step title="Confirmer via callback">
    Attendez le callback sur votre `callback_url`. Une fois `status: "completed"` reçu, mettez à jour le statut de la commande et notifiez le client.
  </Step>
</Steps>

```json Exemple custom_data theme={null}
{
  "transaction_id": "REFUND-ORD-2024-001"
}
```

## Paiement de salaires

Vous devez verser des rémunérations à des employés ou des agents terrain sur leurs comptes mobile money.

**Méthode recommandée :** Payout Marchand (`/pay/v01/straight/payout`)

Les destinataires n'ont pas nécessairement de compte LigdiCash. Le Payout Marchand permet d'envoyer directement vers n'importe quel numéro mobile money.

<Warning>
  Le Payout Marchand n'est pas instantané. Pour des paiements groupés (bulk), envoyez les requêtes en séquence et suivez chaque `token` retourné. Ne considérez un paiement comme finalisé qu'à réception du callback `status: "completed"`.
</Warning>

## Distribution de gains et cashback

Vous souhaitez créditer des gains, des récompenses ou du cashback à vos utilisateurs — qu'ils puissent utiliser sur votre plateforme ou retirer sur leur mobile money.

**Méthode recommandée :** Payout Client (`/pay/v01/withdrawal/create`)

<Tabs>
  <Tab title="Gains utilisables sur la plateforme">
    Utilisez `top_up_wallet: 1` — les fonds arrivent dans le wallet LigdiCash de l'utilisateur. Il peut s'en servir pour payer sur les plateformes LigdiCash. Le retrait vers mobile money reste à son initiative.

    **Idéal pour :** cashback, crédits fidélité, gains de jeu conservés dans l'écosystème LigdiCash.
  </Tab>

  <Tab title="Gains versés directement sur mobile money">
    Utilisez `top_up_wallet: 0` — les fonds arrivent d'abord dans le wallet LigdiCash de l'utilisateur, puis LigdiCash déclenche automatiquement le virement vers son mobile money. L'utilisateur reçoit les fonds sans action de sa part.

    **Idéal pour :** gains de tournois, primes, récompenses que l'utilisateur doit recevoir en cash.
  </Tab>
</Tabs>

## Paiement d'agents et de prestataires

Vous devez régler des freelances, des agents terrain ou des fournisseurs qui ont réalisé une prestation.

**Méthode recommandée :** Payout Marchand (`/pay/v01/straight/payout`)

Les prestataires n'ont généralement pas de compte LigdiCash. Le Payout Marchand envoie directement vers leur numéro mobile money, quel que soit l'opérateur — à condition que le sous-compte correspondant soit approvisionné.

<Note>
  Si vous payez régulièrement vers plusieurs opérateurs différents, surveillez vos soldes par sous-compte depuis le Dashboard LigdiCash. Un payout échoue si le sous-compte de l'opérateur destinataire est insuffisant, même si vos autres sous-comptes sont créditeurs.
</Note>

## Tableau récapitulatif

| Cas d'usage                   | Méthode         | `top_up_wallet` |
| ----------------------------- | --------------- | --------------- |
| Remboursement client          | Payout Marchand | —               |
| Salaires et rémunérations     | Payout Marchand | —               |
| Cashback / crédits plateforme | Payout Client   | `1`             |
| Gains versés sur mobile money | Payout Client   | `0`             |
| Paiement de prestataires      | Payout Marchand | —               |

## Pages associées

* [Payout Client](/api-paiement/payout/vers-wallet-ligdicash)
* [Payout Marchand](/api-paiement/payout/vers-mobile-money)
* [Vérifier le statut d'un payout](/api-paiement/payout/verifier-statut)
* [Le compte marchand LigdiCash](/concepts/compte-marchand)


# Payout — Introduction
Source: https://developers.ligdicash.com/api-paiement/payout/introduction

Envoyez des fonds à vos clients ou prestataires : Payout Client vers un wallet LigdiCash, ou Payout Marchand directement vers un compte mobile money.

Le payout vous permet d'envoyer des fonds depuis votre compte marchand LigdiCash vers un destinataire. Deux méthodes existent selon que le destinataire possède un compte LigdiCash ou non.

## Payout Client vs Payout Marchand

**Payout Client** — vous envoyez vers le numéro de compte LigdiCash du destinataire. Les fonds arrivent instantanément dans son wallet LigdiCash. Vous choisissez ensuite, via le paramètre `top_up_wallet`, si les fonds restent dans son wallet LigdiCash ou si LigdiCash déclenche automatiquement un virement vers son compte mobile money.

**Payout Marchand** — vous envoyez directement vers un numéro mobile money, sans wallet LigdiCash intermédiaire. Cette méthode n'est pas instantanée : le traitement peut prendre de quelques secondes à plusieurs jours selon l'opérateur.

<CardGroup>
  <Card title="Payout Client" icon="wallet" href="/api-paiement/payout/vers-wallet-ligdicash">
    Vers un wallet LigdiCash. Instantané. Avec option de virement automatique vers mobile money.
  </Card>

  <Card title="Payout Marchand" icon="paper-plane" href="/api-paiement/payout/vers-mobile-money">
    Directement vers un numéro mobile money. Non instantané.
  </Card>
</CardGroup>

## Tableau de décision

| Je veux…                                                                                       | Méthode         | `top_up_wallet` |
| ---------------------------------------------------------------------------------------------- | --------------- | --------------- |
| Envoyer vers le wallet LigdiCash du destinataire, il gère son retrait lui-même                 | Payout Client   | `1`             |
| Envoyer vers le wallet LigdiCash du destinataire, LigdiCash vire ensuite vers son mobile money | Payout Client   | `0`             |
| Envoyer directement vers un numéro mobile money (pas de compte LigdiCash requis)               | Payout Marchand | —               |

<Note>
  Avec le Payout Client (`top_up_wallet: 0`), les fonds arrivent toujours d'abord dans le wallet LigdiCash du destinataire — instantanément. C'est le virement automatique subsequent vers son mobile money qui peut prendre du temps.
</Note>

## Comptes marchands et soldes par opérateur

Votre compte marchand LigdiCash est composé de **sous-comptes distincts par opérateur** activé dans votre contrat. Les paiements reçus via Orange Burkina alimentent votre sous-compte Orange Burkina. Ceux reçus via Moov Burkina alimentent votre sous-compte Moov Burkina, et ainsi de suite.

Lors d'un payout, les fonds quittent le sous-compte correspondant à l'opérateur du numéro destinataire.

<Warning>
  Si le sous-compte de l'opérateur concerné n'est pas suffisamment approvisionné, le payout échoue — même si vos autres sous-comptes ont un solde disponible. Assurez-vous que le bon sous-compte est crédité avant d'initier un payout.
</Warning>

## Cas d'usage typiques

* **Remboursements** — rembourser un client après annulation de commande
* **Gains et cashback** — reverser des gains, récompenses ou commissions
* **Paiement de prestataires** — régler des freelances ou partenaires
* **Salaires** — verser des rémunérations vers des comptes mobile money

## Commissions

Chaque payout est soumis aux frais définis dans votre contrat LigdiCash. Ces frais sont systématiquement prélevés par LigdiCash — il n'existe pas de payout à zéro frais. Le montant effectivement reçu par le bénéficiaire peut donc être inférieur au montant envoyé selon la structure tarifaire de votre contrat.

<Warning>
  Anticipez les frais dans votre logique métier. Un remboursement de 5 000 XOF ne reversera pas nécessairement 5 000 XOF au bénéficiaire. Consultez votre contrat LigdiCash pour connaître le barème applicable.
</Warning>

## Prérequis

* Le sous-compte opérateur concerné doit disposer d'un solde suffisant.
* Le payout doit être activé sur votre projet API.
* **Vos adresses IP serveur doivent être whitelistées par LigdiCash.** Les requêtes payout provenant d'adresses IP non whitelistées sont rejetées. Communiquez vos adresses IP à l'équipe LigdiCash avant de commencer l'intégration.

Pour l'activation du payout et le whitelisting de vos IPs, contactez [developper@ligdicash.com](mailto:developper@ligdicash.com).

## Dans cette section

<CardGroup>
  <Card title="Payout Client" icon="wallet" href="/api-paiement/payout/vers-wallet-ligdicash">
    `POST /pay/v01/withdrawal/create` — vers wallet LigdiCash avec option `top_up_wallet`
  </Card>

  <Card title="Payout Marchand" icon="paper-plane" href="/api-paiement/payout/vers-mobile-money">
    `POST /pay/v01/straight/payout` — envoi direct vers mobile money
  </Card>

  <Card title="Vérifier le statut" icon="circle-check" href="/api-paiement/payout/verifier-statut">
    `GET /pay/v01/withdrawal/confirm` — suivre le résultat d'un payout
  </Card>

  <Card title="Cas d'usage" icon="lightbulb" href="/api-paiement/payout/cas-usage">
    Remboursements, salaires, gains — exemples concrets
  </Card>
</CardGroup>


# Vérifier le statut d'un payout
Source: https://developers.ligdicash.com/api-paiement/payout/verifier-statut

Interrogez GET /pay/v01/withdrawal/confirm pour connaître le résultat d'un payout après sa création.

Après avoir initié un payout, LigdiCash vous notifie du résultat via votre `callback_url`. Si le callback ne se déclenche pas — réseau indisponible, serveur redémarré, délai trop long — vous pouvez interroger cet endpoint directement avec le `token` retourné à la création.

<Note>
  Le callback reste la méthode principale. Cet endpoint est un **filet de sécurité**, pas un substitut au callback. Ne l'utilisez pas en boucle rapide : préférez un polling espacé (toutes les 30 à 60 secondes) avec un nombre maximum de tentatives.
</Note>

## Endpoint

```
GET https://app.ligdicash.com/pay/v01/withdrawal/confirm/
```

## Paramètres

| Paramètre         | Type         | Description                                               |
| ----------------- | ------------ | --------------------------------------------------------- |
| `withdrawalToken` | query string | Le `token` retourné par l'endpoint de création du payout. |

## En-têtes requis

| En-tête         | Valeur                |
| --------------- | --------------------- |
| `Apikey`        | Votre clé API         |
| `Authorization` | `Bearer {AUTH_TOKEN}` |

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://app.ligdicash.com/pay/v01/withdrawal/confirm/?withdrawalToken={PAYOUT_TOKEN}' \
  --header 'Apikey: {API_KEY}' \
  --header 'Authorization: Bearer {AUTH_TOKEN}'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ withdrawalToken: payoutToken });

  const response = await fetch(
    `https://app.ligdicash.com/pay/v01/withdrawal/confirm/?${params}`,
    {
      headers: {
        'Apikey': process.env.LIGDICASH_API_KEY,
        'Authorization': `Bearer ${process.env.LIGDICASH_AUTH_TOKEN}`,
      },
    }
  );

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

  ```php PHP theme={null}
  $params = http_build_query(['withdrawalToken' => $payoutToken]);

  $response = $client->get(
      "https://app.ligdicash.com/pay/v01/withdrawal/confirm/?{$params}",
      [
          'headers' => [
              'Apikey'        => $_ENV['LIGDICASH_API_KEY'],
              'Authorization' => 'Bearer ' . $_ENV['LIGDICASH_AUTH_TOKEN'],
          ],
      ]
  );
  ```
</CodeGroup>

## Réponse

<ResponseField name="response_code" type="string">
  Code de résultat de la requête. `"00"` indique que l'appel a abouti. Toute autre valeur indique une erreur.
</ResponseField>

<ResponseField name="token" type="string">
  Token JWT du payout — identique à celui utilisé en paramètre.
</ResponseField>

<ResponseField name="response_text" type="string">
  Libellé du code de résultat issu du wiki LigdiCash. Peut être vide.
</ResponseField>

<ResponseField name="description" type="string">
  Description complémentaire. Peut être vide.
</ResponseField>

<ResponseField name="custom_data" type="array">
  Toujours `[]` sur cet endpoint.
</ResponseField>

<ResponseField name="wiki" type="string">
  URL vers la liste des codes d'erreur spécifiques à cet endpoint.
</ResponseField>

<ResponseField name="status" type="string">
  Statut de la transaction payout : `"completed"`, `"pending"` ou `"notcompleted"`. Voir [Codes de réponse et statuts](/concepts/codes-reponse-statuts).
</ResponseField>

<ResponseField name="operator_id" type="string">
  Identifiant de l'opérateur qui a traité le payout (ex : `"11"` pour Orange Burkina).
</ResponseField>

<ResponseField name="operator_name" type="string">
  Nom de l'opérateur (ex : `"ORANGE BURKINA"`).
</ResponseField>

```json Succès theme={null}
{
  "response_code": "00",
  "token": "{PAYOUT_TOKEN}",
  "response_text": "",
  "description": "",
  "custom_data": [],
  "wiki": "https://client.ligdicash.com/wiki/createStraightWithdrawal",
  "status": "completed",
  "operator_id": "11",
  "operator_name": "ORANGE BURKINA"
}
```

## Interpréter le statut

Basez votre logique métier sur le champ `status`.

| `status`       | Signification               | Action recommandée                                             |
| -------------- | --------------------------- | -------------------------------------------------------------- |
| `completed`    | Payout finalisé avec succès | Mettre à jour votre base de données, notifier le bénéficiaire  |
| `pending`      | Traitement en cours         | Attendre le callback ; si absent, repoll dans 30 à 60 secondes |
| `notcompleted` | Payout échoué               | Consulter `wiki` pour le détail, notifier le demandeur         |

## Pages associées

* [Payout Client](/api-paiement/payout/vers-wallet-ligdicash) — créer un payout vers wallet LigdiCash
* [Payout Marchand](/api-paiement/payout/vers-mobile-money) — créer un payout vers mobile money
* [Codes de réponse et statuts](/concepts/codes-reponse-statuts)


# Payout Marchand — vers mobile money
Source: https://developers.ligdicash.com/api-paiement/payout/vers-mobile-money

Transférez des fonds directement vers un numéro mobile money avec POST /pay/v01/straight/payout, sans wallet LigdiCash intermédiaire.

Le Payout Marchand envoie des fonds directement vers un **numéro mobile money**, sans que le bénéficiaire ait besoin d'un compte LigdiCash. C'est la méthode à privilégier quand le destinataire n'est pas inscrit sur LigdiCash ou quand vous souhaitez payer vers n'importe quel numéro mobile money.

<Warning>
  Cette méthode n'est pas instantanée. Le délai de traitement peut aller de quelques secondes à plusieurs jours selon l'opérateur. Prévoyez un mécanisme de suivi via callback et/ou polling.
</Warning>

## Prérequis

* Le payout doit être activé sur votre projet API.
* Vos adresses IP serveur doivent être **whitelistées par LigdiCash** — les requêtes provenant d'IP non whitelistées sont rejetées. Contactez [developper@ligdicash.com](mailto:developper@ligdicash.com) pour l'activation.
* Le sous-compte de l'opérateur correspondant au numéro bénéficiaire doit être suffisamment approvisionné.

## Endpoint

```
POST https://app.ligdicash.com/pay/v01/straight/payout
```

## En-têtes requis

| En-tête         | Valeur                |
| --------------- | --------------------- |
| `Apikey`        | Votre clé API         |
| `Authorization` | `Bearer {AUTH_TOKEN}` |
| `Accept`        | `application/json`    |
| `Content-Type`  | `application/json`    |

## Corps de la requête

Tous les champs sont imbriqués dans un objet `commande`.

<ParamField type="object">
  <Expandable title="Champs de commande">
    <ParamField type="integer">
      Montant à transférer en XOF. Doit être un entier positif (pas de décimales).
    </ParamField>

    <ParamField type="string">
      Description de l'opération. Apparaît dans l'historique de la transaction.
    </ParamField>

    <ParamField type="string">
      Numéro de téléphone mobile money du bénéficiaire, avec indicatif pays, sans `+` ni espaces. Exemple : `22670000000`.
    </ParamField>

    <ParamField type="string">
      URL HTTPS de votre serveur qui recevra la notification de résultat. Doit être accessible publiquement.
    </ParamField>

    <ParamField type="object">
      Données personnalisées associées à la transaction. Recommandé : incluez un `transaction_id` unique généré côté marchand pour identifier la transaction dans votre système.
    </ParamField>
  </Expandable>
</ParamField>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://app.ligdicash.com/pay/v01/straight/payout' \
  --header 'Apikey: {API_KEY}' \
  --header 'Authorization: Bearer {AUTH_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "commande": {
      "amount": 5000,
      "description": "Remboursement commande ORD-2024-001",
      "customer": "22670000000",
      "callback_url": "https://backend.masuperboutique.com/callback-payout",
      "custom_data": {
        "transaction_id": "PAYOUT-ORD-2024-001"
      }
    }
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.ligdicash.com/pay/v01/straight/payout', {
    method: 'POST',
    headers: {
      'Apikey': process.env.LIGDICASH_API_KEY,
      'Authorization': `Bearer ${process.env.LIGDICASH_AUTH_TOKEN}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      commande: {
        amount: 5000,
        description: 'Remboursement commande ORD-2024-001',
        customer: '22670000000',
        callback_url: 'https://backend.masuperboutique.com/callback-payout',
        custom_data: {
          transaction_id: 'PAYOUT-ORD-2024-001',
        },
      },
    }),
  });

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

  ```php PHP theme={null}
  $response = $client->post('https://app.ligdicash.com/pay/v01/straight/payout', [
      'headers' => [
          'Apikey'        => $_ENV['LIGDICASH_API_KEY'],
          'Authorization' => 'Bearer ' . $_ENV['LIGDICASH_AUTH_TOKEN'],
          'Accept'        => 'application/json',
          'Content-Type'  => 'application/json',
      ],
      'json' => [
          'commande' => [
              'amount'       => 5000,
              'description'  => 'Remboursement commande ORD-2024-001',
              'customer'     => '22670000000',
              'callback_url' => 'https://backend.masuperboutique.com/callback-payout',
              'custom_data'  => [
                  'transaction_id' => 'PAYOUT-ORD-2024-001',
              ],
          ],
      ],
  ]);
  ```
</CodeGroup>

## Réponse

<ResponseField name="response_code" type="string">
  Code de résultat de la requête. `"00"` indique que le payout a été initié avec succès. Toute autre valeur indique une erreur.
</ResponseField>

<ResponseField name="token" type="string">
  Token JWT identifiant le payout. À stocker immédiatement — il est requis pour [vérifier le statut](/api-paiement/payout/verifier-statut) si votre callback ne se déclenche pas.
</ResponseField>

<ResponseField name="response_text" type="string">
  Message textuel associé au code de réponse. Peut être vide.
</ResponseField>

<ResponseField name="description" type="string">
  Description complémentaire. Peut être vide.
</ResponseField>

<ResponseField name="custom_data" type="string">
  Toujours `""` pour le Payout Marchand.
</ResponseField>

<ResponseField name="wiki" type="string">
  URL vers la liste des codes d'erreur spécifiques à cet endpoint. À consulter lorsque `response_code !== "00"`.
</ResponseField>

```json Succès theme={null}
{
  "response_code": "00",
  "token": "{PAYOUT_TOKEN}",
  "response_text": "",
  "description": "",
  "custom_data": "",
  "wiki": "https://client.ligdicash.com/wiki/createStraightWithdrawal"
}
```

<Warning>
  Un `response_code: "00"` signifie que le payout a été **initié**, pas finalisé. Le résultat définitif vous parvient via le callback — qui peut arriver avec un délai significatif selon l'opérateur. Stockez le `token` pour pouvoir [vérifier le statut](/api-paiement/payout/verifier-statut) en cas de non-réception.
</Warning>

## Différences avec le Payout Client

|                           | Payout Marchand            | Payout Client                |
| ------------------------- | -------------------------- | ---------------------------- |
| Endpoint                  | `/pay/v01/straight/payout` | `/pay/v01/withdrawal/create` |
| Compte LigdiCash requis   | Non                        | Oui                          |
| Instantané                | Non                        | Oui (crédit wallet)          |
| Paramètre `top_up_wallet` | Absent                     | Requis                       |

## Pages associées

* [Payout Client](/api-paiement/payout/vers-wallet-ligdicash) — envoi vers wallet LigdiCash avec option de virement automatique
* [Vérifier le statut d'un payout](/api-paiement/payout/verifier-statut)
* [Le compte marchand LigdiCash](/concepts/compte-marchand) — comprendre les sous-comptes et les soldes par opérateur


# Payout Client — vers wallet LigdiCash
Source: https://developers.ligdicash.com/api-paiement/payout/vers-wallet-ligdicash

Transférez des fonds vers le wallet LigdiCash d'un bénéficiaire avec POST /pay/v01/withdrawal/create.

Le Payout Client envoie des fonds vers le **wallet LigdiCash** d'un bénéficiaire identifié par son numéro de téléphone. Les fonds arrivent instantanément dans son wallet. Via le paramètre `top_up_wallet`, vous choisissez si les fonds y restent ou si LigdiCash déclenche automatiquement un virement vers son compte mobile money.

<Note>
  Cette méthode requiert que le bénéficiaire possède un compte LigdiCash. Si ce n'est pas le cas, utilisez le [Payout Marchand](/api-paiement/payout/vers-mobile-money) qui envoie directement vers un numéro mobile money.
</Note>

## Prérequis

* Le payout doit être activé sur votre projet API.
* Vos adresses IP serveur doivent être **whitelistées par LigdiCash** — les requêtes provenant d'IP non whitelistées sont rejetées. Contactez [developper@ligdicash.com](mailto:developper@ligdicash.com) pour l'activation.
* Le sous-compte de l'opérateur correspondant au numéro bénéficiaire doit être suffisamment approvisionné.

## Endpoint

```
POST https://app.ligdicash.com/pay/v01/withdrawal/create
```

## En-têtes requis

| En-tête         | Valeur                |
| --------------- | --------------------- |
| `Apikey`        | Votre clé API         |
| `Authorization` | `Bearer {AUTH_TOKEN}` |
| `Accept`        | `application/json`    |
| `Content-Type`  | `application/json`    |

## Corps de la requête

Tous les champs sont imbriqués dans un objet `commande`.

<ParamField type="object">
  <Expandable title="Champs de commande">
    <ParamField type="integer">
      Montant à transférer en XOF. Doit être un entier positif (pas de décimales).
    </ParamField>

    <ParamField type="string">
      Description de l'opération. Apparaît dans l'historique du bénéficiaire.
    </ParamField>

    <ParamField type="string">
      Numéro de téléphone du bénéficiaire, avec indicatif pays, sans `+` ni espaces. Exemple : `22670000000`.
    </ParamField>

    <ParamField type="string">
      URL HTTPS de votre serveur qui recevra la notification de résultat. Doit être accessible publiquement.
    </ParamField>

    <ParamField type="integer">
      Comportement après crédit du wallet bénéficiaire :

      * `1` — les fonds restent dans le wallet LigdiCash du bénéficiaire
      * `0` — LigdiCash déclenche automatiquement un virement vers le compte mobile money lié au wallet
    </ParamField>

    <ParamField type="object">
      Données personnalisées associées à la transaction. Recommandé : incluez un `transaction_id` unique généré côté marchand pour identifier la transaction dans votre système.
    </ParamField>
  </Expandable>
</ParamField>

## Le paramètre `top_up_wallet`

<Tabs>
  <Tab title="top_up_wallet: 1 — wallet uniquement">
    Les fonds arrivent dans le wallet LigdiCash du bénéficiaire et y restent. Le bénéficiaire peut les utiliser pour payer sur les plateformes LigdiCash ou initier lui-même un retrait vers son mobile money.

    **À utiliser pour** : créditer un compte fidélité, distribuer des récompenses que le bénéficiaire utilisera sur votre plateforme.
  </Tab>

  <Tab title="top_up_wallet: 0 — virement automatique">
    Les fonds arrivent dans le wallet LigdiCash du bénéficiaire, puis LigdiCash déclenche automatiquement un virement vers son compte mobile money lié. Le bénéficiaire reçoit les fonds sur son téléphone.

    **À utiliser pour** : remboursements, salaires, gains — quand le bénéficiaire doit recevoir de l'argent sur son mobile money sans action de sa part.

    <Note>
      Le crédit du wallet est instantané. Le virement vers le mobile money peut prendre quelques minutes selon l'opérateur.
    </Note>
  </Tab>
</Tabs>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://app.ligdicash.com/pay/v01/withdrawal/create' \
  --header 'Apikey: {API_KEY}' \
  --header 'Authorization: Bearer {AUTH_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "commande": {
      "amount": 5000,
      "description": "Remboursement commande ORD-2024-001",
      "customer": "22670000000",
      "callback_url": "https://backend.masuperboutique.com/callback-payout",
      "top_up_wallet": 1,
      "custom_data": {
        "transaction_id": "PAYOUT-ORD-2024-001"
      }
    }
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.ligdicash.com/pay/v01/withdrawal/create', {
    method: 'POST',
    headers: {
      'Apikey': process.env.LIGDICASH_API_KEY,
      'Authorization': `Bearer ${process.env.LIGDICASH_AUTH_TOKEN}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      commande: {
        amount: 5000,
        description: 'Remboursement commande ORD-2024-001',
        customer: '22670000000',
        callback_url: 'https://backend.masuperboutique.com/callback-payout',
        top_up_wallet: 1,
        custom_data: {
          transaction_id: 'PAYOUT-ORD-2024-001',
        },
      },
    }),
  });

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

  ```php PHP theme={null}
  $response = $client->post('https://app.ligdicash.com/pay/v01/withdrawal/create', [
      'headers' => [
          'Apikey'        => $_ENV['LIGDICASH_API_KEY'],
          'Authorization' => 'Bearer ' . $_ENV['LIGDICASH_AUTH_TOKEN'],
          'Accept'        => 'application/json',
          'Content-Type'  => 'application/json',
      ],
      'json' => [
          'commande' => [
              'amount'       => 5000,
              'description'  => 'Remboursement commande ORD-2024-001',
              'customer'     => '22670000000',
              'callback_url' => 'https://backend.masuperboutique.com/callback-payout',
              'top_up_wallet'=> 1,
              'custom_data'  => [
                  'transaction_id' => 'PAYOUT-ORD-2024-001',
              ],
          ],
      ],
  ]);
  ```
</CodeGroup>

## Réponse

<ResponseField name="response_code" type="string">
  Code de résultat de la requête. `"00"` indique que le payout a été initié avec succès. Toute autre valeur indique une erreur.
</ResponseField>

<ResponseField name="token" type="string">
  Token JWT identifiant le payout. À stocker immédiatement — il est requis pour [vérifier le statut](/api-paiement/payout/verifier-statut) si votre callback ne se déclenche pas.
</ResponseField>

<ResponseField name="response_text" type="string">
  Message textuel associé au code de réponse. Peut être vide.
</ResponseField>

<ResponseField name="description" type="string">
  Description complémentaire. Peut être vide.
</ResponseField>

<ResponseField name="custom_data" type="array">
  Toujours `[]` pour le Payout Client.
</ResponseField>

<ResponseField name="wiki" type="string">
  URL vers la liste des codes d'erreur spécifiques à cet endpoint. À consulter lorsque `response_code !== "00"`.
</ResponseField>

```json Succès theme={null}
{
  "response_code": "00",
  "token": "{PAYOUT_TOKEN}",
  "response_text": "",
  "description": "",
  "custom_data": [],
  "wiki": "https://client.ligdicash.com/wiki/createWithdrawal"
}
```

<Warning>
  Un `response_code: "00"` signifie que le payout a été **initié**, pas nécessairement finalisé. Le résultat définitif vous parvient via le callback. Stockez le `token` pour pouvoir [vérifier le statut](/api-paiement/payout/verifier-statut) en cas de non-réception du callback.
</Warning>

## Pages associées

* [Payout Marchand](/api-paiement/payout/vers-mobile-money) — envoi direct vers mobile money sans wallet intermédiaire
* [Vérifier le statut d'un payout](/api-paiement/payout/verifier-statut)
* [Le compte marchand LigdiCash](/concepts/compte-marchand) — comprendre les sous-comptes et les soldes par opérateur


# Vérification de statut — Vue d'ensemble
Source: https://developers.ligdicash.com/api-paiement/verification-statut/introduction

Comment et quand vérifier le statut d'une transaction LigdiCash — payin ou payout — à tout moment.

LigdiCash expose des endpoints `confirm` qui permettent d'interroger l'état d'une transaction à partir du token obtenu à la création. Cette vérification active est le complément indispensable du callback : elle vous permet de réconcilier votre base de données lorsque le callback n'est pas disponible, a été manqué, ou doit être re-vérifié pour des raisons de sécurité.

## Endpoints disponibles

| Flux                             | Méthode | Endpoint                                     | Paramètre         |
| -------------------------------- | ------- | -------------------------------------------- | ----------------- |
| Payin (redirect & sans redirect) | `GET`   | `/pay/v01/redirect/checkout-invoice/confirm` | `token`           |
| Payout                           | `GET`   | `/pay/v01/withdrawal/confirm/`               | `withdrawalToken` |

<Note>
  Le même endpoint `confirm` est utilisé pour le payin avec redirection et le payin sans redirection. La différence est dans le moment où vous l'appelez, pas dans l'endpoint lui-même.
</Note>

## Valeurs de `status`

Quel que soit le flux, la réponse `confirm` contient un champ `status` avec trois valeurs possibles :

| `status`       | Signification                                | Action recommandée                              |
| -------------- | -------------------------------------------- | ----------------------------------------------- |
| `completed`    | Transaction finalisée avec succès            | Honorer la commande ou confirmer le paiement    |
| `pending`      | En attente de traitement côté opérateur      | Patienter et rappeler, ou attendre le callback  |
| `notcompleted` | Transaction non aboutie (annulée ou échouée) | Proposer de réessayer ou notifier l'utilisateur |

## Quand appeler `confirm`

Il y a trois situations où vous devez appeler `confirm` :

**1. Après la redirection vers `return_url` (payin redirect)**

Quand le client revient sur votre site après le paiement, votre frontend déclenche un appel à votre backend, qui appelle `confirm` avec le token stocké à la création. Ne jamais appeler `confirm` directement depuis le navigateur — vos clés API seraient exposées.

**2. Dans votre handler de callback (tous les flux)**

Avant d'honorer une commande suite à un callback, re-vérifiez systématiquement avec `confirm`. N'importe qui connaissant l'URL de votre endpoint peut envoyer un faux payload — la re-vérification est la seule garantie.

<Warning>
  N'honorez jamais une commande sur la seule foi du payload de callback. Appelez toujours `confirm` avec le **token stocké à la création** avant de déclencher votre logique métier.
</Warning>

**3. En polling de secours (callback indisponible ou en retard)**

Si le callback n'est pas disponible dans votre environnement de développement, ou s'il tarde à arriver en production, interrogez `confirm` à intervalles réguliers jusqu'à obtenir un statut terminal (`completed` ou `notcompleted`).

<Note>
  Le polling est un filet de sécurité, pas la stratégie principale. Consultez [Polling vs callback](/api-paiement/verification-statut/polling-vs-callback) pour choisir la bonne approche selon votre contexte.
</Note>

## Token de création vs token du callback

<Warning>
  Le `token` reçu dans le payload du callback est **différent** du token retourné à la création. Les deux permettent techniquement d'appeler `confirm`, mais seul le **token de création** vous permet de faire la réconciliation avec votre commande côté marchand. Stockez toujours le token de création en base de données dès la création de la facture.
</Warning>

## Pages de référence

* [Vérifier le statut — payin redirect](/api-paiement/payin-redirect/verifier-statut) — référence complète, champs de réponse et payloads réels
* [Vérifier le statut — payin sans redirect](/api-paiement/payin-sans-redirect/verifier-statut) — spécificités du flux sans redirection
* [Vérifier le statut — payout](/api-paiement/payout/verifier-statut) — endpoint `withdrawal/confirm`
* [Polling vs callback](/api-paiement/verification-statut/polling-vs-callback) — choisir la bonne stratégie
* [Recommandations](/api-paiement/verification-statut/recommandations) — intervalles, timeouts, pattern hybride
* [Callback — sécurisation](/api-paiement/callback/securisation) — pourquoi toujours re-vérifier avec `confirm`


# Polling vs callback
Source: https://developers.ligdicash.com/api-paiement/verification-statut/polling-vs-callback

Quand utiliser le polling (vérification active) et quand se fier au callback (notification passive) — avantages, limites et pattern hybride recommandé.

Il existe deux façons de savoir si une transaction LigdiCash a abouti : **attendre que LigdiCash vous notifie** (callback), ou **interroger l'API à intervalles réguliers** (polling). Les deux approches sont complémentaires — l'une sans l'autre laisse un angle mort.

## Définitions

**Callback (notification passive)**

LigdiCash envoie une requête POST à votre `callback_url` dès que le statut d'une transaction change. Vous n'avez rien à déclencher : c'est LigdiCash qui vient vous notifier.

**Polling (vérification active)**

Votre backend appelle périodiquement l'endpoint `confirm` avec le token de la transaction jusqu'à obtenir un statut terminal (`completed` ou `notcompleted`). Vous interrogez LigdiCash au lieu d'attendre qu'il vous contacte.

## Avantages et limites

|                         | Callback                                      | Polling                                        |
| ----------------------- | --------------------------------------------- | ---------------------------------------------- |
| **Latence**             | Faible — notification quasi-immédiate         | Variable — dépend de l'intervalle choisi       |
| **Charge serveur**      | Minimale — un seul appel entrant              | Répétée — N appels sortants par transaction    |
| **Fiabilité réseau**    | Fragile — votre serveur doit être accessible  | Robuste — vous initiez les appels              |
| **Environnement local** | Difficile — nécessite un tunnel (ngrok, etc.) | Facile — fonctionne partout                    |
| **Sécurité**            | Nécessite re-vérification avec `confirm`      | Natif — vous interrogez directement l'API      |
| **Transactions lentes** | Idéal — notifié dès que ça bouge              | Coûteux — continue de poller pendant l'attente |

## Recommandations selon le cas d'usage

**Utilisez le callback comme stratégie principale**

Le callback est le mécanisme conçu par LigdiCash pour la notification en production. Il est réactif, peu coûteux, et adapté aux transactions dont le délai de confirmation est variable (quelques secondes à plusieurs minutes selon l'opérateur).

<Warning>
  LigdiCash envoie **deux requêtes POST** pour chaque callback : une en `application/x-www-form-urlencoded` et une en `application/json`. Votre handler doit dédupliquer — consultez [Idempotence du callback](/api-paiement/callback/idempotence).
</Warning>

**Utilisez le polling en développement local**

En local, votre serveur n'est pas accessible depuis internet. Utilisez le polling pour simuler le comportement de production sans avoir à configurer un tunnel.

**Utilisez le polling comme filet de sécurité en production**

Même en production, un callback peut ne pas arriver : votre serveur était temporairement indisponible, le réseau a coupé, ou LigdiCash a rencontré une erreur en envoyant la notification. Un polling de secours déclenché quelques minutes après la création d'une transaction encore `pending` permet de récupérer ces cas.

**Ne remplacez pas le callback par du polling**

Un polling rapide (toutes les secondes) pour remplacer le callback est une mauvaise idée : il multiplie les appels API, augmente la latence perçue, et crée des problèmes de concurrence si deux workers traitent la même transaction.

## Pattern hybride recommandé

L'architecture la plus robuste combine les deux : **callback principal + polling de fallback**.

```
Transaction créée
       │
       ├─► Stocker le token en base (status = "pending")
       │
       ├─► [Callback] LigdiCash notifie → re-vérifier avec confirm → mettre à jour
       │
       └─► [Fallback] Job planifié après N minutes :
               Si status toujours "pending" → appeler confirm
               Si "completed" ou "notcompleted" → mettre à jour et stopper
               Si toujours "pending" après timeout → marquer comme "expiré" et alerter
```

```javascript JavaScript — polling de fallback theme={null}
async function verifierTransactionEnAttente(token) {
  const MAX_TENTATIVES = 10;
  const INTERVALLE_MS = 5000; // 5 secondes entre chaque appel

  for (let i = 0; i < MAX_TENTATIVES; i++) {
    const res = await fetch(
      `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=${token}`,
      {
        headers: {
          Apikey: process.env.LIGDICASH_API_KEY,
          Authorization: `Bearer ${process.env.LIGDICASH_API_TOKEN}`,
          Accept: "application/json",
        },
      }
    );
    const data = await res.json();

    if (data.status === "completed" || data.status === "notcompleted") {
      return data; // statut terminal atteint
    }

    await new Promise((r) => setTimeout(r, INTERVALLE_MS));
  }

  // Après MAX_TENTATIVES sans statut terminal
  return { status: "timeout" };
}
```

<Tip>
  En production, déclenchez ce polling depuis un job de fond (cron, worker queue) plutôt que depuis le thread de la requête HTTP. Cela évite de bloquer la réponse à l'utilisateur pendant l'attente.
</Tip>

## Sécurité : re-vérification obligatoire

Que vous utilisiez le callback ou le polling, **n'honorez jamais une commande sans avoir appelé `confirm`** avec le token stocké à la création. Un faux payload de callback peut être envoyé par n'importe qui connaissant votre URL. `confirm` est la seule source de vérité.

<Note>
  Consultez [Sécurisation du callback](/api-paiement/callback/securisation) pour le pattern complet de re-vérification avec gestion de l'idempotence.
</Note>

## Pages associées

* [Recommandations](/api-paiement/verification-statut/recommandations) — intervalles de polling, timeouts, gestion du pending
* [Callback — sécurisation](/api-paiement/callback/securisation) — re-vérification avec `confirm`
* [Callback — idempotence](/api-paiement/callback/idempotence) — déduplication des deux requêtes
* [Codes de réponse et statuts](/concepts/codes-reponse-statuts) — référence complète des valeurs de `status`


# Recommandations de vérification
Source: https://developers.ligdicash.com/api-paiement/verification-statut/recommandations

Intervalles de polling, timeouts, stratégie hybride et gestion des transactions en pending — les bonnes pratiques pour un suivi fiable.

Cette page rassemble les bonnes pratiques opérationnelles pour vérifier le statut des transactions LigdiCash de façon fiable, sans surcharger l'API ni laisser de transactions orphelines.

## Intervalle de polling recommandé

L'intervalle optimal dépend du type de transaction :

| Flux                              | Intervalle recommandé | Raison                                                                                 |
| --------------------------------- | --------------------- | -------------------------------------------------------------------------------------- |
| Payin (redirect ou sans redirect) | **3 à 5 secondes**    | La confirmation opérateur arrive souvent en quelques secondes après l'action du client |
| Payout                            | **30 à 60 secondes**  | Les payouts sont traités par batch côté opérateur — poller trop vite est inutile       |

<Warning>
  Ne descendez pas en dessous de 3 secondes entre deux appels `confirm`. Un polling trop agressif peut déclencher des limites de débit côté LigdiCash et dégrader la fiabilité de vos intégrations.
</Warning>

## Timeouts — quand abandonner le polling

Fixez un nombre maximum de tentatives plutôt qu'un délai absolu : cela vous donne un contrôle précis sur le nombre d'appels API générés.

| Flux   | Max tentatives recommandées | Durée totale approx. |
| ------ | --------------------------- | -------------------- |
| Payin  | 10 à 15                     | 40 à 75 secondes     |
| Payout | 10                          | 5 à 10 minutes       |

Au-delà du timeout, la transaction reste techniquement `pending` côté LigdiCash — elle n'est pas annulée. Le callback peut encore arriver. Adoptez la logique suivante :

1. **Marquez la transaction comme `expiré` dans votre base** (statut applicatif, pas LigdiCash).
2. **Informez l'utilisateur** que le traitement est en cours et qu'il sera notifié.
3. **Continuez à écouter le callback** — s'il arrive, re-vérifiez avec `confirm` et mettez à jour.

## Stratégie hybride — callback principal + polling de fallback

```
1. Créer la transaction → stocker le token et status = "pending"
2. Configurer un callback_url accessible depuis internet
3. À la réception du callback :
     → Appeler confirm avec le token de création
     → Mettre à jour votre base
4. Si le callback n'arrive pas après 2 minutes :
     → Déclencher un polling de fallback (job asynchrone)
     → 10 tentatives, toutes les 5 secondes
5. Si polling timeout :
     → Marquer "expiré" en base
     → Continuer à traiter le callback s'il arrive tard
```

<Tip>
  Déclenchez le polling de fallback depuis un job de fond (cron, queue worker) — pas depuis le thread de la requête HTTP initiale. Cela évite de bloquer l'utilisateur pendant l'attente.
</Tip>

## Gérer les transactions en `pending`

Une transaction reste `pending` tant que l'opérateur n'a pas rendu sa décision finale. Plusieurs situations expliquent un `pending` prolongé :

* **Mode approbation (Moov Africa)** — le client doit confirmer sur son application mobile, ce qui peut prendre plusieurs minutes.
* **OTP expiré** — le client n'a pas saisi l'OTP à temps. La transaction restera `pending` puis passera en `notcompleted` après expiration.
* **Congestion réseau opérateur** — rare, mais possible lors de pics de trafic.
* **Payout en attente de fonds** — si le solde du compte marchand est insuffisant au moment de l'initiation.

Pour chaque transaction encore `pending` après votre timeout de polling, conservez le token en base et planifiez une re-vérification différée (exemple : +30 min, +2h, +24h) avant de la considérer définitivement perdue.

```javascript JavaScript — re-vérification différée theme={null}
async function reVerifierTransactionExpirée(token) {
  const res = await fetch(
    `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=${token}`,
    {
      headers: {
        Apikey: process.env.LIGDICASH_API_KEY,
        Authorization: `Bearer ${process.env.LIGDICASH_API_TOKEN}`,
        Accept: "application/json",
      },
    }
  );
  const data = await res.json();

  if (data.status === "completed") {
    await mettreAJourCommande(token, "payée");
  } else if (data.status === "notcompleted") {
    await mettreAJourCommande(token, "échouée");
  }
  // Si toujours "pending", laisser le job planifié pour la prochaine vérification
}
```

## Pages associées

* [Polling vs callback](/api-paiement/verification-statut/polling-vs-callback) — choisir la bonne stratégie
* [Callback — sécurisation](/api-paiement/callback/securisation) — re-vérification avec `confirm`
* [Callback — idempotence](/api-paiement/callback/idempotence) — déduplication des deux requêtes
* [Modes de validation](/api-paiement/payin-sans-redirect/modes-validation) — OTP USSD, OTP SMS, approbation
* [Codes de réponse et statuts](/concepts/codes-reponse-statuts) — référence complète


# Vue d'ensemble de l'API de paiement
Source: https://developers.ligdicash.com/api-paiement/vue-ensemble

Choisissez la bonne méthode de paiement LigdiCash selon votre cas d'usage : payin avec ou sans redirection, payout client ou marchand.

LigdiCash propose plusieurs méthodes de paiement selon que vous collectez des fonds (payin) ou que vous en envoyez (payout), et selon le niveau de contrôle que vous souhaitez sur l'expérience utilisateur.

## Tableau de décision

| Je veux…                                                 | Méthode                                                                  |
| -------------------------------------------------------- | ------------------------------------------------------------------------ |
| Laisser LigdiCash gérer l'interface de paiement          | [Payin avec redirection](/api-paiement/payin-redirect/introduction)      |
| Intégrer le paiement directement dans mon interface      | [Payin sans redirection](/api-paiement/payin-sans-redirect/introduction) |
| Envoyer de l'argent vers le wallet LigdiCash d'un client | [Payout Client](/api-paiement/payout/vers-wallet-ligdicash)              |
| Envoyer de l'argent directement vers un mobile money     | [Payout Marchand](/api-paiement/payout/vers-mobile-money)                |

## Payin avec redirection

Le client est redirigé vers la page de paiement hébergée par LigdiCash. Il choisit son opérateur, saisit son numéro et valide le paiement. Une fois terminé, il est renvoyé vers votre site.

**Avantages** — intégration simple, pas de gestion de l'UX de paiement, compatible avec tous les opérateurs supportés.

**Cas d'usage** — e-commerce, portails web, tout contexte où une redirection est acceptable.

<Card title="Payin avec redirection" icon="arrow-up-right" href="/api-paiement/payin-redirect/introduction">
  Créer une facture et rediriger le client vers la page de paiement LigdiCash
</Card>

## Payin sans redirection

Le paiement s'initie directement depuis votre interface. Votre client ne quitte pas votre application. Vous gérez la collecte du numéro de téléphone et, selon l'opérateur, la saisie de l'OTP.

**Avantages** — expérience utilisateur fluide, intégration native dans votre app web ou mobile.

**Cas d'usage** — applications mobiles, interfaces métier, flux où la redirection n'est pas souhaitable.

<Card title="Payin sans redirection" icon="mobile" href="/api-paiement/payin-sans-redirect/introduction">
  Initier un paiement directement depuis votre interface sans redirection
</Card>

## Payout Client

Envoi d'argent vers le **wallet LigdiCash** du client. L'endpoint utilisé est `POST /pay/v01/withdrawal/create`.

**Cas d'usage** — remboursements, gains, cashback vers des clients disposant d'un compte LigdiCash.

<Card title="Payout Client" icon="wallet" href="/api-paiement/payout/vers-wallet-ligdicash">
  Envoyer des fonds vers le wallet LigdiCash d'un client
</Card>

## Payout Marchand

Envoi d'argent **directement vers un numéro mobile money**, sans passer par un wallet LigdiCash intermédiaire. L'endpoint utilisé est `POST /pay/v01/straight/payout`.

**Cas d'usage** — paiement de prestataires, salaires, transferts vers des destinataires sans compte LigdiCash.

<Card title="Payout Marchand" icon="paper-plane" href="/api-paiement/payout/vers-mobile-money">
  Envoyer des fonds directement vers un numéro mobile money
</Card>


# PayLinks
Source: https://developers.ligdicash.com/autres-produits/paylinks

Générez des liens de paiement depuis le dashboard LigdiCash, sans code ni intégration technique. Idéal pour les marchands sans site web.

Les PayLinks vous permettent de créer des pages de paiement en quelques clics depuis le dashboard LigdiCash. Aucune intégration technique n'est requise : vous renseignez les informations du produit ou du service, et LigdiCash génère une URL de paiement que vous pouvez partager par WhatsApp, email, SMS ou réseaux sociaux.

## Prérequis

* Un compte LigdiCash actif
* Un **contrat PayLink** signé avec LigdiCash (distinct du contrat API)
* Un **projet PayLink** activé par l'équipe LigdiCash

<Note>
  Le contrat PayLink est séparé du contrat API de paiement. Contactez [developper@ligdicash.com](mailto:developper@ligdicash.com) pour l'activer.
</Note>

## Structure : projets et PayLinks

Les PayLinks sont organisés en deux niveaux dans le dashboard :

```
Projet PayLink "Ma Boutique"
├── PayLink "Chaussures Adidas — 25 000 XOF"  → paylink.ligdicash.com/adidas
├── PayLink "Facture client janvier"           → paylink.ligdicash.com/facture-jan
└── PayLink "Collecte association 2024"        → paylink.ligdicash.com/collecte-2024
```

Un **projet PayLink** est un container qui regroupe vos PayLinks. Chaque projet dispose de son propre sous-compte marchand, comme un projet API.

Un **PayLink** est le lien de paiement individuel, associé à un produit ou un service.

## Créer un PayLink

Depuis le dashboard : **Marchands → Paylinks → Créer un nouveau PayLink**.

### Détails du PayLink

| Champ                   | Description                                                                 |
| ----------------------- | --------------------------------------------------------------------------- |
| **Projet**              | Le projet PayLink auquel ce lien est rattaché                               |
| **Libellé**             | Nom du produit ou du service, affiché sur la page de paiement               |
| **Mot-clé**             | Slug de l'URL (`paylink.ligdicash.com/{mot-clé}`) — sans espaces ni accents |
| **Description**         | Description longue affichée sur la page de paiement (éditeur enrichi)       |
| **Images descriptives** | Photos du produit ou du service                                             |

### Configuration du paiement

<AccordionGroup>
  <Accordion title="Prix fixe">
    Vous définissez un montant fixe en XOF. Le client ne peut pas le modifier. Adapté aux produits à prix unique.
  </Accordion>

  <Accordion title="Prix variable">
    Le client saisit lui-même le montant qu'il souhaite payer. Un champ libre s'affiche sur la page de paiement. Adapté aux dons ou aux paiements à montant libre.
  </Accordion>

  <Accordion title="Prix plancher">
    Vous définissez un montant minimum. Le client peut payer ce montant ou davantage, mais pas moins. Adapté aux abonnements ou contributions avec minimum obligatoire.
  </Accordion>

  <Accordion title="Collecte">
    Vous définissez un objectif de montant global. Chaque client contribue librement jusqu'à ce que l'objectif total soit atteint. Adapté aux levées de fonds ou aux cagnottes.
  </Accordion>
</AccordionGroup>

### Autres paramètres

| Paramètre                 | Options                                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Gestion du stock**      | Sans gestion / Avec gestion (limite le nombre d'achats)                                                             |
| **Quantité achetée**      | Le client saisit la quantité ou non                                                                                 |
| **Durée de vie**          | Illimitée / Limitée (vous choisissez une date de début et de fin)                                                   |
| **Action post-paiement**  | Voir ci-dessous                                                                                                     |
| **Message post-paiement** | Texte affiché au client après le paiement réussi                                                                    |
| **Callback URL**          | URL notifiée après chaque paiement (même fonctionnement que le [callback API](/api-paiement/callback/introduction)) |

### Action post-paiement

<AccordionGroup>
  <Accordion title="Ne rien faire">
    LigdiCash affiche le message post-paiement que vous avez saisi. Le client reste sur la page de confirmation LigdiCash.
  </Accordion>

  <Accordion title="Redirection vers une URL">
    Le client est redirigé vers une page de votre site après le paiement. Vous saisissez l'URL cible.
  </Accordion>
</AccordionGroup>

<Note>
  Les options « Générer un ticket » et « Téléchargement de fichier » existent dans l'interface mais ne sont pas fonctionnelles.
</Note>

## L'URL générée

Chaque PayLink est accessible à l'adresse :

```
https://paylink.ligdicash.com/{mot-clé}
```

Cette URL est publique et partageable directement. Elle s'ouvre dans n'importe quel navigateur et affiche une page de paiement LigdiCash avec les opérateurs mobile money disponibles selon votre contrat.

<Tip>
  Le mot-clé apparaît dans l'URL — choisissez-le court et mémorable. Exemple : `facture-123` plutôt que `paiement-de-la-facture-numero-123-janvier-2024`.
</Tip>

## Callback

Si vous renseignez une Callback URL, LigdiCash envoie une notification à votre serveur après chaque paiement validé. Le fonctionnement est identique au callback de l'API de paiement : double requête (`application/x-www-form-urlencoded` + `application/json`), même structure de payload.

Consultez la section [Sécurisation du callback](/api-paiement/callback/securisation) pour le pattern de re-vérification recommandé.

## Suivi des paiements

Les paiements reçus via un PayLink apparaissent dans **Marchands → Payin** avec la source `PAYLINK`. Chaque ligne affiche le token, le `trans_id` et un bouton **PayLink** pour identifier le lien d'origine.

Les fonds sont crédités sur le sous-compte marchand du projet PayLink correspondant à l'opérateur utilisé par le client, comme pour tout paiement LigdiCash.

## Différence avec l'API de paiement

|                       | API de paiement             | PayLinks                                             |
| --------------------- | --------------------------- | ---------------------------------------------------- |
| Intégration technique | Requise (code backend)      | Aucune                                               |
| Page de paiement      | Hébergée par LigdiCash      | Hébergée par LigdiCash                               |
| Montant               | Dynamique (par requête API) | Configurable (fixe / variable / plancher / collecte) |
| Callback              | Oui                         | Oui                                                  |
| Public cible          | Développeurs                | Tout marchand                                        |
| Contrat requis        | Contrat API                 | Contrat PayLink                                      |


# SMS LigdiCash
Source: https://developers.ligdicash.com/autres-produits/sms

Envoyez des SMS transactionnels et marketing à vos clients via l'infrastructure LigdiCash SMS, un service indépendant de l'API de paiement.

LigdiCash SMS est un service d'envoi de SMS disponible séparément de l'API de paiement. Il permet d'envoyer des SMS transactionnels (confirmations, codes OTP, notifications) et marketing à vos clients en Afrique de l'Ouest.

<Note>
  LigdiCash SMS est un produit indépendant avec sa propre infrastructure, ses propres clés d'authentification et sa propre documentation. Il n'utilise pas les mêmes endpoints ni les mêmes credentials que l'API de paiement.
</Note>

## Documentation

La documentation complète du service SMS LigdiCash est disponible sur le portail dédié :

<CardGroup>
  <Card title="Portail SMS LigdiCash" icon="comment-sms" href="https://sms.ligdicash.io/">
    Accédez au tableau de bord SMS, gérez vos campagnes et consultez vos statistiques d'envoi.
  </Card>

  <Card title="Documentation technique" icon="book" href="https://sms.ligdicash.io/documentation/index.html">
    Endpoints, paramètres, exemples de code et guide d'intégration de l'API SMS.
  </Card>
</CardGroup>

## Contacter l'équipe

Pour activer le service SMS ou obtenir de l'aide sur l'intégration :

* **Email** : [info@ligdicash.com](mailto:info@ligdicash.com)
* **Support** : [Voir la page Support](/ressources/support)


# Authentification
Source: https://developers.ligdicash.com/concepts/authentification

Comment authentifier vos requêtes vers l'API LigdiCash avec les en-têtes Apikey et Authorization.

Chaque requête vers l'API LigdiCash doit être accompagnée de deux clés d'identification, transmises dans les en-têtes HTTP. Ces clés sont disponibles dans votre dashboard LigdiCash une fois votre projet activé.

## Les deux clés

| En-tête         | Valeur               | Rôle                   |
| --------------- | -------------------- | ---------------------- |
| `Apikey`        | Votre clé API        | Identifie votre projet |
| `Authorization` | `Bearer {API_TOKEN}` | Authentifie la requête |

Ces deux clés sont distinctes et toutes les deux obligatoires. Une requête avec une seule des deux sera rejetée.

<Note>
  Une fois votre projet activé, vos clés `Apikey` et `API_TOKEN` sont disponibles directement dans votre dashboard LigdiCash.
</Note>

## En-têtes complets

Toutes vos requêtes doivent inclure ces quatre en-têtes :

```
Apikey: {API_KEY}
Authorization: Bearer {API_TOKEN}
Accept: application/json
Content-Type: application/json
```

## Exemple cURL

```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 '{ ... }'
```

## Bonnes pratiques

**Stockez vos clés dans des variables d'environnement**, jamais en dur dans le code source :

<CodeGroup>
  ```bash .env theme={null}
  LIGDICASH_API_KEY=votre_api_key
  LIGDICASH_API_TOKEN=votre_api_token
  ```

  ```javascript Node.js theme={null}
  const apiKey = process.env.LIGDICASH_API_KEY;
  const apiToken = process.env.LIGDICASH_API_TOKEN;
  ```

  ```php PHP theme={null}
  $apiKey = getenv('LIGDICASH_API_KEY');
  $apiToken = getenv('LIGDICASH_API_TOKEN');
  ```

  ```python Python theme={null}
  import os
  api_key = os.environ["LIGDICASH_API_KEY"]
  api_token = os.environ["LIGDICASH_API_TOKEN"]
  ```
</CodeGroup>

<Warning>
  Ne transmettez jamais vos clés depuis un navigateur ou une application mobile. Tout appel à l'API LigdiCash doit transiter par votre serveur backend.
</Warning>

## Erreurs d'authentification

Une erreur d'authentification se manifeste par `response_code: "01"` et `response_text: "Echec (Code00)"` :

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

Causes possibles :

* `Apikey` incorrecte ou expiré
* `API_TOKEN` incorrect ou expiré
* Un ou plusieurs en-têtes obligatoires absents

Le champ `wiki` présent dans chaque réponse contient une URL vers la documentation des codes d'erreur spécifique à l'endpoint appelé. **Consultez toujours cette URL** pour obtenir la signification exacte du code retourné — c'est la référence officielle LigdiCash pour interpréter `response_text`.

## Régénérer vos clés

Si vos clés sont compromises, contactez l'équipe LigdiCash pour en obtenir de nouvelles. Les anciennes clés sont immédiatement invalidées à la réémission.

<Warning>
  Toute réémission de clés interrompt immédiatement les appels en production. Préparez vos nouvelles variables d'environnement avant de demander la réémission.
</Warning>


# Codes de réponse et statuts
Source: https://developers.ligdicash.com/concepts/codes-reponse-statuts

Comprendre response_code, response_text et le champ wiki pour interpréter chaque réponse de l'API LigdiCash.

Chaque réponse de l'API LigdiCash contient trois champs qui permettent d'interpréter le résultat d'un appel : `response_code`, `response_text` et `wiki`. Ils sont présents sur tous les endpoints.

## response\_code

Le champ `response_code` indique si la requête a été acceptée ou rejetée par LigdiCash.

| Valeur | Signification                                                   |
| ------ | --------------------------------------------------------------- |
| `00`   | Requête valide — la transaction est initiée                     |
| `01`   | Requête rejetée — payload invalide ou erreur d'authentification |

<Warning>
  `response_code: "00"` ne signifie pas que le paiement a réussi. Cela signifie uniquement que votre payload était correct et que la transaction a bien été initiée. L'issue réelle du paiement — succès ou échec — est communiquée ultérieurement via le callback ou l'endpoint `confirm`.
</Warning>

## response\_text

La valeur de `response_text` dépend à la fois du résultat et de l'endpoint appelé.

**En cas de succès (`response_code: "00"`)**, le contenu varie selon le type de transaction :

| Flux                   | Contenu de `response_text`                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| Payin avec redirection | L'URL de la page de paiement LigdiCash — c'est ce lien que vous devez ouvrir pour le client |
| Payin sans redirection | Un message textuel indiquant que la transaction est en cours de traitement                  |

**En cas d'échec (`response_code: "01"`)**, il prend la forme `Echec (CodeXX)` où `XX` est un sous-code spécifique à l'endpoint — par exemple `Echec (Code00)` pour un échec d'authentification.

<Tip>
  En cas d'échec, `response_text` est un code technique (`Echec (CodeXX)`). Préférez consulter le champ `wiki` pour en obtenir la description lisible et afficher un message adapté à votre utilisateur.
</Tip>

## Le champ wiki

Le champ `wiki` présent dans chaque réponse contient une URL vers la documentation des sous-codes de l'endpoint appelé. **Consultez toujours cette URL** quand `response_code` vaut `01` pour connaître la cause exacte de l'échec.

La page retournée affiche une liste structurée des sous-codes possibles et leur description, au format var\_dump PHP :

```
array:2 [▼
  0 => array:2 [▶]
  1 => array:3 [▼
    "code" => "01"
    "description" => "There is an error"
    "subcodes" => array:19 [▼
      0 => array:2 [▼
        "code" => "Echec (Code00)"
        "description" => "Authentification failure"
      ]
      1 => array:2 [▶]
      2 => array:2 [▶]
      ...
    ]
  ]
]
```

Chaque entrée de `subcodes` correspond à une valeur possible de `response_text` et sa signification en anglais.

## Exemple de réponse

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

  ```json Succès — payin sans redirection theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Transaction en cours de traitement",
    "description": "",
    "custom_data": {},
    "wiki": "https://client.ligdicash.com/wiki/createInvoice"
  }
  ```

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

## Pattern recommandé

```javascript Node.js theme={null}
const data = await response.json();

if (data.response_code === "01") {
  // Loggez le sous-code technique
  console.error("LigdiCash error:", data.response_text);

  // Consultez data.wiki pour obtenir la description du sous-code
  // et construire un message adapté à votre utilisateur
}
```

## Pages associées

* [Cycle de vie d'une transaction](/concepts/cycle-vie-transaction) — statuts `pending`, `completed`, `notcompleted`
* [Erreurs courantes](/erreurs/erreurs-courantes) — causes et solutions par endpoint
* [Le champ wiki](/erreurs/champ-wiki) — utilisation avancée


# Le compte marchand LigdiCash
Source: https://developers.ligdicash.com/concepts/compte-marchand

Structure du compte marchand LigdiCash : sous-comptes par opérateur, flux entrants et sortants, Cashin, Cashout et gestion des soldes.

Lorsque vous signez un contrat LigdiCash, vous obtenez un **compte marchand**. C'est l'entité centrale qui regroupe tous vos flux financiers : paiements reçus de vos clients (payin) et versements que vous effectuez (payout). Comprendre sa structure est indispensable pour anticiper où votre argent se trouve et pourquoi certaines opérations peuvent échouer.

## Un sous-compte par opérateur

Votre compte marchand n'est pas un compte unique avec un solde global. Il est composé de **sous-comptes distincts** — un par opérateur activé dans votre contrat.

```
Compte marchand MonApp
├── Sous-compte Orange Burkina    → solde : 125 000 XOF
├── Sous-compte Moov Burkina      → solde :  48 500 XOF
├── Sous-compte Wave Sénégal      → solde :  12 000 XOF
└── ...
```

Ces sous-comptes sont indépendants. Il n'existe pas de mutualisation automatique des soldes entre eux.

<Note>
  Un sous-compte est créé automatiquement lors de la première transaction reçue via cet opérateur — pas à l'activation du projet.
</Note>

## Flux entrants — le payin

Lorsqu'un client paie avec Orange Burkina, les fonds sont crédités dans votre **sous-compte Orange Burkina**. S'il paie avec Moov Burkina, les fonds vont dans votre **sous-compte Moov Burkina**. Chaque payin alimente exclusivement le sous-compte correspondant à l'opérateur utilisé.

Vous pouvez également alimenter un sous-compte manuellement via un **Cashin** : vous envoyez une demande à LigdiCash en précisant le code du sous-compte à créditer et le montant, puis vous effectuez un virement bancaire vers le compte LigdiCash. Une fois le virement vérifié, LigdiCash crédite votre sous-compte.

<Note>
  Le code de chaque sous-compte est disponible à tout moment depuis le Dashboard LigdiCash. Il est requis pour toute demande de Cashin ou Cashout.
</Note>

## Flux sortants — le payout

Lors d'un payout, les fonds quittent le **sous-compte correspondant à l'opérateur du numéro destinataire**. Si vous envoyez de l'argent vers un numéro Orange Burkina, les fonds sont prélevés sur votre sous-compte Orange Burkina.

<Warning>
  Les soldes ne sont pas mutualisés entre opérateurs. Un payout vers Orange Burkina ne peut pas être financé par votre sous-compte Moov Burkina. Si le sous-compte de l'opérateur destinataire est insuffisant, le payout échoue — même si vos autres sous-comptes sont bien approvisionnés.
</Warning>

Vous pouvez retirer des fonds d'un sous-compte via un **Cashout** : vous envoyez une demande à LigdiCash en précisant le code du sous-compte à débiter, le montant et vos coordonnées bancaires. LigdiCash déduit le montant et effectue un virement vers votre compte bancaire.

En combinant un Cashout sur un sous-compte et un Cashin sur un autre, vous pouvez **rééquilibrer vos soldes** entre opérateurs — utile avant un payout massif vers un opérateur spécifique.

<Note>
  Les demandes de Cashin et Cashout se font par email auprès de l'équipe LigdiCash. Il n'existe pas d'endpoint API pour ces opérations.
</Note>

## Retirer vos fonds depuis le dashboard

En dehors du Cashout (virement bancaire via l'équipe LigdiCash), vous pouvez initier un retrait directement depuis le dashboard sans passer par l'équipe support.

Depuis le dashboard : **Marchands → Comptes → Actions → Nouveau retrait marchand**.

Deux modes de retrait sont disponibles :

**Transfert mobile** — vous envoyez les fonds vers un numéro mobile money. Le numéro doit être saisi au format indicatif + numéro, sans espace (`22670XXXXXXX`). Le numéro destinataire doit appartenir à la **même zone monétaire** que l'opérateur du sous-compte : vous ne pouvez pas envoyer des fonds d'un sous-compte Orange Burkina vers un numéro guinéen, qui n'est pas dans la zone UEMOA. En revanche, un numéro Moov Burkina ou Orange Mali sera accepté depuis un sous-compte Orange Burkina.

**Transfert bancaire** — vous envoyez les fonds vers un compte bancaire. Dans le champ « Détails bancaires », renseignez les informations nécessaires pour le virement : nom du titulaire, nom de la banque, numéro de compte ou RIB.

Dans les deux cas, un récapitulatif affiche le montant reçu, les frais éventuels et le montant débité avant confirmation.

<Note>
  Le dashboard affiche la liste de tous vos sous-comptes marchands (projets API et projets PayLink confondus). Vous pouvez filtrer par opérateur ou par projet pour retrouver le compte à débiter.
</Note>

## Consulter vos soldes

La consultation des soldes se fait exclusivement depuis le **Dashboard LigdiCash**. Il n'existe pas d'endpoint API pour lire le solde d'un sous-compte. Prévoyez un suivi manuel ou des alertes basées sur vos propres logs de transactions si vous avez besoin de surveiller vos soldes en temps réel.

## Ce que ça change pour votre intégration

**Côté payin** — vous n'avez rien à gérer : les fonds arrivent automatiquement dans le bon sous-compte selon l'opérateur du client.

**Côté payout** — vérifiez toujours que le sous-compte de l'opérateur destinataire est suffisamment approvisionné avant d'initier un payout. Si vous faites régulièrement des payouts vers plusieurs opérateurs, surveillez vos soldes par opérateur, pas globalement.

## Pages associées

* [Vue d'ensemble de l'API de paiement](/api-paiement/vue-ensemble)
* [Payout vers wallet LigdiCash](/api-paiement/payout/vers-wallet-ligdicash)
* [Payout vers mobile money](/api-paiement/payout/vers-mobile-money)


# Cycle de vie d'une transaction
Source: https://developers.ligdicash.com/concepts/cycle-vie-transaction

Les trois statuts d'une transaction LigdiCash — pending, completed, notcompleted — et pourquoi une transaction peut rester pending indéfiniment.

Une transaction LigdiCash ne passe pas directement de « créée » à « payée ». Elle traverse des états que votre système doit savoir interpréter. Le comportement est différent de ce que l'on trouve habituellement dans d'autres passerelles de paiement — il est important de bien le comprendre avant de concevoir votre intégration.

## Les trois statuts

| Statut         | Signification                                        |
| -------------- | ---------------------------------------------------- |
| `pending`      | Transaction créée, en attente d'une issue définitive |
| `completed`    | Paiement confirmé avec succès — état final           |
| `notcompleted` | Paiement échoué ou annulé — état final               |

## Ce que `pending` signifie vraiment

`pending` est l'état par défaut de toute transaction à la création. C'est aussi l'état dans lequel la plupart des transactions **restent le plus longtemps** — et parfois indéfiniment.

Plusieurs tentatives de paiement échouées sur une même transaction ne font pas passer celle-ci à `notcompleted`. Le client peut saisir un OTP incorrect plusieurs fois : la transaction reste `pending`.

Il n'existe pas de délai d'expiration côté LigdiCash. Une transaction peut rester à `pending` des jours après sa création, pour une raison simple : un client peut déposer une réclamation auprès de son opérateur mobile money, et l'opérateur peut valider ou annuler la transaction plusieurs jours plus tard. LigdiCash attend l'issue définitive avant de mettre à jour le statut.

<Warning>
  Ne considérez jamais qu'une transaction `pending` est perdue ou expirée. Ne la recréez pas automatiquement après un délai. Attendez le callback ou interrogez `confirm` avant de prendre une décision.
</Warning>

## `completed` et `notcompleted` sont des états finaux

Une fois qu'une transaction atteint `completed` ou `notcompleted`, son statut ne changera plus. `notcompleted` est rare — il indique qu'une issue définitive négative a été confirmée (annulation opérateur, rejet définitif).

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending : Création de la transaction
    pending --> pending : Tentatives échouées, réclamations en cours
    pending --> completed : Paiement confirmé (état final)
    pending --> notcompleted : Annulation confirmée (état final, rare)
```

## Comment connaître le statut

Deux mécanismes permettent de suivre le statut d'une transaction :

**Le callback** — LigdiCash envoie une notification à votre `callback_url` quand le statut change. C'est le mécanisme principal.

**L'endpoint `confirm`** — vous pouvez interroger LigdiCash à tout moment avec le `token` stocké à la création pour obtenir le statut courant.

<Warning>
  Ne mettez jamais à jour le statut d'une commande sur la seule base du payload reçu dans le callback. Appelez toujours `confirm` avec le `token` stocké à la création pour valider. N'importe qui connaissant votre URL de callback pourrait envoyer un faux payload.
</Warning>

Consultez [Sécuriser le callback](/api-paiement/callback/securisation) pour le pattern de re-vérification complet.

## Pages associées

* [Sécuriser le callback](/api-paiement/callback/securisation) — pattern de re-vérification avec `confirm`
* [Polling vs callback](/api-paiement/verification-statut/polling-vs-callback) — quand utiliser l'un ou l'autre
* [Codes de réponse et statuts](/concepts/codes-reponse-statuts)


# Devises et montants
Source: https://developers.ligdicash.com/concepts/devises-montants

LigdiCash opère exclusivement en XOF. Format des montants et limites par opérateur.

LigdiCash opère exclusivement en **francs CFA (XOF)**. Tous les montants transmis à l'API, quelle que soit la devise d'affichage dans votre interface, doivent être exprimés en XOF.

## Devise

Le champ `devise` dans le body de toutes vos requêtes doit toujours valoir `"XOF"` :

```json theme={null}
{
  "invoice": {
    "total_amount": 5000,
    "devise": "XOF",
    ...
  }
}
```

<Warning>
  Si votre application gère plusieurs devises en interne, la conversion vers le XOF est de votre responsabilité **avant** d'appeler l'API LigdiCash. L'API n'effectue aucune conversion — elle interprète le montant reçu comme du XOF.
</Warning>

## Format des montants

Le XOF n'a pas de décimales. Tous les montants sont des **entiers** :

| ✅ Correct | ❌ Incorrect        |
| --------- | ------------------ |
| `5000`    | `5000.00`          |
| `100`     | `100.5`            |
| `25000`   | `"25000"` (chaîne) |

Les montants doivent être passés comme des **nombres entiers** (type `integer`), jamais comme des chaînes de caractères ni avec des décimales.

## Limites par opérateur

Chaque opérateur impose ses propres limites de montant par transaction. Ces limites couvrent généralement :

* **Montant minimum** par transaction
* **Montant maximum** par transaction
* **Plafond quotidien** (selon l'opérateur)

Les limites exactes sont documentées sur la page de chaque opérateur. Consultez la section [Opérateurs](/api-paiement/payin-sans-redirect/operateurs/orange-burkina) pour l'opérateur qui vous intéresse.

<Note>
  Si un montant dépasse la limite de l'opérateur, la transaction retournera une erreur. Consultez [Sous-codes par endpoint](/erreurs/sous-codes) — notamment `Echec (Code02)` sur `createInvoice` — pour les détails.
</Note>

## Pages associées

* [Codes de réponse et statuts](/concepts/codes-reponse-statuts) — interpréter les erreurs de l'API
* [Erreurs courantes](/erreurs/erreurs-courantes) — dont les erreurs de montant hors limite


# Environnements d'intégration
Source: https://developers.ligdicash.com/concepts/environnements

LigdiCash ne dispose pas de sandbox. Durant la phase d'intégration, LigdiCash vous fournit un compte réel temporaire dédié aux tests.

LigdiCash ne propose pas d'environnement sandbox distinct de la production. Il n'existe qu'un seul environnement, accessible via une seule URL de base. La distinction entre phase de test et production se fait par les **identifiants utilisés**, pas par l'URL.

## Compte d'intégration temporaire

Durant la période d'intégration, LigdiCash vous fournit un **compte LigdiCash réel temporaire** dédié à vos travaux d'intégration. Ce compte est configuré avec :

* Un projet API pré-activé
* Les opérateurs prévus par votre contrat
* Des clés `Apikey` et `API_TOKEN` prêtes à l'emploi

Vous pouvez réaliser l'intégration complète et vos tests directement sur ce compte, dans les mêmes conditions qu'en production — le code que vous écrivez n'aura pas à changer lors du passage en production.

<Note>
  Pour obtenir votre compte d'intégration temporaire, contactez [developper@ligdicash.com](mailto:developper@ligdicash.com) ou consultez les [contacts par pays](/ressources/support#contacts-par-pays).
</Note>

## URL de base

L'URL est identique durant l'intégration et en production :

```
https://app.ligdicash.com
```

## Passer en production

Une fois votre intégration terminée et validée, vous passez sur votre propre compte LigdiCash en remplaçant simplement les clés dans votre configuration :

|              | Compte d'intégration        | Compte de production         |
| ------------ | --------------------------- | ---------------------------- |
| `Apikey`     | Clé fournie par LigdiCash   | Clé de votre propre projet   |
| `API_TOKEN`  | Token fourni par LigdiCash  | Token de votre propre projet |
| URL de base  | `https://app.ligdicash.com` | `https://app.ligdicash.com`  |
| Comportement | Identique                   | Identique                    |

<Tip>
  Stockez vos clés dans des variables d'environnement (`LIGDICASH_API_KEY`, `LIGDICASH_AUTH_TOKEN`) dès le début de l'intégration. La bascule en production se résume alors à changer les valeurs de ces variables — aucune modification de code.
</Tip>

## Récupérer vos clés

Les clés `Apikey` et `API_TOKEN` sont disponibles dans le dashboard LigdiCash de votre projet. Consultez [Authentification](/concepts/authentification) pour les détails d'utilisation.

## Pages associées

* [Authentification](/concepts/authentification) — comment utiliser Apikey et API\_TOKEN
* [Projet API](/concepts/projet-api) — comment obtenir et utiliser votre projet API


# Projet API
Source: https://developers.ligdicash.com/concepts/projet-api

Le projet API LigdiCash est créé et activé par l'équipe technique, au terme des démarches administratives. Voici comment accéder à vos clés une fois le projet activé.

Un projet API LigdiCash regroupe vos clés d'authentification, les opérateurs activés sur votre compte et les paramètres de votre intégration (URL de callback, URL de retour, etc.).

<Warning>
  **Vous ne créez pas vous-même votre projet API.** C'est l'équipe technique LigdiCash qui crée et active votre projet, à l'issue du [protocole d'intégration](/essentials/protocole-integration) — après la signature du contrat, la réalisation des tests de fin d'intégration et la signature du PV. Vous n'avez aucune démarche à faire sur le dashboard pour cette étape.
</Warning>

## Ce que contient un projet API

| Élément                     | Description                                                     |
| --------------------------- | --------------------------------------------------------------- |
| `Apikey`                    | Clé qui identifie votre projet dans chaque requête              |
| `API_TOKEN`                 | Token Bearer qui authentifie vos requêtes                       |
| Opérateurs activés          | Les opérateurs mobile money et/ou Visa prévus par votre contrat |
| `callback_url`              | URL où LigdiCash envoie les notifications de paiement           |
| `return_url` / `cancel_url` | URLs de redirection après paiement (payin redirect)             |

## Récupérer vos clés

Une fois votre projet activé par l'équipe technique, connectez-vous à votre dashboard LigdiCash :

```
https://client.ligdicash.com
```

Vos clés `Apikey` et `API_TOKEN` sont disponibles dans la section de gestion de votre projet API.

<Tip>
  Stockez vos clés dans des variables d'environnement plutôt qu'en dur dans votre code. Cela facilite la bascule entre le compte d'intégration temporaire et votre compte de production sans modifier votre code source.

  ```
  LIGDICASH_API_KEY=votre_apikey
  LIGDICASH_AUTH_TOKEN=votre_api_token
  ```
</Tip>

## Comment utiliser vos clés

Toutes vos requêtes vers l'API LigdiCash doivent inclure ces deux clés en en-têtes HTTP :

```
Apikey: {API_KEY}
Authorization: Bearer {AUTH_TOKEN}
Accept: application/json
Content-Type: application/json
```

Consultez [Authentification](/concepts/authentification) pour les détails.

## Compte d'intégration vs compte de production

Durant la phase d'intégration, l'équipe technique vous fournit un compte temporaire avec un projet API pré-activé. Ce compte est utilisé pour vos travaux d'intégration et vos tests.

Lors du passage en production, vous créez votre propre compte LigdiCash via l'application mobile ([App Store / Play Store](https://www.ligdicash.com/download)) et l'équipe technique y active votre projet de production. Seules vos clés changent — le code, les endpoints et la structure des requêtes restent identiques.

Consultez [Environnements](/concepts/environnements) pour le détail du processus.

## Modifier la configuration du projet

Pour toute modification de votre projet API en production (ajouter un opérateur, changer l'URL de callback, etc.), contactez l'équipe technique via le groupe Microsoft Teams dédié à votre intégration.

## Pages associées

* [Protocole d'intégration](/essentials/protocole-integration) — comment obtenir votre projet API
* [Authentification](/concepts/authentification) — utiliser Apikey et API\_TOKEN dans vos requêtes
* [Environnements](/concepts/environnements) — compte temporaire vs compte de production


# Tokens et identifiants
Source: https://developers.ligdicash.com/concepts/tokens-et-identifiants

Différence entre token, request_id, transaction_id et external_id dans l'API LigdiCash — quel identifiant utiliser pour quoi.

L'API LigdiCash fait circuler plusieurs identifiants dans les requêtes, les réponses et les callbacks. Ils ont des rôles distincts et ne sont pas interchangeables. Confondre `token` et `transaction_id`, par exemple, est l'une des erreurs les plus fréquentes lors d'une première intégration.

## Tableau de synthèse

| Identifiant      | Généré par  | Format        | Où il apparaît                                     | Rôle                                                |
| ---------------- | ----------- | ------------- | -------------------------------------------------- | --------------------------------------------------- |
| `token`          | LigdiCash   | Chaîne longue | Réponse création + callback                        | Appeler `confirm`                                   |
| `request_id`     | LigdiCash   | `PXXXXXXXX`   | Page de paiement + callback                        | Référence courte affichable                         |
| `transaction_id` | Le marchand | Libre         | `custom_data` de la requête + callback + dashboard | Réconciliation marchand                             |
| `external_id`    | Le marchand | Libre         | Champ `invoice` de la requête                      | Équivalent de `transaction_id`, syntaxe alternative |

## Le token

Le `token` est généré par LigdiCash à la création de chaque transaction. Il est retourné dans la réponse de création :

```json theme={null}
{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
```

Son **unique utilité** est d'être passé à l'endpoint `confirm` pour vérifier le statut d'une transaction. Stockez-le en base dès la création.

<Warning>
  La valeur du `token` dans le callback est différente de celle obtenue à la création. N'utilisez jamais le token comme identifiant de transaction — il n'est pas stable. Utilisez votre `transaction_id` pour la réconciliation.
</Warning>

## Le request\_id

Le `request_id` est un identifiant court généré par LigdiCash pour chaque transaction. Son format est `PXXXXXXXX` — par exemple `P2756808232026`.

Il est affiché sur la page de paiement LigdiCash et est présent dans le callback. Sa concision le rend facile à communiquer : un marchand peut l'afficher à son client comme référence de paiement, par exemple sur un reçu ou dans une interface de suivi.

<Tip>
  Le `request_id` est un bon identifiant à montrer à vos clients pour le suivi ou le support — il est court, unique et reconnu par LigdiCash.
</Tip>

## Le transaction\_id

Le `transaction_id` est un identifiant que **vous générez côté marchand** et que vous injectez dans le champ `custom_data` de votre requête. LigdiCash vous le retourne dans le callback et l'affiche dans votre dashboard parmi vos transactions payin et payout.

C'est le pivot de votre réconciliation : il fait le lien entre une transaction LigdiCash et votre propre système de commandes.

Le format est entièrement libre — référence commande, UUID, code court lisible par un client, etc.

Consultez [Le pattern transaction\_id](/concepts/transaction-id-pattern) pour les bonnes pratiques de format et d'utilisation.

## L'external\_id

L'`external_id` est l'équivalent direct du `transaction_id` — ils servent le même objectif. La différence est leur emplacement dans la requête : `external_id` est un champ du bloc `invoice`, tandis que `transaction_id` est injecté dans `custom_data`.

```json theme={null}
"invoice": {
  "total_amount": 5000,
  "devise": "XOF",
  "external_id": "ORD-2026-00042",
  "otp": "",
  ...
}
```

Utilisez l'un ou l'autre selon ce qui convient mieux à votre architecture — pas les deux simultanément. Dans les réponses de l'API, ces deux champs auront la même valeur.

<Note>
  Les deux sont retournés dans le callback. Utilisez celui qui correspond le mieux à votre architecture — ils auront la même valeur dans les réponses de l'API.
</Note>

## Pages associées

* [Le pattern transaction\_id](/concepts/transaction-id-pattern) — format, cycle de vie, extraction dans le callback
* [Sécuriser le callback](/api-paiement/callback/securisation) — pourquoi re-vérifier avec le token stocké
* [Codes de réponse et statuts](/concepts/codes-reponse-statuts)


# Le pattern transaction_id : la règle d'or
Source: https://developers.ligdicash.com/concepts/transaction-id-pattern

Pourquoi générer et stocker votre propre identifiant de transaction avant chaque appel API LigdiCash — et comment le retrouver dans le callback et le dashboard.

Lorsque vous créez une transaction via l'API LigdiCash, vous recevez un `token` en retour. Ce token **n'est pas stable** : sa valeur dans le callback diffère de celle obtenue à la création. Si vous vous appuyez sur lui pour identifier vos transactions, vous perdrez le fil entre ce que vous avez initié et ce que vous avez confirmé.

La solution est simple : générez votre propre identifiant côté marchand, stockez-le **avant** d'appeler l'API, et passez-le dans le champ `custom_data`. LigdiCash vous le renverra intact dans le callback, et l'affichera dans votre dashboard.

## Le problème : le token change entre création et callback

À la création d'une transaction, l'API retourne un `token` :

```json theme={null}
{
  "response_code": "00",
  "token": "abc123-creation",
  ...
}
```

Lorsque LigdiCash vous notifie du résultat via le callback, ce même champ contient une **valeur différente** :

```json theme={null}
{
  "token": "xyz789-callback",
  ...
}
```

Les deux tokens désignent la même transaction, mais vous ne pouvez pas les relier directement. Sans identifiant propre à votre système, la réconciliation est impossible.

## La solution : injecter votre transaction\_id dans custom\_data

Le champ `custom_data` de chaque requête est un **objet JSON** dont vous définissez librement les clés. C'est ici que vous injectez votre identifiant :

```json theme={null}
"custom_data": {
  "transaction_id": "COMMANDE-20240815-00042"
}
```

Dans le callback, LigdiCash transforme cet objet en un **tableau**. Votre `transaction_id` y apparaît sous cette forme :

```json theme={null}
"custom_data": [
  {
    "keyof_customdata": "transaction_id",
    "valueof_customdata": "COMMANDE-20240815-00042",
    "datecreation_customdata": "2026-02-17 06:56:46.55245"
  }
]
```

Filtrez sur `keyof_customdata` pour extraire votre valeur — ne vous fiez pas à la position dans le tableau, d'autres entrées peuvent être présentes.

### Format du transaction\_id

Vous êtes libre de choisir le format qui correspond à votre métier :

| Format                | Exemple                                | Usage typique                      |
| --------------------- | -------------------------------------- | ---------------------------------- |
| Référence commande    | `ORD-2026-00042`                       | E-commerce — affiché au client     |
| Code court lisible    | `PAY-8KXZ`                             | Support client, mémorisable        |
| UUID v4               | `f47ac10b-58cc-4372-a567-0e02b2c3d479` | Systèmes distribués, usage interne |
| Timestamp + aléatoire | `1723718400-a3f9`                      | File de jobs                       |
| ID interne            | `order_8821`                           | Application existante              |

<Tip>
  Si vous affichez le `transaction_id` à vos clients — par exemple sur le reçu ou dans l'interface de suivi — privilégiez un format court et lisible comme `ORD-2026-00042`. Cela facilite les échanges avec votre support : le client peut le dicter ou le recopier sans erreur.
</Tip>

<Tip>
  Si le `transaction_id` reste purement interne, un UUID v4 est un bon choix par défaut : garanti unique sans coordination entre serveurs.
</Tip>

<Warning>
  Évitez les identifiants purement séquentiels exposés côté client (ex : `order_1`, `order_2`) — ils révèlent votre volume de transactions. Préférez un préfixe + compteur non trivial, ou un identifiant aléatoire.
</Warning>

## Cycle de vie recommandé

<Steps>
  <Step title="Générez le transaction_id">
    Avant d'appeler l'API, générez votre identifiant unique côté serveur.
  </Step>

  <Step title="Persistez-le en base">
    Enregistrez-le en base de données avec le statut `pending` **avant** d'appeler l'API. Si l'appel échoue, vous avez quand même la trace.
  </Step>

  <Step title="Passez-le dans custom_data">
    Incluez-le dans le tableau `custom_data` de votre requête de création.
  </Step>

  <Step title="Stockez le token de création">
    Conservez également le `token` retourné par l'API — il sera nécessaire pour appeler l'endpoint `confirm` lors de la re-vérification du callback.
  </Step>

  <Step title="Retrouvez-le dans le callback">
    Quand LigdiCash vous notifie, extrayez votre `transaction_id` depuis `custom_data` et mettez à jour le statut en base.
  </Step>
</Steps>

## Retrouver le transaction\_id dans le callback

Le payload du callback contient un champ `custom_data`. Sa forme varie selon le flux (voir [Parser custom\_data](/api-paiement/callback/parser-custom-data)), mais pour un payin il s'agit d'un tableau :

<CodeGroup>
  ```javascript Node.js theme={null}
  function extractTransactionId(customData) {
    if (!Array.isArray(customData)) return null;
    const entry = customData.find(
      (item) => item.keyof_customdata === "transaction_id"
    );
    return entry?.valueof_customdata ?? null;
  }
  ```

  ```php PHP theme={null}
  function extractTransactionId(array $customData): ?string {
      foreach ($customData as $item) {
          if ($item['keyof_customdata'] === 'transaction_id') {
              return $item['valueof_customdata'];
          }
      }
      return null;
  }
  ```

  ```python Python theme={null}
  def extract_transaction_id(custom_data: list) -> str | None:
      for item in custom_data:
          if item.get("keyof_customdata") == "transaction_id":
              return item.get("valueof_customdata")
      return None
  ```
</CodeGroup>

<Warning>
  Le callback contient aussi un champ `transaction_id` **à la racine** du payload. LigdiCash le construit en concaténant les `valueof_customdata` de toutes les entrées dont la clé contient `id` (ex : `transaction_id`, `partner_id`, `event_id`…), séparés par `;`. Si vous avez injecté plusieurs champs de ce type, cette valeur racine sera un mélange — pas votre identifiant seul. Préférez toujours l'extraction depuis le tableau `custom_data`.
</Warning>

## Visibilité dans le dashboard LigdiCash

Le `transaction_id` que vous injectez dans `custom_data` est affiché dans le dashboard LigdiCash, dans le tableau des transactions — aussi bien pour les **payin** que pour les **payout**. Cela vous permet de réconcilier visuellement vos transactions sans avoir à interroger votre propre base de données.

## Exemple de requête complet

<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 {AUTH_TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "commande": {
        "invoice": {
          "items": [{ "name": "Abonnement Pro", "price": 5000, "quantity": 1 }],
          "total_amount": 5000,
          "devise": "XOF",
          "description": "Abonnement Pro — Janvier 2025",
          "customer": "",
          "customer_firstname": "Amadou",
          "customer_lastname": "Diallo",
          "customer_email": "amadou@exemple.com"
        },
        "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": "COMMANDE-20240815-00042"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  import { randomUUID } from "crypto";

  const transactionId = randomUUID(); // ou votre propre format

  // Persistez transactionId en base avec statut "pending" avant ce fetch
  await db.orders.update({ id: orderId, ligdicash_tx_id: transactionId, status: "pending" });

  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_AUTH_TOKEN}`,
        Accept: "application/json",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        commande: {
          invoice: {
            items: [{ name: "Abonnement Pro", price: 5000, quantity: 1 }],
            total_amount: 5000,
            devise: "XOF",
            description: "Abonnement Pro — Janvier 2025",
            customer: "",
            customer_firstname: "Amadou",
            customer_lastname: "Diallo",
            customer_email: "amadou@exemple.com",
          },
          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: transactionId },
        },
      }),
    }
  );

  const data = await response.json();
  // Stockez data.token pour la re-vérification ultérieure
  await db.orders.update({ ligdicash_tx_id: transactionId, ligdicash_token: data.token });
  ```
</CodeGroup>

## Pages associées

* [Tokens et identifiants](/concepts/tokens-et-identifiants) — différences entre `token`, `transaction_id` et `external_id`
* [Sécuriser le callback](/api-paiement/callback/securisation) — pourquoi re-vérifier avec le token stocké
* [Parser custom\_data](/api-paiement/callback/parser-custom-data) — les 3 formes possibles de `custom_data`


# Le champ wiki
Source: https://developers.ligdicash.com/erreurs/champ-wiki

Comment utiliser le champ wiki retourné par chaque endpoint pour décoder les sous-codes d'erreur Echec (CodeXX) en messages lisibles.

Chaque réponse de l'API LigdiCash — qu'elle soit un succès ou un échec — contient un champ `wiki` avec une URL vers la documentation des sous-codes de l'endpoint appelé. Ce champ est votre point d'entrée principal pour comprendre la cause exacte d'un `response_code: "01"`.

## Les URLs wiki par endpoint

| Endpoint                                         | URL wiki                                                     |
| ------------------------------------------------ | ------------------------------------------------------------ |
| `POST /pay/v01/redirect/checkout-invoice/create` | `https://client.ligdicash.com/wiki/createInvoice`            |
| `GET /pay/v01/redirect/checkout-invoice/confirm` | `https://client.ligdicash.com/wiki/confirmInvoice`           |
| `POST /pay/v01/straight/checkout-invoice/create` | `https://client.ligdicash.com/wiki/createInvoice`            |
| `POST /pay/v01/withdrawal/create`                | `https://client.ligdicash.com/wiki/createWithdrawal`         |
| `POST /pay/v01/straight/payout`                  | `https://client.ligdicash.com/wiki/createStraightWithdrawal` |
| `POST /pay/v01/withdrawal/confirm`               | `https://client.ligdicash.com/wiki/confirmInvoice`           |

<Note>
  L'URL wiki est toujours retournée dans la réponse, même en cas de succès. Vous n'avez pas besoin de la coder en dur dans votre application — lisez-la directement depuis le champ `wiki` de la réponse.
</Note>

## Format de la page wiki

La page wiki retourne une structure de données au format `var_dump` PHP listant tous les sous-codes possibles pour cet endpoint :

```
array:2 [▼
  0 => array:2 [▶]
  1 => array:3 [▼
    "code" => "01"
    "description" => "There is an error"
    "subcodes" => array:N [▼
      0 => array:2 [▼
        "code" => "Echec (Code00)"
        "description" => "Authentification failure"
      ]
      1 => array:2 [▼
        "code" => "Echec (Code01)"
        "description" => "Merchant Payout not activated"
      ]
      ...
    ]
  ]
]
```

Chaque entrée de `subcodes` correspond à une valeur possible de `response_text` et sa signification en anglais.

## Pattern d'utilisation côté backend

L'approche recommandée est de fetch la page wiki uniquement quand `response_code === "01"`, pour enrichir vos logs et construire un message adapté à votre utilisateur.

<CodeGroup>
  ```javascript Node.js theme={null}
  async function handleLigdicashError(data) {
    if (data.response_code !== "01") return;

    // Fetch la page wiki pour décoder le sous-code
    let wikiDescription = data.response_text; // fallback
    try {
      const wikiRes = await fetch(data.wiki);
      const wikiText = await wikiRes.text();
      // Extraire la description du sous-code (parsing selon votre besoin)
      // Exemple : chercher la ligne contenant data.response_text
      wikiDescription = parseWikiDescription(wikiText, data.response_text);
    } catch (e) {
      // La wiki est optionnelle — ne pas bloquer si indisponible
    }

    logger.error({
      event: "ligdicash_error",
      subcode: data.response_text,       // ex: "Echec (Code00)"
      description: wikiDescription,      // ex: "Authentification failure"
      wiki_url: data.wiki,
    });

    return {
      userMessage: buildUserMessage(data.response_text),
      technicalCode: data.response_text,
    };
  }
  ```

  ```php PHP theme={null}
  function handleLigdicashError(array $data): array {
      if ($data['response_code'] !== '01') {
          return [];
      }

      $wikiDescription = $data['response_text']; // fallback
      try {
          $wikiContent = file_get_contents($data['wiki']);
          // Parser le contenu pour trouver la description du sous-code
          // $wikiDescription = parseWikiDescription($wikiContent, $data['response_text']);
      } catch (\Exception $e) {
          // La wiki est optionnelle — ne pas bloquer
      }

      error_log(json_encode([
          'event'       => 'ligdicash_error',
          'subcode'     => $data['response_text'],
          'description' => $wikiDescription,
          'wiki_url'    => $data['wiki'],
      ]));

      return [
          'userMessage'   => buildUserMessage($data['response_text']),
          'technicalCode' => $data['response_text'],
      ];
  }
  ```

  ```python Python theme={null}
  import requests
  import logging

  def handle_ligdicash_error(data: dict) -> dict:
      if data.get("response_code") != "01":
          return {}

      wiki_description = data["response_text"]  # fallback
      try:
          wiki_res = requests.get(data["wiki"], timeout=3)
          # Parser le contenu pour trouver la description du sous-code
          # wiki_description = parse_wiki_description(wiki_res.text, data["response_text"])
      except Exception:
          pass  # La wiki est optionnelle

      logging.error({
          "event": "ligdicash_error",
          "subcode": data["response_text"],
          "description": wiki_description,
          "wiki_url": data["wiki"],
      })

      return {
          "user_message": build_user_message(data["response_text"]),
          "technical_code": data["response_text"],
      }
  ```
</CodeGroup>

## Construire des messages utilisateur

Le `response_text` (`Echec (CodeXX)`) est un code technique à ne jamais afficher directement à l'utilisateur final. Construisez un mapping dans votre application :

```javascript Node.js theme={null}
const USER_MESSAGES = {
  "Echec (Code00)": "Vos identifiants API sont invalides. Vérifiez votre Apikey et votre token d'autorisation.",
  "Echec (Code01)": "Cette opération n'est pas activée sur votre compte. Contactez le support LigdiCash.",
  // Ajoutez les autres sous-codes selon la page /erreurs/sous-codes
};

function buildUserMessage(subcode) {
  return USER_MESSAGES[subcode] ?? "Une erreur est survenue. Veuillez réessayer ou contacter le support.";
}
```

<Tip>
  Maintenez ce mapping dans une configuration externe (base de données, fichier JSON) plutôt qu'en dur dans le code, afin de pouvoir le mettre à jour sans redéploiement si LigdiCash ajoute de nouveaux sous-codes.
</Tip>

## Intégration dans votre monitoring

En production, enrichissez vos alertes avec le sous-code wiki :

```javascript Node.js theme={null}
// Exemple avec un système de monitoring type Sentry / Datadog
if (data.response_code === "01") {
  monitoring.captureEvent({
    message: `LigdiCash payment rejected: ${data.response_text}`,
    level: "error",
    tags: {
      ligdicash_subcode: data.response_text,
      ligdicash_wiki: data.wiki,
      endpoint: "createInvoice",
    },
  });
}
```

***

## Pages associées

* [Liste des sous-codes](/erreurs/sous-codes) — référence de tous les `Echec (CodeXX)` par endpoint
* [Erreurs courantes](/erreurs/erreurs-courantes) — causes, solutions et sous-codes associés
* [Codes de réponse et statuts](/concepts/codes-reponse-statuts) — vue d'ensemble de `response_code`


# Erreurs courantes et solutions
Source: https://developers.ligdicash.com/erreurs/erreurs-courantes

Les erreurs les plus fréquentes rencontrées par les marchands lors de l'intégration LigdiCash, leurs causes réelles et comment les résoudre.

Cette page recense les erreurs les plus fréquentes rencontrées en intégration et en production, issues du retour terrain des marchands LigdiCash.

<Note>
  Les sous-codes (`Echec (CodeXX)`) sont propres à chaque endpoint. Consultez [la liste des sous-codes](/erreurs/sous-codes) pour la correspondance complète. Pour décoder un sous-code en production, utilisez le champ `wiki` retourné dans la réponse.
</Note>

***

## Authentification échouée

**Symptôme** : `response_code: "01"`, `response_text: "Echec (Code00)"` sur chaque requête.

**Causes probables** :

* L'en-tête `Apikey` est absent ou incorrect
* L'en-tête `Authorization` ne suit pas le format `Bearer {AUTH_TOKEN}`
* Le token d'autorisation a expiré ou été révoqué
* Les clés utilisées appartiennent à un autre projet API

**Solution** :

```bash cURL theme={null}
curl -X POST https://app.ligdicash.com/pay/v01/... \
  -H "Apikey: {API_KEY}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
```

Vérifiez vos clés dans le [dashboard LigdiCash](https://client.ligdicash.com) sous le projet API concerné. Si le problème persiste, contactez le support.

***

## Payin ou payout non activé sur le compte

**Symptôme** : `response_code: "01"`, `response_text: "Echec (Code01)"` dès la création de la transaction.

**Cause** : La fonctionnalité payin ou payout n'est pas activée sur votre projet API LigdiCash.

**Solution** :

Contactez l'équipe LigdiCash pour activer la fonctionnalité concernée : [developper@ligdicash.com](mailto:developper@ligdicash.com) ou via votre Partner Manager. Précisez votre identifiant de projet API.

***

## Mauvaise route pour le payout

**Symptôme** : `response_code: "01"`, `response_text: "Echec (Code02)"` sur l'endpoint `withdrawal/create`, avec la description *"Customer not registered on the platform"*.

**Cause** : L'endpoint `POST /pay/v01/withdrawal/create` effectue un payout vers le **wallet LigdiCash** du client. Il exige donc que le client ait un compte enregistré sur la plateforme LigdiCash. Si vous souhaitez envoyer directement vers un numéro mobile money sans compte LigdiCash préalable, vous devez utiliser l'autre endpoint.

<Warning>
  LigdiCash propose deux routes de payout avec des usages distincts :

  | Endpoint                          | Destination                     | Condition                                |
  | --------------------------------- | ------------------------------- | ---------------------------------------- |
  | `POST /pay/v01/withdrawal/create` | Wallet LigdiCash du client      | Le client doit avoir un compte LigdiCash |
  | `POST /pay/v01/straight/payout`   | Numéro mobile money directement | Aucun compte LigdiCash requis            |

  Utiliser `withdrawal/create` pour un client sans compte LigdiCash retourne systématiquement `Echec (Code02)`.
</Warning>

Consultez [Payout vers wallet LigdiCash](/api-paiement/payout/vers-wallet-ligdicash) et [Payout vers mobile money](/api-paiement/payout/vers-mobile-money) pour choisir la bonne route selon votre cas d'usage.

***

## IP non whitelistée

**Symptôme** : `response_code: "01"`, `response_text: "Echec (Code03)"` (createInvoice) ou `"Echec (Code06)"` (createWithdrawal / createStraightWithdrawal) — *"IP Denied"*.

**Cause** : Les endpoints de payout requièrent que l'adresse IP du serveur appelant soit autorisée sur votre projet LigdiCash. Si votre serveur utilise une IP dynamique (qui change à chaque redémarrage ou reconnexion), vous serez bloqué dès que l'IP change.

**Contrainte importante** : LigdiCash limite le nombre d'IPs whitelistées à **3 adresses maximum** par projet.

**Solution** :

1. Identifiez l'adresse IP fixe de votre serveur de production.
2. Transmettez-la au support technique LigdiCash ([developper@ligdicash.com](mailto:developper@ligdicash.com)) pour qu'il l'ajoute à la whitelist de votre projet — cette opération ne peut pas être faite depuis le dashboard marchand.
3. Si votre infrastructure utilise des IPs dynamiques (hébergement mutualisé, VPS sans IP fixe, CI/CD), vous devez soit :
   * Passer par un **proxy sortant à IP fixe** pour tous vos appels vers LigdiCash
   * Migrer vers un hébergement avec IP dédiée fixe

<Note>
  La contrainte des 3 IPs maximum est importante si vous avez plusieurs environnements (développement, staging, production). Réservez les 3 slots à vos serveurs de production et testez en staging depuis le même IP si possible. Anticipez cette demande avant la mise en production — le délai de configuration dépend du support LigdiCash.
</Note>

***

## Solde marchand insuffisant par opérateur

**Symptôme** : `response_code: "01"`, `response_text: "Echec (Code04)"` (createWithdrawal) ou `"Echec (Code08)"` (createStraightWithdrawal) — *"Merchant balance low"* ou *"Merchant operator account low balance"*.

**Cause** : Votre compte marchand LigdiCash dispose d'un solde distinct **par opérateur**. Un payout vers Orange Money Burkina débitera votre solde Orange Burkina, pas votre solde global. Si ce solde opérateur est insuffisant, le payout échoue même si votre solde global est positif.

**Solution** :

Rechargez le solde de l'opérateur concerné via le [dashboard LigdiCash](https://client.ligdicash.com). Surveillez les soldes par opérateur indépendamment et mettez en place des alertes de bas solde pour chaque opérateur que vous utilisez.

***

## Montant hors limites

**Symptôme** : `response_code: "01"`, `response_text: "Echec (Code02)"` sur createInvoice — *"Wrong amount"*.

**Causes probables** :

* Montant inférieur à 9 XOF ou supérieur à 2 000 000 XOF (limites globales LigdiCash)
* Montant non entier (`500.5` au lieu de `500` ou `501`)
* Plafond quotidien du client mobile money atteint côté opérateur

<Warning>
  Le XOF n'a pas de sous-unité. Le montant doit toujours être un entier. `500.5` sera rejeté.
</Warning>

Validez le montant côté serveur avant d'appeler l'API :

```javascript Node.js theme={null}
function validerMontant(montant) {
  if (!Number.isInteger(montant)) throw new Error("Montant non entier");
  if (montant < 9)        throw new Error("Montant minimum : 9 XOF");
  if (montant > 2000000)  throw new Error("Montant maximum : 2 000 000 XOF");
}
```

***

## Transaction en pending malgré un OTP valide

**Symptôme** : La transaction reste indéfiniment à `status: "pending"` alors que le client affirme avoir généré l'OTP correctement.

**Cause** : Pour les opérateurs en mode OTP USSD (Orange Money Burkina Faso...), le client génère un OTP via son menu USSD en saisissant le montant exact de la transaction. Si vous avez configuré votre intégration pour que **les frais de transaction soient à la charge du client**, le montant que le client doit saisir dans son USSD est le montant de base **plus les frais**. Si le client ne saisit que le montant de base, l'OTP est valide mais le montant attendu ne correspond pas — LigdiCash ne peut pas valider la transaction et la laisse en `pending`.

**Exemple** :

* Montant de la transaction : 10 000 XOF
* Frais à la charge du client : 200 XOF
* Montant à saisir dans le USSD : **10 200 XOF**
* Si le client saisit 10 000 XOF → OTP valide mais montant incorrect → `pending` indéfini

**Solution** :

Si les frais sont à la charge du client, votre interface doit afficher clairement le montant total à saisir dans l'USSD, frais inclus. Communiquez ce montant dans vos instructions à l'écran avant que le client ne compose le code USSD.

```
⚠️ Composez le code USSD avec le montant exact : 10 200 XOF (10 000 XOF + 200 XOF de frais)
```

Si les frais sont à votre charge (côté marchand), le client saisit uniquement le montant de la transaction, et vous l'absorbez dans votre marge.

***

## Incompréhension du statut pending

**Symptôme** : Vous attendez un callback avec `status: "notcompleted"` après un OTP invalide ou expiré, mais aucun callback n'arrive — la transaction reste indéfiniment en `pending`.

**Cause** : LigdiCash ne considère pas automatiquement une transaction comme échouée parce que l'OTP était incorrect. Du point de vue de LigdiCash, la transaction peut encore aboutir si le client fournit le bon OTP — la fenêtre d'attente est indéfinie. LigdiCash n'envoie un callback `notcompleted` que lorsque l'opérateur lui-même communique un signal d'échec définitif. Tant que ce signal n'arrive pas, la transaction reste en `pending`, qu'il s'écoule 5 minutes ou plusieurs heures.

<Warning>
  Ne vous fiez pas à LigdiCash pour décider quand une transaction est "expirée". C'est à votre système de définir un timeout métier et d'agir en conséquence.
</Warning>

**Solution** :

Définissez un timeout côté marchand (par exemple 15 minutes après la création) au-delà duquel vous passez la transaction en `timeout` dans votre base et notifiez le client pour relancer la démarche :

```javascript Node.js theme={null}
// Vérification périodique des transactions pending
async function verifierTransactionsPending() {
  const timeout = new Date(Date.now() - 15 * 60 * 1000); // 15 minutes

  const pendingTransactions = await db.transactions.findAll({
    where: {
      status: "pending",
      created_at: { [Op.lt]: timeout },
    },
  });

  for (const tx of pendingTransactions) {
    // Dernier appel à confirm avant d'abandonner
    const confirm = await appellerConfirm(tx.ligdicash_token);

    if (confirm.status === "completed") {
      await tx.update({ status: "completed" });
    } else {
      // Toujours pending après 15 min → timeout côté marchand
      await tx.update({ status: "timeout" });
      await notifierClient(tx, "Votre paiement n'a pas abouti. Veuillez réessayer.");
    }
  }
}
```

***

## Double callback non géré

**Symptôme** : Une même transaction déclenche deux actions dans votre système (double livraison, double crédit de compte...).

**Cause** : LigdiCash envoie systématiquement **deux requêtes POST** pour chaque événement de callback : une en `application/x-www-form-urlencoded` et une en `application/json`. Ce comportement est normal et documenté. Si votre handler callback ne déduplique pas, il traitera les deux requêtes.

**Solution** :

Vérifiez en base si la transaction a déjà été traitée avant tout traitement métier :

```javascript Node.js theme={null}
async function handleCallback(payload) {
  const transactionId = payload.custom_data?.find(
    e => e.keyof_customdata === "transaction_id"
  )?.valueof_customdata;

  const transaction = await db.transactions.findOne({
    where: { transaction_id: transactionId }
  });

  if (transaction?.status === "completed") {
    return res.status(200).send("OK"); // Déjà traité
  }

  // ... traitement métier
}
```

Voir [Idempotence et déduplication](/api-paiement/callback/idempotence) pour le pattern complet.

***

## Callback reçu mais transaction introuvable en base

**Symptôme** : Vous recevez un callback valide mais votre système ne retrouve pas la transaction correspondante, ou l'appel à `confirm` retourne `Echec (Code02) — Invoice not found`.

**Causes probables** :

* Vous recherchez la transaction avec un identifiant autre que le `transaction_id` que vous avez stocké à la création (ID interne, numéro de commande, token callback...)
* Vous utilisez le `token` du payload callback pour appeler `confirm`, alors qu'il faut utiliser le `token` de création

<Warning>
  Deux tokens différents circulent dans votre intégration :

  | Token                 | Où                                          | Usage                                        |
  | --------------------- | ------------------------------------------- | -------------------------------------------- |
  | Token de **création** | Retourné dans `response_text` à la création | À stocker en base, à utiliser pour `confirm` |
  | Token de **callback** | Présent dans le payload callback            | À ne jamais utiliser pour `confirm`          |

  Ces deux tokens sont distincts et non interchangeables.
</Warning>

**Solution** :

Stockez le `transaction_id` que vous avez envoyé dans `custom_data` à la création, et retrouvez la transaction avec ce même `transaction_id` dans le callback :

```javascript Node.js theme={null}
// À la création — stocker le transaction_id et le token LigdiCash
await db.transactions.create({
  transaction_id: "TXN-MON-ID-INTERNE",  // votre identifiant
  ligdicash_token: response.token,         // token LigdiCash de création
  status: "pending",
});

// Dans le callback — retrouver par transaction_id, pas par token callback
function extraireTransactionId(callbackPayload) {
  const customData = callbackPayload.custom_data;
  if (!Array.isArray(customData)) return null;
  const entry = customData.find(e => e.keyof_customdata === "transaction_id");
  return entry?.valueof_customdata ?? null;
}

const transactionId = extraireTransactionId(callbackPayload);
const transaction = await db.transactions.findOne({
  where: { transaction_id: transactionId }
});
```

Voir [Pattern transaction\_id](/concepts/transaction-id-pattern) et [Sécurisation du callback](/api-paiement/callback/securisation) pour les patterns complets.

***

## Pages associées

* [Le champ wiki](/erreurs/champ-wiki) — décoder `Echec (CodeXX)` en message lisible
* [Liste des sous-codes](/erreurs/sous-codes) — référence complète par endpoint
* [Idempotence et déduplication](/api-paiement/callback/idempotence) — gérer les double callbacks
* [Sécurisation du callback](/api-paiement/callback/securisation) — re-vérification via confirm
* [Pattern transaction\_id](/concepts/transaction-id-pattern) — identifier vos transactions de façon fiable


# Liste des sous-codes par endpoint
Source: https://developers.ligdicash.com/erreurs/sous-codes

Référence complète des sous-codes Echec (CodeXX) retournés par chaque endpoint LigdiCash, avec leur description et l'action recommandée.

Quand `response_code` vaut `01`, le champ `response_text` contient un sous-code de la forme `Echec (CodeXX)`. Ce sous-code est propre à l'endpoint appelé. Cette page liste l'ensemble des sous-codes possibles pour chacun.

<Tip>
  En production, vous n'avez pas besoin de coder ces tables en dur. Chaque réponse API contient un champ `wiki` avec l'URL de la page de sous-codes de l'endpoint appelé. Voir [Le champ wiki](/erreurs/champ-wiki).
</Tip>

***

## createInvoice

Endpoint : `POST /pay/v01/redirect/checkout-invoice/create` et `POST /pay/v01/straight/checkout-invoice/create`

Wiki : `https://client.ligdicash.com/wiki/createInvoice`

| Sous-code        | Description                                    | Action recommandée                                                                                     |
| ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `Echec (Code00)` | Authentification failure                       | Vérifier `Apikey` et `Authorization: Bearer`                                                           |
| `Echec (Code01)` | Merchant Payin not activated                   | Contacter le support LigdiCash pour activer le payin                                                   |
| `Echec (Code02)` | Wrong amount (must be between 9 and 2 000 000) | Corriger le montant — entier entre 9 et 2 000 000 XOF                                                  |
| `Echec (Code03)` | IP Denied                                      | L'IP du serveur n'est pas autorisée — Contacter le support technique pour whitelister votre adresse IP |
| `Echec (Code04)` | An error occurred while processing request     | Erreur interne LigdiCash — retenter                                                                    |
| `Echec (Code05)` | An error occurred while sending request        | Erreur d'envoi vers l'opérateur — retenter                                                             |
| `Echec (Code06)` | An error occurred while sending request        | Erreur d'envoi vers l'opérateur — retenter                                                             |
| `Echec (Code07)` | No network access configured                   | L'opérateur correspondant n'est pas configuré pour ce projet — contacter LigdiCash                     |
| `Echec (Code08)` | Data Input error                               | Payload malformé — vérifier tous les champs obligatoires                                               |
| `Echec (Code09)` | Api error                                      | Erreur interne API — contacter le support                                                              |
| `Echec (Code10)` | No hash provided                               | Hash absent de la requête — vérifier la construction des en-têtes                                      |
| `Echec (Code11)` | Invalid hash                                   | Hash invalide — vérifier la signature de la requête                                                    |
| `Echec (Code12)` | Invalid method                                 | Méthode HTTP incorrecte                                                                                |
| `Echec (Code13)` | Unauthorized method                            | Méthode non autorisée pour ce projet                                                                   |
| `Echec (Code14)` | Wrong Wallet Credentials                       | Identifiants wallet incorrects                                                                         |
| `Echec (Code15)` | Wrong OTP                                      | OTP incorrect — demander au client de regénérer et re-saisir                                           |
| `Echec (Code16)` | Expired OTP                                    | OTP expiré — créer une nouvelle transaction et recommencer le flux OTP                                 |
| `Echec (Code17)` | Wrong OTP Amount                               | Montant de l'OTP ne correspond pas au montant de la transaction                                        |
| `Echec (Code18)` | Wallet low balance                             | Solde du wallet LigdiCash insuffisant                                                                  |

***

## confirmInvoice

Endpoint : `GET /pay/v01/redirect/checkout-invoice/confirm` et `POST /pay/v01/withdrawal/confirm`

Wiki : `https://client.ligdicash.com/wiki/confirmInvoice`

| Sous-code        | Description                                | Action recommandée                                                                                                          |
| ---------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `Echec (Code00)` | Authentification failure                   | Vérifier `Apikey` et `Authorization: Bearer`                                                                                |
| `Echec (Code01)` | Merchant Payin not activated               | Contacter le support LigdiCash                                                                                              |
| `Echec (Code02)` | Invoice not found                          | Le token passé est invalide ou appartient à un autre projet — utiliser le token stocké à la création, pas celui du callback |
| `Echec (Code03)` | An error occurred while processing request | Erreur interne — retenter                                                                                                   |
| `Echec (Code04)` | Data Input error                           | Paramètre manquant ou malformé dans la requête confirm                                                                      |

<Warning>
  `Echec (Code02) — Invoice not found` est l'erreur la plus fréquente sur cet endpoint. Elle survient quand vous utilisez le `token` reçu dans le payload callback au lieu du `token` retourné à la création de la transaction. Ces deux tokens sont différents. Voir [Sécurisation du callback](/api-paiement/callback/securisation).
</Warning>

***

## createWithdrawal

Endpoint : `POST /pay/v01/withdrawal/create` (payout vers wallet LigdiCash)

Wiki : `https://client.ligdicash.com/wiki/createWithdrawal`

| Sous-code         | Description                                       | Action recommandée                                                                  |
| ----------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `Echec (Code00)`  | Authentification failure                          | Vérifier `Apikey` et `Authorization: Bearer`                                        |
| `Echec (Code01)`  | Merchant Payout not activated                     | Contacter le support LigdiCash pour activer le payout                               |
| `Echec (Code02)`  | Customer not registered on the platform           | Le client (numero) n'a pas de compte LigdiCash                                      |
| `Echec (Code03)`  | No merchant account on the specified network      | Pas de compte marchand configuré pour cet opérateur                                 |
| `Echec (Code03a)` | Pending/Processed payout within the last 24 hours | Un payout vers ce client a déjà été initié dans les dernières 24 h                  |
| `Echec (Code03b)` | No deposit within the last 3 months               | Le client n'a pas effectué de dépôt dans les 3 derniers mois                        |
| `Echec (Code04)`  | Merchant balance low                              | Solde du compte marchand insuffisant — recharger le compte                          |
| `Echec (Code05)`  | Request amount out of range \[9;2 000 000]        | Corriger le montant                                                                 |
| `Echec (Code06)`  | IP denied                                         | IP non autorisée — Contacter le support technique pour whitelister votre adresse IP |
| `Echec (Code07)`  | Transaction\_id already exists                    | Ce `transaction_id` a déjà été utilisé — générer un nouvel identifiant unique       |
| `Echec (Code08)`  | An error occurred while processing                | Erreur interne — retenter                                                           |
| `Echec (Code09)`  | Data Input error                                  | Payload malformé — vérifier tous les champs                                         |
| `Echec (Code10)`  | Api error                                         | Erreur interne API — contacter le support                                           |
| `Echec (Code11)`  | No hash provided                                  | Hash absent                                                                         |
| `Echec (Code12)`  | Invalid hash                                      | Hash invalide                                                                       |
| `Echec (Code13)`  | App Marah/Agrivoucher not identified              | Application partenaire Marah/Agrivoucher non identifiée                             |

<Note>
  `Echec (Code07) — Transaction_id already exists` confirme l'importance du pattern `transaction_id` : chaque appel doit porter un identifiant unique, y compris les retries. Voir [Pattern transaction\_id](/concepts/transaction-id-pattern).
</Note>

***

## createStraightWithdrawal

Endpoint : `POST /pay/v01/straight/payout` (payout direct vers mobile money)

Wiki : `https://client.ligdicash.com/wiki/createStraightWithdrawal`

| Sous-code        | Description                                | Action recommandée                                                                  |
| ---------------- | ------------------------------------------ | ----------------------------------------------------------------------------------- |
| `Echec (Code00)` | Token Authentification error               | Vérifier le token d'autorisation Bearer                                             |
| `Echec (Code01)` | Application Authentification error         | Vérifier l'Apikey du projet                                                         |
| `Echec (Code02)` | Request amount out of range \[9;2 000 000] | Corriger le montant                                                                 |
| `Echec (Code05)` | Recipient operator not identified          | L'opérateur du destinataire n'a pas pu être identifié à partir du numéro            |
| `Echec (Code06)` | Merchant operator account not identified   | Compte marchand non trouvé pour cet opérateur                                       |
| `Echec (Code07)` | Merchant operator account not identified   | Compte marchand non trouvé pour cet opérateur                                       |
| `Echec (Code08)` | Merchant operator account low balance      | Solde du compte marchand pour cet opérateur insuffisant                             |
| `Echec (Code09)` | An error occurred while processing request | Erreur interne — retenter                                                           |
| `Echec (Code10)` | Api error                                  | Erreur interne API — contacter le support                                           |
| `Echec (Code11)` | No hash provided                           | Hash absent                                                                         |
| `Echec (Code12)` | Invalid hash                               | Hash invalide                                                                       |
| `Echec (Code13)` | Unauthorized currency conversion           | Conversion de devise non autorisée                                                  |
| `Echec (Code14)` | IP denied                                  | IP non autorisée - Contacter le support technique pour whitelister votre adresse IP |
| `Echec (Code15)` | App Marah/Agrivoucher not identified       | Application partenaire Marah/Agrivoucher non identifiée                             |

***

## Pages associées

* [Le champ wiki](/erreurs/champ-wiki) — lire les sous-codes dynamiquement depuis la réponse API
* [Erreurs courantes](/erreurs/erreurs-courantes) — causes et solutions par type d'erreur
* [Vue d'ensemble](/erreurs/vue-ensemble) — les deux niveaux d'erreur


# Gestion des erreurs — Vue d'ensemble
Source: https://developers.ligdicash.com/erreurs/vue-ensemble

Comprendre les deux niveaux d'erreur de l'API LigdiCash : rejet de la requête (response_code) et échec de la transaction (callback/confirm).

L'API LigdiCash distingue deux niveaux d'erreur qu'il est essentiel de ne pas confondre : le rejet immédiat d'une requête malformée, et l'échec d'une transaction pourtant bien initiée. Ce guide explique comment traiter chacun.

## Les deux niveaux d'erreur

### Niveau 1 — Rejet de la requête (response\_code)

Survient immédiatement à l'appel HTTP. LigdiCash a lu votre payload et le rejette.

| `response_code` | Signification                                                     |
| --------------- | ----------------------------------------------------------------- |
| `00`            | Payload valide — la transaction est initiée                       |
| `01`            | Payload invalide ou erreur d'authentification — rien n'a été créé |

Quand `response_code` vaut `01`, le champ `response_text` contient un sous-code technique de la forme `Echec (CodeXX)`. Consultez le champ `wiki` pour en obtenir la description lisible.

<Warning>
  `response_code: "00"` ne garantit pas que le paiement aboutira. C'est uniquement la confirmation que votre requête était syntaxiquement correcte et que la transaction a été mise en file d'attente. Le résultat réel du paiement est communiqué via le callback ou l'endpoint `confirm`.
</Warning>

### Niveau 2 — Échec de la transaction (callback / confirm)

Survient après `response_code: "00"`. La transaction a été initiée mais n'a pas abouti côté opérateur.

| Champ                        | Valeur en cas d'échec                    |
| ---------------------------- | ---------------------------------------- |
| `status` dans le callback    | `notcompleted`                           |
| `response_code` de `confirm` | `01` avec sous-code dans `response_text` |

Ces échecs indiquent des problèmes métier : solde insuffisant, OTP incorrect, numéro non éligible, etc.

***

## Les catégories d'erreur

| Catégorie                  | Quand              | Exemples                                                       |
| -------------------------- | ------------------ | -------------------------------------------------------------- |
| **Authentification**       | Immédiat           | Apikey invalide, token expiré                                  |
| **Payload invalide**       | Immédiat           | Champ manquant, format de numéro incorrect, montant non entier |
| **Erreur opérateur**       | Différé (callback) | Annulation                                                     |
| **Erreur métier marchand** | Immédiat           | Payout non activé sur le compte, plafond dépassé               |
| **Erreur technique**       | Immédiat           | Timeout, service indisponible                                  |

***

## Stratégie générale de traitement

<Steps>
  <Step title="Vérifier response_code immédiatement">
    Si `response_code === "01"` : loggez `response_text`, consultez l'URL dans `wiki` pour la description lisible. Ne pas lancer de retry immédiat — corriger d'abord la cause.
  </Step>

  <Step title="Stocker le token de création">
    Si `response_code === "00"` : stocker le `token` retourné dans votre base de données, associé à votre `transaction_id`. Vous en aurez besoin pour re-vérifier le callback.
  </Step>

  <Step title="Traiter le callback de façon défensive">
    Ne jamais faire confiance au payload callback seul. Toujours appeler `confirm` avec le token stocké à l'étape précédente pour valider l'issue réelle.
  </Step>
</Steps>

***

## Exemple de traitement complet

```javascript Node.js theme={null}
async function initierPaiement(payload) {
  const res = 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_AUTH_TOKEN}`,
      "Accept": "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  const data = await res.json();

  if (data.response_code === "01") {
    // Niveau 1 — rejet immédiat
    logger.error({
      event: "ligdicash_request_rejected",
      subcode: data.response_text,  // ex: "Echec (Code00)"
      wiki: data.wiki,              // URL pour la description lisible
    });
    throw new Error(`Requête rejetée : ${data.response_text}`);
  }

  // response_code === "00" : transaction initiée
  // Stocker le token pour la re-vérification callback
  await db.transactions.create({
    transaction_id: payload.custom_data[0].valueof_customdata,
    ligdicash_token: data.token,
    status: "pending",
  });

  return data;
}
```

***

## Pages associées

* [Le champ wiki](/erreurs/champ-wiki) — comment décoder `Echec (CodeXX)` en message lisible
* [Liste des sous-codes](/erreurs/sous-codes) — référence complète par endpoint
* [Erreurs courantes](/erreurs/erreurs-courantes) — causes et solutions
* [Codes de réponse et statuts](/concepts/codes-reponse-statuts) — référence complète de `response_code`
* [Sécurisation du callback](/api-paiement/callback/securisation) — re-vérification via `confirm`


# Introduction
Source: https://developers.ligdicash.com/essentials/introduction

Bienvenue dans la documentation LigdiCash. Découvrez notre solution de paiement mobile money en Afrique de l'Ouest.

**LigdiCash** est une solution de paiement sécurisée qui propose des web services et des APIs intégrables par les marchands dans leurs sites, applications mobiles et systèmes back-office. Cette documentation explique comment intégrer nos services, avec des exemples concrets, des guides pas à pas et une référence API complète.

<Note>
  L'accès à l'API LigdiCash passe par un **protocole d'intégration** avec notre équipe. Avant de commencer l'intégration technique, votre compte doit être activé par l'équipe LigdiCash. Consultez le [Protocole d'intégration](/essentials/protocole-integration) pour comprendre le parcours complet.
</Note>

## Par où commencer

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/essentials/quickstart">
    Effectuez votre premier paiement en moins de 5 minutes.
  </Card>

  <Card title="Protocole d'intégration" icon="handshake" href="/essentials/protocole-integration">
    Le parcours complet : KYC, contrat, formation, mise en production.
  </Card>

  <Card title="Pattern transaction_id" icon="shield-check" href="/concepts/transaction-id-pattern">
    La règle d'or à connaître avant toute intégration.
  </Card>

  <Card title="Cycle de vie d'une transaction" icon="arrows-rotate" href="/concepts/cycle-vie-transaction">
    Comprendre les étapes d'une transaction LigdiCash.
  </Card>
</CardGroup>

## Nos services

<CardGroup>
  <Card title="API de paiement" icon="code" href="/api-paiement/vue-ensemble">
    Recevez et envoyez de l'argent par mobile money ou carte bancaire.
  </Card>

  <Card title="Cartes bancaires" icon="credit-card" href="/api-paiement/cartes-visa/introduction">
    Acceptez les paiements par carte (Visa, MasterCard, AmEx).
  </Card>

  <Card title="Paylinks" icon="link" href="/autres-produits/paylinks">
    Générez des liens de paiement sans coder.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/autres-produits/sms">
    Envoyez des SMS transactionnels et marketing depuis votre compte.
  </Card>
</CardGroup>

## Couverture géographique

LigdiCash est disponible dans **9 pays d'Afrique de l'Ouest et Centrale** : Burkina Faso, Mali, Niger, Bénin, Togo, Côte d'Ivoire, Sénégal, RD Congo, Guinée Conakry.

Pour la liste complète des opérateurs et des moyens de paiement supportés, voir la [référence des opérateurs](/reference/operateurs-supportes).

## SDK et plugins

<CardGroup>
  <Card title="PHP" icon="php" href="/sdk/php" />

  <Card title="Python" icon="python" href="/sdk/python" />

  <Card title="JavaScript" icon="js" href="/sdk/javascript" />

  <Card title="Dart / Flutter" icon="flutter" href="/sdk/dart-flutter" />

  <Card title="WordPress / WooCommerce" icon="wordpress" href="/sdk/wordpress-woocommerce" />

  <Card title="Skill IA (Claude Code, Cursor…)" icon="sparkles" href="/sdk/skill-ia" />
</CardGroup>

## Besoin d'aide ?

<CardGroup>
  <Card title="FAQ" icon="circle-question" href="/ressources/faq">
    Réponses aux questions fréquentes.
  </Card>

  <Card title="Support" icon="life-ring" href="/ressources/support">
    Contactez l'équipe support LigdiCash.
  </Card>
</CardGroup>


# Protocole d'intégration
Source: https://developers.ligdicash.com/essentials/protocole-integration

Le parcours complet pour devenir partenaire LigdiCash : démarches administratives, formation, intégration technique et mise en production.

Devenir partenaire LigdiCash suit un processus structuré en deux grandes phases : une phase administrative (contrat, KYC) pilotée par votre Partner Manager, puis une phase technique (formation, intégration, tests) encadrée par l'équipe technique LigdiCash.

## Vue d'ensemble

<Steps>
  <Step title="Contact avec le Partner Manager">
    Prenez contact avec l'équipe commerciale LigdiCash. Un **Partner Manager** vous sera assigné — c'est votre interlocuteur pour toute la phase administrative.

    Consultez les [contacts par pays](/ressources/support#contacts-par-pays) pour joindre le Partner Manager de votre région.
  </Step>

  <Step title="KYC — Remplir le KYC et fournir les documents">
    Le Partner Manager vous communiquera la liste complète des documents requis. Vous devrez notamment remplir le **KYC (dossier de connaissance client)** — c'est le KYC LigdiCash. Il comprend entre autres :

    * Le RCCM (Registre du Commerce et du Crédit Mobilier)
    * Le numéro IFU (Identifiant Financier Unique)
    * La fiche descriptive de votre entreprise
    * Tout autre document demandé par le Partner Manager selon votre activité

    <Note>
      La liste exacte des pièces à fournir vous sera communiquée par votre Partner Manager. Elle peut varier selon votre pays et la nature de votre activité.
    </Note>
  </Step>

  <Step title="Négociation des commissions et signature du contrat">
    Votre Partner Manager discute avec vous des conditions tarifaires (commissions par opérateur, par type de transaction). Une fois les conditions validées, vous signez le contrat de partenariat LigdiCash.

    Si vous souhaitez activer les **paiements par carte Visa**, un contrat additionnel spécifique est requis à cette étape. Voir [Activer Visa](/api-paiement/cartes-visa/activation).
  </Step>

  <Step title="Mise en contact avec l'équipe technique">
    Après la signature du contrat, votre Partner Manager vous met en contact avec l'**équipe technique LigdiCash**, qui prend en charge la suite du processus.
  </Step>

  <Step title="Formation dashboard et API">
    L'équipe technique planifie avec vous une **session de formation** couvrant :

    * La prise en main du dashboard LigdiCash
    * Les principes de l'API (endpoints, authentification, flux de paiement, callback)

    Cette formation pose les bases nécessaires avant de commencer l'intégration.
  </Step>

  <Step title="Création du groupe d'intégration Microsoft Teams">
    L'équipe technique crée un **groupe de travail Microsoft Teams** dédié à votre intégration. Ce groupe est votre canal de communication direct avec LigdiCash tout au long de l'intégration et au-delà.

    Dans ce groupe, l'équipe technique vous remet votre **compte d'intégration temporaire** — un compte LigdiCash réel configuré avec les opérateurs de votre contrat, utilisé exclusivement pour vos travaux d'intégration. Voir [Environnements](/concepts/environnements).
  </Step>

  <Step title="Intégration technique">
    Vous réalisez l'intégration avec le compte temporaire fourni. Vous pouvez contacter l'équipe technique à tout moment via le groupe Teams en cas de question ou de blocage.

    Points clés à implémenter et tester :

    * Création de factures et flux de redirection (ou sans redirection selon les opérateurs signés)
    * Réception et traitement du callback
    * Re-vérification du statut avec l'endpoint `confirm`

    <Warning>
      Le callback est l'élément le plus important de l'intégration. Assurez-vous que votre endpoint de callback est accessible depuis internet, qu'il déduplique les requêtes et qu'il appelle `confirm` avant d'honorer une commande. C'est ce point qui sera vérifié en priorité lors des tests de fin d'intégration.
    </Warning>
  </Step>

  <Step title="Tests de fin d'intégration">
    Quand vous estimez votre intégration terminée, signalez-le à l'équipe technique via le groupe Teams. L'équipe planifie alors des **tests de fin d'intégration** pour valider votre implémentation.

    Le point central des tests est le **callback** : l'équipe technique vérifie que votre endpoint reçoit correctement les notifications, les traite de manière idempotente et re-vérifie le statut avec `confirm`.

    Si des ajustements sont nécessaires, l'équipe technique vous accompagne jusqu'à la validation complète.
  </Step>

  <Step title="Signature du PV de fin d'intégration">
    Une fois tous les tests validés, l'équipe technique vous adresse un **PV (procès-verbal) de fin d'intégration**, document numérique à signer en ligne. Ce document atteste que votre intégration est conforme et approuvée.
  </Step>

  <Step title="Passage en production">
    Après la signature du PV, le processus de mise en production se déroule ainsi :

    1. **Vous créez votre propre compte LigdiCash** via l'application mobile LigdiCash ([App Store / Play Store](https://www.ligdicash.com/download)).
    2. **L'équipe technique active votre projet API en production** sur ce compte, avec les opérateurs et les droits prévus par votre contrat.
    3. Vous remplacez les clés du compte d'intégration temporaire par les clés de votre compte de production dans votre configuration.

    <Tip>
      Si vous avez stocké vos clés dans des variables d'environnement dès le début de l'intégration, la bascule en production se limite à changer les valeurs de ces variables. Aucune modification de code n'est nécessaire.
    </Tip>
  </Step>
</Steps>

## Après la mise en production

Le groupe Microsoft Teams reste actif. Il constitue votre canal privilégié pour :

* Contacter l'**équipe support technique** en cas de problème
* Déposer des **réclamations**
* Demander l'activation de nouveaux opérateurs ou fonctionnalités

## Récapitulatif des phases

| Phase           | Pilote                     | Ce que vous faites        |
| --------------- | -------------------------- | ------------------------- |
| Administrative  | Partner Manager            | KYC, contrat, commissions |
| Formation       | Équipe technique           | Dashboard, API            |
| Intégration     | Équipe technique + vous    | Code, tests callback      |
| Validation      | Équipe technique           | Tests finaux, PV          |
| Production      | Équipe technique           | Activer votre projet      |
| Support continu | Équipe technique & support | Groupe Teams              |

## Pages associées

* [Environnements](/concepts/environnements) — compte d'intégration temporaire vs production
* [Authentification](/concepts/authentification) — utiliser vos clés API
* [Sécurisation du callback](/api-paiement/callback/securisation) — ce qui est validé lors des tests finaux


# Quickstart — Premier paiement en 5 minutes
Source: https://developers.ligdicash.com/essentials/quickstart

Réalisez votre premier payin avec redirection de bout en bout : créer la facture, rediriger le client, recevoir le callback et vérifier le paiement.

Ce guide vous fait parcourir le flux complet d'un payin avec redirection : vous créez une facture, vous redirigez votre client vers la page de paiement LigdiCash, vous recevez le callback, et vous vérifiez le statut avec l'endpoint `confirm`.

## Prérequis

* Votre `Apikey` et votre `API_TOKEN` disponibles dans votre dashboard LigdiCash
* Une `callback_url` accessible publiquement depuis internet (pas `localhost`)

<Note>
  Pour exposer un serveur local lors du développement, vous pouvez utiliser un outil comme [ngrok](https://ngrok.com).
</Note>

## Étape 1 — Créer la transaction

Appelez l'endpoint de création en passant votre `transaction_id` dans `custom_data`. Stockez le `token` retourné — vous en aurez besoin à l'étape 4.

<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", "price": 5000, "quantity": 1 }
          ],
          "total_amount": 5000,
          "devise": "XOF",
          "description": "Abonnement Pro — Janvier 2025",
          "customer": "",
          "customer_firstname": "Amadou",
          "customer_lastname": "Diallo",
          "customer_email": "amadou@exemple.com"
        },
        "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 transactionId = "ORD-2025-00042";

  // Stockez transactionId en base avec statut "pending" avant cet appel
  await db.orders.update({ id: orderId, ligdicash_tx_id: transactionId, status: "pending" });

  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", price: 5000, quantity: 1 }],
            total_amount: 5000,
            devise: "XOF",
            description: "Abonnement Pro — Janvier 2025",
            customer: "",
            customer_firstname: "Amadou",
            customer_lastname: "Diallo",
            customer_email: "amadou@exemple.com",
          },
          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: transactionId },
        },
      }),
    }
  );

  const data = await response.json();

  if (data.response_code !== "00") {
    throw new Error(`LigdiCash error: ${data.response_text}`);
  }

  // Stockez le token pour la re-vérification à l'étape 4
  await db.orders.update({ ligdicash_tx_id: transactionId, ligdicash_token: data.token });

  const paymentUrl = data.response_text;
  ```

  ```php PHP theme={null}
  $transactionId = "ORD-2025-00042";

  $payload = [
    "commande" => [
      "invoice" => [
        "items" => [["name" => "Abonnement Pro", "price" => 5000, "quantity" => 1]],
        "total_amount" => 5000,
        "devise" => "XOF",
        "description" => "Abonnement Pro — Janvier 2025",
        "customer" => "",
        "customer_firstname" => "Amadou",
        "customer_lastname" => "Diallo",
        "customer_email" => "amadou@exemple.com",
      ],
      "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" => $transactionId],
    ],
  ];

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

  if ($data["response_code"] !== "00") {
    throw new Exception("LigdiCash error: " . $data["response_text"]);
  }

  $paymentUrl = $data["response_text"];
  ```
</CodeGroup>

La réponse en cas de succès contient dans `response_text` l'URL de la page de paiement :

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

## Étape 2 — Rediriger le client

L'URL de paiement est dans `response_text`. Ouvrez-la dans le même onglet ou un nouvel onglet — **jamais dans une iframe**.

```javascript Node.js theme={null}
// Même onglet
window.location.href = paymentUrl;

// Nouvel onglet
window.open(paymentUrl, "_blank");
```

<Warning>
  L'iframe est bloqué par LigdiCash. Le lien de paiement doit obligatoirement s'ouvrir dans le même onglet, un nouvel onglet, un popup, ou une WebView native sur mobile.
</Warning>

Une fois le paiement effectué ou annulé, LigdiCash redirige le client vers votre `return_url` ou `cancel_url`.

## Étape 3 — Recevoir le callback

LigdiCash envoie une requête POST à votre `callback_url` quand le statut de la transaction change.

```javascript Node.js (Express) theme={null}
app.post("/api/callback/ligdicash", async (req, res) => {
  // Idéalement, toujours répondre 200 en premier
  res.status(200).json({ ok: true });

  const payload = req.body;

  // Extraire votre transaction_id depuis custom_data
  const entry = payload.custom_data?.find(
    (item) => item.keyof_customdata === "transaction_id"
  );
  const transactionId = entry?.valueof_customdata;

  if (!transactionId) return;

  // Récupérer le token stocké à la création (étape 1)
  const order = await db.orders.findOne({ ligdicash_tx_id: transactionId });
  if (!order) return;

  // Re-vérifier le statut avec confirm (étape 4)
  await verifyAndUpdateOrder(order);
});
```

<Tip>
  Par convention, répondez `200` à LigdiCash pour accuser réception du callback.
</Tip>

## Étape 4 — Vérifier avec confirm

N'accordez jamais confiance au seul payload du callback. Appelez `confirm` avec le `token` stocké à la création pour valider le statut.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken={TOKEN}" \
    -H "Apikey: {API_KEY}" \
    -H "Authorization: Bearer {API_TOKEN}" \
    -H "Accept: application/json"
  ```

  ```javascript Node.js theme={null}
  async function verifyAndUpdateOrder(order) {
    const response = await fetch(
      `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=${order.ligdicash_token}`,
      {
        headers: {
          Apikey: process.env.LIGDICASH_API_KEY,
          Authorization: `Bearer ${process.env.LIGDICASH_API_TOKEN}`,
          Accept: "application/json",
        },
      }
    );

    const data = await response.json();

    if (data.status === "completed") {
      await db.orders.update({ id: order.id, status: "paid" });
    } else if (data.status === "notcompleted") {
      await db.orders.update({ id: order.id, status: "failed" });
    }
    // Si "pending" : ne rien faire, attendre le prochain callback
  }
  ```
</CodeGroup>

## Et après ?

Votre premier paiement fonctionne. Pour aller plus loin :

<CardGroup>
  <Card title="Payin sans redirection" icon="mobile" href="/api-paiement/payin-sans-redirect/introduction">
    Initiez le paiement directement depuis votre interface, sans quitter votre app
  </Card>

  <Card title="Sécuriser le callback" icon="shield" href="/api-paiement/callback/securisation">
    Le pattern complet de re-vérification et de déduplication
  </Card>

  <Card title="Payout" icon="arrow-right" href="/api-paiement/payout/introduction">
    Effectuez des virements vers vos clients ou partenaires
  </Card>

  <Card title="Tous les opérateurs" icon="globe" href="/reference/operateurs-supportes">
    Orange Money, Moov, MTN, Wave et plus encore
  </Card>
</CardGroup>


# Architecture recommandée
Source: https://developers.ligdicash.com/guides/architecture-recommandee

Comment structurer votre backend pour intégrer LigdiCash en toute sécurité : proxy, base de données, gestion du callback et fallback polling.

Cette page décrit les principes d'architecture à respecter pour une intégration LigdiCash robuste et sécurisée. Elle s'adresse aux développeurs qui conçoivent l'infrastructure autour de l'API.

## Principe fondamental : tout passe par le backend

Vos identifiants LigdiCash (Apikey et Auth Token) ne doivent **jamais** apparaître dans votre frontend, votre application mobile ou votre code source public. Toutes les requêtes vers l'API LigdiCash partent de votre serveur.

```
Client / App mobile
       |
       ↓
Votre backend (proxy)   ←→   API LigdiCash
       |
       ↓
Votre base de données
```

<Warning>
  Un Apikey ou Auth Token exposé côté client permet à n'importe qui de créer des factures ou déclencher des payouts en votre nom. Stockez ces secrets dans des variables d'environnement serveur uniquement.
</Warning>

## Structure de la table des transactions

Votre base de données doit conserver assez d'informations pour tracer chaque transaction, traiter le callback de manière idempotente et effectuer un polling de fallback.

```sql theme={null}
CREATE TABLE transactions_paiement (
    id              VARCHAR(64) PRIMARY KEY,   -- votre transaction_id interne
    commande_id     VARCHAR(64) NOT NULL,
    montant         INTEGER NOT NULL,           -- en XOF, entier
    statut          VARCHAR(20) NOT NULL DEFAULT 'pending',
                                               -- pending | completed | notcompleted
    ligdicash_token TEXT,                       -- token retourné à la création
    ligdicash_ref   VARCHAR(64),               -- operator_id retourné dans le callback
    callback_recu_at TIMESTAMPTZ,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX ON transactions_paiement (commande_id);
CREATE INDEX ON transactions_paiement (statut, created_at);
```

<Note>
  Le champ `ligdicash_token` doit être stocké dès la création de la facture. C'est lui que vous utiliserez pour appeler l'endpoint `confirm`, aussi bien dans le callback que dans le polling de fallback. Ne comptez pas sur le `token` reçu dans le callback — c'est un token différent.
</Note>

## Endpoints à exposer côté backend

Votre backend joue le rôle de proxy entre votre frontend et l'API LigdiCash. Exposez au minimum ces trois routes :

| Route                      | Méthode | Rôle                                                                              |
| -------------------------- | ------- | --------------------------------------------------------------------------------- |
| `/api/paiement/initier`    | POST    | Crée la facture LigdiCash, stocke le token, retourne l'URL de paiement            |
| `/api/paiement/:id/statut` | GET     | Retourne le statut de la transaction (avec polling LigdiCash si encore `pending`) |
| `/api/ligdicash/callback`  | POST    | Reçoit les notifications LigdiCash, re-vérifie, met à jour la base                |

### Route d'initiation

```javascript Node.js (Express) theme={null}
app.post("/api/paiement/initier", async (req, res) => {
  const { commandeId, montant, description, clientEmail } = req.body;

  // Générer un transaction_id unique
  const transactionId = `txn_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;

  // Créer la transaction en base
  await db.transactionsPaiement.insert({
    id: transactionId,
    commande_id: commandeId,
    montant,
    statut: "pending",
  });

  // Appeler LigdiCash
  const ligdicash = 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_AUTH_TOKEN}`,
        Accept: "application/json",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        commande: {
          invoice: {
            items: [],
            total_amount: montant,
            devise: "XOF",
            description,
            customer: "",
            customer_email: clientEmail ?? "",
            external_id: "",
            otp: "",
          },
          store: {
            name: process.env.STORE_NAME,
            website_url: process.env.STORE_URL,
          },
          actions: {
            cancel_url: `${process.env.FRONTEND_URL}/paiement/annule?txn=${transactionId}`,
            return_url: `${process.env.FRONTEND_URL}/paiement/succes?txn=${transactionId}`,
            callback_url: `${process.env.BACKEND_URL}/api/ligdicash/callback`,
          },
          custom_data: { transaction_id: transactionId },
        },
      }),
    }
  ).then((r) => r.json());

  if (ligdicash.response_code !== "00") {
    await db.transactionsPaiement.update(transactionId, { statut: "notcompleted" });
    return res.status(502).json({ error: "ligdicash_error", detail: ligdicash.description });
  }

  // Stocker le token
  await db.transactionsPaiement.update(transactionId, {
    ligdicash_token: ligdicash.token,
  });

  res.json({
    transaction_id: transactionId,
    pay_url: ligdicash.response_text,
  });
});
```

### Route de callback

```javascript Node.js (Express) theme={null}
app.post("/api/ligdicash/callback", express.json(), async (req, res) => {
  // Répondre 200 immédiatement
  res.sendStatus(200);

  // Extraire le transaction_id
  const customData = req.body.custom_data ?? [];
  const entry = Array.isArray(customData)
    ? customData.find((e) => e.keyof_customdata === "transaction_id")
    : null;

  if (!entry?.valueof_customdata) return;

  const transactionId = entry.valueof_customdata;
  const txn = await db.transactionsPaiement.findById(transactionId);

  // Idempotence : ignorer si déjà traité
  if (!txn || txn.statut !== "pending") return;

  // Re-vérifier via confirm
  const confirm = await fetch(
    `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=${txn.ligdicash_token}`,
    {
      headers: {
        Apikey: process.env.LIGDICASH_API_KEY,
        Authorization: `Bearer ${process.env.LIGDICASH_AUTH_TOKEN}`,
        Accept: "application/json",
      },
    }
  ).then((r) => r.json());

  await db.transactionsPaiement.update(transactionId, {
    statut: confirm.status ?? "pending",
    callback_recu_at: new Date(),
  });

  if (confirm.status === "completed") {
    await commandes.confirmer(txn.commande_id);
  }
});
```

## Fallback polling

LigdiCash n'impose pas de politique de retry sur les callbacks. Si votre endpoint était indisponible ou si un callback a été manqué, une transaction peut rester `pending` indéfiniment. Mettez en place un polling périodique côté backend.

```javascript Fallback polling (cron) theme={null}
// Exécuté toutes les 5 minutes par un cron job
async function pollTransactionsPending() {
  // Transactions pending depuis plus de 2 minutes et moins de 24h
  const txns = await db.transactionsPaiement.findAll({
    statut: "pending",
    created_at: { gte: new Date(Date.now() - 24 * 3600 * 1000) },
    callback_recu_at: null,
  });

  for (const txn of txns) {
    if (!txn.ligdicash_token) continue;

    const confirm = await fetch(
      `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=${txn.ligdicash_token}`,
      {
        headers: {
          Apikey: process.env.LIGDICASH_API_KEY,
          Authorization: `Bearer ${process.env.LIGDICASH_AUTH_TOKEN}`,
          Accept: "application/json",
        },
      }
    ).then((r) => r.json());

    if (confirm.status && confirm.status !== "pending") {
      await db.transactionsPaiement.update(txn.id, { statut: confirm.status });

      if (confirm.status === "completed") {
        await commandes.confirmer(txn.commande_id);
      }
    }
  }
}
```

<Note>
  LigdiCash ne passe jamais automatiquement une transaction en `notcompleted`. Une transaction reste `pending` indéfiniment si le client n'a pas finalisé le paiement. Après 24h, vous pouvez considérer la transaction expirée et la clôturer vous-même.
</Note>

## Logging et audit

Conservez une trace de chaque interaction avec LigdiCash pour faciliter le diagnostic en cas de litige.

```sql theme={null}
CREATE TABLE logs_paiement (
    id              BIGSERIAL PRIMARY KEY,
    transaction_id  VARCHAR(64),
    direction       VARCHAR(10) NOT NULL,  -- 'outgoing' | 'incoming'
    type            VARCHAR(30) NOT NULL,  -- 'create' | 'confirm' | 'callback' | 'poll'
    payload         JSONB,
    response        JSONB,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

<Tip>
  Loggez aussi bien les requêtes sortantes vers LigdiCash que les callbacks entrants. En cas de litige sur une transaction, vous pourrez présenter un historique complet avec horodatage.
</Tip>

## Variables d'environnement

```bash .env theme={null}
# Clés LigdiCash — NE JAMAIS les exposer côté client
LIGDICASH_API_KEY=votre_apikey
LIGDICASH_AUTH_TOKEN=votre_auth_token

# URLs
STORE_NAME=Ma Boutique
STORE_URL=https://maboutique.com
FRONTEND_URL=https://maboutique.com
BACKEND_URL=https://api.maboutique.com
```

## Schéma récapitulatif

```mermaid theme={null}
flowchart LR
    CLIENT["Client"]
    FE["Frontend / App mobile"]
    PROXY["Votre backend"]
    DB[("Base de données")]
    CRON["Cron polling"]
    LC["API LigdiCash"]
    PAY["Page de paiement\nLigdiCash"]

    CLIENT -->|"1. initie"| FE
    FE -->|"2. POST /initier"| PROXY
    PROXY -->|"3. INSERT pending"| DB
    PROXY -->|"4. POST /create"| LC
    LC -->|"5. token + pay_url"| PROXY
    PROXY -->|"6. stocke token"| DB
    PROXY -->|"7. pay_url"| FE
    FE -->|"8. redirige"| PAY
    CLIENT -->|"9. paie"| PAY
    PAY -->|"10. POST /callback"| PROXY
    PROXY -->|"11. GET /confirm"| LC
    LC -->|"12. status"| PROXY
    PROXY -->|"13. UPDATE statut"| DB
    CRON -.->|"poll pending"| DB
    CRON -.->|"GET /confirm"| LC
```

## Pages associées

* [Sécurisation du callback](/api-paiement/callback/securisation) — pourquoi re-vérifier toujours
* [Idempotence du callback](/api-paiement/callback/idempotence) — gérer le double envoi LigdiCash
* [Pattern transaction\_id](/concepts/transaction-id-pattern) — identifier les transactions de manière fiable
* [Checklist de mise en production](/guides/checklist-production) — vérifications avant le go-live


# Checklist de mise en production
Source: https://developers.ligdicash.com/guides/checklist-production

Vérifications techniques, sécurité et business à effectuer avant de basculer votre intégration LigdiCash en production.

Cette checklist couvre les points critiques à valider avant d'ouvrir votre intégration aux clients finaux. Parcourez-la dans l'ordre — chaque section s'appuie sur la précédente.

## Sécurité

<AccordionGroup>
  <Accordion title="Les clés API ne sont pas exposées côté client">
    L'Apikey et l'Auth Token ne doivent apparaître ni dans le code JavaScript du navigateur, ni dans une app mobile, ni dans un dépôt Git public.

    * [ ] Variables d'environnement serveur uniquement (`process.env`, `.env` non commité)
    * [ ] `.gitignore` inclut le fichier `.env`
    * [ ] Pas de clé dans les logs applicatifs
    * [ ] Pas de clé dans les réponses d'API retournées au frontend
  </Accordion>

  <Accordion title="Le callback re-vérifie le statut via l'endpoint confirm">
    Ne jamais faire confiance au payload reçu dans le callback — il peut être forgé. Appelez toujours `/confirm` avec le token stocké à la création.

    * [ ] Le handler de callback appelle `/checkout-invoice/confirm` avant toute action métier
    * [ ] Le token utilisé pour `confirm` est celui stocké à la création (pas le `token` du callback)
    * [ ] Un payload malformé ou avec un `transaction_id` inconnu est ignoré silencieusement
    * [ ] Voir [Sécurisation du callback](/api-paiement/callback/securisation)
  </Accordion>

  <Accordion title="La callback_url est accessible publiquement">
    LigdiCash doit pouvoir atteindre votre endpoint de callback depuis Internet.

    * [ ] URL accessible depuis une IP externe (pas `localhost` ou IP privée)
    * [ ] HTTPS recommandé (HTTP accepté par LigdiCash, mais déconseillé en production)
    * [ ] Pas de règle firewall bloquant les IPs LigdiCash
    * [ ] Si whitelisting requis : contactez le support LigdiCash pour obtenir les IPs à autoriser (max 3 IPs par projet)
  </Accordion>

  <Accordion title="Les identifiants de transaction sont non-devinables">
    Un `transaction_id` séquentiel (`1`, `2`, `3`...) permet à un attaquant d'énumérer vos transactions.

    * [ ] Utilisez un UUID v4 ou un ID préfixé avec suffixe aléatoire (`txn_` + timestamp + aléatoire)
    * [ ] Voir [Pattern transaction\_id](/concepts/transaction-id-pattern)
  </Accordion>
</AccordionGroup>

## Technique

<AccordionGroup>
  <Accordion title="Flux payin avec redirection">
    * [ ] `customer` est vide (`""`) dans tous les exemples de payin redirect
    * [ ] `cancel_url` pointe vers la page d'annulation, `return_url` vers la page de succès (pas inversé)
    * [ ] L'URL de paiement s'ouvre dans le même onglet, un nouvel onglet ou un popup — jamais dans une iframe
    * [ ] Le frontend vérifie le statut réel via le backend après retour sur `return_url` (la redirection n'est pas une preuve de paiement)
  </Accordion>

  <Accordion title="Flux payin sans redirection (le cas échéant)">
    * [ ] `external_id` et `otp` sont vides (`""`) dans les requêtes où ils ne sont pas utilisés
    * [ ] Le mode d'authentification (OTP USSD / SMS / Approbation) est correctement documenté dans l'UX pour chaque opérateur
    * [ ] Pour le mode OTP SMS : la requête initiale est soumise avec `otp: ""`, puis re-soumise avec l'OTP reçu
    * [ ] Pour le mode Approbation (Moov) : le callback est la seule confirmation — pas de polling insuffisant
  </Accordion>

  <Accordion title="Gestion du callback">
    * [ ] Le handler est idempotent (deux appels avec le même `transaction_id` n'exécutent la logique qu'une fois)
    * [ ] Les deux formats de callback sont gérés (`application/json` et `application/x-www-form-urlencoded`)
    * [ ] Voir [Idempotence du callback](/api-paiement/callback/idempotence) et [Parser custom\_data](/api-paiement/callback/parser-custom-data)
  </Accordion>

  <Accordion title="Base de données et traçabilité">
    * [ ] La transaction est créée en base **avant** l'appel à LigdiCash
    * [ ] Le `token` LigdiCash est stocké dès la création de la facture
    * [ ] Les logs d'entrée et de sortie (requêtes LigdiCash + callbacks reçus) sont conservés
    * [ ] Voir [Architecture recommandée](/guides/architecture-recommandee)
  </Accordion>

  <Accordion title="Fallback polling">
    * [ ] Un job périodique vérifie les transactions restées `pending` depuis plus de quelques minutes
    * [ ] Le polling s'arrête après un délai raisonnable (ex : 24h) — les transactions ne passent jamais automatiquement en `notcompleted`
    * [ ] Le polling utilise le `token` stocké à la création, pas un token issu du callback
  </Accordion>
</AccordionGroup>

## Payout (si applicable)

<AccordionGroup>
  <Accordion title="Flux payout vers wallet LigdiCash">
    * [ ] Le client destinataire possède un compte LigdiCash (requis pour `/withdrawal/create`)
    * [ ] La sémantique de `top_up_wallet` est correctement implémentée : `1` = fonds dans le wallet, `0` = virement automatique vers le mobile money lié
  </Accordion>

  <Accordion title="Flux payout vers mobile money direct">
    * [ ] Le numéro de téléphone est au format `22670XXXXXXX` (sans `+`, sans espaces)
    * [ ] L'endpoint `/straight/payout` est utilisé (pas `/withdrawal/create`) pour les destinataires sans compte LigdiCash
  </Accordion>
</AccordionGroup>

## Business et opérationnel

<AccordionGroup>
  <Accordion title="Compte marchand et projet API">
    * [ ] Le compte marchand LigdiCash est actif et vérifié (KYC complété)
    * [ ] Le projet API est en mode production (pas de compte de test)
    * [ ] Les opérateurs souhaités sont activés sur le projet API (vérifiez dans le dashboard)
    * [ ] Visa activé séparément si vous en avez besoin (contrat spécifique)
  </Accordion>

  <Accordion title="Gestion des erreurs côté UX">
    * [ ] Chaque code d'erreur LigdiCash est mappé à un message lisible par l'utilisateur
    * [ ] L'utilisateur est informé clairement si son paiement échoue, avec une invitation à réessayer
    * [ ] Voir [Erreurs courantes](/erreurs/erreurs-courantes)
  </Accordion>

  <Accordion title="Communication avec LigdiCash">
    * [ ] Votre `callback_url` a été testée en conditions réelles
    * [ ] Vous avez un groupe d'intégration Microsoft Teams LigdiCash pour les urgences en production
    * [ ] Si whitelisting IP requis : les IPs de votre serveur ont été transmises au support technique LigdiCash
  </Accordion>
</AccordionGroup>

## Tests pré-production

Avant le go-live, effectuez au moins un test de bout en bout pour chaque flux que vous intégrez.

| Scénario                                    | À tester                                                                 |
| ------------------------------------------- | ------------------------------------------------------------------------ |
| Paiement réussi                             | Le statut passe à `completed`, la commande est confirmée                 |
| Paiement annulé par l'utilisateur           | La `cancel_url` est atteinte, la commande reste `pending` puis expire    |
| Callback reçu deux fois                     | La logique métier n'est exécutée qu'une fois                             |
| Transaction toujours `pending` après 10 min | Le polling de fallback la met à jour correctement                        |
| Clé API invalide                            | L'erreur est capturée et loggée, l'utilisateur voit un message générique |

<Warning>
  LigdiCash n'a pas d'environnement sandbox distinct. Les tests sont effectués avec un compte de test réel fourni par l'équipe LigdiCash pendant la période d'intégration. Contactez [developper@ligdicash.com](mailto:developper@ligdicash.com) pour obtenir un accès de test.
</Warning>

## Pages associées

* [Architecture recommandée](/guides/architecture-recommandee) — structure backend
* [Sécurisation du callback](/api-paiement/callback/securisation) — pattern de re-vérification
* [Pattern transaction\_id](/concepts/transaction-id-pattern) — identifier les transactions
* [Gestion des erreurs](/erreurs/vue-ensemble) — codes et stratégies


# Guide e-commerce : panier → paiement → livraison
Source: https://developers.ligdicash.com/guides/quickstart-ecommerce

Implémentez un flux de paiement complet avec LigdiCash : création de commande, paiement mobile money, réception du callback et confirmation de livraison.

Ce guide décrit le flux de bout en bout pour un site e-commerce : depuis la validation du panier côté client jusqu'à la confirmation de livraison côté serveur. Il utilise le payin avec redirection, qui est le mode d'intégration le plus simple et le plus compatible avec tous les opérateurs.

**Pré-requis :** vous avez un projet API LigdiCash avec une Apikey et un Auth Token. Voir [Créer un projet API](/concepts/projet-api).

## Vue d'ensemble du flux

```
Client           Frontend          Backend          LigdiCash
  |                 |                  |                 |
  |-- Valider --->  |                  |                 |
  |   le panier     |-- POST /pay --> |                  |
  |                 |                  |-- create -----> |
  |                 |                  | <-- token ----- |
  |                 | <-- pay_url ---- |                 |
  |-- Redirect -->  |                  |                 |
  |                 |--- Ouvre URL --> |                 |
  |  [Paiement sur la page LigdiCash]  |                 |
  |                 |                  | <-- callback -- |
  |                 |                  |-- confirm ----> |
  |                 |                  | <-- statut ---- |
  |                 |                  |-- Confirme      |
  |                 |                  |   commande      |
  | <-- Retour ---- |                  |                 |
  |   return_url    |-- GET /statut -> |                 |
  |                 | <-- résultat --- |                 |
```

<Warning>
  Ne jamais appeler l'API LigdiCash directement depuis le frontend. Votre Apikey et votre Auth Token doivent rester sur votre backend. Voir [Architecture recommandée](/guides/architecture-recommandee).
</Warning>

## Étape 1 — Stocker la commande avant le paiement

Avant de créer la facture LigdiCash, persistez la commande en base de données avec le statut `pending`. Vous aurez besoin de son identifiant pour tracer le paiement.

```sql theme={null}
INSERT INTO commandes (id, client_id, montant, statut, created_at)
VALUES ('cmd_7f3a9b', 42, 15000, 'pending', NOW());
```

<Tip>
  Utilisez un identifiant interne non-devinable (UUID ou ID préfixé) comme `transaction_id`. Vous le passerez dans `custom_data` et l'utiliserez pour identifier la commande dans le callback.
</Tip>

## Étape 2 — Créer la facture côté backend

Votre backend appelle l'endpoint de création de facture et stocke le `token` retourné.

<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 {AUTH_TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "commande": {
        "invoice": {
          "items": [
            {
              "name": "Abonnement Premium",
              "description": "1 mois d'\''accès Premium",
              "quantity": 1,
              "unit_price": 15000,
              "total_price": 15000
            }
          ],
          "total_amount": 15000,
          "devise": "XOF",
          "description": "Commande #cmd_7f3a9b",
          "customer": "",
          "customer_firstname": "Aminata",
          "customer_lastname": "Ouédraogo",
          "customer_email": "aminata@exemple.com",
          "external_id": "",
          "otp": ""
        },
        "store": {
          "name": "Ma Boutique",
          "website_url": "https://maboutique.com"
        },
        "actions": {
          "cancel_url": "https://maboutique.com/paiement/annule",
          "return_url": "https://maboutique.com/paiement/succes",
          "callback_url": "https://maboutique.com/api/ligdicash/callback"
        },
        "custom_data": {
          "transaction_id": "cmd_7f3a9b"
        }
      }
    }'
  ```

  ```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_AUTH_TOKEN}`,
        Accept: "application/json",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        commande: {
          invoice: {
            items: [
              {
                name: "Abonnement Premium",
                description: "1 mois d'accès Premium",
                quantity: 1,
                unit_price: 15000,
                total_price: 15000,
              },
            ],
            total_amount: 15000,
            devise: "XOF",
            description: "Commande #cmd_7f3a9b",
            customer: "",
            customer_firstname: "Aminata",
            customer_lastname: "Ouédraogo",
            customer_email: "aminata@exemple.com",
            external_id: "",
            otp: "",
          },
          store: {
            name: "Ma Boutique",
            website_url: "https://maboutique.com",
          },
          actions: {
            cancel_url: "https://maboutique.com/paiement/annule",
            return_url: "https://maboutique.com/paiement/succes",
            callback_url: "https://maboutique.com/api/ligdicash/callback",
          },
          custom_data: {
            transaction_id: "cmd_7f3a9b",
          },
        },
      }),
    }
  );

  const data = await response.json();
  // data.response_code === "00" → succès
  // data.response_text → URL de paiement
  ```

  ```php PHP theme={null}
  $client = new \GuzzleHttp\Client();

  $response = $client->post(
      'https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/create',
      [
          'headers' => [
              'Apikey'        => $_ENV['LIGDICASH_API_KEY'],
              'Authorization' => 'Bearer ' . $_ENV['LIGDICASH_AUTH_TOKEN'],
              'Accept'        => 'application/json',
              'Content-Type'  => 'application/json',
          ],
          'json' => [
              'commande' => [
                  'invoice' => [
                      'items' => [
                          [
                              'name'        => 'Abonnement Premium',
                              'description' => '1 mois d\'accès Premium',
                              'quantity'    => 1,
                              'unit_price'  => 15000,
                              'total_price' => 15000,
                          ],
                      ],
                      'total_amount'      => 15000,
                      'devise'            => 'XOF',
                      'description'       => 'Commande #cmd_7f3a9b',
                      'customer'          => '',
                      'customer_firstname'=> 'Aminata',
                      'customer_lastname' => 'Ouédraogo',
                      'customer_email'    => 'aminata@exemple.com',
                      'external_id'       => '',
                      'otp'               => '',
                  ],
                  'store' => [
                      'name'        => 'Ma Boutique',
                      'website_url' => 'https://maboutique.com',
                  ],
                  'actions' => [
                      'cancel_url'   => 'https://maboutique.com/paiement/annule',
                      'return_url'   => 'https://maboutique.com/paiement/succes',
                      'callback_url' => 'https://maboutique.com/api/ligdicash/callback',
                  ],
                  'custom_data' => [
                      'transaction_id' => 'cmd_7f3a9b',
                  ],
              ],
          ],
      ]
  );

  $data = json_decode($response->getBody(), true);
  // $data['response_code'] === '00' → succès
  // $data['response_text'] → URL de paiement
  ```
</CodeGroup>

Réponse en cas de succès (`response_code: "00"`) :

```json theme={null}
{
  "response_code": "00",
  "response_text": "https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm?token=eyJ0...",
  "description": "Checkout-Invoice created with success.",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
```

**Stockez le `token` en base de données** en l'associant à votre commande. Vous en aurez besoin pour vérifier le paiement.

```sql theme={null}
UPDATE commandes
SET ligdicash_token = 'eyJ0eXAiOiJKV1Qi...'
WHERE id = 'cmd_7f3a9b';
```

## Étape 3 — Rediriger le client vers la page de paiement

Retournez `response_text` (l'URL de paiement) à votre frontend, puis redirigez le client.

```javascript Frontend (JavaScript) theme={null}
// Appel backend → récupère l'URL de paiement
const { payUrl } = await fetch("/api/commandes/cmd_7f3a9b/payer", {
  method: "POST",
}).then((r) => r.json());

// Redirection dans le même onglet (recommandé)
window.location.href = payUrl;

// Ou dans un nouvel onglet
// window.open(payUrl, "_blank");
```

<Warning>
  Ne jamais ouvrir l'URL LigdiCash dans une `<iframe>`. LigdiCash bloque l'affichage en iframe. Utilisez une redirection dans le même onglet, un nouvel onglet, ou un popup. Voir [Pièges courants](/api-paiement/payin-redirect/pieges-courants).
</Warning>

Le client voit la page de paiement LigdiCash, sélectionne son opérateur mobile money et finalise le paiement. LigdiCash le redirige ensuite vers votre `return_url` (succès) ou `cancel_url` (annulation).

## Étape 4 — Réceptionner le callback

LigdiCash envoie une notification POST à votre `callback_url` dès que le statut de la transaction change. Votre backend doit :

1. Identifier la commande via `custom_data`
2. Re-vérifier le statut avec l'endpoint `confirm` (ne jamais faire confiance au payload seul)
3. Mettre à jour la commande en base
4. Répondre `200 OK`

```javascript Node.js (Express) theme={null}
app.post("/api/ligdicash/callback", express.json(), async (req, res) => {
  // Répondre 200 immédiatement pour éviter les retries
  res.sendStatus(200);

  // Extraire le transaction_id depuis custom_data
  const customData = req.body.custom_data ?? [];
  const entry = Array.isArray(customData)
    ? customData.find((e) => e.keyof_customdata === "transaction_id")
    : null;

  if (!entry) return;

  const transactionId = entry.valueof_customdata;

  // Récupérer la commande et son token LigdiCash
  const commande = await db.commandes.findById(transactionId);
  if (!commande || commande.statut !== "pending") return;

  // Re-vérifier le statut côté LigdiCash
  const confirm = await fetch(
    `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=${commande.ligdicash_token}`,
    {
      headers: {
        Apikey: process.env.LIGDICASH_API_KEY,
        Authorization: `Bearer ${process.env.LIGDICASH_AUTH_TOKEN}`,
        Accept: "application/json",
      },
    }
  ).then((r) => r.json());

  if (confirm.status === "completed") {
    await db.commandes.update(transactionId, { statut: "payee" });
    await livraison.declencher(transactionId);
  } else if (confirm.status === "notcompleted") {
    await db.commandes.update(transactionId, { statut: "echec" });
  }
  // Si "pending" : ne rien faire, attendre le prochain callback
});
```

<Note>
  LigdiCash envoie **deux requêtes POST** à votre callback pour chaque événement : une en `application/x-www-form-urlencoded` et une en `application/json`. Traitez-les de manière idempotente. Voir [Idempotence du callback](/api-paiement/callback/idempotence).
</Note>

## Étape 5 — Vérifier le statut côté frontend

Après la redirection vers votre `return_url`, le frontend interroge votre backend pour afficher le résultat final. La `return_url` est un signal d'interface — elle ne prouve pas que le paiement a réussi.

```javascript Frontend — page return_url theme={null}
// Extrait le transaction_id depuis l'URL (ex: /paiement/succes?cmd=cmd_7f3a9b)
const params = new URLSearchParams(window.location.search);
const commandeId = params.get("cmd");

const { statut } = await fetch(`/api/commandes/${commandeId}/statut`).then(
  (r) => r.json()
);

switch (statut) {
  case "payee":
    afficherConfirmation();
    break;
  case "pending":
    // Le callback n'est pas encore arrivé — afficher un loader et repolling
    afficherAttenteVerification();
    break;
  case "echec":
    afficherErreur();
    break;
}
```

```javascript Backend — GET /api/commandes/:id/statut theme={null}
app.get("/api/commandes/:id/statut", async (req, res) => {
  const commande = await db.commandes.findById(req.params.id);
  if (!commande) return res.status(404).json({ error: "not_found" });

  // Si toujours pending, interroger LigdiCash en temps réel
  if (commande.statut === "pending") {
    const confirm = await fetch(
      `https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm/?invoiceToken=${commande.ligdicash_token}`,
      {
        headers: {
          Apikey: process.env.LIGDICASH_API_KEY,
          Authorization: `Bearer ${process.env.LIGDICASH_AUTH_TOKEN}`,
          Accept: "application/json",
        },
      }
    ).then((r) => r.json());

    if (confirm.status === "completed") {
      await db.commandes.update(commande.id, { statut: "payee" });
      commande.statut = "payee";
    }
  }

  res.json({ statut: commande.statut });
});
```

## Récapitulatif

<Steps>
  <Step title="Stocker la commande">
    Créez la commande en base avec le statut `pending` avant tout appel LigdiCash.
  </Step>

  <Step title="Créer la facture">
    Backend → POST `/pay/v01/redirect/checkout-invoice/create`. Stockez le `token` retourné.
  </Step>

  <Step title="Rediriger le client">
    Frontend → redirection vers `response_text` (même onglet ou popup). Jamais d'iframe.
  </Step>

  <Step title="Réceptionner le callback">
    Répondre `200` immédiatement, puis re-vérifier via `confirm` avec le token stocké.
  </Step>

  <Step title="Confirmer la commande">
    Mettre à jour le statut en base et déclencher la livraison si `status === "completed"`.
  </Step>

  <Step title="Afficher le résultat">
    Frontend → interroger votre backend pour afficher le statut réel après retour sur `return_url`.
  </Step>
</Steps>

## Pages associées

* [Créer une facture](/api-paiement/payin-redirect/creer-facture) — paramètres complets de l'endpoint
* [Sécurisation du callback](/api-paiement/callback/securisation) — pattern de re-vérification détaillé
* [Parser custom\_data](/api-paiement/callback/parser-custom-data) — les 3 formes possibles
* [Architecture recommandée](/guides/architecture-recommandee) — structure backend complète


# Guide mobile : React Native et Flutter
Source: https://developers.ligdicash.com/guides/quickstart-mobile

Intégrer LigdiCash dans une application mobile React Native ou Flutter : architecture, WebView, gestion du retour et confirmation côté backend.

Ce guide explique comment intégrer LigdiCash dans une application mobile. Il couvre l'architecture recommandée, l'ouverture de la page de paiement via WebView, la détection du retour utilisateur et la confirmation du paiement côté backend.

**Pré-requis :** vous avez un backend exposant une route d'initiation du paiement et une route de statut. Ne jamais appeler l'API LigdiCash directement depuis l'application mobile. Voir [Architecture recommandée](/guides/architecture-recommandee).

## Architecture mobile

```
App mobile
    |
    | POST /api/paiement/initier
    ↓
Votre backend   →   LigdiCash
    |
    | { pay_url, transaction_id }
    ↓
App mobile
    |
    | Ouvre pay_url dans une WebView native
    ↓
Page de paiement LigdiCash
    |
    | Redirige vers return_url ou cancel_url
    ↓
WebView détecte l'URL → ferme la WebView
    |
    | GET /api/paiement/:id/statut
    ↓
Votre backend (interroge LigdiCash si needed)
    |
    | { statut: "completed" | "pending" | "notcompleted" }
    ↓
App mobile — affiche le résultat
```

<Warning>
  Ne jamais ouvrir l'URL LigdiCash dans le navigateur système. Cela fait quitter l'application et rend le retour impossible à détecter proprement. Utilisez une WebView native ou, en fallback acceptable, `SFSafariViewController` / Chrome Custom Tabs avec deep link.
</Warning>

## React Native

### Installation

```bash theme={null}
npm install react-native-webview
# iOS uniquement
npx pod-install
```

### Composant WebView de paiement

```jsx React Native theme={null}
import { useState } from "react";
import { ActivityIndicator, StyleSheet, View, Alert } from "react-native";
import { WebView } from "react-native-webview";

/**
 * @param {string} paymentUrl   - URL retournée par votre backend (response_text LigdiCash)
 * @param {Function} onSuccess  - Appelé quand return_url est détectée
 * @param {Function} onCancel   - Appelé quand cancel_url est détectée
 */
export function PaiementWebView({ paymentUrl, onSuccess, onCancel }) {
  const [loading, setLoading] = useState(true);

  const RETURN_URL = "https://monapp.com/paiement/succes";
  const CANCEL_URL = "https://monapp.com/paiement/annule";

  const handleNavigationChange = (navState) => {
    const { url } = navState;
    if (url.startsWith(RETURN_URL)) onSuccess();
    else if (url.startsWith(CANCEL_URL)) onCancel();
  };

  return (
    <View style={styles.container}>
      <WebView
        source={{ uri: paymentUrl }}
        onNavigationStateChange={handleNavigationChange}
        onLoadStart={() => setLoading(true)}
        onLoadEnd={() => setLoading(false)}
        onError={() => Alert.alert("Erreur", "Impossible de charger la page de paiement.")}
        javaScriptEnabled
      />
      {loading && (
        <ActivityIndicator style={styles.loader} size="large" color="#FF6B00" />
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  loader: { position: "absolute", alignSelf: "center", top: "50%" },
});
```

### Intégration dans un écran de paiement

```jsx React Native theme={null}
import { useState } from "react";
import { View, Text, TouchableOpacity, ActivityIndicator, StyleSheet } from "react-native";
import { PaiementWebView } from "./PaiementWebView";

export function EcranPaiement({ route, navigation }) {
  const { commandeId, montant, description } = route.params;

  const [payUrl, setPayUrl] = useState(null);
  const [transactionId, setTransactionId] = useState(null);
  const [statut, setStatut] = useState("idle"); // idle | loading | webview | verifying | done

  const initierPaiement = async () => {
    setStatut("loading");

    const res = await fetch("https://api.monapp.com/api/paiement/initier", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ commandeId, montant, description }),
    }).then((r) => r.json());

    if (!res.pay_url) {
      setStatut("idle");
      Alert.alert("Erreur", "Impossible d'initier le paiement. Réessayez.");
      return;
    }

    setTransactionId(res.transaction_id);
    setPayUrl(res.pay_url);
    setStatut("webview");
  };

  const verifierPaiement = async () => {
    setStatut("verifying");

    const res = await fetch(
      `https://api.monapp.com/api/paiement/${transactionId}/statut`
    ).then((r) => r.json());

    setStatut("done");

    if (res.statut === "completed") {
      navigation.replace("CommandeConfirmee", { commandeId });
    } else if (res.statut === "notcompleted") {
      navigation.replace("PaiementEchoue", { commandeId });
    } else {
      // pending : le callback n'est pas encore arrivé
      navigation.replace("PaiementEnAttente", { transactionId });
    }
  };

  if (statut === "webview") {
    return (
      <PaiementWebView
        paymentUrl={payUrl}
        onSuccess={verifierPaiement}
        onCancel={() => setStatut("idle")}
      />
    );
  }

  if (statut === "verifying") {
    return (
      <View style={styles.center}>
        <ActivityIndicator size="large" color="#FF6B00" />
        <Text style={styles.text}>Vérification du paiement…</Text>
      </View>
    );
  }

  return (
    <View style={styles.center}>
      <Text style={styles.montant}>{montant.toLocaleString()} XOF</Text>
      <Text style={styles.desc}>{description}</Text>
      <TouchableOpacity
        style={styles.bouton}
        onPress={initierPaiement}
        disabled={statut === "loading"}
      >
        {statut === "loading" ? (
          <ActivityIndicator color="#fff" />
        ) : (
          <Text style={styles.boutonTexte}>Payer maintenant</Text>
        )}
      </TouchableOpacity>
    </View>
  );
}

const styles = StyleSheet.create({
  center: { flex: 1, justifyContent: "center", alignItems: "center", padding: 24 },
  montant: { fontSize: 32, fontWeight: "bold", marginBottom: 8 },
  desc: { fontSize: 16, color: "#666", marginBottom: 32 },
  bouton: {
    backgroundColor: "#FF6B00",
    paddingHorizontal: 32,
    paddingVertical: 16,
    borderRadius: 8,
    minWidth: 200,
    alignItems: "center",
  },
  boutonTexte: { color: "#fff", fontSize: 18, fontWeight: "600" },
  text: { marginTop: 16, fontSize: 16, color: "#666" },
});
```

## Flutter

### Dépendance

```yaml pubspec.yaml theme={null}
dependencies:
  webview_flutter: ^4.0.0
  http: ^1.0.0
```

### Widget WebView de paiement

```dart Flutter theme={null}
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

class PaiementWebView extends StatefulWidget {
  final String paymentUrl;
  final VoidCallback onSuccess;
  final VoidCallback onCancel;

  const PaiementWebView({
    required this.paymentUrl,
    required this.onSuccess,
    required this.onCancel,
    super.key,
  });

  @override
  State<PaiementWebView> createState() => _PaiementWebViewState();
}

class _PaiementWebViewState extends State<PaiementWebView> {
  late final WebViewController _controller;
  bool _loading = true;

  static const _returnUrl = "https://monapp.com/paiement/succes";
  static const _cancelUrl = "https://monapp.com/paiement/annule";

  @override
  void initState() {
    super.initState();
    _controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..setNavigationDelegate(NavigationDelegate(
        onPageStarted: (_) => setState(() => _loading = true),
        onPageFinished: (_) => setState(() => _loading = false),
        onNavigationRequest: (request) {
          if (request.url.startsWith(_returnUrl)) {
            widget.onSuccess();
            return NavigationDecision.prevent;
          }
          if (request.url.startsWith(_cancelUrl)) {
            widget.onCancel();
            return NavigationDecision.prevent;
          }
          return NavigationDecision.navigate;
        },
      ))
      ..loadRequest(Uri.parse(widget.paymentUrl));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Paiement"),
        leading: IconButton(
          icon: const Icon(Icons.close),
          onPressed: widget.onCancel,
        ),
      ),
      body: Stack(
        children: [
          WebViewWidget(controller: _controller),
          if (_loading) const Center(child: CircularProgressIndicator()),
        ],
      ),
    );
  }
}
```

### Écran de paiement complet

```dart Flutter theme={null}
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'paiement_webview.dart';

class EcranPaiement extends StatefulWidget {
  final String commandeId;
  final int montant;
  final String description;

  const EcranPaiement({
    required this.commandeId,
    required this.montant,
    required this.description,
    super.key,
  });

  @override
  State<EcranPaiement> createState() => _EcranPaiementState();
}

class _EcranPaiementState extends State<EcranPaiement> {
  String _statut = "idle";
  String? _payUrl;
  String? _transactionId;

  Future<void> _initierPaiement() async {
    setState(() => _statut = "loading");

    final res = await http.post(
      Uri.parse("https://api.monapp.com/api/paiement/initier"),
      headers: {"Content-Type": "application/json"},
      body: jsonEncode({
        "commandeId": widget.commandeId,
        "montant": widget.montant,
        "description": widget.description,
      }),
    );

    final data = jsonDecode(res.body) as Map<String, dynamic>;

    if (data["pay_url"] == null) {
      setState(() => _statut = "idle");
      if (mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(content: Text("Impossible d'initier le paiement.")),
        );
      }
      return;
    }

    setState(() {
      _payUrl = data["pay_url"] as String;
      _transactionId = data["transaction_id"] as String;
      _statut = "webview";
    });
  }

  Future<void> _verifierPaiement() async {
    setState(() => _statut = "verifying");

    final res = await http.get(
      Uri.parse("https://api.monapp.com/api/paiement/$_transactionId/statut"),
    );

    final data = jsonDecode(res.body) as Map<String, dynamic>;
    final statut = data["statut"] as String?;

    if (!mounted) return;

    if (statut == "completed") {
      Navigator.of(context).pushReplacementNamed(
        "/commande-confirmee",
        arguments: widget.commandeId,
      );
    } else if (statut == "notcompleted") {
      Navigator.of(context).pushReplacementNamed("/paiement-echoue");
    } else {
      // pending — le callback n'est pas encore arrivé
      Navigator.of(context).pushReplacementNamed(
        "/paiement-en-attente",
        arguments: _transactionId,
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    if (_statut == "webview") {
      return PaiementWebView(
        paymentUrl: _payUrl!,
        onSuccess: _verifierPaiement,
        onCancel: () => setState(() => _statut = "idle"),
      );
    }

    if (_statut == "verifying") {
      return const Scaffold(
        body: Center(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              CircularProgressIndicator(),
              SizedBox(height: 16),
              Text("Vérification du paiement…"),
            ],
          ),
        ),
      );
    }

    return Scaffold(
      appBar: AppBar(title: const Text("Paiement")),
      body: Center(
        child: Padding(
          padding: const EdgeInsets.all(24),
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              Text(
                "${widget.montant.toString()} XOF",
                style: const TextStyle(fontSize: 32, fontWeight: FontWeight.bold),
              ),
              const SizedBox(height: 8),
              Text(widget.description, style: const TextStyle(color: Colors.grey)),
              const SizedBox(height: 32),
              SizedBox(
                width: double.infinity,
                child: ElevatedButton(
                  onPressed: _statut == "loading" ? null : _initierPaiement,
                  style: ElevatedButton.styleFrom(
                    backgroundColor: const Color(0xFFFF6B00),
                    padding: const EdgeInsets.symmetric(vertical: 16),
                  ),
                  child: _statut == "loading"
                      ? const CircularProgressIndicator(color: Colors.white)
                      : const Text(
                          "Payer maintenant",
                          style: TextStyle(fontSize: 18, color: Colors.white),
                        ),
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}
```

## Gérer l'état "pending"

Quand le callback n'est pas encore arrivé au moment où l'utilisateur revient dans l'application, la transaction est `pending`. Deux approches :

<Tabs>
  <Tab title="Polling côté app">
    Affichez un écran « Vérification en cours » et interrogez votre backend toutes les 3 secondes pendant 30 secondes maximum.

    ```dart Flutter — polling theme={null}
    Future<String> attendreStatut(String transactionId) async {
      for (var i = 0; i < 10; i++) {
        await Future.delayed(const Duration(seconds: 3));

        final res = await http.get(
          Uri.parse("https://api.monapp.com/api/paiement/$transactionId/statut"),
        );
        final statut = jsonDecode(res.body)["statut"] as String;

        if (statut != "pending") return statut;
      }
      return "pending"; // toujours pending après 30s
    }
    ```
  </Tab>

  <Tab title="Notification push">
    Votre backend reçoit le callback LigdiCash et envoie une notification push à l'application via FCM ou APNs. L'application rafraîchit l'écran à la réception.

    C'est l'approche la plus propre : elle évite le polling et garantit que l'utilisateur voit le résultat dès que LigdiCash confirme, même s'il a mis l'application en arrière-plan.
  </Tab>
</Tabs>

## Points de vigilance

<Warning>
  La détection de `return_url` ou `cancel_url` dans la WebView est un signal d'interface, pas une preuve de paiement. Confirmez toujours le statut via votre backend avant d'afficher une confirmation à l'utilisateur.
</Warning>

<Note>
  Sur iOS, `WKWebView` (utilisé par `react-native-webview` et `webview_flutter`) bloque les requêtes vers des URLs HTTP si App Transport Security est activé. Utilisez des URLs HTTPS pour votre `return_url` et `cancel_url`.
</Note>

<Tip>
  Passez le `transaction_id` dans les paramètres de query de `return_url` et `cancel_url` (`?txn=txn_abc123`) pour l'extraire facilement dans la WebView sans avoir à le stocker en état global.
</Tip>

## Pages associées

* [Intégration mobile native (payin redirect)](/api-paiement/payin-redirect/integration-mobile) — WebView détaillée pour iOS (Swift) et Android (Kotlin)
* [Architecture recommandée](/guides/architecture-recommandee) — structure backend proxy
* [Sécurisation du callback](/api-paiement/callback/securisation) — re-vérification côté serveur
* [Guide e-commerce](/guides/quickstart-ecommerce) — le même flux côté web


# Envoyer l'OTP Wallet LigdiCash
Source: https://developers.ligdicash.com/reference/endpoints/debit-otp

GET https://app.ligdicash.com/pay/v02/debitotp/{phone_number}/{amount}
Déclenche l'envoi d'un OTP SMS au client pour authentifier un paiement via son wallet LigdiCash. Première étape du flux wallet.

<Note>
  Cet endpoint est **exclusif au Wallet LigdiCash**. Pour tous les autres opérateurs mobile money, utilisez [POST /pay/v01/straight/checkout-invoice/create](/reference/endpoints/payin-straight-create).
</Note>

## En-têtes

<ParamField type="string">
  Clé API du projet LigdiCash.
</ParamField>

<ParamField type="string">
  `Bearer {API_TOKEN}`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

## Paramètres de chemin

<ParamField type="string">
  Numéro de téléphone du client associé à son compte LigdiCash. Format : indicatif pays + numéro local, sans `+` ni espaces. Exemple : `22670000000`.
</ParamField>

<ParamField type="integer">
  Montant en XOF (entier, sans décimales).
</ParamField>

## Réponse

<ResponseField name="error" type="boolean">
  `false` = OTP envoyé avec succès. `true` = échec.
</ResponseField>

<ResponseField name="message" type="string">
  Message descriptif. Exemple : `"OTP sent. Please check your phone."`
</ResponseField>

<CodeGroup>
  ```json Succès theme={null}
  {
    "error": false,
    "message": "OTP sent. Please check your phone."
  }
  ```

  ```json Échec theme={null}
  {
    "error": true,
    "message": "..."
  }
  ```
</CodeGroup>

<Warning>
  Vérifiez que `error` vaut `false` avant d'afficher le champ de saisie OTP au client. Si `error` est `true`, ne proposez pas la saisie.
</Warning>

## Suite du flux

Après réception de l'OTP par le client, soumettez la transaction avec [POST /pay/v02/debitwallet/withotp](/reference/endpoints/debit-wallet-with-otp).

## Guide associé

[Wallet LigdiCash](/api-paiement/payin-sans-redirect/operateurs/wallet-ligdicash) — flux complet en deux étapes.


# Soumettre un paiement Wallet LigdiCash
Source: https://developers.ligdicash.com/reference/endpoints/debit-wallet-with-otp

POST https://app.ligdicash.com/pay/v02/debitwallet/withotp
Finalise un paiement via wallet LigdiCash en soumettant l'OTP reçu par le client. Deuxième étape du flux wallet.

<Note>
  Cet endpoint est **exclusif au Wallet LigdiCash**, à appeler après [GET /pay/v02/debitotp](/reference/endpoints/debit-otp) qui déclenche l'envoi de l'OTP au client.
</Note>

## En-têtes

<ParamField type="string">
  Clé API du projet LigdiCash.
</ParamField>

<ParamField type="string">
  `Bearer {API_TOKEN}`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

## Corps

Même structure que [POST /pay/v01/straight/checkout-invoice/create](/reference/endpoints/payin-straight-create), avec `customer` renseigné et `otp` contenant le code reçu par le client.

<ParamField type="object">
  <Expandable title="commande">
    <ParamField type="object">
      <Expandable title="invoice">
        <ParamField type="array">Articles. Peut être `[]`.</ParamField>
        <ParamField type="integer">Montant en XOF (entier).</ParamField>
        <ParamField type="string">Toujours `"XOF"`.</ParamField>
        <ParamField type="string">Description de la commande.</ParamField>
        <ParamField type="string">Numéro de téléphone du compte LigdiCash client. Format : `22670XXXXXXX`.</ParamField>
        <ParamField type="string">Prénom.</ParamField>
        <ParamField type="string">Nom.</ParamField>
        <ParamField type="string">Email.</ParamField>
        <ParamField type="string">Toujours `""`.</ParamField>
        <ParamField type="string">OTP reçu par le client sur son application ou par SMS LigdiCash.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      <Expandable title="store">
        <ParamField type="string">Nom de la boutique.</ParamField>
        <ParamField type="string">URL du site marchand.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      <Expandable title="actions">
        <ParamField type="string">Toujours `""`.</ParamField>
        <ParamField type="string">Toujours `""`.</ParamField>
        <ParamField type="string">URL de notification backend. Accessible publiquement.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">Métadonnées libres. Recommandé : inclure un `transaction_id` unique.</ParamField>
  </Expandable>
</ParamField>

## Réponse

<ResponseField name="response_code" type="string">`"00"` = succès, `"01"` = erreur.</ResponseField>
<ResponseField name="token" type="string">Token de la transaction. **À stocker immédiatement** — requis pour `confirm`.</ResponseField>
<ResponseField name="response_text" type="string">Succès : `"Votre requête est en cours de traitement"`. Échec : `Echec (CodeXX)`.</ResponseField>
<ResponseField name="wiki" type="string">URL de la documentation des sous-codes.</ResponseField>

<CodeGroup>
  ```json Succès theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "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>

## Codes d'erreur

Wiki : `https://client.ligdicash.com/wiki/createInvoice` — voir [Sous-codes par endpoint](/erreurs/sous-codes#createinvoice).

## Guide associé

[Wallet LigdiCash](/api-paiement/payin-sans-redirect/operateurs/wallet-ligdicash) — flux complet en deux étapes.


# Vérifier le statut d'une facture payin
Source: https://developers.ligdicash.com/reference/endpoints/payin-redirect-confirm

GET https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/confirm
Vérifie le statut d'une facture payin (redirect ou sans redirect) à partir du token de création.

## En-têtes

<ParamField type="string">
  Clé API du projet LigdiCash.
</ParamField>

<ParamField type="string">
  `Bearer {API_TOKEN}`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

## Paramètre de requête

<ParamField type="string">
  Token retourné par l'endpoint `create` à la création de la facture. **Ne pas utiliser le token du callback** — ils sont différents.
</ParamField>

## Réponse

<ResponseField name="response_code" type="string">`"00"` = appel réussi, `"01"` = erreur technique.</ResponseField>
<ResponseField name="status" type="string">Statut du paiement : `completed`, `pending` ou `notcompleted`.</ResponseField>
<ResponseField name="token" type="string">Vide dans la réponse `confirm`.</ResponseField>
<ResponseField name="response_text" type="string">Sous-code d'erreur si `response_code = "01"`, vide sinon.</ResponseField>
<ResponseField name="description" type="string">Description libre. Peut être vide.</ResponseField>
<ResponseField name="operator_id" type="string">Identifiant de l'opérateur utilisé. Vide si `status = pending`.</ResponseField>
<ResponseField name="operator_name" type="string">Nom de l'opérateur. Vide si `status = pending`.</ResponseField>
<ResponseField name="customer" type="string">Numéro du payeur. `null` si `status = pending`.</ResponseField>
<ResponseField name="montant" type="integer">Montant en XOF.</ResponseField>
<ResponseField name="amount" type="integer">Identique à `montant`.</ResponseField>
<ResponseField name="date" type="string">Date de la transaction. Format : `YYYY-MM-DD HH:MM:SS+TZ`.</ResponseField>
<ResponseField name="external_id" type="string">Concaténation des `valueof_customdata` dont la clé contient `"id"`. Correspond au `transaction_id` si le pattern est respecté.</ResponseField>
<ResponseField name="oreference" type="string">Référence opérateur. Peut être vide.</ResponseField>
<ResponseField name="request_id" type="string">Identifiant unique LigdiCash. Utile pour le support.</ResponseField>

<ResponseField name="custom_data" type="array">
  Métadonnées enrichies par LigdiCash.

  <Expandable title="Champs d'une entrée">
    <ResponseField name="keyof_customdata" type="string">Clé. LigdiCash ajoute ses propres entrées (`logfile`).</ResponseField>
    <ResponseField name="valueof_customdata" type="string">Valeur.</ResponseField>
    <ResponseField name="datecreation_customdata" type="string">Date de création de l'entrée.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customer_details" type="object">
  <Expandable title="Champs">
    <ResponseField name="firstname" type="string">Prénom.</ResponseField>
    <ResponseField name="lastname" type="string">Nom.</ResponseField>
    <ResponseField name="email" type="string">Email.</ResponseField>
    <ResponseField name="phone" type="string">Téléphone.</ResponseField>
    <ResponseField name="details" type="string">Informations complémentaires.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="wiki" type="string">URL de la documentation des sous-codes.</ResponseField>

| `status`       | Signification                      |
| -------------- | ---------------------------------- |
| `completed`    | Paiement confirmé                  |
| `pending`      | En attente de traitement opérateur |
| `notcompleted` | Paiement non abouti                |

<CodeGroup>
  ```json completed theme={null}
  {
    "response_code": "00",
    "status": "completed",
    "operator_id": "14",
    "operator_name": "MOOV CI",
    "customer": "2250171584035",
    "montant": 5000,
    "amount": 5000,
    "date": "2026-04-15 11:19:28+00",
    "external_id": "ORD-2025-00042",
    "oreference": "",
    "request_id": "P2771491712026",
    "token": "",
    "response_text": "",
    "description": "",
    "custom_data": [
      { "keyof_customdata": "transaction_id", "valueof_customdata": "ORD-2025-00042", "datecreation_customdata": "2026-04-15 11:19:28.977757" },
      { "keyof_customdata": "logfile", "valueof_customdata": "2026041511192869df7440ed917", "datecreation_customdata": "2026-04-15 11:19:28.977757" }
    ],
    "customer_details": { "firstname": "Amadou", "lastname": "Diallo", "email": "amadou@exemple.com", "phone": "2250171584035", "details": "" },
    "wiki": "https://client.ligdicash.com/wiki/confirmInvoice"
  }
  ```

  ```json pending theme={null}
  {
    "response_code": "00",
    "status": "pending",
    "operator_id": "",
    "operator_name": "",
    "customer": null,
    "montant": 5000,
    "amount": 5000,
    "date": "2026-04-22 16:51:02+00",
    "external_id": "ORD-2025-00042",
    "token": "",
    "response_text": "",
    "wiki": "https://client.ligdicash.com/wiki/confirmInvoice"
  }
  ```

  ```json Erreur API theme={null}
  {
    "response_code": "01",
    "response_text": "Echec (Code01)",
    "status": "",
    "wiki": "https://client.ligdicash.com/wiki/confirmInvoice"
  }
  ```
</CodeGroup>

## Codes d'erreur

Wiki : `https://client.ligdicash.com/wiki/confirmInvoice` — voir [Sous-codes par endpoint](/erreurs/sous-codes#confirminvoice).

## Guides associés

* [Vérifier le statut — payin redirect](/api-paiement/payin-redirect/verifier-statut)
* [Vérifier le statut — payin sans redirect](/api-paiement/payin-sans-redirect/verifier-statut)
* [Sécurisation du callback](/api-paiement/callback/securisation)


# Créer une facture payin redirect
Source: https://developers.ligdicash.com/reference/endpoints/payin-redirect-create

POST https://app.ligdicash.com/pay/v01/redirect/checkout-invoice/create
Crée une facture de paiement avec redirection et retourne l'URL de la page de paiement LigdiCash.

## En-têtes

<ParamField type="string">
  Clé API du projet LigdiCash.
</ParamField>

<ParamField type="string">
  `Bearer {API_TOKEN}`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

## Corps

<ParamField type="object">
  <Expandable title="commande">
    <ParamField type="object">
      <Expandable title="invoice">
        <ParamField type="array">
          Articles de la commande. Peut être `[]` — dans ce cas seul `total_amount` est utilisé.

          <Expandable title="item">
            <ParamField type="string">Nom de l'article.</ParamField>
            <ParamField type="string">Description.</ParamField>
            <ParamField type="integer">Quantité.</ParamField>
            <ParamField type="integer">Prix unitaire en XOF.</ParamField>
            <ParamField type="integer">`unit_price × quantity` en XOF.</ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="integer">Montant total en XOF (entier).</ParamField>
        <ParamField type="string">Toujours `"XOF"`.</ParamField>
        <ParamField type="string">Description affichée sur la page de paiement.</ParamField>
        <ParamField type="string">Toujours `""`. Un numéro non vide filtre les opérateurs affichés.</ParamField>
        <ParamField type="string">Prénom du client.</ParamField>
        <ParamField type="string">Nom du client.</ParamField>
        <ParamField type="string">Email du client.</ParamField>
        <ParamField type="string">Identifiant marchand alternatif. `""` si non utilisé.</ParamField>
        <ParamField type="string">Toujours `""`.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      <Expandable title="store">
        <ParamField type="string">Nom de la boutique affiché sur la page de paiement.</ParamField>
        <ParamField type="string">URL du site marchand.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      <Expandable title="actions">
        <ParamField type="string">URL de redirection si le client annule.</ParamField>
        <ParamField type="string">URL de redirection après paiement réussi.</ParamField>
        <ParamField type="string">URL de notification backend. Doit être accessible publiquement.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">Métadonnées libres retournées dans le callback. Recommandé : inclure un `transaction_id` unique.</ParamField>
  </Expandable>
</ParamField>

## Réponse

<ResponseField name="response_code" type="string">
  `"00"` = succès, `"01"` = erreur.
</ResponseField>

<ResponseField name="token" type="string">
  Token de la transaction. **À stocker immédiatement** — requis pour appeler `confirm`.
</ResponseField>

<ResponseField name="response_text" type="string">
  Succès : URL de la page de paiement à ouvrir pour le client. Échec : sous-code `Echec (CodeXX)`.
</ResponseField>

<ResponseField name="wiki" type="string">
  URL de la documentation des sous-codes pour cet endpoint.
</ResponseField>

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

## Codes d'erreur

Wiki : `https://client.ligdicash.com/wiki/createInvoice` — voir [Sous-codes par endpoint](/erreurs/sous-codes#createinvoice).

## Guide associé

[Créer une facture](/api-paiement/payin-redirect/creer-facture) — exemples complets et pièges à éviter.


# Créer une transaction payin sans redirect
Source: https://developers.ligdicash.com/reference/endpoints/payin-straight-create

POST https://app.ligdicash.com/pay/v01/straight/checkout-invoice/create
Initie un paiement mobile money directement depuis votre interface, sans redirection vers une page LigdiCash.

<Note>
  Le Wallet LigdiCash utilise des endpoints distincts (`/v02`). Voir [GET /pay/v02/debitotp](/reference/endpoints/debit-otp) et [POST /pay/v02/debitwallet/withotp](/reference/endpoints/debit-wallet-with-otp).
</Note>

## En-têtes

<ParamField type="string">
  Clé API du projet LigdiCash.
</ParamField>

<ParamField type="string">
  `Bearer {API_TOKEN}`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

## Corps

<ParamField type="object">
  <Expandable title="commande">
    <ParamField type="object">
      <Expandable title="invoice">
        <ParamField type="array">
          Articles. Peut être `[]` — `total_amount` fait foi.

          <Expandable title="item">
            <ParamField type="string">Nom de l'article.</ParamField>
            <ParamField type="string">Description.</ParamField>
            <ParamField type="integer">Quantité.</ParamField>
            <ParamField type="integer">Prix unitaire en XOF.</ParamField>
            <ParamField type="integer">`unit_price × quantity` en XOF.</ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="integer">Montant total en XOF (entier).</ParamField>
        <ParamField type="string">Toujours `"XOF"`.</ParamField>
        <ParamField type="string">Description de la commande.</ParamField>
        <ParamField type="string">Numéro mobile money du client. Format : `22670XXXXXXX` (sans `+` ni espaces).</ParamField>
        <ParamField type="string">Prénom du client.</ParamField>
        <ParamField type="string">Nom du client.</ParamField>
        <ParamField type="string">Email du client.</ParamField>
        <ParamField type="string">Toujours `""`.</ParamField>

        <ParamField type="string">
          OTP selon le mode de l'opérateur : OTP USSD → valeur ; USSD Push / Approbation / 1ère requête OTP SMS → `""` ; 2ème requête OTP SMS → OTP reçu par SMS.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      <Expandable title="store">
        <ParamField type="string">Nom de la boutique.</ParamField>
        <ParamField type="string">URL du site marchand.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      <Expandable title="actions">
        <ParamField type="string">Toujours `""`.</ParamField>
        <ParamField type="string">Toujours `""`.</ParamField>
        <ParamField type="string">URL de notification backend. Accessible publiquement.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">Métadonnées libres retournées dans le callback. Recommandé : inclure un `transaction_id` unique.</ParamField>
  </Expandable>
</ParamField>

## Réponse

<ResponseField name="response_code" type="string">`"00"` = succès, `"01"` = erreur.</ResponseField>
<ResponseField name="token" type="string">Token de la transaction. **À stocker immédiatement** — requis pour `confirm`.</ResponseField>
<ResponseField name="response_text" type="string">Succès : `"Votre requête est en cours de traitement"`. Échec : `Echec (CodeXX)`.</ResponseField>
<ResponseField name="wiki" type="string">URL de la documentation des sous-codes.</ResponseField>

<CodeGroup>
  ```json Succès theme={null}
  {
    "response_code": "00",
    "token": "eyJ0eXAiOiJKV1Qi...",
    "response_text": "Votre requête est en cours de traitement",
    "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>

## Codes d'erreur

Wiki : `https://client.ligdicash.com/wiki/createInvoice` — voir [Sous-codes par endpoint](/erreurs/sous-codes#createinvoice).

## Guides associés

* [Créer une transaction](/api-paiement/payin-sans-redirect/creer-transaction) — exemples par mode OTP
* [Modes de validation](/api-paiement/payin-sans-redirect/modes-validation) — OTP USSD, OTP SMS, Approbation


# Créer un payout mobile money direct
Source: https://developers.ligdicash.com/reference/endpoints/straight-payout

POST https://app.ligdicash.com/pay/v01/straight/payout
Transfère des fonds directement vers un numéro mobile money, sans compte LigdiCash intermédiaire.

<Note>
  Cette méthode n'est pas instantanée. Le délai peut aller de quelques secondes à plusieurs jours selon l'opérateur. Pour un crédit instantané vers un wallet LigdiCash, utilisez [POST /pay/v01/withdrawal/create](/reference/endpoints/withdrawal-create).
</Note>

## En-têtes

<ParamField type="string">
  Clé API du projet LigdiCash.
</ParamField>

<ParamField type="string">
  `Bearer {API_TOKEN}`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

## Corps

<ParamField type="object">
  <Expandable title="commande">
    <ParamField type="integer">Montant en XOF (entier positif).</ParamField>
    <ParamField type="string">Description de l'opération.</ParamField>
    <ParamField type="string">Numéro mobile money du bénéficiaire. Format : indicatif + numéro, sans `+` ni espaces. Exemple : `22670000000`.</ParamField>
    <ParamField type="string">URL HTTPS de notification. Doit être accessible publiquement.</ParamField>
    <ParamField type="object">Métadonnées libres. Recommandé : inclure un `transaction_id` unique.</ParamField>
  </Expandable>
</ParamField>

## Réponse

<ResponseField name="response_code" type="string">`"00"` = payout initié, autre valeur = erreur.</ResponseField>
<ResponseField name="token" type="string">Token du payout. À stocker — requis pour [vérifier le statut](/reference/endpoints/withdrawal-confirm).</ResponseField>
<ResponseField name="response_text" type="string">Message associé. Peut être vide.</ResponseField>
<ResponseField name="description" type="string">Description complémentaire. Peut être vide.</ResponseField>
<ResponseField name="custom_data" type="string">Toujours `""`.</ResponseField>
<ResponseField name="wiki" type="string">URL de la documentation des sous-codes.</ResponseField>

<CodeGroup>
  ```json Succès theme={null}
  {
    "response_code": "00",
    "token": "{PAYOUT_TOKEN}",
    "response_text": "",
    "description": "",
    "custom_data": "",
    "wiki": "https://client.ligdicash.com/wiki/createStraightWithdrawal"
  }
  ```

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

## Codes d'erreur

Wiki : `https://client.ligdicash.com/wiki/createStraightWithdrawal` — voir [Sous-codes par endpoint](/erreurs/sous-codes#createstraightwithdrawal).

## Guide associé

[Payout Marchand — vers mobile money](/api-paiement/payout/vers-mobile-money) — différences avec le payout wallet.


# Vérifier le statut d'un payout
Source: https://developers.ligdicash.com/reference/endpoints/withdrawal-confirm

GET https://app.ligdicash.com/pay/v01/withdrawal/confirm/
Interroge le statut d'un payout (wallet ou mobile money) à partir du token retourné à la création.

## En-têtes

<ParamField type="string">
  Clé API du projet LigdiCash.
</ParamField>

<ParamField type="string">
  `Bearer {API_TOKEN}`
</ParamField>

## Paramètre de requête

<ParamField type="string">
  Token retourné par l'endpoint de création du payout (`/withdrawal/create` ou `/straight/payout`).
</ParamField>

## Réponse

<ResponseField name="response_code" type="string">`"00"` = appel réussi, autre valeur = erreur.</ResponseField>
<ResponseField name="token" type="string">Token JWT du payout — identique à celui passé en paramètre.</ResponseField>
<ResponseField name="response_text" type="string">Libellé du code de résultat. Peut être vide.</ResponseField>
<ResponseField name="description" type="string">Description complémentaire. Peut être vide.</ResponseField>
<ResponseField name="custom_data" type="array">Toujours `[]`.</ResponseField>
<ResponseField name="status" type="string">Statut du payout : `completed`, `pending` ou `notcompleted`.</ResponseField>
<ResponseField name="operator_id" type="string">Identifiant de l'opérateur. Exemple : `"11"` pour Orange Burkina.</ResponseField>
<ResponseField name="operator_name" type="string">Nom de l'opérateur. Exemple : `"ORANGE BURKINA"`.</ResponseField>
<ResponseField name="wiki" type="string">URL de la documentation des sous-codes.</ResponseField>

| `status`       | Signification               |
| -------------- | --------------------------- |
| `completed`    | Payout finalisé avec succès |
| `pending`      | Traitement en cours         |
| `notcompleted` | Payout échoué               |

<CodeGroup>
  ```json completed theme={null}
  {
    "response_code": "00",
    "token": "{PAYOUT_TOKEN}",
    "response_text": "",
    "description": "",
    "custom_data": [],
    "status": "completed",
    "operator_id": "11",
    "operator_name": "ORANGE BURKINA",
    "wiki": "https://client.ligdicash.com/wiki/createStraightWithdrawal"
  }
  ```

  ```json pending theme={null}
  {
    "response_code": "00",
    "token": "{PAYOUT_TOKEN}",
    "status": "pending",
    "operator_id": "",
    "operator_name": "",
    "wiki": "https://client.ligdicash.com/wiki/createStraightWithdrawal"
  }
  ```

  ```json Erreur API theme={null}
  {
    "response_code": "01",
    "response_text": "Echec (Code01)",
    "wiki": "https://client.ligdicash.com/wiki/createStraightWithdrawal"
  }
  ```
</CodeGroup>

## Codes d'erreur

Wiki : `https://client.ligdicash.com/wiki/createStraightWithdrawal` — voir [Sous-codes par endpoint](/erreurs/sous-codes#createstraightwithdrawal).

## Guide associé

[Vérifier le statut d'un payout](/api-paiement/payout/verifier-statut) — stratégie polling vs callback.


# Créer un payout wallet
Source: https://developers.ligdicash.com/reference/endpoints/withdrawal-create

POST https://app.ligdicash.com/pay/v01/withdrawal/create
Transfère des fonds vers le wallet LigdiCash d'un bénéficiaire, avec option de virement automatique vers son mobile money.

<Note>
  Le bénéficiaire doit posséder un compte LigdiCash. Pour envoyer directement vers un numéro mobile money sans compte LigdiCash, utilisez [POST /pay/v01/straight/payout](/reference/endpoints/straight-payout).
</Note>

## En-têtes

<ParamField type="string">
  Clé API du projet LigdiCash.
</ParamField>

<ParamField type="string">
  `Bearer {API_TOKEN}`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

<ParamField type="string">
  `application/json`
</ParamField>

## Corps

<ParamField type="object">
  <Expandable title="commande">
    <ParamField type="integer">Montant en XOF (entier positif).</ParamField>
    <ParamField type="string">Description de l'opération.</ParamField>
    <ParamField type="string">Numéro de téléphone du bénéficiaire. Format : indicatif + numéro, sans `+` ni espaces. Exemple : `22670000000`.</ParamField>
    <ParamField type="string">URL HTTPS de notification. Doit être accessible publiquement.</ParamField>

    <ParamField type="integer">
      * `1` — les fonds restent dans le wallet LigdiCash du bénéficiaire.
      * `0` — LigdiCash déclenche automatiquement un virement vers le compte mobile money lié.
    </ParamField>

    <ParamField type="object">Métadonnées libres. Recommandé : inclure un `transaction_id` unique.</ParamField>
  </Expandable>
</ParamField>

## Réponse

<ResponseField name="response_code" type="string">`"00"` = payout initié, autre valeur = erreur.</ResponseField>
<ResponseField name="token" type="string">Token du payout. À stocker — requis pour [vérifier le statut](/reference/endpoints/withdrawal-confirm).</ResponseField>
<ResponseField name="response_text" type="string">Message associé. Peut être vide.</ResponseField>
<ResponseField name="description" type="string">Description complémentaire. Peut être vide.</ResponseField>
<ResponseField name="custom_data" type="array">Toujours `[]`.</ResponseField>
<ResponseField name="wiki" type="string">URL de la documentation des sous-codes.</ResponseField>

<CodeGroup>
  ```json Succès theme={null}
  {
    "response_code": "00",
    "token": "{PAYOUT_TOKEN}",
    "response_text": "",
    "description": "",
    "custom_data": [],
    "wiki": "https://client.ligdicash.com/wiki/createWithdrawal"
  }
  ```

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

## Codes d'erreur

Wiki : `https://client.ligdicash.com/wiki/createWithdrawal` — voir [Sous-codes par endpoint](/erreurs/sous-codes#createwithdrawal).

## Guide associé

[Payout Client — vers wallet LigdiCash](/api-paiement/payout/vers-wallet-ligdicash) — cas d'usage et détail de `top_up_wallet`.


# Référence API
Source: https://developers.ligdicash.com/reference/introduction

URL de base, en-têtes obligatoires, format des requêtes et des réponses pour tous les endpoints LigdiCash.

## URL de base

Tous les endpoints sont accessibles sur :

```
https://app.ligdicash.com
```

Il n'existe pas d'URL sandbox distincte. Durant la phase d'intégration, vous utilisez cette même URL avec les clés de votre compte temporaire. Voir [Environnements](/concepts/environnements).

## En-têtes obligatoires

Toutes les requêtes doivent inclure ces en-têtes :

| En-tête         | Valeur                                        |
| --------------- | --------------------------------------------- |
| `Apikey`        | Clé API de votre projet                       |
| `Authorization` | `Bearer {API_TOKEN}`                          |
| `Accept`        | `application/json`                            |
| `Content-Type`  | `application/json` (requêtes POST uniquement) |

```bash theme={null}
curl -X POST https://app.ligdicash.com/pay/v01/... \
  -H "Apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
```

Voir [Authentification](/concepts/authentification) pour obtenir vos clés.

## Format des requêtes

Les corps de requête sont en JSON. L'objet racine est toujours `commande` pour les endpoints de création de transaction.

## Format des réponses

Toutes les réponses sont en JSON. Les champs communs à toutes les réponses :

| Champ           | Type     | Description                                        |
| --------------- | -------- | -------------------------------------------------- |
| `response_code` | `string` | `"00"` = succès, `"01"` = erreur                   |
| `token`         | `string` | Token de la transaction (vide en cas d'erreur)     |
| `response_text` | `string` | Message ou sous-code d'erreur (`Echec (CodeXX)`)   |
| `wiki`          | `string` | URL vers la liste des sous-codes pour cet endpoint |

<Note>
  `response_code: "00"` indique que la **requête API a abouti**, pas nécessairement que la transaction est complétée. Utilisez le champ `status` (via `confirm` ou callback) pour connaître le résultat du paiement.
</Note>

## Versionnement

L'API LigdiCash expose deux versions :

| Version | Endpoints                                             | Usage                                   |
| ------- | ----------------------------------------------------- | --------------------------------------- |
| `v01`   | Tous les endpoints payin et payout standard           | Opérateurs mobile money et flux général |
| `v02`   | `/pay/v02/debitotp` et `/pay/v02/debitwallet/withotp` | Wallet LigdiCash uniquement             |

## Endpoints disponibles

<CardGroup>
  <Card title="Payin redirect — create" href="/reference/endpoints/payin-redirect-create">
    `POST /pay/v01/redirect/checkout-invoice/create`
  </Card>

  <Card title="Payin — confirm" href="/reference/endpoints/payin-redirect-confirm">
    `GET /pay/v01/redirect/checkout-invoice/confirm`
  </Card>

  <Card title="Payin sans redirect — create" href="/reference/endpoints/payin-straight-create">
    `POST /pay/v01/straight/checkout-invoice/create`
  </Card>

  <Card title="Wallet — envoyer OTP" href="/reference/endpoints/debit-otp">
    `GET /pay/v02/debitotp/{phone}/{amount}`
  </Card>

  <Card title="Wallet — soumettre paiement" href="/reference/endpoints/debit-wallet-with-otp">
    `POST /pay/v02/debitwallet/withotp`
  </Card>

  <Card title="Payout wallet — create" href="/reference/endpoints/withdrawal-create">
    `POST /pay/v01/withdrawal/create`
  </Card>

  <Card title="Payout mobile money — create" href="/reference/endpoints/straight-payout">
    `POST /pay/v01/straight/payout`
  </Card>

  <Card title="Payout — confirm" href="/reference/endpoints/withdrawal-confirm">
    `GET /pay/v01/withdrawal/confirm/`
  </Card>
</CardGroup>


# Opérateurs supportés
Source: https://developers.ligdicash.com/reference/operateurs-supportes

Tableau maître de tous les opérateurs supportés par LigdiCash : pays, operator_name, mode de validation, endpoint, montant minimum.

LigdiCash couvre **9 pays d'Afrique de l'Ouest et Centrale**. Le tableau ci-dessous recense tous les opérateurs disponibles avec leurs identifiants techniques, leur mode de validation et l'endpoint API à utiliser.

<Note>
  L'`operator_id` est un identifiant numérique retourné par l'API dans certaines réponses. Il est documenté pour les opérateurs déjà confirmés par l'équipe technique — `-` indique qu'il sera ajouté ultérieurement. Pour les détails d'intégration, consultez la page dédiée à chaque opérateur.
</Note>

## Tableau maître

| Pays           | Opérateur                                 | `operator_id` | `operator_name`                | Mode de validation              | Endpoint                                     | Min |
| -------------- | ----------------------------------------- | ------------- | ------------------------------ | ------------------------------- | -------------------------------------------- | --- |
| —              | Wallet LigdiCash                          | `-`           | `LIGDICASH`                    | OTP SMS                         | `/v02/debitotp` + `/v02/debitwallet/withotp` | --  |
| Bénin          | Moov Africa                               | `2`           | `MOOV BENIN`                   | USSD Push                       | `/v01/straight/checkout-invoice/create`      | 100 |
| Bénin          | MTN Mobile Money                          | `1`           | `MTN BENIN`                    | USSD Push                       | `/v01/straight/checkout-invoice/create`      | 100 |
| Burkina Faso   | Orange Money                              | `11`          | `ORANGE BURKINA`               | OTP USSD                        | `/v01/straight/checkout-invoice/create`      | 10  |
| Burkina Faso   | Moov Africa                               | `12`          | `MOOV AFRICA BURKINA`          | USSD Push (fallback USSD guidé) | `/v01/straight/checkout-invoice/create`      | 100 |
| Côte d'Ivoire  | Orange Money                              | `16`          | `ORANGE CI`                    | Redirection opérateur           | `/v01/straight/checkout-invoice/create`      | 10  |
| Côte d'Ivoire  | Moov Africa                               | `14`          | `MOOV CI`                      | USSD Push (fallback USSD guidé) | `/v01/straight/checkout-invoice/create`      | 100 |
| Côte d'Ivoire  | MTN Mobile Money                          | `15`          | `MTN CI`                       | USSD guidé                      | `/v01/straight/checkout-invoice/create`      | 10  |
| Guinée Conakry | Orange Money                              | `33`          | `ORANGE GUINEE`                | Redirection LigdiCash           | `/v01/straight/checkout-invoice/create`      | 200 |
| Guinée Conakry | MTN Mobile Money                          | `51`          | `MTN GUINEE`                   | Redirection LigdiCash           | `/v01/straight/checkout-invoice/create`      | 200 |
| Mali           | Orange Money                              | `18`          | `ORANGE MALI`                  | Redirection opérateur           | `/v01/straight/checkout-invoice/create`      | 100 |
| Niger          | Airtel                                    | `27`          | `AIRTEL NIGER`                 | USSD Push                       | `/v01/straight/checkout-invoice/create`      | 10  |
| Niger          | Zamani                                    | `28`          | `ORANGE/ZAMANI NIGER`          | USSD guidé                      | `/v01/straight/checkout-invoice/create`      | 10  |
| Niger          | Moov Africa                               | `29`          | `MOOV AFRICA NIGER`            | USSD Push                       | `/v01/straight/checkout-invoice/create`      | --  |
| RD Congo       | Orange Money                              | `34`          | `ORANGE RDC CONGO`             | Redirection LigdiCash           | `/v01/straight/checkout-invoice/create`      | 10  |
| RD Congo       | Vodacom (M-Pesa)                          | `36`          | `VODACOM RDC CONGO`            | USSD Push                       | `/v01/straight/checkout-invoice/create`      | 10  |
| RD Congo       | Airtel Money                              | `37`          | `AIRTEL RDC CONGO`             | USSD Push                       | `/v01/straight/checkout-invoice/create`      | 10  |
| RD Congo       | Africell Money                            | `38`          | `AFRICELL RDC CONGO`           | USSD Push                       | `/v01/straight/checkout-invoice/create`      | 100 |
| Sénégal        | Orange Money                              | `31`          | `ORANGE SENEGAL`               | Redirection LigdiCash           | `/v01/straight/checkout-invoice/create`      | --  |
| Sénégal        | Wave                                      | `39`          | `WAVE SENEGAL`                 | Redirection LigdiCash           | `/v01/straight/checkout-invoice/create`      | --  |
| Sénégal        | Free                                      | `32`          | `FREE SENEGAL`                 | Redirection LigdiCash           | `/v01/straight/checkout-invoice/create`      | --  |
| Togo           | Moov Africa                               | `4`           | `MOOV TOGO`                    | USSD Push                       | `/v01/straight/checkout-invoice/create`      | 100 |
| Togo           | YAS (Mixx by Yas)                         | `3`           | `YAS TOGO`                     | USSD Push                       | `/v01/straight/checkout-invoice/create`      | 100 |
| —              | Cartes bancaires (Visa, MasterCard, AmEx) | `35`          | `VISA, MasterCard, AmEx, Etc.` | 3D Secure (page de paiement)    | `/v01/redirect/checkout-invoice/create`      | --  |

Le montant minimum est exprimé en XOF. Le maximum dépend des limites contractuelles de chaque opérateur — contactez votre interlocuteur LigdiCash si besoin.

## Légende des modes de validation

| Mode                      | Description                                                                                                                         | Endpoint                                                                                                                 |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **OTP USSD**              | Le client génère un OTP en composant un code USSD avant la soumission                                                               | `/v01/straight/checkout-invoice/create`                                                                                  |
| **USSD Push**             | L'opérateur pousse un menu USSD au client après la soumission                                                                       | `/v01/straight/checkout-invoice/create`                                                                                  |
| **USSD guidé**            | L'opérateur envoie un SMS contenant un code USSD que le client compose pour valider                                                 | `/v01/straight/checkout-invoice/create`                                                                                  |
| **OTP SMS**               | Après la 1ʳᵉ requête, un OTP est envoyé par SMS au client. Le client le communique au marchand qui soumet une 2ᵉ requête avec l'OTP | `/v01/straight/checkout-invoice/create` (cas général) ou `/v02/debitotp` + `/v02/debitwallet/withotp` (Wallet LigdiCash) |
| **Redirection LigdiCash** | LigdiCash retourne une URL vers une page de paiement LigdiCash dédiée, avec numéro prérempli et opérateur pré-filtré via `customer` | `/v01/straight/checkout-invoice/create`                                                                                  |
| **Redirection opérateur** | LigdiCash retourne une URL vers le portail web de l'opérateur ; le client s'y authentifie                                           | `/v01/straight/checkout-invoice/create`                                                                                  |

Voir la page [Modes de validation](/api-paiement/payin-sans-redirect/modes-validation) pour le détail des flux et les exemples d'UX.

## Indicatifs téléphoniques par pays

| Pays           | Indicatif | Format type     |
| -------------- | --------- | --------------- |
| Bénin          | +229      | `229XXXXXXXX`   |
| Burkina Faso   | +226      | `22670XXXXXXX`  |
| Côte d'Ivoire  | +225      | `225XXXXXXXXXX` |
| Guinée Conakry | +224      | `224XXXXXXXXX`  |
| Mali           | +223      | `22370XXXXXXX`  |
| Niger          | +227      | `22790XXXXXXX`  |
| RD Congo       | +243      | `243XXXXXXXXX`  |
| Sénégal        | +221      | `22170XXXXXXX`  |
| Togo           | +228      | `228XXXXXXXX`   |

<Warning>
  Les formats sont fournis à titre indicatif. Toujours envoyer le numéro **sans `+` ni espaces**. Le préfixe exact accepté par chaque opérateur (Vodacom 81-82, Orange 85, Airtel 97-98, etc. en RDC par exemple) est précisé sur la page d'intégration correspondante quand connu.
</Warning>

## Pages d'intégration par opérateur

### Bénin

* [Moov Africa — Bénin](/api-paiement/payin-sans-redirect/operateurs/moov-benin)
* [MTN Mobile Money — Bénin](/api-paiement/payin-sans-redirect/operateurs/mtn-benin)

### Burkina Faso

* [Orange Money — Burkina Faso](/api-paiement/payin-sans-redirect/operateurs/orange-burkina)
* [Moov Africa — Burkina Faso](/api-paiement/payin-sans-redirect/operateurs/moov-burkina)

### Côte d'Ivoire

* [Orange Money — Côte d'Ivoire](/api-paiement/payin-sans-redirect/operateurs/orange-cote-divoire)
* [Moov Africa — Côte d'Ivoire](/api-paiement/payin-sans-redirect/operateurs/moov-cote-divoire)
* [MTN Mobile Money — Côte d'Ivoire](/api-paiement/payin-sans-redirect/operateurs/mtn-cote-divoire)

### Guinée Conakry

* [Orange Money — Guinée Conakry](/api-paiement/payin-sans-redirect/operateurs/orange-guinee)
* [MTN Mobile Money — Guinée Conakry](/api-paiement/payin-sans-redirect/operateurs/mtn-guinee)

### Mali

* [Orange Money — Mali](/api-paiement/payin-sans-redirect/operateurs/orange-mali)

### Niger

* [Airtel — Niger](/api-paiement/payin-sans-redirect/operateurs/airtel-niger)
* [Zamani — Niger](/api-paiement/payin-sans-redirect/operateurs/zamani-niger)
* [Moov Africa — Niger](/api-paiement/payin-sans-redirect/operateurs/moov-niger)

### RD Congo

* [Orange Money — RD Congo](/api-paiement/payin-sans-redirect/operateurs/orange-rdc)
* [Vodacom — RD Congo](/api-paiement/payin-sans-redirect/operateurs/vodacom-rdc)
* [Airtel — RD Congo](/api-paiement/payin-sans-redirect/operateurs/airtel-rdc)
* [Africell — RD Congo](/api-paiement/payin-sans-redirect/operateurs/africell-rdc)

### Sénégal

* [Orange Money — Sénégal](/api-paiement/payin-sans-redirect/operateurs/orange-senegal)
* [Wave — Sénégal](/api-paiement/payin-sans-redirect/operateurs/wave-senegal)
* [Free — Sénégal](/api-paiement/payin-sans-redirect/operateurs/free-senegal)

### Togo

* [Moov Africa — Togo](/api-paiement/payin-sans-redirect/operateurs/moov-togo)
* [YAS — Togo](/api-paiement/payin-sans-redirect/operateurs/yas-togo)

### Wallet

* [Wallet LigdiCash](/api-paiement/payin-sans-redirect/operateurs/wallet-ligdicash)

### Visa (et autres cartes bancaires : MasterCard, AmEx)

* [Introduction aux cartes bancaires](/api-paiement/cartes-visa/introduction)
* [Activation des cartes sur votre projet](/api-paiement/cartes-visa/activation)
* [Flux de paiement par carte](/api-paiement/cartes-visa/flux-paiement)
* [3D Secure](/api-paiement/cartes-visa/3d-secure)


# Changelog
Source: https://developers.ligdicash.com/ressources/changelog

Historique des changements de l'API LigdiCash et de la documentation officielle.

Ce changelog retrace les évolutions significatives de l'API LigdiCash et de cette documentation. Les changements sont classés par date, du plus récent au plus ancien.

<Note>
  Ce changelog est maintenu par l'équipe LigdiCash. Si vous identifiez un changement manquant ou une incohérence, contactez [developper@ligdicash.com](mailto:developper@ligdicash.com).
</Note>

## Comment lire ce changelog

Chaque entrée précise :

* **Date** — mois et année de la modification
* **Type** — nature du changement (voir légende ci-dessous)
* **Description** — ce qui a changé et pourquoi

### Légende des types

| Type            | Signification                                              |
| --------------- | ---------------------------------------------------------- |
| `Nouveau`       | Nouvelle fonctionnalité ou endpoint ajouté                 |
| `Modifié`       | Comportement existant modifié (non cassant)                |
| `Déprécié`      | Fonctionnalité encore disponible mais amenée à disparaître |
| `Supprimé`      | Fonctionnalité retirée                                     |
| `Corrigé`       | Correction d'un bug ou d'un comportement incorrect         |
| `Sécurité`      | Correctif ou renforcement lié à la sécurité                |
| `Documentation` | Mise à jour de la documentation sans changement d'API      |

***

## 2026

### Mai 2026

| Type            | Description                          |
| --------------- | ------------------------------------ |
| `Documentation` | Refonte complète de la documentation |

***

## À venir

Les prochaines évolutions prévues seront annoncées ici avant leur déploiement. Pour être notifié des changements d'API, contactez votre Partner Manager.

Prochainement :

* **Forum développeurs** — espace communautaire pour poser vos questions, partager vos retours d'intégration et suivre les annonces LigdiCash.
* **Page de statut** — suivi en temps réel de la disponibilité des services LigdiCash et des opérateurs.


# FAQ
Source: https://developers.ligdicash.com/ressources/faq

Questions fréquentes sur l'intégration LigdiCash — technique, compte, business.

Cette page regroupe les questions les plus fréquentes posées par les développeurs et les équipes business qui intègrent LigdiCash. Pour aller plus loin, chaque réponse renvoie vers la documentation détaillée.

## Compte et accès

<AccordionGroup>
  <Accordion title="Comment créer un compte marchand LigdiCash ?">
    Téléchargez l'application mobile LigdiCash (App Store / Play Store) et créez votre compte depuis l'app. Vous devrez ensuite fournir les documents requis dans le cadre du KYC et signer un contrat de partenariat avec votre Partner Manager.

    Voir [Protocole d'intégration](/essentials/protocole-integration) pour le détail des étapes.
  </Accordion>

  <Accordion title="Comment obtenir mes clés API ?">
    Vous n'avez pas à créer vous-même votre projet API. Après la signature du contrat, c'est l'**équipe technique LigdiCash** qui crée et active votre projet. Vos clés `Apikey` et `API_TOKEN` sont ensuite disponibles dans le Dashboard.

    Voir [Projet API](/concepts/projet-api) et [Authentification](/concepts/authentification).
  </Accordion>

  <Accordion title="Peut-on avoir plusieurs projets API sur un même compte ?">
    Oui, mais chaque projet API fait l'objet d'un **contrat distinct**. Si vous avez plusieurs applications ou pays à couvrir, discutez-en avec votre Partner Manager avant de démarrer une nouvelle intégration.
  </Accordion>

  <Accordion title="Existe-t-il un environnement sandbox pour tester sans payer ?">
    LigdiCash ne propose pas d'environnement sandbox distinct à ce jour. Les tests se font en production avec de vraies transactions. Renseignez-vous auprès de votre Partner Manager pour connaître les modalités de test disponibles.

    Contact : [developper@ligdicash.com](mailto:developper@ligdicash.com)
  </Accordion>
</AccordionGroup>

## Intégration technique

<AccordionGroup>
  <Accordion title="Quelle est la différence entre payin avec redirection et payin sans redirection ?">
    * **Avec redirection** : le client est envoyé vers une page de paiement hébergée par LigdiCash. Intégration simple, UI gérée par LigdiCash, mais moins de contrôle.
    * **Sans redirection** : le marchand gère entièrement l'interface et soumet le paiement via API. Plus de contrôle sur l'UX, mais intégration plus complexe et spécifique à chaque opérateur.

    Voir [Vue d'ensemble de l'API de paiement](/api-paiement/vue-ensemble) pour le tableau de décision.
  </Accordion>

  <Accordion title="Puis-je afficher la page de paiement dans une iframe ?">
    Non. LigdiCash bloque l'affichage de sa page dans une iframe. Vous devez ouvrir le lien dans le même onglet, un nouvel onglet, un popup, ou une WebView native (applications mobiles).

    Voir [Pièges courants du payin redirect](/api-paiement/payin-redirect/pieges-courants).
  </Accordion>

  <Accordion title="Pourquoi le champ customer doit-il rester vide dans le payin redirect ?">
    Si vous renseignez un numéro de téléphone dans `customer`, LigdiCash filtre la page de paiement pour n'afficher que les opérateurs correspondant à ce numéro, masquant les autres options. Laissez `customer: ""` pour que votre client puisse choisir librement son opérateur.

    Voir [Pièges courants du payin redirect](/api-paiement/payin-redirect/pieges-courants).
  </Accordion>

  <Accordion title="Mon popup de paiement est bloqué par le navigateur. Comment contourner cela ?">
    Les navigateurs bloquent les popups ouverts en dehors d'un événement utilisateur direct. Le pattern recommandé est d'ouvrir `window.open('about:blank')` au moment du clic utilisateur (avant le `await fetch`), puis de naviguer vers l'URL de paiement une fois la réponse reçue.

    Voir [Rediriger le client](/api-paiement/payin-redirect/rediriger-client).
  </Accordion>

  <Accordion title="Comment identifier ma transaction dans le callback si le token change ?">
    Le `token` présent dans le callback est différent du token retourné à la création. Ne vous y fiez pas pour retrouver votre commande. La méthode fiable est d'injecter votre propre identifiant de commande dans `custom_data` à la création, puis de le retrouver via `keyof_customdata === "transaction_id"` dans le callback.

    Voir [Le pattern transaction\_id](/concepts/transaction-id-pattern) et [Parser custom\_data](/api-paiement/callback/parser-custom-data).
  </Accordion>

  <Accordion title="Pourquoi mon callback est-il appelé deux fois pour une même transaction ?">
    C'est le comportement normal de LigdiCash. Pour chaque événement, deux requêtes POST sont envoyées à votre URL callback : une en `application/x-www-form-urlencoded` et une en `application/json`. Le contenu est identique. Implémentez une logique de déduplication (vérifier si la transaction est déjà traitée en base avant d'agir).

    Voir [Idempotence du callback](/api-paiement/callback/idempotence).
  </Accordion>

  <Accordion title="Comment sécuriser mon endpoint de callback ?">
    Ne faites jamais confiance au payload reçu sans vérification. N'importe qui connaissant l'URL de votre callback peut envoyer un faux payload. Après réception, re-vérifiez toujours le statut en appelant l'endpoint `confirm` avec le token que vous avez stocké lors de la création de la facture.

    Voir [Sécurisation du callback](/api-paiement/callback/securisation).
  </Accordion>

  <Accordion title="L'endpoint withdrawal/confirm est-il GET ou POST ?">
    L'endpoint `GET /pay/v01/withdrawal/confirm/` s'appelle en **GET** avec le token en query string. Il y a une incohérence dans la documentation actuelle.

    Voir [Vérifier le statut d'un payout](/api-paiement/payout/verifier-statut).
  </Accordion>

  <Accordion title="Quelle est la différence entre payout vers wallet et payout mobile money direct ?">
    * **`/withdrawal/create`** : envoie vers le wallet LigdiCash du destinataire. L'argent peut rester dans le wallet (`top_up_wallet: 1`) ou être automatiquement viré vers son mobile money lié (`top_up_wallet: 0`).
    * **`/straight/payout`** : envoie directement vers le numéro mobile money, sans wallet intermédiaire. Plus lent, mais ne nécessite pas que le destinataire ait un compte LigdiCash.

    Voir [Payout — Introduction](/api-paiement/payout/introduction).
  </Accordion>

  <Accordion title="Comment gérer les différents modes de validation selon les opérateurs ?">
    Il existe quatre modes selon l'opérateur :

    * **OTP USSD** — le client génère un OTP en composant un code USSD avant que vous ne soumettiez. Une seule requête API.
    * **USSD Push** — vous soumettez avec `otp: ""`, l'opérateur envoie un écran USSD push au client qui valide avec son PIN. Une seule requête API.
    * **USSD guidé** — vous soumettez avec `otp: ""`, l'opérateur envoie un SMS avec les instructions et un code USSD à composer. Une seule requête API.
    * **OTP SMS** — vous soumettez d'abord avec `otp: ""`, l'opérateur envoie un OTP par SMS, vous re-soumettez avec l'OTP saisi. Deux requêtes API.

    Voir [Modes de validation](/api-paiement/payin-sans-redirect/modes-validation) pour le détail des flux et des UX recommandées.
  </Accordion>
</AccordionGroup>

## Sécurité

<AccordionGroup>
  <Accordion title="Comment protéger mes clés API ?">
    * Ne jamais exposer `Apikey` et `Auth Token` côté client (navigateur, application mobile).
    * Toujours faire les appels LigdiCash depuis votre backend.
    * Utiliser des variables d'environnement, jamais des constantes dans le code source.
    * Régénérer les clés immédiatement en cas de compromission depuis le Dashboard.

    Voir [Architecture recommandée](/guides/architecture-recommandee).
  </Accordion>

  <Accordion title="Que faire si mes clés API sont compromises ?">
    Connectez-vous au Dashboard LigdiCash et régénérez vos clés immédiatement. Mettez à jour vos variables d'environnement en production. Auditez vos logs pour détecter des transactions non autorisées. Contactez [developper@ligdicash.com](mailto:developper@ligdicash.com) si vous suspectez une fraude.
  </Accordion>

  <Accordion title="Comment éviter les doublons de transaction ?">
    Deux mécanismes combinés :

    1. **Déduplication du callback** : avant de traiter un callback, vérifiez en base si le `transaction_id` a déjà été traité.
    2. **Re-vérification systématique** : appelez l'endpoint `confirm` avec le token de création pour valider l'état réel, plutôt que de vous fier au payload callback reçu.

    Voir [Idempotence du callback](/api-paiement/callback/idempotence) et [Sécurisation du callback](/api-paiement/callback/securisation).
  </Accordion>
</AccordionGroup>

## Business et opérationnel

<AccordionGroup>
  <Accordion title="Quels pays et opérateurs sont supportés ?">
    LigdiCash couvre le Burkina Faso, la Côte d'Ivoire, le Mali, le Niger, le Bénin, le Togo, le Sénégal, la Guinée Conakry et la RD Congo. Les opérateurs supportés incluent Orange Money, Moov Africa, MTN Mobile Money, Wave, Airtel Money, Vodacom, Africell, YAS, Zamani et le Wallet LigdiCash.

    Voir [Opérateurs supportés](/reference/operateurs-supportes) pour le tableau complet.
  </Accordion>

  <Accordion title="Quelle est la devise utilisée dans l'API ?">
    L'API LigdiCash utilise **toujours le XOF**, quelle que soit la devise locale du pays du client. Cela vaut également pour la RD Congo et la Guinée Conakry, dont les devises nationales ne sont pas le XOF — LigdiCash gère la conversion en interne. Les montants sont toujours des **entiers** (le XOF n'a pas de décimales).

    Pour des devises étrangères comme le dollar ou l'euro, c'est au marchand d'effectuer la conversion en XOF avant d'appeler l'API.

    Voir [Devises et montants](/concepts/devises-montants).
  </Accordion>

  <Accordion title="Quels sont les montants minimum et maximum par transaction ?">
    Les limites varient selon l'opérateur et le pays. Contactez votre Partner Manager ou consultez le Dashboard pour les limites en vigueur sur votre compte.

    Voir [Opérateurs supportés](/reference/operateurs-supportes).
  </Accordion>

  <Accordion title="Quels sont les délais de virement vers mon compte bancaire ?">
    Les conditions de reversement (fréquence, délai, seuil minimum) sont définies dans votre contrat de partenariat. Contactez votre Partner Manager pour les détails.
  </Accordion>

  <Accordion title="Comment intégrer LigdiCash sur une boutique WooCommerce ?">
    Un plugin officiel est disponible. Installez-le manuellement depuis votre Dashboard WooCommerce, configurez vos clés API et le comportement du callback, et vous êtes prêt.

    Voir [SDK WordPress / WooCommerce](/sdk/wordpress-woocommerce).
  </Accordion>

  <Accordion title="Existe-t-il des SDK officiels pour mon langage ?">
    Oui. LigdiCash propose des SDK officiels pour PHP, Python, JavaScript/Node.js, Dart/Flutter et un plugin WooCommerce.

    Voir [Vue d'ensemble des SDK](/sdk/vue-ensemble).
  </Accordion>

  <Accordion title="Comment passer en production après mes tests ?">
    Le passage en production suit un processus formel :

    1. Vous complétez votre intégration et vos tests sur le compte temporaire.
    2. L'équipe technique LigdiCash effectue des **tests de validation** de votre intégration.
    3. Un **procès-verbal (PV) est signé** entre vous et LigdiCash pour officialiser la fin de l'intégration.
    4. L'équipe technique active votre projet de production. Seules vos clés changent — le code reste identique.

    Consultez aussi la checklist technique pour préparer votre intégration avant la validation.

    Voir [Checklist de mise en production](/guides/checklist-production).
  </Accordion>
</AccordionGroup>


# Glossaire
Source: https://developers.ligdicash.com/ressources/glossaire

Définitions des termes techniques et métier utilisés dans la documentation LigdiCash.

Ce glossaire regroupe les termes que vous rencontrerez dans la documentation LigdiCash. Chaque définition est reliée aux pages où le concept est développé en détail.

## A–C

<AccordionGroup>
  <Accordion title="Apikey">
    Clé d'identification de votre projet API. Elle est transmise dans le header `Apikey` de chaque requête. Elle identifie le projet, pas l'utilisateur. À ne pas confondre avec le `Auth Token`.

    Voir [Authentification](/concepts/authentification).
  </Accordion>

  <Accordion title="Auth Token (Bearer)">
    Jeton d'authentification du compte marchand. Il est transmis dans le header `Authorization: Bearer {AUTH_TOKEN}`. Associé à l'`Apikey`, il forme la paire d'identification requise sur tous les endpoints.

    Voir [Authentification](/concepts/authentification).
  </Accordion>

  <Accordion title="Callback (webhook)">
    Requête HTTP POST envoyée automatiquement par LigdiCash vers votre serveur lorsqu'une transaction change de statut. LigdiCash envoie **deux requêtes** à chaque événement : une en `application/x-www-form-urlencoded` et une en `application/json`. Pensez à dédupliquer.

    Voir [Introduction au callback](/api-paiement/callback/introduction).
  </Accordion>

  <Accordion title="Checkout invoice">
    Facture de paiement créée côté LigdiCash lors de l'initiation d'un payin. Elle est identifiée par un `token` unique et contient les détails de la transaction (montant, opérateur, store, custom\_data). Le terme apparaît dans les endpoints (`/checkout-invoice/create`, `/checkout-invoice/confirm`).
  </Accordion>

  <Accordion title="custom_data">
    Tableau de métadonnées libres que vous attachez à une transaction lors de sa création. Il est retourné tel quel dans le callback, ce qui vous permet de retrouver votre propre identifiant de commande. LigdiCash y ajoute ses propres champs (`logfile`, `id_invoice`). Peut prendre trois formes dans le callback : tableau peuplé, `[]` (vide), ou `""` (chaîne vide).

    Voir [Parser custom\_data](/api-paiement/callback/parser-custom-data).
  </Accordion>
</AccordionGroup>

## D–L

<AccordionGroup>
  <Accordion title="external_id">
    Champ présent dans les requêtes payin sans redirection. Dans la plupart des cas, il doit rester vide (`""`). Ne pas confondre avec `transaction_id` que vous définissez dans `custom_data`.
  </Accordion>

  <Accordion title="Invoice">
    Voir **Checkout invoice**.
  </Accordion>

  <Accordion title="keyof_customdata / valueof_customdata">
    Structure d'un élément du tableau `custom_data`. Chaque entrée est un objet `{ keyof_customdata: "clé", valueof_customdata: "valeur" }`. Pour retrouver votre identifiant de commande, filtrez sur `keyof_customdata === "transaction_id"`.

    Voir [Parser custom\_data](/api-paiement/callback/parser-custom-data).
  </Accordion>
</AccordionGroup>

## M–O

<AccordionGroup>
  <Accordion title="Marchand">
    Entreprise ou développeur intégrant l'API LigdiCash pour accepter ou émettre des paiements. Votre compte marchand est géré depuis le [Dashboard LigdiCash](https://client.ligdicash.com).
  </Accordion>

  <Accordion title="Mobile money">
    Service de paiement mobile proposé par les opérateurs téléphoniques (Orange Money, Moov Africa, MTN, Wave, etc.). LigdiCash est un agrégateur : il abstrait tous ces opérateurs derrière une API unique.
  </Accordion>

  <Accordion title="operator_id">
    Identifiant numérique retourné par l'API dans les réponses et callbacks pour désigner l'opérateur utilisé (ex : `11` pour Orange Burkina). Utile pour le logging et la réconciliation. Ne s'envoie pas dans les requêtes.

    Voir [Opérateurs supportés](/reference/operateurs-supportes).
  </Accordion>

  <Accordion title="operator_name">
    Nom lisible de l'opérateur retourné par l'API (ex : `"ORANGE BURKINA"`). Toujours en majuscules dans les réponses LigdiCash.

    Voir [Opérateurs supportés](/reference/operateurs-supportes).
  </Accordion>

  <Accordion title="OTP (One-Time Password)">
    Code à usage unique servant à autoriser une transaction de payin sans redirection. Selon l'opérateur, il est généré par le client via menu USSD, envoyé par SMS, ou remplacé par une approbation directe sur l'app mobile money.

    Voir [Modes de validation](/api-paiement/payin-sans-redirect/modes-validation).
  </Accordion>
</AccordionGroup>

## P–R

<AccordionGroup>
  <Accordion title="Payin">
    Opération de collecte : le client paie le marchand. LigdiCash propose deux modes — avec redirection (le client est renvoyé vers une page de paiement hébergée) et sans redirection (le paiement est initié programmatiquement via OTP ou approbation).

    Voir [Vue d'ensemble de l'API de paiement](/api-paiement/vue-ensemble).
  </Accordion>

  <Accordion title="Payin avec redirection">
    Mode de payin où le client est redirigé vers une page de paiement hébergée par LigdiCash. L'intégration est simple mais impose des contraintes : pas d'iframe, `customer` vide, gestion des popups.

    Voir [Payin avec redirection — Introduction](/api-paiement/payin-redirect/introduction).
  </Accordion>

  <Accordion title="Payin sans redirection">
    Mode de payin où le marchand gère l'interface et soumet l'OTP via API. Plus de contrôle sur l'UX, mais une intégration plus complexe et spécifique à chaque opérateur.

    Voir [Payin sans redirection — Introduction](/api-paiement/payin-sans-redirect/introduction).
  </Accordion>

  <Accordion title="Payout">
    Opération de décaissement : le marchand envoie de l'argent à un client ou partenaire. Deux variantes : vers le wallet LigdiCash du destinataire (`/withdrawal/create`) ou directement vers son mobile money (`/straight/payout`).

    Voir [Payout — Introduction](/api-paiement/payout/introduction).
  </Accordion>

  <Accordion title="Projet API">
    Entité créée dans le Dashboard LigdiCash qui regroupe une `Apikey` et un `Auth Token`. Un compte marchand peut avoir plusieurs projets API (un par application, par pays, etc.).

    Voir [Créer un projet API](/concepts/projet-api).
  </Accordion>

  <Accordion title="response_code">
    Code de retour présent dans toutes les réponses API LigdiCash. `"00"` = succès, `"01"` = échec. En cas d'échec, le champ `wiki` contient une URL vers la description détaillée.

    Voir [Codes de réponse et statuts](/concepts/codes-reponse-statuts).
  </Accordion>
</AccordionGroup>

## S–T

<AccordionGroup>
  <Accordion title="Statut de transaction">
    État courant d'une transaction. Valeurs possibles : `Completed` (confirmée), `Pending` (en attente), `Cancelled` (annulée). À récupérer via l'endpoint `confirm` ou via le callback.

    Voir [Cycle de vie d'une transaction](/concepts/cycle-vie-transaction).
  </Accordion>

  <Accordion title="Store">
    Objet représentant votre boutique dans une requête LigdiCash. Contient `name`, `website_url`, `logo_url`, et `return_url`. Apparaît dans le body des requêtes de création de facture.
  </Accordion>

  <Accordion title="token (création)">
    Identifiant de transaction retourné par LigdiCash à la création d'une facture. Sert à appeler l'endpoint `confirm` pour vérifier le statut. **Ce token est différent du token présent dans le callback** — ne pas les confondre.

    Voir [Tokens et identifiants](/concepts/tokens-et-identifiants).
  </Accordion>

  <Accordion title="token (callback)">
    Valeur du champ `token` reçue dans le payload callback. Elle est différente du token de création et ne doit pas être utilisée pour identifier la transaction. Utilisez toujours votre `transaction_id` stocké en base, ou re-vérifiez avec le token de création.

    Voir [Sécurisation du callback](/api-paiement/callback/securisation).
  </Accordion>

  <Accordion title="top_up_wallet">
    Paramètre de l'endpoint `/withdrawal/create`. Détermine si l'argent reste dans le wallet LigdiCash du client (`1`) ou est automatiquement viré vers son mobile money lié (`0`).

    Voir [Payout vers wallet LigdiCash](/api-paiement/payout/vers-wallet-ligdicash).
  </Accordion>

  <Accordion title="transaction_id">
    Identifiant de commande que **vous** générez côté marchand et que vous injectez dans `custom_data` à la création. C'est la méthode recommandée pour corréler une transaction LigdiCash avec votre système de commandes — fiable dans tous les flux, y compris en cas de retry callback.

    Voir [Le pattern transaction\_id](/concepts/transaction-id-pattern).
  </Accordion>
</AccordionGroup>

## U–Z

<AccordionGroup>
  <Accordion title="USSD">
    Protocole de messagerie courte utilisé par les opérateurs mobile money pour déclencher des actions depuis le téléphone (ex : `#144*82#` pour Orange Burkina). En mode payin sans redirection OTP-USSD, le client compose le code USSD sur son téléphone pour obtenir son OTP avant que vous ne soumettiez la transaction.
  </Accordion>

  <Accordion title="Wallet LigdiCash">
    Portefeuille électronique interne à LigdiCash, distinct des wallets des opérateurs mobile money. Le wallet LigdiCash peut recevoir des payouts via `/withdrawal/create` et est lié à un compte client LigdiCash.

    Voir [Payout vers wallet LigdiCash](/api-paiement/payout/vers-wallet-ligdicash).
  </Accordion>

  <Accordion title="wiki (champ)">
    Champ présent dans les réponses d'erreur de l'API LigdiCash. Contient une URL vers une page listant les sous-codes d'erreur spécifiques à l'endpoint appelé. À fetcher programmatiquement pour obtenir une description lisible de l'erreur.

    Voir [Le champ wiki](/erreurs/champ-wiki).
  </Accordion>

  <Accordion title="XOF (Franc CFA BCEAO)">
    Devise utilisée par LigdiCash pour les transactions en Afrique de l'Ouest (Burkina Faso, Mali, Niger, Bénin, Togo, Côte d'Ivoire, Sénégal, Guinée-Bissau). Le XOF n'a pas de décimales — les montants sont toujours des entiers.

    Voir [Devises et montants](/concepts/devises-montants).
  </Accordion>
</AccordionGroup>


# Support
Source: https://developers.ligdicash.com/ressources/support

Contacter l'équipe LigdiCash — canaux disponibles, contacts par pays, et comment bien rapporter un problème.

Vous avez une question technique, un problème d'intégration ou besoin d'accéder à votre compte ? Cette page liste les canaux disponibles et vous guide pour obtenir une réponse rapide.

## Canaux de support

<Warning>
  **Canal privilégié — Groupe Teams d'intégration** : si LigdiCash vous a ajouté à un groupe Microsoft Teams dédié à votre intégration, **utilisez ce groupe en priorité** pour toutes vos questions techniques. C'est le canal le plus rapide pour obtenir une réponse de l'équipe LigdiCash pendant votre phase d'intégration.
</Warning>

<CardGroup>
  <Card title="Support technique" icon="envelope" href="mailto:developper@ligdicash.com">
    Pour les problèmes d'API, les erreurs de transaction et les questions d'intégration.
    **[developper@ligdicash.com](mailto:developper@ligdicash.com)**
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://client.ligdicash.com">
    Gestion de votre compte, projets API, clés, et historique des transactions.
    **client.ligdicash.com**
  </Card>
</CardGroup>

## Contacts par pays

| Pays           | Contact            | Email                                                                       |
| -------------- | ------------------ | --------------------------------------------------------------------------- |
| Burkina Faso   | Mariam Koné        | [mariam.kone@ligdicash.com](mailto:mariam.kone@ligdicash.com)               |
| Côte d'Ivoire  | Ilaria Ouédraogo   | [ilaria.ouedraogo@ligdicash.com](mailto:ilaria.ouedraogo@ligdicash.com)     |
| Mali           | Hénoc Belemnegré   | [henoc.belemgnegre@ligdicash.com](mailto:henoc.belemgnegre@ligdicash.com)   |
| Niger          | Chérifatou Harouna | [cherifatou.harouna@ligdicash.com](mailto:cherifatou.harouna@ligdicash.com) |
| Sénégal        | Lamine Gassama     | [lamine.gassama@ligdicash.com](mailto:lamine.gassama@ligdicash.com)         |
| Togo           | Inoussa Ouédraogo  | [inoussa.ouedraogo@ligdicash.com](mailto:inoussa.ouedraogo@ligdicash.com)   |
| Guinée Conakry | Sabine Traoré      | [sabine.traore@ligdicash.com](mailto:sabine.traore@ligdicash.com)           |
| Bénin          | Mariam Koné        | [mariam.kone@ligdicash.com](mailto:mariam.kone@ligdicash.com)               |
| RD Congo       | Richard Muteba     | [richard.muteba@ligdicash.com](mailto:richard.muteba@ligdicash.com)         |
| Tous les pays  | Support général    | [developper@ligdicash.com](mailto:developper@ligdicash.com)                 |

<Note>
  Pour toute question commerciale (tarifs, contrat, remboursement, limites de transaction), votre Partner Manager est l'interlocuteur privilégié.
</Note>

## Comment bien rapporter un problème technique

Un bon rapport permet à l'équipe de reproduire et résoudre le problème rapidement. Incluez systématiquement :

<Steps>
  <Step title="L'endpoint concerné">
    Exemple : `POST /pay/v01/redirect/checkout-invoice/create`
  </Step>

  <Step title="La requête complète (sans clés réelles)">
    Remplacez vos clés par `{API_KEY}` et `{AUTH_TOKEN}`. Incluez les headers et le body JSON.
  </Step>

  <Step title="La réponse reçue">
    Collez la réponse JSON complète, y compris `response_code`, `message`, et le champ `wiki` si présent.
  </Step>

  <Step title="Le comportement attendu vs observé">
    Décrivez clairement ce que vous attendiez et ce que vous avez obtenu à la place.
  </Step>

  <Step title="L'horodatage et l'environnement">
    Date et heure de la requête (avec timezone), nom du projet API (sans clé), pays et opérateur ciblé.
  </Step>
</Steps>

<Tip>
  Consultez d'abord la page [Erreurs courantes](/erreurs/erreurs-courantes) et le [Champ wiki](/erreurs/champ-wiki) — beaucoup de problèmes courants y sont documentés avec la résolution.
</Tip>

## Informations à ne jamais envoyer au support

<Warning>
  Ne partagez jamais votre `Apikey` ni votre `Auth Token` dans vos échanges email ou tickets support. Si vous avez besoin de partager des détails d'accès, demandez un canal sécurisé à votre Partner Manager. En cas de compromission de clés, régénérez-les immédiatement depuis le Dashboard.
</Warning>


# SDK Dart / Flutter
Source: https://developers.ligdicash.com/sdk/dart-flutter

Installez et utilisez le SDK Dart LigdiCash dans vos applications Flutter iOS et Android.

Le SDK Dart LigdiCash est conçu pour Flutter. Il utilise les conventions Dart — named parameters, enums, `Future<>` — et s'intègre naturellement dans vos widgets et services.

## Installation

Ajoutez la dépendance dans votre `pubspec.yaml` :

```yaml pubspec.yaml theme={null}
dependencies:
  ligdicash: ^1.0.2
```

Puis installez :

```bash theme={null}
flutter pub get
```

**Prérequis :** Dart SDK ≥ 3.4.1 / Flutter ≥ 3.x.

## Initialisation

```dart Dart theme={null}
import 'package:ligdicash/ligdicash.dart';

final client = Ligdicash(
  apikey: '{API_KEY}',
  authToken: '{AUTH_TOKEN}',
  platform: PlatformType.live,
);
```

Obtenez votre `apikey` et votre `authToken` depuis le [dashboard LigdiCash](https://dashboard.ligdicash.com) en créant un projet API. Stockez-les dans vos variables d'environnement, jamais en dur dans le code Flutter.

***

## Payin avec redirection

Le client est redirigé vers la page de paiement hébergée par LigdiCash dans une WebView. C'est le flux recommandé sur mobile.

```dart Dart theme={null}
// 1. Créer la facture
final invoice = client.Invoice(
  currency: 'xof',
  description: 'Commande #ORD-20240512',
  customerFirstname: 'Amadou',
  customerLastname: 'Ouédraogo',
  customerEmail: 'amadou@exemple.com',
  storeName: 'MaSuperBoutique',
  storeWebsiteUrl: 'https://masuperboutique.com',
);

// 2. Ajouter les articles
invoice.addItem(
  name: 'Chemise kente',
  description: 'Taille M',
  quantity: 2,
  unitPrice: 15000,
);
invoice.addItem(
  name: 'Frais de livraison',
  description: '',
  quantity: 1,
  unitPrice: 1500,
);

// 3. Lancer le paiement
final response = await invoice.payWithRedirection(
  returnUrl: 'https://masuperboutique.com/commande/succes',
  cancelUrl: 'https://masuperboutique.com/commande/annulation',
  callbackUrl: 'https://backend.masuperboutique.com/ligdicash/callback',
  customData: {'transaction_id': 'ORD-20240512'},
);

// 4. Ouvrir la WebView avec l'URL de paiement
final paymentUrl = response.responseText;
```

<Warning>
  Sur Flutter, ouvrez `paymentUrl` dans une **WebView native** (package `webview_flutter`). Ne jamais l'afficher dans un `WebView` basé sur iframe HTML — LigdiCash le bloque.
</Warning>

<Tip>
  Détectez l'URL de retour (`returnUrl` / `cancelUrl`) dans le callback `onNavigationRequest` de la WebView pour la fermer automatiquement et reprendre le flux de l'application.
</Tip>

<Tip>
  Laissez toujours `customer` absent dans le payin avec redirection. Si vous passez un numéro, LigdiCash filtre la page de paiement pour ne montrer que les opérateurs de ce numéro.
</Tip>

***

## Payin sans redirection

Le client paie directement depuis votre interface Flutter. Vous devez collecter son numéro de téléphone et, selon l'opérateur, son code OTP.

```dart Dart theme={null}
// 1. Créer la facture
final invoice = client.Invoice(
  currency: 'xof',
  description: 'Commande #ORD-20240512',
  customerFirstname: 'Amadou',
  customerLastname: 'Ouédraogo',
  customerEmail: 'amadou@exemple.com',
  storeName: 'MaSuperBoutique',
  storeWebsiteUrl: 'https://masuperboutique.com',
);
invoice.addItem(
  name: 'Chemise kente',
  description: 'Taille M',
  quantity: 2,
  unitPrice: 15000,
);

// 2. Lancer le paiement (avec OTP fourni par le client)
final response = await invoice.payWithoutRedirection(
  otp: '123456',            // Code OTP saisi par le client
  customer: '22670123456',  // Numéro du client, sans + ni espaces
  callbackUrl: 'https://backend.masuperboutique.com/ligdicash/callback',
  customData: {'transaction_id': 'ORD-20240512'},
);

// 3. Stocker le token pour vérification ultérieure
final token = response.token;
```

<Note>
  Le mode OTP varie selon l'opérateur. Par exemple, pour un opérateur en mode USSD, le client génère son OTP sur son téléphone **avant** que vous ne soumetttiez. Pour un opérateur en mode approbation (ex. Moov Africa), envoyez `otp: ''` — le client approuve directement sur son application. Consultez la [page de l'opérateur](/api-paiement/payin-sans-redirect/introduction) concerné.
</Note>

***

## Payout

Envoyez de l'argent vers un client — remboursement, gain, salaire.

### Vers le wallet LigdiCash du client

```dart Dart theme={null}
final withdrawal = client.Withdrawal(
  amount: 5000,
  description: 'Remboursement commande ORD-20240510',
  customer: '22670123456',
);

final response = await withdrawal.send(
  type: WithdrawalType.client,
  toWallet: false,  // false = virement automatique vers le mobile money lié
  callbackUrl: 'https://backend.masuperboutique.com/ligdicash/callback-payout',
  customData: {'transaction_id': 'REFUND-20240512'},
);

final token = response.token;
```

### Directement vers le mobile money

```dart Dart theme={null}
final response = await withdrawal.send(
  type: WithdrawalType.merchant,  // Payout direct, sans wallet intermédiaire
  callbackUrl: 'https://backend.masuperboutique.com/ligdicash/callback-payout',
  customData: {'transaction_id': 'PAY-20240512'},
);
```

<Note>
  `WithdrawalType.client` utilise `POST /pay/v01/withdrawal/create` (via wallet LigdiCash). `WithdrawalType.merchant` utilise `POST /pay/v01/straight/payout` (mobile money direct, plus lent). Voir [Payout — Introduction](/api-paiement/payout/introduction).
</Note>

***

## Vérification de statut

Appelez `getTransaction` avec le token stocké à la **création** (pas le token du callback, qui est différent).

```dart Dart theme={null}
final token = 'eyJ0eXAiOiJ...';  // Token retourné lors de la création

// Payin
final transaction = await client.getTransaction(
  token: token,
  type: TransactionType.payin,
);

// Payout client (withdrawal/create)
// final transaction = await client.getTransaction(
//   token: token,
//   type: TransactionType.clientPayout,
// );

if (transaction.status == 'completed') {
  // Livrer la commande / valider le paiement
} else if (transaction.status == 'pending') {
  // Paiement en cours — relancer dans quelques secondes
} else {
  // Paiement échoué ou annulé
}
```

**Valeurs de `TransactionType` :**

| Valeur                         | Endpoint vérifié                         |
| ------------------------------ | ---------------------------------------- |
| `TransactionType.payin`        | `GET /redirect/checkout-invoice/confirm` |
| `TransactionType.clientPayout` | `GET /withdrawal/confirm`                |

**Champs disponibles sur `transaction` :**

| Propriété      | Type                   | Description                                   |
| -------------- | ---------------------- | --------------------------------------------- |
| `status`       | `String`               | `"completed"`, `"pending"`, `"cancelled"`     |
| `responseCode` | `String`               | `"00"` succès, `"01"` échec                   |
| `amount`       | `double`               | Montant de la transaction                     |
| `operatorId`   | `String`               | Identifiant de l'opérateur                    |
| `operatorName` | `String`               | Nom de l'opérateur                            |
| `customer`     | `String`               | Numéro du client                              |
| `token`        | `String`               | Token de la transaction                       |
| `customData`   | `Map<String, dynamic>` | Données personnalisées envoyées à la création |

<Warning>
  Ne livrez jamais une commande uniquement sur la base d'un callback entrant. Appelez toujours `getTransaction` avec le token stocké à la création pour confirmer le statut côté serveur LigdiCash. Voir [Sécurisation du callback](/api-paiement/callback/securisation).
</Warning>

***

## Gestion des erreurs

```dart Dart theme={null}
try {
  final response = await invoice.payWithRedirection(
    returnUrl: 'https://masuperboutique.com/succes',
    cancelUrl: 'https://masuperboutique.com/annulation',
    callbackUrl: 'https://backend.masuperboutique.com/callback',
    customData: {'transaction_id': 'ORD-20240512'},
  );

  if (response.responseCode != '00') {
    // Erreur retournée par l'API — consultez response.wiki
    debugPrint('Erreur API: ${response.responseText}');
  }
} catch (e) {
  // Erreur réseau ou exception inattendue
  debugPrint('Erreur: $e');
}
```

<Note>
  Vérifiez `response.responseCode` après chaque appel : `"00"` indique un succès, `"01"` une erreur. En cas d'erreur, consultez `response.wiki` pour obtenir l'URL de détail des sous-codes.
</Note>

***

## Liens utiles

* [Guide — Intégration mobile Flutter](/guides/quickstart-mobile)
* [Payin avec redirection — Integration mobile](/api-paiement/payin-redirect/integration-mobile)
* [Payout — Introduction](/api-paiement/payout/introduction)
* [Sécurisation du callback](/api-paiement/callback/securisation)
* [Pattern transaction\_id](/concepts/transaction-id-pattern)
* [Dépôt GitHub ligdicash-dart](https://github.com/Ligdicash/ligdicash-dart)


# SDK JavaScript / TypeScript
Source: https://developers.ligdicash.com/sdk/javascript

Installez et utilisez le SDK JavaScript LigdiCash pour Node.js, TypeScript et NestJS. Types TypeScript inclus.

Le SDK JavaScript LigdiCash fonctionne en Node.js et dans les environnements TypeScript. Tous les appels réseau sont asynchrones (`async/await`). Les types TypeScript sont inclus dans le package.

## Installation

```bash theme={null}
npm install ligdicash
```

**Prérequis :** Node.js. La dépendance `cross-fetch` est installée automatiquement.

## Initialisation

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Ligdicash from "ligdicash";

  const client = new Ligdicash({
    apiKey: "{API_KEY}",
    authToken: "{AUTH_TOKEN}",
    platform: "live",
    baseUrl: "https://app.ligdicash.com",
  });
  ```

  ```javascript JavaScript (CommonJS) theme={null}
  const Ligdicash = require("ligdicash").default;

  const client = new Ligdicash({
    apiKey: "{API_KEY}",
    authToken: "{AUTH_TOKEN}",
    platform: "live",
    baseUrl: "https://app.ligdicash.com",
  });
  ```
</CodeGroup>

Obtenez votre `apiKey` et votre `authToken` depuis le [dashboard LigdiCash](https://dashboard.ligdicash.com) en créant un projet API.

***

## Payin avec redirection

Le client est redirigé vers la page de paiement hébergée par LigdiCash. C'est le flux recommandé pour les boutiques en ligne.

```typescript TypeScript theme={null}
// 1. Créer la facture
const invoice = client.Invoice({
  currency: "xof",
  description: "Commande #ORD-20240512",
  customer_firstname: "Amadou",
  customer_lastname: "Ouédraogo",
  customer_email: "amadou@exemple.com",
  store_name: "MaSuperBoutique",
  store_website_url: "https://masuperboutique.com",
});

// 2. Ajouter les articles
invoice.addItem({ name: "Chemise kente", description: "Taille M", quantity: 2, unit_price: 15000 });
invoice.addItem({ name: "Frais de livraison", description: "", quantity: 1, unit_price: 1500 });

// 3. Lancer le paiement
const response = await invoice.payWithRedirection({
  return_url: "https://masuperboutique.com/commande/succes",
  cancel_url: "https://masuperboutique.com/commande/annulation",
  callback_url: "https://backend.masuperboutique.com/ligdicash/callback",
  custom_data: { transaction_id: "ORD-20240512" },
});

// 4. Rediriger le client
const paymentUrl = response.response_text;
```

<Warning>
  Tous les appels réseau (`payWithRedirection`, `payWithoutRedirection`, `send`, `getTransaction`) retournent une `Promise`. Un `await` manquant provoque une comparaison silencieuse sur un objet `Promise` au lieu du résultat réel.
</Warning>

<Warning>
  Ne jamais ouvrir `paymentUrl` dans une iframe — LigdiCash la bloque. Redirigez dans le même onglet, un nouvel onglet ou un popup. Sur mobile natif, utilisez une WebView.
</Warning>

<Tip>
  **Pattern popup anti-bloqueur :** ouvrez `window.open("about:blank")` au clic utilisateur (avant le `await`), puis naviguez vers `paymentUrl` après réception de la réponse. Cela contourne les bloqueurs de popups navigateur.
</Tip>

***

## Payin sans redirection

Le client paie directement depuis votre interface. Vous devez collecter son numéro de téléphone et, selon l'opérateur, son code OTP.

```typescript TypeScript theme={null}
// 1. Créer la facture
const invoice = client.Invoice({
  currency: "xof",
  description: "Commande #ORD-20240512",
  customer_firstname: "Amadou",
  customer_lastname: "Ouédraogo",
  customer_email: "amadou@exemple.com",
  store_name: "MaSuperBoutique",
  store_website_url: "https://masuperboutique.com",
});
invoice.addItem({ name: "Chemise kente", description: "Taille M", quantity: 2, unit_price: 15000 });

// 2. Lancer le paiement (avec OTP fourni par le client)
const response = await invoice.payWithoutRedirection({
  otp: "123456",            // Code OTP saisi par le client
  customer: "22670123456",  // Numéro du client, sans + ni espaces
  callback_url: "https://backend.masuperboutique.com/ligdicash/callback",
  custom_data: { transaction_id: "ORD-20240512" },
});

// 3. Stocker le token pour vérification ultérieure
const token = response.token;
```

<Note>
  Le mode OTP varie selon l'opérateur. Par exemple, pour un opérateur en mode USSD, le client génère son OTP sur son téléphone **avant** que vous ne soumetttiez. Pour un opérateur en mode approbation (ex. Moov Africa), envoyez `otp: ""` — le client approuve directement sur son application. Consultez la [page de l'opérateur](/api-paiement/payin-sans-redirect/introduction) concerné.
</Note>

***

## Payout

Envoyez de l'argent vers un client — remboursement, salaire, gain.

### Vers le wallet LigdiCash du client

```typescript TypeScript theme={null}
const withdrawal = client.Withdrawal(5000, "Remboursement commande ORD-20240510", "22670123456");

const response = await withdrawal.send({
  type: "client",
  to_wallet: false,  // false = virement automatique vers le mobile money lié
  callback_url: "https://backend.masuperboutique.com/ligdicash/callback-payout",
  custom_data: { transaction_id: "REFUND-20240512" },
});

const token = response.token;
```

### Directement vers le mobile money

```typescript TypeScript theme={null}
const response = await withdrawal.send({
  type: "merchant",  // Payout direct, sans wallet intermédiaire
  callback_url: "https://backend.masuperboutique.com/ligdicash/callback-payout",
  custom_data: { transaction_id: "PAY-20240512" },
});
```

<Note>
  `type: "client"` utilise `POST /pay/v01/withdrawal/create` (via wallet LigdiCash). `type: "merchant"` utilise `POST /pay/v01/straight/payout` (mobile money direct, plus lent). Voir [Payout — Introduction](/api-paiement/payout/introduction).
</Note>

***

## Vérification de statut

Appelez `getTransaction` avec le token stocké à la **création** (pas le token du callback, qui est différent).

```typescript TypeScript theme={null}
const token = "eyJ0eXAiOiJ...";  // Token retourné lors de la création

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

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

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

if (transaction.status === "completed") {
  // Livrer la commande / valider le paiement
} else if (transaction.status === "pending") {
  // Paiement en cours — relancer dans quelques secondes
} else {
  // Paiement échoué ou annulé
}
```

**Champs disponibles sur `transaction` :**

| Propriété       | Type       | Description                                   |
| --------------- | ---------- | --------------------------------------------- |
| `status`        | `string`   | `"completed"`, `"pending"`, `"cancelled"`     |
| `response_code` | `string`   | `"00"` succès, `"01"` échec                   |
| `amount`        | `number`   | Montant de la transaction                     |
| `operator_id`   | `string`   | Identifiant de l'opérateur                    |
| `operator_name` | `string`   | Nom de l'opérateur                            |
| `customer`      | `string`   | Numéro du client                              |
| `token`         | `string`   | Token de la transaction                       |
| `custom_data`   | `object`   | Données personnalisées envoyées à la création |
| `wiki`          | `string[]` | Liens vers les codes d'erreur de l'endpoint   |

<Warning>
  Ne livrez jamais une commande uniquement sur la base d'un callback entrant. Appelez toujours `getTransaction` avec le token stocké à la création pour confirmer le statut côté serveur LigdiCash. Voir [Sécurisation du callback](/api-paiement/callback/securisation).
</Warning>

***

## Types TypeScript

Le SDK exporte les types suivants pour vos signatures de fonction et vos interfaces :

```typescript TypeScript theme={null}
import type {
  InvoiceParam,
  InvoiceItemParam,
  PayWithRedirectionParam,
  PayWithoutRedirectionParam,
  BaseResponseType,
} from "ligdicash";
```

| Type                         | Usage                                         |
| ---------------------------- | --------------------------------------------- |
| `InvoiceParam`               | Paramètres du constructeur `Invoice`          |
| `InvoiceItemParam`           | Paramètres de `addItem`                       |
| `PayWithRedirectionParam`    | Paramètres de `payWithRedirection`            |
| `PayWithoutRedirectionParam` | Paramètres de `payWithoutRedirection`         |
| `BaseResponseType`           | Réponse retournée par les appels payin/payout |

***

## Gestion des erreurs

```typescript TypeScript theme={null}
try {
  const response = await invoice.payWithRedirection({
    return_url: "https://masuperboutique.com/succes",
    cancel_url: "https://masuperboutique.com/annulation",
    callback_url: "https://backend.masuperboutique.com/callback",
    custom_data: { transaction_id: "ORD-20240512" },
  });
} catch (error) {
  // Le SDK lève une exception en cas d'erreur HTTP ou d'erreur API
  console.error(error);
}
```

<Note>
  Vérifiez aussi `response.response_code` après chaque appel : `"00"` indique un succès, `"01"` une erreur. En cas d'erreur, consultez `response.wiki` pour obtenir l'URL de détail des sous-codes.
</Note>

***

## Liens utiles

* [Payin avec redirection — Introduction](/api-paiement/payin-redirect/introduction)
* [Payin sans redirection — Modes d'authentification](/api-paiement/payin-sans-redirect/modes-validation)
* [Payout — Introduction](/api-paiement/payout/introduction)
* [Sécurisation du callback](/api-paiement/callback/securisation)
* [Pattern transaction\_id](/concepts/transaction-id-pattern)
* [Package npm ligdicash](https://www.npmjs.com/package/ligdicash)


# SDK PHP
Source: https://developers.ligdicash.com/sdk/php

Installez et utilisez le SDK PHP LigdiCash pour vos backends Laravel, Symfony ou PHP vanilla.

Le SDK PHP LigdiCash s'installe via Composer et fonctionne avec n'importe quel backend PHP. Les appels réseau sont synchrones. Le SDK utilise Guzzle comme client HTTP.

## Installation

```bash theme={null}
composer require ligdicash/ligdicash
```

**Prérequis :** PHP ≥ 7.4. Guzzle est installé automatiquement comme dépendance.

## Initialisation

```php PHP theme={null}
require_once 'vendor/autoload.php';

$client = new \Ligdicash\Ligdicash([
    "api_key"    => "{API_KEY}",
    "auth_token" => "{AUTH_TOKEN}",
    "platform"   => "live",
]);
```

Obtenez votre `api_key` et votre `auth_token` depuis le [dashboard LigdiCash](https://dashboard.ligdicash.com) en créant un projet API.

***

## Payin avec redirection

Le client est redirigé vers la page de paiement hébergée par LigdiCash. C'est le flux recommandé pour les boutiques en ligne.

```php PHP theme={null}
// 1. Créer la facture
$invoice = $client->Invoice([
    "currency"           => "xof",
    "description"        => "Commande #ORD-20240512",
    "customer_firstname" => "Amadou",
    "customer_lastname"  => "Ouédraogo",
    "customer_email"     => "amadou@exemple.com",
    "store_name"         => "MaSuperBoutique",
    "store_website_url"  => "https://masuperboutique.com",
]);

// 2. Ajouter les articles
$invoice->addItem([
    "name"        => "Chemise kente",
    "description" => "Taille M",
    "quantity"    => 2,
    "unit_price"  => 15000,
]);
$invoice->addItem([
    "name"        => "Frais de livraison",
    "description" => "",
    "quantity"    => 1,
    "unit_price"  => 1500,
]);

// 3. Lancer le paiement
$response = $invoice->payWithRedirection([
    "return_url"   => "https://masuperboutique.com/commande/succes",
    "cancel_url"   => "https://masuperboutique.com/commande/annulation",
    "callback_url" => "https://backend.masuperboutique.com/ligdicash/callback",
    "custom_data"  => ["transaction_id" => "ORD-20240512"],
]);

// 4. Rediriger le client
$paymentUrl = $response->response_text;
header("Location: $paymentUrl");
exit;
```

<Warning>
  Ne jamais ouvrir `$paymentUrl` dans une iframe — LigdiCash la bloque. Redirigez dans le même onglet, un nouvel onglet ou un popup.
</Warning>

<Tip>
  Laissez toujours `customer` absent (ou vide) dans le payin avec redirection. Si vous passez un numéro, LigdiCash filtre la page de paiement pour ne montrer que les opérateurs de ce numéro.
</Tip>

***

## Payin sans redirection

Le client paie directement depuis votre interface. Vous devez collecter son numéro de téléphone et, selon l'opérateur, son code OTP.

```php PHP theme={null}
// 1. Créer la facture
$invoice = $client->Invoice([
    "currency"           => "xof",
    "description"        => "Commande #ORD-20240512",
    "customer_firstname" => "Amadou",
    "customer_lastname"  => "Ouédraogo",
    "customer_email"     => "amadou@exemple.com",
    "store_name"         => "MaSuperBoutique",
    "store_website_url"  => "https://masuperboutique.com",
]);
$invoice->addItem([
    "name" => "Chemise kente", "description" => "Taille M",
    "quantity" => 2, "unit_price" => 15000,
]);

// 2. Lancer le paiement (avec OTP fourni par le client)
$response = $invoice->payWithoutRedirection([
    "otp"          => "123456",       // Code OTP saisi par le client
    "customer"     => "22670123456",  // Numéro du client, sans + ni espaces
    "callback_url" => "https://backend.masuperboutique.com/ligdicash/callback",
    "custom_data"  => ["transaction_id" => "ORD-20240512"],
]);

// 3. Stocker le token pour vérification ultérieure
$token = $response->token;
```

<Note>
  Le mode OTP varie selon l'opérateur. Par exemple, pour un opérateur en mode USSD, le client génère son OTP sur son téléphone **avant** que vous ne soumetttiez. Pour un opérateur en mode approbation (ex. Moov Africa), envoyez `"otp" => ""` — le client approuve directement sur son application. Consultez la [page de l'opérateur](/api-paiement/payin-sans-redirect/introduction) concerné.
</Note>

***

## Payout

Envoyez de l'argent vers un client — remboursement, salaire, gain.

### Vers le wallet LigdiCash du client

```php PHP theme={null}
$withdrawal = $client->Withdrawal([
    "amount"      => 5000,
    "description" => "Remboursement commande ORD-20240510",
    "customer"    => "22670123456",
]);

$response = $withdrawal->send([
    "type"         => "client",
    "to_wallet"    => false,  // false = virement automatique vers le mobile money lié
    "callback_url" => "https://backend.masuperboutique.com/ligdicash/callback-payout",
    "custom_data"  => ["transaction_id" => "REFUND-20240512"],
]);

$token = $response->token;
```

### Directement vers le mobile money

```php PHP theme={null}
$response = $withdrawal->send([
    "type"         => "merchant",  // Payout direct, sans wallet intermédiaire
    "callback_url" => "https://backend.masuperboutique.com/ligdicash/callback-payout",
    "custom_data"  => ["transaction_id" => "PAY-20240512"],
]);
```

<Note>
  `"type" => "client"` utilise `POST /pay/v01/withdrawal/create` (via wallet LigdiCash). `"type" => "merchant"` utilise `POST /pay/v01/straight/payout` (mobile money direct, plus lent). Voir [Payout — Introduction](/api-paiement/payout/introduction).
</Note>

***

## Vérification de statut

Appelez `getTransaction` avec le token stocké à la **création** (pas le token du callback, qui est différent).

```php PHP theme={null}
$token = "eyJ0eXAiOiJ...";  // Token retourné lors de la création

// Payin
$transaction = $client->getTransaction([
    "token" => $token,
    "type"  => "payin",  // "payin" ou "payout"
]);

if ($transaction->status === "completed") {
    // Livrer la commande / valider le paiement
} elseif ($transaction->status === "pending") {
    // Paiement en cours — relancer dans quelques secondes
} else {
    // Paiement échoué ou annulé
}
```

<Note>
  En PHP, le paramètre `type` de `getTransaction` accepte `"payin"` ou `"payout"` (pas `"client_payout"` ni `"merchant_payout"` comme dans les SDK Python et JavaScript).
</Note>

**Champs disponibles sur `$transaction` :**

| Propriété       | Type     | Description                                   |
| --------------- | -------- | --------------------------------------------- |
| `status`        | `string` | `"completed"`, `"pending"`, `"cancelled"`     |
| `response_code` | `string` | `"00"` succès, `"01"` échec                   |
| `amount`        | `int`    | Montant de la transaction                     |
| `operator_id`   | `string` | Identifiant de l'opérateur                    |
| `operator_name` | `string` | Nom de l'opérateur                            |
| `customer`      | `string` | Numéro du client                              |
| `token`         | `string` | Token de la transaction                       |
| `custom_data`   | `array`  | Données personnalisées envoyées à la création |
| `wiki`          | `array`  | Liens vers les codes d'erreur de l'endpoint   |

<Warning>
  Ne livrez jamais une commande uniquement sur la base d'un callback entrant. Appelez toujours `getTransaction` avec le token stocké à la création pour confirmer le statut côté serveur LigdiCash. Voir [Sécurisation du callback](/api-paiement/callback/securisation).
</Warning>

***

## Gestion des erreurs

```php PHP theme={null}
try {
    $response = $invoice->payWithRedirection([
        "return_url"   => "https://masuperboutique.com/succes",
        "cancel_url"   => "https://masuperboutique.com/annulation",
        "callback_url" => "https://backend.masuperboutique.com/callback",
        "custom_data"  => ["transaction_id" => "ORD-20240512"],
    ]);
} catch (\InvalidArgumentException $e) {
    // Paramètre manquant ou invalide (currency, type, etc.)
    echo $e->getMessage();
} catch (\Exception $e) {
    // Erreur réseau ou erreur retournée par l'API
    echo $e->getMessage();
}
```

<Note>
  Vérifiez aussi `$response->response_code` après chaque appel : `"00"` indique un succès, `"01"` une erreur. En cas d'erreur, consultez `$response->wiki` pour obtenir l'URL de détail des sous-codes.
</Note>

***

## Liens utiles

* [Payin avec redirection — Introduction](/api-paiement/payin-redirect/introduction)
* [Payin sans redirection — Modes d'authentification](/api-paiement/payin-sans-redirect/modes-validation)
* [Payout — Introduction](/api-paiement/payout/introduction)
* [Sécurisation du callback](/api-paiement/callback/securisation)
* [Pattern transaction\_id](/concepts/transaction-id-pattern)


# SDK Python
Source: https://developers.ligdicash.com/sdk/python

Installez et utilisez le SDK Python LigdiCash pour vos backends Django, Flask, FastAPI ou scripts serveur.

Le SDK Python LigdiCash expose trois objets principaux — `Invoice`, `Withdrawal` et `get_transaction` — qui couvrent l'ensemble des flux de paiement. Contrairement aux autres SDK, l'initialisation se fait via des variables globales de module, pas via une instance de classe.

## Installation

```bash theme={null}
pip install ligdicash
```

**Prérequis :** Python ≥ 3.0. La dépendance `requests` est installée automatiquement.

## Initialisation

```python Python theme={null}
import ligdicash

ligdicash.api_key   = "{API_KEY}"
ligdicash.auth_token = "{AUTH_TOKEN}"
ligdicash.platform  = "live"
```

Obtenez votre `api_key` et votre `auth_token` depuis le [dashboard LigdiCash](https://dashboard.ligdicash.com) en créant un projet API.

***

## Payin avec redirection

Le client est redirigé vers la page de paiement hébergée par LigdiCash. C'est le flux recommandé pour les boutiques en ligne.

```python Python theme={null}
import ligdicash

# 1. Décrire la facture
invoice = ligdicash.Invoice(
    currency="xof",
    description="Commande #ORD-20240512",
    customer_firstname="Amadou",
    customer_lastname="Ouédraogo",
    customer_email="amadou@exemple.com",
    store_name="MaSuperBoutique",
    store_website_url="https://masuperboutique.com",
)

# 2. Ajouter les articles
invoice.add_item(name="Chemise kente", description="Taille M", quantity=2, unit_price=15000)
invoice.add_item(name="Frais de livraison", description="", quantity=1, unit_price=1500)

# 3. Lancer le paiement
response = invoice.pay_with_redirection(
    return_url="https://masuperboutique.com/commande/succes",
    cancel_url="https://masuperboutique.com/commande/annulation",
    callback_url="https://backend.masuperboutique.com/ligdicash/callback",
    custom_data={"transaction_id": "ORD-20240512"},
)

# 4. Rediriger le client
payment_url = response.response_text
redirect_user(payment_url)
```

<Warning>
  Ne jamais ouvrir `payment_url` dans une iframe — LigdiCash la bloque. Redirigez dans le même onglet, un nouvel onglet, ou un popup. Sur mobile natif, utilisez une WebView.
</Warning>

<Tip>
  Laissez toujours `customer` vide dans le payin avec redirection (c'est le comportement par défaut). Si vous passez un numéro, LigdiCash filtre la page de paiement pour ne montrer que les opérateurs de ce numéro.
</Tip>

***

## Payin sans redirection

Le client paie directement depuis votre interface. Vous devez collecter son numéro de téléphone et, selon l'opérateur, son code OTP.

```python Python theme={null}
import ligdicash

# 1. Décrire la facture (identique au payin avec redirection)
invoice = ligdicash.Invoice(
    currency="xof",
    description="Commande #ORD-20240512",
    customer_firstname="Amadou",
    customer_lastname="Ouédraogo",
    customer_email="amadou@exemple.com",
    store_name="MaSuperBoutique",
    store_website_url="https://masuperboutique.com",
)
invoice.add_item(name="Chemise kente", description="Taille M", quantity=2, unit_price=15000)

# 2. Lancer le paiement (avec OTP fourni par le client)
response = invoice.pay_without_redirection(
    otp="123456",             # Code OTP saisi par le client
    customer="22670123456",   # Numéro du client, sans + ni espaces
    callback_url="https://backend.masuperboutique.com/ligdicash/callback",
    custom_data={"transaction_id": "ORD-20240512"},
)

# 3. Stocker le token pour vérification ultérieure
token = response.token
```

<Note>
  Le mode OTP varie selon l'opérateur. Par exemple, pour un opérateur en mode USSD, le client génère son OTP sur son téléphone **avant** que vous ne soumetttiez. Pour un opérateur en mode approbation (ex. Moov Africa), envoyez `otp=""` — le client approuve directement sur son application. Consultez la [page de l'opérateur](/api-paiement/payin-sans-redirect/introduction) concerné.
</Note>

***

## Payout

Envoyez de l'argent vers un client — remboursement, salaire, gain.

### Vers le wallet LigdiCash du client

```python Python theme={null}
import ligdicash

withdrawal = ligdicash.Withdrawal(
    amount=5000,
    description="Remboursement commande ORD-20240510",
    customer="22670123456",
)

response = withdrawal.send(
    type="client",
    to_wallet=False,   # False = virement automatique vers le mobile money lié
    callback_url="https://backend.masuperboutique.com/ligdicash/callback-payout",
    custom_data={"transaction_id": "REFUND-20240512"},
)

token = response.token
```

### Directement vers le mobile money

```python Python theme={null}
response = withdrawal.send(
    type="merchant",   # Payout direct, sans wallet intermédiaire
    callback_url="https://backend.masuperboutique.com/ligdicash/callback-payout",
    custom_data={"transaction_id": "PAY-20240512"},
)
```

<Note>
  `type="client"` utilise l'endpoint `POST /pay/v01/withdrawal/create` (via wallet LigdiCash). `type="merchant"` utilise `POST /pay/v01/straight/payout` (mobile money direct, plus lent). Voir [Payout — Introduction](/api-paiement/payout/introduction).
</Note>

***

## Vérification de statut

Appelez `get_transaction` avec le token stocké à la **création** (pas le token du callback, qui est différent).

```python Python theme={null}
import ligdicash

token = "eyJ0eXAiOiJ..."   # Token retourné lors de la création

# Payin
transaction = ligdicash.get_transaction(token, "payin")

# Payout client (withdrawal/create)
# transaction = ligdicash.get_transaction(token, "client_payout")

# Payout marchand (straight/payout)
# transaction = ligdicash.get_transaction(token, "merchant_payout")

if transaction.status == "completed":
    # Livrer la commande / valider le paiement
    pass
elif transaction.status == "pending":
    # Paiement en cours — relancer dans quelques secondes
    pass
else:
    # Paiement échoué ou annulé
    pass
```

**Champs disponibles sur `transaction` :**

| Attribut        | Type   | Description                                   |
| --------------- | ------ | --------------------------------------------- |
| `status`        | `str`  | `"completed"`, `"pending"`, `"cancelled"`     |
| `response_code` | `str`  | `"00"` succès, `"01"` échec                   |
| `amount`        | `int`  | Montant de la transaction                     |
| `operator_id`   | `str`  | Identifiant de l'opérateur                    |
| `operator_name` | `str`  | Nom de l'opérateur                            |
| `customer`      | `str`  | Numéro du client                              |
| `token`         | `str`  | Token de la transaction                       |
| `custom_data`   | `dict` | Données personnalisées envoyées à la création |
| `wiki`          | `list` | Liens vers les codes d'erreur de l'endpoint   |

<Warning>
  Ne livrez jamais une commande uniquement sur la base d'un callback entrant. Appelez toujours `get_transaction` avec le token stocké à la création pour confirmer le statut côté serveur LigdiCash. Voir [Sécurisation du callback](/api-paiement/callback/securisation).
</Warning>

***

## Gestion des erreurs

Toutes les erreurs héritent de `ligdicash.LigdicashError` et exposent `.code` et `.message`.

```python Python theme={null}
import ligdicash

try:
    response = invoice.pay_with_redirection(
        return_url="https://masuperboutique.com/succes",
        cancel_url="https://masuperboutique.com/annulation",
        callback_url="https://backend.masuperboutique.com/callback",
        custom_data={"transaction_id": "ORD-20240512"},
    )
except ligdicash.AuthenticationError as e:
    # Clé API ou token d'authentification invalide
    print(e.message)
except ligdicash.MerchantPayinDisabledError as e:
    # La fonctionnalité payin n'est pas activée pour ce projet
    print(e.message)
except ligdicash.InvalidAmountError as e:
    # Montant hors de la plage [20 ; 1 000 000] XOF
    print(e.message)
except ligdicash.LigdicashError as e:
    # Toute autre erreur LigdiCash
    print(f"{e.code}: {e.message}")
```

**Classes d'erreur disponibles :**

| Classe                                | Déclenchée quand                             |
| ------------------------------------- | -------------------------------------------- |
| `AuthenticationError`                 | `api_key` ou `auth_token` invalide           |
| `ApplicationAuthenticationError`      | Application non authentifiée                 |
| `MerchantPayinDisabledError`          | Payin non activé sur le projet               |
| `MerchantPayoutDisabledError`         | Payout non activé sur le projet              |
| `MerchantBalanceLowError`             | Solde marchand insuffisant                   |
| `CustomerDoesNotExistError`           | Client non enregistré sur la plateforme      |
| `InvalidAmountError`                  | Montant hors de la plage \[20 ; 1 000 000]   |
| `InvalidTokenError`                   | Token invalide ou absent                     |
| `InvoiceNotFoundError`                | Facture introuvable                          |
| `TransactionAlreadyExistError`        | Transaction déjà créée                       |
| `RecipientOperatorNotIdentifiedError` | Opérateur du destinataire non identifié      |
| `FeatureNotTestableError`             | Fonctionnalité indisponible en mode `"test"` |

***

## Liens utiles

* [Payin avec redirection — Introduction](/api-paiement/payin-redirect/introduction)
* [Payin sans redirection — Modes d'authentification](/api-paiement/payin-sans-redirect/modes-validation)
* [Payout — Introduction](/api-paiement/payout/introduction)
* [Sécurisation du callback](/api-paiement/callback/securisation)
* [Pattern transaction\_id](/concepts/transaction-id-pattern)
* [Package PyPI ligdicash](https://pypi.org/project/ligdicash/)


# Skill LigdiCash pour agent IA
Source: https://developers.ligdicash.com/sdk/skill-ia

Installez le skill LigdiCash pour que Claude Code connaisse l'API dès le départ — endpoints, patterns de sécurité et pièges documentés.

Le skill LigdiCash encode toutes les conventions de l'API dans Claude Code : endpoints, format des données, pattern `transaction_id`, gestion du callback et pièges connus. Une fois installé, Claude Code l'active automatiquement dès que vous mentionnez LigdiCash dans vos prompts.

## Contenu du skill

| Fichier                           | Contenu                                                                                                   |
| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `SKILL.md`                        | Point d'entrée — authentification, payin redirect, payin sans redirect, payout, callback, codes de statut |
| `references/api-reference.md`     | Référence complète de tous les endpoints avec exemples de requête et de réponse réels                     |
| `references/payin-no-redirect.md` | Détail des quatre modes de validation OTP par opérateur                                                   |
| `references/security-patterns.md` | Pattern de re-vérification du callback, déduplication, cycle de vie complet                               |

## Installation

<Steps>
  <Step title="Récupérer le skill">
    Installez avec le CLI `skills` (recommandé) ou consultez les sources sur GitHub :

    <CardGroup>
      <Card title="Installer via npx" icon="terminal">
        ```bash theme={null}
        npx skills add ligdicash/skills --skill ligdicash-integration
        ```
      </Card>

      <Card title="Voir sur GitHub" icon="github" href="https://github.com/ligdicash/skills">
        Parcourir le code source, signaler un bug ou contribuer
      </Card>
    </CardGroup>
  </Step>

  <Step title="Lancer Claude Code">
    ```bash theme={null}
    claude
    ```

    Claude Code détecte automatiquement le skill au démarrage.
  </Step>

  <Step title="Vérifier l'activation">
    Tapez dans Claude Code :

    ```
    Quel skill LigdiCash as-tu chargé ?
    ```

    Claude Code doit lister le skill `ligdicash-integration` et décrire son contenu.
  </Step>
</Steps>

## Utiliser le skill

Une fois installé, utilisez des prompts directs — le skill fournit le contexte automatiquement.

<AccordionGroup>
  <Accordion title="Payin avec redirection">
    ```
    Implémente un payin LigdiCash avec redirection en [langage].
    Montant variable, inclure transaction_id dans custom_data.
    Ouvrir l'URL dans un nouvel onglet. Gérer les erreurs.
    ```
  </Accordion>

  <Accordion title="Handler de callback sécurisé">
    ```
    Écris un handler de callback LigdiCash en [langage/framework].
    Re-vérifier via confirm, dédupliquer par token, extraire
    transaction_id depuis custom_data.
    ```
  </Accordion>

  <Accordion title="Payout vers mobile money">
    ```
    Implémente un payout LigdiCash direct vers mobile money en [langage].
    Inclure transaction_id dans custom_data. Logger la wiki URL en cas d'erreur.
    ```
  </Accordion>

  <Accordion title="Payin sans redirection (OTP USSD)">
    ```
    Implémente un payin LigdiCash sans redirection, mode OTP USSD, en [langage].
    external_id vide, transaction_id dans custom_data, confirmation par callback.
    ```
  </Accordion>
</AccordionGroup>

## Cursor et Windsurf

Le skill est conçu pour Claude Code. Pour Cursor et Windsurf, les fichiers `references/` servent de contexte de session :

* **Cursor** — glissez `api-reference.md` et `security-patterns.md` dans le chat
* **Windsurf** — ajoutez-les via **Add Context** dans Cascade

Consultez les pages [Claude Code](/ai-tools/claude-code), [Cursor](/ai-tools/cursor) et [Windsurf](/ai-tools/windsurf) pour les fichiers de règles spécifiques à chaque éditeur.


# SDK officiels
Source: https://developers.ligdicash.com/sdk/vue-ensemble

Choisissez le SDK LigdiCash adapté à votre stack : Python, JavaScript/TypeScript, PHP ou Dart/Flutter.

Les SDK officiels LigdiCash encapsulent les appels HTTP, la sérialisation des payloads et la gestion des erreurs. Ils exposent les mêmes trois opérations dans chaque langage : payin avec redirection, payin sans redirection, payout et vérification de statut.

## SDK disponibles

<CardGroup>
  <Card title="Python" icon="python" href="/sdk/python">
    `pip install ligdicash` — backends Django, Flask, FastAPI, scripts serveur.
  </Card>

  <Card title="JavaScript / TypeScript" icon="js" href="/sdk/javascript">
    `npm install ligdicash` — Node.js, TypeScript, NestJS. Types inclus.
  </Card>

  <Card title="PHP" icon="php" href="/sdk/php">
    `composer require ligdicash/ligdicash` — Laravel, Symfony, WordPress custom.
  </Card>

  <Card title="Dart / Flutter" icon="mobile" href="/sdk/dart-flutter">
    `ligdicash: ^1.0.2` — applications Flutter iOS et Android.
  </Card>

  <Card title="WordPress / WooCommerce" icon="wordpress" href="/sdk/wordpress-woocommerce">
    Plugin ZIP à installer manuellement — aucun code requis.
  </Card>
</CardGroup>

## Comparatif rapide

|                   | Python                                                  | JavaScript                                                  | PHP                        | Dart                                                  | WordPress          |
| ----------------- | ------------------------------------------------------- | ----------------------------------------------------------- | -------------------------- | ----------------------------------------------------- | ------------------ |
| **Version**       | 1.0.5                                                   | 1.0.2                                                       | —                          | 1.0.2                                                 | 2.2.0              |
| **Installation**  | pip                                                     | npm                                                         | Composer                   | pub.dev                                               | ZIP manuel         |
| **Init**          | Globals de module                                       | Instance `new Ligdicash()`                                  | Instance `new Ligdicash()` | Instance `Ligdicash()`                                | Interface admin WP |
| **Appels réseau** | Synchrones                                              | `async/await`                                               | Synchrones                 | `async/await`                                         | — (plugin)         |
| **Types**         | —                                                       | TypeScript natif                                            | —                          | Enums `PlatformType`, `TransactionType`               | —                  |
| **Source**        | [GitHub](https://github.com/Ligdicash/ligdicash-python) | [GitHub](https://github.com/Ligdicash/ligdicash-javascript) | —                          | [GitHub](https://github.com/Ligdicash/ligdicash-dart) | —                  |

## Quel SDK choisir ?

**Backend web** — choisissez le SDK correspondant au langage de votre serveur (Python, PHP ou JavaScript/Node.js). Tous les trois s'intègrent naturellement dans un contrôleur ou une route.

**Application mobile Flutter** — utilisez le SDK Dart. Il gère nativement les `Future<>` et les named parameters idiomatiques Dart.

**Site WordPress + WooCommerce** — utilisez le plugin. Aucun code à écrire : installez le ZIP, entrez vos clés API dans l'interface d'administration WooCommerce, et la passerelle de paiement est opérationnelle.

**Pas de SDK pour votre langage ?** Implémentez les appels HTTP directement depuis la [Référence des endpoints](/reference/introduction). Les exemples cURL sont reproduits dans chaque page d'endpoint.

<Card title="Skill LigdiCash pour Claude Code" icon="brain-circuit" href="/sdk/skill-ia">
  Installez le skill pour que Claude Code, Cursor et Windsurf connaissent l'API LigdiCash dès le départ.
</Card>

## Ce que tous les SDK exposent

Quelle que soit la langue, vous disposez de trois objets / fonctions :

| Objet / Fonction | Rôle                                                                                          |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `Invoice`        | Crée une facture, ajoute des articles, déclenche un payin (avec ou sans redirection)          |
| `Withdrawal`     | Déclenche un payout vers le wallet LigdiCash d'un client ou directement vers son mobile money |
| `getTransaction` | Vérifie le statut d'une transaction à partir de son token                                     |


# Plugin WordPress / WooCommerce
Source: https://developers.ligdicash.com/sdk/wordpress-woocommerce

Installez et configurez le plugin LigdiCash pour accepter les paiements mobile money sur votre boutique WooCommerce, sans écrire de code.

Le plugin LigdiCash pour WooCommerce s'installe manuellement depuis un fichier ZIP. Une fois activé, il ajoute une passerelle de paiement dans votre interface WooCommerce — aucun code à écrire.

<a href="/downloads/plugin-wordpress.zip">**Télécharger le plugin (ZIP)**</a>

**Ce que fait le plugin :**

* Ajoute une méthode de paiement LigdiCash à la page de commande WooCommerce
* Redirige le client vers la page de paiement LigdiCash lors du passage en caisse
* Reçoit le callback de confirmation et met à jour automatiquement le statut de la commande
* Ajoute le support de la devise FCFA (XOF) dans WooCommerce

## Prérequis

* WordPress ≥ 4.x
* WooCommerce installé et activé
* Un projet API LigdiCash avec une `api_key` et un `auth_token` — voir [Créer un projet API](/concepts/projet-api)
* Devise de la boutique configurée sur **XOF** ou **FCFA**

***

## Installation

Le plugin s'installe en téléchargeant le dossier sous forme de fichier ZIP et en l'important dans WordPress.

<Steps>
  <Step title="Télécharger le plugin">
    Téléchargez le fichier ZIP via le lien en haut de cette page ou directement : [plugin-wordpress.zip](/downloads/plugin-wordpress.zip).
  </Step>

  <Step title="Importer dans WordPress">
    Dans votre tableau de bord WordPress, allez dans **Extensions → Ajouter une extension → Téléverser une extension**, sélectionnez le fichier `.zip`, puis cliquez sur **Installer maintenant**.
  </Step>

  <Step title="Activer le plugin">
    Une fois l'installation terminée, cliquez sur **Activer l'extension**.
  </Step>

  <Step title="Accéder aux paramètres">
    Allez dans **WooCommerce → Réglages → Paiements**, puis cliquez sur **LigdiCash** pour ouvrir la page de configuration.
  </Step>
</Steps>

***

## Configuration

Depuis **WooCommerce → Réglages → Paiements → LigdiCash** :

| Champ                  | Description                                                                      |
| ---------------------- | -------------------------------------------------------------------------------- |
| **Activer/Désactiver** | Cochez pour afficher LigdiCash comme méthode de paiement à la caisse             |
| **Titre**              | Texte affiché au client sur la page de commande (ex. : `Paiement mobile, VISA…`) |
| **Description**        | Description affichée sous le titre sur la page de commande                       |
| **Clé Principale**     | Votre `api_key` générée dans le dashboard LigdiCash                              |
| **Token**              | Votre `auth_token` généré dans le dashboard LigdiCash                            |

<Warning>
  Ne partagez jamais votre **Clé Principale** ni votre **Token** — ils donnent accès à votre compte marchand. Ne les commitez pas dans votre dépôt Git.
</Warning>

***

## Flux de paiement

Une fois le plugin configuré, voici ce qui se passe lors d'une commande :

<Steps>
  <Step title="Le client passe commande">
    Sur la page de commande WooCommerce, le client sélectionne **LigdiCash** comme mode de paiement et valide.
  </Step>

  <Step title="Redirection vers LigdiCash">
    Le plugin crée une facture via `POST /pay/v01/redirect/checkout-invoice/create` et redirige le client vers la page de paiement LigdiCash.
  </Step>

  <Step title="Paiement du client">
    Le client choisit son opérateur mobile money et effectue le paiement sur la page LigdiCash.
  </Step>

  <Step title="Retour sur la boutique">
    Après paiement, le client est redirigé vers la page de confirmation WooCommerce. Le plugin vérifie le statut via `GET /pay/v01/redirect/checkout-invoice/confirm/` et met à jour la commande.
  </Step>

  <Step title="Confirmation par callback">
    LigdiCash envoie également un callback POST à l'URL `{votre-site}/wc-api/wc_ligdicash/`. Le plugin traite ce callback et marque la commande comme **Terminée** si le statut est `completed`.
  </Step>
</Steps>

<Note>
  L'URL de callback est générée automatiquement par le plugin : `{votre-site}/wc-api/wc_ligdicash/`. Vous n'avez pas à la configurer manuellement — elle est enregistrée dans WooCommerce à l'activation du plugin.
</Note>

***

## Devise

Le plugin ajoute automatiquement la devise **FCFA (XOF)** dans WooCommerce. Configurez la devise de votre boutique sur **XOF** ou **FCFA** dans **WooCommerce → Réglages → Général**.

***

## Liens utiles

* [Créer un projet API](/concepts/projet-api)
* [Authentification — api\_key et auth\_token](/concepts/authentification)
* [Payin avec redirection — Introduction](/api-paiement/payin-redirect/introduction)
* [Callback — Introduction](/api-paiement/callback/introduction)