Charges
post/v1/charges/{charge}/dispute

PostChargesChargeDispute

Path parameters

NameDescription
charge*

Request body

FieldTypeDescription
evidenceobject

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.

28 nested fields
FieldTypeDescription
access_activity_logstring
billing_addressstring
cancellation_policystring
cancellation_policy_disclosurestring
cancellation_rebuttalstring
customer_communicationstring
customer_email_addressstring
customer_namestring
customer_purchase_ipstring
customer_signaturestring
duplicate_charge_documentationstring
duplicate_charge_explanationstring
duplicate_charge_idstring
enhanced_evidenceobject | string
product_descriptionstring
receiptstring
refund_policystring
refund_policy_disclosurestring
refund_refusal_explanationstring
service_datestring
service_documentationstring
shipping_addressstring
shipping_carrierstring
shipping_datestring
shipping_documentationstring
shipping_tracking_numberstring
uncategorized_filestring
uncategorized_textstring
expandarray<string>

Specifies which fields in the response should be expanded.

metadataobject | string

Set of key-value pairs 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.

submitboolean

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).

Response

FieldTypeDescription
amount*integer

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_transactions*array<balance_transaction>

List of zero, one, or two balance transactions that show funds withdrawn and reinstated to your Stripe account as a result of this dispute.

array item fields
FieldTypeDescription
amount*integer

Gross amount of this transaction (in cents (or local equivalent)). A positive value represents funds charged to another party, and a negative value represents funds sent to another party.

available_on*integer (unix-time)

The date that the transaction's net funds become available in the Stripe balance.

balance_type*string

The balance that this transaction impacts.

created*integer (unix-time)

Time at which the object was created. Measured in seconds since the Unix epoch.

currency*string (currency)

Three-letter ISO currency code, in lowercase. Must be a supported currency.

descriptionstring

An arbitrary string attached to the object. Often useful for displaying to users.

exchange_ratenumber

If applicable, this transaction uses an exchange rate. If money converts from currency A to currency B, then the amount in currency A, multipled by the exchange_rate, equals the amount in currency B. For example, if you charge a customer 10.00 EUR, the PaymentIntent's amount is 1000 and currency is eur. If this converts to 12.34 USD in your Stripe account, the BalanceTransaction's amount is 1234, its currency is usd, and the exchange_rate is 1.234.

fee*integer

Fees (in cents (or local equivalent)) paid for this transaction. Represented as a positive integer when assessed.

fee_details*array<fee>

Detailed breakdown of fees (in cents (or local equivalent)) paid for this transaction.

id*string

Unique identifier for the object.

net*integer

Net impact to a Stripe balance (in cents (or local equivalent)). A positive value represents incrementing a Stripe balance, and a negative value decrementing a Stripe balance. You can calculate the net impact of a transaction on a balance by amount - fee

object*string

String representing the object's type. Objects of the same type share the same value.

reporting_category*string

Learn more about how reporting categories can help you understand balance transactions from an accounting perspective.

sourcestring | application_fee | charge | connect_collection_transfer | customer_cash_balance_transaction | dispute

This transaction relates to the Stripe object.

status*string

The transaction's net funds status in the Stripe balance, which are either available or pending.

type*string

Transaction type: tax_fund, adjustment, advance, advance_funding, anticipation_repayment, application_fee, application_fee_refund, charge, climate_order_purchase, climate_order_refund, connect_collection_transfer, contribution, inbound_transfer, inbound_transfer_reversal, issuing_authorization_hold, issuing_authorization_release, issuing_dispute, issuing_transaction, obligation_outbound, obligation_reversal_inbound, payment, payment_failure_refund, payment_network_reserve_hold, payment_network_reserve_release, payment_refund, payment_reversal, payment_unreconciled, payout, payout_cancel, payout_failure, payout_minimum_balance_hold, payout_minimum_balance_release, refund, refund_failure, reserve_transaction, reserved_funds, reserve_hold, reserve_release, stripe_fee, stripe_fx_fee, stripe_balance_payment_debit, stripe_balance_payment_debit_reversal, tax_fee, topup, topup_reversal, transfer, transfer_cancel, transfer_failure, transfer_refund, or fee_credit_funding. Learn more about balance transaction types and what they represent. To classify transactions for accounting purposes, consider reporting_category instead.

charge*string | charge

ID of the charge that's disputed.

created*integer (unix-time)

