Webhooks

Format d'un événement

Mobupay envoie une requête POST à votre endpoint avec un body JSON :

{
  "id": "evt_2NjK8mLk0093xY",
  "type": "payment.authorized",
  "createdAt": "2026-05-14T12:34:56Z",
  "data": {
    "paymentId": "pay_xxxxxxxx",
    "amount": 1000,
    "currency": "XPF",
    "status": "transit",
    "reference": "SPR-xxxxxxxx",
    "customerId": "cus_xxxxxxxx",
    "customerCreated": true,
    "paymentMethodId": "pm_xxxxxxxx",
    "cardBrand": "CB",
    "cardLast4": "0007"
  }
}

Quand un client est créé pendant le paiement (paramètre saveCustomer), le champ customerId contient l'identifiant créé et customerCreated vaut true. Si une carte est enregistrée au passage, paymentMethodId est fourni.

Répondez 2xx dans les 10 secondes pour acquitter la réception. Tout autre code (4xx/5xx) ou timeout déclenchera un retry.

Détail des commissions dans l'événement

Les événements payment.authorized, payment.captured, payment.refunded, payment.partially_refunded et payment.cancelled portent un bloc settlement : la commission Mobupay, le net, et la composition ligne par ligne. Vous n'avez pas besoin de rappeler l'API pour savoir ce qui vous a été facturé.

"settlement": {
  "capturedAmount": 9479,
  "mobupayCommission": 165,
  "netAmount": 9314,
  "currency": "XPF",
  "settled": false,
  "detailedFees": [
    {
      "id": "spirit_commission",
      "label": "Commission sur encaissement",
      "type": "PERCENTAGE",
      "rate": 140,
      "amount": 132, "amountEur": 111,
      "taxAmount": 8, "taxAmountEur": 7,
      "taxes": [{ "id": "TGC6", "type": "PERCENTAGE", "value": 600, "amount": 8, "amountEur": 7 }],
      "totalAmount": 141, "totalAmountEur": 118
    },
    { "id": "spirit_fixed_fee", "label": "Frais fixe par transaction", "totalAmount": 16, "totalAmountEur": 13 },
    { "id": "authorization_result", "label": "Autorisation (capture différée)", "totalAmount": 8, "totalAmountEur": 7 }
  ]
}

Les montants sont dans la devise d'origine du paiement ; les champs amountEur portent la valeur exacte en centimes d'euro. La grille tarifaire étant en euros, chaque ligne est convertie puis arrondie au franc : la somme des totalAmount peut donc dépasser mobupayCommission d'un franc. Pour un rapprochement comptable exact, additionnez les totalAmountEur.

settled: false signifie que le règlement de l'acquéreur n'est pas encore parvenu : les lignes décrivent la facturation engagée. Les frais déjà prélevés ne sont pas restitués par un remboursement, qui ajoute sa propre ligne. Sur un paiement de place de marché, chaque entrée de platformDistribution porte de la même façon son detailedCommission.

Liste des événements

Événements de facturation

Émis par le module Facturation, pour les factures dont vous êtes l'émetteur. Ils évitent d'interroger l'API en boucle pour savoir si une facture a été réglée.

La charge utile porte les identifiants, le statut, les montants et le reste dû, mais jamais les lignes ni l'identité de votre client : ces données ne traversent pas le réseau sans nécessité. Pour le détail complet, appelez GET /billing/invoices/{id}, qui sert toujours l'état courant, alors qu'un webhook peut arriver dans le désordre.

Événements plateforme

Si vous êtes une plateforme (marketplace), abonnez-vous à ces événements pour suivre le cycle de vie de vos sous-marchands affiliés : invitation, onboarding KYB, ouverture du compte de paiement et rattachement.

Vérification de signature

Chaque requête webhook contient un header X-Mobupay-Signature avec une signature HMAC-SHA256 du body. Vérifiez-la avant de traiter l'événement pour vous protéger des requêtes forgées.

Exemple Node.js :

import crypto from "node:crypto";

const SECRET = process.env.MOBUPAY_WEBHOOK_SECRET;

function verifySignature(rawBody, signature) {
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

app.post("/webhook", (req, res) => {
  const signature = req.headers["x-mobupay-signature"];
  if (!verifySignature(req.rawBody, signature)) {
    return res.status(401).send("Invalid signature");
  }
  const event = JSON.parse(req.rawBody);
  // ... traiter l'event
  res.sendStatus(200);
});

Important : utilisez le body brut (non-parsé) pour calculer la signature. Un body re-serialisé par JSON.stringify peut produire un hash différent.

Signature V2 (anti-rejeu, recommandée)

En plus de X-Mobupay-Signature (V1, HMAC du corps), chaque livraison porte X-Mobupay-Timestamp (epoch secondes) et X-Mobupay-Signature-V2 = HMAC-SHA256 de {timestamp}.{corps}. Le timestamp étant signé, une requête interceptée ne peut pas être rejouée plus tard : rejetez-la si l'horodatage dépasse votre fenêtre de tolérance (5 min recommandé).

import crypto from "node:crypto";

function verifyV2(rawBody, headers, secret, toleranceSec = 300) {
  const ts = headers["x-mobupay-timestamp"];
  const sig = headers["x-mobupay-signature-v2"];
  if (!ts || !sig) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false; // anti-rejeu
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

V1 reste émise pour compatibilité. Les nouveaux intégrateurs (connecteurs e-commerce) doivent vérifier V2 + la fraîcheur du timestamp.

Politique de retry

Idempotence côté receiver

À cause des retry, un même événement peut être livré plusieurs fois. Utilisez le champ id (préfixe evt_) pour dédupliquer côté serveur : stockez les IDs déjà traités et ignorez les doublons.