Sessions de checkout

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

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

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}, 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. 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.