Connect et l’API Accounts v2

En tant que plateforme Connect, vous permettez à vos comptes connectés d’accepter des paiements. Vous pouvez aussi accepter des paiements de vos comptes connectés lorsqu’ils achètent vos produits ou s’abonnent à vos services. Avec l’API Accounts v1, associer ces achats et abonnements à votre compte connecté nécessite un objet Customer distinct que vous devez relier manuellement à l’objet Account du compte connecté.

L’API Accounts v2 vous permet de créer un seul objet Account qui prend en charge toutes les interactions avec votre compte connecté, vous n’avez donc pas besoin de créer et de gérer des objets Customer distincts.

API Accounts v2

L’API Accounts v2 fournit :

• Configurations de compte flexibles : activez ou modifiez les capacités d’un compte connecté et sa compatibilité avec les fonctionnalités Stripe en mettant à jour les configurations de son compte. Chaque capacité est rattachée à une configuration particulière.
• Données d’identité centralisées : lorsque vous ajoutez une configuration à un compte existant 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.

Représenter les comptes connectés en utilisant Accounts v2

Avec l’API Accounts v2, vous pouvez associer une ou plusieurs configurations à un Compte afin d’activer diverses fonctionnalités. Par exemple :

• Attribuez la configuration merchant pour permettre à l’Account d’accepter des paiements. La configuration merchant inclut les fonctionnalités card_payments et stripe_balance.payouts (remplaçant les payouts v1).
• Attribuez la configuration Customer pour débiter le Compte en tant que client. Vous pouvez utiliser un Compte avec la configuration customer à la place d’un objet Client lors de la création d’un abonnement.
• Attribuez la configuration recipient pour permettre à l’Account de recevoir des transferts. La configuration recipient inclut la fonctionnalité stripe_balance.stripe_transfers (remplaçant les transfers v1), nécessaire pour utiliser les paiements indirects.

L’exemple ci-dessous illustre la création d’un Compte via l’API v2. Vous remarquerez que la structure de l’objet Compte n’est pas la même que celle utilisée dans l’API v1.

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-09-30.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": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        },
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        }
    },
    "defaults": {
        "currency": "usd",
        "responsibilities": {
            "fees_collector": "stripe",
            "losses_collector": "stripe"
        },
        "locales": [
            "en-US"
        ]
    },
    "include": [
        "configuration.customer",
        "configuration.merchant",
        "identity",
        "requirements"
    ]
  }'

Avec l’API v1, chaque compte connecté doit disposer d’un objet Account pour accepter des paiements, et d’un objet Customer séparé pour relier cette entreprise aux paiements effectués sur votre plateforme. Comme les objets Accounts v1 et Customers v1 n’ont pas de lien direct, vous devez gérer ces objets indépendamment et conserver un mappage des identifiants Account vers les identifiants Customer.

Créer un compte

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d country=US \
  -d "controller[fees][payer]"=application \
  -d "controller[losses][payments]"=application \
  -d "controller[stripe_dashboard][type]"=express

Créer un client

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Jenny Rosen" \
  --data-urlencode email="jenny.rosen@example.com" \
  -d "metadata[account_id]]"=acct_1234

Utiliser Accounts comme clients

Chaque API qui accepte un paramètre customer prend aussi en charge un paramètre customer_account, vous permettant de passer l’identifiant d’un Compte configuré comme client.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-09-30.preview" \
  -d customer_account=acct_123 \
  -d "payment_method_types[]"=stripe_balance \
  -d confirm=true \
  -d usage=off_session \
  -d "payment_method_data[type]"=stripe_balance

En savoir plus sur l’utilisation des comptes en tant que clients.

Plateformes Connect utilisant Accounts v1 et Customers v1

Stripe prend toujours en charge les API Accounts v1 et Customers v1. Cependant, vous pouvez utiliser l’API Accounts v2 pour gérer les comptes créés avec l’API Accounts v1, y compris pour leur attribuer la configuration Customer.

Considérations

Stripe déconseille de faire coexister les deux versions de l’API Accounts sur le long terme. Continuez d’utiliser les API v1 si votre plateforme :

• Utilise OAuth pour s’authentifier auprès des comptes connectés
• Utilise les virements transfrontaliers