Skip to main content

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.

a representment cannot be empty

Carry at least one of: a completed document on the active stage, questionnaire answers, or a submissionNote.

Upload evidence​

Uploading evidence takes three mutations:

MutationWhat it does
initiateCardPaymentDisputeEvidenceUploadOpens one upload session scoped to the dispute's active stage.
createCardPaymentDisputeEvidenceUploadLinkMints an upload link for a single file, and declares what that file is.
submitCardPaymentDisputeEvidenceCloses 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 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
}
}
}
FieldTypeDescription
documentUploadSessionIdID!The session opened by initiateCardPaymentDisputeEvidenceUpload.
evidenceTypeCardPaymentDisputeStageEvidenceType!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 file has to decode, not just be named correctly

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"
you have five minutes

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
}
}
}
StatusDescription
PENDINGThe link is waiting for a file to be uploaded.
IN_PROGRESSThe upload is being processed.
COMPLETEDThe file uploaded successfully and is securely stored.
DENIEDThe file was rejected by the malware scan. Create a new link and upload a clean file.
FAILEDThe 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:

TypeWhat it is
PROOF_OF_DELIVERYProof the goods or services were delivered, such as a signed courier confirmation or a tracking number.
SHIPPING_DOCUMENTATIONProof the goods were shipped.
TRANSACTION_RECEIPTA receipt for the disputed transaction.
INVOICEAn invoice issued for the goods or services.
CONTRACTThe agreement the cardholder entered into for the goods or services.
TERMS_AND_CONDITIONSThe terms and conditions the cardholder agreed to.
SIGNED_ORDER_FORMA signed mail order or telephone order form.
CARDHOLDER_SIGNATUREThe cardholder's signature captured for the transaction.
CARDHOLDER_IDENTIFICATIONA copy of the identification the cardholder presented.
CARDHOLDER_COMMUNICATIONCommunication with the cardholder about the disputed transaction.
CORRESPONDENCEGeneral correspondence related to the dispute.
AVS_OR_CVV_RESPONSEThe Address Verification Service (AVS) or Card Verification Value (CVV) response captured at transaction time.
AUTHORIZATION_LOGA record of the authorization obtained for the transaction.
SYSTEM_ACCESS_LOGA log showing the cardholder accessed or used the goods or services.
SERVICE_RECORDA record of the service provided, such as a service agreement, a completion certificate, or usage logs.
PHOTO_EVIDENCEPhotographic evidence of the goods or services.
PRIOR_TRANSACTION_RECORDA record of earlier transactions by the same cardholder that were not disputed.
PROOF_OF_REFUNDProof that a refund was issued for the disputed transaction.
OTHER_EVIDENCEEvidence that does not fall into any of the other types.
OTHER_EVIDENCE is a choice, not a default

Reach 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 completed uploads are submitted, and nothing says what was left out

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
}
}
}
FieldTypeDescription
cardPaymentDisputeIdID!The CardPaymentDispute whose active stage's uploaded evidence is finalized.
questionnaireDisputeQuestionnaireInputOptional. Answers for the category's evidence questionnaire. Provide exactly one variant. See Evidence Questionnaires.
partialDisputedAmountAmountInputOptional. The portion of the disputed amount to contest. Omit to contest the full amount. Must be less than the active stage's amount.
submissionNoteStringOptional. A free-text note forwarded to the card network with your response.