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

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