Fonctionnement des soldes et des transactions

Pour comprendre les soldes Treasury et les effets de transactions sur ceux-ci.

Les comptes financiers 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.

Sauf échec de l’opération, la réponse renvoie un objet FinancialAccount avec un hachage balance qui décrit en détail les fonds et leur disponibilité.

{
  "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é), vous avez la responsabilité de le rétablir à 0 USD. Après 180 jours de solde négatif, Stripe débite votre plateforme. Nous vous contactons également si les soldes individuels ou agrégés 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 de transferts entrants ou de virements Stripe. Veillez à surveiller régulièrement les soldes de vos comptes connectés et à les joindre rapidement.

Lorsqu’un compte financier est négatif depuis 180 jours, Stripe débite les fonds du compte financier de votre plateforme et vous envoie un e-mail à l’avance. Si le transfert échoue en raison d’une insuffisance de fonds, Stripe vous contacte pour vous indiquer les prochaines étapes.

Transactions

Toutes les modifications apportées à un solde sont associées à un objet Transaction correspondant qui décrit en détail les transferts de fonds. Les transactions affectent uniquement un solde et sont dans une seule devise (à l’heure actuelle, seuls les USD sont pris en charge par Stripe Treasury).

Chaque transaction pointe vers l’objet de transfert de fonds affectant le solde, par exemple un OutboundTransfer, un ReceivedCredit ou un ReceivedDebit.

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é.

Sauf échec de l’opération, la réponse renvoie l’objet Transaction.

JSON (commenté)
{
  "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.

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, vous pouvez filtrer les transactions sur les éléments suivants.

status
flow
created ou posted_at, mais pas les deux

{
  // 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.

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

{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{T}}",
  ...
  "flow": "{{OUTBOUND_PAYMENT_ID}}",
  "flow_type": "outbound_payment",
  "status": "open",
  "amount": -1000,
  "currency": "usd",

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.

{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{T}}",
  ...
  "flow": "{{OUTBOUND_PAYMENT_ID}}",
  "flow_type": "outbound_payment",
  "status": "posted",
  "amount": -1000,
  "currency": "usd",

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é.

Sauf échec de l’opération, la réponse renvoie un objet TransactionEntry au format suivant :

{
  "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.

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, vous pouvez filtrer les écritures de transaction sur les éléments suivants :

transaction
created ou effective_at, mais pas les deux

{
  // 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).

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.