Stripe Billing

Vue d’ensemble

L’intégration Stripe Billing transforme une commande Qwoty signée en Subscription Schedule Stripe. Chaque phase du plan tarifaire devient une phase Stripe avec ses propres éléments, sa fréquence de facturation et sa durée. Les frais ponctuels (frais de mise en service, matériel, onboarding) sont ajoutés comme éléments de facture sur le premier cycle de facturation. Les remises sont appliquées sous forme de coupons Stripe natifs, au niveau de l’élément, de la phase ou de l’élément de facture ajouté. Si la commande comporte un délai de démarrage, l’intégration crée automatiquement une période d’essai de cette durée avant le début de la facturation.

Authentification

Accéder à votre tableau de bord Stripe

Rendez-vous sur dashboard.stripe.com et connectez-vous.

Créer une clé API restreinte

Allez dans Developers › API keys › Create restricted key.Accordez l’accès en écriture à : Customers, Subscriptions, Subscription Schedules, Invoices, Tax rates, Coupons.

Copier la clé secrète

Copiez la clé qui commence par sk_live_ (ou sk_test_ pour les tests).

La coller dans les paramètres de l’intégration

Collez la clé dans le champ Workspace API token ci-dessous.

Si vous utilisez plusieurs comptes Stripe (un par unité commerciale), réglez Token scope sur business_unit et fournissez une clé par ID d’unité commerciale.

Paramètres

Authentification

Clé	Valeur par défaut	Description
`token_scope`	`workspace`	`workspace` : une clé globale. `business_unit` : une clé par unité commerciale. Obligatoire.
`workspace_api_token`	—	Clé secrète Stripe (si `token_scope = workspace`). Obligatoire.

Facturation

Clé	Valeur par défaut	Description
`collection_method`	`charge_automatically`	Mode d’encaissement Stripe. `charge_automatically` débite le moyen de paiement enregistré du client. `send_invoice` envoie une facture par e-mail.
`days_until_due`	`30`	Nombre de jours dont dispose le client pour payer (utilisé uniquement quand `collection_method = send_invoice`).
`payment_behavior`	`allow_incomplete`	Comportement si le premier paiement échoue. `allow_incomplete` : crée l’abonnement au statut `incomplete`. `default_incomplete` : `incomplete` uniquement si un paiement est requis. `error_if_incomplete` : renvoie une erreur et ne crée pas l’abonnement.

Taxes

Clé	Valeur par défaut	Description
`tax_mode`	`manual`	`automatic` : Stripe Tax calcule automatiquement les taux de taxe (nécessite l’activation de Stripe Tax). `manual` : les taux de taxe sont repris de la commande Qwoty et synchronisés vers Stripe.

Quand tax_mode = automatic, aucun taux de taxe Qwoty n’est envoyé à Stripe. Stripe Tax doit être configuré dans votre tableau de bord Stripe.

Période d’essai

Clé	Valeur par défaut	Description
`trial_end_behavior`	`create_invoice`	Ce qui se passe si le client n’a pas de moyen de paiement à la fin de la période d’essai. `create_invoice` : génère quand même une facture. `pause` : met l’abonnement en pause. `cancel` : annule l’abonnement.

Une période d’essai est créée automatiquement quand le type de démarrage de facturation de la commande est sign_day avec delay_days > 0. Elle dure exactement delay_days jours.

Après la création

Clé	Valeur par défaut	Description
`post_action`	`none`	Action après la création du schedule. `none` : rien. `send_email` : envoie un e-mail de confirmation via Qwoty.

Résultat

Ce qui est créé dans Stripe

1. Customer (s’il n’est pas déjà associé) L’intégration recherche le client par son ID Qwoty (stocké dans les métadonnées Stripe), puis par e-mail. S’il est introuvable, un nouveau client Stripe est créé et son ID Stripe est réécrit dans Qwoty (external_ids.accounting). 2. Coupons (un par montant de remise distinct) Pour chaque remise de la commande, l’intégration recherche un coupon Stripe existant avec l’ID qwoty_{orderId}_{amountCents}_{currency}_{duration} avant d’en créer un nouveau. Tous les coupons Qwoty sont préfixés par qwoty_ pour être facilement repérables dans votre tableau de bord Stripe. 3. Taux de taxe (mode manuel uniquement) Les taux de taxe sont résolus via external_ids.accounting sur chaque taxe. S’ils sont introuvables, l’intégration recherche dans Stripe par pourcentage et par pays, puis crée un nouveau taux de taxe s’il n’existe pas. 4. Subscription Schedule

