> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fapshi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestion des transactions

> Comment éviter les paiements en double, réessayer en toute sécurité, rapprocher les résultats incertains, gérer les échecs et comprendre les frais et remboursements avec l’API Fapshi.

***

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](https://docs.fapshi.com/fr/api-reference/endpoint/initiate-pay.md), [Direct Pay](https://docs.fapshi.com/fr/api-reference/endpoint/direct-pay.md) ou [Payout](https://docs.fapshi.com/fr/api-reference/endpoint/payout.md).

## Idempotence et prévention des doublons

> [!WARNING]
>
> 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](https://docs.fapshi.com/fr/api-reference/endpoint/direct-pay.md) 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](https://docs.fapshi.com/fr/api-reference/endpoint/payout.md) 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}`](https://docs.fapshi.com/fr/api-reference/endpoint/transaction-by-user) 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é.

> [!NOTE]
>
> Une transaction est renvoyée par [`GET /transaction/{userId}`](https://docs.fapshi.com/fr/api-reference/endpoint/transaction-by-user) 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

| Statut | Final ? | Signification |
| :- | :- | :- |
| CREATED | Non | La transaction existe mais aucune tentative de paiement n’a encore été faite. |
| PENDING | Non | Le client est en train de payer (par ex. une demande de paiement a été envoyée sur son téléphone). |
| SUCCESSFUL | Oui | Le paiement est terminé. La **totalité du montant transmis à l’API** a été collectée (Fapshi ne collecte pas de paiements partiels). |
| FAILED | Oui pour Direct Pay | La tentative de paiement a échoué. Voir [Transactions échouées](#transactions-échouées). |
| EXPIRED | Oui | Uniquement pour les liens de paiement : 24 heures se sont écoulées sans paiement réussi, ou le lien a été [expiré manuellement](https://docs.fapshi.com/fr/api-reference/endpoint/expire-pay.md). |

* Les transactions [Direct Pay](https://docs.fapshi.com/fr/api-reference/endpoint/direct-pay.md) n’expirent jamais. Leur état final est toujours `SUCCESSFUL` ou `FAILED`.
* Les [liens de paiement](https://docs.fapshi.com/fr/api-reference/endpoint/initiate-pay.md) 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](https://docs.fapshi.com/fr/api-reference/endpoint/webhook.md) comme signal principal et [`GET /payment-status/{transId}`](https://docs.fapshi.com/fr/api-reference/endpoint/payment-status) pour confirmer un statut ou récupérer une notification manquée.

## Transactions échouées

> [!WARNING]
>
> 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

| Situation | Que faire |
| :- | :- |
| La requête de création a expiré / réponse perdue | Recherchez par `userId` + `externalId` comme décrit dans [Réessayer après un timeout](#réessayer-après-un-timeout-ou-une-réponse-perdue). |
| Vous avez un `transId` mais aucun webhook reçu | Appelez [`GET /payment-status/{transId}`](https://docs.fapshi.com/fr/api-reference/endpoint/payment-status). Les webhooks ne sont pas renvoyés automatiquement. |
| Vous voulez passer en revue de nombreuses transactions | Utilisez [`GET /search`](https://docs.fapshi.com/fr/api-reference/endpoint/search-transactions) (statut, moyen, période, montant). |
| Un webhook n’a pas atteint votre serveur | Renvoyez-le manuellement depuis le tableau de bord Fapshi, ou consultez le statut du paiement. Voir [Webhooks](https://docs.fapshi.com/fr/api-reference/endpoint/webhook.md). |
| `GET /payment-status/{transId}` renvoie 400 ou 404 | Le `transId` est invalide ou n’a jamais été émis par Fapshi. Voir [Statut de paiement](https://docs.fapshi.com/fr/api-reference/endpoint/payment-status.md#réponses-derreur). |

## 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 :

```
revenue = amount − frais      (frais = 3 % de amount)
```

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](https://www.fapshi.com/fr/faq).

## Remboursements

Fapshi ne dispose **pas** d’API de remboursement dédiée. Pour rembourser un client, envoyez-lui l’argent avec l’[endpoint Payout](https://docs.fapshi.com/fr/api-reference/endpoint/payout.md), 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](https://docs.fapshi.com/fr/api-reference/endpoint/payout.md#alimenter-votre-service-de-retrait).

> [!NOTE]
>
> 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](https://docs.fapshi.com/fr/api-reference/endpoint/payout.md). 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](mailto:support@fapshi.com) ou visitez notre [Centre d’aide et de support](https://fapshi.com/fr/aide-et-support).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.