Disputes list

The Disputes list component displays the disputes associated with a connected account. Each row in the list represents a dispute. Connected accounts can click a row to show detailed information about the dispute and its associated charge. When you enable the dispute_management feature, connected accounts can take actions to manage disputes, such as submit evidence or accept disputes. The component also includes functionality to filter disputes based on specific criteria, and export the disputes list for further analysis or record-keeping.

When creating an Account Session, enable this component by specifying disputes_list in the components parameter. You can turn on or off an individual feature of the payment details component by specifying the features parameter under disputes_list:

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-03-31.preview" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[payments][enabled]"=true \
  -d "components[payments][features][refund_management]"=true \
  -d "components[payments][features][dispute_management]"=true \
  -d "components[payments][features][capture_payments]"=true \
  -d "components[payments][features][destination_on_behalf_of_charge_management]"=false

After creating the Account Session and initializing ConnectJS, you can render the Disputes list component in the front end:

// Include this element in your HTML
const disputesList = stripeConnectInstance.create('disputes-list');
container.appendChild(paymentDisputes);

Dispute management for destination charges

By default, embedded components are most compatible with Connect integrations that accept direct charges. You can allow users to see disputes associated with destination charges with the on_behalf_of attribute by enabling the destination_on_behalf_of_charge_management feature. Otherwise, this component doesn’t include disputes for these types of charges.

When you enable both dispute_management and destination_on_behalf_of_charge_management, your connected accounts can update and modify dispute evidence, counter disputes, and accept disputes for destination charges with the on_behalf_of attribute set to the connected account.

For destination charges, with or without on_behalf_of, Stripe debits dispute amounts and fees from your platform account.

We recommend setting up a webhook to listen to dispute created events. When that happens, you can attempt to recover funds from the connected account by reversing the transfer through the Dashboard or by creating a transfer reversal.

If the connected account has a negative balance, Stripe attempts to debit its external account if debit_negative_balances is set to true.

If you challenge the dispute and win, you can transfer the funds that you previously reversed back to the connected account. If your platform has an insufficient balance, the transfer fails. Prevent insufficient balance errors by adding funds to your Stripe balance.