Responding to Disputes

Learn how to upload evidence and respond to disputes.

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 details what actions are available to the seller:

  • NEEDS_RESPONSE : The Merchant needs to respond to the Dispute by Dispute#respond_by . For details on how to respond to a Dispute , see Responding to Disputes .
  • RESPONDED : The issuing bank has received the evidence and actively reviewing it. No action needed from the Merchant .
  • ACCEPTED : The Merchant has accepted the Dispute . When a Dispute is accepted, you concede that the dispute is not worth challenging or representing. For details on how to accept a Dispute , see Accepting a Dispute .
  • NO_RESPONSE_ALLOWED : The final Dispute#response_state when a Dispute is either WON or LOST .
  • UNKNOWN : Dispute details couldn't be submitted to the processor. Comes up when testing Disputes in sandbox or on the DUMMY_V1 processor.

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

Step 1: Upload Evidence

Finix Dashboard

Use the Disputes tab to upload evidence from the Finix Dashboard. For more information, see Managing Disputes on the Dashboard.

Finix API

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

  • You can upload up to 8 files; the total size of the uploaded files combined cannot exceed 10 MB.
  • The file formats allowed include JPG, PNG, PDF, or TIFF.
  • Individual PNG and JPEG files can't exceed 50 KB; PDF and TIFF files can't exceed 1 MB.
curl \
    -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.png"'

A successful upload will return 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" : ""

There are four values available for evidence#state that details the status of the evidence upload:

  • PENDING: The evidence file has not yet been submitted to the processor. No further action is required.
  • SUCCEEDED: The evidence file has been successfully sent to the processor. No further action is required.
  • CANCELED: The evidence file upload was cancelled by the uploader.
  • FAILED: An issue occurred. Any of the following issues could have occurred:
    • There was an error in the system and the uploader should try uploading the evidence again.
    • There is an issue with the file and the user should retry and upload a different file.
    • There is an issue and the user should contact Finix Support.

Step 2: Submit Evidence

Finix forwards uploaded evidence to the issuing bank. After the issuing bank reviews the file(s), they either request more information or move the dispute forward and makes a decision.

If you want to quickly move to a decision, you can manually submit the evidence to the issuing bank and move the dispute forward using the /disputes/DISPUTE_ID/submit endpoint. Making a POST request lets the issuing bank know the seller has completed submitting evidence and is prepared to move forward with the dispute.


Once submitted, additional evidence can't be uploaded to the Dispute.

curl \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -D {

Example Response

    "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",
    "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": ""
        "application": {
            "href": ""
        "transfer": {
            "href": ""
        "evidence": {
            "href": ""
        "adjustment_transfers": {
            "href": ""

When the dispute moves forward, Dispute#evidence_submitted gets updated to:

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

When a decision gets made, Finix will notify you with a webhook and update the Dispute#state with the issuing bank's decision.

See Dispute States for a breakdown of the different Dispute#states.