Connect et l’API Accounts v2
Créez des comptes connectés avec une identité unifiée sur Stripe.
En tant que plateforme Connect, vous représentez vos comptes connectés à l’aide d’objets Account. Il existe deux versions d’Accounts :
- v2 : prise en charge hautement configurable et évolutive des paiements à destination et en provenance des comptes connectés, des transferts de fonds et d’autres fonctionnalités
- v1 : prise en charge limitée des comptes connectés et des paiements
Les objets Accounts v2 utilisent des configurations pour activer différents ensembles de fonctionnalités. Par exemple, l’ajout de la configuration merchant à un Account v2 lui permet de recevoir des paiements. Si vous souhaitez étendre les fonctionnalités d’un compte connecté existant, vous pouvez lui ajouter d’autres configurations.
Les objets Accounts v1 ne possèdent pas de configurations. Vous pouvez uniquement les utiliser pour gérer les paiements des comptes connectés.
Certaines fonctionnalités ne prennent pas encore directement en charge les Accounts v2. Toutefois, vous pouvez toujours transmettre l’ID d’un Account v2 à un endpoint de l’API Accounts v1. Le cas échéant, la réponse est structurée comme un Account v1, mais toutes les mises à jour s’appliquent tout de même aux propriétés correspondantes de l’objet v2.
Utiliser l’API Accounts v2 pour représenter les comptes connectés
L’API Accounts v2 fournit :
- Configurations de compte flexibles : Activez ou modifiez les fonctionnalités et la compatibilité d’un
Accountainsi que sa compatibilité avec les fonctionnalités Stripe en mettant à jour ses configurations. Chaque fonctionnalité dépend d’une configuration spécifique. - Données d’identité centralisées : lorsque vous ajoutez une configuration à un
Accountexistant pour activer des fonctionnalités supplémentaires, vous n’avez pas besoin de recueillir à nouveau les informations qu’il a déjà fournies. - Une seule API pour les comptes connectés et les clients : dans la majorité des cas, chaque client peut être représenté par un objet
Account. Vous pouvez ainsi utiliser l’API Accounts v2 pour gérer à la fois vos comptes connectés et vos clients, sans avoir à recourir à l’API Customers.
Les configurations les plus courantes sont les suivantes :
- Attribuez la configuration
merchantpour permettre àAccountd’accepter des paiements de la part de clients. Elle inclut les fonctionnalitéscard_etpayments stripe_(qui remplacebalance. payouts payoutsde la v1). - La configuration
customerpermet à votre plateforme de débiter unAccounten tant que client. Vous pouvez l’utiliser à la place d’un objetCustomerlors de la création d’un abonnement ou d’une facture. - La configuration
recipientpermet à unAccountde recevoir des transferts de fonds. Elle inclut la fonctionnalitéstripe_(qui remplacebalance. stripe_ transfers transfersde la v1), laquelle est requise pour utiliser les paiements indirects.
L’exemple suivant crée un Account à l’aide de l’API v2. Notez que sa structure diffère de celle d’un objet Account dans l’API v1.
Structure de réponse de l’API v2
Par défaut, les appels à l’API Accounts v2 renvoient des valeurs pour certaines propriétés et null pour d’autres, quels que soient leurs contenus réels. Pour obtenir des propriétés supplémentaires, utilisez le paramètre include.
curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer" \ -H "Stripe-Version: 2026-06-24.preview" \ --json '{ "contact_email": "jenny.rosen@example.com", "display_name": "Jenny Rosen", "dashboard": "full", "identity": { "business_details": { "registered_name": "Furever" }, "country": "us", "entity_type": "company" }, "configuration": { "merchant": { "capabilities": { "card_payments": { "requested": true } } } }, "defaults": { "currency": "usd", "responsibilities": { "fees_collector": "stripe", "losses_collector": "stripe" }, "locales": [ "en-US" ] }, "include": [ "configuration.merchant", "identity", "requirements" ] }'sk_test_VePHdqKTYQjKNInc7u56JBrQ
La spécification de requirements dans le tableau include renvoie toutes les informations obligatoires par défaut qui s’appliquent au nouvel Account.
Utiliser Accounts comme clients
Toute requête d’API comportant un paramètre customer qui accepte un ID de Customer possède également un paramètre customer_ qui accepte un ID d’Account. Vous pouvez l’utiliser pour fournir l’ID d’un Account v2 doté de la configuration customer au lieu de fournir l’ID d’un Customer. Par exemple :
curl https://api.stripe.com/v1/setup_intents \ -u ":" \ -d customer_account=acct_123 \ -d "automatic_payment_methods[enabled]=true" \ -d confirm=true \ --data-urlencode "return_url=https://example.com/return" \ -d usage=off_sessionsk_test_VePHdqKTYQjKNInc7u56JBrQ
Si vous utilisez l’API Accounts v1, vous ne pouvez pas transmettre un ID de l’objet Account à un endpoint qui attend un ID de Customer. Si vous souhaitez débiter vos comptes connectés à l’aide d’abonnements, vous devez créer et gérer des objets Customer distincts pour ces derniers.
En savoir plus sur l’utilisation des Accounts comme clients.
Plateformes Connect existantes utilisant Accounts v1 et Customers v1
Vous pouvez utiliser l’API Accounts v2 pour gérer les Accounts créés à l’aide de l’API Accounts v1, et notamment leur attribuer la configuration customer.
Stripe déconseille de maintenir indéfiniment deux versions de l’API Accounts en parallèle.
Limitations de l’API Accounts v2
Vous devez utiliser Accounts v1 dans les cas suivants :
- Utiliser OAuth pour s’authentifier auprès des comptes connectés
- Faire signer un contrat d’utilisation du service bénéficiaire aux comptes connectés
- Pour demander ou gérer les fonctionnalités suivantes :
treasurycard_issuing_ * - Fonctionnalités obsolètes telles que
legacy_payments - moyens de paiement obsolètes
- certains moyens de paiement en aperçu public ou privé
Virements transfrontaliers
Utilisez Virements internationaux pour effectuer des virements transfrontaliers.