API reference
Test mode. Use your secret key on your server; live processing is currently disabled.
https://api.knoxapi.comSend form-encoded requests with Authorization: Bearer sk_test_....
Complete OpenAPI specification · Integration guide
Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.
GET /v1/disputes
List all disputes
Returns a list of your disputes.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
charge | query | string | Only return disputes associated to the charge specified by this charge ID. |
created | query | one of multiple schemas | Only return disputes that were created during the given date interval. |
ending_before | query | string | 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. |
expand | query | array of string | Specifies which fields in the response should be expanded. |
limit | query | integer | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. |
payment_intent | query | string | Only return disputes associated to the PaymentIntent specified by this PaymentIntent ID. |
starting_after | query | string | 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. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
data required | array of dispute | |
has_more required | boolean | True if this list has another page of items after this one that can be fetched. |
object required | string | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. |
url required | string | The URL where this list can be accessed. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
GET /v1/disputes/{dispute}
Retrieve a dispute
Retrieves the dispute with the given ID.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
dispute | path | string | |
expand | query | array of string | Specifies which fields in the response should be expanded. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
amount required | 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 required | array of 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. |
charge required | one of multiple schemas | ID of the charge that's disputed. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
currency required | string | 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_types required | array of string | List of eligibility types that are included in `enhanced_evidence`. |
evidence required | dispute_evidence | |
evidence_details required | dispute_evidence_details | |
id required | string | Unique identifier for the object. |
is_charge_refundable required | 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 required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
metadata required | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
payment_intent | one of multiple schemas | ID of the PaymentIntent that's disputed. |
payment_method_details | dispute_payment_method_details | |
reason required | 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](https://docs.stripe.com/disputes/categories). |
status required | 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`. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
POST /v1/disputes/{dispute}
Update a dispute
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 dashboard, but if you prefer, you can use the API to submit evidence programmatically. 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 guide to dispute types.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
dispute | path | string |
| Field | Type | Description |
|---|---|---|
evidence | object | 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. |
expand | array of string | Specifies which fields in the response should be expanded. |
metadata | one of multiple schemas | 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`. |
submit | boolean | 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). |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
amount required | 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 required | array of 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. |
charge required | one of multiple schemas | ID of the charge that's disputed. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
currency required | string | 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_types required | array of string | List of eligibility types that are included in `enhanced_evidence`. |
evidence required | dispute_evidence | |
evidence_details required | dispute_evidence_details | |
id required | string | Unique identifier for the object. |
is_charge_refundable required | 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 required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
metadata required | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
payment_intent | one of multiple schemas | ID of the PaymentIntent that's disputed. |
payment_method_details | dispute_payment_method_details | |
reason required | 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](https://docs.stripe.com/disputes/categories). |
status required | 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`. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
POST /v1/disputes/{dispute}/close
Close a dispute
Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially dismissing the dispute (accepting it), acknowledging it as lost. The status of the dispute will change from needs_response to lost. Closing a dispute is irreversible.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
dispute | path | string |
| Field | Type | Description |
|---|---|---|
expand | array of string | Specifies which fields in the response should be expanded. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
amount required | 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 required | array of 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. |
charge required | one of multiple schemas | ID of the charge that's disputed. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
currency required | string | 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_types required | array of string | List of eligibility types that are included in `enhanced_evidence`. |
evidence required | dispute_evidence | |
evidence_details required | dispute_evidence_details | |
id required | string | Unique identifier for the object. |
is_charge_refundable required | 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 required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
metadata required | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
payment_intent | one of multiple schemas | ID of the PaymentIntent that's disputed. |
payment_method_details | dispute_payment_method_details | |
reason required | 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](https://docs.stripe.com/disputes/categories). |
status required | 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`. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |