API Accounts v2Version bêta publique

Découvrez comment utiliser l’API Accounts v2 pour représenter vos comptes connectés sur Stripe.

L’API Accounts v2 vous permet de représenter votre utilisateur comme une entité unique sur Stripe.

Cette structure API fournit :

Une entité unique qui représente un compte connecté pour l’ensemble de son activité dans plusieurs configurations
Données d’identité structurées de la personne ou de l’entreprise que le compte représente
Les configurations de variables qui prennent en charge l’adoption et les mises à niveau concernant plusieurs produits
Fonctionnalités représentant des fonctionnalités basées sur la configuration qui dépendent d’exigences spécifiques

Comment les appels d’Account renvoient les données

Par défaut, Accounts v2 appelle des valeurs de renvoi pour certaines propriétés et des valeurs nulles pour d’autres, quelles que soient leurs valeurs réelles. Pour récupérer d’autres valeurs de propriété, demandez-les à l’aide du paramètre include.

L’exemple suivant crée un compte sans spécifier de propriétés de renvoi à inclure :

La réponse ne renvoie des valeurs que pour les propriétés qu’elle renvoie par défaut. Il renvoie une valeur nulle pour les autres propriétés, même celles auxquelles la requête a attribué des valeurs.

Response with no include
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer"
  ],
  "created": "2024-07-07T21:41:41.132Z",
  "display_name": "Furever",
  "configuration": null,
  "contact_email": "contact@test.com",
  "requirements": null,
  "identity": null,
  "defaults": null,
  "livemode": false
}

Pour renseigner des propriétés supplémentaires dans la réponse, spécifiez-les dans le paramètre include. Pour les configurations, vous devez spécifier explicitement les types de configuration individuels. Toute configuration non demandée renvoie une valeur nulle, quelles que soient ses données.

L’exemple suivant attribue des configurations customer et merchant, mais demande uniquement la configuration customer dans le paramètre include.

La réponse montre comment l’omission de configuration.merchant dans le tableau include renvoie une valeur null pour la configuration merchant, même si la requête spécifie des valeurs pour celle-ci. La valeur null indique seulement que le paramètre include de la requête n’a pas spécifié cette propriété.

Response with include but omitting merchant
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer",
    "merchant"
  ],
  "configuration": {
    "customer": {
      "automatic_indirect_tax": {
        "exempt": "none",
        "ip_address": null,
        "location": null,
        "location_source": "identity_address"
      },
      "billing": {
        "default_payment_method": null,
        "invoice": {
          "custom_fields": [],
          "footer": null,
          "next_sequence": 1,
          "prefix": "KD5JNJLZ",
          "rendering": null
        }
      },
      "capabilities": {
        "automatic_indirect_tax": {
          "requested": true,
          "status": "restricted",
          "status_details": [
            {
              "code": "requirements_past_due",
              "resolution": "provide_info"
            }
          ]
        }
      },
      "shipping": null,
      "test_clock": null
    },
    "merchant": null,
    "recipient": null
  },
  "requirements": "{...}"
}

Comprendre la création d’objet Account dans l’API v2

Lorsque vous créez un Account, vous devez fournir des informations d’identification sur l’entité qu’il représente et définir une ou plusieurs configurations qui contrôlent son comportement.

Informations d’identité

Remplissez le hachage identity avec des informations sur la personne ou l’entreprise que l’Account représente. Les paramètres spécifiques dépendent de la nature de l’entité.

Type d'entité:

Pour une personne agissant à titre personnel, définissez entity_type sur individual et renseignez le paramètre individual. Si la personne possède et exploite une entreprise sans distinction juridique entre le propriétaire et l’entreprise, définissez également business_details.structure sur sole_proprietorship.

Vous pouvez ajouter une personne représentative à un Account en créant un objet Person associé, comme dans l’exemple suivant.

Configurations

Chaque Account possède une ou plusieurs configurations qui représentent différents profils d’entreprise, tels qu’un marchand ou un client. Elles définissent la manière dont l’Account interagit avec les produits Stripe.

