Stripe Billing

Vue d’ensemble

L’intégration Stripe Billing transforme une commande Qwoty signée en Stripe Subscription Schedule. 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 uniques (frais de mise en service, matériel, onboarding) sont attachés en tant qu’é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’article, de la phase ou de l’add-invoice-item. Si la commande contient 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édez à votre tableau de bord Stripe

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

Créez une clé API restreinte

Accédez à Developers → API keys → Create restricted key.Accordez un accès en écriture à : Customers, Subscriptions, Subscription Schedules, Invoices, Tax rates, Coupons.

Copiez la clé secrète

Copiez la clé commençant par sk_live_ (ou sk_test_ pour les tests).

Collez-la 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), définissez Token scope sur business_unit et fournissez une clé par identifiant d’unité commerciale.

Paramètres

Authentification

Clé	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é	Défaut	Description
`collection_method`	`charge_automatically`	La façon dont Stripe collecte le paiement. `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 accordés au client pour payer (utilisé uniquement lorsque `collection_method = send_invoice`).
`payment_behavior`	`allow_incomplete`	Comportement en cas d’échec du premier paiement. `allow_incomplete` — crée l’abonnement avec le 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é	Défaut	Description
`tax_mode`	`manual`	`automatic` — Stripe Tax calcule les taux de taxe automatiquement (nécessite l’activation de Stripe Tax). `manual` — les taux de taxe sont issus de la commande Qwoty et synchronisés avec Stripe.

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

Période d’essai

Clé	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 une facture quoi qu’il en soit. `pause` — met l’abonnement en pause. `cancel` — annule l’abonnement.

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

Post-création

Clé	Défaut	Description
`post_action`	`none`	Action effectuée après la création du schedule. `none` — aucune action. `send_email` — envoie un e-mail de confirmation via Qwoty.

Résultat

Ce qui est créé dans Stripe

1. Client (s’il n’est pas déjà associé) L’intégration recherche le client par son identifiant Qwoty (stocké dans les métadonnées Stripe), puis par e-mail. S’il n’est pas trouvé, un nouveau client Stripe est créé et l’identifiant Stripe est renvoyé dans Qwoty (external_ids.accounting). 2. Coupons (un par montant de remise unique) Pour chaque remise dans la commande, l’intégration recherche un coupon Stripe existant avec l’identifiant qwoty_{orderId}_{amountCents}_{currency}_{duration} avant d’en créer un nouveau. Tous les coupons Qwoty sont préfixés par qwoty_ pour une identification facile 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 entrée de taxe. S’ils ne sont pas trouvés, l’intégration effectue une recherche dans Stripe par pourcentage et pays, puis crée un nouveau taux de taxe s’il est absent. 4. Subscription Schedule

Source CPQ	Champ Stripe	Notes
Client résolu	`customer`
`start.type = sign_day`	`start_date = "now"`
`start.type = date`	`start_date`	Horodatage 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`	Si renseigné

Phases — une par phase de plan CPQ :

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

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

Source CPQ	Champ Stripe	Notes
`product.name`	`price_data.product_data.name`
`amounts.unit_price`	`price_data.unit_amount`	Prix brut × 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 uniques (issus des sections produit, ajoutés à la phase 0) :

Source CPQ	Champ Stripe	Notes
`product.name`	`price_data.product_data.name`
`amounts.unit_price`	`price_data.unit_amount`	Prix brut × 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 2 phases avec frais de mise en service

Une commande Qwoty avec un 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 en montants bruts (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

Post-création

Résultat

Ce qui est créé dans Stripe

Exemple — Abonnement 2 phases avec frais de mise en service

​Vue d’ensemble

​Authentification

​Paramètres

​Authentification

​Facturation

​Taxes

​Période d’essai

​Post-création

​Résultat

​Ce qui est créé dans Stripe

​Exemple — Abonnement 2 phases avec frais de mise en service

Vue d’ensemble

Authentification

Paramètres

Authentification

Facturation

Taxes

Période d’essai

Post-création

Résultat

Ce qui est créé dans Stripe

Exemple — Abonnement 2 phases avec frais de mise en service