# Fonctionnement des extensions

Découvrez comment personnaliser Stripe avec des extensions.

Les extensions vous permettent d’exécuter une logique personnalisée à des emplacements désignés dans Stripe, appelés [points d’extension](https://docs.stripe.com/extensions/extension-points.md). Lorsque Stripe doit exécuter la logique à ces points d’extension, elle vérifie si une extension y est connectée et, si c’est le cas, exécute la logique personnalisée dans l’extension.

Par exemple, Stripe définit un point d’extension pour les [proratas](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md). Lorsque Stripe atteint l’étape du calcul du prorata, elle exécute la logique de votre extension au lieu de la logique de prorata par défaut. Votre extension détermine comment facturer au prorata, renvoie le montant, et Stripe poursuit le flux de facturation avec ce résultat.

Stripe définit également un point d’extension d’action personnalisée pour les [Workflows](https://docs.stripe.com/extensions/custom-actions/how-custom-actions-work.md). Lorsqu’un workflow se déclenche, Stripe appelle votre extension pour envoyer un email, mettre à jour un CRM ou effectuer toute autre opération que vous définissez.

## Fonctionnement du modèle

Stripe définit des points d’extension, c’est-à-dire des emplacements spécifiques dans les produits Stripe où votre code peut s’exécuter. Chaque point d’extension spécifie :

- **Entrée** : les données que Stripe envoie à votre extension lorsque le point d’extension est atteint, notamment les entrées de l’utilisateur de l’extension
- **Sortie** : les données que votre extension doit renvoyer à Stripe
- **Types de mise en œuvre autorisés** : quels types de mise en œuvre (scripts, fonctions distantes, ou les deux) vous pouvez utiliser à ce point d’extension

(See full diagram at https://docs.stripe.com/extensions/how-extensions-work)

```text
[Entrée par l’utilisateur] --> [Validation]
[Validation] --> [Code de l’extension]
[Entrée par Stripe] --> [Code de l’extension]
[Code de l’extension] --> [Résultat]
```

Commencez par trouver le [point d’extension](https://docs.stripe.com/extensions/extension-points.md) pour votre cas d’usage.

Vous créez votre logique personnalisée comme une extension qui s’intègre à un point d’extension. Nous proposons les extensions dans le cadre de [Stripe Apps](https://docs.stripe.com/stripe-apps.md), qui gère l’installation, les autorisations et la distribution. Vous pouvez avoir plusieurs extensions regroupées au sein de la même application, de tout type d’implémentation : [scripts](https://docs.stripe.com/extensions/how-extensions-work.md#scripts), [remote functions](https://docs.stripe.com/extensions/how-extensions-work.md#remote-functions) ou [UI Extensions](https://docs.stripe.com/extensions/how-extensions-work.md#ui-extensions). Les applications peuvent également contenir des [objets personnalisés](https://docs.stripe.com/custom-objects.md).

## Types de mise en œuvre

Chaque point d’extension prend en charge un ou plusieurs types de mise en œuvre. Le type de mise en œuvre détermine où votre code s’exécute et comment il interagit avec les services externes.

### Choisir un type de mise en œuvre

Si un point d’extension prend en charge à la fois les scripts et les fonctions distantes, utilisez ce tableau pour décider :

| Considération | Script | Fonction distante |
| --- | --- | --- |
| Où elle s’exécute | Environnement d’exécution géré de Stripe | Votre infrastructure |
| Langue | TypeScript | Toute langue (endpoint HTTP) |
| Appels API externes | Dépendant des points d’extension. Autorisé pour les actions personnalisées (via `endpointFetch()`). Non autorisé pour les points d’extension de facturation. | Oui, vous effectuez des appels directement depuis vos serveurs |
| Autorisation pour les services externes | Stripe injecte les secrets via la configuration de l’endpoint et le [Secret Store](https://docs.stripe.com/stripe-apps/store-secrets.md) (dans lequel les appels à l’API externes sont autorisés) | Vous gérez vous-même l’authentification |
| Autorisation de Stripe vers votre code | N/A, votre code s’exécute sur Stripe | Stripe signe chaque requête. Vous [vérifiez la signature webhook](https://docs.stripe.com/webhooks.md#verify-signature). |
| Idéal pour | Logique qui n’a pas besoin de votre propre infrastructure | Logique qui nécessite vos propres systèmes, transformations ou langages autres que TypeScript |
| Limites | Aucune dépendance tierce, pas de `fetch()` brut, TypeScript uniquement | Vous gérez l’hébergement, la disponibilité et le déploiement |

### Scripts

Les scripts sont des méthodes TypeScript qui s’exécutent sur le moteur d’exécution entièrement géré de Stripe. Vous n’avez pas besoin de gérer d’infrastructure, car c’est Stripe qui exécute votre code et vous effectuez le déploiement en téléchargeant votre application via la CLI Stripe.

Les scripts exécutent votre logique métier lorsque Stripe atteint un point d’extension. Utilisez des scripts lorsque vous avez besoin d’effectuer ce qui suit :

- Appliquer des règles d’entreprise complexes à l’aide de code comme le calcul d’une remise basée sur l’historique d’achat du client et les événements promotionnels.
- Valider ou transformer des données avant qu’elles ne soient traitées par Stripe, par exemple pour vérifier si un client remplit les critères d’éligibilité.
- Intégrer des données externes dans les opérations Stripe sans avoir à créer ni à maintenir de webhooks.
- Réaliser des prototypes rapidement sans avoir à déployer ni à gérer vos propres services.

Ce que les scripts peuvent faire dépend du point d’extension :

- **Aux points d’extension de facturation** (solde client, gestion des éléments, calculs au prorata) : les scripts reçoivent des données de Stripe, exécutent votre logique et renvoient un résultat. Les appels à l’API externes ne sont pas autorisés. Ces points d’extension s’exécutent dans le pipeline de facturation, où Stripe limite les effets de bord afin de garantir la fiabilité.
- **Au point d’extension d’action personnalisée** (pour les Workflows) : Les scripts peuvent effectuer des appels HTTP externes à l’aide de `endpointFetch()`. Vous déclarez les endpoints dans votre [manifeste d’application](https://docs.stripe.com/stripe-apps/reference/app-manifest.md?manifestVersion=manifest-v2), et Stripe gère le stockage des secrets et l’injection de l’authentification via le [Secret Store](https://docs.stripe.com/stripe-apps/store-secrets.md). Ceci est conçu pour les actions qui accèdent à des services externes sans que vous ayez à gérer d’infrastructure.

#### Cas d’usage

| Cas d’usage | Comportement de Billing | Script | Description |
| --- | --- | --- | --- |
| Définir un seuil de paiement minimum. | Solde client | [Montant minimal avant recouvrement](https://docs.stripe.com/billing/scripts/stripe-authored/customer-balance.md#minimum-amount-before-collection) | Utilisez ce script pour éviter le recouvrement des factures de faible montant en les reportant sur le solde du client jusqu’à ce que le total dû atteigne un seuil que vous définissez. Utilisez-le lorsque vous souhaitez cumuler des frais sur plusieurs cycles de facturation avant de procéder au recouvrement, ou pour éviter de facturer de petits montants à vos clients. |
| Définir un crédit maximum à appliquer à une seule facture. | Solde client | [Crédit maximal par facture](https://docs.stripe.com/billing/scripts/stripe-authored/customer-balance.md#maximum-credit-per-invoice) | Utilisez ce script lorsque vous souhaitez répartir les crédits sur plusieurs cycles de facturation plutôt que de les appliquer en une seule fois, ou lorsque des règles métier exigent de limiter l’utilisation du crédit par facture. |
| Placer les postes de consommation effective et les postes sous licence sur des factures distinctes. | Création et acheminement des postes de facture | [Facture séparée pour les éléments facturés à l’usage](https://docs.stripe.com/billing/scripts/stripe-authored/invoice-item-creation-and-routing.md#separate-invoice-for-metered-items) | Utilisez ce script lorsque votre équipe financière doit rapprocher séparément les frais liés à l’usage des frais récurrents par siège ou par licence, ou lorsque vos clients s’attendent à recevoir des factures distinctes pour ceux-ci. |
| Calculer les proratas en heures, jours, semaines ou mois. | Prorata | [Facturer au prorata selon un intervalle personnalisé](https://docs.stripe.com/billing/scripts/stripe-authored/proration.md#prorate-by-custom-interval) | Utilisez ce script chaque fois que votre activité nécessite un calcul au prorata selon des unités supérieures à la seconde, que ce soit pour respecter des conventions de facturation régionales, se conformer à des conditions contractuelles ou réduire la confusion des clients liée à des montants fractionnés. |
| Rembourser ou facturer le montant total de certains postes d’un abonnement. | Prorata | [Créditer et débiter le prix total du produit](https://docs.stripe.com/billing/scripts/stripe-authored/proration.md#credit-and-debit-full-product-price) | Utilisez ce script lorsque certains produits d’un abonnement ne sont pas facturés au prorata. Par exemple, des frais de support fixes ou des frais d’accès à une plateforme qui sont toujours facturés en totalité, quelle que soit la date à laquelle l’abonnement est modifié. |
| Appliquer une remise en pourcentage avec un montant maximum. | Calcul de la remise | [Pourcentage de remise avec plafond](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#percent-off-up-to-maximum) | Utilisez ce script pour proposer une remise en pourcentage tout en plafonnant le montant maximal de remise appliqué sur une facture. |
| Offrez gratuitement des unités supplémentaires de produits sélectionnés. | Calcul de la remise | [Offres BOGO et promotions sur la quantité](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#bogo-and-quantity-promos) | Utilisez ce script pour des promotions basées sur la quantité pour les produits sélectionnés par des métadonnées. |
| Appliquer une remise fixe sur des prix sélectionnés. | Calcul de la remise | [Montant de remise ciblé par prix](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#price-targeted-amount-off) | Utilisez ce script pour déduire un montant fixe sur les prix sélectionnés par métadonnées, sans appliquer de remise sur les autres postes de facture. |
| Appliquer une remise en pourcentage sur des prix sélectionnés. | Calcul de la remise | [Pourcentage de remise ciblé par prix](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#price-targeted-percent-off) | Utilisez ce script pour appliquer une promotion en pourcentage sur les prix sélectionnés par métadonnées, sans réduire les autres postes de facture. |

#### Limites

La plupart des fonctionnalités [TypeScript](https://www.typescriptlang.org/docs/handbook/intro.html#get-started) fonctionnent dans l’environnement d’exécution de Stripe, mais les modèles suivants ne sont pas disponibles. Les étapes de compilation et de téléversement les détectent automatiquement :

- Les fonctions d’évaluation de code telles que `eval()` ou `new Function()`
- Fonctions de temporisation telles que `setTimeout()`, `setInterval()` et `setImmediate()`
- L’accès au scope global via `global` ou `globalThis`
- Les API liées au processus, telles que `process.exit()` ou `process.env`
- `console.log()`. Utilisez [Workbench](https://docs.stripe.com/workbench.md) pour consulter les journaux d’exécution des logs.
- Clés API ou clés secrètes intégrées dans le code. Utilisez le [Stripe secret store](https://docs.stripe.com/stripe-apps/store-secrets.md) pour gérer les valeurs sensibles.
- API d’accès au réseau telles que `fetch()`. Utilisez `endpointFetch()` pour [invoquer des endpoints depuis un script](https://docs.stripe.com/extensions/invoke-endpoints.md).

Stripe ne prend actuellement pas en charge les bibliothèques tierces en tant que dépendances.

### Fonctions distantes

Les fonctions distantes sont des endpoints HTTP que vous hébergez sur votre propre infrastructure. Stripe appelle votre endpoint lorsque le point d’extension est atteint, en signant chaque requête avec une [signature webhook](https://docs.stripe.com/webhooks.md#verify-signature) afin que vous puissiez vérifier qu’elle provient de Stripe.

Vous gérez l’authentification pour tout service externe que votre code appelle, Stripe n’injecte pas de clés secrètes pour les fonctions à distance. Vous vérifiez la signature Stripe entrante, et vous gérez vous-même l’autorisation sortante.

Utilisez des fonctions distantes lorsque vous devez :

- Exécuter la logique sur vos propres serveurs ou dans votre propre environnement
- Intégrer vos propres systèmes tels que votre ERP ou votre CRM.
- Utiliser un langage autre que TypeScript

#### Limites

Les fonctions à distance présentent actuellement les limites suivantes :

- Vous gérez l’hébergement, la disponibilité et le déploiement.
- Vos endpoints doivent répondre dans le délai défini par le point d’extension (par exemple, 20 secondes pour les actions personnalisées).

### Extensions d’interface utilisateur

Composants React affichés dans le Dashboard Stripe. Utilisez une extension d’interface utilisateur pour proposer des éléments d’interface utilisateur personnalisés aux utilisateurs du Dashboard. Voir [Extensions d’interface utilisateur](https://docs.stripe.com/stripe-apps/how-ui-extensions-work.md).

## Autorisations

Lorsque vous créez une extension, vous devez déclarer les autorisations dont votre extension a besoin. Une extension ne peut accéder qu’aux données pour lesquelles elle a reçu l’autorisation de lecture ou d’écriture. Les utilisateurs d’extensions accordent ces autorisations lors de l’installation de l’application contenant les extensions. Consultez la liste complète de toutes les [autorisations](https://docs.stripe.com/stripe-apps/reference/permissions.md).

## Comptes connectés

Vos extensions configurées ne s’appliquent pas à vos comptes connectés. Les comptes connectés doivent configurer l’extension indépendamment dans leur application installée.

## Cycle de vie

Une extension peut suivre ce cycle de vie. La gestion des versions, la publication, la dépréciation et l’archivage sont facultatifs :

1. **Création** : vous créez une extension au sein d’une application Stripe.
2. **Téléchargement** : vous téléchargez l’application à l’aide de l’interface CLI de Stripe qui la traite et la rend disponible à l’installation.
3. (Facultatif) **Version** : vous téléchargez de nouvelles versions au fur et à mesure de vos itérations.
4. (Facultatif) **Publication** : vous partagez l’application via un [canal de test externe](https://docs.stripe.com/stripe-apps/test-app.md) ou la plateforme [Stripe App Marketplace](https://docs.stripe.com/stripe-apps/publish-app.md). Elle devient alors disponible à l’installation sur les comptes de vos clients.
5. **Installation** : vous, ou vos clients avec lesquelles l’application est partagée, l’installez en acceptant les autorisations associées.
6. **Activation** : l’utilisateur de l’application active une extension à son point d’extension.
7. **Invocation** : Stripe sollicite l’extension activée chaque fois qu’elle atteint le point d’extension.
8. (Facultatif) [Déprécier](https://docs.stripe.com/extensions/manage-extension-lifecycle.md) : l’utilisateur de l’application ne peut pas activer une version d’une extension, mais les extensions déjà activées sur cette version continuent de s’exécuter.
9. (Facultatif) [Archiver](https://docs.stripe.com/extensions/manage-extension-lifecycle.md) : les extensions activées sont déplacées vers une version compatible, ou leur exécution est bloquée si aucune version n’est définie.
10. **Désactivation** : l’utilisateur de l’application désactive l’extension. Celle-ci reste associée au compte, mais Stripe ne la sollicite plus lorsqu’elle atteint le point d’extension.
11. **Désinstallation** : l’utilisateur supprime l’application et ses extensions de son compte.

## Démarrer la création

Si vous cherchez à personnaliser la facturation, commencez par le guide étape par étape : [Créer une extension de script de facturation](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md). Il couvre les prérequis, la création de l’application, les commandes CLI et le téléversement.

Sinon, le guide que vous suivez dépend du point d’extension pour lequel vous créez :

- [Créez une extension de script de facturation](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md) pour personnaliser le solde client, la gestion des éléments ou le comportement du calcul au prorata.
- [Créez une action de flux de travail personnalisée à l’aide d’un script](https://docs.stripe.com/extensions/custom-actions/build-with-script.md) ou de [fonctions distantes](https://docs.stripe.com/extensions/custom-actions/build-with-remote-function.md). Apprenez davantage sur le [mode de fonctionnement des actions personnalisées](https://docs.stripe.com/extensions/custom-actions/how-custom-actions-work.md).

Pour obtenir la liste complète des points d’extension disponibles et de leurs types de mises en œuvre prises en charge, consultez [Points d’extension](https://docs.stripe.com/extensions/extension-points.md).