Création de bénéficiaires à l’aide de l’APIVersion bêta publique

Créez un flux de collecte de données permettant à vos bénéficiaires de recueillir les informations relatives au bénéficiaire et au mode de virement, puis transmettez ces informations à Stripe via nos API. Votre entreprise est responsable de toutes les interactions avec vos bénéficiaires et de la collecte de toutes les informations nécessaires pour les vérifier. Nous mettons à jour les exigences de vérification au fur et à mesure de l’évolution des lois et réglementations du monde entier. Prévoyez de revoir et de mettre à jour les exigences d’inscription régulièrement pour éviter les échecs de virement.

Pour créer un bénéficiaire pouvant recevoir des virements, vous devez créer :

• Un bénéficiaire actif avec l’API Accounts v2
• un mode de virement activé avec l’API USBankAccount v2

Créer des formulaires pour collecter des informations

Pour effectuer un virement, vous devez recueillir les informations de votre bénéficiaire. Créez une méthode ou un formulaire permettant à vos bénéficiaires de vous envoyer des informations, puis transmettez ces informations à Stripe à l’aide de l’API.

Les exigences de vérification dépendant des exigences légales et réglementaires, les informations à collecter sont susceptibles d’évoluer. Concevez votre logique d’application de manière à pouvoir ajouter des paramètres supplémentaires à l’avenir.

Créer un bénéficiaire

Utilisez l’API Accounts v2 pour créer votre bénéficiaire. Vous devez fournir les paramètres suivants pour créer l’ID de compte :

Vous devez préciser à l’aide de l’API Accounts v2 les modes de virement que vous comptez utiliser, car certains nécessitent des informations supplémentaires sur votre bénéficiaire avant que nous puissions les activer. Les modes que vous activez à l’aide du paramètre capabilities déterminent les informations que vous devez collecter concernant votre bénéficiaire. Par exemple, configuration.recipient.capabilities.bank_accounts.local pour un bénéficiaire aux États-Unis nécessite que vous fournissiez un numéro de compte et un numéro de routage.

Plusieurs moyens de virement peuvent être activés pour un bénéficiaire. Selon le pays du bénéficiaire, tous les modes de virement ne seront pas disponibles. Consultez la liste complète des moyens de virement disponibles par pays.

Une fois que vous avez ajouté ces champs et les moyens de virement demandés, Stripe détermine les informations supplémentaires requises dans la réponse de l’API que vous devez soumettre pour que le bénéficiaire soit prêt à recevoir des virements. Pour recevoir ces exigences, incluez requirements, configuration.recipient et identity dans le tableau include. Dans le cas contraire, Stripe renverra une réponse nulle, indépendamment des valeurs réelles.

Lorsque vous créez, récupérez ou modifiez un compte, certains champs ne sont renseignés dans la réponse que si vous les spécifiez dans le paramètre include. Les champs que vous ne spécifiez pas seront inclus dans la réponse avec une valeur nulle, indépendamment de leur valeur réelle.

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-03-31.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "country": "us",
        "entity_type": "individual"
    },
    "configuration": {
        "recipient": {
            "capabilities": {
                "bank_accounts": {
                    "local": {
                        "requested": true
                    }
                }
            }
        }
    },
    "include": [
        "identity",
        "configuration.recipient",
        "requirements"
    ]
  }'

Déterminer les champs requis pour activer un bénéficiaire

Utilisez la réponse de l’API Accounts v2 et examinez les requirements.entries pour déterminer quels champs vous devez envoyer à Stripe. Toutes les entries qui ont le champ restricts_capabilities sont indispensables pour que le bénéficiaire accepte les virements.

{
 "id": "acct_1R9UxIQlxdq9VtNU",
 "object": "v2.core.account",
 "applied_configurations": [
   "recipient"
 ],
 "configuration": {
   "customer": null,
   "merchant": null,
   "recipient": {
     "capabilities": {
       "bank_accounts": {
         "local": {
           "requested": true,
           "status": "restricted",
           "status_details": [
             {
               "code": "requirements_past_due",
               "resolution": "provide_info"
             }
           ]
         },
         "wire": null
       },
       "cards": null,

Envoyer les coordonnées du bénéficiaire à Stripe

Une fois que vous avez déterminé les champs supplémentaires que vous devez transmettre, utilisez l’API Accounts v2 pour envoyer les informations requises.

curl -X POST https://api.stripe.com/v2/core/accounts/acct_1234 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-03-31.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "country": "us",
        "entity_type": "individual",
        "individual": {
            "address": {
                "city": "Brothers",
                "country": "US",
                "line1": "27 Fredrick Ave",
                "postal_code": "97712",
                "state": "OR",
                "id_numbers": [
                    {
                        "type": "us_ein",
                        "value": "000000000"
                    }
                ]
            }
        }
    },
    "include": [
        "identity"
    ]
  }'

Confirmer que le bénéficiaire est activé

Utilisez l’API Accounts v2 pour récupérer un compte et examiner le status des fonctionnalités que vous avez demandées. Pour qu’un bénéficiaire reçoive les virements par le mode de virement souhaité, la valeur de status doit être active.

curl -G https://api.stripe.com/v2/core/accounts/acct_1234 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-03-31.preview" \
  -d include=identity \
  -d include="configuration.recipient"

Créer des moyens de virement pour vos bénéficiaires

Utilisez l’API USBankAccount v2 pour envoyer à Stripe les informations relatives à la méthode de virement afin d’effectuer un virement à un bénéficiaire.

Les USBankAccounts peuvent recevoir des virements par virement bancaire ou ACH. Si vous avez l’intention d’envoyer des virements bancaires, indiquez la mention fedwire_routing_number. Des frais supplémentaires s’appliquent. Pour plus d’informations, consultez notre section sur les tarifs.

L’en-tête Stripe-Context de cette requête doit contenir l’ID de compte du bénéficiaire.

curl -X POST https://api.stripe.com/v2/core/vault/us_bank_accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-06-30.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
" \
  --json '{
    "routing_number": "110000000",
    "account_number": "000123456789",
    "fedwire_routing_number": "110000000"
  }'

Vous pouvez également utiliser des cartes de débit comme mode de virement. Cependant, vos bénéficiaires doivent envoyer leurs coordonnées de carte de débit directement à Stripe. Si vous souhaitez activer les virements par carte de débit, utilisez l’API Account Links v2 pour créer un formulaire à partager permettant à vos utilisateurs de soumettre leurs données de carte de débit.

Afficher tous les moyens de virement d’un bénéficiaire

Affichez tous les modes de virement créés pour un bénéficiaire. Appelez l’API Payout Methods v2 et indiquez l’ID du bénéficiaire.

L’en-tête Stripe-Context de cette requête doit contenir l’ID de compte du bénéficiaire.

curl https://api.stripe.com/v2/money_management/payout_methods \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-06-30.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
"

La réponse contient une liste des objets PayoutMethod que possède un bénéficiaire. Utilisez les ID de PayoutMethod pour effectuer un virement à l’aide de l’API OutboundPayments. Consultez la section Envoyer des fonds pour plus de détails.