SDK JavaScript / TypeScript

Le package @mabipay/sdk permet d'intégrer MabiPay côté serveur (Node.js) ou frontend.

Installation

npm install @mabipay/sdk
pnpm add @mabipay/sdk
yarn add @mabipay/sdk

Initialisation

import { MabiPayClient } from "@mabipay/sdk";

const mabipay = new MabiPayClient({
  apiKey: "mbp_live_xxxxxxxxxxxxxxxxxxxx",
  environment: "live", // 'sandbox' | 'live'
});

Options de configuration

Option	Type	Défaut	Description
apiKey	string	requis	Votre clé API secrète
environment	string	'sandbox'	Environnement cible
baseUrl	string	URL automatique selon environment	Override pour dev local
timeout	number	30000	Timeout HTTP en ms

Paiements

Initier un paiement

const payment = await mabipay.payments.initiate({
  amount: 5000,
  currency: "XOF",
  operator: "OM_CI", // WAVE_CI | MTN_CI | MOOV_CI | OM_CI
  merchantRef: "ORDER-001",
  customerPhone: "0700000001",
  customerName: "Jean Dupont",
  notifyUrl: "https://votre-api.com/webhooks",
  description: "Commande #001",
});

// payment.checkoutUrl → rediriger le client (toujours présent)
// payment.paymentUrl  → URL opérateur, peut être `null`
// payment.reference   → stocker pour suivi (format `PAY-...`)

Récupérer une transaction

const tx = await mabipay.payments.get("PAY-XXXXXXXXXX");
console.log(tx.status); // 'success' | 'pending' | 'failed' | ...

Lister les transactions

const { data, meta } = await mabipay.payments.list({
  page: 1,
  limit: 20, // max 100
  status: "success", // ou une liste : "pending,success"
});

console.log(meta); // { total, page, limit, totalPages }

La liste est restreinte au marchand et à l'environnement de la clé : une clé sandbox n'expose jamais les transactions de production.

Virements (Payouts)

const payout = await mabipay.payouts.initiate({
  amount: 10000,
  currency: "XOF",
  operator: "MTN_CI",
  merchantRef: "PAYOUT-001",
  recipientPhone: "670000000",
  recipientName: "Marie Martin",
});

Opérateurs disponibles

const operators = await mabipay.operators.list();
// Filtrer par type
const mobileMoneyOps = await mabipay.operators.list({ type: "mobile_money" });

Checkout hébergé

// Récupérer les détails d'un checkout
const checkout = await mabipay.checkout.get("PAY-XXXXXXXXXX");

// Vérifier le statut
const { status } = await mabipay.checkout.status("PAY-XXXXXXXXXX");

Vérification des webhooks

import { verifyWebhookSignature } from "@mabipay/sdk";

// Express
app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const valid = verifyWebhookSignature({
    secret: process.env.MABIPAY_WEBHOOK_SECRET!,
    signature: req.headers["x-mabipay-signature"] as string,
    payload: req.body.toString(),
  });

  if (!valid) return res.status(401).json({ error: "Signature invalide" });

  const event = JSON.parse(req.body.toString());
  // Traiter l'événement...
  res.json({ received: true });
});

Gestion des erreurs

import type { MabiPayError } from '@mabipay/sdk';

try {
  await mabipay.payments.initiate({ ... });
} catch (err) {
  const error = err as MabiPayError;
  switch (error.code) {
    case 'INSUFFICIENT_BALANCE':
      console.error('Solde insuffisant');
      break;
    case 'OPERATOR_UNAVAILABLE':
      console.error('Opérateur temporairement indisponible');
      break;
    default:
      console.error(`Erreur ${error.statusCode}: ${error.message}`);
  }
}