# Disputes for a payment

Enable a connected account to view and manage disputes for a payment.

Render a UI component for connected accounts to view disputes for a specific payment. Connected accounts can see details for each dispute, such as the dispute reason, status, amount, and creation date. Enable the `dispute_management` feature for the Account Session to let connected accounts submit evidence and accept disputes. This functionality is also available in the [payment details component](https://docs.stripe.com/connect/supported-embedded-components/payment-details.md).

To let connected accounts use [Smart Disputes](https://docs.stripe.com/disputes/smart-disputes.md), enable `smart_disputes_management`. Connected accounts can still submit evidence or accept disputes manually when this feature is enabled. Smart Disputes can also respond to eligible disputes that they don’t handle manually and are about to close due to timeout. This feature defaults to the value of `dispute_management`, and you can enable it only when `dispute_management` is also enabled. Set `smart_disputes_management` to `false` to disable Smart Disputes while preserving manual dispute management.

For connected accounts that use the Express Dashboard, configure Smart Disputes separately in [Express features settings](https://dashboard.stripe.com/settings/connect/express-dashboard/features).

This inline component can be integrated on the same page as your other payments UI. It’s suitable for use in full screen, overlay, drawer, or any other layout with adaptable widths. If there aren’t any disputes associated with the payment, the component renders nothing. You can also configure custom behavior, such as different margins, for when there are no disputes. To do so, set a custom callback function using `onDisputesLoaded`.

Note: The following is a preview/demo component that behaves differently than live mode usage with real connected accounts. The actual component has more functionality than what might appear in this demo component. For example, for connected accounts without Stripe dashboard access (custom accounts), no user authentication is required in production.

In rare cases, a connected account can receive multiple disputes for the same payment created by a customer. Your connected account must review and handle each dispute for the same payment separately. We recommend you inform your connected accounts about this best practice to help improve their payment success rate.

By default, embedded components are most compatible with Connect integrations that accept direct charges. Embedded components display less information for destination charges and separate charges and transfers, and this UI component renders nothing for these charge types. To enable users to see disputes associated with destination charges with the [on_behalf_of](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-on_behalf_of) attribute, enable the `destination_on_behalf_of_charge_management` feature.

When [creating an Account Session](https://docs.stripe.com/api/account_sessions/create.md), enable this component by specifying `payment_disputes` in the `components` parameter. You can turn on or off an individual feature of the payment details component by specifying the `features` parameter under `payment_disputes`:

```curl
curl https://api.stripe.com/v1/account_sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_ID}}" \
  -d "components[payment_disputes][enabled]=true" \
  -d "components[payment_disputes][features][refund_management]=true" \
  -d "components[payment_disputes][features][dispute_management]=true" \
  -d "components[payment_disputes][features][smart_disputes_management]=true" \
  -d "components[payment_disputes][features][destination_on_behalf_of_charge_management]=false"
```

After creating the account session and [initializing ConnectJS](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions), you can render the Disputes for a payment component in the frontend:

#### JavaScript

```js
// Include this element in your HTML
const paymentDisputes = stripeConnectInstance.create('payment-disputes');
paymentDisputes.setPayment('{{PAYMENT_INTENT_OR_CHARGE_ID}}');
container.appendChild(paymentDisputes);
```

For [destination charges](https://docs.stripe.com/connect/destination-charges.md) and [separate charges and transfers](https://docs.stripe.com/connect/separate-charges-and-transfers.md), the PaymentIntent doesn’t exist on the connected account. Instead, pass the associated charge ID that belongs to the connected account:

1. Retrieve the charge ID from the PaymentIntent’s [latest_charge](https://docs.stripe.com/api/payment_intents/object.md?api-version=2025-05-28.basil).
2. Expand the `transfer` parameter for this charge.
3. In the expanded object, find the connected account’s charge ID in [transfer.destination_payment](https://docs.stripe.com/api/transfers/object.md#transfer_object-destination_payment).

## Supported parameters

This embedded component supports the following parameters:

#### HTML + JS

| Method | Type | Description |  |
| --- | --- | --- | --- |
| `setPayment` | `string` | The ID of the payment, charge, or PaymentIntent that displays in the overlay. This should be an ID of the payment, charge, or PaymentIntent on the connected account. If this attribute isn’t defined, the embedded component renders nothing. To obtain this ID, query the [charges API](https://docs.stripe.com/api/charges.md) or use a payment ID that you’ve created or stored in your integration. | required |
| `setOnDisputesLoaded` | `({total}: {total: number}) => void` | We send this event with the total number of disputes on this payment when the disputes are loaded. It allows specifying custom behaviors when disputes are loaded. |  |

#### React

| React prop | Type | Description |  |
| --- | --- | --- | --- |
| `payment` | `string` | The ID of the payment, charge, or PaymentIntent that displays in the overlay. This should be an ID of the payment, charge, or PaymentIntent on the connected account. If this parameter isn’t passed in, the embedded component renders nothing. To obtain this ID, query the [charges API](https://docs.stripe.com/api/charges.md) or use a payment ID that you’ve created or stored in your integration. | required |
| `onDisputesLoaded` | `() => void` | Allows user to provide a callback to specify custom behaviors when disputes are loaded. |  |

## Disputes and refunds for destination charges 

When you enable `destination_on_behalf_of_charge_management` feature in the  component, you can also enable the `refund_management` and `dispute_management` features to allow your connected accounts to take action on destination charges with the `on_behalf_of` attribute set to the connected account:

- Issue refunds
- Submit and update dispute evidence
- Counter disputes
- Accept disputes

### Refunds

Refunding a destination charge through the  component automatically reverses its associated transfer.

Refunding any type of charge in the component doesn’t refund application fees, which is consistent with the default behavior on the [Refunds API](https://docs.stripe.com/api/refunds/create.md#create_refund-refund_application_fee).

### Disputes

Stripe debits dispute amounts and fees from your platform account for all [destination charges](https://docs.stripe.com/connect/destination-charges.md), with or without `on_behalf_of`.

Set up [a webhook](https://docs.stripe.com/webhooks.md) to listen for [dispute created events](https://docs.stripe.com/api/events/types.md#event_types-charge.dispute.created).

You can reverse the transfer to your connected account through the [Dashboard](https://dashboard.stripe.com/test/transfers) or by [creating a transfer reversal](https://docs.stripe.com/api/transfer_reversals/create.md) to recover the dispute chargeback funds. If the connected account has a negative balance, Stripe attempts to debit its external account if [debit_negative_balances](https://docs.stripe.com/connect/account-balances.md#automatically-debit-connected-accounts) is set to `true`.

Time your reversal according to how you choose to handle the dispute:

- If you accept the dispute, you can reverse the transfer immediately.
- If you challenge the dispute, wait for the dispute outcome before reversing the transfer.
  - If you win, don’t reverse the transfer.
  - If you lose, reverse the transfer.

If you reverse the transfer for a disputed payment that you challenge and win, transfering those funds back to a connected account can have unexpected results:

- If your platform has an insufficient balance, the transfer fails. Prevent insufficient balance errors by [adding funds to your Stripe balance](https://docs.stripe.com/get-started/account/add-funds.md).
- [Cross-border transfer restrictions](https://docs.stripe.com/connect/account-capabilities.md#transfers-cross-border) might prevent you from repaying your connected account.