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

# Sessions de checkout

> Une session de checkout est une demande de paiement hébergée par Mercy Pay, avec un cycle de vie précis.

Une **session de checkout** représente une demande de paiement : un montant, une devise et une page hébergée que votre client peut ouvrir pour payer.

## Cycle de vie

| Statut | Signification |
| - | - |
| `created` | Session créée, aucun paiement commencé |
| `pending_payment` | Un paiement est en cours de traitement |
| `completed` | Un paiement a réussi |
| `expired` | Personne n'a payé avant `expires_at` |
| `cancelled` | Réservé, jamais renvoyé aujourd'hui. Une session abandonnée ou que vous fermez passe à `expired`. |

Une session expire après **30 minutes** sans paiement réussi. Au-delà, créez-en une nouvelle.

## Identifiant

Chaque session a un `id` de la forme `cs_01J9Z3V8QK4M2XW7R6TB5N0HYD` : c'est lui que vous utilisez pour relire ou expirer la session ensuite.

## Champs

| Champ | Requis | Description |
| - | - | - |
| `amount` | oui | Entier en unités mineures, supérieur à 0 |
| `currency` | oui | Code ISO 4217 |
| `description` | non | Libellé affiché au client, 500 caractères maximum |
| `payer_name`, `payer_email`, `payer_phone` | non | Pré-remplissent la page de paiement |
| `success_url`, `cancel_url` | non | Redirections après paiement ou annulation. `{CHECKOUT_SESSION_ID}` y est remplacé par l'`id` de la session. |
| `payment_method_types` | non | Moyens proposés : `["mobile_money"]`, `["card"]` ou les deux. Absent : tous. |
| `allowed_countries` | non | Pays mobile money proposés, par exemple `["CMR", "GAB"]`. Absent : tous les pays ouverts. |
| `metadata` | non | Objet libre, renvoyé dans chaque réponse |

## Retrouver la session au retour

Ajoutez `{CHECKOUT_SESSION_ID}` à votre `success_url` : `https://boutique.example/merci?session={CHECKOUT_SESSION_ID}`. Au retour, votre page reçoit `?session=cs_…` et peut relire la session avec [`GET /api/v1/checkout_sessions/{id}`](https://docs.mercy-pay.com/api/checkout-sessions/get), sans paramètre maison. La confirmation reste le webhook `payment.succeeded` : un client peut fermer l'onglet avant d'être redirigé.

## Choisir ce que la page propose

Vous encaissez déjà la carte ailleurs ? Passez `payment_method_types: ["mobile_money"]` et la page ne propose plus que le mobile money. `allowed_countries` limite de la même façon les pays proposés. Un moyen ou un pays masqué est aussi refusé si quelqu'un essaie de payer avec lui directement.

## Paiement mobile money dans une autre devise

Sur la page hébergée, votre client peut choisir n'importe quel pays mobile money disponible, même si sa devise diffère de celle de la session : le montant est alors converti automatiquement vers la devise de l'opérateur choisi avant l'encaissement. Le paiement qui en résulte (consultable via `GET /api/v1/payments/{id}`) reflète ce montant converti, pas celui de la session d'origine, voir [Paiements](https://docs.mercy-pay.com/payments/payment-object.md). Un paiement par carte, lui, encaisse toujours exactement le montant et la devise de la session, sans conversion.

## Idempotence

Après un timeout, vous ne savez pas si votre requête a abouti. Envoyez un en-tête `Idempotency-Key` à la création : si vous rejouez la même requête après un doute, vous récupérez la session déjà créée au lieu d'en ouvrir une deuxième. Voir [Idempotence](https://docs.mercy-pay.com/developers/idempotency.md).


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