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

# Paiements

> Un paiement est la trace d'un encaissement : montants, commission, moyen de paiement et statut.

Un **paiement** est créé lorsqu'un client valide une session de checkout, ou directement via `POST /api/v1/payments`. Son `id` commence par `pay_`. Il vous est consultable via l'API et dans le tableau de bord.

## Montants

Pour un paiement de 5 000 XAF réglé par mobile money :

| Champ | Valeur | Signification |
| - | - | - |
| `amount` | 5000 | Montant payé par le client |
| `fee_amount` | 175 | Frais retenus |
| `net_amount` | 4825 | Ce qui est crédité à votre solde |

Ce sont les mêmes noms que sur un retrait. Seul `net_amount` compte pour votre solde.

## Moyen de paiement

* `payment_method` : `mobile_money` ou `card`.
* Pour le mobile money, `mobile_money_country` et `mobile_money_provider` indiquent le pays et l'opérateur, par exemple `CMR` et `MTN_MOMO_CMR`.

Un opérateur mobile money ne déplace que sa propre devise nationale : si le pays choisi a une devise différente de celle demandée, le montant est converti automatiquement avant l'encaissement, et `currency` et `amount` reflètent le montant réellement prélevé dans la devise de l'opérateur. Une carte, elle, encaisse toujours exactement la devise demandée, sans conversion.

## `next_action`

Un paiement né d'une session de checkout ou d'une charge directe (`POST /api/v1/payments`) porte toujours un champ `next_action` : `null` quand il n'y a rien de plus à faire côté client (le mobile money aujourd'hui), ou un objet `{"type": "...", ...}` quand votre frontend doit terminer quelque chose pour confirmer le paiement. Pour une carte, `type` est `"card_payment"`. Décidez toujours sur `type`, jamais sur la seule présence du champ : un futur moyen de paiement introduira son propre `type` sans jamais changer la forme de ceux déjà documentés.

## Statuts

| Statut | Signification |
| - | - |
| `pending` | Enregistré, en attente de confirmation |
| `processing` | Accepté, en cours de traitement |
| `succeeded` | Encaissé : le solde est crédité |
| `failed` | Refusé ou en échec, voir `failure_code` (code stable à tester) et `failure_reason` (texte français à afficher), voir [la liste complète](https://docs.mercy-pay.com/api/payments/create.md#failure_code). Une carte peut encore réussir ensuite, voir plus bas. |
| `canceled` | Annulé avant encaissement |
| `expired` | Délai dépassé sans confirmation. Une carte non terminée expire après 24 heures. |
| `refunded` | Remboursé : le montant est reparti vers le client, voir [Rembourser un paiement](https://docs.mercy-pay.com/payments/refunds.md) |
| `disputed` | Réservé, non utilisé pour l'instant |

Un paiement ne passe à `succeeded` qu'une seule fois. Marquez une commande comme payée à la réception du webhook `payment.succeeded`, pas à la redirection vers `success_url` : le client peut fermer l'onglet ou perdre sa connexion, alors que le webhook est renvoyé tant que votre serveur ne répond pas `2xx`.

## Un refus carte n'est pas toujours définitif

Sur le même formulaire, un client peut se tromper de carte puis réessayer avec la bonne. Le paiement passe alors de `failed` à `succeeded`, et vous recevez `payment.failed` puis `payment.succeeded`. Ne bloquez donc pas une commande pour toujours au premier `payment.failed` d'une carte : `payment.succeeded` a toujours le dernier mot. Cela ne concerne que la carte. Un paiement mobile money en `failed` reste en `failed`.


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