Skip to content

Responding to Disputes

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

Viewing disputes you can respond to

Finix's dashboard shows you all disputes that need to be responded to by default. In this view, you can see how much time you have left to respond for each Dispute.

Disputes Respond By List

Responding via the Dashboard

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

Disputes Respond By Details

After you upload your evidence documentation, you have the opportunity to write additional information you want to provide to the issuing bank.

Disputes Challenge Button

When all your evidence files are uploaded and your Additional Information is filled out, click the Submit Response button. This will submit the inforation to the cardholder's bank for them to review. This may take between 2-3 months to get a final response.

Disputes Submit Response

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

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

Please note that you're responsible for making sure any documents you upload are accurate and complete. While Finix converts files to meet card network file format requirements, Finix can't guarantee the conversion will be perfect or that your original documents meet all requirements - that remains your responsibility.

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.

Building an API Integration

When can I 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 details 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.

  • 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, PDF or PNG.
  • Individual files can't exceed 1 MB.
  • PNG files will be automatically converted and returned 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 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": "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.

Once submitted, additional evidence can't be uploaded 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 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.