Créer une Checkout Session

Qu’est-ce qu’une Checkout Session ?

Une Checkout Session représente la session de paiement de votre client. Elle contrôle ce que le client voit sur la page de paiement : les produits, le montant, la devise, et les options disponibles.

Format de l’identifiant : cs_ suivi de 24 caractères alphanumériques.Exemple : cs_abc123def456ghi789jkl012

Modes de la session

payment

Paiement uniquePour les achats ponctuels de produits ou services.

subscription

AbonnementPour créer un abonnement récurrent avec facturation automatique.

setup

ConfigurationPour enregistrer un moyen de paiement sans effectuer de paiement immédiat.

Créer une Checkout Session

Requête de base

curl -X POST https://api.yabetoo.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://votre-site.com/success",
    "cancel_url": "https://votre-site.com/cancel",
    "line_items": [
      {
        "price_data": {
          "currency": "XOF",
          "unit_amount": 15000,
          "product_data": {
            "name": "T-shirt Premium"
          }
        },
        "quantity": 2
      }
    ]
  }'

Paramètres requis

Paramètre	Type	Description
`success_url`	string	URL de redirection après paiement réussi
`line_items`	array	Liste des articles à acheter

Paramètres optionnels

Paramètre	Type	Description
`cancel_url`	string	URL de redirection si le client annule
`mode`	string	`payment`, `subscription`, ou `setup` (défaut: `payment`)
`customer`	string	ID d’un client existant (`cus_xxx`)
`customer_email`	string	Email du client (pré-remplit le formulaire)
`client_reference_id`	string	Votre référence interne (ex: ID commande)
`allow_promotion_codes`	boolean	Autoriser les codes promo
`locale`	string	Langue de la page (`fr`, `en`, etc.)
`expires_at`	number	Timestamp Unix d’expiration
`metadata`	object	Données personnalisées

Définir les articles (line_items)

Vous avez deux options pour définir les articles :

Prix inline (price_data)
Prix existant (price)

Définissez le prix directement dans la requête :

{
  "line_items": [
    {
      "price_data": {
        "currency": "XOF",
        "unit_amount": 25000,
        "product_data": {
          "name": "Formation JavaScript",
          "description": "Accès complet à la formation",
          "images": ["https://example.com/image.jpg"]
        }
      },
      "quantity": 1
    }
  ]
}

Référencez un prix créé dans votre catalogue :

{
  "line_items": [
    {
      "price": "price_abc123def456",
      "quantity": 1
    }
  ]
}

Utilisez des prix pré-créés pour une gestion centralisée de votre catalogue.

Structure du line_item

Champ	Type	Description
`price_data`	object	Prix défini inline (voir ci-dessous)
`price`	string	ID d’un prix existant (`price_xxx`)
`quantity`	number	Quantité (minimum 1)
`adjustable_quantity`	object	Permet au client de modifier la quantité

Structure de price_data

Champ	Type	Description
`currency`	string	Code devise (`XOF`, `EUR`, `USD`)
`unit_amount`	number	Prix unitaire
`product_data`	object	Informations sur le produit
`recurring`	object	Pour les abonnements uniquement

Structure de product_data

Champ	Type	Description
`name`	string	Nom du produit (requis)
`description`	string	Description
`images`	array	URLs des images
`metadata`	object	Données personnalisées

Abonnements récurrents

Pour créer un abonnement, utilisez mode: "subscription" et ajoutez recurring dans price_data :

{
  "mode": "subscription",
  "success_url": "https://votre-site.com/success",
  "line_items": [
    {
      "price_data": {
        "currency": "XOF",
        "unit_amount": 9900,
        "product_data": {
          "name": "Abonnement Pro"
        },
        "recurring": {
          "interval": "month",
          "interval_count": 1
        }
      },
      "quantity": 1
    }
  ]
}

Intervalles disponibles

Interval	Description
`day`	Facturation quotidienne
`week`	Facturation hebdomadaire
`month`	Facturation mensuelle
`year`	Facturation annuelle

Options avancées

Collecter les adresses

