Passer au contenu principal
Cette page explique comment Fapshi traite les transactions que vous créez, et ce dont votre application est responsable pour garder des statuts de transaction fiables. Lisez-la avant de passer en production avec Initiate Pay, Direct Pay ou Payout.

​
Idempotence et prévention des doublons

Fapshi ne prend pas en charge les clés d’idempotence et n’impose pas l’unicité de externalId (ni de userId). Chaque appel réussi à un endpoint de création de transaction crée une nouvelle transaction indépendante, même si vous envoyez exactement le même corps deux fois.
Cela signifie que :
  • Si vous envoyez deux requêtes Direct Pay avec le même externalId, Fapshi crée deux transactions et envoie deux demandes de paiement au client. Les deux peuvent être payées.
  • Si vous envoyez deux requêtes Payout avec le même externalId, les deux retraits sont effectués.
  • La prévention des doublons est de la responsabilité de votre application.

​
Approche recommandée

  1. Générez un externalId unique dans votre système pour chaque tentative de paiement (par ex. l’ID de commande suivi d’un numéro de tentative) et enregistrez-le avant d’appeler Fapshi.
  2. Envoyez toujours aussi un userId. C’est ce qui vous permet de retrouver la transaction plus tard si vous ne recevez jamais la réponse (voir ci-dessous).
  3. Enregistrez le transId renvoyé par Fapshi avec votre externalId dès que vous le recevez.
  4. Ne créez pas de nouvelle transaction pour une commande qui en a déjà une au statut CREATED, PENDING ou SUCCESSFUL.

​
Réessayer après un timeout ou une réponse perdue

Si une requête de création de transaction expire (timeout) ou si vous ne recevez jamais sa réponse, ne la renvoyez pas aveuglément. La transaction existe peut-être déjà. À la place :
  1. Appelez GET /transaction/{userId} avec le userId que vous avez envoyé.
  2. Cherchez une transaction dont le externalId correspond à celui que vous avez envoyé.
  3. Si vous la trouvez, enregistrez son transId et continuez à suivre cette transaction. Ne réessayez pas.
  4. Si vous ne la trouvez pas, la transaction n’a pas été créée et vous pouvez renvoyer la requête en toute sécurité.
Une transaction est renvoyée par GET /transaction/{userId} dès sa création (statut CREATED). Vous pouvez donc faire cette vérification immédiatement, même si la réponse initiale de l’API a été perdue.

​
Statuts des transactions

  • Les transactions Direct Pay n’expirent jamais. Leur état final est toujours SUCCESSFUL ou FAILED.
  • Les liens de paiement expirent au bout de 24 heures. D’ici là, un client peut réessayer sur le même lien après une tentative échouée.
Pour suivre les changements de statut, utilisez les webhooks comme signal principal et GET /payment-status/{transId} pour confirmer un statut ou récupérer une notification manquée.

​
Transactions échouées

Un statut FAILED n’indique pas pourquoi un paiement a échoué. Fapshi ne fait pas de distinction entre un paiement refusé, un solde insuffisant, une demande annulée ou une demande ignorée par le client. Les messages renvoyés par les opérateurs mobile money sont généralement vagues, ce qui empêche de déterminer la cause exacte avec certitude.
Traitement recommandé :
  • Considérez FAILED comme le résultat final de cette transaction.
  • Affichez un message générique au client (par ex. « Le paiement n’a pas pu être effectué. Veuillez vérifier votre solde et réessayer. »).
  • Si le client souhaite réessayer, créez une nouvelle transaction avec un nouvel externalId.

​
Liste de contrôle du rapprochement

​
Montants et frais

  • Fapshi ne collecte pas de paiements partiels. Fapshi collecte toujours la totalité du montant (amount) que vous transmettez à l’API ; une transaction SUCCESSFUL signifie donc toujours que ce montant exact a été collecté.
  • Les frais de transaction de Fapshi sont de 3 % du montant payé.
  • Les frais sont identiques pour tous les moyens de paiement (MTN Mobile Money et Orange Money) et ne varient pas selon le volume de transactions.
  • Le champ revenue d’une transaction correspond à ce que vous recevez après déduction des frais Fapshi :
Par exemple, un paiement réussi de 10 000 XAF a un revenue de 9 700 XAF. Pour les délais de règlement et les autres questions de tarification, consultez la FAQ Fapshi.

​
Remboursements

Fapshi ne dispose pas d’API de remboursement dédiée. Pour rembourser un client, envoyez-lui l’argent avec l’endpoint Payout, en utilisant un service distinct activé pour les retraits. Le remboursement est payé depuis le solde de votre service de retrait, et non depuis le service de collecte qui a reçu le paiement initial. Assurez-vous d’abord que le service de retrait est alimenté (transfert instantané et gratuit depuis votre service de collecte, ou rechargement) ; voir Alimenter votre service de retrait.
Les retraits sont désactivés par défaut en environnement live et doivent être activés. Les conditions et restrictions sont décrites sur la page de l’endpoint Payout. Les retraits sont soumis à la même règle que les paiements : Fapshi n’empêche pas les retraits en double, appliquez donc la même approche de prévention des doublons décrite ci-dessus.

​
Moyens de paiement pris en charge

L’API prend en charge uniquement MTN Mobile Money et Orange Money (ainsi que les comptes Fapshi comme destination de retrait). Il n’est pas prévu d’ajouter d’autres réseaux de paiement à court terme.
Besoin d’aide ? Contactez-nous via support@fapshi.com ou visitez notre Centre d’aide et de support.