Sessions Checkout

Une Session Checkout crée une page de paiement hébergée sur checkout.sangho.com. Votre client est redirigé vers cette page, y complète son paiement, puis est renvoyé vers votre success_url. Vous ne gérez jamais les données de paiement directement — Sangho s’en charge.

C’est l’intégration recommandée pour les e-commerces et applications web : zéro PCI DSS de votre côté, personnalisable aux couleurs de votre marque depuis votre dashboard.

Cycle de vie

open→processing→complete→expired / payment_failed

Statut	Signification
`open`	Session créée — page de paiement accessible.
`processing`	Paiement soumis, traitement en cours.
`complete`	Paiement réussi — client redirigé vers success_url.
`expired`	Session expirée sans paiement (délai dépassé ou /expire/ appelé).
`payment_failed`	Tentative de paiement échouée — session reste ouverte pour réessai.

Modes

Mode	Usage
`payment`	Paiement unique — flux standard. Crée une Intention de paiement.
`subscription`	Abonnement récurrent. Crée un Subscription.
`setup`	Sauvegarde d'une méthode de paiement sans débit immédiat.

Endpoints

Méthode	Endpoint	Description
POST	`/checkout-sessions/`	Créer une session
GET	`/checkout-sessions/`	Lister les sessions
GET	`/checkout-sessions/{id}/`	Récupérer une session
POST	`/checkout-sessions/{id}/expire/`	Expirer manuellement une session

Cette introduction est-elle claire ?

Schéma de l’objet

Response Objet CheckoutSession

json

{
  "id": "cs_xxxxxxxxxxxx",
  "object": "checkout_session",
  "mode": "payment",
  "status": "open",
  "currency": "XAF",
  "amount_total": 25000,
  "amount_subtotal": 25000,
  "payment_intent": null,
  "customer": "cust_xxxxxxxx",
  "customer_email": "client@email.com",
  "url": "https://checkout.sangho.com/c/cs_xxx",
  "success_url": "https://boutique.com/merci?session={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://boutique.com/panier",
  "line_items": [
    {
      "product": "prod_xxx",
      "description": "Formation Excel Avancé",
      "quantity": 1,
      "unit_amount": 25000,
      "amount_total": 25000
    }
  ],
  "payment_method_types": ["mobile_money", "bank_card"],
  "expires_at": "2026-03-01T10:30:00Z",
  "livemode": true,
  "metadata": {},
  "created_at": "2026-03-01T10:00:00Z"
}

Créer une Session Checkout

Crée une session de paiement et retourne l’URL de la page de paiement hébergée (url). Redirigez immédiatement votre client vers cette URL.

POST Corps de la requête

success_url Requis

string URL HTTPS ex : https://boutique.com/merci?session={CHECKOUT_SESSION_ID}

URL de redirection après un paiement réussi. Sangho remplace automatiquement {CHECKOUT_SESSION_ID} par l’ID de la session — utilisez-le pour vérifier le paiement côté serveur.

Vérifiez toujours côté serveur que la session est bien en statut complete avant de livrer le produit ou service. Ne faites jamais confiance à la redirection seule — un utilisateur pourrait manipuler l’URL.

line_items Requis

array[object]

Lignes de commande. Chaque objet contient product (ID) ou description + unit_amount, plus quantity (entier, défaut 1).

Pour les Products à prix libre (price_type: free), vous devez fournir le unit_amount dans la ligne de commande pour remplacer le prix par défaut. Maximum 20 lignes par session.

currency Requis

string ISO 4217

Code devise de la session. Toutes les lignes sont facturées dans cette devise.

mode Optionnel

string défaut : payment

Mode de la session : payment, subscription, ou setup.

En mode subscription, la session crée un objet Subscription et débite le client selon la récurrence du plan. En mode setup, aucun débit n’est effectué — la méthode est sauvegardée pour usage futur.

customer Optionnel

string cust_...

ID d’un Customer existant à associer à la session. La page de paiement est pré-remplie avec ses informations.

Mutuellement exclusif avec customer_email. Si ni l’un ni l’autre n’est fourni, Sangho crée un Customer anonyme au moment du paiement si collect_customer_info: true.

customer_email Optionnel

string email

Email pré-rempli dans le formulaire de la page de paiement. Sangho crée ou retrouve automatiquement le Customer correspondant.

cancel_url Optionnel

string URL HTTPS

URL de redirection si l’acheteur clique sur « Annuler » ou ferme la page de paiement.

Si non fournie, un bouton de retour générique est affiché. Recommandé : pointez vers le panier ou la page produit pour réduire l’abandon.

payment_method_types Optionnel

array[string]

Méthodes de paiement proposées sur la page checkout. Si omis, toutes les méthodes actives de l’App sont disponibles.

expires_in Optionnel

integer secondes défaut : 1800

Durée de validité de la session en secondes à partir de sa création.

Minimum : 300 secondes (5 min). Maximum : 86 400 secondes (24h). Passé ce délai, la page de paiement affiche un message d’expiration et la session passe en expired. Une session expirée ne peut pas être réactivée — créez-en une nouvelle.

metadata Optionnel

object

Données libres associées à la session. Retournées dans le webhook checkout.session.completed.

Vérification côté serveur obligatoire

Après redirection vers success_url, appelez toujours GET /checkout-sessions/{id}/ côté serveur pour confirmer que status === ‘complete’ avant de livrer votre produit. N’accordez jamais la livraison sur la seule base de la redirection URL.

Les paramètres de la Session Checkout sont-ils clairs ?

Créer une session et rediriger

bash

curl -X POST https://api.sangho.com/v1/checkout-sessions/ \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://boutique.com/merci?session={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://boutique.com/panier",
    "currency": "XAF",
    "line_items": [
      { "product": "prod_xxx", "quantity": 1 },
      { "product": "prod_yyy", "quantity": 2 }
    ],
    "customer_email": "client@email.com",
    "expires_in": 3600
  }'

Response 201 Created

La session est ouverte. Redirigez immédiatement votre client vers session.url. La session expire après expires_in secondes.

json

{
  "id": "cs_xxxxxxxxxxxx",
  "object": "checkout_session",
  "status": "open",
  "currency": "XAF",
  "amount_total": 75000,
  "url": "https://checkout.sangho.com/c/cs_xxx",
  "expires_at": "2026-03-01T11:00:00Z",
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z"
}

Response Session complète (vérification)

Appelez GET /checkout-sessions/{id}/ côté serveur après redirection pour confirmer le paiement. Ne livrez que si status === complete.

json

{
  "id": "cs_xxxxxxxxxxxx",
  "status": "complete",
  "amount_total": 75000,
  "payment_intent": "pay_xxxxxxxxxxxx",
  "customer": "cust_xxxxxxxx",
  "currency": "XAF",
  "updated_at": "2026-03-01T10:04:00Z"
}