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

> Encaissez directement en API, ou consultez les paiements créés par vos sessions de checkout.

Un paiement naît de l'une de deux façons : via le flux de checkout (votre serveur crée une session, le client paie sur la page hébergée), ou directement par `POST /api/v1/payments`. Peu importe lequel, le calcul des frais et la confirmation par webhook se comportent exactement pareil ensuite. Seule la façon de démarrer diffère.

## POST /api/v1/payments

Encaisse un paiement mobile money sans jamais passer par une session de checkout ni une page hébergée : votre serveur collecte le numéro et l'opérateur du client dans sa propre interface et appelle directement cet endpoint, en sandbox comme en live.

Pour l'instant, seul le mobile money est pris en charge ici. La carte demande une étape de tokenisation côté client que cet endpoint ne gère pas encore.

### En-têtes

| Nom | Requis | Description |
| - | - | - |
| `Authorization` | oui | `Bearer mp_…` |
| `Content-Type` | oui | `application/json` |
| `Idempotency-Key` | recommandé | Évite les doublons, voir [Idempotence](/resources/idempotency) |

### Corps

| Champ | Requis | Type | Règles |
| - | - | - | - |
| `amount` | oui | entier | Unités mineures, au moins `1` |
| `currency` | oui | chaîne | Code ISO 4217 de 3 lettres |
| `country` | oui | chaîne | Pays ISO 3166-1 alpha-3, par exemple `CMR` |
| `provider` | oui | chaîne | Code opérateur, par exemple `MTN_MOMO_CMR` |
| `phone` | oui | chaîne | Numéro avec indicatif, sans `+` |
| `payer_name` | non | chaîne | 255 caractères maximum |
| `payer_email` | non | chaîne | Adresse e-mail valide |
| `description` | non | chaîne | 500 caractères maximum |

```bash theme={null}
curl https://mercy-pay.com/api/v1/payments \
  -H "Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-9123" \
  -d '{
    "amount": 1000,
    "currency": "XAF",
    "country": "CMR",
    "provider": "MTN_MOMO_CMR",
    "phone": "237680000000",
    "description": "Commande 9123"
  }'
```

### Réponse `201`

```json theme={null}
{
  "data": {
    "uuid": "5e0c8a7b-3d1f-4a2e-9c64-8b7f0d2e1a93",
    "checkout_session": null,
    "gross_amount": 1000,
    "psp_fee_amount": 20,
    "platform_fee_amount": 30,
    "net_amount_to_merchant": 950,
    "currency": "XAF",
    "payment_method": "mobile_money",
    "mobile_money_country": "CMR",
    "mobile_money_provider": "MTN_MOMO_CMR",
    "psp_reference": "3a7f1e2c-8b4d-4e9a-a6f0-1d5c9e7b2f48",
    "status": "pending",
    "failure_reason": null,
    "created_at": "2026-10-04T10:20:00+00:00"
  }
}
```

Le statut reste `pending` jusqu'à ce que le webhook `payment.succeeded` ou `payment.failed` tranche, exactement comme pour un paiement né d'une session de checkout. Voir [Gérer les webhooks](/guides/handle-webhooks).

<Note>
  Un opérateur mobile money ne déplace que sa propre devise nationale. Si `currency` ne correspond pas à la devise du pays choisi (`country`), le montant est converti automatiquement avant l'encaissement. La réponse reflète alors le montant réellement prélevé, dans la devise de l'opérateur, pas celle envoyée dans la requête. Par exemple, une requête avec `"amount": 1000, "currency": "XAF", "country": "RWA", "provider": "MTN_MOMO_RWA"` encaisse réellement en RWF : la réponse renvoie `"currency": "RWF"` et `gross_amount` dans cette devise. Si aucun taux n'est disponible pour la devise de l'opérateur, la requête échoue en `422`.
</Note>

### Erreurs

| Code | Cause |
| - | - |
| `403` | Clé live et KYC non approuvé, ou marchand suspendu |
| `422` | Pays/opérateur invalide, numéro manquant ou invalide, devise non convertible vers celle de l'opérateur, ou paiement refusé (voir `failure_reason`) |

## GET /api/v1/payments

Liste vos paiements, du plus récent au plus ancien.

| Paramètre | Description |
| - | - |
| `status` | `pending`, `processing`, `succeeded`, `failed`, `canceled`, `expired`, `refunded`, `disputed` |
| `from`, `to` | Dates `AAAA-MM-JJ`, bornes incluses |
| `per_page` | 20 par défaut, 100 au maximum |

```bash theme={null}
curl "https://mercy-pay.com/api/v1/payments?status=succeeded&per_page=5" \
  -H "Authorization: Bearer mp_sandbox_XXXXXXXXXXXXXXXX"
```

## GET /api/v1/payments/{uuid}

Renvoie un paiement, qu'il vienne d'une session de checkout ou d'une charge directe.

### Réponse

```json theme={null}
{
  "data": {
    "uuid": "5e0c8a7b-3d1f-4a2e-9c64-8b7f0d2e1a93",
    "checkout_session": "01J9Z3V8QK4M2XW7R6TB5N0HYD",
    "gross_amount": 15000,
    "psp_fee_amount": 300,
    "platform_fee_amount": 450,
    "net_amount_to_merchant": 14250,
    "currency": "XAF",
    "payment_method": "mobile_money",
    "mobile_money_country": "CMR",
    "mobile_money_provider": "MTN_MOMO_CMR",
    "psp_reference": "3a7f1e2c-8b4d-4e9a-a6f0-1d5c9e7b2f48",
    "status": "succeeded",
    "failure_reason": null,
    "created_at": "2026-10-03T10:20:00+00:00"
  }
}
```

| Champ | Description |
| - | - |
| `checkout_session` | Référence de la session de checkout à l'origine du paiement, `null` pour une charge directe |
| `gross_amount` | Montant payé par le client |
| `psp_fee_amount`, `platform_fee_amount` | Décomposition informative de la commission |
| `net_amount_to_merchant` | Montant crédité à votre solde |
| `mobile_money_country`, `mobile_money_provider` | Pays et opérateur. `null` pour une carte. |
| `failure_reason` | Raison de l'échec si `status` est `failed`, sinon `null` |

Voir [Paiements](/concepts/payments) pour les statuts.

### Erreurs

| Code | Cause |
| - | - |
| `404` | Paiement inconnu, ou appartenant à un autre marchand |


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