@applite/duticotac

SDK JavaScript/TypeScript pour intégrer les paiements Duticotac (mobile money, offres, transactions).

Installation

pnpm add @applite/duticotac

Démarrage rapide

import { DuticotacSDK } from "@applite/duticotac";

const duticotac = new DuticotacSDK({
  apiKey: "your_api_key",
  appId: "your_app_id", // optionnel
});

Le SDK se connecte par défaut à https://api.appliteui.com. Vous pouvez passer un baseUrl personnalisé si nécessaire.

Modules

Balance

const { data: balance } = await duticotac.balance.balance();

Offres

// Créer une offre
await duticotac.offer.create({
  name: "Forfait Premium",
  ref: "premium-monthly",
  price: 5000,
  platform: "DUTICOTAC",
  type: "STATIC",
  description: "Accès premium mensuel",
});

// Lister les offres
const { data: offers } = await duticotac.offer.list();

// Récupérer une offre
const { data: offer } = await duticotac.offer.get({ ref: "premium-monthly" });

// Modifier une offre
await duticotac.offer.update({ ref: "premium-monthly", price: 7500 });

// Supprimer une offre
await duticotac.offer.delete({ ref: "premium-monthly" });

Paiements Mobile Money

// Encaissement (cash in)
await duticotac.mobileMoney.cashin({
  amount: 5000,
  phone: "+2250700000000",
  paymentMethod: "OM_CI",
  password: "password123",
});

// Décaissement (cash out)
await duticotac.mobileMoney.cashout({
  transactionId: "txn_123",
  ref: "ref_123",
  phone: "+2250700000000",
  name: "Jean Dupont",
  email: "[email protected]",
  paymentMethod: "OM_CI",
  otp: "1234", // requis pour Orange Money
});

Providers supportés : OM_CI (Orange Money), MTN_CI, MOOV_CI, WAVE_CI, CREDIT_CARD, CASH, IAP

Transactions

// Récupérer le statut d'une transaction
const { data: tx } = await duticotac.transaction.get({ id: "transaction_id" });

// Polling avec backoff exponentiel (idéal pour paiements asynchrones)
const { data: confirmed } = await duticotac.transaction.poll("transaction_id", {
  intervalMs: 2000, // intervalle minimum (défaut: 2s)
  timeoutMs: 90_000, // timeout global (défaut: 90s)
  onPoll: (attempt, elapsed) => {
    console.log(`Tentative ${attempt} (${elapsed}ms)`);
  },
  signal: abortController.signal, // annulation externe
});

Le polling utilise un backoff exponentiel (1s → 2s → 3s → 5s → 8s) et se termine quand la transaction passe en CONFIRMED, CANCELLED ou FAILED.

Méthodes de paiement

// Récupérer les méthodes configurées
const { data: methods } = await duticotac.paymentMethod.get();

// Configurer les méthodes
await duticotac.paymentMethod.set({
  providers: ["OM_CI", "MTN_CI", "WAVE_CI"],
});

Webhooks

// Récupérer l'URL du webhook
const { data: url } = await duticotac.webhook.get();

// Configurer l'URL
await duticotac.webhook.set({ url: "https://example.com/webhook" });

Types exportés

import type {
  // Enums
  TransactionStatus, // "PENDING" | "CONFIRMED" | "CANCELLED" | "FAILED"
  PlatformType, // "STORE" | "TRANSPORT" | "RESTAURATION" | ...
  PaymentProvider, // "OM_CI" | "MTN_CI" | "MOOV_CI" | "WAVE_CI" | ...
  Currency, // "USD" | "EUR" | "XOF" | "XAF"
  CoreApp, // "XORAIA" | "MONSMSPRO" | "FREE"
  DuTicOTacOfferType, // "STATIC" | "DYNAMIC"

  // Modèles
  TransactionModel,
  OfferModel,
  OfferAppModel,
  DuticotacSettingModel,
  PaymentLinksCountModel,
} from "@applite/duticotac";

Gestion des erreurs

Le SDK lève des DuticotacError avec un code correspondant aux erreurs de l'API :

import { DuticotacError } from "@applite/duticotac";

try {
  await duticotac.mobileMoney.cashout({ ... });
} catch (e) {
  if (e instanceof DuticotacError) {
    console.log(e.code);    // ex: "otp-required"
    console.log(e.message); // ex: "Code OTP requis pour les paiements Orange Money"
  }
}

Utilitaires

import {
  getProviderName, // "OM_CI" → "Orange Money"
  getProviderLogo, // "OM_CI" → URL du logo
  getErrorMessage, // "otp-required" → message en français
  ERROR_MESSAGES, // map code → message
} from "@applite/duticotac";

Scripts

• pnpm build – build CJS/ESM avec déclarations de types
• pnpm dev – mode watch pour le développement