Fonctionnement des comptes financiers

Une fois que vous avez obtenu l’accès à l’API Financial Accounts pour les plateformes, Stripe associe un compte financier au compte de votre plateforme et vous permet d’approvisionner les comptes financiers des 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é sur votre plateforme peut avoir un solde de 100 USD sur le compte connecté et un solde de 200 USD sur le compte financier. Dans ce scénario, le propriétaire du compte connecté a une somme de 300 USD répartie entre le solde de son compte financier et le solde du compte connecté. Ces deux soldes restent distincts, mais l’API permet de transférer des fonds du solde du compte connecté vers le solde du compte financier.

Dans l’API Stripe, les objets FinancialAccount servent de source et de destination aux requêtes de l’API de transfert de fonds. Vous demandez des fonctionnalités via l’API à affecter aux FinancialAccounts qui fournissent 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, vous envoyez une requête API avec l’ID FinancialAccount pour la fonctionnalité card_issuing. Pour en savoir plus sur les objets fonctionnalités, consultez la section des fonctionnalités du Compte financier. Consultez la section fonctionnalités disponibles de ce guide pour vérifier les capacités requises des comptes connectés pour chaque fonctionnalité.

Avant de créer des comptes financiers en mode production pour votre intégration de Financial Accounts pour les plateformes, nous vous recommandons de créer en premier lieu des comptes financiers de test dans un environnement de 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 d’acheminement et de compte. 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 également les fonctionnalités du compte financier lorsque vous effectuez la requête à l’API pour créer le compte. Quelles que soient les fonctionnalités que vous demandez, la fonctionnalité trésorerie doit être activée pour le compte connecté. Si vous ne savez pas si le compte connecté dispose de cette fonctionnalité, utilisez GET /v1/accounts/{{CONNECTED_ACCOUNT_ID}} pour le vérifier. Le hachage des fonctionnalités du compte doit avoir la valeur trésorerie 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 pseudo sera vide et renverra nul. Vous pouvez mettre à jour 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 section de fonctionnalités du compte financier.

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}}"

curl -X POST https://api.stripe.com/v1/treasury/financial_accounts/
{{FINANCIAL_ACCOUNT_ID}}
/close \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_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é.

Indiquez les paramètres de transfert lorsque vous clôturez le compte financier. L’exemple suivant utilise un compte bancaire externe comme compte de transfert.

curl https://api.stripe.com/v1/treasury/financial_accounts/
{{FINANCIAL_ACCOUNT_ID}}
/close \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "forwarding_settings[type]"=payment_method \
  -d "forwarding_settings[payment_method]"=
"{{PAYMENT_METHOD_ID}}"

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.