# Représenter des clients à l’aide d’objets Account Gérez vos clients à l’aide de l’API Accounts v2 plutôt que de l’API Customers. L’API Accounts v2 utilise des *configurations* (Account configurations represent role-based functionality that you can enable for accounts, such as merchant, customer, or recipient) pour activer la fonctionnalité des objets `Account`. Lorsque vous utilisez l’API v2, vous pouvez représenter un client en utilisant un objet `Account` au lieu d’un objet `Customer` en attribuant la [configuration client](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) à l’`Account`. Lorsque vous effectuez une requête qui accepte un ID `Customer` comme argument du paramètre `customer`, fournissez plutôt l’ID `Account` comme argument du paramètre `customer_account`. L’exemple suivant crée un `Account` avec la configuration `customer` et demande la fonctionnalité courante `automatic_indirect_taxer`, qui fait partie de la configuration `customer`. La demande de la fonctionnalité est facultative ; vous pouvez simplement ajouter la configuration en spécifiant `configuration.customer`. ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: $latestPreviewApiVersion" \ --json '{ "contact_email": "jenny.rosen@example.com", "display_name": "Jenny Rosen", "identity": { "country": "us", "individual": { "given_name": "Jenny Rosen" } }, "configuration": { "customer": { "capabilities": { "automatic_indirect_tax": { "requested": true } } } }, "include": [ "configuration.customer", "identity" ] }' ``` Lorsque vous activez l’API Accounts v2, vos intégrations hébergées par Stripe, telles que Checkout, créent des `Accounts` avec la configuration `customer` au lieu des objets `Customer.` Si votre code fait référence à des objets `Customer,` nous vous recommandons de le mettre à jour pour faire référence à des objets `Account` configurés par le client. | Objectif | Référence v1 | Référence v2 | | ---------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Référence client | `customer` | `customer_account` | | Identification des clients | `cus_xxxxx` | `acct_xxxxx` | | Définir une adresse de facturation | [address](https://docs.stripe.com/api/customers/create.md#create_customer-address) | - [identity.individual.address](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-identity-individual-address) si le type d’entité est `individual`. - [identity.entreprise_details.address](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-identity-business_details-address) si le type d’entité est autre que `individual`. | | Définir une adresse de livraison | [shipping](https://docs.stripe.com/api/customers/create.md#create_customer-shipping) | [configuration.customer.shipping](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-shipping) | ## Indiquer un objet Account en tant que client Les requêtes API telles que `Subscriptions` et `SetupIntents` vous obligent à spécifier un client. Ces requêtes acceptent soit le paramètre `customer` ou `customer_account`. L’exemple suivant créé un abonnement et spécifie le client en transmettant un ID `Account` en tant que `client_account`. ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Version: $latestPreviewApiVersion" \ -d customer_account=acct_xxxxx \ -d "items[0][price]=price_CBb6IXqvTLXp3f" \ -d "items[0][quantity]=5" ``` ## Comptes de référence dans les intégrations Customer v1 Une requête qui précise le paramètre `customer_account` renvoie les deux propriétés `customer` et`customer_account`, avec des valeurs formatées correspondantes. Cela maintient la compatibilité avec les intégrations existantes de Billing and Payments. ```javascript { "id": "sub_1Mow234", . . . "customer": "cus_xxxxx", "customer_account": "acct_xxxxx" } ``` Vous pouvez également récupérer ou mettre à jour des comptes configurés par le client en utilisant l’endpoint `/v1/customers`. ```curl curl -X POST https://api.stripe.com/v1/customers/acct_1234 \ -u "<>:" ``` ## Webhooks Accounts v2 Les webhooks d’Accounts v2 envoient des [événements légers](https://docs.stripe.com/event-destinations.md#thin-events). | Action | Événement v1 | Événement v2 | | ---------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client créé | `customer.created` | Accounts v2 envoie des événements distincts indiquant la création du compte et la configuration du client : - `v2.core.account.created` - `v2.core.account[configuration.customer].updated` | | Adresse de facturation mise à jour | `customer.updated` | `v2.core.account[identity].updated` | | Actions abonnement | `customer.subscription.[action]` | Aucune ; utiliser l’événement v1 | | Client effacé | `customer.deleted` | `v2.core.account.closed` | ## Propriétés de la facture client | Valeur des données | Propriété Customers v1 | Propriété Accounts v2 | | ----------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Crédit client sauvegardé | `invoice_credit_balance` | Aucune ; consultez [Référencer un ID Accounts v2 dans un chemin /v1/customers](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md#reference-accounts-v2-in-v1-customers-path) | | Préfixe facture client | `invoice_prefix` | [configuration.customer.billing.invoice.prefix](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-prefix) | | Paramètres personnalisés | `invoice_settings.custom_fields` | [configuration.customer.billing.invoice.custom_fields](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-custom_fields) | | Moyen de paiement par défaut | `invoice_settings.default_payment_method` | [configuration.customer.billing.default_payment_method](https://docs.stripe.com/api/v2/core/accounts/update.md#v2_update_accounts-response-configuration-customer-billing-default_payment_method) | | Pied de page de la facture | `invoice_settings.footer` | [configuration.customer.billing.invoice.footer](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-footer) | | Options de rendu des factures | `invoice_settings.rendering_options` | [configuration.customer.billing.invoice.rendering.template](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer-billing-invoice-rendering-template) | ## Faire référence à un ID Account avec un endpoint Customers L’API Accounts v2 n’a pas d’endpoints pour chaque fonction client. Pour effectuer les actions suivantes pour un objet `Account`, utilisez l’endpoint `v1/customers` et transmettez l’ID `Account` (`acct_xxxxx`) comme paramètre de chemin d’accès. | Cas d’usage | Endpoint v1 avec ID de compte | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Gérer les soldes de trésorerie | - `v1/customers/acct_xxxxx/cash_balances` - `v1/customers/acct_xxxxx/cash_balances/:id` | | Gérer la liste de toutes les opérations sur solde disponible | - `GET v1/customers/acct_xxxxx/cash_balance_transactions` - `GET v1/customers/acct_xxxxx/cash_balance_transactions/:id` - `POST v1/test_helpers/customers/acct_xxxxx/fund_cash_balance` - `POST v1/customers/acct_xxxxx/funding_instructions` - `GET v1/customers/acct_xxxxx/funding_instructions` | | Gérer le solde créditeur de la facture Pour les objets `Account`, le [ending_balance](https://docs.stripe.com/api/invoices/object.md?api-version=preview#invoice_object-ending_balance) de la dernière facture finalisée du compte correspond à la `invoice_credit_balance` de l’objet `Customer`. | - `POST v1/customers/acct_xxxxx/balance_transactions` - `POST v1/customers/acct_xxxxx/balance_transactions/:id` - `GET v1/customers/acct_xxxxx/balance_transactions/:id` - `GET v1/customers/acct_xxxxx/balance_transactions` | ## Carte des propriétés de l’objet Customer-Account Le tableau suivant décrit comment les propriétés des objets `Customer` correspondent aux propriétés des objets `Account` configurés par le client. Sauf indication contraire, Stripe copie les valeurs mappées lors de la génération d’un `Account` correspondant vers un `Customer` existant. Les valeurs mappées restent synchronisées. Par exemple, si vous définissez `identity.country` sur un `Account`, alors lorsque vous transmettez cet ID `Account` comme `customer_account` à un endpoint v1, le `country` renvoyé contient la même valeur. | Propriété Customers v1 | Propriété Accounts v2 | Remarques | | --------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | {all properties} | `identity.business_details.address` ou `identity.individual.address` | Lorsque Stripe associe un `Customer` v1 à un `Account` v2, `address` n’est inclus que s’il réussit la validation. `address.country` (chaîne dans la v1 et énumération dans la v2) n’est inclus que s’il correspond à une énumération ou à un nom de pays valide, en ignorant la casse et les éventuels caractères spéciaux. | | `country` | `identity.country` | Lorsque Stripe associe un `Customer` v1 à un `Account` v2, `address.country` (chaîne) n’est copié dans `identity.country` (énumération) que s’il correspond à une énumération ou un nom de pays valide, en ignorant la casse et les éventuels caractères spéciaux. | | `business_name` | `identity.business_details.registered_name` | | | `created` | {not mapped} | Lorsque Stripe associe un `Customer` v1 à un `Account` v2, la propriété `created` par `Account` reflète l’horodatage au moment de la création du `Account`, et non le `Customer` d’origine. | | `currency` | {not mapped} | La propriété `default.devise` du `Account` v2 ne s’applique pas à la configuration `Customer`. | | `customer_account` | `id` | Lorsque Stripe associe un `Customer` v1 à un `Account` v2, la propriété `customer_account` du `Customer` contient l’ID de ce `Account`. L’ID du `Customer` n’est pas disponible sur le `Account`. Les utilisateurs qui créent des `Accounts` v2 représentant des clients n’ont pas besoin d’utiliser un ID `Customer` v1. | | `description` | {not mapped} | La `description` `Customer` v1 n’est pas disponible sur le `Account` v2. Cependant, elle apparaît (en lecture seule) sur la page d’informations client du Dashboard. | | `email` | `contact_email` | | | `id` | {not mapped} | L’ID du `Customer` v1 n’est pas disponible sur le `Account` v2. Les utilisateurs qui créent des `Accounts` v2 représentant des clients n’ont pas besoin d’utiliser un ID `Customer` v1. | | `individual_name` | `display_name` | Lorsque Stripe associe un `Customer` v1 à un `Account` v2, il ne copie `individual_name` que si le `name` du `Customer` est nul. | | `invoice_prefix` | `configuration.customer.billing.invoice.prefix` | | | `invoice_settings` | `custom_fields` | `configuration.customer.billing.invoice.custom_fields` | Le tableau `Account` est limité à 4 éléments. | | `default_payment_method` | `configuration.customer.billing.invoice.default_payment_method` | | | `footer` | `configuration.customer.billing.invoice.footer` | | | `rendering_options` | `configuration.customer.billing.invoice.rendering` | Lorsque Stripe associe un `Customer` v1 à un `Account` v2, `invoice_settings.rendering_options.amount_tax_display` (chaîne) ne copie dans `configuration.customer.billing.invoice.rendering.amount_tax_display` (énumération) que si elle correspond à une valeur d’énumération (`include_inclusive_tax` ou `exclude_tax`). | | `livemode` | `livemode` | | | `metadata` | `metadata` | | | `name` | `display_name` | Lorsque Stripe associe un `Customer` v1 à un `Account` v2, si `name` est nul, le `individual_name` du `Customer` est copié dans `display_name`. | | `next_invoice_sequence` | `configuration.customer.billing.invoice.next_sequence` | | | `phone` | `identity.business_details.phone or identity.individual.phone` | | | `preferred_locales` | `defaults.locales` | La propriété `Customer` `preferred_locales` est un tableau de chaînes annulable, et la propriété `Account` `defaults.locales` est un tableau d’énumérations annulable. Lorsque Stripe associe un `Customer` v1 à un `Account` v2, une chaîne `preferred_locales` donnée n’est incluse que si elle correspond à une valeur d’énumération `defaults.locales`, en ignorant la casse et les éventuels caractères spéciaux. | | `shipping` | `configuration.customer.shipping` | | | `subscriptions` | {not mapped} | L’objet `Account` v2 n’inclut pas de tableau des abonnements. Pour récupérer les abonnements d’un client, utilisez l’API Subscriptions et filtrez par `Customer` ou `customer_account`. | | `tax` | `automatic_tax` | `configuration.customer.capabilities.automatic_indirect_tax.status` {value not synchronized} | La propriété `Account` n’est disponible qu’après avoir demandé la fonctionnalité Taxe indirecte automatique. De plus, elle n’a pas d’équivalent à la valeur `not_collecting` de la propriété `Customer`. Elle indique uniquement l’état de la fonctionnalité. | | `ip_address` | `configuration.customer.automatic_indirect_tax.ip_address` | | | `location` | `configuration.customer.automatic_indirect_tax.location` {value not synchronized} | Lorsque Stripe associe un `Customer` v1 à un `Account` v2, `tax.location` n’est pas automatiquement inclus. Vous devez demander la fonctionnalité Taxe indirecte automatique pour définir `configuration.customer.automatic_indirect_tax.location`. | | `provider` | {not mapped} | Si un `Customer` est associé à un prestataire de services fiscaux tiers, Stripe n’associe pas automatiquement ce `Customer` à un `Account`. | | `tax_exempt` | `configuration.customer.automatic_indirect_tax.exempt` | | | `tax_ids` | {not mapped} | L’objet `Account` v2 n’inclut pas de tableau de numéros fiscaux. Pour récupérer les numéros fiscaux d’un client, utilisez l’API Tax IDs et filtrez par `owner.customer` ou `owner.customer_account`. | | `test_clock` | `configuration.customer.test_clock` | | ## Activer la version bêta de Accounts v2 Auparavant, l’API Accounts v2 n’était disponible que pour les plateformes Connect. Elle est désormais disponible en version bêta pour tous les utilisateurs Stripe. Accounts v2 vous donne un moyen unifié de représenter vos utilisateurs à travers les produits Stripe. Au lieu d’utiliser des objets `Customer`, qui fournissent uniquement des fonctionnalités pour stocker des moyens de paiement et effectuer des paiements récurrents, vous pouvez utiliser des objets `Account`, qui offrent une plus grande flexibilité grâce à l’utilisation de configurations lorsque fonctionnalités supplémentaires sont nécessaires. Pour activer la version bêta : 1. Accédez aux [aperçus et fonctionnalités de Account](https://dashboard.stripe.com/settings/features/product-previews) dans votre Dashboard. 1. Activez le bouton d’activation **Moyens de paiement réutilisables pour Global Payouts**. Si vous ne voyez pas le bouton d’activation, requête d’accès à l’aide du formulaire en haut de cette page. Lorsque vous vous inscrivez, vos objets `Customer` existants sont automatiquement synchronisés avec les objets `Account` v2 configurés client correspondants. Lorsque vous créez un nouveau client dans le Dashboard, il génère un objet `Account` configuré client, et non un objet `Customer`. Vous pouvez utiliser ces `Accounts` dans la [plupart des intégrations qui font référence à des objets Customer](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md#reference-accounts-in-customers-v1-integrations). En activant la version bêta de Accounts v2, vous activez également les [identifiants de paiement réutilisables pour Global Payouts](https://docs.stripe.com/global-payouts/credential-reuse.md), ce qui vous permet de stocker et de réutiliser des moyens de paiement pour toutes les transactions Global Payouts. ## Limitations et désabonnement La version bêta de Accounts v2 ne prend pas en charge les fonctionnalités suivantes : - [Clonage de clients](https://docs.stripe.com/get-started/data-migrations/pan-copy-self-serve.md) - [Partager les clients et moyens de paiement au sein d’une organisation](https://docs.stripe.com/get-started/account/orgs/sharing/customers-payment-methods.md) - Intégrations fiscales tierces (Stripe Tax est pris en charge) Pour refuser, désactivez le bouton dans les [aperçus et fonctionnalités de Account](https://dashboard.stripe.com/settings/features/product-previews). La désactivation n’annule pas les objets `Customer` existants qui sont déjà associés aux objets `Account` v2. Si vous avez besoin de fonctionnalités non prises en charge pour ces clients, vous devez leur créer de nouveaux objets `Customer`.