A dispute occurs when a customer questions your charge with their card issuer. When this happens, you have the opportunity to respond to the dispute with evidence that shows that the charge is legitimate.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/stripe-disputes-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Stripe Accounts Account Disputes API
description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
contact:
email: dev-platform@stripe.com
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Disputes
paths:
/v1/disputes:
get:
description: <p>Returns a list of your disputes.</p>
operationId: GetDisputes
parameters:
- description: Only return disputes associated to the charge specified by this charge ID.
in: query
name: charge
required: false
schema:
maxLength: 5000
type: string
style: form
- explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: Only return disputes associated to the PaymentIntent specified by this PaymentIntent ID.
in: query
name: payment_intent
required: false
schema:
maxLength: 5000
type: string
style: form
- description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetDisputesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/DisputeList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Disputes
/v1/disputes/{dispute}:
get:
description: <p>Retrieves the dispute with the given ID.</p>
operationId: GetDisputesDispute
parameters:
- in: path
name: dispute
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetDisputesDisputeRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/dispute'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Disputes
post:
description: '<p>When you get a dispute, contacting your customer is always the best first step. If that doesn’t work, you can submit evidence to help us resolve the dispute in your favor. You can do this in your <a href="https://dashboard.stripe.com/disputes">dashboard</a>, but if you prefer, you can use the API to submit evidence programmatically.</p>
<p>Depending on your dispute type, different evidence fields will give you a better chance of winning your dispute. To figure out which evidence fields to provide, see our <a href="/docs/disputes/categories">guide to dispute types</a>.</p>'
operationId: PostDisputesDispute
parameters:
- in: path
name: dispute
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
evidence:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostDisputesDisputeRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/dispute'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Disputes
/v1/disputes/{dispute}/close:
post:
description: '<p>Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially dismissing the dispute, acknowledging it as lost.</p>
<p>The status of the dispute will change from <code>needs_response</code> to <code>lost</code>. <em>Closing a dispute is irreversible</em>.</p>'
operationId: PostDisputesDisputeClose
parameters:
- in: path
name: dispute
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostDisputesDisputeCloseRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/dispute'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Disputes
/v1/issuing/disputes:
get:
description: <p>Returns a list of Issuing <code>Dispute</code> objects. The objects are sorted in descending order by creation date, with the most recently created object appearing first.</p>
operationId: getIssuingDisputes
parameters:
- description: Select Issuing disputes that were created during the given date interval.
explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Select Issuing disputes with the given status.
in: query
name: status
required: false
schema:
enum:
- expired
- lost
- submitted
- unsubmitted
- won
type: string
style: form
- description: Select the Issuing dispute for the given transaction.
in: query
name: transaction
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetIssuingDisputesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/IssuingDisputeList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Issuing Disputes
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Disputes
post:
description: <p>Creates an Issuing <code>Dispute</code> object. Individual pieces of evidence within the <code>evidence</code> object are optional at this point. Stripe only validates that required evidence is present during submission. Refer to <a href="/docs/issuing/purchases/disputes#dispute-reasons-and-evidence">Dispute reasons and evidence</a> for more details about evidence requirements.</p>
operationId: postIssuingDisputes
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
evidence:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
treasury:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostIssuingDisputesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/issuing.dispute'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Issuing Disputes
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Disputes
/v1/issuing/disputes/{dispute}:
get:
description: <p>Retrieves an Issuing <code>Dispute</code> object.</p>
operationId: getIssuingDisputesDispute
parameters:
- in: path
name: dispute
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetIssuingDisputesDisputeRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/issuing.dispute'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Issuing Disputes
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Disputes
post:
description: <p>Updates the specified Issuing <code>Dispute</code> object by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Properties on the <code>evidence</code> object can be unset by passing in an empty string.</p>
operationId: postIssuingDisputesDispute
parameters:
- in: path
name: dispute
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
evidence:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostIssuingDisputesDisputeRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/issuing.dispute'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Issuing Disputes
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Disputes
components:
schemas:
issuing.token:
description: An issuing token object is created when an issued card is added to a digital wallet. As a [card issuer](https://stripe.com/docs/issuing), you can [view and manage these tokens](https://stripe.com/docs/issuing/controls/token-management) through Stripe.
properties:
card:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/issuing.card'
description: Card associated with this token.
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/issuing.card'
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
device_fingerprint:
description: The hashed ID derived from the device ID from the card network associated with the token
maxLength: 5000
type:
- string
- 'null'
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
last4:
description: The last four digits of the token.
maxLength: 5000
type: string
livemode:
description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
type: boolean
network:
description: The token service provider / card network associated with the token.
enum:
- mastercard
- visa
type: string
network_data:
$ref: '#/components/schemas/issuing_network_token_network_data'
network_updated_at:
description: Time at which the token was last updated by the card network. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- issuing.token
type: string
status:
description: The usage state of the token.
enum:
- active
- deleted
- requested
- suspended
type: string
wallet_provider:
description: The digital wallet for this token, if one was used.
enum:
- apple_pay
- google_pay
- samsung_pay
type: string
required:
- card
- created
- id
- livemode
- network
- network_updated_at
- object
- status
title: IssuingNetworkToken
type: object
x-expandableFields:
- card
- network_data
x-resourceId: issuing.token
GetIssuingDisputesDisputeRequest:
type: object
properties: {}
GetIssuingDisputesRequest:
type: object
properties: {}
DisputeList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/dispute'
type: array
has_more:
description: True if this list has another page of items after this one that can be fetched.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/disputes
type: string
PostIssuingDisputesDisputeRequest:
type: object
properties:
amount:
description: The dispute amount in the card's currency and in the [smallest currency unit](https://stripe.com/docs/currencies#zero-decimal).
type: integer
evidence:
description: Evidence provided for the dispute.
properties:
canceled:
anyOf:
- properties:
additional_documentation:
anyOf:
- type: string
- enum:
- ''
type: string
canceled_at:
anyOf:
- format: unix-time
type: integer
- enum:
- ''
type: string
cancellation_policy_provided:
anyOf:
- type: boolean
- enum:
- ''
type: string
cancellation_reason:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
expected_at:
anyOf:
- format: unix-time
type: integer
- enum:
- ''
type: string
explanation:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
product_description:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
product_type:
enum:
- ''
- merchandise
- service
type: string
return_status:
enum:
- ''
- merchant_rejected
- successful
type: string
returned_at:
anyOf:
- format: unix-time
type: integer
- enum:
- ''
type: string
title: canceled
type: object
- enum:
- ''
type: string
duplicate:
anyOf:
- properties:
additional_documentation:
anyOf:
- type: string
- enum:
- ''
type: string
card_statement:
anyOf:
- type: string
- enum:
- ''
type: string
cash_receipt:
anyOf:
- type: string
- enum:
- ''
type: string
check_image:
anyOf:
- type: string
- enum:
- ''
type: string
explanation:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
original_transaction:
maxLength: 5000
type: string
title: duplicate
type: object
- enum:
- ''
type: string
fraudulent:
anyOf:
- properties:
additional_documentation:
anyOf:
- type: string
- enum:
- ''
type: string
explanation:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
title: fraudulent
type: object
- enum:
- ''
type: string
merchandise_not_as_described:
anyOf:
- properties:
additional_documentation:
anyOf:
- type: string
- enum:
- ''
type: string
explanation:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
received_at:
anyOf:
- format: unix-time
type: integer
- enum:
- ''
type: string
return_description:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
return_status:
enum:
- ''
- merchant_rejected
- successful
type: string
returned_at:
anyOf:
- format: unix-time
type: integer
- enum:
- ''
type: string
title: merchandise_not_as_described
type: object
- enum:
- ''
type: string
not_received:
anyOf:
- properties:
additional_documentation:
anyOf:
- type: string
- enum:
- ''
type: string
expected_at:
anyOf:
- format: unix-time
type: integer
- enum:
- ''
type: string
explanation:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
product_description:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
product_type:
enum:
- ''
- merchandise
- service
type: string
title: not_received
type: object
- enum:
- ''
type: string
other:
anyOf:
- properties:
additional_documentation:
anyOf:
- type: string
- enum:
- ''
type: string
explanation:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
product_description:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
product_type:
enum:
- ''
- merchandise
- service
type: string
title: other
type: object
- enum:
- ''
type: string
reason:
enum:
- canceled
- duplicate
- fraudulent
- merchandise_not_as_described
- not_received
- other
- service_not_as_described
type: string
x-stripeBypassValidation: true
service_not_as_described:
anyOf:
- properties:
additional_documentation:
anyOf:
- type: string
- enum:
- ''
type: string
canceled_at:
anyOf:
- format: unix-time
type: integer
- enum:
- ''
type: string
cancellation_reason:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
explanation:
anyOf:
- maxLength: 1500
type: string
- enum:
- ''
type: string
received_at:
anyOf:
- format: unix-time
type: integer
- enum:
- ''
type: string
title: service_not_as_described
type: object
- enum:
- ''
type: string
title: evidence_param
type: object
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- enum:
- ''
type: string
description: Set of [key-value pairs](https://stripe.com/docs/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`.
IssuingDisputeList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/issuing.dispute'
type: array
has_more:
description: True if this list has another page of items after this one that can be fetched.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/issuing/disputes
type: string
issuing.transaction:
description: 'Any use of an [issued card](https://stripe.com/docs/issuing) that results in funds entering or leaving
your Stripe account, such as a completed purchase or refund, is represented by an Issuing
`Transaction` object.
Related guide: [Issued card transactions](ht
# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-disputes-api-openapi.yml