Stripe: Post Charges Charge Dispute

← Charges operations · Get started

Operation stripe.postchargeschargedispute

Provider route: POST /v1/charges/{charge}/dispute. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["charges"]["postChargesChargeDispute"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.charges.postChargesChargeDispute(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.charges.post_charges_charge_dispute(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.charge	string	Required within parent	Maximum length: 5000
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	Model	Optional	Expand Post Charges Charge Dispute — request body — body

Referenced models: Post Charges Charge Dispute — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Close a dispute — response body

Referenced models: Close a dispute — response body

Schemas

711 more schemas are linked from the tables above, on the schema pages.

Close a dispute — response body

Field	Type	Presence	Description and constraints
$	object	Root	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. Related guide: [Disputes and fraud](https://docs.stripe.com/disputes)
amount	JSON	Required within parent
amount (anyOf 1)	integer	Alternative	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).
amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
balance_transactions	array	Required within parent	List of zero, one, or two balance transactions that show funds withdrawn and reinstated to your Stripe account as a result of this dispute.
balance_transactions[]	Model	Each item	Expand Retrieve a balance transaction — balance get Balance History Id — response body
charge	JSON	Required within parent	ID of the charge that's disputed.
charge (anyOf 1)	string	Alternative	Maximum length: 5000
charge (anyOf 2)	Model	Alternative	Expand Create a charge — response body
created	JSON	Required within parent
created (anyOf 1)	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
created (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
currency	string	Required within parent	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). Format: currency
enhanced_eligibility_types	array	Required within parent	List of eligibility types that are included in `enhanced_evidence`.
enhanced_eligibility_types[]	string	Each item	Known values: mastercard_compliance, visa_compelling_evidence_3, visa_compliance
evidence	Model	Required within parent	Expand Close a dispute — response body — evidence
evidence_details	Model	Required within parent	Expand Close a dispute — response body — evidence details
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
is_charge_refundable	boolean	Required within parent	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	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadata	object	Required within parent	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. Additional keys: see wildcard field
metadata.*	string	Additional keys	Maximum length: 500
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: dispute
payment_intent	JSON	Optional
payment_intent (anyOf 1)	JSON	Alternative	ID of the PaymentIntent that's disputed.
payment_intent (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
payment_intent (anyOf 1) (anyOf 2)	Model	Alternative	Expand Cancel a Payment Intent — response body
payment_intent (anyOf 2)	null	Alternative
payment_method_details	Model	Optional	Expand Close a dispute — response body — payment method details
reason	string	Required within parent	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). Maximum length: 5000
status	string	Required within parent	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`. Known values: lost, needs_response, prevented, under_review, warning_closed, warning_needs_response, warning_under_review, won

Referenced models: Retrieve a balance transaction — balance get Balance History Id — response body, Create a charge — response body, Close a dispute — response body — evidence, Close a dispute — response body — evidence details, Close a dispute — response body — payment method details, Cancel a Payment Intent — response body

Post Charges Charge Dispute — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
evidence	Model	Optional	Expand Post Charges Charge Dispute — request body — body evidence
expand	array	Optional	Specifies which fields in the response should be expanded.
expand[]	string	Each item	Maximum length: 5000
metadata	JSON	Optional	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`.
metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
metadata (anyOf 1).*	string	Additional keys
metadata (anyOf 2)	string	Alternative	One of:
submit	boolean	Optional	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).

Referenced models: Post Charges Charge Dispute — request body — body evidence

Close a dispute — response body — evidence details

Field	Type	Presence	Description and constraints
$	object	Root
due_by	JSON	Optional
due_by (anyOf 1)	JSON	Alternative
due_by (anyOf 1) (anyOf 1)	integer	Alternative	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. Format: unix-time
due_by (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
due_by (anyOf 2)	null	Alternative
enhanced_eligibility	Model	Required within parent	Expand Close a dispute — response body — evidence details enhanced eligibility
has_evidence	boolean	Required within parent	Whether evidence has been staged for this dispute.
past_due	boolean	Required within parent	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	JSON	Required within parent
submission_count (anyOf 1)	integer	Alternative	The number of times evidence has been submitted. Typically, you may only submit evidence once.
submission_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Close a dispute — response body — evidence details enhanced eligibility

Close a dispute — response body — payment method details

Field	Type	Presence	Description and constraints
$	object	Root
amazon_pay	Model	Optional	Expand Close a dispute — response body — payment method details amazon pay
card	Model	Optional	Expand Close a dispute — response body — payment method details card
klarna	Model	Optional	Expand Close a dispute — response body — payment method details klarna
paypal	Model	Optional	Expand Close a dispute — response body — payment method details paypal
type	string	Required within parent	Payment method type. Known values: amazon_pay, card, klarna, paypal

Referenced models: Close a dispute — response body — payment method details amazon pay, Close a dispute — response body — payment method details card, Close a dispute — response body — payment method details klarna, Close a dispute — response body — payment method details paypal

Create a Payment Method — response body — zip

Field	Type	Presence	Description and constraints
$	object	Root

Policy, approvals and errors

SDK function policy ID: stripe.postchargeschargedispute. Catalog operation: PostChargesChargeDispute. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source