Handle refunds and disputes
Manage funds movement for payment reversals.
This guide is specific to SaaS platforms using direct charges, and outlines your responsibilities for managing disputes, chargebacks, and refunds. Before you begin, see How disputes work.
Sometimes businesses must reverse successful payments due to a customer return or dispute. Moving funds back to the correct parties depends on your charge type.
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. |
Issue refunds
Similarly to how platforms can create charges on connected accounts, they can also create refunds of charges on connected accounts. Create a refund using your platform’s secret key while authenticated as the connected account.
Application fees aren’t automatically refunded when issuing a refund. Your platform must explicitly refund the application fee or the connected account—the account on which the charge was created—loses that amount. You can refund an application fee by passing a refund_application_fee value of true in the refund request:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
By default, the entire charge is refunded, but you can create a partial refund by setting an amount value as a positive integer. If the refund results in the entire charge being refunded, the entire application fee is refunded. Otherwise, a proportional amount of the application fee is refunded. Alternatively, you can provide a refund_application_fee value of false and refund the application fee separately.
Refund application fees
Payment refunds don’t return the application fee to the connected account by default. When you create a refund, you can return the application fee by setting refund_application_fee to true. The application fee refund amount is proportional to the payment refund amount. For example, an original payment of 100 USD with a 5 USD application fee that you refund 40 USD (40%) refunds 2 USD of the application fee.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
If you don’t set refund_application_fee, you can refund the application fee separately as a transfer to the connected account.
Best practices for dispute and chargeback management
To manage disputes and chargebacks and protect your platform, consider implementing the following best practices:
- Implement automated systems that listen to webhook events to alert you about refunds and disputes related to charges.
- Clearly define responsibilities for disputes and refunds in your agreements with connected accounts.
- Maintain reserves for accounts with high dispute rates, and consider holding funds for high-risk transactions until the time period for disputes is over.
- 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 to prevent some disputes and automatically resolve others without incurring fees.
Accept or challenge disputes
For connected accounts that use direct charges, 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.
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 = application | Platform |
v2 Account with 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 = application_unified_accounts_beta | Connected account (for information about changing the payer to your platform, contact Stripe Support) |
v1 Account with controller.fees.payer = application | Platform |
v1 Account with 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 = application_unified_accounts_beta | Connected account (for information about changing the payer to your platform, contact Stripe Support) |
Provide Connect embedded components to allow your connected accounts to respond to disputes
If your connected accounts don’t have access to the full Stripe Dashboard, provide them with the following Connect embedded components to help them respond to disputes without leaving your website:
- Payments component : Displays all payments and disputes for an account.
- Payment details : 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 : Displays all disputes associated with an account.
- Disputes for a payment component : Displays disputes for a specific payment, which allows you to integrate dispute management features into your payments UI.