Construire un checkout B2B

Objectif métier

Une checkout_session représente une tentative de checkout pour une party et un contact acheteur. Elle porte le panier, les montants, les adresses, l’URL de retour et le processus qui décide comment le buyer peut régler sa commande.

Le checkout peut être initié dans un parcours en ligne, par exemple depuis un site e-commerce ou un portail B2B, mais aussi en magasin ou depuis un point de vente assisté. Dans tous les cas, la session conserve le même rôle : contextualiser l'acheteur et la transaction, exécuter les contrôles requis et produire une décision exploitable par le système qui porte la commande.

Le parcours peut aboutir à un paiement immédiat, une autorisation ou un crédit différé. Votre système conserve la maîtrise de la commande et de son fulfillment ; Ormuz fournit le résultat nécessaire pour prendre cette décision.

Prérequis

La party et le party_contact doivent appartenir au même marchand, et le contact doit être rattaché à cette party. Si plusieurs launchers checkout sont actifs, transmettez explicitement leprocess_definition_id à utiliser lors de la création de la session.

Parcours cible

Créer la session

Appelez POST /v1/checkout/sessions depuis votre backend. Les trois montants sont requis, exprimés dans l'unité mineure de la devise, et doivent respecter amount_excluding_tax + amount_tax = amount_including_tax. La requête ne choisit pas un mode paiement ou crédit : le processus checkout porte cette décision et les capacités qu’il exécute.

POST /v1/checkout/sessions
Content-Type: application/json

{
  "merchant_id": "mer_abc123",
  "buyer_id": "pty_abc123",
  "buyer_contact_id": "ptc_abc123",
  "currency": "eur",
  "amount_excluding_tax": 10000,
  "amount_tax": 2000,
  "amount_including_tax": 12000,
  "return_url": "https://shop.example/orders/ORD-2026-104",
  "source_reference": "ORD-2026-104",
  "line_items": [
    {
      "line_type": "service",
      "product_name": "Licence annuelle",
      "quantity": 1,
      "unit_amount_excluding_tax": 10000,
      "unit_amount_including_tax": 12000,
      "currency": "eur"
    }
  ]
}

{
  "id": "cs_abc123",
  "object": "checkout_session",
  "status": "open",
  "payment_status": "unpaid",
  "merchant_id": "mer_abc123",
  "buyer_id": "pty_abc123",
  "buyer_contact_id": "ptc_abc123",
  "process_instance_id": "pci_abc123",
  "source_reference": "ORD-2026-104",
  "currency": "eur",
  "amount_including_tax": 12000,
  "url": "https://hosted.example/access/..."
}

Les line_items décrivent le panier au moment de la création. Ils peuvent représenter un produit, un service, une livraison, une remise ou des frais. Ils ne sont plus modifiables après la création de la session.

Porter la décision financière dans le process

Le process reçoit la checkout_session comme objet d'entrée. Il peut lire ses lignes, son montant, sa party et son contact sans demander au concepteur de mapper des identifiants techniques.

Le node finalize_checkout_session permet de mettre à jour ensemble le résultat financier et le cycle de vie. Cette finalisation explicite évite de considérer la simple fin des écrans du parcours utilisateur comme une preuve de paiement.

Séparer parcours et résultat financier

Les deux axes de statut répondent à des questions différentes. status décrit le parcours ; payment_status décrit l'issue financière.

Une session completed + unpaid n'autorise pas la livraison. Inversement, credit_granted indique une décision favorable sans imposer le provider ou le mécanisme qui porte le risque.

Événements et suivi

Un parcours utilisateur n'est requis que si le processus comporte des actions utilisateur. Un checkout entièrement automatisé peut rester côté serveur : votre intégration attend alors le webhook checkout_session.completed, puis relit la session avant de mettre à jour la commande.

Après une redirection de succès, relisez également la session côté serveur. La redirection améliore l'expérience utilisateur ; l'API et les événements portent le résultat métier à utiliser pour votre commande.

Une session ouverte expire par défaut après 24 heures si vous ne fournissez pas expires_at. Vous pouvez aussi expirer explicitement une session ouverte avec POST /v1/checkout/sessions/:id/expire.

Checklist d'intégration

• Créer ou résoudre la party et le contact acheteur avant le checkout.
• Configurer au moins un launcher checkout actif et sélectionner explicitement le process_definition_id lorsqu'il y en a plusieurs.
• Envoyer des montants et des lignes cohérents dans une même devise.
• Stocker l'ID de session avec la commande source.
• Rediriger vers l'URL de parcours utilisateur retournée par Ormuz uniquement si le processus attend une action utilisateur.
• Pour un parcours automatisé, attendre le webhook de fin de checkout sans imposer de redirection.
• Finaliser explicitement status et payment_status dans le process.
• Confirmer la commande avec la règle à deux axes, jamais avec status seul.
• Traiter les webhooks de façon idempotente et relire la session avant fulfillment.
• Prévoir les cas de refus, d'annulation, d'expiration et d'abandon.