Disputes

As a card issuer, you can dispute transactions that the cardholder does not recognize, suspects to be fraudulent, or has other issues with.

Related guide: Issuing disputes

Was this section helpful? Yes No

Create a dispute

POST / v1 / issuing / disputes

Update a dispute

POST / v1 / issuing / disputes /:id

Retrieve a dispute

GET / v1 / issuing / disputes /:id

List all disputes

GET / v1 / issuing / disputes

Submit a dispute

POST / v1 / issuing / disputes /:id / submit

The Dispute object

Attributes

• id string Unique identifier for the object.
• amount integer Disputed amount in the card’s currency and in the smallest currency unit. Usually the amount of the transaction, but can differ (usually because of currency fluctuation).
• balance _ transactions nullable array of objects Includable List of balance transactions associated with the dispute.
• currency enum The currency the transaction was made in.
• evidence object Evidence for the dispute. Evidence contains exactly two non-null fields: the reason for the dispute and the associated evidence field for the selected reason.
• metadata map 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.
• status enum Current status of the dispute. Possible enum values expired The dispute has expired. lost The dispute is lost. submitted The dispute has been submitted to Stripe. unsubmitted The dispute is pending submission to Stripe. won The dispute is won.
• transaction string Expandable The transaction being disputed.

More attributes

• object string, value is "issuing.dispute"
• created timestamp
• livemode boolean
• loss _ reason nullable enum

The Dispute object

{ "id": "idp_1MykdxFtDWhhyHE1BFAV3osZ", "object": "issuing.dispute", "amount": 100, "created": 1681947753, "currency": "usd", "evidence": { "fraudulent": { "additional_documentation": null, "dispute_explanation": null, "explanation": "This transaction is fraudulent.", "uncategorized_file": null }, "reason": "fraudulent" }, "livemode": false, "metadata": {}, "status": "unsubmitted", "transaction": "ipi_1MykXhFtDWhhyHE1UjsZZ3xQ"}

Create a dispute

POST / v1 / issuing / disputes

Creates an Issuing Dispute object. Individual pieces of evidence within the evidence object are optional at this point. Stripe only validates that required evidence is present during submission. Refer to Dispute reasons and evidence for more details about evidence requirements.

Parameters

• evidence object Evidence provided for the dispute.
• metadata map 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.
• transaction string The ID of the issuing transaction to create a dispute for. For transaction on Treasury FinancialAccounts, use treasury.received_debit.

More parameters

• amount integer

Returns

Returns an Issuing Dispute object in unsubmitted status if creation succeeds.

Response

{ "id": "idp_1MykdxFtDWhhyHE1BFAV3osZ", "object": "issuing.dispute", "amount": 100, "created": 1681947753, "currency": "usd", "evidence": { "fraudulent": { "additional_documentation": null, "dispute_explanation": null, "explanation": "This transaction is fraudulent.", "uncategorized_file": null }, "reason": "fraudulent" }, "livemode": false, "metadata": {}, "status": "unsubmitted", "transaction": "ipi_1MykXhFtDWhhyHE1UjsZZ3xQ"}