Skip to main content
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.
This method requires the beneficiary to have a LigdiCash account. If they do not, use Merchant payout, which sends directly to a mobile money number.

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

HeaderValue
ApikeyYour API key
AuthorizationBearer {AUTH_TOKEN}
Acceptapplication/json
Content-Typeapplication/json

​
Request body

All fields are nested inside a commande object.
​
commande
object
required

​
The top_up_wallet parameter

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.

​
Request example

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"
    }
  }
}'

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();

$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',
            ],
        ],
    ],
]);

​
Response

​
response_code
string
Request result code. "00" means the payout was initiated successfully. Any other value indicates an error.
​
token
string
JWT token identifying the payout. Store it immediately — it is required to verify the status if your callback does not fire.
​
response_text
string
Textual message associated with the response code. Can be empty.
​
description
string
Additional description. Can be empty.
​
custom_data
array
Always [] for Customer payout.
​
wiki
string
URL to the list of error codes specific to this endpoint. Consult when response_code !== "00".
Success
{
  "response_code": "00",
  "token": "{PAYOUT_TOKEN}",
  "response_text": "",
  "description": "",
  "custom_data": [],
  "wiki": "https://client.ligdicash.com/wiki/createWithdrawal"
}
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 if the callback is not received.