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.

Dispute Evidence

Part of handling disputes requires sellers to provide compelling evidence that counters the dispute claims made by buyers. Upload evidence that shows the transactions was legitimate and goods/services were delivered.

This evidence can include order receipts, shipping information, tracking numbers, communication records or any other relevant information that can help establish the validity of the transaction.

  • Providing shipping details, tracking numbers, or delivery confirmation can help demonstrate that the product or service was delivered as agreed upon.
  • Including any relevant communication records, such as emails or chat transcripts, can also provide valuable context.

By diligently gathering and uploading evidence that is clear, organized, and directly addresses the dispute, sellers can effectively fight against disputes and protect their reputation in the eyes of the card networks.

Some other examples of evidence you can upload includes:

  • Email thread of conversations with the cardholder
  • Screenshots of conversations with the cardholder
  • Show use of service/software consistently over a period of time
  • Product photos
  • E-signature Contracts
  • Returns/Refund Policy
  • Proof of shipping

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

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, or PDF.
  • Individual PNG and JPEG files can't exceed 50 KB; PDF and JPEG files can't exceed 1 MB.
Copy
Copied
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.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.

Copy
Copied
{
    "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"
        }
    }
}

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.

attention

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

Copy
Copied
curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/submit \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -D {
  }

Example Response

Copy
Copied
{
    "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 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.