Accéder directement au contenu
Créez un compte ou connecter-vous
Logo de la documentation Stripe
/
Créez un compteConnectez-vous

Créer un bénéficiaire pour Global Payouts avec l'APIVersion bêta publique

Découvrez comment intégrer des bénéficiaires pour Global Payouts à l'aide de l'API Stripe.

Créez un flux de recouvrement permettant à vos bénéficiaires de collecter les informations relatives aux bénéficiaires et aux modes de virement, puis transmettez ces informations à Stripe via nos API.

Considérations

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. Stripe met à jour les exigences en matière de vérification des bénéficiaires à mesure que les lois et réglementations évoluent à travers le monde.

Lorsque vous créez une intégration de paiement, réfléchissez à la manière de gérer :

  • L’examen régulier des modifications apportées aux exigences légales et réglementaires
  • La mise à jour de la logique de votre application en réponse à ces changements

Prévoyez de vérifier et de mettre à jour régulièrement les exigences en matière d’onboarding pour éviter les échecs de virement.

Créez un bénéficiaire

Lorsque vous utilisez un formulaire pour collecter les informations relatives aux bénéficiaires des paiements, utilisez l’API Accounts v2 pour créer un bénéficiaire. Vous devez fournir les paramètres suivants pour créer l’ID du compte :

Informations requisesParamètre
Pays du bénéficiaireidentity.country
Type d’entreprise bénéficiaireidentity.entity_type
Adresse e-mail du bénéficiairecontact_email
Nom d’affichage du compte. Il apparaît dans le Dashboard Stripe et sur toutes les factures que vous envoyez au compte.display_name
Moyens de virement que vous souhaitez activerconfiguration.recipient.capabilities

Version bêta publique

Les virements transfrontaliers pour les expéditeurs américains sont disponibles en version bêta publique.

Vous devez spécifier les moyens de virement souhaités avec l’API Accounts v2, car certains moyens nécessitent des informations supplémentaires sur votre destinataire avant de pouvoir les activer. Les moyens que vous activez à l’aide du paramètre capabilities déterminent les informations que vous devez collecter pour votre destinataire. Par exemple, le paramètre configuration.recipient.bank_accounts.local pour un destinataire américain vous oblige à fournir un numéro de compte et un numéro de routage.

Méthode de virementParamètre de l’APIDescription
Banque localeconfiguration.recipient.capabilities.bank_accounts.localPermet au compte de recevoir des OutboundPayments sur les réseaux bancaires locaux, tels que ACH ou FPS.
Virement bancaireconfiguration.recipient.capabilities.bank_accounts.wirePermet au compte de recevoir des OutboundPayments sur des réseaux de virement bancaire, tels que Fedwire ou SWIFT.
Cartes bancairesconfiguration.recipient.capabilities.cardsPermet au compte de recevoir des OutboundPayments sur des réseaux de cartes de débit, tels que Visa Direct ou Mastercard Send.

Plusieurs moyens de virement peuvent être activés pour un bénéficiaire. Tous les moyens de virement ne sont pas disponibles pour les bénéficiaires dans tous les pays. Consultez la liste complète des moyens de virement disponibles par pays.

Après avoir ajouté ces champs et les méthodes de virement demandées, 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 reçoive les virements. Pour recevoir ces exigences, incluez requirements, configuration.recipient et identity dans le tableau include. Sinon, Stripe renvoie une réponse nulle, quelle que soit leur valeur réelle.

Lorsque vous créez, récupérez ou mettez à jour un compte, certains champs ne sont renseignés dans la réponse que si vous les spécifiez dans le paramètre include. Pour tout champ non spécifié, la réponse inclut une valeur nulle, indépendamment de sa valeur réelle.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-01-28.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 obligatoires pour activer un bénéficiaire

Utilisez la réponse de l’API Accounts v2 pour examiner les requirements.entries afin de déterminer les champs spécifiques que vous devez soumettre à Stripe. Toutes les entries qui comportent le champ restricts_capabilities sont nécessaires pour que le bénéficiaire accepte les virements.

{
 "id": "{{CONNECTED_ACCOUNT_ID}}",
 "object": "v2.core.account",
 "applied_configurations": [
   "recipient"
 ],
 "configuration": {
   "customer": null,
   "merchant": null,
   "recipient": {

Envoyer les informations sur le bénéficiaire à Stripe

Après avoir déterminé les champs supplémentaires que vous devez soumettre, utilisez l’API Accounts v2 pour soumettre les informations requises. Utilisez l’ID de la réponse ci-dessus dans l’URI.

Command Line
cURL
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-01-28.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "country": "us",
        "entity_type": "individual",
        "individual": {
            "given_name": "Jenny",
            "surname": "Rosen",
            "address": {
                "city": "Brothers",
                "country": "US",
                "line1": "27 Fredrick Ave",
                "postal_code": "97712",
                "state": "OR"
            }
        }
    },
    "include": [
        "identity"
    ]
  }'

Confirmer que le bénéficiaire est activé

Utilisez l’API Accounts v2 pour récupérer un compte et inspecter le status des fonctionnalités que vous avez demandées. Le status doit être active pour qu’un bénéficiaire puisse recevoir des virements selon le moyen de virement spécifié.

Command Line
cURL
No results
curl -G https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-01-28.preview" \
  -d "include[0]"="configuration.recipient"

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

Utilisez l’API OutboundSetupIntents v2 pour soumettre les détails du moyen de virement à Stripe afin d’activer un virement à un bénéficiaire.

L’en-tête Stripe-Context de cette requête doit correspondre à l’identifiant du compte du destinataire.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/money_management/outbound_setup_intents \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-01-28.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
" \
  --json '{
    "payout_method_data": {
        "type": "bank_account",
        "bank_account": {
            "country": "FR",
            "account_number": "FR76300060000112345678901234"
        }
    }
  }'

Remarque

La réponse de l’OutboundSetupIntent contient le moyen de virement imbriqué en son sein. Lorsque vous effectuez un OutboundPayment, utilisez l’ID du moyen de virement de la réponse (par exemple, frba_test_...), et non l’ID de l’OutboundSetupIntent (osi_test_...).

Pour envoyer des virements par transfert bancaire, utilisez l’API USBankAccount v2 afin d’ajouter le fedwire_acheminement_number à la méthode de virement. Des frais supplémentaires s’appliquent. Consultez les tarifs pour en savoir plus.

You can also use debit cards as a payout method. However, your recipients must submit their debit card information directly to Stripe. If you’re interested in enabling payouts by debit cards, use the Account Links v2 API to create a shareable form for your user to submit their debit card credentials.

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

Affichez tous les moyens de virement créés pour un bénéficiaire. Appelez l’API Virement Methods v2 et fournissez l’ID du bénéficiaire.

L’en-tête Stripe-Context de cette requête doit correspondre à l’identifiant du compte du destinataire.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v2/money_management/payout_methods \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-01-28.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
"

La réponse contient une liste d’objets PayoutMethod détenus par un destinataire. Utilisez les ID de PayoutMethod pour effectuer un virement à l’aide de l’API OutboundPayments. Pour en savoir plus, consultez la page Envoyer des fonds.