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

# Customer payout — to LigdiCash wallet

> Transfer funds to a beneficiary's LigdiCash wallet with POST /pay/v01/withdrawal/create.

Customer payout sends funds to a beneficiary's **LigdiCash wallet**, identified by their phone number. Funds arrive instantly in their wallet. Via the `top_up_wallet` parameter, you choose whether the funds stay there or whether LigdiCash automatically triggers a transfer to their mobile money account.

<Note>
  This method requires the beneficiary to have a LigdiCash account. If they do not, use [Merchant payout](/en/payment-api/payout/to-mobile-money), which sends directly to a mobile money number.
</Note>

## Prerequisites

* Payout must be enabled on your API project.
* Your server IP addresses must be **whitelisted by LigdiCash** — requests from non-whitelisted IPs are rejected. Contact [developper@ligdicash.com](mailto:developper@ligdicash.com) to enable it.
* The sub-account of the operator matching the beneficiary's number must be sufficiently funded.

## Endpoint

```
POST https://app.ligdicash.com/pay/v01/withdrawal/create
```

## Required headers

| Header          | Value                 |
| --------------- | --------------------- |
| `Apikey`        | Your API key          |
| `Authorization` | `Bearer {AUTH_TOKEN}` |
| `Accept`        | `application/json`    |
| `Content-Type`  | `application/json`    |

## Request body

All fields are nested inside a `commande` object.

<ParamField body="commande" type="object" required>
  <Expandable title="commande fields">
    <ParamField body="amount" type="integer" required>
      Amount to transfer in XOF. Must be a positive integer (no decimals).
    </ParamField>

    <ParamField body="description" type="string" required>
      Description of the operation. Appears in the beneficiary's history.
    </ParamField>

    <ParamField body="customer" type="string" required>
      Beneficiary's phone number, with country code, no `+` or spaces. Example: `22670000000`.
    </ParamField>

    <ParamField body="callback_url" type="string" required>
      HTTPS URL of your server that will receive the result notification. Must be publicly accessible.
    </ParamField>

    <ParamField body="top_up_wallet" type="integer" required>
      Behavior after the beneficiary's wallet is credited:

      * `1` — funds stay in the beneficiary's LigdiCash wallet
      * `0` — LigdiCash automatically triggers a transfer to the mobile money account linked to the wallet
    </ParamField>

    <ParamField body="custom_data" type="object">
      Custom data associated with the transaction. Recommended: include a merchant-generated unique `transaction_id` to identify the transaction in your system.
    </ParamField>
  </Expandable>
</ParamField>

## The `top_up_wallet` parameter

<Tabs>
  <Tab title="top_up_wallet: 1 — wallet only">
    Funds arrive in the beneficiary's LigdiCash wallet and stay there. The beneficiary can use them to pay on LigdiCash platforms or initiate a withdrawal to their mobile money themselves.

    **Use for:** crediting a loyalty account, distributing rewards the beneficiary will spend on your platform.
  </Tab>

  <Tab title="top_up_wallet: 0 — auto-transfer">
    Funds arrive in the beneficiary's LigdiCash wallet, then LigdiCash automatically triggers a transfer to their linked mobile money account. The beneficiary receives the funds on their phone.

    **Use for:** refunds, salaries, winnings — when the beneficiary must receive money on their mobile money without any action from them.

    <Note>
      Wallet crediting is instant. The transfer to mobile money may take a few minutes depending on the operator.
    </Note>
  </Tab>
</Tabs>

## Request example

<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": "Refund for order ORD-2024-001",
      "customer": "22670000000",
      "callback_url": "https://backend.mygreatshop.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: 'Refund for order ORD-2024-001',
        customer: '22670000000',
        callback_url: 'https://backend.mygreatshop.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'  => 'Refund for order ORD-2024-001',
              'customer'     => '22670000000',
              'callback_url' => 'https://backend.mygreatshop.com/callback-payout',
              'top_up_wallet'=> 1,
              'custom_data'  => [
                  'transaction_id' => 'PAYOUT-ORD-2024-001',
              ],
          ],
      ],
  ]);
  ```
</CodeGroup>

## Response

<ResponseField name="response_code" type="string">
  Request result code. `"00"` means the payout was initiated successfully. Any other value indicates an error.
</ResponseField>

<ResponseField name="token" type="string">
  JWT token identifying the payout. Store it immediately — it is required to [verify the status](/en/payment-api/payout/verify-status) if your callback does not fire.
</ResponseField>

<ResponseField name="response_text" type="string">
  Textual message associated with the response code. Can be empty.
</ResponseField>

<ResponseField name="description" type="string">
  Additional description. Can be empty.
</ResponseField>

<ResponseField name="custom_data" type="array">
  Always `[]` for Customer payout.
</ResponseField>

<ResponseField name="wiki" type="string">
  URL to the list of error codes specific to this endpoint. Consult when `response_code !== "00"`.
</ResponseField>

```json Success theme={null}
{
  "response_code": "00",
  "token": "{PAYOUT_TOKEN}",
  "response_text": "",
  "description": "",
  "custom_data": [],
  "wiki": "https://client.ligdicash.com/wiki/createWithdrawal"
}
```

<Warning>
  A `response_code: "00"` means the payout was **initiated**, not necessarily finalized. The final result reaches you via the callback. Store the `token` so you can [verify the status](/en/payment-api/payout/verify-status) if the callback is not received.
</Warning>

## Related pages

* [Merchant payout](/en/payment-api/payout/to-mobile-money) — direct transfer to mobile money without an intermediary wallet
* [Verify the status of a payout](/en/payment-api/payout/verify-status)
* [The LigdiCash merchant account](/en/concepts/merchant-account) — understanding sub-accounts and per-operator balances