Dispute Settlement Details

Learn how to use Dispute Settlement Details to track money movement for disputes.

Availability

This feature is available to eligible Issuing platforms. Contact your Stripe account manager or Stripe Support to request access.

When a cardholder files a dispute or a dispute changes state, card networks move money between you and the businesses where the card was used. The total amount that moves in a settlement period is included in the settlement.net_total_amount, which you can use to determine the aggregate amount needed for settlement, inclusive of dispute funds flows.

For reconciliation purposes, Stripe also creates DisputeSettlementDetail objects to reflect network money movement for each dispute, based on state changes. We create these records from the card network’s clearing files.

DisputeSettlementDetail lifecycle

Stripe receives clearing records for each stage in the dispute lifecycle, including dispute filing, merchant representments or pre-arbitrations, and win or loss outcomes. When we receive a network record we create a DisputeSettlementDetail and tie it back to the appropriate Settlement object during reconciliation.

Stripe notifies you of these changes with webhook events:

• We send the issuing _ dispute _ settlement _ detail. created event when we receive a dispute financial record and create the DisputeSettlementDetail (the initial object with no settlement).
• We send the issuing _ dispute _ settlement _ detail. updated event when the DisputeSettlementDetail’s settlement is set during reconciliation.

Example object:

{ 
 "id": "idpsd_1MzFN1K8M4JkH0lBmFq8CqBS",
 "object": "issuing.dispute_settlement_detail", 
 "amount": 1000,
 "card": "{{CARD_ID}}", 
 "cardholder": "{{CARDHOLDER_ID}}", 
 "created": 1743532000, 
 "currency": "usd", 
 "dispute": "idp_1MzFNdK8M4JkH0lBmFq8CqXY", 
 "event_type": "win", 
 "livemode": true, 
 "network": "visa", 
 "settlement": "ise_1R9Op42j5ohbiDWAVaavpeVG", 
 "network_data": { "processing_date": "2024-08-06" }, 
 "merchant_data": { "...": "..." } 
}

Interpret dispute funds flows

The DisputeSettlementDetail's amount indicates the amount of money that moves for each dispute. The event_type parameter indicates what stage of the dispute lifecycle triggered that money movement. We send you an issuing_dispute_settlement_detail.updated event to notify you of new money movement for a dispute.

Similar to the Settlement API, positive values in issuing_dispute_settlement.amount represent amounts the card network owes you (credits), and negative values represent amounts you owe the network (debits).

The event_type indicates stages in the dispute lifecycle, and the values generally follow this logic

Note

Sometimes the values for each event_type can be reversed (for example, a representment could be positive instead of negative), and you could receive multiple updates with the same event_type (for example, two separate updated webhooks both with an event_type of win). Prepare your code to handle these edge cases.

Depending on how far the dispute progresses along the network’s dispute resolution lifecycle, you might not see an event_type of win or loss.

If you already received a credit during dispute submission (as indicated by an event_type = filing) and you don’t have a subsequent debit from an event_type of representment you don’t receive an additional credit if you ultimately win. You also don’t receive an updated event_type of win.

If the business contests a dispute and you were debited with an event_type of representment, you don’t receive an additional debit if you subsequently lose. You don’t receive an updated event_type of loss.

Reconcile dispute funds flows in settlements

The settlement.transaction_amount parameter indicates the total money movement related to disputes and transactions for a given settlement. You can reconcile this amount against transaction and dispute data by adding the amount parameters on the transactions and the dispute settlement details associated with the settlement object.

Find all DisputeSettlementDetails in a Settlement

To determine the disputes that are included in a specific settlement, you can list the disputes associated with the settlement.

Command Line

cURL

Example response:

Test mode

DisputeSettlementDetails aren’t available in test mode.