Challenging Disputes
Overview
Challenging a dispute means contesting it with evidence instead of accepting the loss. The flow has two parts: upload each evidence file to the dispute's active stage, then submit the evidence to finalize your response.
What you submit depends on the dispute's category. Fraud and authorization disputes take supporting documents only, while processing-error and consumer disputes can also carry an optional category-specific questionnaire.
Carry at least one of: a completed document on the active stage, questionnaire answers, or a submissionNote.
Upload evidence
Uploading evidence takes three mutations:
| Mutation | What it does |
|---|---|
initiateCardPaymentDisputeEvidenceUpload | Opens one upload session scoped to the dispute's active stage. |
createCardPaymentDisputeEvidenceUploadLink | Mints an upload link for a single file, and declares what that file is. |
submitCardPaymentDisputeEvidence | Closes the session and files the response. |
Open the session once, then for each file create an upload link, PUT the file to the link, and confirm the upload completed. Submit when every file is in.
Open an evidence upload session
Open a session for the dispute's active stage by passing the dispute's ID (cardPaymentDisputeId) to initiateCardPaymentDisputeEvidenceUpload:
mutation InitiateCardPaymentDisputeEvidenceUpload(
$input: InitiateCardPaymentDisputeEvidenceUploadInput!
) {
initiateCardPaymentDisputeEvidenceUpload(input: $input) {
... on CardPaymentDisputeEvidenceUploadSession {
documentUploadSessionId
expiresAt
}
... on UserError {
errors {
code
description
}
}
... on AccessDeniedError {
message
}
}
}
Create an upload link
Create one link per file with createCardPaymentDisputeEvidenceUploadLink, passing the session's documentUploadSessionId and the evidenceType that describes the file:
mutation CreateCardPaymentDisputeEvidenceUploadLink(
$input: CreateCardPaymentDisputeEvidenceUploadLinkInput!
) {
createCardPaymentDisputeEvidenceUploadLink(input: $input) {
... on CardPaymentDisputeEvidenceUploadLink {
id
evidenceType
uploadUrl
}
... on UserError {
errors {
code
description
}
}
... on AccessDeniedError {
message
}
}
}
| Field | Type | Description |
|---|---|---|
documentUploadSessionId | ID! | The session opened by initiateCardPaymentDisputeEvidenceUpload. |
evidenceType | CardPaymentDisputeStageEvidenceType! | What the file is. See Evidence types. |
Upload the file
PUT the file's raw bytes to the link's uploadUrl, with Content-Type set to the file's MIME type. The URL is signed—no Authorization header is needed. The maximum file size is 10 MB, and each link accepts a single file.
Accepted formats are PDF, JPEG, and TIFF. The set is the same on every card network, so a file accepted for one dispute is accepted for any.
The card network validates that a file's bytes really are the format declared, not just its label or extension. A macOS screenshot saved as .tiff, for example, is a valid little-endian TIFF but carries an alpha channel that falls outside baseline TIFF, and is rejected with E-123000029. Re-saved as JPEG, the same evidence uploads without trouble.
curl -X PUT "UPLOAD_URL" \
-H "Content-Type: image/jpeg" \
--data-binary "@evidence.jpg"
Upload links expire 5 minutes after creation. If a link expires before you upload, create a new one.
Check upload status
Uploaded files are scanned before they are stored. Check each CardPaymentDisputeEvidenceUploadLink's status with a node query:
query CheckCardPaymentDisputeEvidenceUploadLink($id: ID!) {
node(id: $id) {
... on CardPaymentDisputeEvidenceUploadLink {
id
status
evidenceType
updatedAt
}
}
}
| Status | Description |
|---|---|
PENDING | The link is waiting for a file to be uploaded. |
IN_PROGRESS | The upload is being processed. |
COMPLETED | The file uploaded successfully and is securely stored. |
DENIED | The file was rejected by the malware scan. Create a new link and upload a clean file. |
FAILED | The upload failed due to a server communication error. Retry the upload. |
Confirm every file's link reports COMPLETED before submitting the evidence.
Evidence types
evidenceType declares what a file is. You declare it on the file's upload link—not when you submit—so decide what each file is before you mint its link.
The declaration is recorded against the file on the dispute's stage and returned on CardPaymentDisputeStageEvidence.type. The label itself is never sent to the card network. On Visa allocation pre-arbitrations, though, the types you declare determine the pre-arbitration reason and compelling-evidence category filed on your behalf—so declaring accurately materially affects how your dispute is argued.
These are the supported types:
| Type | What it is |
|---|---|
PROOF_OF_DELIVERY | Proof the goods or services were delivered, such as a signed courier confirmation or a tracking number. |
SHIPPING_DOCUMENTATION | Proof the goods were shipped. |
TRANSACTION_RECEIPT | A receipt for the disputed transaction. |
INVOICE | An invoice issued for the goods or services. |
CONTRACT | The agreement the cardholder entered into for the goods or services. |
TERMS_AND_CONDITIONS | The terms and conditions the cardholder agreed to. |
SIGNED_ORDER_FORM | A signed mail order or telephone order form. |
CARDHOLDER_SIGNATURE | The cardholder's signature captured for the transaction. |
CARDHOLDER_IDENTIFICATION | A copy of the identification the cardholder presented. |
CARDHOLDER_COMMUNICATION | Communication with the cardholder about the disputed transaction. |
CORRESPONDENCE | General correspondence related to the dispute. |
AVS_OR_CVV_RESPONSE | The Address Verification Service (AVS) or Card Verification Value (CVV) response captured at transaction time. |
AUTHORIZATION_LOG | A record of the authorization obtained for the transaction. |
SYSTEM_ACCESS_LOG | A log showing the cardholder accessed or used the goods or services. |
SERVICE_RECORD | A record of the service provided, such as a service agreement, a completion certificate, or usage logs. |
PHOTO_EVIDENCE | Photographic evidence of the goods or services. |
PRIOR_TRANSACTION_RECORD | A record of earlier transactions by the same cardholder that were not disputed. |
PROOF_OF_REFUND | Proof that a refund was issued for the disputed transaction. |
OTHER_EVIDENCE | Evidence that does not fall into any of the other types. |
OTHER_EVIDENCE is a choice, not a defaultReach for OTHER_EVIDENCE when a file genuinely fits none of the other eighteen types—a kind of evidence the list does not name.
It is not the entry to pick when you are unsure which type applies: on a Visa allocation pre-arbitration, a stage of OTHER_EVIDENCE files leaves nothing to derive a specific compelling-evidence category from.
On a card-absent fraud dispute that means filing on the general category rather than the stronger one your files could have supported.
On a card-present fraud dispute there is no general category to fall back on at all: the pre-arbitration is filed with no compelling-evidence category and an invalid-data reason.
The type you declare is independent of the dispute's category and of any questionnaire you submit alongside it. Category and questionnaire describe the dispute; evidenceType describes one file.
Submit evidence
Finalize the uploaded evidence with submitCardPaymentDisputeEvidence.
This closes the upload session. No further evidence can be added to the stage afterward.
Only links reporting COMPLETED are included. A link still PENDING or IN_PROGRESS, or one that ended FAILED or DENIED, is left out. The submission still succeeds without it, so nothing tells you the file did not go. Check every link's status, and check that each file is the one you meant to send, before you submit.
A representment with no questionnaire answers, no submissionNote, and no completed document returns a UserError with code EVIDENCE_SUBMISSION_EMPTY.
The error is not retriable.
Upload at least one document, or provide questionnaire answers or a submissionNote, then submit again.
To see which questionnaire fields a stage still wants answered, read its actions.
The questionnaire action's details is a CardPaymentDisputeStageQuestionnaireActionDetails, and its requestedQuestions lists them as DisputeQuestionnaireField values.
Answer what you can in questionnaire when you submit—the API accepts a partial questionnaire.
mutation SubmitCardPaymentDisputeEvidence(
$input: SubmitCardPaymentDisputeEvidenceInput!
) {
submitCardPaymentDisputeEvidence(input: $input) {
... on CardPaymentDispute {
id
cardPaymentDisputeStatus
}
... on UserError {
errors {
code
description
}
}
... on AccessDeniedError {
message
}
}
}
| Field | Type | Description |
|---|---|---|
cardPaymentDisputeId | ID! | The CardPaymentDispute whose active stage's uploaded evidence is finalized. |
questionnaire | DisputeQuestionnaireInput | Optional. Answers for the category's evidence questionnaire. Provide exactly one variant. See Evidence Questionnaires. |
partialDisputedAmount | AmountInput | Optional. The portion of the disputed amount to contest. Omit to contest the full amount. Must be less than the active stage's amount. |
submissionNote | String | Optional. A free-text note forwarded to the card network with your response. |