Identify the issuing_transaction.id to dispute; disputes can only be filed against settled (captured) transactions, not pending authorizations
POST /v1/issuing/disputes with transaction=<issuing_transaction_id> and evidence object; the evidence must include a reason (one of canceled, duplicate, fraudulent, merchandise_not_as_described, not_received, other, service_not_as_described) with matching sub-fields
For reason=not_received, include evidence.not_received.expected_at (Unix timestamp) and optionally a product_description; for reason=fraudulent, include evidence.fraudulent.explanation
After creation the dispute has status=unsubmitted; call POST /v1/issuing/disputes/<id>/submit to formally submit it to the card network
Monitor the issuing_dispute.updated webhook for status transitions to submitted, won, or lost; winning credits the cardholder's balance, losing does not
Known gotchas
The evidence sub-object fields required differ by reason code; submitting with missing required fields will result in a 400 error or a weak evidence package
Issuing disputes have network-imposed deadlines; submit well before the deadline to avoid automatic denial
You cannot dispute a transaction that was already refunded by the merchant; Stripe will reject the dispute submission in this case
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?