# Utiliser l’API Accounts v2 dans votre intégration existante Découvrez comment mettre à jour les intégrations basées sur Accounts v1 et Customers v1. Suivez ce guide pour mettre à jour votre intégration Connect reposant sur Accounts v1 et Customers v1 et profiter des fonctionnalités proposées par Accounts v2 : - Reliez vos comptes connectés aux paiements effectués sur votre plateforme, sans avoir besoin de créer des objets Customer. - Évitez les coûts de réseau en permettant à vos comptes connectés de payer votre plateforme avec leur solde Stripe. - Permettez à vos comptes connectés de conserver des fonds sur votre plateforme en utilisant les Comptes financiers v2. Si vous n’avez pas besoin des fonctionnalités d’Accounts v2, vous pouvez continuer à utiliser votre intégration de plateforme basée sur Accounts v1 et Customers v1. ## Utilisez les endpoints v2 pour l’ensemble de vos comptes L’API Accounts v2 fonctionne avec vos `Accounts` v1 existants, sans nécessiter aucune modification. > #### Délai de création d’un compte > > Un nouveau `Account` v1 peut nécessiter jusqu’à 10 minutes avant de pouvoir être utilisé avec un endpoint Accounts v2. Lorsque l’`Account` est prêt pour les requêtes API v2, il envoie un événement webhook `v2.core.account.created`. ### Ajouter une configuration client En ajoutant la configuration `Customer` à un `Account`, vous pouvez utiliser l’identifiant `Account` dans toute requête API qui accepte un identifiant `Customer`, par exemple pour créer un abonnement. Plutôt que de renseigner le paramètre `customer` avec un identifiant `Customer`, vous indiquez le paramètre `customer_account` avec l’identifiant `Account`. Dans cet exemple, l’API Accounts v2 permet d’ajouter la configuration `Customer` à un Account v1 existant, puis de mettre à jour un abonnement pour que le compte soit facturé via son solde Stripe. 1. Mettez à jour l’`Account` pour ajouter la configuration `customer`. ```curl curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "configuration": { "customer": { "capabilities": { "automatic_indirect_tax": { "requested": true } } } }, "include": [ "configuration.customer", "identity" ] }' ``` 1. Récupérez le compte connecté pour confirmer qu’il dispose de la fonctionnalité `card_payments` dans la configuration commerçant. Cette fonctionnalité doit être active pour pouvoir utiliser le solde Stripe comme moyen de paiement. ```curl curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "include": [ "configuration.merchant", "identity", "defaults" ] }' ``` 1. Ajoutez le solde Stripe du compte connecté comme moyen de paiement. ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d customer_account=acct_1abc \ -d "payment_method_types[]=stripe_balance" \ -d confirm=true \ -d usage=off_session \ -d "payment_method_data[type]=stripe_balance" ``` 1. Créez un abonnement qui facture le compte connecté en utilisant son solde Stripe. ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer_account=acct_1abc \ -d payment_behavior=default_incomplete \ -d "items[0][price]={{PRICE_ID}}" \ -d "payment_settings[save_default_payment_method]=on_subscription" ``` Il n’est plus nécessaire de créer un objet `Customer` séparé pour recevoir les paiements d’abonnement de ce compte connecté. ## Adaptez votre intégration progressivement, étape par étape Comme vous pouvez utiliser à la fois les API Accounts v1 et v2 avec vos `Accounts`, vous pouvez mettre à jour votre intégration selon le rythme qui convient le mieux à votre activité. Par exemple, vous pouvez : - Appelez les endpoints `/v2/core/accounts` pour les `Accounts` créés avec l’API v1. - Appelez les endpoints `/v1/accounts` pour les `Accounts` créés avec l’API v2. - Appelez les endpoints `/v1/customers` pour les `Accounts` disposant de la configuration client. - Utilisez l’API Événements v2 pour écouter les modifications des objets, qu’ils soient créés via la version v1 ou v2 de l’API. Grâce à ces compatibilités, vous pouvez adapter votre intégration progressivement, sans avoir à maintenir plusieurs versions en production ni à mettre à jour l’intégralité de votre intégration d’un coup. Nous recommandons de mettre à jour votre intégration dans l’ordre suivant : 1. Configurez un nouveau endpoint pour écouter les [Événements v2](https://docs.stripe.com/event-destinations.md#thin-events). 1. Modifiez vos appels de `create` `Account` et `Customer` pour créer des `Accounts` configurés comme client en utilisant `/v2/core/accounts`. 1. Modifiez vos appels de `update` `Account` et `Customer` pour utiliser `/v2/core/accounts`. 1. Modifiez vos appels de `retrieve` `Account` et `Customer` pour utiliser `/v2/core/accounts`. ### Utilisez des Accounts v2 dans des endpoints v1 Lorsque vous utilisez des objets v2 dans des endpoints v1, les données sont renvoyées au format d’un objet v1. Par exemple : - Lorsque vous référencez un `Account` v2 dans un endpoint `/v1/accounts`, les données sont renvoyées au format d’un `Account` v1. - Lorsque vous référencez un `Account` v2 dans un endpoint `/v1/customers`, les données sont renvoyées au format d’un `Customer` v1 et contiennent à la fois l’identifiant `customer` et l’identifiant `customer_account`. ```curl curl https://api.stripe.com/v1/customers/acct_1abc \ -u "<>:" \ -d "business_name=Furever Plus" ``` Vous pouvez utiliser des `Accounts` configurés avec Customer dans l’API Customers v1, mais vous ne pouvez pas référencer des `Customers` v1 dans l’API Accounts v2. Vous devez soit migrer les données client vers un `Account` configuré avec Customer, soit mettre à jour un compte connecté existant pour ajouter la configuration `Customer`. ## Événements de webhook Les Comptes génèrent des [événements v1 (snapshot) et v2 (thin)](https://docs.stripe.com/event-destinations.md#events-overview). Nous vous conseillons de créer un nouveau endpoint dédié afin de recevoir les événements Accounts v2. 1. Dans votre [Dashboard Stripe](https://dashboard.stripe.com), ouvrez le menu des développeurs en cliquant sur **Développeurs** au bas du menu de navigation, puis sélectionnez **Webhooks**. 1. Cliquez sur **+ Ajouter une destination**. 1. Dans la section **Événements de**, sélectionnez **Comptes connectés**. 1. Sélectionnez **Afficher les options avancées**. Dans la section Style de charge utile, sélectionnez **Léger**. 1. Dans le champ Événements, sélectionnez un ou plusieurs événements correspondant à la version de l’objet `Account` : - Pour v1, entrez « v1 » pour filtrer les types d’événements des objets v1, puis choisissez **v1.account.updated**. - Pour v2, entrez « v2 » pour filtrer les types d’événements des objets v2. Choisissez **v2.core.account.updated** ou l’un des événements **v2.core.account[\*].updated** correspondants. 1. Poursuivez la configuration de votre destination d’événements en suivant les instructions du [générateur d’endpoint de webhook interactif](https://docs.stripe.com/webhooks/quickstart.md). Par exemple, la mise à jour d’un `Account`, quelle que soit sa version, peut générer : - Un événement v1 `account.updated` - Un événement v2 `v1.account.updated` - Un événement v2 `v2.core.account.updated` ### Différences de version des Comptes dans l’API Événements v2 La majorité des événements `v2.core.account` ne correspondent pas directement aux événements `v1.account`. Par exemple, toute modification d’une propriété d’un `Account` déclenche un événement `v1.account.updated`, tandis que la même modification peut produire des événements ciblés pour v2, comme `v2.core.account[identity].updated` ou `v2.core.account[configuration.recipient].updated`. L’événement `v2.core.account.updated` est envoyé uniquement lorsque des propriétés de premier niveau, comme `dashboard` ou `display_name`, sont mises à jour, sans déclencher les événements de mise à jour plus spécifiques. ## Limitations de l’API Accounts v2 Vous devez utiliser Accounts v1 dans les cas suivants : - Comptes connectés via OAuth - Des comptes ayant signé un contrat d’utilisation du service du bénéficiaire - Pour demander ou gérer les fonctionnalités suivantes : - `treasury` - `card_issuing_*` - [Fonctionnalités obsolètes](https://docs.stripe.com/connect/account-capabilities.md?accounts-namespace=v2#deprecated-capabilities) telles que `legacy_payments` - moyens de paiement obsolètes - moyens de paiement en aperçu public ou privé > #### Virements transfrontaliers > > Utilisez [Virements internationaux](https://docs.stripe.com/global-payouts.md) pour effectuer des virements transfrontaliers.