# 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 Treasury 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-05-27.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-05-27.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 `Accounts` v2 envoient à la fois des [Events v1 (snapshot) et des Events v2 (légers)](https://docs.stripe.com/event-destinations.md#events-overview). Les événements v1 dépendent de la configuration mise à jour. Par exemple, la mise à jour des propriétés de la configuration `merchant` génère des événements v1 `account.updated`, tandis que la mise à jour des propriétés de la configuration `customer` génère des événements v1 `customer.updated`. Nous recommandons de configurer de nouveaux endpoints pour écouter les événements v2. Les webhooks pour les utilisateurs de Connect écoutent les événements dans différentes portées, selon la source de l’événement : - **Votre compte** : la plupart des événements déclenchés par des ressources qui existent dans votre compte. Cela inclut la plupart des requêtes effectuées avec vos clés API et sans [s’authentifier en tant qu’autre compte Stripe](https://docs.stripe.com/connect/authentication.md), telles que : - Événements `v2.core.account.*` pour les `Accounts` v2 de votre compte - Événements pour les `Customers` de votre compte - Événements pour les paiements directs sur votre compte - Événements pour les *paiements indirects* (A charge type where customers transact directly with your platform instead of with a connected account. Indirect charges include destination charges and separate charges and transfers) sur votre compte pour vos comptes connectés - **Comptes connectés** : événements déclenchés par des ressources qui existent dans des comptes connectés et certaines ressources qui existent dans votre compte, tels que : - Événements `v2.core.account.*` pour les `Accounts` v2 représentant les clients et bénéficiaires de vos comptes connectés - Événements v1 `account.updated` pour les `Accounts` v1 et v2 représentant les clients et bénéficiaires de vos comptes connectés - *Paiements directs* (A charge type where customers transact directly with a connected account, which is always the merchant of record. With each payment, the connected account pays fees to Stripe and, optionally, to your platform) pour les clients de vos comptes connectés > #### Portées des événements pour les comptes v2 représentant des comptes connectés > > Les objets `Account` v2 déclenchent à la fois des `Events` v1 et v2, dont la portée peut différer. Pour les événements déclenchés par des comptes connectés, les `Events` v2 utilisent la portée **Votre compte**, tandis que les `Events` v1 utilisent la portée **Comptes connectés**, même lorsqu’ils sont déclenchés par le même `Account` v2. > > Le comportement des événements `Account` v2 diffère de celui des événements `Account` v1, car tous les événements associés aux objets `Account` v1 utilisent la portée **Comptes connectés**. Le tableau suivant indique la portée à sélectionner lors de la création d’un webhook : | Source de l’événement | Portée de l’événement | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | Mises à jour des objets `Account` v1 représentant des comptes connectés | Comptes connectés | | Mises à jour des objets `Account` v2 représentant des comptes connectés | - Événements v2 : Votre compte (portée modifiée depuis l’API v1) - Événements v1 : Comptes connectés | | Mises à jour des objets `Customer` représentant des comptes connectés | Votre compte | | Mises à jour des objets `Account` v2 représentant des clients de comptes connectés qui effectuent des paiements directs | - Événements v2 : Comptes connectés - Événements v1 : Comptes connectés | | Mises à jour des objets `Customer` représentant des clients de comptes connectés qui effectuent des paiements directs | Comptes connectés | | Mises à jour des objets `Account` v2 représentant des clients de comptes connectés qui effectuent des paiements indirects créés sur la plateforme | - Événements v2 : Votre compte - Événements v1 : Votre compte | | Mises à jour des objets `Customer` représentant des clients de comptes connectés qui effectuent des paiements indirects sur la plateforme | Votre compte | | Paiements directs effectués vers des comptes connectés | Comptes connectés | | Mises à jour des `Invoices` et des `Subscriptions` que les comptes connectés facturent à leurs clients via des paiements directs | Comptes connectés | | Paiements indirects créés sur la plateforme pour les clients de comptes connectés | Votre compte | | Mises à jour des `Invoices` et des `Subscriptions` que les clients de comptes connectés règlent via des paiements indirects créés sur la plateforme | Votre compte | | Paiements directs créés sur la plateforme, y compris les paiements effectués par des comptes connectés | Votre compte | Pour écouter les `Events` v2 déclenchés par les `Accounts` représentant vos comptes connectés : 1. Ouvrez l’onglet [Webhooks](https://dashboard.stripe.com/workbench/webhooks) dans Workbench. 1. Créez une nouvelle destination d’événement ou modifiez une destination existante. 1. Dans la section **Événements provenant de**, sélectionnez **Votre compte**. 1. Dans la section **Événements**, sélectionnez les types d’événements v2 que le webhook doit écouter, puis cliquez sur **Continuer**. 1. Sélectionnez le type de destination et cliquez sur **Continuer**. 1. Finalisez la configuration de l’endpoint en suivant l’outil de création interactif pour le type de destination sélectionné. ### 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.