# 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](https://support.stripe.com/) 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:

```json
{ 
 "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

| Dispute lifecycle stage | event_type value | Conceptual money movement |
| --- | --- | --- |
| The dispute is submitted to the network. | `filing` | Credit to issuer |
| The business contests a dispute (for example, representment or pre-arbitration). | `representment` | Debit to issuer |
| The issuer wins the dispute at any stage. | `win` | Credit to issuer |
| The issuer loses the dispute at any stage. | `loss` | Debit to issuer. |

> 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](https://docs.stripe.com/api/issuing/dispute-settlement-detail/list.md) associated with the settlement.

```curl
curl https://api.stripe.com/v1/issuing/dispute_settlement_details \
  -u "<<YOUR_SECRET_KEY>>:"
```

Example response:

```json
{ 
 "object": "list", 
 "url": "/v1/issuing/dispute_settlement_details", 
 "has_more": false, 
 "data": [ 
{ 
 "id": "idpsd_1MzFN1K8M4JkH0lBmFq8CqBS", 
 "object": "issuing.dispute_settlement_detail", 
 "amount": 1000, "card": "{{CARD_ID}}", 
 "cardholder": "{{CARDHOLDER_ID}}", 
 "created": 1743532000, 
 "currency": "usd", 
 "livemode": true, 
 "event_type": "win", 
 "settlement": "ise_1R9Op42j5ohbiDWAVaavpeVG", 
 "network": "visa", 
 "network_data": { "processing_date": "2024-08-06" } 
} 
    ] 
}
```

## Test mode

`DisputeSettlementDetails` aren’t available in test mode.