> ## 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 JavaScript / TypeScript

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