ormuz
Guides métier/Prélèvement SEPA

Prélèvement SEPA avec Stripe

Collectez une fois l’autorisation SEPA d’un acheteur, réutilisez ce mandat pour les prélèvements ultérieurs, puis synchronisez chaque exécution Stripe vers le paiement PSP canonique Ormuz avant rapprochement.

Objectif métier

Un prélèvement récurrent combine deux responsabilités distinctes : obtenir un mandat réutilisableet exécuter un paiement. Le mandat appartient au contexte Stripe du Customer ; chaque débit est, lui, matérialisé dans Ormuz par un psp_payment distinct portant montant, devise et rattachements métier.

Mandat ≠ paiement Un mandat SEPA autorise un rail de prélèvement ; il ne prouve ni qu’un débit a été déclenché ni qu’il a été encaissé. Créez un nouveau psp_payment pour chaque intention de débit.

Modèle mental

Customer Stripe + mandat actif
psp_payment draft ou pending
Trigger SEPA Debit
PaymentIntent Stripe
Synchronisation psp_payment

Le Customer et le mandat sont réutilisables ; le psp_payment représente une intention de paiement précise et reste le point d’ancrage Ormuz de son exécution Stripe.

La correspondance entre objets Ormuz et Stripe est durable. Le processus n’a donc pas à transporter des IDs Stripe bruts entre ses étapes : les nodes Stripe prennent des objets typés et réutilisent les mappings existants.

Prérequis

  • Une configuration Stripe active et cohérente avec l’environnement Ormuz.
  • Un entreprise acheteuse et, pour la collecte interactive, un contact disposant des informations nécessaires.
  • Un processus capable de présenter un parcours utilisateur lorsque la signature du mandat est requise.
  • Une règle claire de création du psp_payment : facture, commande, session de checkout ou autre base métier explicite.

1. Collecter ou réutiliser le mandat

Commencez par stripe.ensure_customer. Le node crée le Customer Stripe uniquement si aucune correspondance réutilisable n’existe pour l’entreprise ou le contact.

Utilisez ensuite stripe.ensure_sepa_debit_mandatepour le chemin standard. Il cherche d’abord les mandats actifs : s’il n’en trouve aucun, il ouvre une action utilisateur Stripe Elements ; s’il en trouve exactement un, il le réutilise sans interaction ; s’il en trouve plusieurs, il s’arrête sur une ambiguïté au lieu de choisir arbitrairement.

BesoinNodeComportement
Réutiliser si possible, collecter s’il n’existe aucun mandatstripe.ensure_sepa_debit_mandateRéutilise l’unique mandat actif, collecte lorsqu’il n’y en a aucun et échoue en cas d’ambiguïté.
Résoudre sans interactionstripe.resolve_sepa_debit_mandateRoute explicitement aucun, un ou plusieurs mandats candidats.
Forcer une nouvelle collectestripe.collect_sepa_debit_mandateCrée un nouveau SetupIntent et suspend le processus pendant la signature.
Ne choisissez jamais silencieusement entre plusieurs mandats Si la résolution retourne plusieurs mandats actifs, traitez l’ambiguïté dans le processus. Le choix d’un mandat est une décision métier et ne doit pas dépendre d’un ordre de liste provider.

2. Créer puis déclencher le prélèvement

Créez d’abord l’intention Ormuz avec create_psp_payment. Le montant, la devise et la base métier du débit sont alors figés dans un platform.psp_payment au statut draft.

Passez ce paiement, le Customer et le mandat à stripe.trigger_sepa_debit. Le node valide la cohérence du mandat, crée ou réutilise le PaymentIntent Stripe de façon idempotente et conserve son mapping vers le même psp_payment.

Le montant vient d’Ormuz Le node Stripe ne redéfinit pas librement le montant du prélèvement : le psp_payment fourni reste la source de vérité de l’intention de paiement.

3. Suivre le résultat et rapprocher

Un prélèvement SEPA peut évoluer après sa création. Utilisez les événements Stripe et stripe.sync_psp_payment pour relire le PaymentIntent et reporter le statut et les montants autoritaires vers le psp_payment Ormuz.

Lorsque le paiement constitue réellement un encaissement à appliquer à une facture ou un receivable, utilisez ensuite reconcile_payment ou le parcours de réconciliation de paiement. Le règlement d’une facture ne doit pas être déduit du seul statut provider sans créer l’allocation métier correspondante.

Reprises, idempotence et sécurité

  • Customer : réutilisé via le mapping Stripe de l’entreprise ou du contact.
  • Mandat : réutilisable tant qu’il reste actif et compatible avec le Customer.
  • PaymentIntent : corrélé au psp_payment pour éviter un second débit lors d’une reprise.
  • Secrets Stripe : les valeurs nécessaires au navigateur ne doivent être exposées que pendant l’interaction qui les consomme.
  • Replay : placez une frontière de reprise avant toute interaction qu’il serait dangereux de répéter automatiquement.

Checklist

  • Résoudre le Customer Stripe depuis un objet Ormuz, jamais depuis un ID Stripe codé en dur.
  • Réutiliser un mandat actif lorsqu’il existe et traiter explicitement les ambiguïtés.
  • Créer un psp_payment distinct pour chaque prélèvement.
  • Déclencher le débit à partir du montant et de la devise du paiement Ormuz.
  • Synchroniser le résultat Stripe avant toute décision métier dépendant du statut final.
  • Créer une payment_allocation lorsque le cash doit régler une facture ou réduire un receivable.