Migrer votre intégration Connect pour utiliser les propriétés du contrôleur au lieu des types de comptes

Apprenez à utiliser les propriétés du contrôleur de compte au lieu de spécifier des types de compte.

Vous pouvez configurer des comptes connectés à l’aide des propriétés du contrôleur de compte au lieu de définir des comptes Standard, Express ou Custom. Ces propriétés de contrôleur vous permettent de préciser des comportements de compte distincts, tels que l’accès à un Dashboard hébergé par Stripe et si Stripe perçoit des frais sur le compte ou sur la plateforme. Cette modularité permet des options de configuration plus flexibles.

Vous n’avez pas besoin de mettre à jour la version de votre API pour utiliser les propriétés du contrôleur de compte. La migration de votre intégration est facultative. Si vous n’utilisez qu’un seul type de compte connecté et que l’utilisation d’une nouvelle configuration ne vous intéresse pas, vous n’avez pas besoin de mettre votre intégration à jour.

Nous vous recommandons de mettre à jour votre intégration pour profiter d’une modularité accrue et des nouvelles configurations disponibles. Les nouvelles propriétés sont entièrement rétrocompatibles : vous pouvez ainsi migrer votre intégration progressivement tout en continuant de travailler avec les types de compte.

Chaque type de compte correspond à un ensemble de propriétés du contrôleur. Nous définissons automatiquement ces propriétés sur vos comptes connectés existants et sur tous les comptes nouvellement créés avec des types de compte. Lorsque vous mettez votre intégration à jour de façon à ce qu’elle fonctionne avec les propriétés du contrôleur, vous n’avez pas besoin de mettre à jour vos comptes connectés.

Remarque

Vous pouvez commencer à utiliser des fonctionnalités telles que les composants intégrés sans prendre en compte les modifications suggérées dans ce guide.

Avant de commencer

Découvrez comment fonctionnent les propriétés du contrôleur de compte et de quelle manière elles correspondent à vos comptes connectés existants.
Déterminez quelles sont les nouvelles configurations de compte qui conviennent à votre intégration.

La mise à jour de votre intégration implique ce qui suit :

Identifier le code de votre intégration qui référence le type de compte et le mettre à jour pour qu’il référence les propriétés correspondantes du contrôleur.
Mettre à jour votre processus de création de compte pour spécifier les propriétés du contrôleur au lieu du type. Il n’est plus nécessaire de spécifier le type.

Propriétés du contrôleur de compte

Vous pouvez spécifier des valeurs pour les propriétés du contrôleur lorsque vous créez un compte connecté à l’aide de l’API Accounts. Les propriétés non spécifiées sont définies sur une valeur par défaut qui présente les exigences d’intégration les moins complexes.

Si vous créez une nouvelle intégration, vous pouvez obtenir une recommandation de configuration en effectuant l’inscription de la plateforme Connect.

Propriété	Valeur par défaut	Description
controller.losses.payments	`stripe`	Valeurs possibles : `application` : votre plateforme assume la responsabilité des soldes négatifs et gère les risques liés au crédit et à la fraude sur le compte connecté. Vous devez pour cela prendre connaissance et accepter vos responsabilités dans le Dashboard `stripe` : Stripe est responsable lorsque ce compte ne peut pas rembourser des soldes négatifs causés par des paiements. Votre plateforme reste responsable de tout solde négatif sur votre compte de plateforme.
controller.fees.payer	`account`	Valeurs possibles : `account` : le compte connecté paie tous les frais Stripe directement à Stripe, y compris les frais de traitement des paiements `application` : la plateforme Connect prend en charge tous les frais Stripe, y compris les frais de traitement des paiements `application_custom` : le compte a été créé avec type=custom `application_express` : le compte a été créé avec type=express Lorsque vous créez un compte, vous pouvez uniquement spécifier `application` ou `account`. `application_express` et `application_custom` ne sont pas des paramètres de création valides. Pour consultez la description complète des frais Stripe, reportez-vous à la documentation sur le comportement en matière de frais.
controller.requirement_collection	`stripe`	Valeurs possibles : `application` : votre plateforme est responsable de la collecte des informations à jour lorsque des exigences doivent être satisfaites ou évoluent `stripe` : Stripe est responsable de la collecte des informations à jour lorsque des exigences doivent être satisfaites ou évoluent La valeur de `application` signifie que votre plateforme peut accéder à l’intégralité des propriétés KYC du compte et attester que le compte a lu et accepté les Conditions d’utilisation du service Stripe via l’API.
controller.stripe_dashboard.type	`full`	Valeurs possibles : `express` : le compte connecté peut accéder au Dashboard Express `full` : le compte connecté peut accéder au Dashboard Stripe complet `none` : le compte n’a ni accès au Dashboard Express ni au Dashboard complet
type	Voir la description	Valeurs possibles : `custom` : le compte a été créé en tant que compte connecté Custom `express` : le compte a été créé en tant que compte connecté Express `standard` : le compte a été créé en tant que compte connecté Standard ou avec des propriétés de contrôleur correspondant aux comptes Standard `none` : le compte a été créé sans valeur de type et ses propriétés de contrôleur ne correspondent à aucun des trois types de compte La spécification du `type` est facultative. Si vous créez un compte en utilisant `type`, vous ne pouvez spécifier que `custom`, `express` ou `standard`. `none` n’est pas un paramètre de création de compte valide.

