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 also take a category-specific questionnaire.

Upload evidence

Uploading evidence starts by opening a session scoped to the dispute's active stage. Then, for each file, create an upload link, PUT the file to the link, and confirm the upload completed.

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

Pass the session's documentUploadSessionId and the file's documentType to createDocumentUploadLink to create a link for each file:

mutation CreateDocumentUploadLink($input: CreateDocumentUploadLinkInput!) {
  createDocumentUploadLink(input: $input) {
    ... on DocumentUploadLink {
      id
      uploadUrl
    }
    ... on UserError {
      errors {
        code
        description
      }
    }
  }
}

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.

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 DocumentUploadLink's status with a node query:

query CheckDocumentUploadLink($id: ID!) {
  node(id: $id) {
    ... on DocumentUploadLink {
      id
      status
      documentType
      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.

Submit evidence

Finalize the uploaded evidence with submitCardPaymentDisputeEvidence. This closes the upload session. No further evidence can be added to the stage afterward.

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.

To see which questionnaire fields the network requests, read the active stage's actions: the questionnaire action's details list the outstanding fields as DisputeQuestionnaireField values in requestedQuestions. Answer those fields in questionnaire when you submit.