mainpay-africa

SDK officiel Node.js pour l'API MainPay Africa.

Intégrez les paiements MainPay Africa dans votre application en quelques minutes.

Installation

npm install mainpay-africa

Aucune dépendance externe — utilise uniquement les modules Node.js natifs.

Démarrage rapide

const MainPay = require('mainpay-africa');

const mainpay = new MainPay({
  apiKey        : process.env.MAINPAY_API_KEY,    // mp_live_xxx
  webhookSecret : process.env.MAINPAY_WEBHOOK_SECRET, // whsec_xxx
});

// 1. Créer une session de paiement
const session = await mainpay.checkout.create({
  type           : 'payment',
  amount         : 50000,          // 50 000 GNF
  currency       : 'GNF',
  country        : 'GN',
  description    : 'Abonnement Premium',
  returnUrl      : 'https://votreapp.com/paiement/retour',
  webhookUrl     : 'https://votreapp.com/webhooks/mainpay',
  idempotencyKey : `order_${orderId}`,
});

// 2. Rediriger l'utilisateur
res.redirect(session.checkoutUrl);

Recevoir les webhooks

// ⚠️ express.raw() OBLIGATOIRE sur la route webhook — NE PAS utiliser express.json()
app.post('/webhooks/mainpay', express.raw({ type: 'application/json' }), (req, res) => {
  const isValid = mainpay.webhooks.verify({
    signature : req.headers['x-mainpay-signature'],
    timestamp : req.headers['x-mainpay-timestamp'],
    rawBody   : req.body,  // Buffer brut
  });

  if (!isValid) return res.status(400).send('Signature invalide');

  const event = JSON.parse(req.body);

  if (event.event === 'transaction.completed') {
    // Débloquer le service pour l'utilisateur
    await activateSubscription(event.metadata.userId);
  }

  res.sendStatus(200);
});

Versement direct (payout)

// Verser des gains directement dans le wallet d'un utilisateur
const payout = await mainpay.payouts.create({
  accountNumber  : 'GN12345678',
  amount         : 25000,
  currency       : 'GNF',
  country        : 'GN',
  description    : 'Gains semaine 18',
  idempotencyKey : `payout_user123_week18`,
});

console.log(payout.status); // 'completed'

Remboursement

const refund = await mainpay.refunds.create({
  sessionId      : 'sess_xyz789',
  idempotencyKey : `refund_sess_xyz789`,
  reason         : 'Commande annulée par le client',
});

Gestion des erreurs

const { MainPayError, MainPayAuthError, MainPayRateLimitError } = require('mainpay-africa');

try {
  const session = await mainpay.checkout.create({ ... });
} catch (err) {
  if (err instanceof MainPayAuthError) {
    console.error('Clé API invalide');
  } else if (err instanceof MainPayRateLimitError) {
    console.error(`Rate limit — réessayer dans ${err.retryAfter}s`);
  } else if (err instanceof MainPayError) {
    console.error(`Erreur API [${err.code}]: ${err.message}`);
  } else {
    console.error('Erreur réseau:', err.message);
  }
}

Sandbox (test)

Utilisez une clé mp_test_xxx — aucun vrai argent n'est débité.

Compte de test : GN00000001 — PIN : 000000

Documentation

• Guide démarrage
• Référence API complète
• Webhooks
• Sandbox

Support

• Email : [email protected]
• GitHub Issues : mainpayafrica/mainpay-node