What is changing

We are standardizing the behavior of Balance Transactions for all debit payment methods in 2024. Balance Transactions are API objects that represent funds into and out of a Stripe account balance. Currently, for certain debit method payments, Balance Transactions are only created when a payment succeeds. This is typically a few days after a payment is created and is determined by the scheme and banking partner.

Going forward, Stripe will create Balance Transactions earlier. Instead of waiting for a successful payment, Balance Transactions will be created when Stripe submits the payment to the banking network. This means that once a Balance Transaction is created, it will be in a pending state until the payment is transitioned to a successful state. Additionally, Balance Transactions have an attribute called available_on which denotes when the Balance Transaction is available to be paid out to your external bank account. The Balance Transaction available_on dates will remain constant throughout this change.

API implications

Rely on charge status for success signals

If your integration currently waits for a payment to be successful prior to fulfilling orders, you should listen for charge.succeeded or payment_intent.succeeded events to reliably confirm that payments have succeeded.

Although uncommon, it was previously possible to rely on Balance Transaction presence as a proxy for payment success. Doing so is no longer recommended, as pending payments may also have Balance Transactions and these funds are not considered settled until success time. Note also that Balance Transaction available_on should not be used as a signal for payment success – this represents when funds will be released to your Stripe balance.

Failed charges may have 2 Balance Transactions

Prior to this change, Balance Transactions were not issued for failed payments. After this change, failed payments that were submitted to banking rails will have 2 Balance Transactions: A positive balance_transaction and a second negative failure_balance_transaction in the Charge object.

If your integration is querying for balances or payout attribution data, you may have to handle this new type of Balance Transaction in your accounting or reconciliation processes.

(Connect Only) Connect transfers are executed early

This section is only applicable to Connect Platforms performing destination charges. When a payment generates a Balance Transaction, transfers are executed in tandem. After this change, pending transfers will be created prior to payment success. Despite being created earlier, Stripe will ensure that the transfer’s available_on value matches the source transaction.

(Connect Only) Separate charges & transfers

If you are a Connect Platform performing separate charges & transfers with the source_transaction transfer option, you will also have the flexibility of initiating transfers against pending payments after this change. No changes are required to your integration if you would like to preserve your existing behavior.

Testmode

We’ll enable testmode by April 29, 2024. After this date, you’ll be able to initiate test transactions via the dashboard or API which will allow you to observe the Balance Transaction timing changes. Note that in testmode, transactions settle on an accelerated timeline.

Why we are doing this

We’re standardizing the way all debit payments work – this will make debit methods easier to integrate, especially if you enable multiple debit methods. Creating the Balance Transaction earlier will also provide more visibility over the payment lifecycle which may allow for more accurate financial / accounting reporting.