# Fonctionnement des soldes et des transactions Pour comprendre les soldes des comptes financiers et les effets de transactions sur ceux-ci. Les [comptes financiers](https://docs.stripe.com/financial-accounts/connect/account-management/financial-accounts.md) présentent un solde distinct du solde du compte auquel ils sont associés (compte de la plateforme ou compte connecté). Les objets `Balance` recensent le montant des fonds d’un compte financier et leur état de disponibilité. Les objets `Transaction` et `TransactionEntry` permettent de débiter ou de créditer des fonds sur ce solde. ## Soldes Un compte financier présente un solde de fonds. Toutefois, le montant total du solde n’est pas toujours disponible pour les dépenses, car il peut inclure des transactions en attente sur ou à partir du compte financier. Le solde du compte financier contient trois propriétés qui définissent la disponibilité de ses fonds : - `cash` : fonds que l’utilisateur peut dès à présent dépenser. - `inbound_pending` : fonds qui ne peuvent pas encore être dépensés, mais qui seront disponibles ultérieurement. La propriété `inbound_pending`, bientôt disponible, est toujours nulle. - `outbound_pending` : fonds présents sur le compte, mais bloqués pour des flux sortants en attente et qui ne peuvent donc pas être dépensés. Utilisez `GET /v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}` pour récupérer des informations sur le solde d’un compte financier avec l’ID associé. Si le compte financier est associé à l’un de vos comptes connectés, veillez à fournir l’en-tête `Stripe-Account`. En revanche, s’il est associé au compte de votre plateforme, ne rajoutez pas cet en-tête. ```curl curl https://api.stripe.com/v1/treasury/financial_accounts/{{TREASURYFINANCIALACCOUNT_ID}} \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" ``` Sauf échec de l’opération, la réponse renvoie un objet [FinancialAccount](https://docs.stripe.com/api/treasury/financial_accounts.md) avec un hachage `balance` qui décrit en détail les fonds et leur disponibilité. ```json { "object": "treasury.financial_account", "id": "{{FINANCIAL_ACCOUNT_ID}}", ... "balance": { // $90 is currently available for use, // with an additional $10 held in the outbound_pending sub-balance "cash": {"usd": 9000}, "inbound_pending": {"usd": 0}, "outbound_pending": {"usd": 1000} } } ``` ### Soldes négatifs et découverts Si votre compte connecté présente un solde négatif (par exemple, si votre compte financier reçoit un crédit ACH qui est annulé), il vous incombe de le rétablir à 0 USD. Lorsque le solde du compte financier d’un compte connecté devient négatif, Stripe s’approprie immédiatement une réserve équivalente sur le [solde de réserve connecté](https://docs.stripe.com/connect/account-balances.md#understanding-connected-reserve-balances) de votre plateforme (alimenté par le [solde de paiements](https://docs.stripe.com/payments/balances.md#payments-balance) de votre plateforme). Cette réserve est automatiquement débloquée lorsque le solde négatif est comblé. Stripe vous contacte si les soldes spécifiques ou multiples dépassent nos limites de risque. Nous vous recommandons de surveiller vos comptes connectés afin de récupérer des fonds pour leurs soldes négatifs. Vous pouvez recharger les fonds sur votre compte financier à l’aide des [transferts entrants](https://docs.stripe.com/financial-accounts/connect/moving-money/into/inbound-transfers.md) ou de [Payouts Stripe](https://docs.stripe.com/financial-accounts/connect/moving-money/payouts.md). Veillez à surveiller régulièrement les soldes de vos comptes connectés et d’intervenir rapidement. Si un compte financier est négatif depuis plus de 180 jours, Stripe comble le solde négatif en transférant des fonds depuis la réserve de la plateforme pour couvrir le solde négatif et remettre le compte financier à zéro. ## Transactions Toutes les modifications apportées à un solde ont un objet [transaction](https://docs.stripe.com/api/treasury/transactions.md) correspondant qui détaille les mouvements de fonds. Les transactions affectent un seul solde et ne sont libellées que dans une seule devise (Financial Accounts pour les plateformes ne prend en charge que les USD, actuellement). Chaque transaction pointe vers l’objet de transfert de fonds affectant le solde, par exemple un [OutboundTransfer](https://docs.stripe.com/api/treasury/outbound_transfers.md), un [ReceivedCredit](https://docs.stripe.com/api/treasury/received_credits.md) ou un [ReceivedDebit](https://docs.stripe.com/api/treasury/received_debits.md). ### Transaction State Machine | État | État appliqué | Description | Passe à | | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `open` | initial | Il s’agit de l’état initial pour toutes les transactions. La transaction entraîne des modifications des montants du sous-solde, mais le solde actuel n’est pas impacté tant que la transaction n’est pas comptabilisée. | `posted` ou `void` | | `posted` | définitif | Les fonds ont été versés ou prélevés sur le compte. Le solde actuel a été modifié en conséquence. | S.O. | | `void` | définitif | La transaction n’a jamais impacté le solde. Une transaction peut par exemple présenter cet état lorsqu’un paiement sortant a été initié, puis annulé avant que les fonds ne soient prélevés sur le compte. | S.O. | Les endpoints `Transaction` disponibles vous permettent de récupérer des transactions spécifiques et de lister ou filtrer les transactions affectant un compte financier. Aucun webhook n’est disponible pour les transactions, mais des webhooks sont disponibles pour les objets de transfert de fonds associés (par exemple, `OutboundPayments`). ## Récupérer une transaction Utilisez `GET/v1/treasury/transactions/{{TRANSACTION_ID}}` pour récupérer la transaction avec l’ID associé. ```curl curl https://api.stripe.com/v1/treasury/transactions/txn_123 \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" ``` Sauf échec de l’opération, la réponse renvoie l’objet `Transaction`. #### JSON (commenté) ```json { "id": "{{TRANSACTION_ID}}", "object": "treasury.transaction", "created": "{{Timestamp}}", "livemode": false, // The FinancialAccount this Transaction impacts "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // The flow responsible for this Transaction. Each Transaction is created // synchronously (that is, in the same API request for initiated objects) with // its flow. "flow": "{{FLOW_OBJECT_ID}}", "flow_type": "inbound_transfer" | "outbound_payment" | "outbound_transfer" | "received_credit" | "received_debit" | "received_hold" | "issuing_dispute" | "credit_reversal" | "debit_reversal" | "other" "flow_details": null, // Includable, see user_expandable polymorphic object // Transaction state machine: open → posted | void // Transactions transition to posted when the amount is non-zero. // Transactions transition to void when the amount is zero AND the // sub-balance amounts are also zero. // Transactions are immutable once (posted && inbound_pending = 0) || void "status": "open" | "posted" | "void", // posted_at: When status changed from open -> posted // void_at: When status changed from open -> void // At most one of these may be set, because both posted and // void are terminal "status_transitions": { "posted_at": "{{?Timestamp}}", "voided_at": "{{?Timestamp}}" }, // Transactions impact a single currency. "currency": "usd", // When status: // open: This describes the projected change to the current balance. // It can still change // posted: The actual change to the current balance. // Can no longer change // void: Always 0 (the actual change to the current balance). // Can no longer change "amount": 10000, "balance_impact": { "cash": 0, "inbound_pending": 10000, "outbound_pending": 0 }, // Freeform en-US string that describes this Transaction "description": "check deposit", "treasury": { // Set when the transaction transitions to `posted`. // The `financial_account.account.balance` amount as of `posted_at` // in `currency`. // // [DEPRECATION WARNING]: this field will be removed in the future. // Please avoid using it in new integrations. "current_balance_amount": "{{?Integer}}", }, "entries": { // includable "object": "list", "data": [ { "id": "{{TRANSACTION_ENTRY_ID}}", "object": "treasury.transaction_entry", ... } ], "has_more": false, "url": "/v1/treasury/transaction_entries?financial_account={{FINANCIAL_ACCOUNT_ID}}&transaction={{TRANSACTION_ID}}", } } ``` ### Lister des transactions Utilisez `GET /v1/treasury/transactions` pour lister les transactions d’un compte financier. Définissez le paramètre obligatoire `financial_account` dans le corps sur la valeur de l’ID du compte financier pour lequel vous souhaitez récupérer des transactions. Ajoutez des paramètres supplémentaires pour filtrer les résultats. Outre [l’ensemble de paramètres de listage standard](https://docs.stripe.com/api/pagination.md), vous pouvez filtrer les transactions sur les éléments suivants. - `status` - `flow` - `created` ou `posted_at`, mais pas les deux ```json { // Standard list parameters limit, starting_after, ending_before, // Filter by FinancialAccount, required financial_account: "{{FINANCIAL_ACCOUNT_ID}}" // Filter by status status: "open" | "posted" | "void", // Filter by flow flow: "{{FLOW_OBJECT_ID}}", // Order the results by the created or posted_at timestamps, default is `created`. // For order_by=posted_at, setting status='posted' is required order_by: "created" | "posted_at", // created can only be specified with order_by = 'created' created: {gt, gte, lt, lte}, status_transitions: { // status_transitions.posted_at can only be specified with order_by = 'posted_at' and status = 'posted' posted_at: {gt, gte, lt, lte} } } ``` La requête suivante permet de récupérer les trois dernières transactions créées au niveau du compte financier et dont le `status` est défini sur `posted`. ```curl curl -G https://api.stripe.com/v1/treasury/transactions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "financial_account={{TREASURYFINANCIALACCOUNT_ID}}" \ -d limit=3 \ -d status=posted \ -d order_by=created ``` ### Webhooks Aucun webhook n’est associé aux écritures de transaction, car les différents mouvements de fonds qui initient une transaction possèdent leurs propres webhooks. ## Écritures de transaction Les objets [TransactionEntry](https://docs.stripe.com/api/treasury/transaction_entries.md) offrent la vue la plus détaillée des transferts de fonds qui affectent le solde d’un compte financier. Un même mouvement de fonds est composé de plusieurs mouvements distincts, chacun étant représenté par une transaction. Les transactions, quant à elles, sont une agrégation de ces écritures de transaction. Par exemple, lorsque vous initiez un paiement sortant de 10 USD à un instant T, le montant correspondant est transféré du sous-solde `cash` vers le sous-solde `outbound_pending`. La réponse de l’objet `Transaction` ci-après illustre cet événement initial. ```json { "id": "{{TRANSACTION_ID}}", "object": "treasury.transaction", "created": "{{T}}", ... "flow": "{{OUTBOUND_PAYMENT_ID}}", "flow_type": "outbound_payment", "status": "open", "amount": -1000, "currency": "usd", "balance_impact": { "cash": -1000, "inbound_pending": 0, "outbound_pending": 1000, }, "entries": { "data": [ { "id": "{{TRANSACTION_ENTRY_ID}}", "object": "treasury.transaction_entry", ... "created": "{{T}}", "effective_at": "{{T}}", "currency": "usd", "balance_impact": { "cash": -1000, "inbound_pending": 0, "outbound_pending": 1000, } } ], "has_more": false, "object": "list", "url": "/v1/treasury/transaction_entries?financial_account=fa_123&transaction=trxn_123", } } ``` Une fois le paiement sortant comptabilisé à l’instant T+1, le montant est déduit de `outbound_pending` et une nouvelle écriture de transaction est ajoutée à la transaction. La réponse `Transaction` suivante démontre cette progression. ```json { "id": "{{TRANSACTION_ID}}", "object": "treasury.transaction", "created": "{{T}}", ... "flow": "{{OUTBOUND_PAYMENT_ID}}", "flow_type": "outbound_payment", "status": "posted", "amount": -1000, "currency": "usd", "balance_impact": { "cash": -1000, "inbound_pending": 0, "outbound_pending": 0, }, "entries": { "data": [ { "id": "{{TRANSACTION_ENTRY_ID}}", "object": "treasury.transaction_entry", ... "created": "{{T+1}}", "effective_at": "{{T+1}}", "currency": "usd", "balance_impact": { "cash": 0, "inbound_pending": 0, "outbound_pending": -1000, } }, { "id": "{{TRANSACTION_ENTRY_ID}}", "object": "treasury.transaction_entry", ... "created": "{{T}}", "effective_at": "{{T}}", "currency": "usd", "balance_impact": { "cash": -1000, "inbound_pending": 0, "outbound_pending": 1000, } } ], "has_more": false, "object": "list", "url": "/v1/treasury/transaction_entries?financial_account={{FINANCIAL_ACCOUNT_ID}}&transaction={{TRANSACTION_ID}}", } } ``` Comme le montrent les réponses précédentes, une transaction peut contenir plusieurs entrées de transaction. Les endpoints `TransactionEntry` disponibles vous permettent de récupérer des entrées de transaction spécifiques et de les lister ou filtrer pour rechercher une transaction donnée. Aucune nouvelle entrée de transaction ne sera ajoutée à une `Transaction` à l’état `void`. Aucune nouvelle écriture de transaction ne sera ajoutée à une `Transaction` à l’état `posted` et dont l’attribut `balance_impact` concerne uniquement le sous-solde `cash`. ### Récupérer des écritures de transaction Utilisez `GET /v1/treasury/transaction_entries/{{TRANSACTIONENTRY_ID}}` pour récupérer des informations sur l’écriture de transaction avec l’ID associé. ```curl curl https://api.stripe.com/v1/treasury/transaction_entries/{{TRANSACTION_ENTRY_ID}} \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" ``` Sauf échec de l’opération, la réponse renvoie un objet `TransactionEntry` au format suivant : ```json { "id": "{{TRANSACTION_ENTRY_ID}}", "object": "treasury.transaction_entry", "created": "{{Timestamp}}", "livemode": false, // The FinancialAccount this transaction entry impacts. "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // The transaction that this transaction entry belongs to. "transaction": "{{TRANSACTION_ID}}", // The flow responsible for this transaction entry. "flow": "{{FLOW_OBJECT_ID}}", "flow_type": "inbound_transfer" | "outbound_payment" | "outbound_transfer" | "received_credit" | "received_debit" | "received_hold" | "issuing_dispute" | "credit_reversal" | "debit_reversal" | "other", "flow_details": null, // Includable, see user_expandable polymorphic object // type describes the specific money movement that generated the transaction entry. "type": "outbound_payment" | "outbound_payment_cancellation" | "outbound_payment_failure" | "outbound_payment_posting" | "outbound_payment_return" | "outbound_transfer" | "outbound_transfer_cancellation" | "outbound_transfer_failure" | "outbound_transfer_posting" | "outbound_transfer_return" | "received_credit" | "received_debit" | "received_hold" | "received_hold_release" | "credit_reversal" | "credit_reversal_posting" | "debit_reversal" | "stripe_fee" | "inbound_transfer" | "other", // effective_at describes when the transaction entry impacted, or will impact, the FinancialAccount's balance. "effective_at": "{{Timestamp}}", // `effective` if `effective`_at` is in the past, otherwise `scheduled`.` "status": "effective" | "scheduled", // Transaction entries impact a single currency. "currency": "usd", // balance_impact describes the change to each sub-balance for this transaction entry. "balance_impact": { "cash": 0, "inbound_pending": 10000, "outbound_pending": 0 } } ``` ### Lister des TransactionEntries Utilisez `GET /v1/treasury/transaction_entries` pour lister les écritures de transaction d’un compte financier. Définissez le paramètre obligatoire `financial_account` dans le corps sur la valeur de l’ID du compte financier pour lequel vous souhaitez récupérer des écritures de transaction. Ajoutez des paramètres supplémentaires si vous souhaitez filtrer la liste. Outre [l’ensemble de paramètres de listage standard](https://docs.stripe.com/api/pagination.md), vous pouvez filtrer les écritures de transaction sur les éléments suivants : - `transaction` - `created` ou `effective_at`, mais pas les deux ```json { // Standard list parameters limit, starting_after, ending_before, // Filter by FinancialAccount, required financial_account: "fa_123" // Filter by transaction transaction: 'trxn_123', // Order the results by the created or effective_at timestamps, default is `created`. order_by: "created" | "effective_at", // created can only be specified with order_by = 'created' created: {gt, gte, lt, lte}, // effective_at can only be specified with order_by = 'effective_at' effective_at: {gt, gte, lt, lte}, } ``` La requête suivante permet de récupérer les écritures de transaction créées avant `{{Timestamp}}` et de les trier par date de création (`created`). ```curl curl -G https://api.stripe.com/v1/treasury/transaction_entries \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "financial_account={{TREASURYFINANCIALACCOUNT_ID}}" \ -d order_by=created \ -d "created[lt]=1234567890" ``` ### Webhooks Aucun webhook n’est associé aux écritures de transaction, car les différents mouvements de fonds qui créent une écriture de transaction possèdent leurs propres webhooks.