Sample - Stripe API
POST/v1/charges/{charge}/dispute

Submit evidence for a charge dispute

Updates the evidence associated with the dispute for a charge and can submit that evidence to the bank. Supply evidence fields to respond to the dispute, and use submit to control whether the evidence is submitted immediately. Updating any evidence field submits the complete evidence set for review when submission is enabled.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 4 body fields
chargestringrequired
The unique identifier of the charge with the dispute. Maximum 5,000 characters.

Optional form-encoded dispute evidence and submission settings.

evidenceobjectoptional
Evidence to upload, to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review. The combined character count of all fields is limited to 150,000.
expandarray<string>optional
Specifies which fields in the response should be expanded.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
submitbooleanoptional
Whether to immediately submit evidence to the bank. If `false`, evidence is staged on the dispute. Staged evidence is visible in the API and Dashboard, and can be submitted to the bank by making another request with this attribute set to `true` (the default).

2 status codes
200Returns the updated dispute object, including its evidence, submission state, status, and review details.
amountintegerrequired
Disputed amount. Usually the amount of the charge, but it can differ (usually because of currency fluctuation or because only part of the order is disputed).
balance_transactionsarray<BalanceTransaction>required
List of zero, one, or two balance transactions that show funds withdrawn and reinstated to your Stripe account as a result of this dispute.
chargestringrequired
ID of the charge that's disputed.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
currencystringrequired
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
enhanced_eligibility_typesarray<string>required
List of eligibility types that are included in `enhanced_evidence`.
evidenceobjectrequired
evidence_detailsobjectrequired
idstringrequired
Unique identifier for the object.
is_charge_refundablebooleanrequired
If true, it's still possible to refund the disputed payment. After the payment has been fully refunded, no further funds are withdrawn from your Stripe account as a result of this dispute.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadataobjectrequired
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:dispute
payment_intentstringoptional
ID of the PaymentIntent that's disputed.
payment_method_detailsobjectoptional
reasonstringrequired
Reason given by cardholder for dispute. Possible values are `bank_cannot_process`, `check_returned`, `credit_not_processed`, `customer_initiated`, `debit_not_authorized`, `duplicate`, `fraudulent`, `general`, `incorrect_account_details`, `insufficient_funds`, `noncompliant`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, or `unrecognized`. Learn more about [dispute reasons](https://docs.stripe.com/disputes/categories).
statusstringrequired
The current status of a dispute. Possible values include:`warning_needs_response`, `warning_under_review`, `warning_closed`, `needs_response`, `under_review`, `won`, `lost`, or `prevented`.
Allowed:lostneeds_responsepreventedunder_reviewwarning_closedwarning_needs_responsewarning_under_reviewwon
defaultReturns an error object when the dispute evidence cannot be updated or submitted.
errorobjectrequired

Error handling

charge must identify the charge with the dispute and must not exceed 5,000 characters. The combined character count of evidence fields must not exceed 150,000, and submit must be a boolean; individual evidence fields must satisfy their declared length limits.