# SDK TypeScript
Source: https://docs.lomi.africa/build/sdks/typescript

SDK TypeScript / JavaScript officiel pour l’API de paiement lomi.

***

title: SDK TypeScript
description: SDK TypeScript / JavaScript officiel pour l’API de paiement lomi.
------------------------------------------------------------------------------

import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Callout } from '@/components/docs/docs-callout';

SDK Node.js / TypeScript officiel pour l’API de paiement lomi. Compatible Node.js, Deno, Bun et navigateur.

## Installation

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']}>
  <Tab value="npm">`bash npm install @lomi./sdk `</Tab>
  <Tab value="pnpm">`bash pnpm add @lomi./sdk `</Tab>
  <Tab value="yarn">`bash yarn add @lomi./sdk `</Tab>
  <Tab value="bun">`bash bun add @lomi./sdk `</Tab>
</Tabs>

## Avant de commencer

1. [Créer un compte lomi.](https://dashboard.lomi.africa/signup) et terminer l’onboarding.
2. Copier une **clé secrète de test** dans **Paramètres → Jetons d’accès** (`lomi_sk_test_…`). Voir [Variables d’environnement](/start/api-keys).
3. L’ajouter dans un fichier `.env` (voir [Gestion des variables](/start/api-keys)).
4. Installer le SDK (ci-dessous), utiliser `environment: 'test'`, puis exécuter l’exemple [premier appel API](#premier-appel-api-bac-a-sable).

## Environnements et URL de base

Utilisez **`test`** pendant le développement. Le SDK choisit l’hôte API automatiquement :

| `environment` | URL API                           | Préfixe clé secrète |
| ------------- | --------------------------------- | ------------------- |
| `'test'`      | `https://sandbox.api.lomi.africa` | `lomi_sk_test_…`    |
| `'live'`      | `https://api.lomi.africa`         | `lomi_sk_live_…`    |

## Démarrage rapide

```typescript
import { LomiSDK } from '@lomi./sdk';

const lomi = new LomiSDK({
  apiKey: process.env.LOMI_SECRET_KEY!,
  environment: 'test', // bac à sable: « live » uniquement en production
});
```

## Premier appel API (bac à sable)

Exemple exécutable : installer le SDK, définir `LOMI_SECRET_KEY` dans `.env`, puis lister les comptes.

```typescript
import { LomiSDK, LomiError } from '@lomi./sdk';

const lomi = new LomiSDK({
  apiKey: process.env.LOMI_SECRET_KEY!,
  environment: 'test',
});

async function main() {
  try {
    const balance = await lomi.accounts.getBalance();
    console.log('Solde :', balance);
  } catch (error) {
    if (error instanceof LomiError) {
      console.error(`Erreur API [${error.status}] : ${error.message}`);
      process.exit(1);
    }
    throw error;
  }
}

main();
```

```bash filename=".env"
LOMI_SECRET_KEY=lomi_sk_test_xxxxxxxxxxxxxxxxxxxxxx
```

```bash filename="Terminal"
npm install @lomi./sdk
npx tsx first-call.ts
```

Résultat attendu : liste JSON depuis `GET https://sandbox.api.lomi.africa/accounts`. Sans SDK : [Intégration API](/start/first-payment).

***

## Exemples de paiement

### Créer une session de paiement

```typescript
const session = await lomi.checkoutSessions.create({
  amount: 10000,
  currency_code: 'XOF',
  title: 'Abonnement Premium',
  description: 'Accès mensuel aux fonctionnalités premium',
  customer_email: 'customer@example.com',
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel',
  metadata: { order_id: 'ORD-123' },
});

console.log('Redirection vers :', session.checkout_url);
```

### Créer un lien de paiement

```typescript
const link = await lomi.paymentLinks.create({
  link_type: 'product',
  title: 'Formule Pro',
  currency_code: 'XOF',
  product_id: 'prod_abc123...',
  allow_coupon_code: true,
});

console.log('Partagez ce lien :', link.url);
```

### Lister les transactions avec filtres

```typescript
const transactions = await lomi.transactions.list({
  status: 'completed',
  provider: 'WAVE',
  startDate: '2024-01-01T00:00:00Z',
  pageSize: 50,
});

for (const tx of transactions) {
  console.log(`${tx.id}: ${tx.gross_amount} ${tx.currency_code}`);
}
```

***

## Gestion des clients

### Créer un client

```typescript
const customer = await lomi.customers.create({
  name: 'Amadou Ba',
  email: 'amadou@example.com',
  phone_number: '+221771234567',
  country: 'Senegal',
  city: 'Dakar',
  metadata: { source: 'website' },
});

console.log('ID client :', customer.id);
```

### Transactions d’un client

```typescript
const transactions = await lomi.customers.getTransactions('cus_abc123...');
```

***

## Produits et abonnements

### Créer un produit

```typescript
const product = await lomi.products.create({
  name: 'Formule Premium',
  description: 'Accès à l’ensemble des fonctionnalités',
  product_type: 'recurring',
  prices: [
    {
      amount: 15000,
      currency_code: 'XOF',
      billing_interval: 'month',
      is_default: true,
    },
  ],
  trial_enabled: true,
  trial_period_days: 7,
});
```

### Ajouter un nouveau tarif

```typescript
const price = await lomi.products.addPrice('prod_abc123...', {
  amount: 150000,
  currency_code: 'XOF',
  billing_interval: 'year',
});
```

### Annuler un abonnement

```typescript
const cancelled = await lomi.subscriptions.cancel('sub_abc123...', {
  cancellation_reason: 'Demande du client',
});
```

***

## Virements et appels spécifiques aux rails

### Virement (`POST /payouts`)

```typescript
await lomi.payouts.create({
  destination: 'beneficiary',
  rail: 'wave',
  amount: 10000,
  currency_code: 'XOF',
  recipient: { name: 'Aicha Diallo', phone: '+221771234567' },
});
```

### Encaissement mobile money (`POST /charge/wave`)

```typescript
await lomi.charges.createWaveCharge({
  amount: 5000,
  currency: 'XOF',
  customer: {
    name: 'Moussa Ndiaye',
    phoneNumber: '+221771234567',
    email: 'moussa@example.com',
  },
});
```

### Carte embarquée (`POST /charge/card`)

```typescript
await lomi.charges.createCardCharge({
  amount: 2500,
  currency_code: 'XOF',
  customer_email: 'buyer@example.com',
  customer_name: 'Acheteur Test',
});
```

***

## Compte et organisation

### Obtenir le solde du compte

```typescript
const balances = await lomi.accounts.getBalance();
const xofBalance = await lomi.accounts.getBalance({ currency: 'XOF' });

console.log('Disponible :', xofBalance.available);
```

### Indicateurs de l’organisation

```typescript
const metrics = await lomi.organizations.getMetrics();

console.log('MRR :', metrics.mrr);
console.log('Nombre de clients :', metrics.total_customers);
```

***

## Gestion des erreurs

```typescript
import { LomiSDK, LomiError, LomiNotFoundError } from '@lomi./sdk';

try {
  const customer = await lomi.customers.get('invalid_id');
} catch (error) {
  if (error instanceof LomiNotFoundError) {
    console.error('Client introuvable');
  } else if (error instanceof LomiError) {
    console.error(`Erreur API [${error.status}] : ${error.message}`);
  } else {
    throw error;
  }
}
```

***

## Options de configuration

```typescript
interface LomiConfig {
  apiKey: string;              // Clé secrète d’API
  environment?: 'test' | 'live'; // Bac à sable ou production
  baseUrl?: string;            // URL de base personnalisée (remplace environment)
  headers?: Record<string, string>; // En-têtes HTTP supplémentaires
  timeout?: number;            // Délai d’expiration des requêtes en ms (défaut : 30000)
}
```

***

## Services disponibles

| Service            | Méthodes                                                                                                                            |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `accounts`         | `list`, `get`, `getBalance`, `getBalanceBreakdown`, `checkBalance`                                                                  |
| `charges`          | `createWaveCharge`, `createMtnCharge`, `createCardCharge`, `getCardCharge`, `cancelCardCharge`                                      |
| `checkoutSessions` | `list`, `get`, `create`                                                                                                             |
| `customers`        | `list`, `get`, `create`, `update`, `delete`, `getTransactions`, `getSubscriptions`, `createPortalSession`                           |
| `coupons`          | `list`, `get`, `create`, `getPerformance`                                                                                           |
| `organizations`    | `list`, `get`, `getMetrics`, `getRadarSettings`, `updateRadarSettings`                                                              |
| `paymentLinks`     | `list`, `get`, `create`                                                                                                             |
| `paymentRequests`  | `list`, `get`, `create`                                                                                                             |
| `payouts`          | `create`, `list`, `get`                                                                                                             |
| `products`         | `list`, `get`, `create`, `addPrice`, `setDefaultPrice`                                                                              |
| `refunds`          | `create`, `list`, `get`                                                                                                             |
| `subscriptions`    | `list`, `get`, `getUsage`, `cancel`, `resume`                                                                                       |
| `transactions`     | `list`, `get`                                                                                                                       |
| `usage`            | `list`, `get`, `create`, `createSubscription`, `listPeriods`, `getRevenue`, `grantCredits`, `createEntitlement`, `checkEntitlement` |
| `webhooks`         | `list`, `get`, `update`, `listDeliveries`, `getDelivery`                                                                            |

***

## Types TypeScript

Les types de lignes Supabase (`Database`) sont exportés pour les intégrations avancées :

```typescript
import type { Database } from '@lomi./sdk';

type Customer = Database['public']['Tables']['customers']['Row'];
```

Pour les corps de requêtes complexes, partez des exemples REST ; les méthodes utilisent encore `unknown` le temps d’affiner le typage.

***

## Ressources

* [Premiers pas](/start/create-account)
* [Référence API](/api)
* [GitHub](https://github.com/lomiafrica/lomi.)
* [Communauté Discord](https://discord.gg/yb4FnBmh)