Correspondance entre les types de comptes et les paramètres du contrôleur

Chacun des trois types de compte est associé à des valeurs dans le hachage controller de v1/accounts qui correspondent au comportement de ce type.

Standard

Si vous créez un compte sans spécifier de propriétés de contrôleur, les valeurs par défaut correspondent au comportement d’un compte Standard. Vous pouvez également créer l’équivalent d’un compte Standard en spécifiant les valeurs qui correspondent au comportement d’un compte Standard.

Ces valeurs correspondent au comportement d’un compte Standard :

losses.payments : stripe
fees.payer : account
requirement_collection : Stripe
stripe_dashboard.type : full

Requête (avec les valeurs par défaut pour toutes les propriétés) :

Réponse :

{
  controller: {
    type: "application",
    is_controller: true,
    losses: {
      payments: "stripe"
    },
    requirement_collection: "stripe",
    fees: {
      payer: "account",
    },
    stripe_dashboard: {
      type: "full"
    }
  },
  type: "standard"
}

Express

Ces valeurs correspondent au comportement d’un compte Express :

losses.payments : application
fees.payer: application (voir note)
requirement_collection : Stripe
stripe_dashboard.type : express

Remarque

Lorsque vous créez un compte Express en utilisant type, la propriété controller.fees.payer est définie sur application_express au lieu d’application. Cette différence indique une variation dans le comportement de facturation des frais de Stripe lorsque que votre plateforme utilise les paiements directs.

Requête :

Réponse :

{
  controller: {
    type: "application",
    is_controller: true,
    losses: {
      payments: "application"
    },
    requirement_collection: "stripe",
    fees: {
      payer: "application",
    },
    stripe_dashboard: {
      type: "express"
    }
  },
  type: "none"
}

Custom

Ces valeurs correspondent au comportement d’un compte Custom :

losses.payments : application
fees.payer: application (voir note)
requirement_collection : application
stripe_dashboard.type : none

Lors de la création d’un compte Custom, vous devez également spécifier le pays du compte et demander les fonctionnalités card_payments et transfers.

Remarque

Lorsque vous créez un compte Custom en utilisant type, la propriété controller.fees.payer est définie sur application_custom au lieu d’application. Cette différence indique une variation dans le comportement de facturation des frais de Stripe lorsque que votre plateforme utilise les paiements directs.

Requête :

Réponse :

{
  controller: {
    type: "application",
    is_controller: true,
    losses: {
      payments: "application"
    },
    requirement_collection: "application",
    fees: {
      payer: "application",
    },
    stripe_dashboard: {
      type: "none"
    }
  },
  type: "none"
}

Migrer le code pour utiliser les propriétés du contrôleur

En plus de mettre à jour votre processus de création de compte pour utiliser les propriétés du contrôleur, mettez votre intégration à jour en examinant votre code et en recherchant des références aux types de compte.

Pour chaque référence à un type de compte, déterminez les propriétés du contrôleur pertinentes et mettez le code à jour en conséquence.

Par exemple, imaginons que votre code comprenne une instruction conditionnelle qui s’applique aux comptes Express et Custom, liée à la responsabilité de votre plateforme à l’égard des soldes négatifs. Mettez à jour cette logique en remplaçant if type == express ou if type == custom par if controller.losses.payments == application.

Si vous créez des comptes connectés qui ne correspondent pas à un type de compte, tenez également compte des propriétés de leur contrôleur lors de la mise à jour de votre code. La logique de gestion de ces comptes peut différer de la logique existante basée sur les types de compte.

Vous pouvez utiliser ce tableau pour identifier les propriétés du contrôleur associées à chaque type de compte :

Type de compte	losses.payments	fees.payer	requirement_collection	stripe_dashboard.type
Custom	`application`	`application_custom`	`application`	`none`
Express	`application`	`application_express`	`stripe`	`express`
Standard	`stripe`	`account`	`stripe`	`full`

Remarque

N’oubliez pas que les comptes Express et Custom ont une valeur différente pour fees.payer que les comptes équivalents créés à l’aide des propriétés du contrôleur. Lorsque vous mettez à jour le code lié à la perception des frais, vous devez tenir compte de cette différence de comportement.

Configurations non prises en charge

Lors de la création de comptes avec des propriétés de contrôleur, les configurations suivantes ne sont pas prises en charge :

controller.requirement_collection = application n’est compatible avec aucune des valeurs suivantes :

controller.losses.payments = stripe
controller.fees.payer = account
controller.stripe_dashboard.type = express
controller.stripe_dashboard.type = full

controller.stripe_dashboard.type = express n’est compatible avec aucune des valeurs suivantes :

controller.losses.payments = stripe
controller.fees.payer = account
controller.requirement_collection = application

controller.stripe_dashboard.type = full n’est compatible avec aucune des valeurs suivantes :

controller.losses.payments = application
controller.fees.payer = application
controller.requirement_collection = application

controller.stripe_dashboard.type = none n’est pas pris en charge lorsque les deux valeurs suivantes sont définies (il est pris en charge lorsqu’une seule d’entre elles est définie) :

controller.requirement_collection = stripe
controller.losses.payments = application