Time at which the object was created. Measured in seconds since the Unix epoch.

currency*string (currency)

Three-letter ISO currency code, in lowercase. Must be a supported currency.

enhanced_eligibility_types*array<string>

List of eligibility types that are included in enhanced_evidence.

evidence*dispute_evidence
28 nested fields
FieldTypeDescription
access_activity_logstring

Any server or activity logs showing proof that the customer accessed or downloaded the purchased digital product. This information should include IP addresses, corresponding timestamps, and any detailed recorded activity.

billing_addressstring

The billing address provided by the customer.

cancellation_policystring | file

(ID of a file upload) Your subscription cancellation policy, as shown to the customer.

cancellation_policy_disclosurestring

An explanation of how and when the customer was shown your refund policy prior to purchase.

cancellation_rebuttalstring

A justification for why the customer's subscription was not canceled.

customer_communicationstring | file

(ID of a file upload) Any communication with the customer that you feel is relevant to your case. Examples include emails proving that the customer received the product or service, or demonstrating their use of or satisfaction with the product or service.

customer_email_addressstring

The email address of the customer.

customer_namestring

The name of the customer.

customer_purchase_ipstring

The IP address that the customer used when making the purchase.

customer_signaturestring | file

(ID of a file upload) A relevant document or contract showing the customer's signature.

duplicate_charge_documentationstring | file

(ID of a file upload) Documentation for the prior charge that can uniquely identify the charge, such as a receipt, shipping label, work order, etc. This document should be paired with a similar document from the disputed payment that proves the two payments are separate.

duplicate_charge_explanationstring

An explanation of the difference between the disputed charge versus the prior charge that appears to be a duplicate.

duplicate_charge_idstring

The Stripe ID for the prior charge which appears to be a duplicate of the disputed charge.

enhanced_evidence*dispute_enhanced_evidence
product_descriptionstring

A description of the product or service that was sold.

receiptstring | file

(ID of a file upload) Any receipt or message sent to the customer notifying them of the charge.

refund_policystring | file

(ID of a file upload) Your refund policy, as shown to the customer.

refund_policy_disclosurestring

Documentation demonstrating that the customer was shown your refund policy prior to purchase.

refund_refusal_explanationstring

A justification for why the customer is not entitled to a refund.

service_datestring

The date on which the customer received or began receiving the purchased service, in a clear human-readable format.

service_documentationstring | file

(ID of a file upload) Documentation showing proof that a service was provided to the customer. This could include a copy of a signed contract, work order, or other form of written agreement.

shipping_addressstring

The address to which a physical product was shipped. You should try to include as complete address information as possible.

shipping_carrierstring

The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, please separate them with commas.

shipping_datestring

The date on which a physical product began its route to the shipping address, in a clear human-readable format.

shipping_documentationstring | file

(ID of a file upload) Documentation showing proof that a product was shipped to the customer at the same address the customer provided to you. This could include a copy of the shipment receipt, shipping label, etc. It should show the customer's full shipping address, if possible.

shipping_tracking_numberstring

The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.

uncategorized_filestring | file

(ID of a file upload) Any additional evidence or statements.

uncategorized_textstring

Any additional evidence or statements.

evidence_details*dispute_evidence_details
5 nested fields
FieldTypeDescription
due_byinteger (unix-time)

Date by which evidence must be submitted in order to successfully challenge dispute. Will be 0 if the customer's bank or credit card company doesn't allow a response for this particular dispute.

enhanced_eligibility*dispute_enhanced_eligibility
has_evidence*boolean

Whether evidence has been staged for this dispute.

past_due*boolean

Whether the last evidence submission was submitted past the due date. Defaults to false if no evidence submissions have occurred. If true, then delivery of the latest evidence is *not* guaranteed.

submission_count*integer

The number of times evidence has been submitted. Typically, you may only submit evidence once.

id*string

Unique identifier for the object.

is_charge_refundable*boolean

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.

livemode*boolean

If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.

metadata*object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

object*string

String representing the object's type. Objects of the same type share the same value.

payment_intentstring | payment_intent

ID of the PaymentIntent that's disputed.

payment_method_detailsdispute_payment_method_details
5 nested fields
FieldTypeDescription
amazon_paydispute_payment_method_details_amazon_pay
carddispute_payment_method_details_card
klarnadispute_payment_method_details_klarna
paypaldispute_payment_method_details_paypal
type*string

Payment method type.

reason*string

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.

status*string

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.