Questions fréquentes

Puis-je appeler l’API depuis mon site web (JavaScript du navigateur) ou mon application mobile ?

Non. Les appels demandent votre secret (sk_…), qui ne doit jamais être visible d’un client. Votre navigateur ou votre application mobile appelle votre serveur, et c’est votre serveur qui appelle MafPay (voir le Guide complet).

Le client dit qu’il a payé, mais ma commande est toujours « en attente ». Que faire ?

Interrogez le statut : GET /payments/{reference}/status/ (Suivre un paiement). Si c’est SUCCESS, validez la commande : votre serveur a simplement raté la notification.
Vérifiez que votre webhook_url est correcte, publique et en HTTPS, et que votre serveur répond 200 (regardez vos logs : recevez-vous l’appel ? la signature est-elle acceptée ?).
Vérifiez que vous utilisez le bon secret pour la signature : sk_test_… pour un paiement sandbox, sk_live_… pour un paiement live.

Je n’ai pas eu de réponse à l’initiation (coupure, timeout). Puis-je relancer le paiement ?

Vous ne savez pas si le paiement a été créé. Ne créez pas un nouveau paiement à l’aveugle. Le plus sûr :

Enregistrez votre commande avant d’appeler MafPay, avec un statut « en attente ».
Si la réponse est perdue, attendez les notifications : si un paiement a été créé, vous recevrez ses notifications avec votre metadata.order_id.
Sinon, après l’expiration du délai, créez un nouveau paiement pour la même commande.

Un paiement en double non payé est sans conséquence : il expirera. Ce qu’il faut éviter, c’est livrer deux fois : c’est pourquoi une commande ne doit passer à « payée » qu’une seule fois (idempotence).

Combien de temps un paiement reste-t-il valable ?

Regardez expires_at dans la réponse d’initiation : chaque opérateur fixe sa durée (de quelques minutes à environ une demi-heure). Passé ce délai, le paiement devient EXPIRED : créez-en un nouveau.

Quelle devise utiliser ?

XOF (franc CFA), qui est la valeur par défaut. Envoyez des montants entiers (obligatoire avec Orange Money).

Comment retrouver ma commande dans une notification ?

Grâce à metadata : mettez { "order_id": 123 } à l’initiation, vous le retrouvez dans data.metadata de chaque notification et dans les réponses.

Puis-je rembourser un paiement ?

Le statut REFUNDED existe et vous serait notifié (transaction.refunded), mais cette API ne propose pas (pour l’instant) de route de remboursement : contactez le support MafPay.

Puis-je utiliser plusieurs applications ?

Oui, et c’est recommandé : une application par site ou produit, et une application dédiée aux tests. Chacune a ses propres clés, ses propres adresses de notification et son propre mode (sandbox / live). Le nombre d’applications par entreprise est limité (10 par défaut).

Pourquoi mes clés `_test_` ne marchent plus ?

Votre application est passée en live : elle n’accepte plus que les clés _live_. Pour continuer à tester, créez une application de test (Sandbox et live).

Mon serveur reçoit deux fois la même notification. Est-ce normal ?

Oui : MafPay réessaie si votre réponse n’est pas un 2xx, ou tarde plus de 15 secondes. Reconnaissez les doublons avec le champ id (Webhooks) et répondez 200 dans tous les cas.

Existe-t-il une documentation interactive ?

Oui : la documentation technique de l’API (Swagger) est disponible à l’adresse {adresse de l'API}/api/docs/. Elle permet d’essayer les routes depuis le navigateur.

Où trouver de l’aide ?

Contactez le support MafPay en précisant : la reference du paiement, l’environnement (sandbox ou live), l’heure approximative et le message d’erreur reçu. Ne communiquez jamais votre secret sk_….