Démarrer

API MivaaPay

MivaaPay est une plateforme d'agrégation de paiement en Afrique de l'Ouest et centrale. Une seule intégration vous donne accès au Mobile Money de sept pays et au paiement par carte, avec les reversements, les remboursements et les webhooks gérés pour vous.

Authentification Récupérer vos clés API et signer vos requêtes. Mode test Intégrer et valider sans qu'un centime ne bouge. Premier paiement Encaisser un client en Mobile Money en trois appels. Webhooks Être notifié quand un paiement change d'état. Référence API Les 16 endpoints, paramètre par paramètre.

URL de base

Toutes les requêtes se font en HTTPS sur :

URL de base

https://api.mivaapay.com/api/v1

Dans cette documentation, les chemins sont notés en relatif à cette base : POST /payments désigne POST https://api.mivaapay.com/api/v1/payments.

Commencez en mode test

Chaque compte dispose de deux jeux de clés. Une clé sk_test_… vous donne un bac à sable complet : paiements, remboursements et webhooks signés, sans qu'un centime ne bouge. Le passage en production ne change qu'une variable d'environnement. Voir Mode test.

Format des réponses

Toutes les réponses sont en JSON et suivent la même enveloppe. Une réponse réussie porte success: true et place la ressource dans data :

Réponse — succès

{
  "success": true,
  "data": {
    "reference": "9f2c1a44-8b0e-4b2e-9b0a-2f1d6e5c7a31",
    "status": "pending",
    "amount": 5000
  }
}

Une erreur porte success: false et un objet error exploitable par programme :

Réponse — erreur

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Les données envoyées sont invalides.",
    "details": {
      "amount": ["Le champ amount est obligatoire."]
    }
  }
}

Testez toujours error.code, jamais error.message : les messages sont rédigés pour être lus par un humain et peuvent être reformulés sans préavis. La liste complète des codes est sur la page Erreurs.

Pagination

Les endpoints de liste (GET /payments, GET /refunds, GET /payment-links, GET /webhooks/deliveries) renvoient la page courante dans data et les compteurs dans meta. Le paramètre per_page vaut 25 par défaut et est plafonné à 100 ; page commence à 1.

Réponse paginée

{
  "success": true,
  "data": [ /* … */ ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 134,
    "last_page": 6
  }
}

Montants et devises

Les montants sont exprimés en unité principale de la devise, pas en centimes : "amount": 5000 signifie 5 000 XOF. Le XOF et le XAF n'ont pas de subdivision, n'envoyez donc pas de décimales pour ces devises.

Devises acceptées : XOF (défaut), XAF, EUR, USD.

Qui paie les frais

Le champ amount est ce que vous encaissez. La commission MivaaPay s'ajoute par-dessus et c'est le client qui la règle : il est débité de total_amount = amount + fee_amount. Vous pouvez calculer ce total avant de créer le paiement avec POST /payment-modes/fees.

Limites de débit

L'API accepte 120 requêtes par minute et par adresse IP. Au-delà, elle répond 429 avec le code rate_limited ; les en-têtes X-RateLimit-Remaining et Retry-After indiquent quand réessayer. Espacez vos appels de suivi (voir Suivre un paiement) ou, mieux, branchez les webhooks plutôt que d'interroger l'API en boucle.

Versionnage

La version fait partie de l'URL. v1 est la version courante et son contrat est stable : nous pouvons ajouter des champs à une réponse ou des paramètres optionnels à une requête, mais jamais retirer ni renommer l'existant. Écrivez donc votre intégration de façon à ignorer les champs inconnus. Toute rupture donnerait lieu à une v2, l'ancienne restant servie.

Ce que couvre l'API

Domaine	Ce que vous pouvez faire
Encaissements	Débiter un client en Mobile Money ou par carte, consulter et lister vos paiements.
Remboursements	Demander le remboursement intégral d'un paiement validé.
Liens de paiement	Générer une page de paiement hébergée, sans écrire de code côté client.
Catalogue	Lister les opérateurs disponibles par pays et simuler les frais.
Portefeuille	Consulter le solde disponible avant reversement.
Webhooks	Configurer votre endpoint, tester l'envoi et consulter le journal des livraisons.

Besoin d'aide

Écrivez à support@mivaapay.com en joignant la reference du paiement concerné : c'est ce qui nous permet de retrouver l'échange exact avec l'opérateur.