Source CPQ	Champ Stripe	Remarques
Client résolu	`customer`
`start.type = sign_day`	`start_date = "now"`
`start.type = date`	`start_date`	Timestamp Unix
Dernière phase `forever`	`end_behavior = "release"`	Renouvellement automatique
Dernière phase avec fin	`end_behavior = "cancel"`	Annulation à la fin
`order.id`	`metadata.quote_id`
`order.quote_number`	`metadata.quote_number`
`order.opportunity_id`	`metadata.opportunity_id`	S’il est défini

Phases : une par phase du plan CPQ :

Source CPQ	Champ Stripe	Remarques
`end.duration`	`iterations`	Converti en nombre de cycles de facturation
`end.date`	`end_date`	Timestamp Unix
`end.forever`	(absent)	Dernière phase, illimitée
`delay_days > 0` (phase 0)	`trial_end`	Timestamp Unix, now + delay_days

Éléments par phase : un par ligne facturable :

Source CPQ	Champ Stripe	Remarques
`product.name`	`price_data.product_data.name`
`amounts.unit_price`	`price_data.unit_amount`	Prix HT × 100 (centimes)
`billing_frequency`	`price_data.recurring`	interval + interval_count
`amounts.discount_amount`	`items[M].discounts[0].coupon`	Coupon `duration = forever`
Taxe résolue	`default_tax_rates[]`	Mode manuel uniquement

Éléments ponctuels (issus des sections produits, ajoutés à la phase 0) :

Source CPQ	Champ Stripe	Remarques
`product.name`	`price_data.product_data.name`
`amounts.unit_price`	`price_data.unit_amount`	Prix HT × 100
`amounts.discount_amount`	`add_invoice_items[M].discounts[0].coupon`	Coupon `duration = once`
Remises globales	`phases[0].discounts[0].coupon`	Coupon `duration = once`
Taxe résolue	`add_invoice_items[M].tax_rates[]`	Mode manuel uniquement

Exemple : abonnement en 2 phases avec frais de mise en service

Une commande Qwoty avec des frais de mise en service et deux phases récurrentes de 12 mois produit :

Subscription Schedule
├── start_date: now
├── end_behavior: cancel
├── Phase 1 (12 iterations)
│   ├── add_invoice_items
│   │   └── "Setup Fee" — 1 400 € HT
│   └── items
│       └── "Licence Enterprise" — 490 €/month × 10 seats
│           └── coupon: qwoty_xxx_4900_eur_forever (-49 €/month)
└── Phase 2 (12 iterations)
    └── items
        └── "Licence Enterprise" — 590 €/month × 10 seats

Tous les prix sont envoyés hors taxes (HT). La taxe est appliquée par Stripe au moment de la génération de la facture, soit automatiquement (Stripe Tax), soit via les taux de taxe résolus.

CRM

Facturation

Messagerie

Lien de paiement

Stripe Billing

Vue d’ensemble

Authentification

Paramètres

Authentification

Facturation

Taxes

Période d’essai

Après la création

Résultat

Ce qui est créé dans Stripe

Exemple : abonnement en 2 phases avec frais de mise en service

​Vue d’ensemble

​Authentification

​Paramètres

​Authentification

​Facturation

​Taxes

​Période d’essai

​Après la création

​Résultat

​Ce qui est créé dans Stripe

​Exemple : abonnement en 2 phases avec frais de mise en service

Vue d’ensemble

Authentification

Paramètres

Authentification

Facturation

Taxes

Période d’essai

Après la création

Résultat

Ce qui est créé dans Stripe

Exemple : abonnement en 2 phases avec frais de mise en service