Chaque type de configuration inclut certaines fonctionnalités, qui activent des fonctionnalités spécifiques à la configuration lorsque les exigences associées sont remplies. Au lieu de simplement activer une fonctionnalité, vous la demandez, ce qui déclenche la collecte de ses exigences. Cette fonctionnalité s’active lorsque Stripe vérifie que ses exigences sont respectées.

Remplissez le paramètre configuration de l’Account avec un ou plusieurs des types de configuration suivants, en fonction de la fonctionnalité que vous souhaitez fournir.

Client

La configuration customer permet à un compte connecté d’effectuer des paiements sur votre plateforme et active des fonctionnalités dans des produits tels que Billing. Elle inclut la fonctionnalité automatic_indirect_tax qui vous aide à collecter les informations dont vous avez besoin pour calculer les taxes sur les factures, les abonnements et les liens de paiement de l’Account.

Marchand

La configuration merchant permet à la plateforme de contrôle de créer des paiements pour l’Account. Elle inclut la fonctionnalité card_payments, qui est nécessaire pour que l’Account accepte les paiements par carte.

Bénéficiaire

La configuration recipient permet à un Account de recevoir des fonds autres que des paiements directs, tels que des virements provenant d’une plateforme Connect. Elle inclut la fonctionnalité stripe_balance.stripe_transfers, qui permet au solde Stripe de l’Account de recevoir des transferts de fonds, et est nécessaire pour des fonctionnalités telles que les paiements indirects.

Fonctionnement des fonctionnalités

Pour activer une fonctionnalité, vous devez d’abord la demander en définissant sa propriété requested sur true. Cela déclenche la collecte des exigences de la fonctionnalité, qui est gérée par Stripe ou votre plateforme, en fonction des propriétés responsibilities de l’Account. Les exigences peuvent concerner la documentation relative à l’identité et à la conformité, ainsi que les données sur les risques. Lorsque Stripe vérifie que les exigences d’une fonctionnalité sont remplies, celle-ci devient active.

Exigences

Les exigences décrivent les informations dont Stripe a besoin pour activer des fonctionnalités pour l’Account, et peuvent comprendre :

Type d’information
Pourquoi Stripe a besoin de l’information ?
Si l’exigence est en retard (la « date limite » peut être une date ou un autre type de seuil, tel qu’un certain volume de paiements)
Conséquences que Stripe impose à la date limite si nous ne pouvons pas vérifier les informations à l’aide de documents acceptables, telles que la suspension de certaines fonctionnalités ou l’arrêt des virements sur le solde Stripe de l’Account
Qui doit agir ?

Représentants de l’entreprise

Certaines fonctionnalités peuvent nécessiter la création d’un objet Person pour l’Account avec relationship.representative défini sur true.

En plus de toute conséquence spécifique à la fonctionnalité, si une fonctionnalité présente des exigences en retard, son status devient restricted, avec un status_details.code dont la valeur est requirements_past_due.

L’exemple suivant demande la fonctionnalité stripe_balance.stripe_transfers, qui appartient à la configuration recipient. Il part du principe que l’Account a déjà la configuration recipient.

To see all the requirements for an Account’s requested capabilities, retrieve the Account and specify both requirements and the assigned configuration types in the include parameter.

L’exemple suivant renvoie l’état et les exigences pour les fonctionnalités appartenant à la configuration recipient.

Dans l’exemple de réponse, la fonctionnalité stripe_balance.stripe_transfers a été demandée, mais ses exigences sont en retard. Étant donné que la requête n’a pas demandé les configurations customer ou merchant, elles renvoient des valeurs nulles même si elles sont définies dans l’objet Account.

