API de Paiement avec Coffre-fort

Démarrage rapide

Intégrez MayfiPay en quelques minutes.

1. Connectez-vous sur app.mayfipay.com
2. Profil → API & Intégration → + Nouveau projet
3. Copiez votre clé mfp_live_xxx

curl -X POST https://api.mayfipay.com/v1/payments \
  -H "Authorization: Bearer mfp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "description": "T-shirt Nike XL",
    "external_id": "order_12345",
    "customer": { "phone": "+242065123456", "name": "Jean Dupont" },
    "return_url": "https://monsite.com/success"
  }'

// Réponse → récupérer checkout_url
window.location.href = response.data.checkout_url;

// Votre serveur reçoit POST sur votre webhook_url
{
  "event": "payment.success",
  "data": { "order_number": "MONSITE-0042", "status": "payee" }
}

Environnements : Sandbox & Live

MayfiPay propose deux environnements. La différence est uniquement dans la clé API utilisée — la même URL de base pour les deux.

https://api.mayfipay.com/v1

1. Connectez-vous sur app.mayfipay.com
2. Profil → API & Intégration → créez un projet et copiez la clé live (mfp_...)
3. Ouvrez le projet → onglet Sandbox → « Activer le sandbox » pour générer une clé de test (mfp_test_...) rattachée au projet

• Avec une clé de test, checkout_url pointe vers une page MayfiPay de simulation (aucun appel Mobile Money)
• Le client clique « Payer » ou « Simuler un échec » — la commande change de statut comme en réel
• Après un paiement simulé réussi, la page affiche le code de livraison à 6 chiffres pour tester la libération des fonds ; ce code est aussi inclus dans le payload du webhook (data.code_livraison)
• Votre webhook reçoit un vrai événement signé (payment.success / payment.failed) avec "sandbox": true
• Aucun argent réel, aucune commission — l'escrow n'est pas déclenché sur les commandes test, et elles n'apparaissent jamais dans vos statistiques

# .env
MAYFIPAY_API_KEY=mfp_live_xxx   # Production
# MAYFIPAY_API_KEY=mfp_test_xxx  # Sandbox

Systeme Coffre-fort (Escrow)

MayfiPay protege acheteurs et vendeurs grace au coffre-fort securise.

// 1. Client paie sur votre site
Client -> Paiement Mobile Money -> MayfiPay

