> ## 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` | Annulée par le client ou par vous |

Une session expire après **30 minutes** sans paiement réussi. Au-delà, créez-en simplement une nouvelle plutôt que de chercher à ressusciter l'ancienne.

## Identifiant

Chaque session a une `reference` au format ULID (26 caractères, par exemple `01J9Z3V8QK4M2XW7R6TB5N0HYD`) : elle apparaît dans l'URL de la page de paiement, et c'est elle que vous utilisez pour relire 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 |
| `metadata` | non | Objet libre, renvoyé dans chaque réponse |

## 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/{uuid}`) reflète ce montant converti, pas celui de la session d'origine, voir [Paiements](/concepts/payments). Un paiement par carte, lui, encaisse toujours exactement le montant et la devise de la session, sans conversion.

## Idempotence

Un timeout réseau ne vous dit jamais si votre requête a vraiment échoué ou si elle a juste mis du temps à répondre. 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](/resources/idempotency).


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