Fonctionnement des comptes financiers Treasury

Une fois que vous avez obtenu l’accès API à Treasury, Stripe attache un compte financier au compte de votre plateforme et vous permet de provisionner des comptes financiers pour les comptes connectés admissibles sur votre plateforme. 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é 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éparti entre les 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 à l’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 comptes 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 pour votre intégration Treasury, nous vous recommandons de créer d’abord des comptes financiers de test dans un environnement de test. Les comptes financiers de test ne peuvent pas recevoir ni envoyer de fonds réels, ne peuvent pas être utilisés en mode production et ne génèrent pas de compte de 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. Ajoutez l’ID du compte connecté comme valeur de l’en-tête Stripe-Account de l’appel pour associer le FinancialAccount à un compte connecté.

Votre compte de plateforme et vos comptes connectés peuvent être associés à plusieurs comptes financiers. Vous pouvez créer un autre compte financier sur votre compte connecté en renseignant l’ID du compte connecté comme valeur de l’en-tête Stripe-Account. Vous pouvez associer un maximum de 3 comptes financiers à un seul compte connecté (les comptes financiers clôturés ne contribuent pas à la limite). La même limite s’applique au nombre de comptes financiers rattachés au compte de la plateforme. Si vous avez besoin d’un seuil de compte plus élevé, contactez treasury-support@stripe.com.

Le code JSON suivant définit la structure de l’objet FinancialAccount :

{
  "object": "treasury.financial_account",
  "created": 1612927106,
  "id": "fa_123",
  "country": "US",
  "supported_currencies": ["usd"],
  // Arrays of active, pending and restricted features summarize the status of all requested features
  "active_features": ["financial_addresses.aba", "deposit_insurance"],
  "pending_features": ["inbound_transfers.ach"],
  "restricted_features": ["intra_stripe_flows", "outbound_payments.ach", "outbound_payments.us_domestic_wire"],
  "balance": {
    "cash": {"usd": 9000},
    "inbound_pending": {"usd": 0},
    "outbound_pending": {"usd": 1000}
  },
  // The FinancialAccount gains a FinancialAddress once the `financial_addresses.aba` feature is active. For more information, see "Activating features"
  "financial_addresses": [
    {
      "type": "aba",
      "supported_networks": ["ach", "domestic_wire_us"],
      "aba": {
        "account_number_last4": "7890",
        // Use the expand[] parameter to view the `account_number` field hidden by default
        "account_number": "1234567890",
        "routing_number": "000000001",
        "bank_name": "Goldman Sachs"
      }
    }
  ],
  "livemode": true,
  // Financial accounts begin in the "open" state, but can be closed
  // `status_details.closed` is populated once a financial account is closed
  "status": "open",
  "status_details": {
    "closed": {
      // List of one or more reasons why the FinancialAccount was closed:
      // - account_rejected
      // - closed_by_platform
      // - other
      "reasons": [],
    }
  },
  // User-defined metadata
  "metadata": {},
  "nickname": {},
  // Restrictions that the platform can apply to the FinancialAccount
  "platform_restrictions": {
    "inbound_flows": "unrestricted",
    "outbound_flows": "restricted"
  },
}

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.

Le champ nickname d’un objet FinancialAccount permet de définir un nom personnalisé pour le compte financier. Vous pouvez utiliser des pseudonymes pour mieux identifier les différents comptes, notamment si plusieurs comptes financiers sont regroupés sous un même compte connecté. Pour être valide, un pseudonyme doit respecter les règles suivantes :

• 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 du 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.

curl https://api.stripe.com/v1/treasury/financial_accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "supported_currencies[]"=usd \
  -d nickname={{OPTIONAL_NICKNAME}} \
  -d "features[card_issuing][requested]"=true \
  -d "features[deposit_insurance][requested]"=true \
  -d "features[financial_addresses][aba][requested]"=true \
  -d "features[inbound_transfers][ach][requested]"=true \
  -d "features[intra_stripe_flows][requested]"=true \
  -d "features[outbound_payments][ach][requested]"=true \
  -d "features[outbound_payments][us_domestic_wire][requested]"=true \
  -d "features[outbound_transfers][ach][requested]"=true \
  -d "features[outbound_transfers][us_domestic_wire][requested]"=true

La réponse renvoie un objet FinancialAccount, qui confirme la création du compte financier.

{
  "object": "treasury.financial_account",
  "created": 1612927106,
  "id": "{{FINANCIAL_ACCOUNT_ID}}",
  "country": "US",
  "supported_currencies": ["usd"],
  "active_features": [
    "card_issuing",
  ],
  // Features that require activation enter a pending state before activating

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.

curl https://api.stripe.com/v1/treasury/financial_accounts/
{{FINANCIAL_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "metadata[key]"=value

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.

curl https://api.stripe.com/v1/treasury/financial_accounts/
{{FINANCIAL_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

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.

curl -G https://api.stripe.com/v1/treasury/financial_accounts/
{{FINANCIAL_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "expand[]"="financial_addresses.aba.account_number"

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.

{
  "id": {{FINANCIAL_ACCOUNT_ID}},
  ...
  "financial_addresses": [
    {
      "aba": {
        "account_holder_name": "jenny",
        "account_number": "4242424242420239",
        "account_number_last4": "0239",
        "bank_name": "Stripe Test Bank",
        "routing_number": "000000001"
      },
      ...
    }
  ],
  ...
}

Pour plus d’informations sur le paramètre expand, consultez notre section sur le 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 :

• Fonctionnalités inactives (incluses dans pending_features ou restricted_features)
• Fonctionnalités actives (incluses dans active_features)
• Fonctionnalités limitées qui requièrent une action (incluses dans restricted_features).

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 :

• Il n’y a pas de transferts entrants en attente.
• Toutes les cartes Issuing associées sont annulées.
• Le solde du compte est nul et il n’y a pas eu d’activité sur le compte au cours des 75 derniers jours. Par ailleurs, vous pouvez indiquer un autre compte financier ou un compte externe vers lequel transférer les débits et les crédits entrants.

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.

Clôture d’un FinancialAccount à l’aide de l’API

Vous pouvez utiliser POST/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close pour clôturer le compte financier avec l’ID associé. Ajoutez 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 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST" \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}"

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 Support de Stripe vous accompagne dans la restitution des fonds restants dus au marchand ou au fournisseur de services et dans la résolution des problèmes liés aux comptes clôturés ayant un solde négatif. Lorsque vous configurez des paramètres de transfert lors de la clôture d’un compte financier, Stripe peut automatiquement transférer les débits et les crédits vers le compte sélectionné.

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 état pending_verification.
• 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 ou restricted_features reflètent ce changement.