Handle refunds and disputesPublic preview

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

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:

curl https://api.stripe.com/v1/refunds \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d charge=
"{{CHARGE_ID}}" \
  -d refund_application_fee=true

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.

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

Direct charges

For connected accounts that use direct charges, Stripe debits the disputed amount from the connected account’s balance. However, dispute fee responsibilities depend on the controller.losses.payments and controller.fees.payer properties.

Accounts that handle their own disputes

For connected accounts where your platform isn’t liable for negative balances (including Standard accounts), these accounts act as the merchant of record. This means disputes and chargebacks are filed against them, and we deduct the total amount for disputes and fees directly from their balance.

Accounts where the platform is liable

For connected accounts where your platform is liable for negative balances (including Custom and Express accounts), your platform is responsible for any disputes related to those accounts. In this case, Stripe deducts the total for disputes and fees from the connected account’s balance. If the balance is insufficient, Stripe pulls the necessary amounts from your platform’s balance instead.

For additional details, refer to the fee behaviors for payer values and learn how to set account controller properties using the Accounts API.

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.