{
  "billing_address_collection": "required",
  "shipping_address_collection": {
    "allowed_countries": ["CG", "CD", "CI", "SN"]
  }
}

Collecter le numéro de téléphone

{
  "phone_number_collection": {
    "enabled": true
  }
}

{
  "allow_promotion_codes": true
}

{
  "discounts": [
    {
      "promotion_code": "promo_abc123"
    }
  ]
}

Personnaliser le bouton de paiement

{
  "submit_type": "pay"
}

Valeur	Texte du bouton
`auto`	Automatique selon le contexte
`pay`	”Payer”
`book`	”Réserver”
`donate`	”Faire un don”

Quantité ajustable

Permettez au client de modifier la quantité sur la page de paiement :

{
  "line_items": [
    {
      "price_data": {
        "currency": "XOF",
        "unit_amount": 5000,
        "product_data": { "name": "Article" }
      },
      "quantity": 1,
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 1,
        "maximum": 10
      }
    }
  ]
}

Exemple complet

curl -X POST https://api.yabetoo.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "success_url": "https://votre-site.com/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://votre-site.com/cancel",
    "customer_email": "client@example.com",
    "client_reference_id": "order_12345",
    "allow_promotion_codes": true,
    "billing_address_collection": "required",
    "phone_number_collection": { "enabled": true },
    "locale": "fr",
    "metadata": {
      "order_id": "12345",
      "source": "website"
    },
    "line_items": [
      {
        "price_data": {
          "currency": "XOF",
          "unit_amount": 25000,
          "product_data": {
            "name": "Écran HD",
            "description": "Écran 24 pouces Full HD",
            "images": ["https://example.com/ecran.jpg"]
          }
        },
        "quantity": 1
      },
      {
        "price_data": {
          "currency": "XOF",
          "unit_amount": 5000,
          "product_data": {
            "name": "Câble HDMI"
          }
        },
        "quantity": 2
      }
    ]
  }'

Réponse

{
  "id": "cs_abc123def456ghi789",
  "object": "checkout.session",
  "mode": "payment",
  "status": "open",
  "payment_status": "unpaid",
  "url": "https://checkout.yabetoo.com/cs_abc123def456ghi789",
  "success_url": "https://votre-site.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://votre-site.com/cancel",
  "customer_email": "client@example.com",
  "client_reference_id": "order_12345",
  "amount_subtotal": 35000,
  "amount_total": 35000,
  "amount_discount": 0,
  "currency": "XOF",
  "allow_promotion_codes": true,
  "line_items": [
    {
      "price_data": {
        "currency": "XOF",
        "unit_amount": 25000,
        "product_data": { "name": "Écran HD" }
      },
      "quantity": 1,
      "amount_subtotal": 25000,
      "amount_total": 25000
    },
    {
      "price_data": {
        "currency": "XOF",
        "unit_amount": 5000,
        "product_data": { "name": "Câble HDMI" }
      },
      "quantity": 2,
      "amount_subtotal": 10000,
      "amount_total": 10000
    }
  ],
  "metadata": {
    "order_id": "12345",
    "source": "website"
  },
  "expires_at": "2024-01-15T12:00:00.000Z",
  "created_at": "2024-01-15T11:00:00.000Z"
}

Champs de la réponse

Champ	Description
`id`	Identifiant unique de la session
`url`	URL de la page de paiement
`status`	`open`, `complete`, ou `expired`
`payment_status`	`unpaid`, `paid`, ou `no_payment_required`
`amount_subtotal`	Sous-total avant réductions
`amount_total`	Montant total à payer
`amount_discount`	Montant des réductions appliquées

Rediriger le client

Une fois la session créée, redirigez le client vers l’URL de paiement :

// Côté serveur : créer la session
const session = await createCheckoutSession(/* ... */);

// Côté client : rediriger
window.location.href = session.url;

Après le paiement

Redirection

Après le paiement, le client est redirigé vers success_url avec l’ID de session :

https://votre-site.com/success?session_id=cs_abc123def456

Vérifier le statut

Ne faites jamais confiance uniquement à la redirection. Vérifiez toujours le statut de la session côté serveur.

