> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ligdicash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payout Client — 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 body="commande" type="object" required>
  <Expandable title="Champs de commande">
    <ParamField body="amount" type="integer" required>
      Montant à transférer en XOF. Doit être un entier positif (pas de décimales).
    </ParamField>

    <ParamField body="description" type="string" required>
      Description de l'opération. Apparaît dans l'historique du bénéficiaire.
    </ParamField>

    <ParamField body="customer" type="string" required>
      Numéro de téléphone du bénéficiaire, avec indicatif pays, sans `+` ni espaces. Exemple : `22670000000`.
    </ParamField>

    <ParamField body="callback_url" type="string" required>
      URL HTTPS de votre serveur qui recevra la notification de résultat. Doit être accessible publiquement.
    </ParamField>

    <ParamField body="top_up_wallet" type="integer" required>
      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 body="custom_data" 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