Skip to content

Responding to Disputes

Challenge a Dispute by uploading evidence and submitting your response before the respond-by deadline. You can respond through the Finix Dashboard or the Finix API.

When a Dispute is created, respond as quickly as possible.

View Disputes you can respond to

By default, the Finix Dashboard shows all Disputes that need a response. This view shows how much time you have left to respond to each Dispute.

List of Disputes with the time remaining to respond to each

Respond on the Dashboard

When you click into a Dispute, you can respond to the full amount or a partial amount of the Dispute.

Dispute detail page with the respond-by date and amount options

After you upload your evidence, you can add any additional information you want to provide to the issuing bank.

Challenge Dispute form with the additional information field

When all your evidence files are uploaded and your Additional Information is filled out, click Submit Response. Finix submits the information to the cardholder's bank for review. A final response may take two to three months.

Submit Response confirmation for a Dispute

After the evidence is submitted, you cannot submit additional evidence unless there is further escalation of the Dispute.

Dispute evidence

To challenge a Dispute, upload compelling evidence that shows the transaction was legitimate and that the goods or services were delivered. This evidence can include order receipts, shipping information, tracking numbers, communication records, or any other information that establishes the validity of the transaction.

  • Shipping details, tracking numbers, or delivery confirmation demonstrate that the product or service was delivered as agreed.
  • Communication records, such as emails or chat transcripts, provide valuable context.

Clear, organized evidence that directly addresses the Dispute gives you the best chance of winning.

Combining evidence files

Evidence files aren't guaranteed to be read or presented in the order they're uploaded. If you upload multiple evidence files and order matters, combine them into a single PDF before uploading to Finix.

Other examples of evidence you can upload include:

  • An email thread of conversations with the cardholder.
  • Screenshots of conversations with the cardholder.
  • Proof of consistent use of a service or software over a period of time.
  • Product photos.
  • E-signature contracts.
  • Your returns or refund policy.
  • Proof of shipping.

You're responsible for making sure any documents you upload are accurate and complete. Finix converts files to meet card network format requirements, but Finix can't guarantee the conversion is perfect or that your original documents meet all requirements. That remains your responsibility.

If you don't have enough evidence, or you believe the Dispute isn't worth fighting, you can accept liability and concede the Dispute. For more information, see Accepting disputes.

Respond with the API

When you can respond to a Dispute

If a Dispute#response_state is NEEDS_RESPONSE, you can upload additional evidence to challenge the Dispute or chargeback.

When a Dispute is filed, Dispute#response_state shows what actions are available to the seller. For more information, see Dispute states.

To challenge a NEEDS_RESPONSE Dispute, upload evidence and submit it to the issuing bank.

Step 1: Upload evidence

Create Dispute evidence to upload your defense material. Use the id of the Dispute to create the evidence.

  • The total size of the uploaded files combined can't exceed 10 MB.
  • Combined length of all Mastercard evidence files cannot exceed 17 pages.
  • Allowed file formats are JPG, PDF, and PNG.
  • Individual files can't exceed 1 MB.
  • Finix automatically converts PNG files and returns them as JPEG files.
curl https://finix.sandbox-payments-api.com/disputes/DItDftgrrkhcyFLzZiUFxn6Y/evidence \
    -H "Content-Type: multipart/form-data" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USpumes23XhzHwXqiy9bfX2B:c69d39e3-f9ff-4735-8c3e-abca86441906 \
    -F 'file=@"/Users/john.smith/Downloads/test-file.pdf"'

A successful upload returns a response with PENDING saved for state. If you run into any issues or get a different response, try uploading the file again or in another format.

{
  "id": "DF2ZnzNUCz4AAabE64Uehgkb",
  "created_at": "2021-05-25T00:34:48.37Z",
  "updated_at": "2021-05-25T00:45:00.52Z",
  "dispute": "DItDftgrrkhcyFLzZiUFxn6Y",
  "state": "SUCCEEDED",
  "tags": {
    "file-extension": ".pdf",
    "content-type": "application/pdf",
    "file-name": "test-file.pdf"
  },
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/disputes/DItDftgrrkhcyFLzZiUFxn6Y/evidence/DF2ZnzNUCz4AAabE64Uehgkb"
    }
  }
}

The evidence#state field has four values that describe the status of the evidence upload:

  • PENDING - The evidence file hasn't yet been submitted to the processor. No further action is required.
  • SUCCEEDED - The evidence file was successfully sent to the processor. No further action is required.
  • CANCELED - The uploader canceled the evidence file upload.
  • FAILED - An issue occurred. Any of the following could have happened:
    • There was a system error. Try uploading the evidence again.
    • There is an issue with the file. Retry with a different file.
    • There is another issue. Contact Finix Support.

Step 2: Submit evidence

To move quickly to a decision, submit your evidence to the issuing bank by making a POST request to the /disputes/DISPUTE_ID/submit endpoint. This tells the issuing bank you've finished submitting evidence and are ready to move the Dispute forward.

After you submit:

  • Finix forwards the uploaded evidence to the issuing bank.
  • The issuing bank reviews the files and either requests more information or moves the Dispute forward and makes a decision.

Once submitted, you can't upload additional evidence to the Dispute.

curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/submit \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -D {}
{
  "id": "DIs7yQRkHDdMYhurzYz72SFk",
  "created_at": "2022-01-27T07:43:03.74Z",
  "updated_at": "2022-09-16T22:21:54.75Z",
  "action": null,
  "amount": 888888,
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "dispute_details": {
    "arn": "123"
  },
  "evidence_submitted": "INQUIRY",
  "identity": "IDpYDM7J9n57q849o9E9yNrG",
  "merchant": "MUucec6fHeaWo3VHYoSkUySM",
  "message": null,
  "occurred_at": "2022-01-27T07:42:48.56Z",
  "reason": "FRAUD",
  "respond_by": "2022-02-03T07:43:03.73Z",
  "state": "INQUIRY",
  "tags": {
    "order_number": "21DFASJSAKAS"
  },
  "transfer": "TRoTrJ3kqNTFh1P2FJ7A36Ky",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "transfer": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRoTrJ3kqNTFh1P2FJ7A36Ky"
    },
    "evidence": {
      "href": "https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/evidence"
    },
    "adjustment_transfers": {
      "href": "https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/adjustment_transfers"
    }
  }
}

When the Dispute moves forward, Dispute#evidence_submitted updates to:

  • INQUIRY if Dispute#state is INQUIRY.
  • CHARGEBACK if Dispute#state is PENDING.

When the issuing bank makes a decision, Finix notifies you with a webhook and updates the Dispute#state with the decision.

Next steps

Dispute states

Look up Dispute states, response states, and reason codes.

Accepting Disputes

Concede a Dispute that is not worth challenging.