# Créer un bénéficiaire pour Global Payouts avec l'API 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 du bénéficiaire des virements, utilisez l’[API Accounts v2](https://docs.stripe.com/api/v2/core/accounts/create.md?api-version=preview) pour créer un destinataire. Vous devez fournir les paramètres suivants pour créer l’identifiant du `Account` : | Informations requises | Paramètre | | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | Pays du bénéficiaire | `identity.country` | | Type d’entreprise bénéficiaire | `identity.entity_type` | | Adresse e-mail du bénéficiaire | `contact_email` | | Nom d’affichage du `Account`. Il apparaît dans le Stripe Dashboard et sur toutes les factures que vous envoyez au `Account`. | `display_name` | | Moyens de virement que vous souhaitez activer | `configuration.recipient.capabilities` | > Les virements transfrontaliers pour les expéditeurs américains sont disponibles en version bêta publique. Vous devez préciser les types de méthodes de virement souhaités en [demandant les capacités correspondantes](https://docs.stripe.com/connect/account-capabilities.md?accounts-namespace=v2) lors de la [création du Account](https://docs.stripe.com/api/v2/core/accounts/create.md?api-version=preview#v2_create_accounts-configuration-recipient-capabilities). | Méthode de virement | Paramètre de l’API | Description | | ------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Banque locale | `configuration.recipient.capabilities.bank_accounts.local` | Permet au `Account` de recevoir des `OutboundPayments` via les réseaux bancaires locaux, tels qu’ACH ou FPS. | | Virement bancaire | `configuration.recipient.capabilities.bank_accounts.wire` | Permet au `Account` de recevoir des `OutboundPayments` via les réseaux de virements, tels que Fedwire ou SWIFT. | | Cartes bancaires | `configuration.recipient.capabilities.cards` | Permet au `Account` de recevoir des `OutboundPayments` via les réseaux de cartes de débit, tels que Visa Direct ou Mastercard Send. | Un bénéficiaire peut avoir plusieurs types de méthodes de virement activés. Tous les types de méthodes de virement ne sont pas disponibles pour les bénéficiaires dans tous les pays. Consultez la liste complète des [méthodes de virement disponibles par pays](https://docs.stripe.com/global-payouts/recipient-creation-options.md#requirements-for-supported-recipient-countries). Certaines capacités nécessitent des informations supplémentaires concernant votre bénéficiaire. Par exemple, `configuration.recipient.capabilities.bank_accounts.local` pour un bénéficiaire aux États-Unis exige la transmission d’un numéro de compte et d’un code de routage. Après avoir demandé des capacités de méthodes de virement, Stripe détermine quelles informations supplémentaires vous devez fournir pour les activer et peut les indiquer dans la réponse de l’API. Pour recevoir ces exigences dans la réponse, incluez `exigences`, `configuration.recipient` et `identité` dans le tableau `inclusion`. Sinon, Stripe renvoie une valeur nulle pour ces propriétés, quelles que soient leurs valeurs réelles. ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.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 Pour identifier les exigences spécifiques que vous devez fournir, examinez le tableau [requirements.entries](https://docs.stripe.com/api/v2/core/accounts/create.md?api-version=preview#v2_create_accounts-response-requirements-entries) dans la réponse de l’API Accounts. Pour que le bénéficiaire puisse recevoir des virements, vous devez fournir toutes les exigences comportant la propriété `restricts_capabilities`. ```json { "id": "{{CONNECTED_ACCOUNT_ID}}", "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, "instant": null }, "cards": null, "stripe_balance": null }, "default_outbound_destination": null } }, "contact_email": "jenny.rosen@stripe.com", "created": "2025-04-02T17:20:00.000Z", "dashboard": null, "identity": { "attestations": { "directorship_declaration": null, "ownership_declaration": null, "persons_provided": { "directors": null, "executives": null, "owners": null, "ownership_exemption_reason": null }, "terms_of_service": { "account": null } }, "business_details": null, "country": "US", "entity_type": "individual", "individual": null }, "defaults": null, "display_name": "Jenny Rosen", "metadata": {}, "requirements": { "collector": "stripe", "entries": [ { "awaiting_action_from": "user", "description": "identity.individual.given_name", "errors": [], "impact": {"restricts_capabilities": [ { "capability": "bank_accounts.local", "configuration": "recipient", "deadline": { "status": "past_due" } } ], "restricts_payouts": null }, "minimum_deadline": { "status": "past_due" }, "reference": null, "requested_reasons": [ { "code": "routine_onboarding" } ] }, { "awaiting_action_from": "user", "description": "identity.individual.surname", "errors": [], "impact": { "restricts_capabilities": [ { "capability": "bank_accounts.local", "configuration": "recipient", "deadline": { "status": "past_due" } } ], "restricts_payouts": null }, "minimum_deadline": { "status": "past_due" }, "reference": null, "requested_reasons": [ { "code": "routine_onboarding" } ] } ], "summary": { "minimum_deadline": { "status": "past_due", "time": null } } } } ``` ## Envoyer les informations sur le bénéficiaire à Stripe Après avoir collecté les informations requises, utilisez l’[API Accounts](https://docs.stripe.com/api/v2/core/accounts/update.md?api-version=preview) pour les transmettre. ```curl curl -X POST https://api.stripe.com/v2/core/accounts/{{CONNECTEDACCOUNT_ID}} \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.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é Récupérez le [Account](https://docs.stripe.com/api/v2/core/accounts/retrieve.md?api-version=preview) et examinez l’`état` des capacités que vous avez demandées. L’`état` d’une capacité de méthode de virement doit être `active` pour que le bénéficiaire puisse recevoir des virements via cette méthode. ```curl curl -G https://api.stripe.com/v2/core/accounts/{{CONNECTEDACCOUNT_ID}} \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ -d "include[0]=configuration.recipient" ``` ## Créer des moyens de virement pour vos bénéficiaires Après avoir activé une fonctionnalité de méthode de virement, utilisez l’[API Outbound Setup Intents](https://docs.stripe.com/api/v2/money-management/outbound-setup-intents/create.md?api-version=preview) pour créer le `PayoutMethod` réel du bénéficiaire. L’en-tête Stripe-Context de cette requête doit correspondre à l’identifiant du compte du destinataire. ```curl curl -X POST https://api.stripe.com/v2/money_management/outbound_setup_intents \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ -H "Stripe-Context: {{CONTEXT_ID}}" \ --json '{ "payout_method_data": { "type": "bank_account", "bank_account": { "country": "FR", "account_number": "FR76300060000112345678901234" } } }' ``` > La réponse de l’`OutboundSetupIntent` contient le [PayoutMethod](https://docs.stripe.com/api/v2/money-management/outbound-setup-intents/create.md?api-version=preview#v2_create_outbound_setup_intents-response-payout_method). Lorsque vous effectuez un `OutboundPayment`, utilisez l’identifiant du `PayoutMethod` (par exemple `frba_test_…`), et non l’identifiant de l’`OutboundSetupIntent` (`osi_test_…`). Pour envoyer des virements via un virement bancaire, utilisez l’API [US Bank Accounts](https://docs.stripe.com/api/v2/core/vault/us-bank-accounts/update.md?api-version=preview) afin d’ajouter le `fedwire_routing_number` au `PayoutMethod`. Des frais supplémentaires s’appliquent. Consultez la [page de tarification](https://docs.stripe.com/global-payouts/pricing.md) pour plus de détails. Vous pouvez également utiliser les cartes de débit comme méthode de virement. Toutefois, vos bénéficiaires doivent transmettre leurs informations de carte de débit directement à Stripe. Si vous souhaitez activer les virements vers des cartes de débit, utilisez l’[API Account Links](https://docs.stripe.com/api/v2/core/account-links.md) pour créer un formulaire partageable permettant à votre utilisateur de fournir ses informations de carte. ## Afficher tous les moyens de virement d’un bénéficiaire Utilisez l’API Payout Methods pour [récupérer les PayoutMethods d’un bénéficiaire](https://docs.stripe.com/api/v2/money-management/payout-methods/list.md?api-version=preview). L’en-tête Stripe-Context de cette requête doit correspondre à l’identifiant du `Account` du bénéficiaire. ```curl curl https://api.stripe.com/v2/money_management/payout_methods \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ -H "Stripe-Context: {{CONTEXT_ID}}" ``` La réponse contient une liste d’objets `PayoutMethod` associés au bénéficiaire. Utilisez un identifiant de `PayoutMethod` pour effectuer un virement à l’aide de l’[API Outbound Payments](https://docs.stripe.com/api/v2/money-management/outbound-payments/create.md?api-version=preview). Consultez la page [Envoyer de l’argent](https://docs.stripe.com/global-payouts/send-money.md) pour plus de détails.