// 2. Argent securise dans le coffre-fort
MayfiPay -> Coffre-fort (l'argent ne va PAS au vendeur)

// 3. SMS envoye au client avec code 6 chiffres
"Votre code livraison: 847293. Donnez-le au vendeur apres reception."

// 4. Vendeur livre le produit
Vendeur -> Livre -> Demande le code au client

// 5. Vendeur entre le code
POST /v1/confirm { "order_number": "MONSITE-0042", "code": "847293" }

// 6. Argent libere vers le vendeur
Coffre-fort -> Portefeuille vendeur -> Retrait Mobile Money

Si le code n'est pas entre dans les 7 jours et qu'aucun litige n'est ouvert, l'argent est automatiquement rembourse a l'acheteur.

Authentification

Toutes les requetes API necessitent votre cle API dans le header Authorization.

Authorization: Bearer mfp_votre_cle_api
Content-Type: application/json

1. Creez un compte vendeur sur app.mayfipay.com
2. Completez votre KYC
3. Profil → API & Intégration → + Nouveau projet
4. Configurez votre prefix de commandes (ex: "MONSITE")

Rate limits

Idempotence

Utilisez le header Idempotency-Key pour éviter les doublons en cas de retry réseau.

• Si le header Idempotency-Key est envoyé et qu'une requête avec cette même clé existe déjà → retourne la réponse originale (HTTP 200) sans créer de nouveau paiement
• Si aucun header n'est fourni → chaque requête crée un nouveau paiement
• L'idempotence est garantie pendant 24 heures après la création
• La clé est propre à votre clé API : deux marchands peuvent utiliser la même valeur sans collision

// Utilisez l'ID de votre commande comme clé d'idempotence
POST /v1/payments
Authorization: Bearer mfp_xxx
Idempotency-Key: order_12345

{
  "external_id": "order_12345",  // Reference de commande (informatif)
  "amount": 10000,
  ...
}

Frais

Structure tarifaire simple et transparente.

Produit: 10 000 FCFA

Acheteur paie:     10 350 FCFA (10 000 + 3.5%)
Vendeur recoit:     9 700 FCFA (10 000 - 3% commission)
Apres retrait:      9 506 FCFA (9 700 - 2% frais retrait)

Creer un paiement

Cree une commande avec coffre-fort et retourne une URL de checkout.

POST /v1/payments
Authorization: Bearer mfp_xxx

{
  "amount": 10000,
  "description": "T-shirt Nike XL",
  "external_id": "order_12345",
  "customer": {
    "phone": "+242065123456",
    "name": "Jean Dupont"
  },
  "return_url": "https://monsite.com/success",
  "webhook_url": "https://monsite.com/webhook"
}

{
  "success": true,
  "data": {
    "payment_id": "pay_abc123",
    "order_number": "MONSITE-0042",
    "checkout_url": "https://checkout.moneroo.io/pay_abc123",
    "tracking_url": "https://mayfipay.com/s/MONSITE-0042?t=xxx",
    "amount": 10000,
    "fees": 350,
    "total": 10350,
    "status": "pending",
    "expires_at": "2026-07-09T12:00:00Z"
  }
}

Consulter un paiement

Recupere le statut d'une commande. L'identifiant accepte trois formats : le payment_id, le numero de commande (order_number) ou votre reference external_id.

curl "https://api.mayfipay.com/v1/payments?id=MONSITE-0042" \
  -H "Authorization: Bearer mfp_xxx"

curl https://api.mayfipay.com/v1/payments/MONSITE-0042 \
  -H "Authorization: Bearer mfp_xxx"

{
  "success": true,
  "data": {
    "payment_id": "pay_abc123",
    "order_number": "MONSITE-0042",
    "external_id": "order_12345",
    "amount": 10000,
    "fees": 350,
    "total": 10350,
    "currency": "XAF",
    "status": "payee",   // pending | payee | livree | annulee | expire
    "description": "T-shirt Nike XL",
    "customer": {
      "name": "Jean Dupont",
      "phone": "+242065123456"
    },
    "tracking_url": "https://mayfipay.com/s/MONSITE-0042?t=xxx",
    "created_at": "2026-08-01T12:00:00Z",
    "paid_at": "2026-08-01T12:03:41Z",
    "expires_at": "2026-08-08T12:00:00Z"
  }
}

En cas de commande inexistante ou n'appartenant pas à votre clé API : HTTP 404 {"success": false, "error": "Order not found"}.

Confirmer la livraison

Le vendeur entre le code donne par l'acheteur pour liberer l'argent du coffre-fort.

POST /v1/confirm
Authorization: Bearer mfp_xxx

{
  "order_number": "MONSITE-0042",
  "code": "847293"
}

{
  "success": true,
  "message": "Livraison confirmee, argent libere",
  "data": {
    "order_number": "MONSITE-0042",
    "status": "livree",
    "vendor_amount": 9700
  }
}

Gestion des sous-vendeurs (Marketplace)

Si votre projet est en mode Marketplace, vous pouvez ajouter des sous-vendeurs qui recevront leur part automatiquement.

POST /v1/vendors
Authorization: Bearer mfp_xxx

{
  "external_id": "vendor_123",
  "name": "Boutique Mode CG",
  "phone": "+242066789012",
  "email": "[email protected]"
}

{
  "success": true,
  "data": {
    "external_id": "vendor_123",
    "name": "Boutique Mode CG",
    "status": "invited",
    "invite_url": "https://mayfipay.com/join/xxx"
  }
}

Le sous-vendeur recoit un SMS d'invitation pour creer son compte MayfiPay. Une fois connecte, il recoit automatiquement sa part des ventes.

Vente: 10 000 FCFA avec service_fee: 1000

Coffre-fort recu: 10 000 FCFA
                    |
                    v
Apres confirmation livraison:
  - MayfiPay: 300 FCFA (3%)
  - Marketplace: 1 000 FCFA (service_fee)
  - Sous-vendeur: 8 700 FCFA

Webhooks

MayfiPay envoie des notifications a votre URL webhook configuree.

{
  "event": "payment.success",
  "data": {
    "order_number": "MONSITE-0042",
    "external_id": "order_12345",
    "amount": 10000,
    "status": "payee",
    "customer": {
      "name": "Jean Dupont",
      "phone": "+242065123456"
    },
    "tracking_url": "https://mayfipay.com/s/MONSITE-0042?t=xxx"
  }
}

Chaque webhook envoyé par MayfiPay inclut un header X-MayfiPay-Signature contenant un HMAC-SHA256 du corps de la requête, signé avec votre secret webhook. Validez toujours cette signature avant de traiter un webhook — sans ça, n'importe qui peut usurper un événement payment.success.

// Node.js — Vérification de signature
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

// Dans votre route POST /webhook :
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-mayfipay-signature'];
  const secret = process.env.MAYFIPAY_WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req.body, sig, secret)) {
    return res.status(401).json({ error: 'Signature invalide' });
  }

  const event = JSON.parse(req.body);
  if (event.event === 'payment.success') {
    // Mettre à jour votre commande
  }

  res.json({ received: true }); // Répondre 200 sous 30s
});

Retrait vers Mobile Money

Le sous-vendeur d'une marketplace transfère ses fonds disponibles (portefeuille MayfiPay) vers son numéro Mobile Money.

POST /v1/payouts
Authorization: Bearer mfp_live_xxx

{
  "user_id": "uuid-du-sous-vendeur",
  "amount": 50000,
  "phone": "+242065123456"
}

{
  "success": true,
  "data": {
    "withdrawal_id": "uuid-retrait",
    "amount": 50000,
    "frais": 1000,
    "montant_net": 49000,
    "phone": "+242065123456",
    "status": "en_cours"
  }
}

Suivi de commande (côté client)

Chaque commande possède une URL de suivi publique, fournie dans la réponse de création (tracking_url) et dans le webhook payment.success. Aucune authentification n'est nécessaire — le token dans l'URL fait foi.

https://mayfipay.com/s/{order_number}?t={suivi_token}

• Statut en temps réel : en attente → payée → livrée (ou annulée/expirée)
• Montant, description et date de la commande
• Le code de livraison à 6 chiffres s'affiche uniquement après paiement réussi

Plugin WordPress / WooCommerce

Integrez MayfiPay sur votre site WordPress en 5 minutes. Compatible avec les plugins multi-vendeurs (Dokan, WCFM, WC Vendors).

• Paiement Mobile Money (MTN, Airtel)
• Coffre-fort securise automatique
• Code livraison par SMS
• Dashboard admin pour confirmer les livraisons
• Mode Marketplace avec commissions
• Invitation automatique des sous-vendeurs

1. Telechargez le plugin
2. Dans WordPress: Extensions > Ajouter > Televerser
3. Activez le plugin
4. Allez dans MayfiPay > Configuration
5. Entrez votre cle API
6. C'est pret!

Si vous utilisez Dokan, WCFM ou WC Vendors, le plugin detecte automatiquement les nouveaux vendeurs et leur envoie une invitation pour creer leur compte MayfiPay.

Codes d'erreur