Guide d'intégration rapide

Ce guide vous permet d'accepter votre premier paiement en moins de 10 minutes.

1. Obtenir un compte marchand

L'ouverture de compte n'est pas self-service : un administrateur MabiPay provisionne votre marchand. Contactez-nous, puis vérifiez que ces trois étapes sont bien réalisées côté MabiPay :

1. Création du marchand (nom, email, pays).
2. Activation du compte — un marchand nouvellement créé est au statut pending, et toutes les requêtes API renvoient 401 tant qu'il n'est pas active.
3. Création de votre utilisateur rattaché au marchand : vous recevez par email un mot de passe temporaire pour vous connecter à https://app.dev.mabipay.com.

2. Récupérer vos clés API

Connectez-vous au dashboard, puis dans Paramètres → Clés API, générez une clé pour l'environnement sandbox.

mbp_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La clé n'est affichée qu'une seule fois

Elle est stockée hachée : conservez-la immédiatement. Si vous la perdez, régénérez-la (l'ancienne est alors invalidée).

3. Installer le SDK

npm install @mabipay/sdk

4. Initier un paiement

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

const mabipay = new MabiPayClient({
  apiKey: process.env.MABIPAY_API_KEY!,
  environment: "sandbox",
});

async function creerPaiement(commande: {
  id: string;
  montant: number;
  telephone: string;
}) {
  const payment = await mabipay.payments.initiate({
    amount: commande.montant, // entier, min. 100
    currency: "XOF",
    operator: "OM_CI", // WAVE_CI | MTN_CI | MOOV_CI | OM_CI
    merchantRef: commande.id, // requis
    customerPhone: commande.telephone,
    notifyUrl: "https://votreapi.com/webhooks/mabipay",
    successUrl: "https://votresite.com/merci",
    failedUrl: "https://votresite.com/erreur",
  });

  // `checkoutUrl` = page de paiement hébergée MabiPay (toujours présente).
  // `paymentUrl` = URL opérateur, parfois `null` → ne pas l'utiliser seule.
  return payment.checkoutUrl;
}

5. Recevoir les notifications

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

app.post(
  "/webhooks/mabipay",
  express.raw({ type: "*/*" }),
  async (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).send("Unauthorized");

    const { event, reference, status } = JSON.parse(req.body.toString());

    if (event === "payment.success") {
      await marquerCommandePayee(reference);
    }

    res.json({ ok: true });
  },
);

6. Passer en production

1. Créez une clé API de production (mbp_live_...)
2. Changez environment: 'live' dans votre config
3. Configurez votre URL de webhook en production
4. Testez un vrai paiement de faible montant (le minimum accepté est 100)

Environnement sandbox

En sandbox, aucun argent réel n'est engagé : les appels sont routés vers l'environnement de test de l'opérateur.

En revanche, les paiements ne se confirment pas tout seuls : le statut évolue via le callback de l'opérateur, exactement comme en production. Vous devez donc aller au bout du parcours de paiement pour observer le passage à success.

Credentials opérateur requis

Chaque environnement exige un credential opérateur actif côté MabiPay. Si aucun credential n'est configuré pour l'environnement de votre clé, l'API répond 503 Service Unavailable.