// Récupérer l'ID de session depuis l'URL
const sessionId = new URLSearchParams(window.location.search).get("session_id");

// Vérifier le statut côté serveur
const response = await fetch(
  "https://api.yabetoo.com/v1/checkout/sessions/" + sessionId,
  {
    headers: {
      Authorization: "Bearer sk_live_...",
    },
  }
);

const session = await response.json();

if (session.status === "complete" && session.payment_status === "paid") {
  // Paiement confirmé - traiter la commande
}

Webhooks

Pour une intégration robuste, utilisez les webhooks pour recevoir les notifications de paiement :

{
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_abc123def456",
      "status": "complete",
      "payment_status": "paid",
      "amount_total": 35000,
      "currency": "XOF"
    }
  }
}

Voir Documentation Webhooks pour plus de détails.

Statuts de la session

Statut	Description
`open`	Session active, en attente de paiement
`complete`	Paiement réussi
`expired`	Session expirée (non payée dans le délai)

Bonnes pratiques

Sécurité

Créez toujours les sessions côté serveur
Ne stockez jamais les clés API côté client
Vérifiez le statut via l’API ou les webhooks

Expérience utilisateur

Pré-remplissez l’email si vous le connaissez
Utilisez client_reference_id pour lier à votre commande
Personnalisez le submit_type selon le contexte

Gestion des erreurs

Gérez le cas où le client annule
Prévoyez l’expiration de la session
Utilisez les webhooks pour les cas edge

Prochaines étapes

Webhooks

Recevez des notifications en temps réel

Codes promo

Appliquez des réductions à vos sessions

Pour commencer

Créer une page de paiement

Intégration avancée des paiements

Décaissements

Transferts

Liens de paiement

Créer une Checkout Session

Qu’est-ce qu’une Checkout Session ?

Modes de la session

payment

subscription

setup

Créer une Checkout Session

Requête de base

Paramètres requis

Paramètres optionnels

Définir les articles (line_items)

Structure du line_item

Structure de price_data

Structure de product_data

Abonnements récurrents

Intervalles disponibles

Options avancées

Collecter les adresses

Collecter le numéro de téléphone

Personnaliser le bouton de paiement

Quantité ajustable

Exemple complet

Réponse

Champs de la réponse

Rediriger le client

Après le paiement

Redirection

Vérifier le statut

Webhooks

Statuts de la session

Bonnes pratiques

Prochaines étapes

Webhooks

Codes promo

Pour commencer

Créer une page de paiement

Intégration avancée des paiements

Décaissements

Transferts

Liens de paiement

Documentation Index

​Qu’est-ce qu’une Checkout Session ?

​Modes de la session

payment

subscription

setup

​Créer une Checkout Session

​Requête de base

​Paramètres requis

​Paramètres optionnels

​Définir les articles (line_items)

​Structure du line_item

​Structure de price_data

​Structure de product_data

​Abonnements récurrents

​Intervalles disponibles

​Options avancées

​Collecter les adresses

​Collecter le numéro de téléphone

​Autoriser les codes promo

​Appliquer un code promo automatiquement

​Personnaliser le bouton de paiement

​Quantité ajustable

​Exemple complet

​Réponse

​Champs de la réponse

​Rediriger le client

​Après le paiement

​Redirection

​Vérifier le statut

​Webhooks

​Statuts de la session

​Bonnes pratiques

​Prochaines étapes

Webhooks

Codes promo

Qu’est-ce qu’une Checkout Session ?

Modes de la session

Créer une Checkout Session

Requête de base

Paramètres requis

Paramètres optionnels

Définir les articles (line_items)

Structure du line_item

Structure de price_data

Structure de product_data

Abonnements récurrents

Intervalles disponibles

Options avancées

Collecter les adresses

Collecter le numéro de téléphone

Autoriser les codes promo

Appliquer un code promo automatiquement

Personnaliser le bouton de paiement

Quantité ajustable

Exemple complet

Réponse

Champs de la réponse

Rediriger le client

Après le paiement

Redirection

Vérifier le statut

Webhooks

Statuts de la session

Bonnes pratiques

Prochaines étapes