Fonctionnement des comptes financiers Treasury
Lorsque vous activez Stripe Treasury sur votre plateforme, vous pouvez ajouter des objets FinancialAccount
à l’architecture de votre plateforme afin de garantir l’efficacité de la réception, de l’envoi et du stockage des fonds. Une fois que vous avez obtenu un accès à Treasury via l’API, Stripe associe un compte financier au compte de votre plateforme et vous pouvez dès lors créer un compte financier pour chaque compte connecté Custom éligible sur votre plateforme.
Note
Multiple Financial Accounts beta La fonctionnalité bêta Comptes financiers multiples vous permet d’ouvrir plusieurs comptes financiers pour un même compte connecté Custom. Contactez treasury-support@stripe.com pour accéder au mode test de cette fonctionnalité et vous inscrire sur la liste d’attente.
Chaque compte financier possède son propre solde de fonds, distinct du solde du compte auquel il est associé. Par exemple, le propriétaire d’un compte connecté Custom de votre plateforme peut posséder un solde de compte connecté d’un montant de 100 USD et un solde de compte financier de 200 USD. Dans ce cas, son solde total s’élève à 300 USD résultat des soldes de son compte financier et de son compte connecté. Ces deux soldes sont distincts, mais l’API offre la possibilité de transférer des fonds depuis le solde du compte connecté vers le solde du compte financier.
Dans l’API Stripe, les objets FinancialAccount
servent de source et de destination pour les requêtes API de mouvement de fonds. Vous pouvez demander des Features
via l’API pour les affecter aux FinancialAccounts
, ce qui fournira des fonctionnalités supplémentaires aux compte financiers de votre plateforme. Par exemple, pour activer les fonctionnalités de carte de paiement sur un compte financier spécifique, envoyez une requête à l’API avec l’ID du FinancialAccount
pour la fonctionnalité card_issuing
. Pour en savoir plus sur les objets Feature
, consultez la section consacrée aux fonctionnalités des comptes financiers. Pour vérifier les fonctionnalités de compte connecté requises pour chaque Feature
, consultez la section consacrée aux fonctionnalités disponibles de ce guide.
Avant de créer des comptes financiers en mode production dans votre intégration Treasury, nous vous recommandons de créer en premier lieu des comptes financiers de test en mode test . Les comptes financiers en mode test ne peuvent pas recevoir ni envoyer d’argent réel, ne peuvent pas être utilisés en mode production et ne génèrent pas un compte en mode production avec de vraies données de compte et de routage. Ils sont cependant identiques en termes de configuration et de fonctionnalités.
Créer un FinancialAccount
Utilisez POST /v1/treasury/financial_accounts
pour créer des FinancialAccounts
. Spécifiez l’ID du compte connecté comme valeur de l’en-tête Stripe-Account
de l’appel pour associer le FinancialAccount
à un compte connecté. À l’heure actuelle, chaque compte connecté ne peut disposer que d’un seul FinancialAccount
.
Note
Multiple Financial Accounts beta Vous pouvez associer plusieurs comptes financiers à un même compte connecté en fournissant le même ID de compte connecté dans l’en-tête Stripe-Account
. Par défaut, vous pouvez associer un maximum de 10 comptes financiers à chaque compte connecté (les comptes financiers clôturés ne comptent pas dans cette limite). Si vous avez besoin d’un seuil plus élevé, contactez-nous à l’adresse treasury-support@stripe.com.
Le code JSON suivant définit la structure de l’objet FinancialAccount
:
En règle générale, vous demandez les fonctionnalités pour votre compte financier en même temps que vous envoyez une requête à l’API pour créer le compte. Quelles que soient les Features
demandées, la fonctionnalité treasury
doit être activée pour le compte. Si vous n’êtes pas sûr que le compte connecté possède cette fonctionnalité, utilisez GET /v1/accounts/{{CONNECTED_ACCOUNT_ID}}
pour vous en assurer : la valeur treasury
du hachage capabilities
du compte doit être définie sur active
.
… "capabilities": { "card_issuing": "active", "card_payments": "active", "transfers": "active", "treasury": "active", "us_bank_account_ach_payments": "active" }, …
Si vous souhaitez émettre des cartes associées au solde du compte financier, vous devez également activer la fonctionnalité Issuing (card_issuing
) pour les comptes connectés de votre plateforme. Vous ne pouvez pas demander cette fonctionnalité pour un compte financier tant qu’elle n’a pas été activée pour le compte connecté correspondant. Le cas échéant, toute tentative de créer un FinancialAccount
en demandant la fonctionnalité card_issuing
entraîne une erreur.
Note
Multiple Financial Account beta Vous pouvez définir le champ nickname
d’un objet FinancialAccount
pour affecter un nom personnalisé au compte financier. Vous pouvez utiliser des pseudonymes pour créer des identifiants uniques, ce qui peut être utile lorsque vous travaillez avec plusieurs comptes financiers pour un même compte connecté. Pour que les pseudonymes soient valides, ils doivent respecter les critères suivants :
- Deux comptes financiers associés à un même compte connecté ne peuvent pas utiliser le même pseudo
- Le pseudo doit être une chaîne non vide
- Le pseudo doit contenir moins de 250 caractères
Si vous ne fournissez pas de pseudo lors de la création du compte, le champ pseudo sera vide et renverra la valeur null
. Vous pouvez modifier les pseudos après la création d’un FinancialAccount
.
La requête suivante permet de créer un compte financier associé au compte connecté avec l’ID spécifié dans l’en-tête Stripe-Account
.
La réponse renvoie un objet FinancialAccount
, qui confirme la création du compte financier.
{ "object": "treasury.financial_account", "created": 1612927106, "id": "fa_123", "country": "US", "supported_currencies": ["usd"], "active_features": [ "card_issuing", ], // Features that require activation enter a pending state before activating "pending_features": [ "deposit_insurance", "financial_addresses.aba", "inbound_transfers.ach", "intra_stripe_flows", "outbound_payments.ach", "outbound_payments.us_domestic_wire", "outbound_transfers.ach", "outbound_transfers.us_domestic_wire" ], "restricted_features": [], // A FinancialAddress is not added until the financial_addresses.aba feature has been activated "financial_addresses": [], "livemode": true, "status": "open", ... }
Mettre à jour un FinancialAccount
Utilisez POST /v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}
pour mettre à jour le FinancialAccount
avec l’ID associé. Spécifiez l’ID du compte connecté comme valeur de l’en-tête Stripe-Account
. L’exemple suivant illustre la mise à jour des métadonnées du FinancialAccount.
Récupérer un FinancialAccount et un numéro de compte
Utilisez GET /v1/treasury/financial_accounts/{{FINANCIALACCOUNT_ID}}
pour récupérer le FinancialAccount
avec l’ID associé. Spécifiez l’ID du compte connecté comme valeur de l’en-tête Stripe-Account
.
Par défaut, le numéro de compte d’un compte financier n’est pas inclus dans la réponse. Intégrez le champ financial_addresses.aba.account_number
au tableau expand
pour récupérer le numéro de compte.
Sauf échec de l’opération, la réponse renvoie l’objet FinancialAccount
avec ou sans le numéro de compte, selon que vous l’ayez ajouté ou non au tableau expand
.
Pour en savoir plus sur le paramètre expand
, consultez la page Développement des réponses.
Récapitulatif des fonctionnalités
L’objet FinancialAccount
contient un récapitulatif de l’état de toutes ses Features
, sous la forme de trois tableaux : active_features
, pending_features
et restricted_features
.
{ "object": "treasury.financial_account", "id": "fa_987", "status": "open", ... "active_features": ["card_issuing"], "pending_features": ["financial_addresses.aba"], "restricted_features": ["outbound_transfers.ach"], }
Ces tableaux sont un moyen efficace de voir :
- Toutes les fonctionnalités inactives (
pending_features
ourestricted_features
ne sont pas vides). - Les fonctionnalités actives (
active_features
contient les fonctionnalités spécifiques). - Les fonctionnalités limitées qui requièrent une action (
restricted_features
n’est pas vide).
Pour en savoir plus, consultez la page Fonctionnalités des comptes financiers.
Clôturer un FinancialAccount
Vous pouvez clôturer définitivement un compte financier s’il remplit les conditions suivantes :
- Son solde est nul.
- Il n’y a pas de transferts entrants en attente.
- Toutes les cartes Issuing associées sont annulées.
Avertissement
Vous ne pouvez pas rouvrir des comptes financiers après les avoir clôturés.
Si vous souhaitez clôturer un compte financier, envoyez un e-mail à l’adresse treasury-support@stripe.com et fournissez l’ID du FinancialAccount
que vous voulez clôturer ainsi que le motif de cette clôture. Vous devez prévenir vos utilisateurs de la clôture du compte, conformément aux instructions de conformité pour Treasury.
La clôture d’un compte financier n’a aucun impact sur la conservation de données pour des objets associés, tels que Transactions
.
Vous ne pouvez pas ouvrir un nouveau compte financier pour un compte connecté si vous avez déjà clôturé un compte financier associé à ce même compte connecté. Vous devez ouvrir un nouveau compte connecté pour créer un nouveau compte financier.
Note
Multiple Financial Account beta La fonctionnalité bêta Comptes financiers multiples vous permet de clôturer un compte financier et d’en ouvrir un nouveau associé au même compte connecté sans avoir à ouvrir un nouveau compte connecté.
Clôture du FinancialAccount via l’API Beta
Une fois que vous avez accès au programme bêta, utilisez POST/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close
pour clôturer le compte financier avec l’ID associé. Spécifiez l’ID du compte connecté associé en tant que valeur d’en-tête.
curl https://api.stripe.com/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close \ -u
: \ -X "POST" \ -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}"sk_test_4eC39HqLyjWDarjtT1zdp7dc
La réponse renvoie l’objet FinancialAccount
dont le status
est défini sur closed
en guise de confirmation de la clôture.
{ "id": "{{FINANCIAL_ACCOUNT_ID}}", "object": "treasury.financial_account", "status": "closed", "status_details": { "closed": { "reasons": ["closed_by_platform"] } }, "active_features": [], "pending_features": [], "restricted_features": ["financial_addresses.aba"], ... }
Gestion des transactions sur les comptes clôturés
Dans de rares cas, les comptes financiers peuvent recevoir des crédits ou des débits sur des comptes clôturés que Stripe ne peut pas reverser automatiquement. En tant que propriétaire de la plateforme, la responsabilité des soldes négatifs encourus après la clôture d’un compte vous incombe. Le service d’assistance de Stripe travaille avec vous pour vous aider à restituer les fonds restants dus au marchand ou au fournisseur de services et à rectifier les comptes clôturés ayant un solde négatif.
Webhooks
Vous pouvez créer des comptes financiers même si toutes les conditions d’inscription n’ont pas encore été remplies. Dans ce cas, le compte est activé de manière asynchrone, puis déclenche un webhook treasury.financial_account.features_status_updated
. Une vue mise à jour présente les fonctionnalités encore limitées en raison des conditions d’inscription qui n’ont pas été satisfaites.
account.updated
- Lors de la demande de nouvelles fonctionnalités, la plateforme peut recevoir un webhook
account.updated
indiquant que le hash requirements a été modifié et que certains nouveaux champs affichent désormais un étatpending_verification
.
- Lors de la demande de nouvelles fonctionnalités, la plateforme peut recevoir un webhook
treasury.financial_account.created
- Déclenché lors de la création d’un FinancialAccount.
treasury.financial_account.closed
- Notifie le passage du FinancialAccount de niveau supérieur à l’état closed.
treasury.financial_account.features_status_updated
- Indique qu’une ou plusieurs fonctionnalités ont changé d’état. Les tableaux
active_features
,pending_features
ourestricted_features
reflètent ce changement.
- Indique qu’une ou plusieurs fonctionnalités ont changé d’état. Les tableaux