Utiliser l’API Accounts v2 dans votre intégration existante

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.

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 -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'

1. Retrieve the connected account to confirm it has the card_payments capability in the merchant configuration. This capability must be active in order to use the Stripe balance as a payment method.

curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "include": [
        "configuration.merchant",
        "identity",
        "defaults"
    ]
  }'

1. Add the connected account’s Stripe balance as a payment method.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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. Create a subscription that charges the connected account using its Stripe balance.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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.
2. Modifiez vos appels de create Account et Customer pour créer des Accounts configurés comme client en utilisant /v2/core/accounts.
3. Modifiez vos appels de update Account et Customer pour utiliser /v2/core/accounts.
4. 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 https://api.stripe.com/v1/customers/acct_1abc \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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). Nous vous conseillons de créer un nouveau endpoint dédié afin de recevoir les événements Accounts v2.

1. Dans votre Dashboard Stripe, ouvrez le menu des développeurs en cliquant sur Développeurs au bas du menu de navigation, puis sélectionnez Webhooks.
2. Cliquez sur + Ajouter une destination.
3. Dans la section Événements de, sélectionnez Comptes connectés.
4. Sélectionnez Afficher les options avancées. Dans la section Style de charge utile, sélectionnez Léger.
5. 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.
6. Poursuivez la configuration de votre destination d’événements en suivant les instructions du générateur d’endpoint de webhook interactif.

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 telles que legacy_payments
  • moyens de paiement obsolètes
  • moyens de paiement en aperçu public ou privé