Understanding Connect Account Balances

    Learn how Stripe account balances work when using Connect.

    Both your platform account and a connected account are still just Stripe accounts, each with their own, separate account balance.

    All Stripe accounts can have balances in two states:

    • pending, meaning the funds are not yet available to pay out
    • available, meaning the funds can be paid out now

    With non-Connect accounts, processing charges increases the Stripe account balance. The charged amount, less any Stripe fees, is initially reflected on the pending balance, and becomes available on a 2-day rolling basis. (This timing can vary by country and account.) Available funds can be paid out to a bank account or debit card. Payouts reduce the Stripe account balance accordingly.

    With Connect, your platform account and each connected account has their own pending and available balances. How funds from payments are allocated between the two types of accounts depends upon which charging approach is used.

    Further, a platform account can also have a connect_reserved balance, used to offset negative balances on connected accounts.

    Accounting for negative balances

    Some actions, such as refunds and chargebacks, create negative transactions in a Stripe account. If at all possible, Stripe automatically offsets negative transactions against future payments to ensure a positive Stripe balance.

    Stripe first assigns negative transactions to the account on which the associated charge was made. For example, when charging on a connected account, a refund or chargeback comes from the connected account. When charging on your platform, a refund or chargeback comes from your platform account.

    However, ultimate responsibility for negative balances depends upon the relationship between your platform and the connected account. A connected Standard account is always ultimately responsible to cover negative balances. For Express and Custom accounts, the platform is ultimately responsible to cover negative balances.

    To check the balance of a connected account, perform a retrieve balance API call authenticated as the connected account. The returned Balance object reflects the pending and available balances.

    curl https://api.stripe.com/v1/balance \
       -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
       -H "Stripe-Account: CONNECTED_STRIPE_ACCOUNT_ID"
    
    Stripe.api_key = {PLATFORM_SECRET_KEY}
    
    balance = Stripe::Balance.retrieve(
      {:stripe_account => CONNECTED_STRIPE_ACCOUNT_ID}
    )
    
    stripe.api_key = {PLATFORM_SECRET_KEY}
    
    balance = stripe.Balance.retrieve(
      stripe_account=CONNECTED_STRIPE_ACCOUNT_ID
    )
    
    StripeStripe::setApiKey({PLATFORM_SECRET_KEY});
    
    $balance = \Stripe\Balance::retrieve(
      ["stripe_account" => CONNECTED_STRIPE_ACCOUNT_ID]
    );
    
    Stripe.apiKey = {PLATFORM_SECRET_KEY};
    RequestOptions requestOptions = RequestOptions.builder().setStripeAccount(CONNECTED_STRIPE_ACCOUNT_ID).build();
    
    Balance balance = Balance.retrieve();
    
    var stripe = require('stripe')({PLATFORM_SECRET_KEY});
    
    stripe.balance.retrieve({
      stripe_account: CONNECTED_STRIPE_ACCOUNT_ID
    }, function(err, balance) {
      // asynchronously called
    });
    

    While an account's balance is negative, you cannot send payouts to the account's bank or debit card on their behalf. Stripe will resume sending payouts to the connected account once the account's Stripe balance is again positive.

    If Stripe has not already attempted to debit a connected account's external account for a negative balance, you can set the debit_negative_balances flag to have Stripe automatically resolve the issue. This functionality works only for banks located in Australia, Canada, and the U.S. Stripe cannot correct a negative Stripe account balance using a debit card or banks located in other countries. Also note that enabling debit_negative_balances triggers debits (as needed) even when the connected account is on manual payouts.

    Understanding connected reserve balances

    To ensure funds can be covered, Stripe holds a reserve on your platform account’s available balance to cover any negative available balances across your Custom accounts. You’ll see this reserve reflected in the Dashboard and exported reports (as a reserve transaction).

    There are three kinds of balance activities related to reserves:

    • Funds reserved to cover a negative balance on a connected account. When a connected account’s balance becomes negative, Stripe temporarily reserves a portion of your balance to ensure that funds can be covered by creating a balance transaction with the type reserve_transaction.
    • Funds released after a positive balance change on a connected account. When a connected account’s previously negative balance becomes less negative due to activity on that account (e.g., through new charges), a corresponding portion of your platform’s reserve balance is released via balance transaction with the type reserve_transaction.
    • Funds collected due to a long-standing negative balance on a connected account. When a connected account holds a negative balance amount for 180 days, Stripe transfers a portion of your balance to zero out that account’s balance by creating a balance transaction with the type connect_collection_transfer.

    To see the current reserves held on your account, perform a retrieve balance API call but for your own account (i.e., not authorized as another user as in the above).

    To clear a connected account’s negative balance, and thereby remove the reserve on your account, send a transfer to the applicable account. If a connected account has a negative balance for more than 180 days, Stripe will automatically transfer your reserves to the connected account to zero out the balance. These transfers are shown as Connect collection transfers in your Dashboard and exported reports.

    Connected reserve balances are also shown on the Monthly report under the Reserve summary section.

    Holding funds

    Some platforms may need more granular control over their payout schedule. This can be accomplished by:

    We recommend platforms only hold funds when there is both a clear purpose for holding and a commitment to complete the payment upon the occurrence of an event or satisfaction of a precondition. The typical use case for holding funds is on-demand services platforms, where the marketplace usually waits for the service to be completed and confirmed before paying out to the service provider (e.g., rentals, delivery services, and ride-sharing).

    Platforms should refrain from holding funds arbitrarily, and instead pay out their connected accounts as soon as they are identified: usually when the charge is made. In case of doubt, speak with your legal advisor.

    For compliance reasons, it is only possible to hold funds in a reserve for up to 90 days from charge creation to payout in either case.

    Further reading

    Discover what other Connect functionality is available!

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.