# How to submit Issuing disputes

Learn the different ways to submit Issuing disputes.

You can create, update, and submit disputes through the Stripe Dashboard or the API. This guide explains each step, from filing a dispute to understanding the outcome.

## Creation 

Enter the disputed amount (full or partial) in the **Dispute Amount** field. It defaults to the full transaction amount.

Account for any refunds or cases where only a partial amount should be disputed. For more information, see [Dispute amount](https://docs.stripe.com/issuing/purchases/disputes.md#dispute-amount).

#### Dashboard

When viewing an eligible transaction, click **Dispute transaction** to redirect to a form that requests different information based on the dispute reason and product type (merchandise, services or digital goods). We create a dispute the first time you click **Save**. If you click **Submit** without saving, we create a dispute and then submit it.

After you submit a dispute, you can’t modify the information or resubmit the dispute.

#### API - Issuing-only

Use the [Create](https://docs.stripe.com/api/issuing/disputes/create.md) method by specifying the [Transaction](https://docs.stripe.com/api/issuing/transactions/object.md) you want to dispute. You must also specify an `evidence` object whose `reason` determines its other fields. In these examples, `not_received` is populated because `reason` takes the value `"not_received"`.

```curl
curl https://api.stripe.com/v1/issuing/disputes \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "transaction={{ISSUINGTRANSACTION_ID}}" \
  -d "evidence[reason]=not_received" \
  -d "evidence[not_received][expected_at]=1590000000" \
  -d "evidence[not_received][explanation]=Never shipped" \
  -d "evidence[not_received][product_description]=Baseball bat" \
  -d "evidence[not_received][product_type]=merchandise"
```

Learn more in the [Dispute reasons](https://docs.stripe.com/issuing/purchases/disputes/dispute-reasons.md) guide. When you create a dispute, all evidence fields are optional so you can collect more evidence before submitting.

All Issuing dispute API methods return a [Dispute](https://docs.stripe.com/api/issuing/disputes/object.md) object.

#### API - Issuing with Treasury for platforms

Use the [Create](https://docs.stripe.com/api/issuing/disputes/create.md) method by specifying the [ReceivedDebit](https://docs.stripe.com/api/treasury/received_debits.md) you want to dispute. You must also specify an `evidence` object whose `reason` determines its other fields. In these examples, `not_received` is populated because `reason` takes the value `"not_received"`.

```curl
curl https://api.stripe.com/v1/issuing/disputes \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "treasury[received_debit]=rd_1KsVPhACgxNDEoMCiKgN6Fm4" \
  -d "evidence[reason]=not_received" \
  -d "evidence[not_received][expected_at]=1590000000" \
  -d "evidence[not_received][explanation]=Never shipped" \
  -d "evidence[not_received][product_description]=Baseball bat" \
  -d "evidence[not_received][product_type]=merchandise"
```

Learn more in the [Dispute reasons](https://docs.stripe.com/issuing/purchases/disputes/dispute-reasons.md) guide. When you create a dispute, all evidence fields are optional so you can collect more evidence before submitting.

All Issuing dispute API methods return a [Dispute](https://docs.stripe.com/api/issuing/disputes/object.md) object.

## Update 

#### Dashboard

Use the **Unsubmitted** tab to access disputes in progress. The **Submit before** date shows when the dispute expires.

From the dispute page, click **Edit submission** to update the evidence.

#### API

Use the [Update](https://docs.stripe.com/api/issuing/disputes/update.md) method to update the evidence and [metadata](https://docs.stripe.com/api/metadata.md) of unsubmitted disputes. For submitted disputes, you can only update metadata.

The table below describes possible updates to `evidence`. In this example, `evidence` starts in this state:

```json
"evidence": {
  "reason": "not_received",
  "not_received": {
    "additional_documentation": null, // We refer to these as "evidence fields"
    "expected_at": null,
    "explanation": "Not shipped",
    "product_description": "Baseball cards",
    "product_type": "merchandise"
  }
}
```

| Action | Input | Result |
| --- | --- | --- |
| Add, replace, and remove evidence fields | ```json
"evidence": {
  "reason": "not_received",
  "not_received": {
    // Add
    "expected_at": 1590000000,
    // Replace
    "explanation": "Lost",
    // Remove
    "product_description": ""
  }
}
``` | ```json
"evidence": {
  "reason": "not_received",
  "not_received": {
    "additional_documentation": null,
    "expected_at": 1590000000,
    "explanation": "Lost",
    "product_description": "",
    "product_type": "merchandise"
  }
}
``` |
| Change reason | ```json
"evidence": {
  "reason": "fraudulent"
}
``` | ```json
"evidence": {
  "reason": "fraudulent",
  "fraudulent": {
    "additional_documentation": null,
    // Copied from "not_received"
    "explanation": "Not shipped"
  }
}
``` |
| Update evidence fields without supplying reason | ```json
"evidence": {
  "not_received": {
    "explanation": "Lost"
  }
}
``` | Error. The `evidence` object must always contain the `reason` field. |
| Unset all evidence fields | ```json
"evidence": {
  "reason": "not_received",
  "not_received": ""
}
``` | ```json
"evidence": {
  "reason": "not_received",
  "not_received": {
    "additional_documentation": null,
    "expected_at": null,
    "explanation": null,
    "product_description": null,
    "product_type": null
  }
}
``` |

## Evidence 

Provide as much relevant information as possible when submitting a dispute, such as email correspondence, card statements, or return shipment tracking. Files must be in PDF or JPEG format and can’t exceed 5 MB. Before submitting, make sure all text and images are legible on a black-and-white fax.

Include all evidence in the file. Don’t link to information that’s hosted externally.

## Submission 

Submit your dispute after gathering all required evidence for the dispute reason.

> Review the evidence thoroughly, because you can’t modify dispute information after submitting the dispute.

#### Dashboard

The **Submit** button on the evidence form is enabled when all required evidence is present.

#### API

The [Submit](https://docs.stripe.com/api/issuing/dispute/submit.md) endpoint validates that all required evidence for the dispute reason is present. For more details, see [Dispute reasons](https://docs.stripe.com/issuing/purchases/disputes/dispute-reasons.md).

```curl
curl -X POST https://api.stripe.com/v1/issuing/disputes/idp_1GW0GkKA9rkJS7vmeJlLI1Gp/submit \
  -u "<<YOUR_SECRET_KEY>>:"
```

## Resolution 

#### Dashboard

Stripe updates the dispute status when we hear back from the card network.

If you win, the dispute status changes to `won` and we credit your Issuing balance in the form of an `issuing_dispute` [balance transaction](https://docs.stripe.com/reports/balance-transaction-types.md#issuing_related). You can access the balance transaction in the Dashboard under [All transactions](https://dashboard.stripe.com/balance) and at the bottom of the dispute details page.

> If you make a transaction in a currency other than your account’s default currency (for example, a GBP transaction that your USD card pays), Stripe refunds the won dispute in the transaction’s original currency.

If you lose, the dispute status changes to `lost` and we don’t credit any amount to your Issuing balance.

#### API

Stripe updates dispute statuses when we hear back from the card network. If the acquiring business wins the dispute, the status changes to `lost` and we don’t transfer any funds.

If you win, the dispute status changes to `won` and we transfer funds back to your Issuing balance. The credit to your account appears as a [balance transaction](https://docs.stripe.com/reports/balance-transaction-types.md#issuing_related) of type `issuing_dispute`.

The balance transaction appears under `balance_transactions` on the `Dispute` object. Stripe doesn’t return this field by default. Use the `expand` field to retrieve it. For more details, see [Expand](https://docs.stripe.com/expand.md).

If you make a transaction in a currency that’s different from your account’s default currency (for example, a GBP charge on a USD card), Stripe refunds the won dispute in the transaction’s original currency.

## Testing 

#### Dashboard

Stripe’s *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) environments let you test dispute logic without affecting your live account. For example, Stripe sends webhook events, creates [balance transactions](https://docs.stripe.com/reports/balance-transaction-types.md), and updates your test Issuing balance without moving any funds or changing any balances on your live account.

Similar to live mode, a test dispute transitions to `expired` 110 days after the transaction is captured.

When you submit a test dispute in the Dashboard, you can choose the dispute’s outcome. Selecting **Won** automatically sets the `explanation` field to `winning_evidence`, and selecting **Lost** sets it to `losing_evidence`.

#### API

Stripe processes test disputes the same way as live disputes to demonstrate the expected behavior. For example, Stripe sends webhook events, creates [balance transactions](https://docs.stripe.com/reports/balance-transaction-types.md), and updates your Issuing balance, all within seconds of submitting the dispute.

In the API, set the `explanation` field to `winning_evidence` or `losing_evidence` to transition the dispute to `won` or `lost`. Otherwise, the dispute transitions to `submitted` status as it would in live mode.

Similar to live mode, a test dispute transitions to `expired` 110 days after the transaction is captured.

## Webhooks

Listen for Issuing dispute [webhook events](https://docs.stripe.com/webhooks.md) to track changes to your disputes. Each event includes the updated [Dispute](https://docs.stripe.com/api/.md#issuing_dispute_object) object.

| Webhook events | Trigger |
| --- | --- |
| `issuing_dispute.created` | Dispute created. |
| `issuing_dispute.updated` | Dispute updated. |
| `issuing_dispute.submitted` | Dispute submitted. |
| `issuing_dispute.funds_reinstated` | Funds transferred to your Issuing balance, typically when a dispute is `won`. |
| `issuing_dispute.funds_rescinded` | Funds deducted from your Issuing balance, typically with a provisional credit clawback. |
| `issuing_dispute.closed` | Dispute transitioned to a `won`, `lost`, or `expired` status. |

## Withdrawing

Stripe can withdraw a dispute only within 24 hours of its submission to the card network. To withdraw a dispute, contact [Stripe Support](https://support.stripe.com/contact) immediately.

## Email connected accounts

Issuing platforms must send [regulated notices](https://docs.stripe.com/issuing/compliance-us/issuing-regulated-customer-notices.md) to connected accounts when a dispute is submitted and again when it’s won or lost.

## Use with Treasury for platforms

When you dispute `ReceivedDebits` on `FinancialAccounts`, Stripe creates a corresponding [DebitReversal](https://docs.stripe.com/api/treasury/debit_reversals.md) after submission.