Skip to content

Managing Disputes

Monitor incoming Disputes and act on them before their deadlines, whether you work in the Finix Dashboard or integrate with the Finix API.

Overview

Finix represents each dispute and its lifecycle as a Dispute resource. You can monitor and act on Disputes through the Finix Dashboard or the Finix API.

For every Dispute, you can review its details, upload evidence to challenge it, or accept it. Use the state of the Dispute to decide your next step. For more information, see Dispute states.

To understand the dispute process, fees, and outcomes before you act, see How disputes work.

Build a process to monitor Disputes daily for updates that require action. Once a buyer disputes a transaction, you can no longer refund it, and a high dispute ratio can lead the card networks to monitor or disable your payment processing.

Platforms must notify their sellers when they receive Disputes. You can send this notification through a Dashboard notification, an email, or any method you choose.

Refunding disputed payments

Disputed transactions can't be refunded or reversed. Attempts to refund or reverse a disputed transaction fail with a 409 error.

Error message reversing a disputed Transfer
{
  "total": 1,
  "_embedded": {
    "errors": [
      {
        "logref": "180636a5364866d0",
        "message": "Reversals and refunds on transactions with disputes are not allowed.",
        "code": "CONFLICT",
        "_links": {
          "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers"
          }
        }
      }
    ]
  }
}

Manage Disputes on the Dashboard

To manage Disputes on the Finix Dashboard, navigate to the Disputes screen. This page lists every reported Dispute so you can track incoming Disputes and their deadlines in one place.

From the Disputes list, you can:

  • Review the details of any Dispute, including its reason code, card network, and respond-by date.
  • Upload evidence to challenge a Dispute. For the full evidence workflow, see Responding to disputes.
  • Accept a Dispute that isn't worth challenging. For more information, see Accepting disputes.

To receive a notification whenever a Dispute is created or updated, subscribe to Finix's webhooks.

Manage Disputes with the API

You can manage Disputes programmatically using webhook events and the Finix API. Managing Disputes with the API starts with receiving the Dispute webhook.

Receive the Dispute webhook

When a Dispute is created, you receive a webhook event with entity: dispute and type: created. The webhook includes the Dispute resource.

Dispute webhook example
{
  "type": "created",
  "entity": "dispute",
  "occurred_at": "2022-01-27T07:43:03.48Z",
  "_embedded": {
    "disputes": [
      {
        "id": "DIs7yQRkHDdMYhurzYz72SFk",
        "application": "APgPDQrLD52TYvqazjHJJchM",
        "tags": {
          "order_number": "21DFASJSAKAS"
        },
        "amount": 888888,
        "state": "PENDING",
        "transfer": "TRoTrJ3kqNTFh1P2FJ7A36Ky",
        "reason": "FRAUD",
        "message": null,
        "action": null,
        "identity": "IDpYDM7J9n57q849o9E9yNrG",
        "created_at": "2022-01-27T07:43:03.74Z",
        "updated_at": "2022-01-27T07:43:03.48Z",
        "occurred_at": "2022-01-27T07:42:48.56Z",
        "respond_by": "2022-02-03T07:43:03.73Z",
        "dispute_details": {
          "arn": "123"
        }
      }
    ]
  }
}

Fetch the Dispute

Use the returned id to query the Dispute.

Fetching a Dispute
curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Dispute resource
{
  "id": "DIs7yQRkHDdMYhurzYz72SFk",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "tags": {
    "order_number": "21DFASJSAKAS"
  },
  "amount": 888888,
  "state": "PENDING",
  "transfer": "TRoTrJ3kqNTFh1P2FJ7A36Ky",
  "reason": "FRAUD",
  "message": null,
  "action": null,
  "identity": "IDpYDM7J9n57q849o9E9yNrG",
  "created_at": "2022-01-27T07:43:03.74Z",
  "updated_at": "2022-01-27T07:43:03.48Z",
  "occurred_at": "2022-01-27T07:42:48.56Z",
  "respond_by": "2022-02-03T07:43:03.73Z",
  "dispute_details": {
    "arn": "123"
  },
  "_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"
    }
  }
}

Use the state of the Dispute to determine your next step. For more information, see Dispute states.

Next steps

Responding to Disputes

Upload evidence and submit a response to challenge a Dispute.

Accepting Disputes

Concede a Dispute that is not worth challenging.

Dispute states

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