Session de checkout (checkout_session)

Rôle

La checkout session est le point d'entrée du flux d'achat. Elle porte deux dimensions indépendantes : le cycle de vie de la session (est-elle encore active ?) et le résultat financier (qu'a-t-il été décidé pour le paiement ?). Leur séparation permet au processus de clore la session (status: completed) quel que soit l'issue — paiement immédiat, crédit accordé, ou échec — sans ambiguïté.

À la création, un processus d'orchestration est lancé automatiquement. C'est ce processus qui pilote le parcours utilisateur, communique avec les providers de paiement et met à jour les statuts de la session via les nodes dédiés.

Identifiant et structure

Chaque session porte un identifiant stable préfixé par cs_. Le champ object vaut "checkout_session".

{
  "object": "checkout_session",
  "id": "cs_5e2d8f1a9b3c4d7e",
  "status": "open",
  "payment_status": "unpaid",
  "buyer_id": "cmp_3a8f1d9c2b4e7f6a",
  "buyer_contact_id": "ctc_d12e3f4a5b6c7d8e",
  "process_definition_id": "prd_1a2b3c4d5e6f7a8b",
  "process_instance_id": "pci_9a8b7c6d5e4f3a2b",
  "process_status": "running",
  "currency": "eur",
  "amount_excluding_tax": 100000,
  "amount_tax": 20000,
  "amount_including_tax": 120000,
  "billing_details": null,
  "shipping_details": null,
  "locale": "fr",
  "url": "https://checkout.example.com/c/cs_5e2d8f…",
  "return_url": "https://example.com/checkout/return",
  "expires_at": "2026-06-18T10:00:00.000Z",
  "closed_at": null,
  "source_reference": "ORDER-2026-00842",
  "metadata": {},
  "created_at": "2026-06-17T10:00:00.000Z"
}

Champs

Cycle de vie (status)

Le champ status suit le cycle de vie de la session. Une session démarre toujours à open et transite vers l'un des trois états finaux.

Un statut final ne peut pas être modifié. Seule une session open peut être expirée via POST /v1/checkout/sessions/:id/expire.

Résultat financier (payment_status)

Le champ payment_status enregistre l'issue financière de la session, indépendamment de son cycle de vie. Il est mis à jour par le processus checkout via le node update_checkout_session_payment_status ou finalize_checkout_session.

Processus associé

Une session créée avec un processus checkout expose deux informations d'exécution :process_instance_id, l'instance qui pilote actuellement la session, et process_status, son état courant. process_status est calculé depuis l'instance associée ; il ne constitue pas un troisième statut métier de la checkout session.

Un retry manuel, un fork retry_step / skip_step ou la reprise d'une étape utilisateur peut créer une nouvelle instance pour poursuivre la même session. Dans ce cas, process_instance_id est transféré vers la nouvelle instance et process_status reflète immédiatement son état. L'ancienne instance reste consultable dans l'historique d'orchestration mais n'est plus l'exécution canonique de la session.

Voir Erreurs et idempotence pour les règles détaillées de retry, fork et transfert de l'instance associée.

Montants

Les trois champs de montant sont exprimés en centimes (entiers non-négatifs) dans la devise indiquée par currency (code ISO 4217 en minuscules). La contrainte suivante est vérifiée à la création :

amount_excluding_tax + amount_tax = amount_including_tax

Exemple pour une commande de 1 000 € HT avec 20 % de TVA :

{
  "currency": "eur",
  "amount_excluding_tax": 100000,
  "amount_tax": 20000,
  "amount_including_tax": 120000
}

La devise est normalisée en minuscules à la persistance. Les lignes d'article rattachées à la session (line_items) doivent utiliser la même devise.

URL et expiration

Le champ url contient l'adresse du parcours utilisateur à transmettre à l'acheteur (redirection, lien par e-mail, iframe). Cette URL est fournie directement dans la réponse à la création — aucun appel supplémentaire n'est nécessaire.

La session expire automatiquement à la date expires_at. Si ce champ n'est pas fourni à la création, la plateforme fixe l'expiration à 24 heures après la création. Une fois expirée, l'URL n'est plus accessible et la session passe à status: expired.

Il est également possible d'expirer une session manuellement avant son échéance :

POST /v1/checkout/sessions/cs_5e2d/expire

{
  "status": "expired",
  "closed_at": "2026-06-17T11:30:00.000Z"
}

Lignes d'article

Des lignes d'article peuvent être jointes à la session à la création via le champ line_items. Elles sont ensuite accessibles via GET /v1/checkout/sessions/:id/line-items. Les lignes ne sont pas modifiables après création.

Une fois jointes, les lignes sont disponibles pour toute logique qui en a besoin : affichage du détail de la commande à l'acheteur dans le parcours utilisateur, transmission à un partenaire de détection de fraude qui analyse la nature ou la valeur des articles, ou exploitation par vos propres règles métier.

Dans les processus

La checkout_session est l'objet central des processus de type checkout. Elle est injectée automatiquement comme entrée du processus au démarrage et circule entre les nodes comme valeur typée platform.checkout_session.

Le node finalize_checkout_session est le pattern recommandé pour clore une session en fin de processus — il garantit que les deux dimensions sont mises à jour de façon atomique.

Si la session a été créée sans process_definition_id, la plateforme sélectionne automatiquement le lanceur de processus de type checkoutconfiguré pour votre compte marchand. Le processus doit accepter une entrée de type platform.checkout_session nommée checkout_session.

Événements

Le passage à cancelled ne déclenche pas d'événement dédié. Seuls completed et expired produisent un événement de transition. Chaque événement inclut l'objet checkout_session complet dans son payload.