# Handle refunds and disputes

Manage funds movement for payment reversals.

This guide shows you how to handle refunds and disputes for SaaS platforms using [direct charges](https://docs.stripe.com/connect/direct-charges.md). It also applies to connected accounts that use the Express Dashboard with [Managed Risk](https://docs.stripe.com/connect/risk-management/managed-risk.md), regardless of whether Stripe or your platform manages payments pricing. Before you begin, see [How disputes work](https://docs.stripe.com/disputes/how-disputes-work.md).

With direct charges, your platform creates payments on the connected account. Stripe debits refunds and disputed amounts from that account’s balance. Whether the connected account or your platform pays dispute-related fees depends on the account’s [fee configuration](https://docs.stripe.com/connect/direct-charges-fee-payer-behavior.md).

## Disputes terminology

| Term | Description |
| --- | --- |
| Dispute | A claim filed by a cardholder or issuing bank regarding a payment. Disputed funds are typically withdrawn immediately and returned only if resolved in favor of the business. |
| Disputed amount | The charge amount being disputed. |
| Dispute fee | A flat fee that Stripe charges when receiving a dispute. |
| Inquiry or retrieval | A preliminary phase initiated by some card networks (for example, American Express) before a claim becomes a formal dispute. Resolving the situation at this stage can avoid dispute fees. |

For differences between direct and indirect charges, see [refund behavior by charge type](https://docs.stripe.com/connect/charges.md#refund-creation) and [Disputes on Connect platforms](https://docs.stripe.com/connect/disputes.md).

## Issue refunds 

[Create a refund](https://docs.stripe.com/api/refunds/create.md) using your platform’s [secret key](https://docs.stripe.com/keys.md#create-a-secret-key) with `charge_write` permission for connected accounts when [authenticated](https://docs.stripe.com/connect/authentication.md#stripe-account-header) as the connected account. Follow [secure key storage guidance](https://docs.stripe.com/keys-best-practices.md#secure-key-storage).

### Refund application fees 

Payment refunds don’t automatically return application fees to the connected account. To return the application fee, set `refund_application_fee` to true in the refund request:

```curl
curl https://api.stripe.com/v1/refunds \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d "charge={{CHARGE_ID}}" \
  -d refund_application_fee=true
```

By default, the entire charge is refunded. To create a partial refund, set `amount` to a positive integer in the currency’s minor unit. When `refund_application_fee` is true, a full refund returns the entire application fee, and a partial refund returns a proportional amount. For example, refunding 40 USD of a 100 USD payment with a 5 USD application fee returns 2 USD of the application fee.

Alternatively, omit `refund_application_fee` or set it to false, and [refund the application fee separately](https://docs.stripe.com/api/fee_refunds/create.md). For this separate request, use your platform’s [secret key](https://docs.stripe.com/keys.md#create-a-secret-key) with `application_fee_write` permission on the platform account, without the `Stripe-Account` header.

## Best practices for dispute and chargeback management

To manage disputes and chargebacks and protect your platform, consider implementing the following best practices:

- Listen to [events on connected accounts](https://docs.stripe.com/connect/webhooks.md) to receive notifications about refunds and disputes for direct charges. [Verify webhook signatures](https://docs.stripe.com/webhooks.md#verify-events) and allowlist Stripe’s [webhook IP addresses](https://docs.stripe.com/ips.md).
- Clearly define responsibilities for disputes and refunds in your agreements with connected accounts.
- When Stripe is responsible for negative balances, Stripe manages risk interventions, including reserves. If your platform is responsible for negative balances, consider maintaining [reserves for accounts](https://docs.stripe.com/connect/connected-account-reserves.md) with high dispute rates.
- Provide clear guidance to connected accounts on gathering and submitting compelling evidence.
- Establish standard evidence collection processes for disputes and monitor real-time notifications.
- Use [Radar rules](https://docs.stripe.com/connect/radar.md) to prevent some disputes and automatically resolve others without incurring fees.

## Accept or challenge disputes

For connected accounts that use [direct charges](https://docs.stripe.com/connect/direct-charges.md), Stripe always attempts to debit disputed amounts from the connected account’s balance. However, if Stripe can’t debit the amount, ultimate responsibility depends on whether Stripe or the platform is [responsible for negative balances](https://docs.stripe.com/connect/risk-management.md#identify-negative-balance-responsibility).

For dispute-related fees, responsibility depends on your connected account options. The following table shows whether Stripe debits dispute-related fees from the platform or the connected account:

| Account option | Dispute fee payer |
| --- | --- |
| v2 `Account` with [defaults.responsibilities.fees_collector](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-defaults-responsibilities-fees_collector) = `application` | Platform |
| v2 `Account` with [defaults.responsibilities.fees_collector](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-defaults-responsibilities-fees_collector) = any of the following values, including legacy Standard, Express, and Custom accounts:
- `stripe`
- `application_custom`
- `application_express` | Connected account |
| v2 `Account` with [defaults.responsibilities.fees_collector](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-defaults-responsibilities-fees_collector) = `application_unified_accounts_beta` | Connected account (for information about changing the payer to your platform, [contact Stripe Support](https://support.stripe.com/)) |
| v1 `Account` with [controller.fees.payer](https://docs.stripe.com/api/accounts/create.md#create_account-controller-fees-payer) = `application` | Platform |
| v1 `Account` with [controller.fees.payer](https://docs.stripe.com/api/accounts/create.md#create_account-controller-fees-payer) = any of the following values, including legacy Standard, Express, and Custom accounts:
- `account`
- `application_custom`
- `application_express` | Connected account |
| v1 `Account` with [controller.fees.payer](https://docs.stripe.com/api/accounts/create.md#create_account-controller-fees-payer) = `application_unified_accounts_beta` | Connected account (for information about changing the payer to your platform, [contact Stripe Support](https://support.stripe.com/)) |

When you use Managed Risk, you and your connected accounts still need to manage disputes, including accepting disputes or submitting evidence before the deadline. See [Respond to disputes](https://docs.stripe.com/disputes/responding.md).

## Enable connected accounts to manage refunds and disputes

Connected accounts with access to the [Express Dashboard](https://docs.stripe.com/connect/express-dashboard.md) can issue refunds and respond to disputes there. When Stripe is responsible for negative balances, these features are required and can’t be disabled. See [Customize features](https://docs.stripe.com/connect/customize-express-dashboard.md#customize-features).

To let connected accounts manage payments and disputes within your application, provide the following Connect embedded components:

- [Payments component](https://docs.stripe.com/connect/supported-embedded-components/payments.md): Displays all payments and disputes for an account.
- [Payment details](https://docs.stripe.com/connect/supported-embedded-components/payment-details.md): Displays detailed information about a specific payment as an overlay, similar to what appears when a user clicks a payment row in the payments component.
- [Disputes list component](https://docs.stripe.com/connect/supported-embedded-components/disputes-list.md): Displays all disputes associated with an account.
- [Disputes for a payment component](https://docs.stripe.com/connect/supported-embedded-components/disputes-for-a-payment.md): Displays disputes for a specific payment, which allows you to integrate dispute management features into your payments UI.

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.

## See also

- [Respond to disputes](https://docs.stripe.com/disputes/responding.md)
- [Dispute categories](https://docs.stripe.com/disputes/categories.md)
- [Prevent disputes and fraud](https://docs.stripe.com/disputes/prevention.md)
- [Use Radar with Connect](https://docs.stripe.com/connect/radar.md)