SDK TypeScript

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

Installation

bash npm install @lomi./sdk

bash pnpm add @lomi./sdk

bash yarn add @lomi./sdk

bash bun add @lomi./sdk

Avant de commencer

Créer un compte lomi. et terminer l’onboarding.
Copier une clé secrète de test dans Paramètres → Jetons d’accès (lomi_sk_test_…). Voir Variables d’environnement.
L’ajouter dans un fichier .env (voir Gestion des variables).
Installer le SDK (ci-dessous), utiliser environment: 'test', puis exécuter l’exemple premier appel API.

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

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.

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

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

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

main();

LOMI_SECRET_KEY=lomi_sk_test_xxxxxxxxxxxxxxxxxxxxxx

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.

Exemples de paiement

Créer une session de paiement

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

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

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

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

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

Produits et abonnements

Créer un produit

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

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

Annuler un abonnement

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

Virements et appels spécifiques aux rails

Virement (`POST /payouts`)

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

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

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

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

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

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

Indicateurs de l’organisation

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

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

Gestion des erreurs

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

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`
`discountCoupons`	`list`, `get`, `create`, `getPerformance`
`organizations`	`list`, `get`, `getMetrics`
`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`, `findByCustomer`, `cancel`
`transactions`	`list`, `get`
`webhookDeliveryLogs`	`list`, `get`
`webhooks`	`list`, `get`, `update`

Types TypeScript

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

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.