Negative Balances

This guide is written for Connect Custom integrations that create destination charges. It describes refund and dispute scenarios that you and your connected accounts can’t initially cover. This happens when your platform or connected account balances are either already negative, or a refund or dispute causes them to become negative.

In Connect Custom integrations, you’re partially responsible for coordinating refunds and disputes. This means your platform account might be used to initially cover refund or dispute amounts. You can then recover those funds from the connected account the refund or dispute was made against.

If the connected account has a negative balance, you can set the debit_negative_balance parameter to true for that account, which allows Stripe to charge the connected account’s bank account. You can read more about how to handle negative balances and disputes in the Connect documentation.

Platform reserves

As soon as a connected account’s balance becomes negative, a platform reserve is held on your platform. Reserves are held separately from other balances on your platform account, and cover the total negative balance amount across your connected accounts. There are multiple steps that can correct the negative balance without affecting your platform’s balance or your platform’s bank account. These steps are explained in the refund and dispute flows below.

If a negative balance on a connected account isn’t resolved in the refund or dispute flows, Stripe continues to hold the platform reserve. Funds are first pulled from your platform’s available balance to cover the negative balance amount. If your Stripe account balance can’t cover the amount, your bank account is debited. When a connected account becomes positive again, Stripe credits your platform’s available balance, which is then paid out according to your payout schedule. If after 180 days the connected account is still negative, Stripe moves funds from your platform to the custom account automatically.

Platform reserves can be viewed in the Stripe Dashboard. The Home and Balance pages display the total reserve amount. You can also view individual reserve amounts on the Transactions page. If a transaction is related to a reserve, the Description column explains whether funds are reserved or released.

A single reserve transaction

Negative balance flows

The flows for refunds and disputes are different. You play a role in each flow, but your customers and Stripe are involved too.

Refund flow

These are the steps refunds go through (assume the original charge is $100):

  1. A cardholder requests a refund from your platform.

  2. Your platform uses the create_refund API call with the reverse_transfer argument set to true. This reverses the original $100 transfer and refunds the cardholder. Funds are taken from the connected account’s balance and transferred to your platform’s balance, even if this causes the connected account’s balance to become negative. If it does, you can have Stripe debit the connected account’s bank account to cover the negative balance. This is done in steps three and four.

  3. Your platform sets debit_negative_balances to true on the connected account.

  4. Stripe attempts to debit the connected account’s bank account for the negative balance at the end of the day.

  5. If the debit fails, Stripe continues to hold a reserve on your platform.

Refund flow

You can read more about accounting for negative balances in our product documentation. It also explains how to use the API to check account balances.

Dispute flow

Disputes go through a different flow than refunds and include chargeback fees. Chargeback fee amounts vary by the connected account’s country. Disputes generally go through these steps (assume the original charge is $100 and the chargeback fee is $15):

  1. A cardholder disputes the charge through their card company.

  2. Stripe debits your platform’s balance for $115 ($100 for the original charge and $15 for the chargeback fee). If your platform’s balance doesn’t have enough funds, step three is triggered.

  3. Stripe attempts to debit your platform’s bank account for the negative balance at the end of the day. As the platform, you have the option to reverse the original $100 transfer to the connected account to cover the funds you used to pay the cardholder. This is done in step four.

  4. Your platform uses the transfer_reversal API call with the reverse_transfer argument set to true. This recovers the original $100 transfer used to pay the cardholder. Funds are taken from the connected account’s balance and transferred to your platform’s balance. If the transfer causes the connected account’s balance to become negative, or if the account is already negative, you can have Stripe debit the connected account’s bank account to cover the negative balance. This is done in steps five and six.

  5. Your platform sets the debit_negative_balances to true.

  6. Stripe attempts to debit the connected account’s bank account for the negative balance at the end of the day.

  7. If the debit fails, Stripe continues to hold a reserve on your platform.

Dispute flow

You can read more about accounting for negative balances in our product documentation. It also explains how to use the API to check account balances.

Passing chargeback fees to connected accounts

Chargeback fees are charged to your platform. You can transfer funds from a connected account to cover these fees if your platform and the connected account are in the same region. Instead of using customer objects or withholding upcoming funds from connected accounts, you create a transfer that pulls funds from the connected account back to your platform. To automate this process:

  1. Use a webhook to listen for the charge.dispute.created event.
  2. When an event is triggered, retrieve the charge to determine the destination account.
  3. Transfer the dispute fee amount from the connected account’s balance to your platform’s balance.

Because you’re retrieving funds for an existing charge, make sure to use the transfer account debit, and not the charge account debit since this creates a new charge. There may be fees associated with account debits. Talk with your account manager or account executive for more details.

Notifying connected accounts

It’s recommended you notify connected accounts when you debit them. This explains why they’re being debited and for how much.

Refund notifications

To notify connected accounts of refunds:

  1. Manually refund the amount using the reverse_transfer parameter. This refunds the charge back to the cardholder using funds from the connected account.

  2. Use a webhook to listen to the charge.refunded event. This event has a destination property that identifies the connected account the refund is associated with.

  3. With the connected account information, send an email to the account owner that explains the refund.

Dispute notifications

If your integration uses the destination parameter and a charge is disputed, funds are withdrawn from your platform’s Stripe balance. To listen for disputes and debit connected accounts:

  1. Use webhooks to listen to the charge.dispute.created and charge.dispute.funds_withdrawn events. These inform you that Stripe is debiting your Stripe account to cover a dispute.

  2. Use the charge ID to retrieve the charge. This has a destination property that identifies the connected account the refund is associated with.

  3. With the connected account information, send an email to the account owner that explains the dispute.

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.