# Intégrez l’API Provisioning à votre plateforme Utilisez l’API Provisioning depuis le back-end de votre plateforme pour connecter des Fournisseurs, provisionner des Ressources, récupérer des identifiants et gérer des services payants pour les locataires autorisés. > L’accès à l’API Provisioning est soumis à une liste d’autorisation lors de la version bêta privée. Contactez votre représentant Stripe ou envoyez un e-mail à l’adresse [provisioning-preview@stripe.com](mailto:provisioning-preview@stripe.com) pour y accéder. > > Lors de la version bêta privée, envoyez la version d’API en version bêta **2026-09-30.preview** dans l’en-tête `Stripe-Version`. Le contrat d’API peut changer pendant la version bêta. Confirmez le contrat de requête et de réponse activé pour votre cohorte avant le déploiement, tolérez les nouveaux champs de réponse et utilisez les valeurs d’énumération renvoyées au lieu de supposer l’orthographe sur le réseau. Dans ce flux, vous vous identifiez avec la clé Stripe de votre plateforme et utilisez `Stripe-Context` pour agir au nom d’un compte connecté autorisé. Ce guide ne couvre pas les intégrations de comptes directes. ## Avant de commencer Avant d’écrire du code, identifiez le compte qui effectue chaque requête, comprenez la façon dont Stripe définit la portée des objets Provisioning et confirmez les fonctionnalités que Stripe a activées pour vous. Les sections suivantes expliquent le modèle de compte, la portée et les relations des objets, ainsi que les vérifications à effectuer avant votre première requête d’écriture. ### Utilisez le modèle de compte approprié Avant d’enregistrer des moyens de paiement ou de mettre en place des ressources payantes pour les utilisateurs, effectuez ces étapes de configuration. | Acteur ou objet | Responsabilité | | --- | --- | | Compte de la plateforme | Identifie les appels d’API avec une clé limitée approuvée ou, le cas échéant, sa clé secrète de plateforme. | | Locataire de plateforme | Votre limite d’autorisation durable, telle qu’un espace de travail ou une organisation. | | Compte connecté | Le compte Stripe qui possède les projets, les connexions au fournisseur, les ressources, le profil de paiement, les identifiants et l’utilisation. | | Environnement d’application | Votre limite de déploiement, telle que la version bêta ou la production. | | Back-end de plateforme | Résout l’utilisateur identifié vers un locataire et un compte connecté, appelle Stripe, conserve l’état et gère les secrets. | | Fournisseur | Un tiers qui propose des services et possède l’infrastructure sous-jacente. | Stockez un mappage vérifié de chaque `tenant_id` vers son `connected_account_id`, et utilisez-le pour résoudre le compte connecté. Ne transmettez pas l’ID d’un compte connecté provenant d’une requête de navigateur, d’une invite de modèle, d’un paramètre d’URL ou d’une application générée directement à Stripe. Incluez les valeurs suivantes dans chaque requête identifiée vers l’API Provisioning : ``` Authorization: Bearer {{PLATFORM_SECRET_OR_RESTRICTED_KEY}} Stripe-Context: {{CONNECTED_ACCOUNT_ID}} Stripe-Version: 2026-09-30.preview Content-Type: application/json ``` Avant que votre back-end n’ajoute `Stripe-Context`, vérifiez que l’utilisateur est autorisé à accéder au locataire et au compte connecté. N’autorisez pas un navigateur, une application générée ou un agent de codage à appeler directement l’API Provisioning. ### Mappez la portée et la topologie Les objets Provisioning ont des portées différentes. La portée d’un service détermine où vous pouvez le partager : Un schéma montrant un locataire de plateforme qui contient un compte connecté, qui possède une connexion au fournisseur à l’échelle du compte, une ressource de type plan à l’échelle du compte, et deux projets qui possèdent chacun une ressource à l’échelle du projet. (See full diagram at https://docs.stripe.com/provisioning) ```text [Locataire de plateforme ou espace de travail] --> [Compte connecté] [Compte connecté] --> [Connexion au fournisseur : passerelle de modèle (à l’échelle du compte)] [Compte connecté] --> [Ressource de type plan : plan de base de données (à l’échelle du compte)] [Compte connecté] --> [Projet : production de l’application A] [Compte connecté] --> [Projet : production de l’application B] [Projet : production de l’application A] --> [Ressource : base de données de l’application A (à l’échelle du projet)] [Projet : production de l’application B] --> [Ressource : base de données de l’application B (à l’échelle du projet)] ``` - Les projets Provisioning diffèrent des environnements CLI. Un environnement CLI stocke la configuration et la sortie de la CLI locale, tandis qu’un projet définit un regroupement Provisioning et une limite d’identifiants. - Créez des connexions au fournisseur à l’échelle du compte. Une seule connexion prend en charge chaque projet du compte connecté. Ne créez donc pas une connexion distincte pour chaque application. - Utilisez la portée `scope` renvoyée pour chaque service. Ne déduisez pas la portée à partir du fournisseur, du nom du service ou de l’utilisation prévue. - Vous pouvez associer une ressource à l’échelle du compte, y compris un plan, à un projet. Cette association ne modifie pas la portée de la ressource. - Vous ne pouvez utiliser un seul plan pour des ressources dépendantes sur plusieurs projets et applications que si la réponse du catalogue l’autorise via la portée et le contrat de dépendance renvoyés. Confirmez ces deux valeurs dans la réponse. ### Inscrivez-vous à la version bêta privée Avant de créer une intégration de production, confirmez les éléments suivants avec le propriétaire de la version bêta : - La plateforme et les comptes connectés de test sont inscrits dans la cohorte. - La version d’API en version bêta est activée pour la cohorte, pour l’API Provisioning et l’API Accounts. - La configuration du compte connecté approuvée et le parcours d’onboarding sont définis. - Les fournisseurs et les partitions de catalogue éligibles sont définis. - Le provisionnement de test payant et les sources de paiement appartenant à la plateforme sont activés, le cas échéant. L’API Provisioning n’inscrit pas automatiquement une plateforme et ne crée pas de relation de compte connecté. L’inscription à la version bêta privée est une étape d’ajout à la liste d’autorisation assistée par Stripe. Utilisez la configuration de l’API Accounts et le flux d’onboarding hébergé que votre cohorte approuve explicitement. ### Effectuez la liste des vérifications préalables Exécutez ces étapes dans l’ordre avant votre première écriture Provisioning. Si vous ne pouvez pas effectuer une étape, arrêtez-vous et résolvez le problème avec le propriétaire de votre version bêta plutôt que de le contourner. 1. Confirmez que le compte de plateforme, les comptes connectés cibles et la cohorte de catalogue et de paiement sont sur la liste d’autorisation. 2. Enregistrez la version `Stripe-Version` activée, et enregistrez séparément la configuration de l’API Accounts que votre cohorte exige. Il s’agit de deux contrats indépendants, et l’activation de l’un n’entraîne pas celle de l’autre. 3. Confirmez quels environnements prennent en charge les lectures de catalogue, le provisionnement gratuit et le provisionnement payant pour votre cohorte. 4. Vérifiez l’éligibilité dans le contexte du compte connecté. 5. Provisionnez une ressource gratuite de bout en bout avant de configurer un service payant. L’éligibilité, la disponibilité du catalogue et l’onboarding du compte connecté constituent trois étapes distinctes. Une lecture réussie du catalogue prouve uniquement que le catalogue est lisible. Elle ne prouve pas que le compte connecté a terminé son onboarding, que le compte est éligible ou qu’un chemin d’écriture fonctionne. ## Créez votre back-end Avant d’effectuer votre première requête API, implémentez les deux composants suivants. Acheminez chaque requête des étapes numérotées via ces deux composants. ### Créez un adaptateur de back-end Chaque appel passe par le back-end de la plateforme. L’adaptateur doit effectuer les actions suivantes : - Utilisez un délai d’attente réseau de 45 secondes ou moins. - Suivez les valeurs `next_page_url` et `previous_page_url` renvoyées. Ne créez jamais de valeur `page` opaque. - Lisez les résultats de liste à partir de `data`, et non à partir d’alias obsolètes tels que `providers`, `services` ou `resources`. - Enregistrez l’écriture prévue avant de l’envoyer. - Stockez les identifiants de requête non secrets, les identifiants d’objet, les transitions d’état, les noms d’endpoint ou d’action, les statuts HTTP et les codes d’erreur. - Considérez `request_log_url` comme des données de diagnostic supplémentaires, et non comme un chemin de récupération fiable. - Expurgez les informations d’identification, les configurations d’accès, les secrets de rappel, les informations de paiement et les URL pré-authentifiées des logs, des réponses du navigateur, des analyses, des tickets du service de support et des prompts de modèle. La version bêta ne fournit pas d’idempotence contrôlée par l’appelant ni de corrélation de requête pour les opérations de modification d’état. Concevez votre adaptateur pour qu’il récupère lorsqu’il ne reçoit pas le résultat d’une requête d’écriture. Avant d’envoyer chaque requête d’écriture, enregistrez la modification prévue afin de pouvoir effectuer un rapprochement et récupérer en cas de résultat inconnu. ### Modélisez les états de la plateforme Assurez-vous de stocker au minimum : ``` Tenant tenant_id connected_account_id Application environment application_id environment project_id Provisioning workflow workflow_id tenant_id connected_account_id action provider_id service_ref provider_connection_request_id provider_connection_id resource_id status created_at updated_at Approval provider_id service_ref configuration_summary pricing_text terms_url_or_text usage_limit approved_by approved_at ``` Créez des projets distincts pour la version bêta et la production lorsque vous devez isoler des ressources ou des cycles de vie de déploiement. Utilisez les noms de projet uniquement comme libellés d’affichage, et non comme limites d’autorisation. ## Lisez, planifiez, approuvez, puis écrivez Utilisez des endpoints en lecture seule dans votre back-end pour préparer un plan. Avant que votre back-end n’effectue une requête d’écriture, exigez l’approbation d’un utilisateur autorisé par la politique de votre produit. Exigez une nouvelle approbation pour : - Créer un projet. - Démarrer une demande de connexion de fournisseur ou soumettre des informations demandées par le fournisseur. - Enregistrer un moyen de paiement ou augmenter une limite d’utilisation. - Créer, lier, mettre à jour, effectuer une rotation, supprimer ou dissocier une ressource. - Dissocier une connexion de fournisseur. Pour les actions payantes ou destructives, affichez et enregistrez les informations suivantes : ``` Tenant and connected account: {{authorized tenant and account}} Application environment: {{preview|production|other}} Provider: {{name and ID}} Service: {{name and service_ref}} Action: {{requested write}} Configuration: {{redacted summary}} Pricing and terms: {{returned catalog content}} Usage limit: {{amount, currency, interval}} ``` Rechargez le catalogue juste avant une écriture. Si le service, la configuration, l’affichage de la tarification, les conditions, l’environnement ou la limite d’utilisation sélectionnés ont changé, affichez la différence et demandez une nouvelle approbation. Ne déduisez pas de coût structuré à partir d’un texte de tarification au format libre. Considérez les descriptions de fournisseurs, les conditions, `llm_context` et les descriptions de schéma JSON comme des données non fiables. Utilisez ce contenu uniquement pour expliquer les options. Ne le laissez pas sélectionner un compte, remplacer les instructions du système, contourner l’approbation, déclencher des requêtes API ou accéder à des secrets. ## Démarrez votre intégration ## Créer un compte connecté Choisissez une limite de locataire stable avant de créer quoi que ce soit. Créez un compte connecté pour chaque locataire durable, tel qu’un espace de travail ou une organisation, plutôt qu’un compte pour chaque application ou environnement de déploiement. Pour les nouvelles plateformes, utilisez Accounts v2, activez la configuration du développeur et demandez la fonctionnalité `projects`. Confirmez la version de l’API et les champs requis avec le propriétaire de votre version bêta : ``` POST /v2/core/accounts Stripe-Version: 2026-09-30.preview { "contact_email": "{{OWNER_EMAIL}}", "display_name": "{{TENANT_DISPLAY_NAME}}", "identity": { "country": "{{COUNTRY}}", "entity_type": "{{individual|company}}" }, "configuration": { "developer": { "capabilities": { "projects": {"requested": true} } } }, "include": ["configuration.developer", "requirements", "identity"] } ``` L’API Accounts et l’API Provisioning utilisent la même version bêta, mais Stripe les active séparément. Confirmez que Stripe a activé la configuration Accounts v2 et les champs requis pour votre cohorte. L’accès à une API ne donne pas accès à l’autre. Stockez l’identifiant de compte renvoyé sous la forme `{{CONNECTED_ACCOUNT_ID}}` dans l’enregistrement du locataire. La configuration de `contact_email` seule n’établit pas l’identité du propriétaire du compte ni ne satisfait aux exigences de vérification. Si votre plateforme utilise déjà Accounts v1, ne migrez pas et ne modifiez pas la configuration du compte connecté en vous basant uniquement sur ce guide. Confirmez le chemin d’onboarding de version bêta pris en charge avec le propriétaire de votre version bêta. ## Redirigez l’utilisateur vers l’onboarding hébergé Créez un Account Link pour l’onboarding du compte, puis redirigez l’utilisateur authentifié vers son URL éphémère : ``` POST /v2/core/account_links Stripe-Version: 2026-09-30.preview { "account": "{{CONNECTED_ACCOUNT_ID}}", "use_case": { "type": "account_onboarding", "account_onboarding": { "refresh_url": "{{PLATFORM_REFRESH_URL}}", "return_url": "{{PLATFORM_RETURN_URL}}", "collection_options": {"fields": "currently_due"} } } } ``` S’il expire, créez un autre lien. Pour les corrections ultérieures, utilisez `account_update` : ``` POST /v2/core/account_links Stripe-Version: 2026-09-30.preview { "account": "{{CONNECTED_ACCOUNT_ID}}", "use_case": { "type": "account_update", "account_update": { "refresh_url": "{{PLATFORM_REFRESH_URL}}", "return_url": "{{PLATFORM_RETURN_URL}}" } } } ``` Authentifiez les deux gestionnaires `refresh_url` et `return_url`. Le gestionnaire d’actualisation crée un nouvel Account Link avec la même intention. Après le retour de l’utilisateur, récupérez le compte : ``` GET /v2/core/accounts/{{CONNECTED_ACCOUNT_ID}}?include=configuration.developer&include=requirements Stripe-Version: 2026-09-30.preview ``` Vérifiez la fonctionnalité Projects de la DeveloperConfig et les exigences en attente. Ne considérez pas la seule redirection de l’Account Link comme une preuve de réussite. Ne démarrez le provisionnement qu’une fois la fonctionnalité `projects` active et l’onboarding requis terminé. Si les événements d’état de fonctionnalité sont activés pour votre cohorte, considérez un événement comme une incitation à récupérer le compte plutôt que comme la source de vérité. ## Vérifiez l’éligibilité du compte connecté ``` GET /v2/provisioning/eligibility ``` Interprétez l’éligibilité séparément de la disponibilité du catalogue : | Résultat | Action de la plateforme | | --- | --- | | `is_eligible=false` | Arrêtez. Vérifiez la relation entre le locataire et le compte, ainsi que l’inscription à la cohorte actuelle, puis suivez la rectification d’onboarding approuvée. | | `is_eligible=true` avec un tableau `requirements` non vide | Ne considérez pas le compte comme entièrement prêt. Acheminez les tâches requises en matière d’identité ou de conditions via le chemin d’onboarding approuvé, puis récupérez à nouveau l’état actuel. | | `is_eligible=true` sans exigences | Passez aux vérifications du catalogue, de la facturation, de la connexion et de l’approbation. | L’éligibilité du compte, les exigences d’onboarding du compte, la disponibilité du service et votre propre politique produit constituent quatre étapes distinctes. Une réponse d’éligibilité `true` ne rend pas utilisable un service non disponible et n’autorise pas une écriture payante. ## Découvrez un service provisionnable Lisez le catalogue du compte connecté lors de la planification et à nouveau juste avant le provisionnement : ``` GET /v2/provisioning/catalog/providers?limit=100 GET /v2/provisioning/catalog/services?provider_name={{PROVIDER_NAME}}&limit=100 ``` Une clé restreinte nécessite `rak_provisioning_project_read` pour les deux appels ci-dessus. #### Sélectionnez un service Pour chaque fournisseur candidat, listez les services en utilisant le paramètre `provider_name` exact de ce fournisseur, ainsi que la même sélection de catalogue et de développement. Si la réponse des services contient un tableau `data` vide, ce fournisseur ne peut pas être provisionné pour cette offre. Ne créez pas de requête de connexion de fournisseur à cet effet. L’API ne possède aucun paramètre de recherche en texte intégral ou par catégorie générique. N’en créez pas. Parcourez toutes les pages, créez un index local à partir de la valeur `data` renvoyée, appliquez une règle de produit déterministe, puis présentez uniquement les services renvoyés admissibles pour une explication ou un classement assistés par un modèle. | Champ de catalogue | Utilisation | | --- | --- | | `id` du fournisseur | Envoyez dans les champs de requête nommés `provider`. | | `name` du fournisseur | Affichez-le aux utilisateurs et envoyez-le uniquement aux endpoints qui acceptent explicitement `provider_name`. | | Fournisseur `configuration_schema` | Validez la configuration de connexion avant de créer une requête de connexion de Fournisseur. | | Service `service_id` | Envoyez cette valeur en tant que `service_ref` lorsque vous créez, associez ou mettez à jour une Ressource. | | Paramètre `configuration_schema` du Service | Utilisez ce schéma pour valider la configuration lorsque vous créez ou mettez à jour une Ressource. | | `availability` | Excluez les services indisponibles. | | `pricing.paid_pricing` | Affichez la tarification payante à partir de ce champ. N’utilisez pas le champ `pricing.paid` obsolète. | | `kind` et composant `parent_services` | Identifiez les offres, les éléments déployables, les composants et les prérequis. | | `scope` | Décidez de l’emplacement et de l’association du Projet. | | `constraints`, `allowed_updates` | Empêchez les créations et modifications non prises en charge. | | Paramètre `capabilities` du Fournisseur | Activez le comportement facultatif uniquement lorsque le Fournisseur l’indique. | Utilisez la même partition de catalogue pour les requêtes de catalogue et toutes les requêtes de Projet ou de Ressource qui la prennent en charge. Définissez `development=true` uniquement lorsque l’utilisateur sélectionne des entrées exclusivement dédiées au développement. #### Dépendances de l’offre avant la connexion ou le provisionnement Un Fournisseur peut exposer un service d’offre et des services déployables dépendants, ou des services de composants avec `parent_services`. Traitez les offres et les parents requis comme des Ressources distinctes dans l’offre : ``` Plan prerequisite → user approves prerequisite and dependent action → create prerequisite Resource → wait for complete → refresh catalog and approval-sensitive fields → create dependent Resource ``` Si les informations de dépendance ne sont pas claires, arrêtez-vous au lieu de tester différents Fournisseurs ou services. Ne traitez pas les codes d’état HTTP bruts d’un Fournisseur comme faisant partie de votre contrat client. Utilisez plutôt les états, les codes d’erreur et les messages d’erreur fiables de l’API Provisioning. ## Configurez la facturation pour les Services payants Récupérez d’abord le profil effectif du compte connecté : ``` GET /v2/provisioning/payment_profile?livemode=false ``` Définissez `livemode` comme paramètre de requête à chaque lecture. Il n’hérite pas du mode dans lequel le moyen de paiement a été créé, et l’endpoint ignore l’en-tête `Stripe-Livemode`. Envoyez `livemode=false` pour lire un profil en mode test : un profil en mode test existant renvoie `404` lorsque vous omettez le paramètre de requête ou le définissez uniquement à partir de l’en-tête, ce qui donne l’impression qu’une écriture réussie a échoué silencieusement. Une erreur `404 not_found` avec « No payment method linked yet » constitue l’état de départ normal pour un compte, et non une erreur. Traitez-la comme « aucun moyen de paiement pour le moment » et continuez avec l’un des parcours de paiement. Utilisez l’un des parcours de paiement explicitement activés pour votre cohorte : | Chemin | Requête | | --- | --- | | Encaissement hébergé par le compte connecté | Créez une requête de moyen de paiement avec `usage_limits` ; omettez `payment_method_owner` et tous les champs `source_*`. Envoyez l’utilisateur autorisé vers l’URL `checkout_session_url` temporaire renvoyée, puis interrogez le profil de paiement avec le paramètre de requête `livemode` correspondant. | | Source appartenant à la plateforme | Utilisez ce flux uniquement lorsque Stripe l’active explicitement pour votre cohorte d’évaluation. Avant d’envoyer la requête d’écriture, vérifiez que le Customer et le PaymentMethod appartiennent au même compte source. Incluez `payment_method_owner: "platform"`, `source_account`, `source_customer`, `source_payment_method` et `usage_limits` dans la requête. | Pour un encaissement hébergé par un compte connecté, envoyez uniquement `usage_limits` : ``` POST /v2/provisioning/payment_method_requests { "livemode": false, "usage_limits": { "max_amount": "5000", "currency": "usd", "recurring_interval": "month" } } ``` La réponse renvoie `checkout_session_url` et `status`. Pour le parcours de la source appartenant à la plateforme, envoyez les champs du propriétaire et de la source sur le même endpoint : ``` POST /v2/provisioning/payment_method_requests { "livemode": false, "payment_method_owner": "platform", "source_account": "{{PLATFORM_ACCOUNT_ID}}", "source_customer": "{{PLATFORM_CUSTOMER_ID}}", "source_payment_method": "{{PAYMENT_METHOD_ID}}", "usage_limits": { "max_amount": "5000", "currency": "usd", "recurring_interval": "month" } } ``` `max_amount` utilise la plus petite unité de devise et vous l’envoyez sous forme de chaîne. L’API représente les champs int64 sous forme de chaînes. Un nombre sans guillemets échoue donc avec `invalid_fields`. Appliquez la même convention à tous les champs contenant de grands nombres. Les intervalles valides sont `week`, `month` et `year`. Utilisez `POST /v2/provisioning/payment_profile/update_limit`, qui prend également le montant sous forme de chaîne, pour les limites à l’échelle du compte ou les remplacements spécifiques au Fournisseur. Traitez le moyen de paiement, la partition du catalogue et l’environnement de l’application comme des paramètres indépendants. L’accès au catalogue `dev` ou `testing` ne garantit pas que le Fournisseur ne créera pas d’infrastructure ou n’autorisera pas de paiement. Un déploiement d’évaluation ne modifie pas non plus le moyen de paiement. Traitez la validation payante comme potentiellement facturable, sauf si votre cohorte inscrite et le Fournisseur confirment explicitement le contraire. La finalisation de la configuration du paiement n’approuve pas une connexion de Fournisseur, une Ressource payante, un changement de niveau ou une augmentation des dépenses. Exigez l’approbation distincte de l’utilisateur pour chaque action. Considérez une limite d’utilisation de Provisioning comme une limite d’autorisation, et non comme une politique de cycle de vie. Ne partez pas du principe qu’atteindre la limite supprime une Ressource, préserve la disponibilité du service ou déclenche la même notification chez tous les Fournisseurs. Consultez les contrats du service et du Fournisseur, maintenez la limite visible pour l’utilisateur et proposez un moyen approuvé par l’utilisateur pour la modifier. #### Mappez les clients existants de la plateforme aux locataires Provisioning Si vos utilisateurs possèdent déjà des objets `Customer` et des moyens de paiement sauvegardés sur votre plateforme, vous n’avez pas besoin de les migrer ou de les remplacer. Un utilisateur peut être à la fois un Customer de la plateforme et un compte connecté : ``` Platform user ├── Platform Customer: stores the payment method for your platform's own charges └── Connected account: owns Provisioning Projects, Provider connections, Resources, usage, and the payment profile ``` - C’est le profil de paiement de Provisioning, et non le Customer de votre plateforme, qui autorise les services du Fournisseur. - Le parcours de la source appartenant à la plateforme vous permet de débiter un moyen de paiement que vous avez déjà sauvegardé, mais il n’est disponible que lorsqu’il est explicitement activé pour votre cohorte. - L’API Provisioning ne fait pas de votre plateforme le commerçant officiel pour les services du Fournisseur, et elle ne met pas en œuvre de transferts Connect ni de modèle de marketplace. Concevez-les séparément avec Connect si vous en avez besoin. ## Créer un Projet Après l’approbation, créez un Projet pour l’environnement de l’application : ``` POST /v2/provisioning/projects { "name": "{{APPLICATION_NAME}} {{ENVIRONMENT}}" } ``` Sauvegardez l’ID du Projet avec l’enregistrement de l’environnement d’application de la plateforme. Utilisez des Projets d’évaluation et de production distincts lorsque leurs Ressources ou leurs identifiants doivent rester isolés. ## Connecter un Fournisseur Listez les connexions de Fournisseur avant de créer une nouvelle requête : ``` GET /v2/provisioning/provider_connections?limit=100 ``` Si plusieurs connexions actives rendent le résultat ambigu, affichez les détails fiables renvoyés pour le compte du Fournisseur lorsqu’ils sont disponibles, puis arrêtez-vous pour les examiner. S’il n’existe aucune connexion active utilisable, validez le paramètre `configuration_schema` du Fournisseur, puis créez une requête de connexion de Fournisseur après approbation : ``` POST /v2/provisioning/provider_connection_requests { "provider": "{{PROVIDER_ID}}", "configuration": {}, "project": "{{PROJECT_ID}}" } ``` Utilisez `{}` uniquement lorsque le schéma du Fournisseur ne comporte aucun champ obligatoire. Stockez l’ID de requête de connexion de Fournisseur renvoyé avant de rediriger l’utilisateur ou de collecter des informations supplémentaires. Avant de provisionner une Ressource, confirmez que le Fournisseur dispose d’exactement une connexion active. Les requêtes de création et d’association de Ressource identifient le Fournisseur, et non une connexion de Fournisseur spécifique. N’affichez pas de sélecteur de connexion, car l’API d’écriture ne peut pas utiliser la connexion sélectionnée. | État de la demande de connexion au Fournisseur | Action de la plateforme | | --- | --- | | `requested` | Récupérez la demande de connexion au Fournisseur jusqu’à ce qu’elle progresse ou qu’un délai défini expire. | | `pending_auth` | Présentez `redirect_url` uniquement à l’utilisateur authentifié, conservez l’état et interrogez depuis le back-end. | | `needs_information` | Générez les formes `needs_information_schema` prises en charge, collectez uniquement les valeurs fournies par l’utilisateur, puis soumettez `{ "information": {{VALIDATED_INFORMATION}} }`. N’incluez `confirmation_secret` que si le flux du Fournisseur le renvoie ; traitez-le comme un secret. | | `complete` | Lisez la connexion résultante à partir de `provider_connection` et vérifiez qu’il existe une connexion active non ambiguë avant de continuer. La demande reste `complete` même après la dissociation de cette connexion, auquel cas `provider_connection` est absent. | | `error` | Arrêtez-vous et n’affichez qu’une erreur sécurisée. | Gérez le chemin de connexion immédiate directement dans la réponse de création. Certains Fournisseurs terminent lors de la demande de création et renvoient `complete` avec une `provider_connection` active et sans `redirect_url`. Par conséquent, n’attendez pas de redirection et ne continuez pas à interroger une demande déjà terminée. Un Fournisseur peut exiger des informations KYC vérifiées, telles qu’une adresse e-mail vérifiée, même si votre produit considère ces informations comme facultatives. Consultez le `configuration_schema` du Fournisseur et tout `needs_information_schema` renvoyé pour connaître les champs obligatoires. Collectez et soumettez toutes les informations obligatoires, y compris l’e-mail si spécifié. Si l’authentification du Fournisseur nécessite une redirection du navigateur, suspendez le flux de travail et stockez l’ID de la demande de connexion au Fournisseur. Après l’étape du navigateur, reprenez le flux de travail à l’aide de cet ID. Ne contournez et ne simulez pas l’authentification. Le flux actuel n’accepte pas d’URL de rappel de plateforme. Stripe gère le rappel du Fournisseur et l’échange de tokens. Ne fournissez les champs PKCE facultatifs que lorsque Stripe les active explicitement et les exige pour votre flux d’aperçu. ## Créez ou liez une Ressource Avant d’envoyer la demande d’écriture, vérifiez les points suivants : - L’onboarding obligatoire est terminé. - Le Service est toujours disponible dans le catalogue sélectionné. - Toutes les Ressources parentes ou offres préalables sont terminées. - Le Fournisseur possède exactement une connexion active. - La configuration de la Ressource satisfait au `configuration_schema` du service actuel. - Un profil de paiement existe pour chaque service payant. - Le champ `scope`, le champ `constraints`, les mises à jour autorisées et l’association de Projet de la Ressource sont valides. - L’utilisateur a approuvé l’offre actuelle. ``` POST /v2/provisioning/resources { "provider": "{{PROVIDER_ID}}", "service_ref": "{{SERVICE_ID}}", "project": "{{PROJECT_ID}}", "livemode": {{true|false}}, "name": "{{RESOURCE_NAME}}", "configuration": {{VALIDATED_SERVICE_CONFIGURATION}} } ``` Définissez toujours `livemode` explicitement dans les demandes de création et de liaison. Si vous l’omettez, Stripe utilise `true` par défaut, ce qui peut créer une infrastructure de Fournisseur en mode production et entraîner des frais réels. Définissez `livemode` sur `false` pour le provisionnement de test. Le champ `environment` de la Ressource n’accepte que `dev` ou `prod`. Mappez l’environnement de votre application, tel que l’aperçu ou la production, à l’une de ces valeurs. Les champs `environment` et `livemode` sont indépendants : `environment=dev` ne signifie pas que la Ressource s’exécute dans un environnement de test. Pour un service à l’échelle du projet, incluez `project`. Pour un service à l’échelle du compte, omettez `project` sauf si vous devez associer la Ressource à un Projet. L’inclusion de `project` crée l’association mais ne modifie pas la portée de la Ressource du Fournisseur. Adoptez une infrastructure existante uniquement lorsque le Fournisseur annonce `resources:link` et que l’utilisateur l’a approuvée : ``` POST /v2/provisioning/resources/link { "provider": "{{PROVIDER_ID}}", "service_ref": "{{SERVICE_ID}}", "project": "{{PROJECT_ID}}", "environment": "{{dev|prod}}", "catalog": "{{CATALOG}}", "livemode": {{true|false}} } ``` ## Reprenez le travail asynchrone en toute sécurité Une Ressource n’est utilisable que lorsque `status=complete`. | État de la Ressource | Action de la plateforme | | --- | --- | | `pending` | Interrogez `GET /v2/provisioning/resources/{id}` avec une temporisation exponentielle et une variation limitées. | | `needs_information` | Collectez les saisies utilisateur valides pour le schéma, soumettez `{ "submitted_information": {{VALIDATED_INFORMATION}} }`, puis continuez l’interrogation. | | `complete` | Enregistrez la Ressource dans l’environnement de l’application et poursuivez le flux de travail. | | `errored` | Arrêtez-vous et n’exposez `error_message` que si cela est sécurisé. | | `removed` | Traitez comme terminal. | Pendant l’aperçu, interrogez après 1, 2, 4, 8, 16 et 30 secondes, puis toutes les 30 secondes pendant un maximum de 15 minutes. Ajoutez un petit décalage aléatoire, appelé jitter, à chaque attente afin que les flux de travail qui ont démarré en même temps n’envoient pas leurs interrogations aux mêmes moments. L’API ne définit pas d’intervalles d’interrogation, de webhooks ou de limites de requêtes finales. Si l’interrogation expire, conservez les ID d’objet et définissez l’état sur `requires_review`. Ne renvoyez pas automatiquement la demande d’écriture. ## Récupérez les identifiants de la Resource Une fois que la Resource passe à `status=complete`, récupérez sa configuration d’accès actuelle émise par le Provider depuis votre back-end : ``` POST /v2/provisioning/resources/{id}/reveal_access_configuration ``` N’envoyez pas de corps de requête. Pour une clé limitée, accordez l’autorisation `provisioning_resource_reveal_access_configuration`. L’endpoint renvoie la dernière configuration d’accès disponible : ```json { "object": "v2.provisioning.resource_access_configuration", "created": "2026-09-21T14:00:00Z", "resource": "fres_123", "livemode": false, "configuration": { "DATABASE_URL": "postgres://USER:PASSWORD@db.example.test/DATABASE" }, "expires_at": "2026-09-22T14:00:00Z" } ``` Traitez la réponse complète comme un secret. Copiez uniquement les valeurs de configuration nécessaires dans le magasin de secrets de votre système de déploiement. Ne renvoyez pas la réponse à un navigateur et n’incluez pas de noms ou de valeurs de configuration dans les logs, les analyses, les tickets du service de support ou les invites de modèle. Le champ facultatif `expires_at` est absent lorsque le Provider ne définit pas de délai d’expiration. La récupération d’une configuration d’accès n’effectue pas de rotation des identifiants et ne nécessite pas de clé d’idempotence. Pour obtenir des identifiants de remplacement, effectuez d’abord une rotation de la Resource. Si la rotation renvoie `complete`, récupérez la nouvelle configuration d’accès. Envoyez la même valeur `Stripe-Context` vérifiée que celle utilisée pour créer ou récupérer la Resource. Ne récupérez les identifiants que pour une Resource à laquelle votre utilisateur authentifié est autorisé à accéder. ## Gérez les ressources ### Mettre à jour Avant une mise à jour, actualisez le service et vérifiez `allowed_updates`, `constraints`, le catalogue actuel et l’approbation. ``` POST /v2/provisioning/resources/{id} { "configuration": {{VALIDATED_SERVICE_CONFIGURATION}}, "service_ref": "{{OPTIONAL_NEW_SERVICE_ID}}", "catalog": "{{CATALOG}}" } ``` Omettez `service_ref` pour une mise à jour de configuration uniquement. La réponse est le résultat d’une opération : `pending`, `complete` ou `errored`. Ne vous fiez pas à `resource_id` obsolète dans la réponse. ### Renouvelez les identifiants `POST /v2/provisioning/resources/{id}/rotate_credentials` renvoie `pending`, `complete` ou `errored`. - `complete` : enregistrez la rotation sur la Ressource et invalidez toutes les informations d’identification que le Fournisseur a émises avant la rotation. - `errored` : arrêtez le flux de travail et laissez la Ressource inchangée. - `pending` : ne renvoyez pas la demande de rotation. Définissez l’état sur `requires_review`. L’API d’aperçu ne fournit pas de moyen durable de récupérer l’opération de rotation, et la lecture de la Ressource ultérieurement ne confirme pas que la rotation est terminée. ### Suppression, dissociation et dissociation de la connexion Exigez une approbation distincte pour chaque action. | Action | Endpoint | Effet | | --- | --- | --- | | Déprovisionnez l’infrastructure | `POST /v2/provisioning/resources/{id}/remove` | Demande la suppression de l’infrastructure du Fournisseur. | | Arrêtez de gérer une Ressource | `POST /v2/provisioning/resources/{id}/unlink` | Supprime l’association Provisioning ; elle ne supprime pas l’infrastructure du Fournisseur. | | Oubliez la connexion au Fournisseur | `POST /v2/provisioning/provider_connections/{id}/unlink` | Supprime la connexion sauvegardée de Stripe ; cela ne supprime pas les Ressources et ne garantit pas la révocation des tokens du côté du Fournisseur. | Après avoir supprimé ou dissocié une Ressource, ne supposez pas que le Fournisseur a invalidé les informations d’identification précédemment émises. Confirmez leur état auprès du Fournisseur. ## Gérer les erreurs Utilisez le `error.code` de l’API Provisioning, l’état renvoyé et les messages sûrs pour gérer les erreurs. Ne créez pas de branches à partir des statuts HTTP bruts supposés du fournisseur. | Code d’erreur | Action de la plateforme | | --- | --- | | `payment_method_required` | Terminez la configuration du paiement, obtenez l’approbation, puis réessayez délibérément. | | `payment_method_and_customer_required` | Pour un flux platform-source activé, fournissez le client et le PaymentMethod sources correspondants. | | `payment_method_owner_required` | Pour un flux platform-source activé, définissez `payment_method_owner=platform`. | | `unsupported_payment_method_owner` | Arrêtez ; utilisez uniquement un mode propriétaire actuellement activé. | | `connect_relationship_required` | Vérifiez la relation entre la plateforme et le compte connecté, ainsi que la valeur `Stripe-Context`. | | `provider_reauth_required` | Créez une nouvelle requête de connexion au fournisseur et demandez à l’utilisateur de se reconnecter. | | `invalid_resource_configuration` | Actualisez le schéma et collectez les saisies utilisateur corrigées. | | `resource_count_constraint_exceeded` | Expliquez la contrainte et proposez une mise à jour, une association ou une ressource existante autorisée. | | `resource_not_complete` | Récupérez la Resource et suivez son statut actuel. N’interrogez que lorsqu’elle est `pending`, soumettez les informations obligatoires lorsqu’elle est `needs_information` et arrêtez si elle est `errored` ou `removed`. Récupérez la configuration d’accès une fois que la Resource passe à `complete`. | | `resource_access_configuration_unavailable` | Arrêtez. Réassociez ou effectuez une rotation de la Resource, ou suivez les instructions du Provider dans les détails de son statut. | | `resource_access_configuration_expired` | Effectuez une rotation des identifiants de la Resource. Si la rotation renvoie `complete`, récupérez les identifiants de remplacement. Si elle renvoie `pending`, définissez le statut du flux de travail sur `requires_review`. | | Autorisation manquante HTTP `403` | Utilisez une clé disposant de l’autorisation `provisioning_resource_reveal_access_configuration`. | | Autre HTTP `403` | Vérifiez l’inscription à la version preview privée, le compte `Stripe-Context` et la portée du Project de la Resource. N’ajoutez pas d’autorisations à moins que l’erreur n’identifie une autorisation manquante. | | `provider_failure` | Affichez un message sûr. Identifiez un prérequis renvoyé lorsque cela est possible ; ne réessayez qu’après approbation et uniquement si cela est sans risque. | | `api_error` ou code inconnu | Arrêtez, enregistrez des diagnostics sûrs, récupérez les objets connus, marquez `requires_review` et ne relancez pas l’écriture automatiquement. | | `not_found` | Vérifiez l’ID de l’objet et `Stripe-Context` ; ne sondez pas un autre compte. | | `rate_limited` ou HTTP `429` | Appliquez un recul exponentiel avec gigue, en respectant un `Retry-After` renvoyé s’il est présent. Ne réduisez pas les intervalles d’interrogation, ne répartissez pas les tentatives sur plusieurs ressources et ne contournez pas la limite en ajoutant des appelants parallèles. | En cas d’`api_error`, de logs de requête indisponibles ou de résultat d’écriture inconnu, stockez l’endpoint, l’action, l’ID de la requête non secret, les ID des objets, le statut HTTP, le code et le message d’erreur, ainsi que l’état actuel du flux de travail. Si `request_log_url` est manquant, indisponible ou inutile, enregistrez ce résultat comme preuve. Ne demandez pas à l’utilisateur de réessayer l’URL de manière répétée. Après l’expiration d’une requête d’écriture ou si elle renvoie un résultat inconnu, définissez le statut du flux de travail sur `requires_review`. Dans le même contexte de compte connecté, récupérez les requêtes de connexion au fournisseur et les ressources connues. Rapprochez l’état observé avec un utilisateur autorisé et obtenez son approbation avant d’envoyer une autre requête d’écriture. Ne relancez pas la requête d’origine automatiquement. ## Tester votre intégration Avant le déploiement, testez avec les comptes et les services auxquels votre cohorte s’inscrit explicitement : 1. Vérifiez l’autorisation de l’utilisateur vers le locataire puis vers le compte connecté. Confirmez que les ID de compte non approuvés ne peuvent pas changer de contexte. 2. Terminez l’onboarding du compte connecté et confirmez que le compte est prêt avec des exigences vides et non vides. 3. Testez la pagination, la cohérence des partitions de catalogue et de développement, les listes de services vides, la disponibilité, la tarification, la portée, les contraintes et la validation du schéma. 4. Testez les dépendances déployables et de plan ainsi que les dépendances composant-parent sans créer de branches à partir des réponses `422` brutes du fournisseur. 5. Testez la connexion immédiate au fournisseur, la redirection du navigateur et `needs_information`. Vérifiez la récupération du flux de travail après la perte du navigateur ou de la session. 6. Testez une ressource gratuite en passant par les états `pending`, `needs_information` et d’achèvement. 7. Testez le provisionnement payant uniquement lorsque la cohorte le confirme, avec une limite basse explicite et une nouvelle approbation. 8. Testez séparément la mise à jour, la réauthentification et la suppression de ressource par rapport à la dissociation. 9. Testez la récupération des identifiants pour les Resources autorisées. Vérifiez que les Resources incomplètes, indisponibles, expirées, inter-comptes et inter-Projects ne divulguent pas d’identifiants. 10. Testez la rotation synchrone des identifiants, vérifiez que la récupération ne renvoie les identifiants de remplacement validés qu’une fois la rotation terminée, et exigez un examen pour toute rotation en attente. 11. Testez `provider_failure`, `api_error`, l’expiration du délai d’interrogation, les écritures inconnues et les liens de logs de requête indisponibles. ## Limites de la version bêta - Les configurations d’accès sont récupérées une Resource à la fois. La version preview ne permet pas de récupérer des identifiants en masse. - Il n’y a pas de support documenté pour les webhooks Provisioning, utilisez donc une interrogation limitée. - Il n’y a pas d’idempotence de l’appelant ni de contrat de corrélation documentés pour les écritures. - Il n’y a pas d’intervalle d’interrogation du client ni de politique finale de limite d’appels documentés. Certains fournisseurs imposent une limite d’appels stricte ; un appelant qui répartit les requêtes sur de nombreuses ressources ou de nombreux projets peut l’atteindre même avec un volume modéré par utilisateur, appliquez donc un recul de manière centralisée plutôt que par flux de travail. - Les échecs en amont du fournisseur ne constituent pas une interface client stable, utilisez donc les codes de l’API Provisioning et les messages sûrs. - La rotation des identifiants en attente n’a pas de flux de récupération d’opération durable. - Le provisionnement de test payant et les sources de paiement appartenant à la plateforme dépendent de la cohorte. - Les champs et énumérations de la version bêta peuvent changer, évitez donc les champs obsolètes lorsqu’un remplacement actuel existe. ## See also - [Stripe Projects CLI](https://docs.stripe.com/projects.md) - [Fournisseurs disponibles](https://docs.stripe.com/projects.md#available-providers) - [Collecte d’informations auprès des fournisseurs pour Stripe Projects](https://docs.stripe.com/projects/provider-intake.md) - [Stripe Connect](https://docs.stripe.com/connect.md) - [Comptes v2](https://docs.stripe.com/connect/accounts-v2.md)