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.
openapi: 3.0.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:
GetDisputesRequest:
type: object
properties: {}
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`.
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](https://stripe.com/docs/issuing/purchases/transactions)'
properties:
amount:
description: The transaction amount, which will be reflected in your balance. This amount is in your currency and in the [smallest currency unit](https://stripe.com/docs/currencies#zero-decimal).
type: integer
amount_details:
anyOf:
- $ref: '#/components/schemas/issuing_transaction_amount_details'
description: Detailed breakdown of amount components. These amounts are denominated in `currency` and in the [smallest currency unit](https://stripe.com/docs/currencies#zero-decimal).
nullable: true
authorization:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/issuing.authorization'
description: The `Authorization` object that led to this transaction.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/issuing.authorization'
balance_transaction:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/balance_transaction'
description: ID of the [balance transaction](https://stripe.com/docs/api/balance_transactions) associated with this transaction.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/balance_transaction'
card:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/issuing.card'
description: The card used to make this transaction.
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/issuing.card'
cardholder:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/issuing.cardholder'
description: The cardholder to whom this transaction belongs.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/issuing.cardholder'
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
currency:
description: 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).
type: string
dispute:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/issuing.dispute'
description: If you've disputed the transaction, the ID of the dispute.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/issuing.dispute'
id:
description: Unique identifier for the object.
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
merchant_amount:
description: The amount that the merchant will receive, denominated in `merchant_currency` and in the [smallest currency unit](https://stripe.com/docs/currencies#zero-decimal). It will be different from `amount` if the merchant is taking payment in a different currency.
type: integer
merchant_currency:
description: The currency with which the merchant is taking payment.
type: string
merchant_data:
$ref: '#/components/schemas/issuing_authorization_merchant_data'
metadata:
additionalProperties:
maxLength: 500
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.
type: object
network_data:
anyOf:
- $ref: '#/components/schemas/issuing_transaction_network_data'
description: Details about the transaction, such as processing dates, set by the card network.
nullable: true
object:
description: String re
# --- 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