Capability activation response showing requirements
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "recipient"
  ],
  "configuration": {
    "customer": null,
    "merchant": null,
    "recipient": {
      "capabilities": {
        ...
        "stripe_balance": {
          "payouts": {
            "requested": true,
            "status": "restricted",
            "status_details": [
              {
                "code": "requirements_past_due",
                "resolution": "provide_info"
              }
            ]
          },
          "stripe_transfers": {
            "requested": true,
            "status": "restricted",
            "status_details": [
              {
                "code": "requirements_past_due",
                "resolution": "provide_info"
              }
            ]
          }
        }
      },
      ...
    }
  },
  "contact_email": "furever_contact@example.com",
  "created": "2025-04-01T20:29:43.000Z",
  "dashboard": "full",
  "identity": null,
  "defaults": null,
  "display_name": "Furever",
  "metadata": {},
  "requirements": {
    "collector": "stripe",
    "entries": [
      {
        "awaiting_action_from": "user",
        "description": "identity.business_details.address.country",
        "errors": [],
        "impact": {
          "restricts_capabilities": [
            {
              "capability": "card_payments",
              "configuration": "merchant",
              "deadline": {
                "status": "past_due"
              }
            },
            {
              "capability": "stripe_balance.stripe_transfers",
              "configuration": "recipient",
              "deadline": {
                "status": "past_due"
              }
            },
            {
              "capability": "stripe_balance.payouts",
              "configuration": "recipient",
              "deadline": {
                "status": "past_due"
              }
            }
          ]
        },
        "minimum_deadline": {
          "status": "past_due"
        },
        "reference": null,
        "requested_reasons": [
          {
            "code": "routine_onboarding"
          }
        ]
      },
    ...
    ],
    "summary": {
      "minimum_deadline": {
        "status": "past_due",
        "time": null
      }
    }
  }
}

Les variables suivantes affectent les exigences imposées à un objet Account :

Fonctions demandées
Pays d’origine de l’objet Account
Type d’entité de l’objet Account

L’impact d’une exigence décrit la manière dont les fonctionnalités sont affectées lorsque cette exigence est en retard. Son minimum_deadline.status est l’état d’échéance le plus précoce pour toutes les fonctionnalités répertoriées dans son impact. Pour hiérarchiser votre collecte d’exigences, inspectez le deadline.status pour chaque impact.

La plupart des utilisateurs de Stripe satisfont aux exigences lors de l’inscription du compte. Quel que soit le flux d’inscription que vous utilisez, vous avez le choix entre deux stratégies :

Progressif : Ne collectez que les exigences minimales (c’est-à-dire celles dont l’état est currently_due ou past_due) lors de l’inscription.
En amont : Collectez toutes les exigences lors de l’inscription, quel que soit l’état de leur date limite.

Surveiller les mises à jour des exigences

Les lois et réglementations pouvant changer à tout moment, Stripe met continuellement à jour ses systèmes de conformité et de gestion des risques. Cela peut avoir une incidence sur les exigences relatives aux fonctionnalités de vos comptes connectés. Pour éviter toute interruption de leurs activités, vous devez surveiller en permanence l’état de leurs capacités et de leurs exigences, et mettre en œuvre des processus pour mettre à jour les exigences si nécessaire.

Référencement des objets Accounts v2 dans d’autres requêtes V1

Vous pouvez référencer un ID Account v2 dans d’autres API Stripe dans un paramètre account ou customer_account.

Une requête avec un paramètre customer peut accepter l’ID d’un Account v2, mais vous devez le fournir dans le paramètre customer_account au lieu du paramètre customer. L’objet Account doit avoir la configuration customer.
Une requête avec un paramètre account peut accepter l’ID de n’importe quel Account v2 dans ce paramètre.

Informations pour les utilisateurs d’Accounts v1

Si votre plateforme utilise actuellement Accounts v1 et Customers v1, vous pouvez commencer à utiliser Accounts v2 en complément. Cependant, vous ne pouvez pas utiliser l’API v2 pour gérer les objets Account et Customer créés dans l’API v1. Votre plateforme doit gérer les objets v1 et v2 séparément.

Preview considerations

Accounts v2 allows you to use a single, configurable account for each business on your platform that collects payments directly. The preview release doesn’t support Treasury, Issuing, or payment methods that are in preview. You can still use Treasury, Issuing, or payment methods in preview with Accounts v1.

Enable Accounts v2 for your Connect platform from your Dashboard.