# Créer des sandbox récupérables Créez des environnements de test anonymes et récupérables pour permettre à vos utilisateurs de créer des intégrations Stripe. Cette page s’adresse aux plateformes de codage qui s’intègrent à Stripe pour configurer des fonctionnalités de paiement pour leurs utilisateurs. Si vous cherchez à créer une intégration Stripe directement et souhaitez tester les API Stripe, utilisez la [CLI Stripe](https://docs.stripe.com/cli/sandbox) pour obtenir un environnement de test. Les environnements de test réclamables sont des [environnements de test](https://docs.stripe.com/sandboxes.md) anonymes, qui ne sont initialement pas associés à un compte existant. Vous pouvez créer ces environnements de test par voie programmatique à l’aide de l’API Claimable Sandboxes et les préremplir de données afin d’aider vos utilisateurs à démarrer. Lorsque vos utilisateurs sont prêts à prendre possession d’un environnement de test et à mettre des projets en ligne, ils peuvent revendiquer l’environnement de test en se rendant à son URL d’onboarding. Sur cette page, ils peuvent créer un nouveau compte Stripe ou choisir un compte existant pour y transférer l’environnement de test. ## Créer une intégration d’environnement de test réclamable Dans ce guide, vous intégrerez l’API Claimable Sandboxes à une plateforme de codage fictive assistée par un agent, appelée Bizbot, et travailler avec les entités suivantes : - Bizbot : une plateforme de codage assisté par agent - `bizbot` : l’application Stripe qui utilise l’API Claimable Sandboxes - Jenny Rosen : un client final de Bizbot ## Créer une application Stripe Pour utiliser l’API Claimable Sandboxes afin de créer des environnements de test réclamables, vous devez d’abord créer une *application Stripe* (An app that you can build on top of Stripe to customize the functionality of the Stripe Dashboard UI, leverage Stripe user data, store data on Stripe, and more). Cela permet à votre plateforme d’agir dans l’environnement de test au nom du client final et d’accéder aux données de cet environnement de test. > Stripe Apps ne prend pas en charge la distribution publique sur les plateformes Connect. Les environnements de test récupérables ne sont donc pas disponibles sur les plateformes Connect. Pour démarrer, installez les [plugins de la CLI Stripe](https://docs.stripe.com/stripe-apps/create-app.md#install-stripe-apps-cli) requis et créez votre application : ```bash # Install the Stripe Apps CLI plugin (v1.19.0 or later) stripe plugin install apps # Install the Stripe generate CLI plugin (v0.11.5 or later) stripe plugin install generate # Create your app # This guide uses `bizbot` as an example. # Make sure you use a unique ID for your app. stripe generate app bizbot --shape claimable-sandboxes ``` Voici les paramètres par défaut du fichier [manifeste](https://docs.stripe.com/stripe-apps/reference/app-manifest.md) v2 de votre application d’environnement de test revendiquable. > Vous ne pouvez utiliser cette fonctionnalité qu’avec les manifestes v2. Si vous utilisez un manifeste v1, exécutez `stripe apps migrate` pour le migrer vers la v2. ```yaml shapes: - claimable-sandboxes declarations: distribution_type: public stripe_api_access: permissions: - permission: event_read purpose: Allows Bizbot access to read events. stripe_api_access_type: platform sandbox_install_compatible: true ``` Votre application peut demander les [autorisations](https://docs.stripe.com/stripe-apps/reference/permissions.md) supplémentaires dont elle a besoin pour fonctionner dans l’environnement de test. Ne demandez que les autorisations nécessaires aux fonctionnalités que votre application fournit. Par exemple, l’affichage d’une liste d’abonnements nécessite l’autorisation `subscription_read`. Après avoir configuré votre manifeste, [chargez votre application](https://docs.stripe.com/stripe-apps/upload-install-app.md) sur votre **compte en mode production** en exécutant cette commande depuis le répertoire racine de votre projet : ```bash stripe apps upload ``` Cette fonctionnalité facilite la transition des utilisateurs d’un développement en environnement de test vers une intégration en mode production. Votre application doit donc prendre en charge les installations en mode production. Une fois l’application chargée, Stripe crée automatiquement un [environnement de test d’application géré](https://docs.stripe.com/stripe-apps/enable-sandbox-support.md#managed-sandbox) portant le même nom que votre ID d’application. Le schéma suivant illustre la structure du compte. Ce diagramme montre un compte en mode production du compte Bizbot avec l'environnement de test de l'application gérée comme nœud secondaire. (See full diagram at https://docs.stripe.com/sandboxes/claimable-sandboxes) ```text [acct_bizbot_livemodeCompte de production] --> [acct_bizbot_sandboxApplication gérée de l’environnement de test] ``` Après le chargement de l’application, Stripe vérifie votre requête. En fonction de votre cas d’usage, nous pouvons vous accorder l’accès à la fonctionnalité ou vous contacter pour obtenir plus d’informations. Ne passez aux étapes suivantes qu’une fois que Stripe vous a accordé l’accès aux fonctionnalités. ## Configurer le canal de test externe pour l’application Avant de commencer le développement, configurez un [canal de test externe](https://docs.stripe.com/stripe-apps/test-app.md#set-up-test) pour votre application. Cela vous permet de tester l’API sans avoir à publier au préalable votre application. Avant de proposer votre intégration aux utilisateurs, vous devez [faire vérifier votre application et la publier](https://docs.stripe.com/sandboxes/claimable-sandboxes.md#review-and-publish). ## Appeler l'API Claimable Sandbox Utiliser la clé secrète du compte d’environnement de test de votre application gérée pour créer des environnements de test pouvant être réclamés. ```curl curl -X POST https://api.stripe.com/v2/core/claimable_sandboxes \ -H "Authorization: Bearer {{STRIPE_APP_SANDBOX_SECRET_KEY}}" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "app_channel": "testing", "enable_mcp_access": true, "onboarding_link_details": { "refresh_url": "https://example.com/refresh" }, "prefill": { "email": "jenny.rosen@example.com", "name": "Jenny Sandbox", "country": "US" } }' ``` Utilisez ces paramètres lorsque vous créez un environnement de test réclamable. | Paramètre | Description | | --- | --- | | `app_channel` | Une énumération contenant les valeurs `public` ou `testing`. En cours de développement, utilisez `testing`. Lorsque vous proposez cette fonctionnalité à vos utilisateurs, utilisez `public`. Pour en savoir plus, consultez la section [Soumettre l’application pour examen](https://docs.stripe.com/sandboxes/claimable-sandboxes.md#review-and-publish). | | `enable_mcp_access` | Définissez ce paramètre sur `true` invite Stripe à vous envoyer une clé API que vous pouvez utiliser pour communiquer avec le serveur [Stripe MCP](https://docs.stripe.com/mcp.md). Cela permet à un grand modèle linguistique (LLM) d’interagir en toute sécurité avec les comptes Stripe de vos utilisateurs. | | `onboarding_link_details` | Un hachage qui vous permet de spécifier la `refresh_url` vers laquelle votre client final est redirigé s’il accède à un lien d’onboarding expiré. Ce paramètre est requis lorsque vous créez un nouvel environnement de test réclamable. La `refresh_url` doit appeler une méthode sur votre serveur qui invoque l’API claimable sandboxes renew onboarding link pour renouveler la date d’expiration du lien d’onboarding. | | `prefill` | Un hachage qui vous permet de préremplir les valeurs que votre utilisateur fournit lors de la revendication de l’environnement de test. Par exemple, vous pouvez définir le `name` comme étant le nom du projet de votre utilisateur. | > Dans ce guide de développement, nous appelons l’API avec `app_channel: testing`. Avant de passer cette fonctionnalité en mode production, vous devez effectuer une mise à jour pour utiliser `app_channel: public`. Pour en savoir plus, consultez la section [Soumettre l’application pour examen](https://docs.stripe.com/sandboxes/claimable-sandboxes.md#review-and-publish). Voici à quoi ressemble la réponse de l’API une fois que vous avez créé un environnement de test réclamable : ```json { "id": "clmsbx_test_123", "object": "v2.core.claimable_sandbox", "app_channel": "testing", "claimed_at": null, "created": "2026-04-22T00:00:00.000Z", "expires_at": "2026-06-21T00:00:00.000Z", "onboarding_link_details": { "expires_at": "2026-04-29T00:00:00.000Z", "refresh_url": "https://example.com/refresh", "url": "https://dashboard.stripe.com/onboard_sandbox/{{SIGNATURE}}" }, "owner_details": null, "prefill": { "email": "jenny.rosen@example.com", "name": "Jenny Sandbox", "country": "US" }, "sandbox_details": { "account": "acct_jenny_sandbox", "api_keys": { "publishable": "pk_test_123......", "secret": "sk_test_123.....", "mcp": "ek_test_123....." } }, "status": "unclaimed" } ``` ### Disponibilité Lorsque vous appelez l’API, indiquez le pays où Stripe doit créer l’environnement de test en transmettant `prefill.country`. Cette API prend en charge la création d’environnements de test revendiquables dans ces régions : ### Pays concernés - AE - AR - AT - AU - BE - BG - BR - CA - CH - CI - CR - CY - CZ - DE - DK - DO - EE - ES - FI - FR - GB - GI - GR - GT - HK - HR - HU - ID - IE - IN - IT - JP - KR - LI - LT - LU - LV - MT - MX - MY - NL - NO - NZ - PE - PH - PL - PT - RO - RS - SE - SG - SI - SK - SN - TH - TT - US - UY ### Expiration des liens de l’environnement de test et de l’onboarding Un environnement de test récupérable expire après 60 jours. Vous pouvez voir l’horodatage exact d’expiration dans le champ `expires_at` de niveau supérieur. Sept jours avant l’expiration, Stripe envoie un e-mail à l’adresse figurant dans `prefill.email` pour rappeler à vos utilisateurs de réclamer l’environnement de test avant que Stripe ne le supprime. Si un utilisateur ne réclame pas l’environnement de test dans les 60 jours, Stripe le supprime définitivement. Le lien d’onboarding est valable sept jours. Vous pouvez voir l’horodatage exact d’expiration dans le champ `onboarding_link_details.expires_at`. Si un utilisateur accède à un lien d’onboarding expiré, Stripe redirige l’utilisateur vers l’URL dans `onboarding_link_details.refresh_url`. Votre `refresh_url` doit appeler une méthode sur votre serveur qui invoque l’API Claimable sandboxes renew onboarding link, ce qui renouvelle le lien pour sept jours supplémentaires. ### Utiliser les clés API et l’authentification Les clés et la méthode d’authentification que vous utilisez dépendent de l’entité qui effectue l’action : - Les agents LLM agissant au nom de l’utilisateur doivent utiliser les [outils MCP](https://docs.stripe.com/mcp.md#tools) avec la clé MCP. - Le code déterministe de votre plateforme, par exemple, le code qui récupère les données de paiement pour créer un Dashboard listant les paiements, doit [appeler les API](https://docs.stripe.com/stripe-apps/build-backend.md#using-stripe-apis) sur l’environnement de test en utilisant l’[identification Stripe Apps](https://docs.stripe.com/stripe-apps/build-backend.md#authenticate-requests). Stripe limite l’accès à celles que vous avez initialement demandées dans votre manifeste. - La réponse de l’API renvoie les clés `publishable` et `secret` permettant à votre plateforme d’intégrer l’application d’utilisateur final, par exemple, via un fichier `.env`. Lorsqu’un utilisateur final d’une application générée effectue un paiement, ces appels à l’API utilisent les clés `secret` et `publishable`. Enregistrez les clés API de la réponse de création, car Stripe ne les renvoie pas dans les requêtes de récupération ultérieures. > Cette clé MCP expire sept jours après qu’un utilisateur a réclamé l’environnement de test. Suivez la [spécification d’autorisation MCP](https://modelcontextprotocol.io/specification/draft/basic/authorization) pour vous assurer que votre plateforme peut gérer les clés expirées. Lorsque vous créez un nouvel environnement de test réclamable, Stripe préinstalle automatiquement l’application Stripe de votre plateforme dans cet environnement de test. Cela crée une connexion entre votre plateforme et l’environnement de test et vous permet d’effectuer des actions au nom de vos utilisateurs dans l’environnement de test. La structure du compte ressemble désormais à ceci : Ce diagramme montre que l’environnement de test géré de Bizbot est connecté à l’environnement de test non réclamé de Jenny Rosen, créé via l’application Stripe préinstallée (See full diagram at https://docs.stripe.com/sandboxes/claimable-sandboxes) ```text [acct_bizbot_livemodeCompte de production] --> [acct_bizbot_sandboxApplication gérée de l’environnement de test] [acct_bizbot_sandboxApplication gérée de l’environnement de test] -- Application d’environnement de test installée --> [acct_jenny_sandboxEnvironnement de test non réclamé] ``` Dans l’exemple Bizbot, étant donné que l’application Bizbot est préinstallée dans le compte de l’environnement de test `acct_jenny_sandbox`, le compte de l’environnement de test de l’application gérée par Bizbot `acct_bizbot_sandbox` peut désormais appeler des API et écouter les événements provenant de `acct_jenny_sandbox`. Consultez la section [Comment Fonctionnement de Stripe Apps](https://docs.stripe.com/stripe-apps/how-stripe-apps-work.md) pour plus de détails. ## Réclamer l’environnement de test Lorsque votre utilisateur est prêt à réclamer l’environnement de test, votre plateforme doit fournir l’URL d’onboarding pour que l’utilisateur puisse faire la réclamation dans le Dashboard Stripe. Si l’utilisateur a déjà un compte Stripe, il peut réclamer l’environnement de test à partir de ce compte. Si l’utilisateur n’a pas de compte Stripe, Stripe l’invite à s’inscrire, puis déplace l’environnement de test dans ce nouveau compte. Une fois que l’utilisateur réclame l’environnement de test, votre plateforme reçoit l’événement v2.core.claimable_sandbox.claimed. Le hachage `owner_details` est renseigné sur l’objet environnement de test réclamable. La valeur de `owner_details.app_install_status` change si l’utilisateur réclame l’environnement de test dans un compte Stripe existant ou un nouveau compte. Par exemple, si l’utilisateur réclame l’environnement de test dans un nouveau compte Stripe, `app_install_status` est défini sur `pending_onboarding`. ```json { "id": "clmsbx_test_123", "object": "v2.core.claimable_sandbox", "app_channel": "testing", "claimed_at": "2026-04-23T00:00:00.000Z", "created": "2026-04-22T00:00:00.000Z", "expires_at": null, "onboarding_link_details": { "expires_at": "2026-04-29T00:00:00.000Z", "refresh_url": "https://example.com/refresh", "url": "https://dashboard.stripe.com/onboard_sandbox/{{SIGNATURE}}" }, "owner_details": { "account": null, "app_install_status": "pending_onboarding" }, "prefill": { "email": "jenny.rosen@example.com", "country": "US" }, "sandbox_details": { "account": "acct_jenny_sandbox", "api_keys": null }, "status": "claimed" } ``` Le champ `app_install_status` indique l’état du compte propriétaire, c’est-à-dire le compte en mode production qui a réclamé l’environnement de test. Ce champ est utile pour surveiller le cycle de vie de l’environnement de test récupérable. Consultez les valeurs d’énumération possibles. Dans ce scénario, la structure de compte mise à jour ressemble à ceci après la demande : Ce diagramme montre que l’environnement de test géré de Bizbot est connecté à l’environnement de test réclamé pour Jenny Rosen (See full diagram at https://docs.stripe.com/sandboxes/claimable-sandboxes) ```text [acct_bizbot_livemodeCompte de production] --> [acct_bizbot_sandboxApplication gérée de l’environnement de test] [acct_bizbot_sandboxApplication gérée de l’environnement de test] -- Application d’environnement de test installée --> [acct_jenny_sandboxEnvironnement de test réclamable] [acct_jenny_livemodeCompte propriétaire (pas encore inscrit)] --> [acct_jenny_sandboxEnvironnement de test réclamable] ``` ## L’utilisateur envoie le formulaire d’activation Si votre utilisateur réclame l’environnement de test dans un nouveau compte Stripe, l’utilisateur doit inscrire le compte Stripe en soumettant le formulaire d’activation avant la mise en production. Une fois que l’utilisateur réclame l’environnement de test, l’accès au lien d’onboarding le redirige de nouveau vers le formulaire d’activation dans le Dashboard. Une fois le formulaire d’activation envoyé par votre utilisateur, votre plateforme reçoit l’événement v2.core.claimable_sandbox.updated, qui indique que le champ `app_install_status` désormais défini sur `pending_install`. La structure de compte mise à jour ressemble à ceci après l’onboarding : This diagram shows that the managed app sandbox of Bizbot has a connection to the claimed sandbox for Jenny Rosen, and the live account is onboarded (See full diagram at https://docs.stripe.com/sandboxes/claimable-sandboxes) ```text [acct_bizbot_livemodeCompte de production] --> [acct_bizbot_sandboxApplication gérée de l’environnement de test] [acct_bizbot_sandboxApplication gérée de l’environnement de test] -- Application d’environnement de test installée --> [acct_jenny_sandboxEnvironnement de test réclamable] [acct_jenny_livemodeCompte propriétaire (inscrit)] --> [acct_jenny_sandboxEnvironnement de test réclamable] ``` ## L’utilisateur installe votre application Stripe dans le compte propriétaire en mode production Une fois que votre utilisateur envoie le formulaire d’activation, Stripe invite l’utilisateur à installer l’application Stripe de votre plateforme dans le compte en mode production. Après l’installation, votre plateforme reçoit l’événement v2.core.claimable_sandbox.updated, qui indique que le champ `app_install_status` est passé à l’état `installed`. Le champ `owner_details.account` est également renseigné avec l’ID du compte propriétaire. Après l’installation, le champ `status` de l’environnement de test devient `live`. Cela signifie que l’objet environnement de test réclamable a atteint la fin de son cycle de vie et ne changera plus. À ce stade, votre intégration de l’environnement de test réclamable est terminée et prête à être mise en production. ```json { "id": "clmsbx_test_123", "object": "v2.core.claimable_sandbox", "app_channel": "testing", "claimed_at": "2026-04-23T00:00:00.000Z", "created": "2026-04-22T00:00:00.000Z", "expires_at": null, "onboarding_link_details": { "expires_at": "2026-04-29T00:00:00.000Z", "refresh_url": "https://example.com/refresh", "url": "https://dashboard.stripe.com/onboard_sandbox/{{SIGNATURE}}" }, "owner_details": { "account": "acct_jenny_livemode", "app_install_status": "installed" }, "prefill": { "email": "jenny.rosen@example.com", "country": "US" }, "sandbox_details": { "account": "acct_jenny_sandbox", "api_keys": null }, "status": "live" } ``` Le diagramme suivant montre la structure finale du compte. Ceci montre la relation entre les 4 comptes Stripe différents. Le compte Bizbot en mode production peut accéder au compte en mode production de Jenny. L'application de l'environnement de test peut accéder à l'environnement de test de Jenny. (See full diagram at https://docs.stripe.com/sandboxes/claimable-sandboxes) ```text [acct_bizbot_livemodeCompte de production] --> [acct_bizbot_sandboxApplication gérée de l’environnement de test] [acct_bizbot_sandboxApplication gérée de l’environnement de test] -- Application d’environnement de test installée --> [acct_jenny_sandboxEnvironnement de test réclamable] [acct_bizbot_livemodeCompte de production] -- Application installée en mode production --> [acct_jenny_livemodeCompte propriétaire (inscrit)] [acct_jenny_livemodeCompte propriétaire (inscrit)] --> [acct_jenny_sandboxEnvironnement de test réclamable] ``` Après l’installation, votre plateforme peut effectuer des actions à la fois sur l’environnement de test et sur le compte du propriétaire en mode production pour le compte de votre client final. Les types d’actions dépendent des autorisations que vous avez configurées sur votre application Stripe. Dans l’exemple de Bizbot, une fois l’application Bizbot installée dans le compte propriétaire, le compte Bizbot en mode production `acct_bizbot_livemode` peut appeler des API et écouter des événements depuis le compte en mode production `acct_jenny_livemode`. De même, le compte d’environnement de test de l’application `acct_bizbot_sandbox` géré par Bizbot peut accéder au compte d’environnement de test `acct_jenny_sandbox`. Pour en savoir plus, consultez [Fonctionnement de Stripe Apps](https://docs.stripe.com/stripe-apps/how-stripe-apps-work.md). ## Utiliser des liens d’onboarding Le lien d’onboarding pour un environnement de test réclamable est disponible dans le champ `onboarding_link_details.url`. Ce lien avec état redirige votre utilisateur vers la prochaine action requise pour terminer le cycle de vie de l’environnement de test réclamable. - Si l’environnement de test récupérable n’a pas été réclamé, le lien redirige votre utilisateur vers le Dashboard pour qu’il puisse le réclamer. - Si le compte propriétaire de l’environnement de test n’a pas encore effectué son onboarding, le lien redirige votre utilisateur vers le formulaire d’activation dans le Dashboard, à condition que l’utilisateur ait accès à l’environnement de test récupérable. - Si l’application Stripe de votre plateforme n’est pas installée dans le compte propriétaire, le lien redirige votre utilisateur vers une page du Dashboard Stripe qui explique que l’application n’est pas installée et qui inclut un lien pour l’installer, à condition que l’utilisateur ait accès à l’environnement de test récupérable. Le lien d’onboarding est actif pendant sept jours. Vous trouverez la date d’expiration dans `onboarding_link_details.expires_at`. Lorsque le lien d’onboarding expire, l’accès au lien redirige votre utilisateur vers l’URL définie dans `onboarding_link_details.refresh_url`. ## Soumettre l’application pour examen Suivez ces étapes avant de passer votre intégration en mode production : 1. **Envoyez votre application pour examen** : [Envoyez votre application](https://docs.stripe.com/stripe-apps/publish-app.md) à Stripe pour examen. En plus de satisfaire aux exigences habituelles de la [liste des applications](https://docs.stripe.com/stripe-apps/publish-app.md#write-your-listing), prenez en compte les exigences suivantes pour les applications d’environnement de test revendicables : - Fournissez des identifiants de test dans votre liste des applications pour un compte de test sur votre plateforme. Activez l’intégration d’environnement de test revendicable sur le compte de test, afin que le personnel de vérification de l’application puisse se connecter à votre plateforme et tester la fonctionnalité du point de vue de votre utilisateur. - Chargez suffisamment de jetons ou de crédits sur le compte de test, le cas échéant. - Dans les directives de test, fournissez une invite que le personnel de vérification de l’application peut utiliser pour déclencher l’intégration d’environnement de test revendicable. Par exemple, « Créez une application web avec une suite d’outils complète pour mon magasin de plantes et ajoutez le paiement Stripe pour accepter des paiements ». 2. **Publier votre application** : Une fois que Stripe a approuvé votre application, [publiez votre application](https://docs.stripe.com/stripe-apps/publish-app.md#app-review-decision-and-publication). 3. **Mettre à jour votre intégration d’API** : Mettez à jour votre intégration d’API d’environnement de test revendicable pour utiliser `app_channel: public` au lieu de `app_channel: testing`. > Utilisez `app_channel: test` uniquement pour les tests. Ce canal présente des restrictions. Par exemple, vous pouvez effectuer au maximum 25 installations en mode production sur le canal test. Ne passez pas votre intégration en mode production avec le canal de test. ## Optional: Tester une nouvelle version d’application Pour tester une nouvelle version de votre application Stripe avant de la publier, suivez ces étapes : 1. **Mettre à jour la version de test de votre application** : Pour tester une nouvelle version, [mettez à jour la version de test](https://docs.stripe.com/stripe-apps/test-app.md#update-test-version). 2. **Créez un environnement de test réclamable avec `app_channel: testing`** : utilisez l’[API Claimable Sandboxes](https://docs.stripe.com/sandboxes/claimable-sandboxes.md#api) et transmettez le paramètre `app_channel: testing`. Cela crée un environnement de test réclamable avec la nouvelle version de votre application préinstallée. Après avoir vérifié que la nouvelle version fonctionne comme prévu, suivez ces étapes pour qu’elle soit approuvée et [publiez-la](https://docs.stripe.com/sandboxes/claimable-sandboxes.md#review-and-publish) avant de la proposer à vos utilisateurs finaux. Utilisez `app_channel: public` lorsque vous créez des environnements de test réclamables en mode production. ## See also - [Créer une application Stripe](https://docs.stripe.com/stripe-apps/create-app.md) - [Documentation du manifeste d’application](https://docs.stripe.com/stripe-apps/reference/app-manifest.md) - [MCP de Stripe](https://docs.stripe.com/mcp.md)