Dépannage

Symptômes courants et comment les résoudre. Pour la référence complète des erreurs, voir Erreurs & codes de statut.

Authentification

401 Unauthorized à chaque requête

• En-tête manquant/mal formé. Envoyez Authorization: Bearer <token> — le schéma est Bearer, pas Token.
• Jeton expiré. Les jetons API durent 90 jours. Générez-en un nouveau sous Profil → Clés API.
• Jeton révoqué. Si vous l'avez supprimé, il ne peut pas être réutilisé — émettez-en un nouveau.
• Jeton sur une route publique. N'envoyez pas de jeton à signup / verify-email / password-reset — celles-ci rejettent tout jeton avant l'exécution de la vue.

403 Forbidden à la création d'une transaction

Le point de terminaison est réservé aux marchands. Causes :

• Votre compte n'est pas de type marchand, ou
• Vous n'avez pas terminé l'intégration. Complétez votre profil sur /complete-profile (cela provisionne aussi vos portefeuilles).

Création de transactions

400 avec details.currency ou details.service

Le code n'a pas été résolu. Utilisez un code valide, pas un UUID :

• Devise : CDF, USD — listez avec GET /api/organization/currency/.
• Service : Vodacom, Airtel, Orange, Africell — listez avec GET /api/organization/service/. La correspondance est insensible à la casse.

400 avec details.merchant_reference

Vous avez réutilisé un merchant_reference. Il doit être unique par marchand. Soit utilisez une nouvelle référence, soit traitez le 400 comme « ce paiement a déjà été soumis » et retrouvez-le au lieu de réessayer.

400 avec details.merchant

Aucun profil marchand intégré n'est lié à votre compte. Complétez l'intégration sur /complete-profile.

Ma requête est rejetée alors que j'ai envoyé merchant/user/country

Vous n'avez pas besoin de le faire — et vous ne devriez pas. L'identité est dérivée de votre jeton. Envoyez uniquement merchant_reference, amount, currency, service, customer_number, operation (+ callback_url, provider_code_name optionnels). Voir Transactions.

Webhooks

Je ne reçois jamais de callback

• callback_url non définie ou injoignable. Confirmez que vous avez envoyé une callback_url HTTPS valide à la création, et qu'elle est accessible publiquement.
• Réponses non-2xx. Si votre point de terminaison ne renvoie pas 200, la livraison est retentée ; un point de terminaison qui échoue de façon persistante ressemble à « pas de webhook ». Vérifiez vos journaux.
• Toujours manquant ? Rapprochez par interrogation de GET /api/payments/transaction/<reference>/ — voir Rapports.

Je reçois le même callback deux fois

Attendu. Les webhooks sont au moins une fois. Rendez votre gestionnaire idempotent en vous basant sur reference.

Le webhook indique Success mais je n'en suis pas sûr

Ré-interrogez toujours GET /api/payments/transaction/<reference>/ pour confirmer le statut et le montant faisant autorité avant de libérer des biens ou des fonds.

Paiements bloqués en Pending

Pending signifie que le fournisseur a accepté la requête et que le callback final n'est pas encore arrivé. C'est normal pendant une courte fenêtre. Si cela persiste anormalement longtemps, ré-interrogez la transaction ; un 502/provider_error au moment de la sollicitation signifie que le fournisseur a échoué — réessayez ou rapprochez.

Toujours bloqué ?

Collectez les reference / merchant_reference de la requête, le code et le message de la réponse, et l'horodatage, puis contactez le support. Ne partagez jamais votre jeton API.