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.
To let connected accounts use Smart Disputes, 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.
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 behaviour, such as different margins, for when there are no disputes. To do so, set a custom callback function using onDisputesLoaded.
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 attribute, enable the destination_on_behalf_of_charge_management feature.
When creating an Account Session, 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:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
After creating the account session and initialising ConnectJS, you can render the Disputes for a payment component in the front end:
payment-disputes.js
Select a language
JavaScript
React
No results
// 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 and separate charges and transfers, the PaymentIntent doesn’t exist on the connected account. Instead, pass the associated charge ID that belongs to the connected account:
- Retrieve the charge ID from the PaymentIntent’s latest_charge .
- Expand the transfer parameter for this charge.
- In the expanded object, find the connected account’s charge ID in transfer.destination_payment .
Supported parameters
This embedded component supports the following parameters:
| 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 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 behaviours when disputes are loaded. |
Dispute management for destination 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.
Common mistake
Retransferring a previous reversal is subject to cross-border transfer restrictions, meaning you might have no means to repay your connected account. Instead, wait to recover disputed cross-border payment transfers for destination charges with on_behalf_of until after a dispute is lost.