Fonctionnement des soldes et des transactions
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
À l’heure actuelle, comme indiqué dans notre convention de compte de dépôt, Stripe ne propose pas de fonctionnalité de découvert pour les comptes financiers. Si votre solde est insuffisant pour couvrir le montant d’une transaction, Stripe peut rejeter ladite transaction dans la mesure du possible. Sinon, le solde du compte devient négatif et vous devez le rectifier.
Par exemple, si le solde de votre compte financier est inférieur à 100 USD, une authentification Issuing de 100 USD échoue en raison de fonds insuffisants car Stripe a détecté la tentative de surfacturation. En revanche, si le solde de votre compte atteint 50 USD, que vous payez un repas de 50 USD puis que vous laissez un pourboire de 15 USD après la première authentification, l’authentification Issuing aboutit. Par conséquent, la sur-capture Issuing de 65 USD aboutit et génère un solde négatif de -15 USD. Vous devez alors verser de l’argent sur votre compte financier pour éviter que les transactions suivantes soient refusées pour cause de fonds insuffisants.
Si un compte connecté de votre plateforme possède un compte financier avec un solde négatif et qu’il n’y ajoute pas de fonds, vous êtes responsable de la couverture du montant négatif.
Stripe vous envoie un rappel mensuel par e-mail si des comptes financiers associés à votre plateforme présentent des soldes négatifs depuis plus de 15 jours. Cependant, vous devez surveiller régulièrement les soldes des comptes et prendre des mesures correctives dès que possible lorsqu’un solde devient négatif. N’attendez pas l’e-mail de rappel pour traiter vos soldes négatifs.
Note
Vous pouvez faire en sorte que les comptes financiers Treasury couvrent les soldes négatifs des comptes connectés à l’aide de prélèvements automatiques. Pour plus d’informations, consultez la section Soldes négatifs des comptes des bonnes pratiques sur la gestion des risques.
Transactions
Toutes les modifications apportées à un solde sont associées à un objet Transaction
correspondant qui décrit en détail les mouvements 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, tel qu’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
.
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
ouposted_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 mouvements 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,00 $ à 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
oueffective_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.