Utilisez l’intégration native Stripe de Metronome pour facturer vos clients via Stripe. Avec l’intégration Stripe, lorsqu’une facture est finalisée à la fin de la période de facturation, Metronome crée automatiquement une facture correspondante dans Stripe pour collecter le paiement.
S’appuyer sur les capacités avancées de facturation de Stripe vous aide à réduire le churn involontaire en maximisant votre taux de succès de paiement pour des scénarios comme les clients en paiement à l’usage.
Ce guide décrit comment configurer Stripe comme votre fournisseur de facturation externe, interagir avec l’intégration et comprendre comment Metronome gère les limites de Stripe.
La configuration de l’intégration Stripe implique de connecter Metronome et Stripe puis de configurer les paramètres de facturation.
Connecter Metronome et Stripe
Lorsque vous connectez votre compte Stripe à Metronome, Metronome peut créer automatiquement des factures dans Stripe. La connexion implique d’accorder à Metronome les permissions d’écrire et de lire des données en votre nom sur votre compte Stripe.
Les clients connectent souvent Stripe aux environnements de production et sandbox de Metronome. Cela leur permet de tester de bout en bout d’éventuels changements de prix ou autres mises à jour de facture avant de les activer pour les clients de production. Lorsque vous configurez l’intégration Stripe dans Metronome Sandbox, Metronome se connecte automatiquement à votre mode test Stripe afin que vous puissiez tester votre intégration de bout en bout avec la création de factures et l’encaissement de paiements.
Pour connecter Metronome et Stripe :
- Authentifiez votre compte Stripe depuis Metronome. Rendez-vous dans General Settings - Integrations → cliquez sur Enable et complétez l’assistant Stripe.
- Configurez une connexion Stripe depuis chaque environnement Metronome via lequel vous souhaitez envoyer des factures, comme les environnements de production et sandbox.
- Activez les capacités de relance automatique de paiement de Stripe pour améliorer le succès du paiement des factures.
Connecter Metronome à plusieurs comptes Stripe
Metronome prend en charge la facturation multi-entités avec Stripe pour vous permettre de connecter votre environnement Metronome à plusieurs comptes Stripe. Cette fonctionnalité permet aux entreprises complexes de gérer leur facturation et leurs finances en tant qu’unités d’affaires distinctes. Pour configurer plusieurs comptes Stripe :
- Allez dans Connections - > Integrations
- Sélectionnez Stripe - > Add another
- Sélectionnez le compte Stripe approprié
Une fois terminé, vous verrez une ligne dans Active Integrations pour chaque compte Stripe auquel Metronome est connecté. Vous pouvez créer un alias pour chaque compte afin de les identifier. Par exemple : Stripe NA et Stripe EU. Cet alias apparaîtra partout où le compte Stripe est référencé dans l’application Metronome.
AVERTISSEMENTSi vous utilisez la facturation multi-entités, vous devez utiliser delivery_method_id lors de la configuration de la billing configuration du client. Assurez-vous que votre flow d’inscription client utilise ce champ avant de configurer la facturation multi-entités. Voir définir la customer billing configuration pour plus de détails. | Paramètres de facture | |
|---|
| Définir la date d’échéance de la facture | Stripe utilise par défaut des dates d’échéance de facture dans les 30 jours après leur envoi. Vous pouvez modifier cette option à une valeur différente. Ce paramètre n’a aucun effet pour les clients configurés pour être prélevés automatiquement. |
| Laisser les factures en brouillon | Par défaut, Metronome envoie toutes les factures à Stripe avec l’option auto_advance définie à true, permettant aux factures d’être finalisées dans Stripe immédiatement sans aucune action requise de votre part. Si vous préférez laisser les factures en brouillon pour pouvoir les revoir et les finaliser manuellement dans Stripe, cochez l’option « leave invoices as drafts » dans Metronome. Metronome définit alors auto_advance de Stripe à false. |
| Ignorer les factures à total zéro | Si la facturation Stripe est activée pour un client, toutes les factures finalisées dans Metronome sont envoyées à Stripe par défaut. L’option « skip zero-total invoices » limite cela à l’envoi des factures non nulles uniquement. Stripe impose des limites sur les montants minimaux de prélèvement. Par exemple, avec la devise USD, le prélèvement minimum autorisé est de $0,50. Si vous sélectionnez « skip zero-total invoices », Metronome ignore l’envoi à Stripe des factures inférieures au montant minimum de prélèvement pour la devise. |
| Aligner effective_at sur le dernier jour de la période | Par défaut, Stripe renseigne le champ « Invoice Date » sur les factures PDF et effective_at dans l’API avec la date à laquelle la facture est finalisée. Utilisez ce paramètre pour renseigner le champ effective_at avec la dernière date de la période de service de la facture (par exemple, le 31 octobre pour une facture du 1er au 31 octobre). Cela permet de s’assurer que les factures d’usage sont suivies par rapport à la bonne période comptable, en cohérence avec les pratiques de reconnaissance des revenus dans les systèmes financiers en aval. Ce paramètre n’est pas pris en charge avec Stripe Tax en raison d’une limitation de Stripe qui provoque l’échec de la synchronisation des factures. |
| Présentation de la facture | |
|---|
| Afficher les lignes avec quantité zéro sur les factures Stripe | Si sélectionné, Metronome crée une ligne Stripe sur les factures Stripe pour toutes les charges, y compris celles ayant une quantité de zéro. |
| Toujours afficher les informations de prix et de quantité dans les descriptions de ligne des factures Stripe | Comme Stripe ne prend pas en charge les quantités décimales, Metronome affiche par défaut les quantités dans les descriptions de ligne si au moins une quantité sur une facture n’est pas un entier. En sélectionnant « always display quantities in line items », les quantités apparaîtront toujours dans les noms de ligne, que la facture comporte ou non des quantités non entières. |
INFOCes paramètres sont appliqués par compte Stripe au niveau de l’environnement. Vous ne pouvez pas configurer de préférences spécifiques au client.
Créer des règles de mapping d’entité optionnelles
Par défaut, Metronome définit des métadonnées sur les objets de facture Stripe qu’il crée. Un des éléments qu’il définit est metronome_id, qui est l’ID de facture Metronome qui vous permet de mapper une facture Stripe à sa facture Metronome correspondante.
Vous pouvez vouloir ajouter des métadonnées supplémentaires aux entités Stripe. Par exemple :
- Ajouter des attributs comme le nom du contrat ou l’ID du contrat à la facture Stripe (visible par les clients) en mappant des champs personnalisés Metronome de contrat ou de grille tarifaire à des champs personnalisés de facture Stripe.
- Ajouter des métadonnées comme la ligne de facture et les objets price de ligne de facture à la facture Stripe pour vos audits internes ou pour des intégrations en aval comme le calcul de taxes.
Pour configurer Metronome afin qu’il ajoute automatiquement vos propres métadonnées supplémentaires aux entités Stripe, modifiez les règles de mapping de l’intégration Stripe entre les champs personnalisés Metronome et les entités Stripe sur la page General Settings - Integrations.
Si vous êtes connecté à plusieurs comptes Stripe, vous devrez configurer chacun de ces mappings individuellement.
Exemple : assigner des lignes à des produits Stripe
Un cas d’usage courant pour ajouter des métadonnées aux entités Stripe est d’assigner les lignes d’une facture Metronome à un produit existant dans Stripe. Pour ce faire :
- Créez une clé de champ personnalisé sur l’entité produit Metronome :
stripe_product_id.
- Définissez la valeur de la clé de champ personnalisé que vous venez de créer pour chacun de vos produits dans Metronome.
- Allez sur la page General Settings - Integrations et modifiez les règles de mapping pour mapper la clé de champ personnalisé Metronome
stripe_product_id à invoiceitem.price de Stripe.
Obligatoire pour les engagements à paiement préalableSi vous utilisez des engagements à paiement préalable, chaque produit Metronome utilisé sur un engagement à paiement préalable doit avoir un champ personnalisé stripe_product_id mappé à un Stripe Product ID valide. Sans ce mapping, Stripe ne peut pas générer la ligne de facture et la tentative de paiement échouera, annulant l’engagement. Définir la customer billing configuration
Pour déterminer quelles factures envoyer à Stripe, Metronome examine la billing_configuration de chaque client. La billing_configuration est un objet à l’intérieur de l’objet client Metronome qui capture des métadonnées supplémentaires nécessaires à la prise en charge des intégrations natives de Metronome. Cela inclut des informations comme le customer.id du fournisseur de facturation et les préférences de facture. Si la billing_configuration du client est définie sur Stripe, une facture Stripe est émise au client Stripe correspondant.
Définissez la billing configuration pour un client dans l’application Metronome ou via l’API.
INFOSi vous êtes connecté à plusieurs comptes Stripe, vous ne pouvez définir la billing configuration que via l’API.
/customers ou après que le client existe déjà avec /setCustomerBillingProviderConfigurations définissant la billing configuration.
Pour définir une billing configuration, Metronome exige que vous spécifiiez soit un delivery_method, soit un delivery_method_id. Si vous vous connectez à un seul compte Stripe, utilisez delivery_method. Si vous vous connectez à plusieurs comptes Stripe, vous devez utiliser delivery_method_id. Metronome utilise cet ID pour déterminer vers quel compte Stripe chaque facture doit être envoyée.
INFOVous pouvez trouver le delivery_method_id en utilisant l’endpoint /listConfiguredBillingProviders pour récupérer les comptes Stripe configurés dans l’environnement Metronome.
/customers pour définir la billing configuration en utilisant delivery_method :
curl https://api.metronome.com/v1/customers \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"ingest_aliases": [
"team@example.com"
],
"name": "Example, Inc.",
"customer_billing_provider_configurations": [{
"billing_provider": "stripe",
"configuration": {
"stripe_customer_id": "cus_456",
"stripe_collection_method": "charge_automatically"
},
"delivery_method": "direct_to_billing_provider"
}]
}'
/setCustomerBillingProviderConfigurations pour définir la billing configuration d’un client existant en utilisant delivery_method_id :
curl https://api.metronome.com/v1/setCustomerBillingProviderConfigurations \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"data": [
{
"customer_id": "4db51251-61de-4bfe-b9ce-495e244f3491",
"billing_provider": "stripe",
"configuration": {
"stripe_customer_id": "cus_1234",
"stripe_collection_method": "charge_automatically"
},
"delivery_method_id": "5b95d955-b705-41c8-9d2e-34ccbdee5193"
}
]
}'
stripe_customer_id : l’ID du client Stripe pour lequel une facture Stripe est émise.stripe_collection_method : détermine comment encaisser le paiement pour le client. Stripe prend en charge deux méthodes d’encaissement :
-
charge_automatically : Stripe tente de prélever la facture en utilisant le moyen de paiement par défaut attaché au client.
charge_automatically nécessite qu’un moyen de paiement par défaut soit défini sur le client Stripe avant que la facture ne soit finalisée. Si aucun moyen de paiement par défaut n’est configuré, Stripe ne peut pas prélever la facture et le paiement échouera. Confirmez que le client a un moyen de paiement par défaut dans Stripe avant d’utiliser cette méthode d’encaissement.
-
send_invoice : Stripe envoie par e-mail cette facture au client avec les instructions de paiement. Pour l’option send_invoice, vous devez spécifier de combien de jours dispose un client jusqu’à l’échéance du paiement. Cela correspond au champ days_until_due dans l’API Stripe. Par défaut, les factures Stripe sont dues 30 jours après leur création. L’API Metronome ne vous permet pas de définir cette valeur directement, mais vous pouvez mettre à jour ce paramètre sur la page General Settings - Integrations.
Définir la billing configuration du contrat
Metronome prend en charge la configuration de la facturation au niveau du contrat. Cela vous permet d’optimiser la facturation pour chaque contrat : vous pouvez envoyer les contrats de paiement à l’usage via Stripe, mais les contrats de niveau entreprise via AWS.
Cet exemple de payload utilise l’endpoint /contracts/create pour définir la billing configuration :
curl https://api.metronome.com/v1/contracts/create \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "6ae46ff3-a73e-4553-a139-346eafcea608",
"rate_card_id": "cfe45e46-0277-42e0-b66a-45ccbd028913",
"starting_at": "2025-01-01T00:00:00.000Z",
"billing_provider_configuration": {
"billing_provider": "stripe",
"delivery_method": "direct_to_billing_provider"
}
}'
billing_configuration_id qui peut être récupéré depuis l’endpoint /getCustomerBillingProviderConfigurations :
curl https://api.metronome.com/v1/contracts/create \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "6ae46ff3-a73e-4553-a139-346eafcea608",
"rate_card_id": "cfe45e46-0277-42e0-b66a-45ccbd028913",
"starting_at": "2025-01-01T00:00:00.000Z",
"billing_provider_configuration": {
"billing_provider_configuration_id": "561ea579-e830-41d9-9161-d35313c061c5"
}
}'
Ajouter un fournisseur de facturation à un contrat existant
Lorsque vous ajoutez une configuration de fournisseur de facturation à un contrat existant, Metronome n’envoie pas rétroactivement les factures précédemment finalisées à Stripe. Seules les factures qui se finalisent après l’ajout de la configuration au contrat sont envoyées à Stripe.
La première facture envoyée à Stripe est la facture d’usage à terme échu de la période de facturation pendant laquelle la configuration a été ajoutée. Par exemple :
| Date | Événement |
|---|
| 1er janv. | Le contrat commence |
| 1er févr. | La configuration du fournisseur de facturation est créée |
| 15 avr. | La configuration est ajoutée au contrat |
| 1er mai | Première facture envoyée à Stripe (usage à terme échu d’avril) |
Metronome détermine la première facture à envoyer en fonction du moment où la configuration a été ajoutée au contrat, et non du moment où le contrat a commencé ou où la configuration a été créée.
Interagir avec l’intégration Stripe
Après avoir connecté Stripe à Metronome, utilisez l’API et l’application Metronome pour interagir avec votre intégration.
Suivre les statuts de facture Stripe dans Metronome
Metronome capture les événements webhook Stripe lorsque le statut d’une facture change.
Les statuts de facture Stripe sont accessibles dans Metronome dans le cadre de la réponse lors de la récupération des factures depuis l’endpoint API list invoices.
{
"id": "INVOICE_ID",
...
"external_invoice": {
"billing_provider_type": "stripe",
"invoice_id": "in_123",
"issued_at_timestamp": "2024-09-30T16:40:40.30184+00:00",
"external_status": "PAID"
},
...
}
INFOSi la configuration globale est définie sur Leave invoices as drafts, Stripe ne retourne pas de statut et vous ne verrez pas de statut de facture Stripe dans Metronome.
Calculer dynamiquement la taxe de vente
L’intégration native Stripe de Metronome prend en charge les fournisseurs de taxe Anrok, Avalara et Stripe Tax pour ajouter la taxe à une facture créée dans Stripe. Le choix dépend de votre fournisseur de facturation et de vos besoins de conformité :
| Fournisseur | Intégration de facturation |
|---|
| Stripe Tax | Oui |
| Anrok | Oui (via l’application Stripe) |
| Avalara | Oui (via l’application Stripe) |
- Le relevé d’usage Metronome se finalise, créant une facture en brouillon correspondante dans Stripe.
- Metronome transmet les données de mapping d’entité (IDs de produit, métadonnées) à la facture Stripe.
- Votre fournisseur de taxe calcule la taxe sur la facture Stripe.
- La facture est finalisée dans Stripe avec la taxe incluse.
Pour les instructions de configuration, consultez le guide dédié à votre fournisseur : Stripe Tax, Anrok ou Avalara.
Lors de l’intégration avec Avalara ou Anrok directement via Stripe (et non via une application Stripe), Metronome accorde par défaut jusqu’à une heure pour que la taxe soit appliquée aux factures en brouillon avant la finalisation. Notez qu’après une heure, la facture est finalisée dans Stripe. Si vous préférez garder ces factures en brouillon indéfiniment, activez l’option « Leave invoices as drafts » dans vos paramètres d’intégration Stripe.
Si vous utilisez un fournisseur de taxe non listé ci-dessus, ou si vous n’utilisez pas Stripe pour la facturation, contactez votre représentant Metronome pour des conseils sur la configuration de la taxe.
Timing du paiement pour les factures charge_automatically
Metronome finalise les factures immédiatement à la fin de la période de facturation — il n’y a pas d’attente avant que la facture soit envoyée à Stripe. Cependant, lorsque Metronome envoie une facture finalisée à Stripe avec charge_automatically, Stripe attend jusqu’à une heure après la livraison du webhook invoice.created avant de tenter le paiement. La facture reste à l’état open pendant cette fenêtre.
Ce délai est un comportement côté Stripe qui s’applique spécifiquement aux factures finalisées manuellement via l’API (ce qui est la façon dont Metronome soumet toutes les factures aujourd’hui). Il n’est pas configurable dans le Dashboard Stripe — le paramètre « grace period » dans Stripe contrôle uniquement la transition draft → finalized, et non la transition finalized → tentative de paiement.
Ce délai ne s’applique pas à :
Si vous constatez des délais supérieurs à une heure : Stripe se rabat sur une attente de 72 heures lorsque la livraison du webhook invoice.created échoue. Si des factures restent à l’état open bien au-delà d’une heure, vérifiez que votre endpoint webhook Stripe est correctement configuré et renvoie une réponse 2xx.
Contournement pour éviter l’attente d’une heure : confirmez vous-même le payment intent immédiatement après que la facture est finalisée :
- Écoutez le webhook Stripe
invoice.finalized ou payment_intent.created.
- Extrayez l’ID du
payment_intent du payload de l’événement.
- Appelez
POST /v1/payment_intents/:id/confirm sur l’API Stripe.
Cela réduit le temps entre la finalisation et la tentative de paiement à quelques secondes.
Écouter les erreurs
Des erreurs de facturation peuvent survenir. Par exemple, des erreurs se produisent lorsque les clients Stripe n’existent pas. Pour recevoir des notifications de Metronome lorsqu’une erreur d’envoi d’une facture à Stripe survient, écoutez le type de webhook invoice.billing_provider_error. Lors de la réception de ces webhooks, déclenchez des notifications et actions internes pour garantir la bonne facturation de vos clients.
Stripe impose certaines limites sur les factures qui peuvent provoquer des écarts ou des problèmes lors de la facturation des clients. Ce tableau décrit comment Metronome gère ces limitations.
| Limitation Stripe | Approche de Metronome |
|---|
| Stripe ne prend pas en charge les quantités décimales | Si la quantité est une décimale pour au moins une ligne de la facture, Metronome définit la quantité à 1 pour toutes les lignes Stripe de la facture. Metronome fournit la vraie quantité dans le cadre de la description de chaque ligne. |
| Stripe impose un maximum de 250 lignes sur ses factures | Si une facture client dans Metronome dépasse 250 lignes, la facture est condensée en une seule ligne, étiquetée avec le nom de votre société et le total de la facture comme prix associé. Offrez à vos clients une visibilité complète sur la facture (avec toutes les lignes) grâce à des tableaux de bord qui exposent les factures dans votre interface. |
| Stripe n’autorise pas de prélèvement supérieur à 999 999,99 USD | Metronome génère une erreur lors de la création d’une facture avec un montant supérieur au maximum Stripe. Contactez votre représentant Stripe et votre représentant Metronome pour augmenter la limite si vous avez besoin de factures avec des montants supérieurs à $999 999,99. |
| Pas de prise en charge native pour l’émission d’avoirs avec Metronome | L’intégration Metronome ne prend pas en charge nativement l’émission d’avoirs (credit memos) dans Stripe. Découvrez comment émettre des avoirs. |
