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

> Créez, listez et consultez les sessions de paiement hébergées.

## POST /api/v1/checkout-sessions

Crée une session de checkout et vous renvoie directement l'URL de la page de paiement. Il ne vous reste qu'à y rediriger votre client.

### 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 |
| `description` | non | chaîne | 500 caractères maximum |
| `payer_name` | non | chaîne | 255 caractères maximum |
| `payer_email` | non | chaîne | Adresse e-mail valide |
| `payer_phone` | non | chaîne | 20 caractères maximum |
| `success_url` | non | URL | 2048 caractères maximum |
| `cancel_url` | non | URL | 2048 caractères maximum |
| `metadata` | non | objet | Libre, renvoyé dans les réponses |

```bash theme={null}
curl https://mercy-pay.com/api/v1/checkout-sessions \
  -H "Authorization: Bearer mp_sandbox_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-4821" \
  -d '{
    "amount": 15000,
    "currency": "XAF",
    "description": "Commande 4821",
    "success_url": "https://boutique-ada.example/merci",
    "cancel_url": "https://boutique-ada.example/panier",
    "metadata": {"order_id": "4821"}
  }'
```

### Réponse `201`

```json theme={null}
{
  "data": {
    "reference": "01J9Z3V8QK4M2XW7R6TB5N0HYD",
    "amount": 15000,
    "currency": "XAF",
    "description": "Commande 4821",
    "payer_name": null,
    "payer_email": null,
    "payer_phone": null,
    "success_url": "https://boutique-ada.example/merci",
    "cancel_url": "https://boutique-ada.example/panier",
    "status": "created",
    "metadata": {"order_id": "4821"},
    "checkout_url": "https://mercy-pay.com/checkout/01J9Z3V8QK4M2XW7R6TB5N0HYD",
    "expires_at": "2026-10-03T10:50:00+00:00",
    "created_at": "2026-10-03T10:20:00+00:00"
  }
}
```

## GET /api/v1/checkout-sessions

Liste vos sessions, de la plus récente à la plus ancienne.

| Paramètre | Description |
| - | - |
| `status` | `created`, `pending_payment`, `completed`, `expired` ou `cancelled` |
| `from`, `to` | Dates `AAAA-MM-JJ`, bornes incluses |
| `per_page` | 20 par défaut, 100 au maximum |

## GET /api/v1/checkout-sessions/{reference}

Renvoie une session. Pour retrouver le paiement qui l'a réglée, cherchez-le dans `GET /api/v1/payments` : son champ `checkout_session` porte cette même référence.

### Erreurs

| Code | Message |
| - | - |
| `404` | `Session de checkout introuvable.` |
| `422` | Champs invalides, avec le détail dans `errors` |


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